@intentius/chant 0.100.0 → 0.101.0

package/src/workspace/declaration.ts

@@ -107,6 +107,35 @@ export interface ChangesPolicy {
   ignore: string[];
 }
 
+/** The core principal classes (#2524 D5). */
+export const PRINCIPAL_CLASSES = ["human", "agent", "runner", "service"] as const;
+export type PrincipalClass = (typeof PRINCIPAL_CLASSES)[number];
+
+/** How a record is written, as the records commands name it (#2548). */
+export const WRITE_VERBS = ["new", "amend", "review", "close"] as const;
+export type WriteVerb = (typeof WRITE_VERBS)[number];
+
+/** One principal class's entry in the declaration's `writeScope` (#2548, ws-067). */
+export interface ClassScope {
+  /** The members whose files the class may write, or null for every path. Always null for the agent class: a session writes its own member. */
+  members: string[] | null;
+  /** Kind name to the verbs the class may write it with, or null for every kind in reach with every verb. */
+  records: Record<string, WriteVerb[]> | null;
+  pointer: string;
+}
+
+/** The declaration's `writeScope` block: an entry per restricted class. A class with no entry is not restricted. */
+export type WriteScope = Partial<Record<PrincipalClass, ClassScope>>;
+
+/** An agent session the declaration names (#2524 D20, #2548): bound to one member. */
+export interface AgentDeclaration {
+  name: string;
+  member: string;
+  /** Principals that write only as this session. */
+  principals: string[];
+  pointer: string;
+}
+
 export interface MemberRole {
   name: string;
   /** Relative to the member's directory, or null for the whole member. */
@@ -135,6 +164,8 @@ export interface LinkDeclaration {
   output: string;
   /** The link kind as written, or null for the default (`output`). */
   kind: string | null;
+  /** A telemetry link's OTLP protocol as written (#2558), or null. */
+  protocol: string | null;
   /** The link's JSON Pointer in the file, for messages. */
   pointer: string;
 }
@@ -292,6 +323,8 @@ export interface Member {
   box: BoxDeclaration | null;
   upstream: string | null;
   because: string | null;
+  /** Whether `chant workspace export` takes the member (#2552, D10). False when the entry does not say. */
+  travel: boolean;
   suppress: Suppression[];
   /** The entry's JSON Pointer in the file, for messages. */
   pointer: string;
@@ -338,6 +371,10 @@ export interface Declaration {
   hosts: Host[];
   /** The forward coverage check's policy (#2773), or null when the declaration has no `changes` block. */
   changes: ChangesPolicy | null;
+  /** Who may write what (#2548), or null when the declaration has no `writeScope` block. */
+  writeScope: WriteScope | null;
+  /** The agent sessions, in file order (#2548). */
+  agents: AgentDeclaration[];
   /** The file, relative to the workspace root's tree (`chant.workspace.json` or `.jsonc`). */
   file: string;
 }
@@ -543,10 +580,11 @@ export function parseDeclaration(text: string, file: string, reader: string = re
       handWritten: g.handWritten ? { because: (g.handWritten as { because: string }).because } : null,
       pointer: `${pointer}/generated/${j}`,
     }));
-    const links = ((e.links as { member: string; output: string; kind?: string }[] | undefined) ?? []).map((l, j) => ({
+    const links = ((e.links as { member: string; output: string; kind?: string; protocol?: string }[] | undefined) ?? []).map((l, j) => ({
       member: l.member,
       output: l.output,
       kind: l.kind ?? null,
+      protocol: l.protocol ?? null,
       pointer: `${pointer}/links/${j}`,
     }));
     const records = recordKindsOf(e.records, e.dir as string, e.name as string, `${pointer}/records`);
@@ -566,6 +604,7 @@ export function parseDeclaration(text: string, file: string, reader: string = re
       box,
       upstream: (e.upstream as string | undefined) ?? null,
       because: (e.because as string | undefined) ?? null,
+      travel: e.travel === true,
       suppress,
       pointer,
     };
@@ -673,6 +712,8 @@ export function parseDeclaration(text: string, file: string, reader: string = re
   }
 
   const hosts = hostsOf(obj, members, at);
+  const writeScope = writeScopeOf(obj.writeScope, members, at);
+  const agents = agentsOf(obj.agents, members, at);
 
   const pins = ((obj.pins as Record<string, string>[] | undefined) ?? []).map((p) => ({
     package: p.package ?? null,
@@ -695,10 +736,74 @@ export function parseDeclaration(text: string, file: string, reader: string = re
     diagrams: ownDiagrams,
     hosts,
     changes: changesOf(obj.changes as Record<string, unknown> | undefined),
+    writeScope,
+    agents,
     file,
   };
 }
 
+/**
+ * The `writeScope` block, already validated, with the rule the schema can't
+ * say (#2548): a member it names is a declared member.
+ */
+function writeScopeOf(raw: unknown, members: Member[], at: (pointer: string, key?: boolean) => ErrorLocation): WriteScope | null {
+  if (raw === undefined) return null;
+  const block = raw as Partial<Record<PrincipalClass, { members?: "*" | string[]; records?: Record<string, WriteVerb[]> }>>;
+  const out: WriteScope = {};
+  for (const cls of PRINCIPAL_CLASSES) {
+    const entry = block[cls];
+    if (entry === undefined) continue;
+    const pointer = `/writeScope/${cls}`;
+    const list = entry.members === undefined || entry.members === "*" ? null : [...entry.members];
+    for (const [i, name] of (list ?? []).entries()) {
+      if (!members.some((m) => m.name === name)) {
+        throw new WorkspaceReadError(
+          "declaration-invalid",
+          `writeScope.${cls} names the member ${JSON.stringify(name)}, which the declaration does not declare; declared members: ${members.map((m) => m.name).join(", ") || "none"}`,
+          at(`${pointer}/members/${i}`),
+        );
+      }
+    }
+    const records = entry.records === undefined ? null : Object.fromEntries(Object.entries(entry.records).map(([k, v]) => [k, [...v]]));
+    out[cls] = { members: list, records, pointer };
+  }
+  return out;
+}
+
+/**
+ * The `agents` list, already validated, with the rules the schema can't say
+ * (#2548): names are unique, each names a declared member, and a principal
+ * is listed by one session at most.
+ */
+function agentsOf(raw: unknown, members: Member[], at: (pointer: string, key?: boolean) => ErrorLocation): AgentDeclaration[] {
+  const agents = ((raw as { name: string; member: string; principals?: string[] }[] | undefined) ?? []).map((a, i) => ({
+    name: a.name,
+    member: a.member,
+    principals: [...(a.principals ?? [])],
+    pointer: `/agents/${i}`,
+  }));
+  const byName = new Map<string, AgentDeclaration>();
+  const byPrincipal = new Map<string, AgentDeclaration>();
+  for (const a of agents) {
+    const first = byName.get(a.name);
+    if (first) throw new WorkspaceReadError("declaration-invalid", `the agent name ${JSON.stringify(a.name)} is already used by the agent at ${first.pointer}`, at(`${a.pointer}/name`));
+    byName.set(a.name, a);
+    if (!members.some((m) => m.name === a.member)) {
+      throw new WorkspaceReadError(
+        "declaration-invalid",
+        `agent ${a.name} is bound to ${JSON.stringify(a.member)}, which is not a declared member; an agent session is bound to one member, not an example group`,
+        at(`${a.pointer}/member`),
+      );
+    }
+    for (const [i, p] of a.principals.entries()) {
+      const other = byPrincipal.get(p);
+      if (other) throw new WorkspaceReadError("declaration-invalid", `the principal ${JSON.stringify(p)} is already listed by agent ${other.name}`, at(`${a.pointer}/principals/${i}`));
+      byPrincipal.set(p, a);
+    }
+  }
+  return agents;
+}
+
 /** The `changes` block, already validated, with its defaults (#2773). */
 function changesOf(block: Record<string, unknown> | undefined): ChangesPolicy | null {
   if (block === undefined) return null;

package/src/workspace/declared-kinds.test.ts

@@ -5,6 +5,7 @@
  * `--kind` is not given, while `--kind` still overrides.
  */
 
+import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { afterAll, afterEach, beforeEach, describe, expect, test, vi } from "vitest";
@@ -199,6 +200,38 @@ describe("records without --kind reads every declared kind (#2680)", () => {
     expect(printed.kinds.map((k: { records: { id: string }[] }) => k.records.map((r) => r.id))).toEqual([["ref-001"], ["ref-001"]]);
   });
 
+  test("--current adds the spec: the current records of spec: true kinds, with the files they pin (#2546, #2524 D20)", async () => {
+    const server = "export const port = 8080;\n";
+    const sha256 = createHash("sha256").update(server).digest("hex");
+    // ref-004 supersedes ref-001 and pins the app's server file; the note kind is not part of the spec.
+    const ref004 = REF_001.replace('id: "ref-001"', 'id: "ref-004"')
+      .replace("supersedes: []", 'supersedes:\n  - decision: "ref-001"')
+      .replace(/^evidence:\n/m, `evidence:\n  - title: "The server"\n    path: "app/server.mjs"\n    sha256: "${sha256}"\n`);
+    const root = workspace({
+      "decisions/ref-004-how-the-app-is-deployed-now.md": ref004,
+      "design/notes/note.kind.mjs": NOTE_KIND.replace("spec: true", "spec: false"),
+    });
+    expect(await run(root, "--current", "--json")).toBe(0);
+    const printed = JSON.parse(out.join("\n"));
+    expectValid(printed);
+    expect(printed.kinds.map((k: { kind: { spec: boolean } }) => k.kind.spec)).toEqual([true, false]);
+    expect(printed.spec.kinds).toEqual([{ member: null, path: "decisions/decision.kind.mjs", name: null }]);
+    expect(printed.spec.records).toEqual([
+      expect.objectContaining({
+        kind: "decision",
+        id: "ref-004",
+        path: "decisions/ref-004-how-the-app-is-deployed-now.md",
+        state: "decided",
+        valid: true,
+        assets: [{ path: "app/server.mjs", sha256, actual: sha256, state: "pinned" }],
+      }),
+    ]);
+    // Without --current there is no spec: superseded records are still listed under kinds.
+    out.length = 0;
+    expect(await run(root, "--json")).toBe(0);
+    expect(JSON.parse(out.join("\n")).spec).toBeUndefined();
+  });
+
   test("a kind that can't be read is listed with its error, the others are read, and the exit code is 1", async () => {
     const root = workspace({}, [{ kind: "gone.kind.mjs" }]);
     expect(await run(root, "--json")).toBe(1);

package/src/workspace/evidence.schema.json

@@ -0,0 +1,279 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/evidence/v1/evidence.schema.json",
+  "title": "chant workspace evidence output",
+  "description": "What `chant workspace evidence verify --json` prints (#2553), and what a refused `chant workspace evidence sign --json` prints: runner evidence, an in-toto statement over record hashes in a DSSE envelope, checked offline against the runner keys `.chant/trust.json` lists at the base revision. Version 1 of the read contract. Readers ignore fields they do not know; a field is only ever added within a version. The error codes are a closed list, each in the one closed list of `reason-codes.ts`.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "type": "object",
+      "description": "A runner key the policy at base lists signed the envelope. `status` says whether the records still hash as signed; it exits 1 when they don't.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "at",
+        "ok",
+        "status",
+        "runner",
+        "class",
+        "keyid",
+        "statement",
+        "subjects"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/evidence/v1/evidence.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "at": {
+          "type": "string",
+          "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$",
+          "description": "The commit the subjects were compared at."
+        },
+        "ok": {
+          "const": true
+        },
+        "status": {
+          "enum": [
+            "current",
+            "stale"
+          ],
+          "description": "current when every subject hashes the same at `at`; stale otherwise. Stale evidence is never reused."
+        },
+        "runner": {
+          "type": "string",
+          "description": "The runner principal whose key signed."
+        },
+        "class": {
+          "enum": [
+            "runner",
+            "service"
+          ],
+          "description": "A CI runner or a service, as `.chant/trust.json` lists it."
+        },
+        "keyid": {
+          "type": "string",
+          "description": "The ssh SHA256 fingerprint of the key that signed."
+        },
+        "statement": {
+          "$ref": "#/$defs/statement"
+        },
+        "subjects": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/subject"
+          }
+        }
+      }
+    },
+    "statement": {
+      "type": "object",
+      "description": "The in-toto Statement v1 the runner signed.",
+      "required": [
+        "_type",
+        "subject",
+        "predicateType",
+        "predicate"
+      ],
+      "properties": {
+        "_type": {
+          "const": "https://in-toto.io/Statement/v1"
+        },
+        "subject": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "name",
+              "digest"
+            ],
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "digest": {
+                "type": "object",
+                "required": [
+                  "sha256"
+                ],
+                "properties": {
+                  "sha256": {
+                    "type": "string",
+                    "pattern": "^[0-9a-f]{64}$"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "predicateType": {
+          "const": "https://intentius.io/chant/runner-evidence/v1"
+        },
+        "predicate": {
+          "type": "object",
+          "required": [
+            "runner",
+            "commit",
+            "tree",
+            "check"
+          ],
+          "properties": {
+            "runner": {
+              "type": "string"
+            },
+            "commit": {
+              "type": "string",
+              "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$"
+            },
+            "tree": {
+              "type": "string",
+              "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$"
+            },
+            "check": {
+              "type": "string",
+              "description": "The check's id, as given to --check-id."
+            },
+            "claim": {
+              "type": "object",
+              "required": [
+                "sha256"
+              ],
+              "properties": {
+                "sha256": {
+                  "type": "string",
+                  "pattern": "^[0-9a-f]{64}$"
+                }
+              }
+            },
+            "environment": {
+              "type": "object",
+              "required": [
+                "sha256"
+              ],
+              "properties": {
+                "sha256": {
+                  "type": "string",
+                  "pattern": "^[0-9a-f]{64}$"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "subject": {
+      "type": "object",
+      "required": [
+        "name",
+        "signed",
+        "now",
+        "matches"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "The record's path from the repository root."
+        },
+        "signed": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "now": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "string",
+              "pattern": "^[0-9a-f]{64}$"
+            }
+          ],
+          "description": "The record's hash at `at`, or null when it is not there."
+        },
+        "matches": {
+          "type": "boolean"
+        }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "description": "The evidence was refused, or could not be checked. Exits 1.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "at",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/evidence/v1/evidence.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "at": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "string",
+              "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$"
+            }
+          ]
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "not-a-git-repository",
+                "revision-unknown",
+                "trust-policy-unreadable",
+                "envelope-unreadable",
+                "envelope-invalid",
+                "envelope-untrusted",
+                "evidence-payload-type",
+                "evidence-statement-invalid",
+                "evidence-runner-mismatch",
+                "runner-key-invalid",
+                "runner-key-is-signer",
+                "runner-key-unlisted",
+                "kind-unreadable",
+                "kind-invalid",
+                "schema-unreadable",
+                "schema-id-mismatch",
+                "schema-invalid",
+                "location-missing"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/src/workspace/export-cli.ts

@@ -0,0 +1,180 @@
+/**
+ * `chant workspace export [<member>...] [--to <member>] [--param name=value] [--dry-run] [--json]`,
+ * `chant workspace import [<dir>] [--remove] [--dry-run] [--json]` and
+ * `chant workspace admit <return id> [--note <text>] [--dry-run] [--json]` (#2552).
+ *
+ * See ./export.ts, ./import.ts and ./returns.ts.
+ */
+
+import { join } from "node:path";
+import { formatError, formatInfo, formatSuccess, formatWarning } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { findWorkspaceRoot } from "../project-root";
+import { WorkspaceReadError } from "./declaration";
+import { LockError } from "./lineage-lock";
+import { parseParamArgs } from "./template-manifest";
+
+const EXPORT_USAGE = "chant workspace export [<member>[,<member>...]] [--to <export member>] [--param name=value] [--dry-run] [--json]";
+const IMPORT_USAGE = "chant workspace import [<dir>] [--remove] [--dry-run] [--json]";
+const ADMIT_USAGE = "chant workspace admit <return id> [--note <text>] [--dry-run] [--json]";
+
+function workspaceRoot(usage: string): string | undefined {
+  const found = findWorkspaceRoot(process.cwd());
+  if (!found) {
+    console.error(formatError({ message: "no chant.workspace.json here or above", hint: usage }));
+    return undefined;
+  }
+  return found.dir;
+}
+
+function fail(err: unknown, usage: string): number {
+  if (err instanceof WorkspaceReadError) {
+    console.error(formatError({ message: `${err.code}: ${err.describe()}`, hint: usage }));
+    return 1;
+  }
+  if (err instanceof LockError) {
+    console.error(formatError({ message: err.message, hint: usage }));
+    return 1;
+  }
+  throw err;
+}
+
+export async function runWorkspaceExport(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const root = workspaceRoot(EXPORT_USAGE);
+  if (!root) return 1;
+  const members = [args.extraPositional, args.extraPositional2]
+    .filter((x): x is string => x !== undefined)
+    .flatMap((x) => x.split(","))
+    .map((x) => x.trim())
+    .filter(Boolean);
+  try {
+    const { exportWorkspace } = await import("./export");
+    const r = await exportWorkspace({
+      root,
+      members,
+      to: args.migrateTo,
+      params: args.param?.length ? parseParamArgs(args.param) : undefined,
+      dryRun: args.dryRun,
+    });
+    if (args.json) {
+      console.log(JSON.stringify(r, null, 2));
+      return 0;
+    }
+    const m = r.manifest;
+    console.log(`${m.id}  ${m.whole ? "workspace" : "members"} ${m.members.join(", ")} -> ${r.member} (${r.dir})`);
+    console.log(`  ${Object.keys(m.files).length} file(s), ${Object.keys(m.locks).length} lock(s)${m.dirs.length ? `, record directories ${m.dirs.join(", ")}` : ""}`);
+    if (r.switched.length > 0) console.log(`  host values switched in: ${r.switched.join(", ")}`);
+    const d = m.dropped;
+    const left = [
+      ...d.links.map((l) => `link ${l.member} -> ${l.to}`),
+      ...d.agents.map((a) => `agent ${a}`),
+      ...d.pins.map((p) => `pin ${p}`),
+      ...d.records.map((k) => `record kind ${k}`),
+      ...d.diagrams.map((x) => `diagram ${x}`),
+    ];
+    if (left.length > 0) console.log(`  left out of the export's declaration: ${left.join("; ")}`);
+    if (m.from.dirty) console.error(formatWarning({ message: "exported paths have uncommitted changes; the export records HEAD, which does not hold them" }));
+    if (r.written) console.error(formatSuccess(`wrote the export into ${r.dir}. It is a workspace of its own; copy it where it goes, and bring it back with chant workspace import.`));
+    else console.error(formatInfo("--dry-run: nothing written"));
+    return 0;
+  } catch (err) {
+    return fail(err, EXPORT_USAGE);
+  }
+}
+
+export async function runWorkspaceImport(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  if (args.extraPositional2) {
+    console.error(formatError({ message: `unexpected argument: ${args.extraPositional2}`, hint: IMPORT_USAGE }));
+    return 1;
+  }
+  const root = workspaceRoot(IMPORT_USAGE);
+  if (!root) return 1;
+  try {
+    const { importWorkspace } = await import("./import");
+    const r = await importWorkspace({ root, from: args.extraPositional ? join(process.cwd(), args.extraPositional) : undefined, remove: args.remove, dryRun: args.dryRun });
+    const refused = r.outside.length > 0 || r.conflicts.length > 0;
+    if (args.json) {
+      console.log(JSON.stringify(r, null, 2));
+      return refused ? 1 : 0;
+    }
+    console.log(`${r.export} from ${r.from}`);
+    for (const p of r.written) console.log(`  write   ${p}${r.hostValues.includes(p) ? " (host values back)" : ""}`);
+    for (const p of r.removed) console.log(`  remove  ${p}`);
+    for (const p of r.locks) console.log(`  lock    ${p}`);
+    for (const c of r.conflicts) console.log(`  conflict ${c.path}: ${c.reason}`);
+    for (const p of r.outside) console.log(`  outside ${p}`);
+    if (r.outside.length > 0) {
+      console.error(formatError({ message: `the copy holds ${r.outside.length} file(s) outside the members that went with the export; import never writes into another member, so nothing was written` }));
+      return 1;
+    }
+    if (r.conflicts.length > 0) {
+      console.error(formatError({ message: `${r.conflicts.length} conflict(s): nothing was written. Resolve them in the copy or here, then import again` }));
+      return 1;
+    }
+    if (r.return) {
+      const proved = Object.values(r.return.paths).filter((p) => p.origin).length;
+      console.log(`  return  ${r.return.id}: ${proved} file(s) carry the commit they were made in${r.return.signers.length ? `, signed by ${r.return.signers.map((s) => `${s.principal} (${s.fingerprint || "key"})`).join(", ")}` : ""}`);
+    }
+    if (!r.applied) {
+      console.error(formatInfo("--dry-run: nothing written"));
+      return 0;
+    }
+    if (!r.return) console.error(formatInfo("the copy holds no change since the export"));
+    if (r.member) console.log(`  member  ${r.member.name} ${r.member.action}${r.member.note ? `: ${r.member.note}` : ""}`);
+    if (r.returnRecord) {
+      console.error(
+        formatSuccess(
+          `imported, and recorded the return in ${r.returnRecord}. Review and commit it. Work signed by keys the policy at base does not list reads as attested-unverifiable-here until an admin runs chant workspace admit ${r.return!.id} and merges that change.`,
+        ),
+      );
+    }
+    return 0;
+  } catch (err) {
+    return fail(err, IMPORT_USAGE);
+  }
+}
+
+export async function runWorkspaceAdmit(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const id = args.extraPositional;
+  if (!id || args.extraPositional2) {
+    console.error(formatError({ message: "admit takes one return id, such as ret-0123456789ab", hint: ADMIT_USAGE }));
+    return 1;
+  }
+  const root = workspaceRoot(ADMIT_USAGE);
+  if (!root) return 1;
+  try {
+    const { readFileSync, existsSync } = await import("node:fs");
+    const { RETURNS_DIR, admitReturn, parseReturn } = await import("./returns");
+    const { gitTopOf } = await import("./export");
+    const file = join(root, RETURNS_DIR, `${id}.json`);
+    if (!/^ret-[0-9a-f]{12}$/.test(id) || !existsSync(file)) throw new LockError(`no return ${id} in ${RETURNS_DIR}`);
+    const ret = parseReturn(readFileSync(file, "utf-8"), file);
+    const repo = gitTopOf(root);
+    if (!repo) throw new LockError("admit writes .chant/trust.json at the repository root, and this workspace is not in a git repository");
+    const r = admitReturn(repo, ret, { note: args.note, dryRun: args.dryRun });
+    if (args.json) {
+      console.log(JSON.stringify(r, null, 2));
+      return 0;
+    }
+    if (r.added.length === 0) {
+      console.error(formatInfo(`every signer of ${id} is already admitted in ${r.path}`));
+      return 0;
+    }
+    for (const s of r.added) console.log(`  admit ${s.principal}  ${s.key.slice(0, 40)}...`);
+    if (!r.written) {
+      console.error(formatInfo("--dry-run: nothing written"));
+      return 0;
+    }
+    console.error(
+      formatSuccess(
+        `added ${r.added.length} signer(s) for ${id} to ${r.path}. Check each principal, then commit it signed: the file is policy, so the admission counts once an admin's signed commit is merged to the base branch.`,
+      ),
+    );
+    return 0;
+  } catch (err) {
+    return fail(err, ADMIT_USAGE);
+  }
+}