CLI v3 Output Format

Audience

Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

Source Truth

• Public route: reference/cli-v3/format
• Source document: helm-ai-enterprise/docs/public/reference/cli-v3/format.md
• Public manifest: helm-ai-enterprise/docs/public-docs.manifest.json
• Source inventory: helm-ai-enterprise/docs/source-inventory.manifest.json
• Validation: corepack pnpm run docs:coverage, corepack pnpm run docs:truth, and npm run coverage:inventory from docs-platform

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

Troubleshooting

Canonicalization

00_INDEX.json MUST be canonical JSON:

• Keys sorted lexicographically (recursive)
• No trailing whitespace
• UTF-8 encoded
• No BOM
• Single trailing newline

This matches JCS (RFC 8785).

Manifest Root Hash

manifest_root_hash = sha256(canonical_bytes(00_INDEX.json))

Identity of the bundle. Cache key. Single hash that pins the entire evidence tree.

Merkle Tree

Leaves are the sha256 hex strings from each 00_INDEX.json entry, sorted ascending by path string. Each hex string is decoded to 32 bytes before hashing.

Construction

leaf_hash    = sha256(0x00 || entry_sha256_bytes)     # domain separator: leaf
internal     = sha256(0x01 || left_hash || right_hash) # domain separator: node
odd_leaf     → duplicate last leaf
merkle_root  = root hash (hex)

Ordering

Leaves are sorted by canonical path string (ascending, lexicographic). This prevents order drift across implementations.

Verification Algorithm

1. Read 00_INDEX.json
2. Sort entries by path ascending
3. Decode each entry.sha256 from hex → 32 bytes
4. Hash each: leaf = sha256(0x00 || bytes)
5. Build tree bottom-up:
   a. If odd number of leaves, duplicate last
   b. Parent = sha256(0x01 || left || right)
6. Root = final hash (hex)
7. Compare to attestation merkle_root

Attestation

{
  "format":             "helm-attestation-v3",
  "release_tag":        "v0.9.1",
  "asset_name":         "helm-evidence-v0.9.1.tar.gz",
  "asset_sha256":       "abc123...",
  "manifest_root_hash": "def456...",
  "merkle_root":        "789abc...",
  "created_at":         "2026-02-21T12:00:00Z",
  "profiles_version":   "1.0.0"
}

Signed with Ed25519. Signature is over sha256(canonical_bytes(attestation_json)).

Public Key

Shipped in CLI as pinned constant. Key rotation via versioned key list.

Diagram

flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        index["00_INDEX.json"]
        canonical["Canonical JSON"]
        leaves["Sorted leaf hashes"]
        merkle["Merkle root"]
        attest["Attestation"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        verify["CLI verify"]
    end

    %% Operational Flow Edges
    index --> canonical
    canonical --> leaves
    leaves --> merkle
    merkle --> attest
    attest --> verify

    %% Premium Styling Rules
    style verify fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff

flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        index["00_INDEX.json"]
        canonical["Canonical JSON"]
        leaves["Sorted leaf hashes"]
        merkle["Merkle root"]
        attest["Attestation"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        verify["CLI verify"]
    end

    %% Operational Flow Edges
    index --> canonical
    canonical --> leaves
    leaves --> merkle
    merkle --> attest
    attest --> verify

    %% Premium Styling Rules
    style verify fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff

Operational Readiness

Use this page as the public operating layer for CLI v3 Output Format. The source of truth is helm-ai-enterprise/docs/public/reference/cli-v3/format.md; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, llms-full.txt, and MCP without exposing protected routes.

Validation command: corepack pnpm run docs:coverage && corepack pnpm run docs:truth. For website parity, also run npm run exports:boundary and npm run thin-pages:check from docs-platform.

Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.