@intentius/chant 0.101.0 → 0.104.0

package/dist/workspace/trust/run-statement.d.ts

@@ -0,0 +1,128 @@
+/**
+ * The agent-run statement (#3192, ws-090): a runner's or steward's signed
+ * word that an agent run happened as its record says.
+ *
+ * The run record (#3033, ws-076) is written by whatever ran the agent, so on
+ * its own it is as trustworthy as that writer. A statement is an in-toto
+ * Statement v1 in a DSSE envelope (./dsse.ts), signed with an Ed25519 key the
+ * trust policy at base lists under `runners` in `.chant/trust.json`, the same
+ * keys runner evidence uses (#2553, ws-069). A person's key, one the signers
+ * file lists, is never a runner key.
+ *
+ * - `subject`: each commit the run made, by its id (`digest.gitCommit`), with
+ *   its `git patch-id --stable` as an annotation when it has a patch.
+ * - `predicate`: the signer's principal, the run's id and the SHA-256 of its
+ *   record (the start and end lines), the work item, the harness, the model
+ *   and provider, and the principal the run worked for (studio-036 b).
+ *
+ * The statement is stored as a run-ledger fact: a `statement` line in the
+ * run's own file on `chant/lifecycle`, after its end. Verifying needs only
+ * the envelope, the run's record and the runner keys at base, so it works
+ * offline, and a verifier re-checks every stored statement rather than
+ * trusting that it was checked when written.
+ */
+import { z } from "zod";
+import type { RunEndLine, RunStartLine, RunView } from "../runs.js";
+import { type DsseEnvelope } from "./dsse.js";
+import type { KeyObject } from "node:crypto";
+import type { RunnerKey } from "./policy.js";
+export declare const AGENT_RUN_PREDICATE = "https://intentius.io/chant/agent-run/v1";
+/** The statement a runner signs for a run. Strict, so a verifier never acts on a field it does not know. */
+export declare const runStatementSchema: z.ZodObject<{
+    _type: z.ZodLiteral<"https://in-toto.io/Statement/v1">;
+    subject: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        digest: z.ZodObject<{
+            gitCommit: z.ZodString;
+        }, z.core.$strict>;
+        annotations: z.ZodOptional<z.ZodObject<{
+            patchId: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    predicateType: z.ZodLiteral<"https://intentius.io/chant/agent-run/v1">;
+    predicate: z.ZodObject<{
+        signer: z.ZodString;
+        run: z.ZodObject<{
+            id: z.ZodString;
+            record: z.ZodObject<{
+                sha256: z.ZodString;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+        unit: z.ZodNullable<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>>;
+        harness: z.ZodObject<{
+            name: z.ZodString;
+            version: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+        model: z.ZodNullable<z.ZodString>;
+        provider: z.ZodNullable<z.ZodString>;
+        by: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type RunStatement = z.infer<typeof runStatementSchema>;
+/**
+ * The SHA-256 of a run's record: the canonical JSON (keys sorted, no
+ * whitespace) of the array `[start line, end line]` as the ledger holds them.
+ * Statement lines are not part of it, so storing a statement never changes
+ * the hash it signs.
+ */
+export declare function runRecordDigest(start: RunStartLine, end: RunEndLine): string;
+/** The statement for an ended run, as `signer` would sign it. The run's commits are its subjects, sorted by id. */
+export declare function buildRunStatement(run: RunView, signer: string): RunStatement;
+/** The payload bytes a signer signs: the statement's canonical JSON. Any serialization verifies; this one is reproducible. */
+export declare function runStatementPayload(statement: RunStatement): Buffer;
+export declare function signRunStatement(statement: RunStatement, key: KeyObject, publicKey: string): DsseEnvelope;
+/**
+ * Why a stored statement does not verify. Each is in `reason-codes.ts`.
+ * `envelope-invalid` and `envelope-untrusted` are runner evidence's codes:
+ * the envelope is the same, and so is the rule for its keys.
+ */
+export declare const RUN_STATEMENT_FAILURE_CODES: readonly ["envelope-invalid", "envelope-untrusted", "run-statement-invalid", "run-statement-signer-mismatch", "run-statement-mismatch"];
+export type RunStatementFailureCode = (typeof RUN_STATEMENT_FAILURE_CODES)[number];
+/** One stored statement, judged against the runner keys at base and the run's record. */
+export type RunStatementVerdict = {
+    status: "verified";
+    signer: string;
+    class: RunnerKey["class"];
+    keyid: string;
+    statement: RunStatement;
+    reason: string;
+} | {
+    status: "mismatch" | "untrusted" | "invalid";
+    code: RunStatementFailureCode;
+    reason: string;
+    /** Set when a listed runner key signed it, so the failure is in what it says. */
+    signer?: string;
+    class?: RunnerKey["class"];
+    keyid?: string;
+};
+/**
+ * Verify one envelope for `run`: a signature by a runner key at base, a
+ * well-formed statement whose signer is that key's principal, for this run,
+ * and agreeing with its record. Never throws.
+ */
+export declare function verifyRunStatement(envelope: unknown, runners: readonly RunnerKey[], run: RunView): RunStatementVerdict;
+/** A run's attestation: its best statement, or why it has none. */
+export interface RunAttestation {
+    /**
+     * `signed`: a statement verifies. `unsigned`: the ledger holds none.
+     * Otherwise the best failure among the stored statements, `mismatch`
+     * before `untrusted` before `invalid`.
+     */
+    status: "signed" | "unsigned" | "mismatch" | "untrusted" | "invalid";
+    signer: string | null;
+    class: RunnerKey["class"] | null;
+    keyid: string | null;
+    /** The code of the failure `status` reports, or null when signed or unsigned. */
+    code: RunStatementFailureCode | null;
+    reason: string;
+    /** The commits the verified statement names, sorted. Empty unless signed. */
+    commits: string[];
+    /** One verdict per stored statement, in ledger order. */
+    statements: RunStatementVerdict[];
+}
+/** Judge every statement the ledger holds for `run`. */
+export declare function attestRun(run: RunView, runners: readonly RunnerKey[]): RunAttestation;
+//# sourceMappingURL=run-statement.d.ts.map

package/dist/workspace/trust/run-statement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-statement.d.ts","sourceRoot":"","sources":["../../../src/workspace/trust/run-statement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAsD,KAAK,YAAY,EAAE,MAAM,QAAQ,CAAC;AAE/F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C,eAAO,MAAM,mBAAmB,4CAA4C,CAAC;AAO7E,4GAA4G;AAC5G,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA0BpB,CAAC;AACZ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,UAAU,GAAG,MAAM,CAE5E;AAED,mHAAmH;AACnH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,YAAY,CAiB5E;AAED,8HAA8H;AAC9H,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,YAAY,GAAG,MAAM,CAEnE;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,YAAY,EAAE,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,YAAY,CAEzG;AAID;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,yIAA0K,CAAC;AACnN,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnF,yFAAyF;AACzF,MAAM,MAAM,mBAAmB,GAC3B;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACzH;IACE,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,SAAS,CAAC;IAC7C,IAAI,EAAE,uBAAuB,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAIN;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,SAAS,EAAE,EAAE,GAAG,EAAE,OAAO,GAAG,mBAAmB,CAuCtH;AAED,mEAAmE;AACnE,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,CAAC;IACrE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IACjC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,iFAAiF;IACjF,IAAI,EAAE,uBAAuB,GAAG,IAAI,CAAC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,yDAAyD;IACzD,UAAU,EAAE,mBAAmB,EAAE,CAAC;CACnC;AAID,wDAAwD;AACxD,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,SAAS,EAAE,GAAG,cAAc,CAqBrF"}

package/dist/workspace/trust/seal.d.ts

@@ -27,6 +27,11 @@ import { type TrustPolicy } from "./policy.js";
 export declare const REVIEW_SEAL_NAMESPACE = "chant-review";
 /** The ssh signature namespace of a record's author seal (#2688). */
 export declare const RECORD_SEAL_NAMESPACE = "chant-record";
+/**
+ * The ssh signature namespace of a gate approval's seal (#3163, ws-080), so a
+ * verdict, record or commit signature can't stand in for one.
+ */
+export declare const GATE_SEAL_NAMESPACE = "chant-gate";
 /** A seal as a review entry holds it. */
 export interface VerdictSeal {
     /** The principal who signed: the reviewer, as the signers file names them. */
@@ -63,6 +68,28 @@ export declare function reviewSealPayload(record: string, digest: string, verdic
  * states signs an empty last line.
  */
 export declare function recordSealPayload(record: string, digest: string, author: string, state: string | null): Buffer;
+/** The gate approval a seal covers (#3163): the fields of a gate resolution line that say what was approved, by whom and when. */
+export interface SealedGateApproval {
+    op: string;
+    gate: string;
+    environment?: string;
+    planDigest?: string;
+    resolvedBy: string;
+    /** Who relayed the approval for `resolvedBy` (#3402), when someone did. */
+    relayedBy?: string;
+    timestamp: string;
+    seal?: unknown;
+}
+/**
+ * The bytes a gate approval's seal signs (#3163): the op (or component), the
+ * gate, the environment, the plan digest, the approver and the time, joined
+ * by LF with no final newline. An approval that binds no environment or plan
+ * signs an empty line for it. A relayed approval (#3402) signs a seventh line,
+ * `relayed-by <principal>`, so the relay can't be added, changed or removed
+ * after sealing; an approval nobody relayed signs the six lines it always did,
+ * so seals made before #3402 still verify.
+ */
+export declare function gateSealPayload(a: SealedGateApproval): Buffer;
 /** The record an author seal covers (#2688). */
 export interface SealedRecord {
     record: string | null;
@@ -88,6 +115,12 @@ export declare function checkVerdictSeal(policy: TrustPolicy, v: SealedVerdict):
  * null even under an active policy: it claims no author to attest.
  */
 export declare function checkRecordSeal(policy: TrustPolicy, r: SealedRecord): SealCheck;
+/**
+ * Check a gate approval's seal (#3163), as a verdict's is checked, over
+ * {@link gateSealPayload} in the `chant-gate` namespace: it verifies only
+ * when the signers file at base lists a key for the approver.
+ */
+export declare function checkGateSeal(policy: TrustPolicy, a: SealedGateApproval): SealCheck;
 /** Why a seal could not be made. */
 export declare class SealError extends Error {
     constructor(message: string);
@@ -124,4 +157,9 @@ export declare function sealRecord(keyFile: string, r: {
     author: string;
     state: string | null;
 }): VerdictSeal;
+/**
+ * Seal a gate approval (#3163) with the key in `keyFile`, over
+ * {@link gateSealPayload}. Throws a {@link SealError}.
+ */
+export declare function sealGateApproval(keyFile: string, a: SealedGateApproval): VerdictSeal;
 //# sourceMappingURL=seal.d.ts.map

package/dist/workspace/trust/seal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"seal.d.ts","sourceRoot":"","sources":["../../../src/workspace/trust/seal.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"seal.d.ts","sourceRoot":"","sources":["../../../src/workspace/trust/seal.ts"],"names":[],"mappings":"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"}

package/dist/workspace/trust/test-repo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test-repo.d.ts","sourceRoot":"","sources":["../../../src/workspace/trust/test-repo.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,eAAO,MAAM,YAAY,SAA2E,CAAC;AAErG,MAAM,WAAW,GAAG;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,GAAG,EAAE,MAAM,CAAC;CACb;AAED,qBAAa,QAAQ;IACnB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,KAAK,EAAE,MAAM;IASzB,GAAG,CAAC,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,MAAM,CAAC,UAAU;IAc1D,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAO,GAAG,MAAM;IAIjG,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG;IAOtB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAKvC,wFAAwF;IACxF,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,MAAM;IAO5E,IAAI,IAAI,MAAM;IAId;;;;OAIG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,MAAM;IAgBvE,gEAAgE;IAChE,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAO7D,OAAO,IAAI,IAAI;CAGhB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GACtI,IAAI,CAON;AAED,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAqBtD;AAED,wBAAgB,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,SAAK,GAAG,MAAM,CAElD"}
+{"version":3,"file":"test-repo.d.ts","sourceRoot":"","sources":["../../../src/workspace/trust/test-repo.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,eAAO,MAAM,YAAY,SAA2E,CAAC;AAErG,MAAM,WAAW,GAAG;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,GAAG,EAAE,MAAM,CAAC;CACb;AAED,qBAAa,QAAQ;IACnB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,YAAY,KAAK,EAAE,MAAM,EAOxB;IAED,GAAG,CAAC,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,MAAM,CAAC,UAAU,CAYzD;IAED,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAO,GAAG,MAAM,CAEhG;IAED,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAKrB;IAED,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAGtC;IAED,wFAAwF;IACxF,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,MAAM,CAK3E;IAED,IAAI,IAAI,MAAM,CAEb;IAED;;;;OAIG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,MAAM,CActE;IAED,gEAAgE;IAChE,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAK5D;IAED,OAAO,IAAI,IAAI,CAEd;CACF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GACtI,IAAI,CAON;AAED,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAqBtD;AAED,wBAAgB,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,SAAK,GAAG,MAAM,CAElD"}

package/dist/workspace/trust/verify-cli.d.ts

@@ -1,5 +1,5 @@
 /**
- * `chant workspace verify [--base <rev>] [--head <rev>] [--require attested] [--json]`
+ * `chant workspace verify [--base <rev>] [--head <rev>] [--require attested | attested-runs] [--json]`
  * (#2547): check a change against the trust policy at its base. See ./verify.ts.
  *
  * Exit 0 when the change passes, 1 when it does not or cannot be checked.

package/dist/workspace/trust/verify.d.ts

@@ -10,11 +10,23 @@
  *
  * Attestation is opt-in (#2525 rule 6). Without a signers file at base the
  * check passes and says so, unless `--require attested` asks for more.
+ *
+ * Agent runs (#3192): a commit an agent run made, by its `Chant-Run` trailer
+ * or its run's end, is attested by a run statement that a runner or steward
+ * key at base signed and that names the commit. Such a commit counts as
+ * `attested` with the attestor `agent-run`, so `--require attested` tells a
+ * person's signed commit from a run's attested one by the attestor.
+ * `--require attested-runs` asks only that every commit a run made be
+ * covered, and needs runner keys at base but no signers file. Without
+ * `--require`, `runs` reports and nothing fails (studio-035 d).
  */
 import { type CommitAttestor, type ProvenanceLevel } from "./attestor.js";
 import { type BaseSource, type RecordProvenance } from "./provenance.js";
 import { type ExcludedSigner } from "./policy.js";
 import { type RotationRefusalCode } from "./rotation.js";
+import { type ChangeRuns } from "./run-commits.js";
+/** What `--require` takes: a provenance level, or `attested-runs` (#3192). */
+export type VerifyRequirement = ProvenanceLevel | "attested-runs";
 export interface CommitVerdict extends RecordProvenance {
     commit: string;
     subject: string;
@@ -41,8 +53,10 @@ export interface ChangeReport {
         writers: string[];
         problems: string[];
     };
-    require: ProvenanceLevel | null;
+    require: VerifyRequirement | null;
     commits: CommitVerdict[];
+    /** The change's commits that agent runs made, and which a signed run statement covers (#3192). */
+    runs: ChangeRuns;
     protectedPaths: string[];
     /** Protected paths whose content differs between the merge base and head. */
     protectedChanged: string[];
@@ -69,7 +83,7 @@ export interface VerifyOptions {
     repo: string;
     base?: string;
     head?: string;
-    require?: ProvenanceLevel;
+    require?: VerifyRequirement;
     attestors: readonly CommitAttestor[];
 }
 /**

package/dist/workspace/trust/verify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/workspace/trust/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAA+C,KAAK,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACnH,OAAO,EAAiC,KAAK,cAAc,EAAoB,MAAM,UAAU,CAAC;AAChG,OAAO,EAAoD,KAAK,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAExG,MAAM,WAAW,aAAc,SAAQ,gBAAgB;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,eAAe,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,UAAU,GAAG,IAAI,CAAC;IAC5B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE;QACN,MAAM,EAAE,OAAO,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,EAAE,CAAC;QACrB,QAAQ,EAAE,cAAc,EAAE,CAAC;QAC3B,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;IACF,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IAChC,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,6EAA6E;IAC7E,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,eAAe,EAAE,cAAc,EAAE,CAAC;IAClC;;;;OAIG;IACH,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,mBAAmB,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAChI,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,EAAE,EAAE,OAAO,CAAC;CACb;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,SAAS,EAAE,SAAS,cAAc,EAAE,CAAC;CACtC;AAMD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAUnG;AAQD,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,YAAY,CAoH9D"}
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/workspace/trust/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAA+C,KAAK,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACnH,OAAO,EAAiC,KAAK,cAAc,EAAoB,MAAM,UAAU,CAAC;AAChG,OAAO,EAAoD,KAAK,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACxG,OAAO,EAAc,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAE5D,8EAA8E;AAC9E,MAAM,MAAM,iBAAiB,GAAG,eAAe,GAAG,eAAe,CAAC;AAElE,MAAM,WAAW,aAAc,SAAQ,gBAAgB;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,eAAe,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,UAAU,GAAG,IAAI,CAAC;IAC5B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE;QACN,MAAM,EAAE,OAAO,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,EAAE,CAAC;QACrB,QAAQ,EAAE,cAAc,EAAE,CAAC;QAC3B,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;IACF,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAClC,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,kGAAkG;IAClG,IAAI,EAAE,UAAU,CAAC;IACjB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,6EAA6E;IAC7E,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,eAAe,EAAE,cAAc,EAAE,CAAC;IAClC;;;;OAIG;IACH,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,mBAAmB,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAChI,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,EAAE,EAAE,OAAO,CAAC;CACb;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,SAAS,EAAE,SAAS,cAAc,EAAE,CAAC;CACtC;AAMD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAUnG;AAQD,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,YAAY,CAsI9D"}

package/dist/workspace/wip-cli.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `chant workspace wip` (#3172, ws-085): work in progress under
+ * `refs/chant/wip/<branch>`, and its replication.
+ *
+ *   wip [--branch <branch>] [--json]              every branch's snapshots, and where replication stands
+ *   wip save [--label <text>] [--by <principal>]  snapshot the working tree, then push if the policy says so
+ *   wip restore [<snapshot>] [--by <principal>]   put the working tree back as a snapshot holds it
+ *   wip push                                      push what the policy names, for the host's schedule
+ *   wip fetch                                     on a replacement box, bring back what was replicated
+ *
+ * The read prints `wip.schema.json` with `--json`; every write prints
+ * `wip-write.schema.json`, with or without `--json`.
+ */
+import type { CommandContext } from "../cli/registry.js";
+import { type WipDocument } from "./wip.js";
+export declare function runWorkspaceWip(ctx: CommandContext): Promise<number>;
+/** The text `chant workspace wip` prints without `--json`. */
+export declare function formatWip(doc: Extract<WipDocument, {
+    branches: unknown;
+}>): string;
+//# sourceMappingURL=wip-cli.d.ts.map

package/dist/workspace/wip-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wip-cli.d.ts","sourceRoot":"","sources":["../../src/workspace/wip-cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,OAAO,EAAmH,KAAK,WAAW,EAAyB,MAAM,OAAO,CAAC;AAOjL,wBAAsB,eAAe,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA4C1E;AAED,8DAA8D;AAC9D,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,CAAC,WAAW,EAAE;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,GAAG,MAAM,CAyBlF"}

package/dist/workspace/wip.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Work in progress that survives the box (#3172, ws-085).
+ *
+ * ws-074 keeps work in progress as uncommitted files in a work branch's
+ * working tree, and #3147 keeps an unfinished attempt under a local ref. On a
+ * box (a sprite, a fountain sandbox) both sit on one disk until someone
+ * commits and pushes. This module owns one ref namespace for that work and
+ * replicates it under the policy a box block declares:
+ *
+ *   refs/chant/wip/<branch>   a chain of snapshots of the checkout on <branch>
+ *
+ * A snapshot is a commit whose tree is the whole working tree, staged,
+ * unstaged and untracked files alike (ignored files left out), taken through
+ * a temporary index so the checkout's own index is never touched. Its first
+ * parent is the snapshot before it on the same ref, when there is one, and
+ * its last parent is the commit `HEAD` named, so pushing the ref carries the
+ * branch's commits too. Its message carries `Chant-Wip-*` trailers: the
+ * branch, the head, the caller's label (hud's turn, studio's checkpoint), who
+ * took it, and whether it was a save or the checkpoint a restore takes first.
+ * The ref's first-parent chain is the branch's checkpoint history, newest
+ * first. The branch name already separates worktrees and tabs, since a
+ * branch is checked out in one worktree at a time; who took a snapshot is a
+ * trailer, not a path segment.
+ *
+ * Replication pushes the refs a policy names (work branches, kept attempts,
+ * the snapshots and the ledger branch) to a git remote under their own names,
+ * never forced, and records what reached the remote under
+ * `refs/chant/replica/<remote>/<ref without refs/>`, so `status` and `wip`
+ * report how far each ref is from the remote without fetching. `wip fetch`
+ * on a replacement box mirrors the remote into that namespace and creates or
+ * fast-forwards the local refs; `wip restore` then puts the working tree back
+ * exactly as it was saved.
+ *
+ * chant's record writes never run git (ws-074), so nothing here runs on a
+ * record write. A snapshot is taken when a caller asks (`wip save`), and
+ * chant pushes on its own only after a save or a work lease release, as the
+ * policy says.
+ */
+import { type BoxReplicate, type ReplicateRefClass, type ReplicateTrigger } from "./declaration.js";
+/** Where a branch's work-in-progress snapshots live. */
+export declare const WIP_REF_PREFIX = "refs/chant/wip/";
+/** Where chant records what reached each remote: `refs/chant/replica/<remote>/<ref without refs/>`. */
+export declare const REPLICA_REF_PREFIX = "refs/chant/replica/";
+/** The work branches a lease's run works on (`chant/work/[<member>/]<item>`). */
+export declare const WORK_BRANCH_REF_PREFIX = "refs/heads/chant/work/";
+/** The ledger branch. */
+export declare const LEDGER_REF = "refs/heads/chant/lifecycle";
+/** The version of the documents `wip` and its writes print. */
+export declare const WIP_CONTRACT_VERSION = 1;
+export declare const WIP_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/wip/v1/wip.schema.json";
+export declare const WIP_WRITE_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/wip-write/v1/wip-write.schema.json";
+/** Why `wip` could not read. Closed. */
+export declare const WIP_ERROR_CODES: readonly ["declaration-missing", "declaration-ambiguous", "declaration-unparseable", "declaration-invalid", "placement-invalid", "reader-too-old", "root-chant-required", "not-a-git-repository", "revision-unknown"];
+export type WipErrorCode = (typeof WIP_ERROR_CODES)[number];
+/** Why a `wip save|restore|push|fetch` wrote nothing. Closed. */
+export declare const WIP_WRITE_ERROR_CODES: readonly ["declaration-missing", "declaration-ambiguous", "declaration-unparseable", "declaration-invalid", "placement-invalid", "reader-too-old", "root-chant-required", "not-a-git-repository", "revision-unknown", "write-usage-invalid", "wip-no-branch", "wip-none", "wip-snapshot-unknown", "wip-branch-other", "wip-race", "wip-policy-none", "wip-remote-unknown", "principal-unidentified"];
+export type WipWriteErrorCode = (typeof WIP_WRITE_ERROR_CODES)[number];
+/** What a snapshot was taken for: a caller's save, or the checkpoint a restore takes before it changes the working tree. */
+export type WipSnapshotKind = "save" | "pre-restore";
+/** One snapshot of a branch's working tree. */
+export interface WipSnapshot {
+    commit: string;
+    /** The tree of the working tree as it was. */
+    tree: string;
+    /** The branch it was taken on. */
+    branch: string;
+    /** The commit `HEAD` named when it was taken. */
+    head: string;
+    kind: WipSnapshotKind;
+    /** What the caller called it, such as a turn id, or null. */
+    label: string | null;
+    /** Who took it, as the caller named them, or null. */
+    by: string | null;
+    /** When it was taken, ISO 8601. */
+    at: string;
+}
+/** A replicate policy as the read contract prints it: the box that declares it and its fields, defaults filled in. */
+export interface ReplicatePolicyView {
+    box: string;
+    remote: string;
+    refs: ReplicateRefClass[];
+    on: ReplicateTrigger[];
+    every: string | null;
+}
+/** One ref a policy replicates and where it stands against the remote. */
+export interface ReplicaRefState {
+    ref: string;
+    class: ReplicateRefClass;
+    commit: string;
+    /** What the remote held at the last push or fetch through chant (or, for a branch, git's remote-tracking ref), or null when unknown. */
+    replica: string | null;
+    replicated: boolean;
+    /** Commits reachable from `commit` that nothing known to be on the remote reaches: 0 when replicated. */
+    ahead: number;
+}
+/** Where every replicated ref stands (#3172). Read locally; never fetches. */
+export interface ReplicationState {
+    policy: ReplicatePolicyView;
+    /** Whether the checkout has a git remote of the policy's name. */
+    remoteConfigured: boolean;
+    /** True when every ref the policy names is on the remote as it is locally. */
+    replicated: boolean;
+    refs: ReplicaRefState[];
+}
+/** One ref a push or fetch moved, or could not. */
+export interface RefPush {
+    ref: string;
+    commit: string;
+    /** Why the remote refused it or could not be reached; absent when it went. */
+    reason?: string;
+}
+/** What one push did. */
+export interface ReplicationPush {
+    remote: string;
+    pushed: RefPush[];
+    rejected: RefPush[];
+    /** Refs that were already on the remote as they are locally. */
+    upToDate: number;
+}
+type Head = {
+    $schema: string;
+    contract: number;
+    chant: string;
+};
+/** What `chant workspace wip --json` prints. */
+export type WipDocument = (Head & {
+    checkout: {
+        branch: string | null;
+        head: string | null;
+    };
+    branches: {
+        branch: string;
+        ref: string;
+        tip: string;
+        snapshots: WipSnapshot[];
+    }[];
+    replication: ReplicationState | null;
+}) | (Head & {
+    error: {
+        code: WipErrorCode;
+        message: string;
+    };
+});
+export type WipAction = "save" | "restore" | "push" | "fetch";
+/** One ref `wip fetch` looked at, and what it did with the local ref. */
+export interface FetchedRef {
+    ref: string;
+    class: ReplicateRefClass;
+    /** What the remote has. */
+    remote: string;
+    /** The local ref before the fetch, or null when there was none. */
+    local: string | null;
+    result: "created" | "fast-forward" | "up-to-date" | "ahead" | "diverged" | "checked-out";
+}
+/** What `chant workspace wip save|restore|push|fetch` prints. */
+export type WipWriteDocument = (Head & {
+    action: "save";
+    branch: string;
+    ref: string;
+    created: boolean;
+    snapshot: WipSnapshot;
+    replication: ReplicationPush | null;
+}) | (Head & {
+    action: "restore";
+    branch: string;
+    ref: string;
+    head: string;
+    snapshot: WipSnapshot;
+    checkpoint: {
+        created: boolean;
+        snapshot: WipSnapshot;
+    };
+    headMoved: boolean;
+    paths: string[];
+}) | (Head & {
+    action: "push";
+    policy: ReplicatePolicyView;
+    replication: ReplicationPush;
+}) | (Head & {
+    action: "fetch";
+    policy: ReplicatePolicyView;
+    refs: FetchedRef[];
+    failed: string | null;
+}) | (Head & {
+    action: WipAction | null;
+    error: {
+        code: WipWriteErrorCode;
+        message: string;
+    };
+});
+/** The ref a branch's snapshots live on. */
+export declare function wipRef(branch: string): string;
+/** The ref recording what `remote` holds of `ref`. */
+export declare function replicaRef(remote: string, ref: string): string;
+/** The class a ref belongs to, or null when no policy replicates it. */
+export declare function refClass(ref: string): ReplicateRefClass | null;
+/**
+ * The snapshots on `ref`, newest first: its first-parent chain, down to the
+ * first commit that is not a snapshot (the branch commit the oldest was taken
+ * on). History the branch itself reaches is never walked.
+ */
+export declare function listSnapshots(top: string, ref: string, branch: string): WipSnapshot[];
+/** A box's replicate policy as the read contract prints it. */
+export declare function policyView(box: string, r: BoxReplicate): ReplicatePolicyView;
+/**
+ * The replicate policy the declaration in the working tree states, or null
+ * when no box block declares one or there is no declaration. A declaration
+ * that can't be read throws its WorkspaceReadError.
+ */
+export declare function readReplicatePolicy(cwd: string): ReplicatePolicyView | null;
+/** Where every ref the policy names stands against its remote, read locally (#3172). */
+export declare function replicationState(top: string, policy: ReplicatePolicyView): ReplicationState;
+/** Push every ref the policy names that the remote doesn't hold as it is locally. Never forced. */
+export declare function pushReplicas(top: string, policy: ReplicatePolicyView): ReplicationPush;
+/**
+ * Push what the policy names after `event`, when the policy says chant pushes
+ * then. Never throws: a box that can't reach its remote still saves and
+ * releases, and `status` shows what is behind.
+ */
+export declare function replicateAfter(event: ReplicateTrigger, cwd: string): ReplicationPush | null;
+/** `chant workspace wip [--branch <branch>] --json`: every branch's snapshots, and where replication stands. */
+export declare function workspaceWip(req: {
+    cwd: string;
+    branch?: string;
+}): WipDocument;
+export interface WipSaveRequest {
+    cwd: string;
+    /** What the caller calls this snapshot, such as `turn:12` (`--label`). */
+    label?: string;
+    /** Who took it (`--by`), held to the identity rule at base (ws-080). */
+    by?: string;
+    /** The agent session (`CHANT_AGENT`). */
+    agent?: string;
+}
+/** `chant workspace wip save`: snapshot the checkout's working tree onto `refs/chant/wip/<branch>`, then push when the policy says so. */
+export declare function wipSave(req: WipSaveRequest): WipWriteDocument;
+export interface WipRestoreRequest {
+    cwd: string;
+    /** The snapshot to restore, as a commit id or anything git resolves to one; the branch's latest when undefined. */
+    snapshot?: string;
+    by?: string;
+    agent?: string;
+}
+/**
+ * `chant workspace wip restore [<snapshot>]`: put the working tree back as
+ * the snapshot holds it. It first takes a snapshot of the working tree as it
+ * is (kind `pre-restore`), so a restore can itself be undone. The branch and
+ * `HEAD` never move; the index is reset to `HEAD`, so everything restored
+ * reads as uncommitted, staged or not (#3160 counts them alike). Ignored
+ * files are left as they are.
+ */
+export declare function wipRestore(req: WipRestoreRequest): WipWriteDocument;
+/** `chant workspace wip push`: push every ref the policy names that the remote doesn't hold, for a host's schedule (`every`). */
+export declare function wipPush(req: {
+    cwd: string;
+}): WipWriteDocument;
+/**
+ * `chant workspace wip fetch`: on a replacement box, mirror what the remote
+ * holds of the policy's refs into `refs/chant/replica/<remote>/`, then create
+ * each local ref that is missing and fast-forward each that is behind. A
+ * branch checked out in any worktree, and a local ref that has moved on or
+ * forked, are left as they are and reported.
+ */
+export declare function wipFetch(req: {
+    cwd: string;
+}): WipWriteDocument;
+export {};
+//# sourceMappingURL=wip.d.ts.map

package/dist/workspace/wip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wip.d.ts","sourceRoot":"","sources":["../../src/workspace/wip.ts"],"names":[],"mappings":"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"}