@intentius/chant 0.13.0 → 0.15.0

package/src/lifecycle/git.test.ts

@@ -11,6 +11,12 @@ import {
   getHeadCommit,
   pushLifecycle,
   StaleLifecycleBranchError,
+  appendReleaseRecordLine,
+  readReleaseLedgerLines,
+  listLedgerEnvironments,
+  writeBlobToPath,
+  readBlobFromPath,
+  listFilesInDir,
 } from "./git";
 
 function git(args: string[], cwd: string): { stdout: string; exitCode: number } {
@@ -83,6 +89,57 @@ describe("lifecycle/git", () => {
     });
   });
 
+  // ── Generic blob helpers used by ./build-ledger-store.ts (#609) ────────────
+
+  describe("writeBlobToPath / readBlobFromPath / listFilesInDir (generic, non-env namespaces)", () => {
+    test("writes/reads a blob under an arbitrary top-level directory, not just an env", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const sha = await writeBlobToPath("_builds", "sha256_abc.json", '{"a":1}', "Build manifest", { cwd: dir });
+        expect(sha).toMatch(/^[0-9a-f]{40}$/);
+
+        const out = await readBlobFromPath("_builds", "sha256_abc.json", { cwd: dir });
+        expect(JSON.parse(out!)).toEqual({ a: 1 });
+      });
+    });
+
+    test("readBlobFromPath returns null for a missing directory/file", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        expect(await readBlobFromPath("_builds", "missing.json", { cwd: dir })).toBeNull();
+      });
+    });
+
+    test("listFilesInDir lists every file directly under a directory", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        await writeBlobToPath("_builds", "a.json", "{}", "m", { cwd: dir });
+        await writeBlobToPath("_builds", "b.json", "{}", "m", { cwd: dir });
+        const files = await listFilesInDir("_builds", { cwd: dir });
+        expect(files.sort()).toEqual(["a.json", "b.json"]);
+      });
+    });
+
+    test("listFilesInDir returns empty for a directory that doesn't exist yet", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        expect(await listFilesInDir("_builds", { cwd: dir })).toEqual([]);
+      });
+    });
+
+    test("a non-env top-level directory (_builds) coexists with per-env snapshot/release directories", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: dir });
+        await writeBlobToPath("_builds", "sha256_abc.json", '{"b":2}', "Build manifest", { cwd: dir });
+
+        expect(await readSnapshot("prod", "aws", { cwd: dir })).toBeTruthy();
+        const out = await readBlobFromPath("_builds", "sha256_abc.json", { cwd: dir });
+        expect(JSON.parse(out!)).toEqual({ b: 2 });
+      });
+    });
+  });
+
   test("listSnapshots returns commit history of the orphan branch", async () => {
     await withTestDir(async (dir) => {
       await initRepo(dir);
@@ -188,4 +245,65 @@ describe("lifecycle/git", () => {
     expect(err.expected).toBeNull();
     expect(err.message).toContain("moved");
   });
+
+  // ── Release ledger plumbing (#568) ──────────────────────────────────────
+
+  describe("release ledger plumbing", () => {
+    test("appendReleaseRecordLine creates the orphan branch and is readable via readReleaseLedgerLines", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const sha = await appendReleaseRecordLine("prod", '{"v":1}', { cwd: dir });
+        expect(sha).toMatch(/^[0-9a-f]{40}$/);
+        const lines = await readReleaseLedgerLines("prod", { cwd: dir });
+        expect(lines).toEqual(['{"v":1}']);
+      });
+    });
+
+    test("readReleaseLedgerLines returns [] for an environment with no ledger", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        expect(await readReleaseLedgerLines("prod", { cwd: dir })).toEqual([]);
+      });
+    });
+
+    test("appendReleaseRecordLine appends rather than overwrites", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        await appendReleaseRecordLine("prod", '{"v":1}', { cwd: dir });
+        await appendReleaseRecordLine("prod", '{"v":2}', { cwd: dir });
+        await appendReleaseRecordLine("prod", '{"v":3}', { cwd: dir });
+        expect(await readReleaseLedgerLines("prod", { cwd: dir })).toEqual(['{"v":1}', '{"v":2}', '{"v":3}']);
+      });
+    });
+
+    test("release ledger and snapshot files coexist under the same env directory", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: dir });
+        await appendReleaseRecordLine("prod", '{"v":1}', { cwd: dir });
+        // Both must survive — the release ledger uses a different filename
+        // ("releases.jsonl") than any lexicon snapshot ("<lexicon>.json").
+        expect(await readSnapshot("prod", "aws", { cwd: dir })).toBeTruthy();
+        expect(await readReleaseLedgerLines("prod", { cwd: dir })).toEqual(['{"v":1}']);
+      });
+    });
+
+    test("listLedgerEnvironments finds every env with a release ledger, ignoring envs that only have snapshots", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        await writeSnapshot("dev", "aws", JSON.stringify({ a: 1 }), { cwd: dir }); // snapshot only, no ledger
+        await appendReleaseRecordLine("staging", '{"v":1}', { cwd: dir });
+        await appendReleaseRecordLine("prod", '{"v":1}', { cwd: dir });
+
+        expect(await listLedgerEnvironments({ cwd: dir })).toEqual(["prod", "staging"]);
+      });
+    });
+
+    test("listLedgerEnvironments returns [] when the orphan branch doesn't exist yet", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        expect(await listLedgerEnvironments({ cwd: dir })).toEqual([]);
+      });
+    });
+  });
 });

package/src/lifecycle/git.ts

@@ -9,14 +9,31 @@ import { getRuntime } from "../runtime-adapter";
 const STATE_BRANCH = "chant/lifecycle";
 
 /**
- * Write a state snapshot JSON to the orphan branch.
+ * Write a blob to an arbitrary `<environment>/<filename>` path on the orphan
+ * branch, preserving every other env/file entry already on the branch.
  *
- * Pipeline: hash-object → mktree → commit-tree → update-ref
+ * Pipeline: hash-object → mktree → commit-tree → update-ref. Factored out of
+ * `writeSnapshot` so the release ledger (#568, epic #551 "Build & deploy
+ * observability") can reuse the identical git-plumbing path for a different
+ * filename (`releases.jsonl`) under the same env directory, rather than a
+ * parallel storage mechanism.
+ *
+ * Exported (not just used internally) so ./build-ledger-store.ts (#609) can
+ * reuse this exact plumbing for a top-level directory that isn't really an
+ * "environment" (`_builds`, keyed by manifest digest rather than env name) —
+ * a build archive is promoted by digest across environments, never owned by
+ * one, so it belongs in its own digest-keyed namespace on the same orphan
+ * branch rather than duplicated per env. The parameter is still named
+ * `environment` because it is literally the first path segment / root-tree
+ * entry name this function's tree-building logic groups by; callers outside
+ * this module that pass a non-env value (like `_builds`) are relying on that
+ * generic behavior, not on any env-specific semantics.
  */
-export async function writeSnapshot(
+export async function writeBlobToPath(
   environment: string,
-  lexicon: string,
-  json: string,
+  filename: string,
+  content: string,
+  commitMessage: string,
   opts?: { cwd?: string },
 ): Promise<string> {
   const rt = getRuntime();
@@ -25,7 +42,7 @@ export async function writeSnapshot(
   // 1. Write blob — hash-object reads from stdin, but spawn() doesn't expose
   // a stdin handle, so we run via a shell pipeline (`echo … | git hash-object`).
   const blobResult = await rt.spawn(
-    ["sh", "-c", `echo '${json.replace(/'/g, "'\\''")}' | git hash-object -w --stdin`],
+    ["sh", "-c", `echo '${content.replace(/'/g, "'\\''")}' | git hash-object -w --stdin`],
     { cwd },
   );
   if (blobResult.exitCode !== 0) {
@@ -33,13 +50,12 @@ export async function writeSnapshot(
   }
   const blobSha = blobResult.stdout.trim();
 
-  // 2. Read existing tree (if branch exists) to preserve other env/lexicon entries
+  // 2. Read existing tree (if branch exists) to preserve other env/file entries
   const existingTree = await readTree(cwd);
 
   // 3. Build new tree entries
-  const path = `${environment}/${lexicon}.json`;
+  const path = `${environment}/${filename}`;
   const entries = mergeTreeEntry(existingTree, path, blobSha);
-  const treeInput = entries.map((e) => `${e.mode} ${e.type} ${e.sha}\t${e.name}`).join("\n");
 
   // mktree needs a nested tree structure. Build env subtree first, then root tree.
   // Build env subtree
@@ -84,7 +100,7 @@ export async function writeSnapshot(
   const parentRef = await getStateBranchTip(cwd);
   const parentArgs = parentRef ? ["-p", parentRef] : [];
   const commitResult = await rt.spawn(
-    ["git", "commit-tree", ...parentArgs, "-m", "State snapshot", rootTreeSha],
+    ["git", "commit-tree", ...parentArgs, "-m", commitMessage, rootTreeSha],
     { cwd },
   );
   if (commitResult.exitCode !== 0) {
@@ -105,22 +121,141 @@ export async function writeSnapshot(
 }
 
 /**
- * Read a snapshot from the orphan branch.
+ * Read a blob from an arbitrary `<environment>/<filename>` path on the orphan
+ * branch. Returns null when the path doesn't exist (missing branch, env, or
+ * file). Sibling of `writeBlobToPath`. Exported for the same reason
+ * `writeBlobToPath` is — ./build-ledger-store.ts (#609) reads manifests back
+ * from the `_builds` namespace through this identical helper.
  */
-export async function readSnapshot(
+export async function readBlobFromPath(
   environment: string,
-  lexicon: string,
+  filename: string,
   opts?: { cwd?: string },
 ): Promise<string | null> {
   const rt = getRuntime();
   const result = await rt.spawn(
-    ["git", "show", `${STATE_BRANCH}:${environment}/${lexicon}.json`],
+    ["git", "show", `${STATE_BRANCH}:${environment}/${filename}`],
     { cwd: opts?.cwd },
   );
   if (result.exitCode !== 0) return null;
   return result.stdout;
 }
 
+/**
+ * Write a state snapshot JSON to the orphan branch.
+ *
+ * Pipeline: hash-object → mktree → commit-tree → update-ref
+ */
+export async function writeSnapshot(
+  environment: string,
+  lexicon: string,
+  json: string,
+  opts?: { cwd?: string },
+): Promise<string> {
+  return writeBlobToPath(environment, `${lexicon}.json`, json, "State snapshot", opts);
+}
+
+/**
+ * Read a snapshot from the orphan branch.
+ */
+export async function readSnapshot(
+  environment: string,
+  lexicon: string,
+  opts?: { cwd?: string },
+): Promise<string | null> {
+  return readBlobFromPath(environment, `${lexicon}.json`, opts);
+}
+
+/**
+ * Append one immutable release record line to `<environment>/releases.jsonl`
+ * on the orphan branch (#568, epic #551 "Build & deploy observability"). Same
+ * git-plumbing path `writeSnapshot` uses, just a different filename under the
+ * env directory and append-only (JSON Lines) instead of replace-whole-file:
+ * each deploy adds one line, never rewrites a previous one, so the ledger
+ * stays a durable, append-only history rather than a point-in-time snapshot.
+ *
+ * Low-level plumbing over an already-serialized line; ../release-ledger.ts's
+ * `appendReleaseRecord` is the typed, validated public API most callers want
+ * — named distinctly here (`ReleaseRecordLine`) to avoid re-export ambiguity
+ * between the two modules.
+ *
+ * Returns the new orphan-branch commit SHA — the caller still owns pushing
+ * via `pushLifecycle` under the same concurrent-write lease `writeSnapshot`
+ * uses.
+ */
+export async function appendReleaseRecordLine(
+  environment: string,
+  recordJson: string,
+  opts?: { cwd?: string },
+): Promise<string> {
+  const filename = "releases.jsonl";
+  const existing = await readBlobFromPath(environment, filename, opts);
+  const content = existing ? `${existing.replace(/\n$/, "")}\n${recordJson}` : recordJson;
+  return writeBlobToPath(environment, filename, content, "Release record", opts);
+}
+
+/**
+ * Read every release record line for `environment` from the orphan branch,
+ * oldest first, as raw JSON strings. Returns `[]` when no ledger exists yet
+ * for that env (never throws — a component that has never recorded a deploy
+ * is a normal, expected state). ../release-ledger.ts's `readReleaseLedger`
+ * parses/validates these lines into typed `ReleaseRecord`s.
+ */
+export async function readReleaseLedgerLines(
+  environment: string,
+  opts?: { cwd?: string },
+): Promise<string[]> {
+  const content = await readBlobFromPath(environment, "releases.jsonl", opts);
+  if (!content) return [];
+  return content.split("\n").map((line) => line.trim()).filter(Boolean);
+}
+
+/**
+ * List every environment that has a release ledger on the orphan branch —
+ * the root-level directories under `chant/lifecycle` that carry a
+ * `releases.jsonl` entry. Used by `chant components status` (no env arg) to
+ * discover which environments to report on.
+ */
+export async function listLedgerEnvironments(opts?: { cwd?: string }): Promise<string[]> {
+  const tip = await getStateBranchTip(opts?.cwd);
+  if (!tip) return [];
+  const rt = getRuntime();
+  const rootResult = await rt.spawn(["git", "ls-tree", STATE_BRANCH], { cwd: opts?.cwd });
+  if (rootResult.exitCode !== 0) return [];
+
+  const envs: string[] = [];
+  const lines = rootResult.stdout.trim().split("\n").filter(Boolean);
+  for (const line of lines) {
+    const match = line.match(/^(\d+)\s+(\w+)\s+([0-9a-f]+)\t(.+)$/);
+    if (!match) continue;
+    const [, , type, , name] = match;
+    if (type !== "tree") continue;
+    const hasLedger = await readBlobFromPath(name, "releases.jsonl", opts);
+    if (hasLedger) envs.push(name);
+  }
+  return envs.sort();
+}
+
+/**
+ * List every filename directly under `<dir>/` on the orphan branch (no
+ * recursion), or `[]` when the branch/directory doesn't exist yet. Generic
+ * sibling of `readEnvironmentSnapshots`'s inline file listing, factored out
+ * so ./build-ledger-store.ts (#609) can enumerate every persisted build
+ * manifest (`_builds/<digest>.json`) without duplicating this `git ls-tree
+ * --name-only` call.
+ */
+export async function listFilesInDir(dir: string, opts?: { cwd?: string }): Promise<string[]> {
+  const tip = await getStateBranchTip(opts?.cwd);
+  if (!tip) return [];
+  const rt = getRuntime();
+  const lsResult = await rt.spawn(
+    ["git", "ls-tree", "--name-only", `${STATE_BRANCH}:${dir}/`],
+    { cwd: opts?.cwd },
+  );
+  if (lsResult.exitCode !== 0) return [];
+  return lsResult.stdout.trim().split("\n").filter(Boolean);
+}
+
 /**
  * Read all snapshots for an environment (all lexicons).
  */

package/src/lifecycle/index.ts

@@ -5,3 +5,8 @@ export * from "./snapshot";
 export * from "./live-diff";
 export * from "./change-set";
 export * from "./affected";
+export * from "./release-ledger";
+export * from "./build-ledger";
+export * from "./build-ledger-store";
+export * from "./oras-referrer-lookup";
+export * from "./status";

package/src/lifecycle/oras-referrer-lookup.test.ts

@@ -0,0 +1,116 @@
+/**
+ * Tests the real `ReferrerLookup` backend (#610, ./oras-referrer-lookup.ts)
+ * against a `MockProcessRunner`
+ * (../components/verbs/__tests__/mock-process-runner.ts) — no live `oras`,
+ * no live registry. Asserts the `oras discover` command constructed, that
+ * its JSON output is parsed and classified into `Referrer[]`, and that a
+ * missing `oras` binary surfaces `ToolNotAvailableError`.
+ */
+
+import { describe, expect, it } from "vitest";
+import { createOrasReferrerLookup } from "./oras-referrer-lookup";
+import { ToolNotAvailableError } from "../components/verbs/process-runner";
+import { createMockProcessRunner } from "../components/verbs/__tests__/mock-process-runner";
+
+const REPO = "123.dkr.ecr.us-east-1.amazonaws.com/search";
+const DIGEST = "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+
+function orasOutput(manifests: Array<{ digest: string; mediaType: string; artifactType?: string }>): string {
+  return JSON.stringify({ manifests });
+}
+
+describe("createOrasReferrerLookup (#610)", () => {
+  it("constructs the oras discover command against repo@digest", async () => {
+    const mock = createMockProcessRunner({ responses: { "oras discover": orasOutput([]) } });
+    const lookup = createOrasReferrerLookup({ repo: REPO, runner: mock.runner });
+
+    await lookup.discover(DIGEST);
+
+    const call = mock.calls.find((c) => c.command.startsWith("oras discover"))!;
+    expect(call.command).toBe(`oras discover --format json '${REPO}@${DIGEST}'`);
+  });
+
+  it("classifies an spdx/cyclonedx manifest as an sbom referrer", async () => {
+    const mock = createMockProcessRunner({
+      responses: {
+        "oras discover": orasOutput([
+          { digest: "sha256:sbom1", mediaType: "application/vnd.oci.image.manifest.v1+json", artifactType: "application/spdx+json" },
+        ]),
+      },
+    });
+    const lookup = createOrasReferrerLookup({ repo: REPO, runner: mock.runner });
+
+    const referrers = await lookup.discover(DIGEST);
+
+    expect(referrers).toEqual([
+      { kind: "sbom", mediaType: "application/spdx+json", digest: "sha256:sbom1", location: `${REPO}@sha256:sbom1` },
+    ]);
+  });
+
+  it("classifies an in-toto/slsa manifest as a provenance referrer", async () => {
+    const mock = createMockProcessRunner({
+      responses: {
+        "oras discover": orasOutput([
+          { digest: "sha256:prov1", mediaType: "application/vnd.oci.image.manifest.v1+json", artifactType: "application/vnd.in-toto+json" },
+        ]),
+      },
+    });
+    const lookup = createOrasReferrerLookup({ repo: REPO, runner: mock.runner });
+
+    const referrers = await lookup.discover(DIGEST);
+    expect(referrers[0]?.kind).toBe("provenance");
+  });
+
+  it("classifies a cosign signature manifest as a signature referrer", async () => {
+    const mock = createMockProcessRunner({
+      responses: {
+        "oras discover": orasOutput([
+          { digest: "sha256:sig1", mediaType: "application/vnd.dev.cosign.simplesigning.v1+json", artifactType: "application/vnd.dev.cosign.signature" },
+        ]),
+      },
+    });
+    const lookup = createOrasReferrerLookup({ repo: REPO, runner: mock.runner });
+
+    const referrers = await lookup.discover(DIGEST);
+    expect(referrers[0]?.kind).toBe("signature");
+  });
+
+  it("skips a manifest of an unrecognized artifact type rather than guessing", async () => {
+    const mock = createMockProcessRunner({
+      responses: {
+        "oras discover": orasOutput([
+          { digest: "sha256:unknown1", mediaType: "application/vnd.acme.something+json", artifactType: "application/vnd.acme.something+json" },
+        ]),
+      },
+    });
+    const lookup = createOrasReferrerLookup({ repo: REPO, runner: mock.runner });
+
+    expect(await lookup.discover(DIGEST)).toEqual([]);
+  });
+
+  it("returns [] when oras reports no manifests", async () => {
+    const mock = createMockProcessRunner({ responses: { "oras discover": orasOutput([]) } });
+    const lookup = createOrasReferrerLookup({ repo: REPO, runner: mock.runner });
+    expect(await lookup.discover(DIGEST)).toEqual([]);
+  });
+
+  it("returns [] rather than throwing on unparseable oras output", async () => {
+    const mock = createMockProcessRunner({ responses: { "oras discover": "not json" } });
+    const lookup = createOrasReferrerLookup({ repo: REPO, runner: mock.runner });
+    expect(await lookup.discover(DIGEST)).toEqual([]);
+  });
+
+  it("throws ToolNotAvailableError when oras is not installed", async () => {
+    const mock = createMockProcessRunner({ tools: { oras: false } });
+    const lookup = createOrasReferrerLookup({ repo: REPO, runner: mock.runner });
+    await expect(lookup.discover(DIGEST)).rejects.toThrow(ToolNotAvailableError);
+  });
+
+  it("strips a trailing slash from repo before composing the reference", async () => {
+    const mock = createMockProcessRunner({ responses: { "oras discover": orasOutput([]) } });
+    const lookup = createOrasReferrerLookup({ repo: `${REPO}/`, runner: mock.runner });
+    await lookup.discover(DIGEST);
+    const call = mock.calls.find((c) => c.command.startsWith("oras discover"))!;
+    expect(call.command).toContain(`${REPO}@${DIGEST}`);
+  });
+});

package/src/lifecycle/oras-referrer-lookup.ts

@@ -0,0 +1,110 @@
+/**
+ * Real `ReferrerLookup` backend (#610, epic #551 follow-up to #568's
+ * `ReferrerLookup` interface). Shells out to `oras discover --format json
+ * <digest>` — the OCI distribution spec's referrers API, as exposed by the
+ * `oras` CLI — through the same injectable `ProcessRunner`
+ * (../components/verbs/process-runner.ts) the deep-scan `SbomGenerator`
+ * backend (../components/verbs/tool-sbom-generator.ts) and `publish-image`'s
+ * referrer-attach step share, mirroring ../components/verbs/cloud-executor.ts's
+ * `CloudExecutor` pattern once more: production code shells out, tests inject
+ * a `MockProcessRunner` and never touch a real registry/`oras` binary.
+ *
+ * Not the process-wide default: ./build-ledger.ts's `noopReferrerLookup`
+ * remains that (reports no referrers, no network, no registry credentials
+ * required) for exactly the reason `notImplementedSbomGenerator` and
+ * `SbomGenerator`'s hermetic backend aren't `sbom-generator.ts`'s default
+ * either — a project opts into the real registry-backed lookup explicitly
+ * (`buildLedgerEntries(manifest, createOrasReferrerLookup())`) rather than
+ * every previously-network-free build-ledger query silently starting to hit
+ * a registry.
+ */
+
+import {
+  defaultProcessRunner,
+  q,
+  requireTool,
+  type ProcessRunner,
+} from "../components/verbs/process-runner";
+import type { Referrer, ReferrerKind, ReferrerLookup } from "./build-ledger";
+
+/** Shape of one entry in `oras discover --format json`'s `manifests[]` array — the fields this module actually reads, not oras's full manifest descriptor. */
+interface OrasManifestDescriptor {
+  digest: string;
+  mediaType: string;
+  /** oras nests the referrer's own artifact type here for a referrers-API-discovered entry. */
+  artifactType?: string;
+  annotations?: Record<string, string>;
+}
+
+/** Shape of `oras discover --format json <ref>`'s top-level output. */
+interface OrasDiscoverOutput {
+  manifests?: OrasManifestDescriptor[];
+}
+
+/**
+ * Classify one oras-reported referrer manifest into a `ReferrerKind`, keyed
+ * off its `artifactType`/media type — the same three kinds
+ * ../components/verbs/build-ledger.ts's `Referrer.kind` already models
+ * (`sbom`, `provenance`, `signature`). An unrecognized artifact type is
+ * skipped (returns `undefined`) rather than guessed at, since a wrong
+ * classification (e.g. reporting a signature as an SBOM) would be worse than
+ * omitting it — the caller only ever sees referrers this module is confident
+ * about.
+ */
+function classify(descriptor: OrasManifestDescriptor): ReferrerKind | undefined {
+  const type = (descriptor.artifactType ?? descriptor.mediaType ?? "").toLowerCase();
+  if (type.includes("spdx") || type.includes("cyclonedx") || type.includes("sbom")) return "sbom";
+  if (type.includes("in-toto") || type.includes("provenance") || type.includes("slsa")) return "provenance";
+  if (type.includes("cosign") || type.includes("signature") || type.includes("sig.")) return "signature";
+  return undefined;
+}
+
+export interface OrasReferrerLookupOptions {
+  /** Injected process boundary. Defaults to the real, `child_process`-backed runner. */
+  runner?: ProcessRunner;
+  /** Registry/repo prefix `digest` is resolved against (e.g. `123.dkr.ecr.us-east-1.amazonaws.com/search`) — `oras discover` needs a full `repo@digest` reference, not a bare digest. Required; a `ReferrerLookup.discover(digest)` call with no repo context has nothing to query. */
+  repo: string;
+}
+
+/**
+ * Build a real `ReferrerLookup` backed by `oras discover`. `discover(digest)`
+ * runs `oras discover --format json <repo>@<digest>` and maps every returned
+ * manifest into a `Referrer`, classified by `classify` above. Returns `[]`
+ * (never throws) when `oras` reports no referrers for a digest — an image
+ * with no attached SBOM/provenance/signature is a normal outcome, not an
+ * error. Throws `ToolNotAvailableError`
+ * (../components/verbs/process-runner.ts) if `oras` itself is not installed,
+ * so a misconfigured environment fails loudly rather than silently reporting
+ * "no referrers" for every digest.
+ */
+export function createOrasReferrerLookup(options: OrasReferrerLookupOptions): ReferrerLookup {
+  const runner = options.runner ?? defaultProcessRunner();
+
+  return {
+    async discover(digest: string): Promise<Referrer[]> {
+      await requireTool(runner, "oras", `discover OCI referrers for ${options.repo}@${digest}`);
+      const ref = `${options.repo.replace(/\/+$/, "")}@${digest}`;
+      const { stdout } = await runner.run(`oras discover --format json ${q(ref)}`);
+
+      let parsed: OrasDiscoverOutput;
+      try {
+        parsed = JSON.parse(stdout) as OrasDiscoverOutput;
+      } catch {
+        return []; // no referrers / unexpected output shape — degrade to "none known", never throw on a parse hiccup.
+      }
+
+      const referrers: Referrer[] = [];
+      for (const descriptor of parsed.manifests ?? []) {
+        const kind = classify(descriptor);
+        if (!kind) continue;
+        referrers.push({
+          kind,
+          mediaType: descriptor.artifactType ?? descriptor.mediaType,
+          digest: descriptor.digest,
+          location: `${options.repo}@${descriptor.digest}`,
+        });
+      }
+      return referrers;
+    },
+  };
+}