Observability

Two different questions, two different ledgers, joined by one key. Conflating them is where teams lose the thread.

• What’s been built — the build ledger. Identity is content-addressed: a sha256: digest, never a moving tag.
• What’s been deployed — the release ledger plus live truth. Two sub-questions: what we recorded deploying, and what’s actually running.

chant already had the live-truth half — ownership markers and lifecycle diff --live compare declared vs. live, and snapshots on the chant/lifecycle branch give a forensic timeline. What was missing was the recorded half. This page covers the three pieces that fill it in: the release ledger, build-ledger referrer discovery, and the chant components status surface that joins them.

The release ledger

Each deploy appends one immutable record to the chant/lifecycle orphan branch — the same branch snapshots already live on, at <env>/releases.jsonl:

component, env, artifact digest, git sha, run id, timestamp, actor

chant components release prod \
  --component search-service \
  --digest sha256:9fae3d... \
  --git-sha "$(git rev-parse HEAD)" \
  --run-id "$GITHUB_RUN_ID" \
  --actor "$GITHUB_ACTOR"

--git-sha defaults to the current HEAD, and --run-id/--actor fall back to common CI environment variables (GITHUB_RUN_ID/CI_PIPELINE_ID, GITHUB_ACTOR/GITLAB_USER_LOGIN/USER) — but --actor has no silent placeholder fallback; an unattributed release record defeats the point of a ledger, so the command fails rather than guess.

Populated by construction

chant components release is the standalone, explicit way to append a record — but chant run --components <name> --env <env> (both local and --temporal) auto-emits one on every successful deploy that published a digest, so the ledger fills in without a separate step. Opt out with --no-release-record or chant.config.ts’s release.autoRecord: false; see chant run. The auto-recorded path is a CLI post-run step in both cases — never inside the Temporal workflow, which must stay deterministic.

Append-only, never rewritten

A release record is never edited or replaced in place. Recording a new deploy appends a new line; it never rewrites a previous one. This is what makes “which build was in staging last Tuesday” answerable months later, even after staging has moved on through a dozen newer digests — the same reason the timestamp is always a real new Date() taken at record time by the CLI, never threaded in from elsewhere.

The binding key is the digest — the same identity publish-image/load-image-on-host promote by. Because publish never rebuilds, that identity threads build → dev → staging → prod unchanged, so comparing environments is a digest comparison, never a guess through CI logs.

Build ledger: SBOM and referrer discovery

The build archive manifest is already content-addressed and already enumerates a build’s contents, including an sbom-kind entry when a component composed generate-sbom. On top of that, the build ledger discovers an image digest’s referrers — the SBOM, SLSA provenance, and signature attached to the same digest by tooling like oras discover <digest> / cosign tree.

SLSA provenance generation and cosign signing are covered separately — see Supply-Chain Attestations for the attest-provenance/sign/verify capabilities that produce the provenance and signature referrers this section discovers. Referrer discovery itself is surface-and-consume only: the lookup is injectable (ReferrerLookup), defaulting to a no-op so a build-ledger query never requires network/registry access unless a real implementation is wired in:

import { buildLedgerEntries, type ReferrerLookup } from "@intentius/chant/lifecycle";

const orasLookup: ReferrerLookup = {
  async discover(digest) {
    // shell out to `oras discover` / a registry referrers API, return Referrer[]
  },
};

const entries = await buildLedgerEntries(manifest, orasLookup);
// entries[i].referrers: [{ kind: "sbom" | "provenance" | "signature", digest, mediaType, location? }]
// entries[i].sbom: { mediaType, packageCount?, generator?, source: "archive" | "referrer" } | undefined

entries[i].sbom reads whichever source is available — the archive-carried sbom entry first (works for every artifact type and every publish backend, registry or not), the registry-discovered referrer otherwise (image artifacts only). Both trace back to the same generate-sbom run for a given digest, so which one answers doesn’t change the answer.

Persisting the manifest

A BuildArchiveManifest only helps chant components status answer “what’s built” if something durable outlives the in-process build/run that assembled it. chant run --components <name> --env <env> (both local and --temporal) persists the run’s accumulated manifest — the same document docker-build/generate-sbom/extract-config-bom build up across a component’s Build phase — to the chant/lifecycle orphan branch, alongside the release ledger, keyed by the manifest’s own manifestDigest:

import { persistBuildManifest, readBuildManifest, findBuildManifestByArtifactDigest } from "@intentius/chant/lifecycle";

await persistBuildManifest(manifest);                                  // write, keyed by manifest.manifestDigest
const same = await readBuildManifest(manifest.manifestDigest);         // read back by manifest digest
const behindDeploy = await findBuildManifestByArtifactDigest(digest);  // read back by a *promoted artifact* digest

Manifests live under a fixed top-level _builds/ directory on the orphan branch — a peer of the per-env directories the release ledger and snapshots use, never nested inside one. A build archive is promoted by digest across environments rather than owned by a single one, so it doesn’t belong under any single <env>/ path.

Populated by construction, same opt-out as the release record

Like the release record, manifest persistence is a post-run CLI step — never inside the driver (../../components/driver.ts stays capability-agnostic) and never inside the Temporal workflow (which must stay deterministic). It shares the release record’s opt-out: --no-release-record / chant.config.ts’s release.autoRecord: false disables both, and a failed or dry-run deploy persists nothing, by construction — the CLI only reaches this step after a run reports success.

chant components status resolves build/componentBom for a recorded digest by calling findBuildManifestByArtifactDigest and deriving both from the result via buildLedgerEntries/componentBomSummary — the same functions covered above, now fed a real manifest instead of one built by hand. A digest with no persisted manifest (it predates this wiring, or was recorded via the standalone chant components release command with no corresponding build) simply reports null for both fields, exactly as before.

Reconciling with live

chant components status doesn’t recompute drift logic — it reuses the same ownership-aware classification lifecycle plan already trusts (buildChangeSet), then joins it against the release ledger by component name and digest. Four reconciliation outcomes, plus unknown when --live is omitted:

Reconciliation	Meaning
reconciled	A release record exists and live evidence confirms the component is present and chant-owned.
unrecorded	Something is live and owned, but no release record references it — a deploy that happened outside the recorded path.
stale	A release record exists, but nothing live corresponds to it anymore.
drifted	A release record exists, but the live configuration has drifted since (the same update verdict lifecycle plan would give).
unknown	No live evidence was requested (--live omitted) — the ledger alone doesn’t confirm reconciliation either way.

chant components status

chant components status prod                          # ledger only
chant components status prod --live                    # reconcile against live + ownership
chant components status prod --live --json              # stable machine-readable contract
chant components status prod --compare-to staging       # single-query cross-env digest check
chant components status                                 # every environment with release records

--json is a stable array of rows (or, with --compare-to, { rows, comparisons }):

[
  {
    "component": "search-service",
    "env": "prod",
    "recorded": {
      "digest": "sha256:9fae3d...",
      "gitSha": "a1b2c3d",
      "runId": "4821",
      "timestamp": "2026-07-02T18:04:11.000Z",
      "actor": "octocat"
    },
    "build": {
      "manifestDigest": "sha256:...",
      "referrers": ["sbom", "provenance"],
      "sbom": { "mediaType": "application/spdx+json", "packageCount": 142, "generator": "syft", "source": "archive" }
    },
    "reconciliation": "reconciled",
    "detail": "recorded 2026-07-02T18:04:11.000Z (digest sha256:9fae3d...), live and consistent"
  }
]

“Which build is in prod, and is it the one tested in staging” is exactly --compare-to:

chant components status prod --compare-to staging --json

{
  "comparisons": [
    { "component": "search-service", "envA": "prod", "envB": "staging", "digestA": "sha256:9fae3d...", "digestB": "sha256:9fae3d...", "same": true }
  ]
}

Both “what’s built” and “what’s deployed where” resolve to one query each, joined by digest — the property the release ledger exists to protect.

Component names vs. lexicon entity names

Live reconciliation joins on the component’s own name by default. Where a component’s name matches the underlying lexicon entity/resource name one-for-one (the pilot components), --live resolves cleanly with no further declaration. When they diverge — a component named search-svc whose composition targets a stack/service declared under a different name, or a fan-out component that owns several live entities (one stack per node) — declare liveNames on the Component:

export const searchSvc: Component = {
  name: "search-svc",
  liveNames: ["search-service-v2"], // the live entity/resource name(s) this component owns
  dependsOn: [],
  deploy: [ /* … */ ],
};

chant components status --live joins on liveNames when present, aggregating live evidence across every name listed (drift on any one of them surfaces as drift for the component as a whole) — and falls back to name itself when liveNames is omitted, so existing components need no changes.

Read next

• Build Archive — the manifest and digest identity this ledger joins against.
• chant lifecycle — snapshots, diff --live, and plan, which the status surface reuses rather than reimplements.
• Orchestration — where a Verify phase or CI job calls chant components release after a deploy completes.