@intentius/chant 0.85.0 → 0.87.0

package/dist/workspace/reason-codes.d.ts

@@ -44,22 +44,57 @@ export declare const REASONS: {
     readonly "ir-version-unsupported": "The member's IR has a version this chant can't read.";
     readonly "ledger-unreadable": "Reading the ledger failed, so nothing from it is listed.";
     readonly "ledger-malformed": "Some lines of the ledger aren't release records; the rest are listed.";
-    readonly "record-unparseable": "No front matter, a YAML error, or a value outside the JSON subset of YAML.";
-    readonly "record-schema-invalid": "The front matter does not match the kind's schema.";
+    readonly "gates-no-ledger": "The checkout has no chant/lifecycle branch, so there is no gate ledger to read.";
+    readonly "gates-no-gate-ledger": "The branch has no gate ledger for the member: no run of it has reached a gate.";
+    readonly "gates-ledger-unreadable": "Reading the member's gate ledger failed, so no gate is listed.";
+    readonly "record-unparseable": "No front matter, a YAML error or a value outside the JSON subset of YAML, or for a JSON kind a file that is not one object or repeats a member name.";
+    readonly "record-schema-invalid": "The record's front matter, or its JSON object, does not match the kind's schema.";
     readonly "record-id-duplicate": "Another record earlier in path order has the same id.";
     readonly "record-supersedes-unknown": "A supersedes link names an id no record has.";
     readonly "record-supersedes-conflict": "A second closed record supersedes a record another one already superseded.";
+    readonly "session-seal-mismatch": "A closed session's seal is not the digest of its text: the session changed after it closed.";
+    readonly "session-verdict-unknown-record": "A session's verdict names a record that none of the session kind's subject records has.";
     readonly "asset-drift": "A file the record pins by hash has changed: its bytes no longer hash to the pinned sha256.";
     readonly "asset-missing": "A file the record pins by hash does not exist in the tree read.";
     readonly "asset-stale": "A file the record pins is unchanged at the hash a record it supersedes pinned: the decision changed and the artifact did not follow.";
     readonly "record-supersedes-pending": "A supersedes link from a record whose state is weaker than the record it names, so the link has no effect yet.";
     readonly "record-no-evidence": "The record's evidence list is empty: it cites nothing and pins no file. Information for a reviewer, never an error.";
+    readonly "review-undigested": "A verdict names no digest of the text it judged. It still counts, and an amendment does not stop it counting.";
+    readonly "work-needs-unknown": "A work record's needs list names a work id no record has, so the item stays blocked.";
+    readonly "work-implements-unknown": "A work record's implements list names a decision id no decision has.";
+    readonly "work-needs-cycle": "A work record needs itself through its needs links, so it can never be ready.";
+    readonly "work-implements-undecided": "A work record implements a decision whose state is not approved, such as proposed.";
+    readonly "work-done-unpinned": "A work record is done and its evidence list is empty: nothing shows the work was done.";
+    readonly "work-closed-without-date": "A work record is done or dropped and has no closing date.";
+    readonly "work-done-gap-open": "A work record is done, and the finding it came from still fires on its region. graph --intent raises it, and records does by walking that region.";
+    readonly "review-decider": "The verdict is the decider's own, and the quorum counts verdicts besides the decider's.";
+    readonly "review-agent": "The reviewer holds the agent role in the trust policy at base.";
+    readonly "review-duplicate": "A later verdict by the same principal replaces this one. Names are compared after NFKC, trimming and lower-casing.";
+    readonly "review-older-digest": "The verdict names a digest other than the record's text now: the record changed after the verdict.";
+    readonly "review-unattested": "An attestation policy is active at base, and the verdict carries no seal that verifies for its reviewer.";
+    readonly "seal-missing": "The verdict carries no seal.";
+    readonly "seal-signer-unlisted": "The reviewer has no key in the signers file at base, so the seal can't count.";
+    readonly "seal-signature-invalid": "The seal is malformed, names a signer other than the reviewer, or its signature does not verify over the verdict.";
+    readonly "seal-unverifiable": "Nothing here can say whose seal it is: there is no signers file at base, or ssh-keygen is not installed.";
     readonly "kind-unreadable": "The record kind file is missing or could not be imported.";
     readonly "kind-invalid": "The record kind file exports no recordKind, or its shape is wrong.";
     readonly "schema-unreadable": "The schema file the record kind names is missing or is not JSON.";
     readonly "schema-id-mismatch": "The schema's $id differs from the id the record kind names.";
     readonly "schema-invalid": "The record schema itself does not compile.";
     readonly "location-missing": "The records directory does not exist, in the tree or at the revision.";
+    readonly "write-usage-invalid": "The command line lacks a value the write needs, or gives one it does not take.";
+    readonly "write-input-invalid": "The fields given with --from or --set can't be read, are not JSON, or are not a JSON object.";
+    readonly "record-not-found": "No record of the kind has the id given.";
+    readonly "record-id-taken": "The id given for a new record is already used, by a record or a file name.";
+    readonly "record-id-unallocatable": "No id was given and none can be allocated: the records share no single prefix and --prefix names none.";
+    readonly "record-path-unmatched": "The file name made from the record's id and title does not match the kind's location.";
+    readonly "record-closed": "The record is in a closed state, so nothing in it changes; a new record supersedes it instead.";
+    readonly "amend-id-immutable": "An amendment changes the record's id, and ids are never renumbered.";
+    readonly "amend-supersede-instead": "The record is approved, and the amendment changes a field the approval rule does not let change in place; a new record supersedes it instead.";
+    readonly "review-unsupported": "The kind's schema has no reviews field, so its records take no review.";
+    readonly "review-note-required": "A dissent was given with no note: a dissent needs a reason.";
+    readonly "review-sign-failed": "--sign was given and no seal could be made: the key can't be read or used, git names no ssh signing key, or ssh-keygen is not installed.";
+    readonly "since-rev-unknown": "--since names no commit.";
     readonly "intent-region-invalid": "The region's path, or its line range, does not exist in the tree read.";
     readonly "intent-history-shallow": "The repository is a shallow clone, so the region's history stops at the clone's boundary.";
     readonly "intent-plugin-failed": "A kind file's commitJoins, which joins commits to units, contracts and evidence, failed for a commit.";
@@ -67,17 +102,24 @@ export declare const REASONS: {
     readonly "intent-commit-bare": "A commit names no unit, no pull request and no decision covering the region at its time.";
     readonly "intent-pin-drifted": "A decision's pinned artifact no longer hashes to the pin.";
     readonly "intent-pin-missing": "A decision's pinned artifact does not exist in the tree read.";
+    readonly "intent-pin-stale": "A current decision pins an artifact at the hash a record it supersedes pinned, and the artifact has not changed since: the decision moved on and the artifact did not.";
     readonly "intent-artifact-unpinned": "An artifact decisions in the graph pinned, which no current decision pins.";
     readonly "intent-decision-superseded-live": "Every decision constraining the region is superseded.";
     readonly "intent-decision-provisional": "The current decisions constraining the region are all in states their kind does not close, such as decided.";
+    readonly "intent-decision-contested": "A current decision constraining the region has an open concern: a dissent neither addressed nor withdrawn.";
     readonly "intent-constraint-coarse": "The region is constrained only through its member, not by path.";
     readonly "intent-constraint-lost": "A decision's path constraint names a path that does not exist in the tree read.";
     readonly "intent-evidence-unpinned": "A decision's evidence has no hash: a URL, or a path with no sha256.";
     readonly "intent-trailer-unverified": "A commit carries a trailer a plugin says claims authorship, and the commit is not attested.";
     readonly "intent-region-unconstrained": "No decision constrains the region at any granularity.";
+    readonly "intent-decision-unimplemented": "A decided decision constrains the region, no work item that is not dropped implements it, and no commit falls in its window.";
+    readonly "intent-work-blocked": "A work item constraining the region has commits in its window while a work item it needs is not done.";
+    readonly "intent-work-open-decided-code": "Commits in the region are a decision's own work while the work item implementing that decision is still open.";
     readonly "composites-no-chant-member": "No member of kind chant was read, so nothing declares a composite instance or a component.";
     readonly "composites-none-declared": "The members read declare no composite instance.";
     readonly "composites-no-component": "The members read declare no component, so no composite instance has one.";
+    readonly "runtimes-config-unreadable": "The member's chant.config.ts could not be read, so only the built-in local runtime is listed.";
+    readonly "runtimes-lexicon-unreadable": "A lexicon the member's config lists could not be loaded, so it is not listed as a runtime.";
     readonly "lock-invalid": "The lineage lock can't be read.";
     readonly "manual-step-open": "A scope in the lineage lock has an open manual step.";
 };
@@ -88,11 +130,12 @@ export declare function isReasonCode(value: unknown): value is ReasonCode;
 /**
  * A finding code a plugin contributes to the intent graph through its
  * `commitJoins` (#2656): `plugin:<name>:<code>`, where `<name>` is the kind's
- * name and `<code>` is lower case words joined by dashes. These are outside the
+ * name, or the kind file's `commitJoinsName` when it has one (#2663), and
+ * `<code>` is lower case words joined by dashes. These are outside the
  * closed list: the plugin owns its namespace, and core only carries them.
  */
 export type PluginCode = `plugin:${string}:${string}`;
 export declare const PLUGIN_CODE: RegExp;
-/** Whether `value` is a plugin code, and, given `name`, one in that kind's namespace. */
+/** Whether `value` is a plugin code, and, given `name` (a kind's name or its `commitJoinsName`), one in that namespace. */
 export declare function isPluginCode(value: unknown, name?: string): value is PluginCode;
 //# sourceMappingURL=reason-codes.d.ts.map

package/dist/workspace/reason-codes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reason-codes.d.ts","sourceRoot":"","sources":["../../src/workspace/reason-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,sHAAsH;AACtH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,uHAAuH;AACvH,eAAO,MAAM,mBAAmB,WAAW,CAAC;AAE5C,qFAAqF;AACrF,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuEV,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,OAAO,CAAC;AAE9C,mDAAmD;AACnD,eAAO,MAAM,YAAY,EAA2B,UAAU,EAAE,CAAC;AAEjE,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE;AAED;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,UAAU,MAAM,IAAI,MAAM,EAAE,CAAC;AAEtD,eAAO,MAAM,WAAW,QAAkD,CAAC;AAE3E,yFAAyF;AACzF,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAI/E"}
+{"version":3,"file":"reason-codes.d.ts","sourceRoot":"","sources":["../../src/workspace/reason-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,sHAAsH;AACtH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,uHAAuH;AACvH,eAAO,MAAM,mBAAmB,WAAW,CAAC;AAE5C,qFAAqF;AACrF,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyHV,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,OAAO,CAAC;AAE9C,mDAAmD;AACnD,eAAO,MAAM,YAAY,EAA2B,UAAU,EAAE,CAAC;AAEjE,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE;AAED;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,UAAU,MAAM,IAAI,MAAM,EAAE,CAAC;AAEtD,eAAO,MAAM,WAAW,QAAkD,CAAC;AAE3E,2HAA2H;AAC3H,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAI/E"}

package/dist/workspace/record-sessions.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Review sessions (#2673, #2650 C10): a record kind whose records are the
+ * sessions a group reviewed records in. A session kind names, in its
+ * `session` declaration, the list of verdicts a session produced, the field
+ * that seals it once closed, and the kind file of the records its verdicts
+ * name (the subjects, such as decisions).
+ *
+ * On read, a closed session's seal has to match its text
+ * (`session-seal-mismatch`), and each verdict has to name a subject record
+ * that exists (`session-verdict-unknown-record`). Each session also lists the
+ * subjects' review entries that name it in their `session` field, as
+ * `citedBy`. This module only reads; nothing here writes a seal into a file.
+ */
+import { type RecordEntry, type RecordFormat, type RecordKind } from "./records.js";
+/** A subject record's review entry that names a session in its `session` field. */
+export interface SessionCitation {
+    /** The subject record's id. */
+    id: string;
+    /** The subject record's path, from the repository root. */
+    path: string;
+    /** The entry's position in the subject's reviews list, from 0. */
+    index: number;
+    /** The reviewer as the entry writes it, or null when it names none. */
+    reviewer: string | null;
+    /** The verdict as the entry writes it, or null when it names none. */
+    verdict: string | null;
+}
+/**
+ * The seal of a session record: {@link recordTextDigest} with the seal field
+ * in place of the reviews list. That is the lowercase hex SHA-256 of the
+ * file's text with LF line endings and without the front-matter line that
+ * holds the seal, a quoted string on one line. Every other byte, the `---`
+ * lines and the body included, is kept.
+ *
+ * `awk 'NR==1&&/^---$/{f=1;print;next} f&&/^---$/{f=0} f&&/^closed_digest:/{next} {print}' S-0001.md | shasum -a 256`
+ * gives the same value for a file with LF line endings that ends in one.
+ * For a session kind of format json (ws-053), the seal member is removed by
+ * the JSON rule of {@link recordTextDigest} instead.
+ */
+export declare function sessionSeal(text: string, field: string, format?: RecordFormat): string;
+/**
+ * Check each session in `entries` against its seal and the subject records,
+ * and fill in `citedBy`. `texts` holds each entry's file text by path.
+ * `subjects` holds the subject records and the name of their reviews list;
+ * it is null when they were not read, and then no verdict is checked.
+ */
+export declare function joinSessions(kind: RecordKind, entries: RecordEntry[], texts: Map<string, string>, subjects: {
+    records: RecordEntry[];
+    reviews: string;
+} | null): void;
+//# sourceMappingURL=record-sessions.d.ts.map

package/dist/workspace/record-sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-sessions.d.ts","sourceRoot":"","sources":["../../src/workspace/record-sessions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAoB,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAEnG,mFAAmF;AACnF,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,sEAAsE;IACtE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,YAAsC,GAAG,MAAM,CAE/G;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE;IAAE,OAAO,EAAE,WAAW,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,IAAI,CAoDrK"}

package/dist/workspace/record-source.d.ts

@@ -10,6 +10,8 @@ export interface RecordSource {
     list(dir: string): string[] | undefined;
     /** The text of a file listed by `list`. */
     read(path: string): string;
+    /** The bytes of a file listed by `list`, for a content-addressed id (ws-053). */
+    bytes(path: string): Uint8Array;
 }
 /** Records in the working tree under `root`. */
 export declare function workingTreeSource(root: string): RecordSource;

package/dist/workspace/record-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"record-source.d.ts","sourceRoot":"","sources":["../../src/workspace/record-source.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,MAAM,WAAW,YAAY;IAC3B,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd,kHAAkH;IAClH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;IACxC,2CAA2C;IAC3C,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CAC5B;AAED,gDAAgD;AAChD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAgB5D;AAYD,6EAA6E;AAC7E,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMvD;AAED,kEAAkE;AAClE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAOjE;AAED,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,YAAY,CA+C5E"}
+{"version":3,"file":"record-source.d.ts","sourceRoot":"","sources":["../../src/workspace/record-source.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,MAAM,WAAW,YAAY;IAC3B,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd,kHAAkH;IAClH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;IACxC,2CAA2C;IAC3C,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,iFAAiF;IACjF,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC;CACjC;AAED,gDAAgD;AAChD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAmB5D;AAYD,6EAA6E;AAC7E,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMvD;AAED,kEAAkE;AAClE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAOjE;AAED,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,YAAY,CAmD5E"}

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

@@ -8,11 +8,19 @@
  * the exit code is 0 whenever the read itself worked. Only a kind, schema or
  * revision that cannot be read exits 1.
  *
- * It needs no `chant.workspace.json`. The kind is passed explicitly, so
- * nothing is inferred (#2525 rule 1).
+ * It needs no `chant.workspace.json`. The kind is passed explicitly, or,
+ * without `--kind`, it is every record kind the declaration names (#2680), so
+ * nothing is inferred (#2525 rule 1). Several kinds print one document per
+ * kind, in the declaration's order, inside one set.
+ *
+ * With `--since <rev>` it prints what changed between two revisions instead,
+ * through `records-since.ts` (#2673).
  */
 import type { CommandContext } from "../cli/registry.js";
-import { type LoadedRecordKind, type ReadErrorCode, type ReadRecordsResult, type RecordEntry } from "./records.js";
+import { type RecordKindDeclaration } from "./declaration.js";
+import { type LoadedRecordKind, type Quorum, type ReadErrorCode, type ReadRecordsResult, type RecordEntry, type RecordFormat } from "./records.js";
+import { type WorkspaceTree } from "./tree.js";
+import type { DecisionWork } from "./work.js";
 import { type ProvenanceLevel } from "./trust/attestor.js";
 import { type BaseSource, type RecordProvenance } from "./trust/provenance.js";
 /** The version of the `records` output this chant writes. */
@@ -29,11 +37,23 @@ export interface RecordsQuery {
     base?: string;
     /** Where `kind` is resolved from and the repository is found. */
     cwd: string;
+    /**
+     * For a work kind: walk the region of each done item's `source` and raise
+     * `work-done-gap-open` when its finding still fires (#2686). On unless
+     * false; the intent graph passes false, since it raises the warning itself.
+     */
+    workGaps?: boolean;
 }
-/** A record as the output carries it: the entry plus its provenance (#2547). */
+/**
+ * A record as the output carries it: the entry plus its provenance (#2547),
+ * and its quorum when the kind has a reviews list (#2671).
+ */
 export type RecordView = RecordEntry & {
     provenance: RecordProvenance;
+    quorum?: Quorum | null;
 };
+/** The role in the trust policy whose holders' verdicts the quorum does not count (#2671). */
+export declare const AGENT_ROLE = "agent";
 /** Where provenance was judged from (#2547). */
 export interface TrustView {
     /** The full commit id the policy was read at, or null when there is no base. */
@@ -52,6 +72,7 @@ export type RecordsDocument = {
         name: string;
         schema: string;
         file: string;
+        format: RecordFormat;
     };
     at: string | null;
     /** The directory pinned paths resolve in, from the repository root: the workspace holding the kind file, or the repository root (#2549). */
@@ -65,6 +86,8 @@ export type RecordsDocument = {
         invalid: number;
         superseded: number;
     };
+    /** For a work kind (#2683): each decision its decision kind reads, with the work records implementing it. */
+    decisions?: DecisionWork[];
 } | {
     $schema: string;
     contract: number;
@@ -73,6 +96,41 @@ export type RecordsDocument = {
         message: string;
     };
 };
+/** Where a document in a {@link RecordsSetDocument} comes from: the declaration's entry for its kind (#2680). */
+export interface DeclaredKindView {
+    /** The member that declares the kind, or null for the workspace's own. */
+    member: string | null;
+    /** The kind file from the workspace root. */
+    path: string;
+    /** The name the declaration gives the kind, or null. */
+    name: string | null;
+}
+/**
+ * The `records` output without `--kind` when the declaration names record
+ * kinds (#2680): one {@link RecordsDocument} per kind, in the declaration's
+ * order, each with the entry that declares it.
+ */
+export interface RecordsSetDocument {
+    $schema: string;
+    contract: number;
+    kinds: (RecordsDocument & {
+        declared: DeclaredKindView;
+    })[];
+}
+/**
+ * The record kinds the declaration nearest above `cwd` names, in the tree
+ * `at` reads, with each kind file on disk. Empty when there is no declaration.
+ * Throws a {@link WorkspaceReadError} for one that can't be read.
+ */
+export declare function declaredKindFiles(cwd: string, at?: string): {
+    declared: RecordKindDeclaration;
+    file: string;
+}[];
+/** Read every declared kind in `kinds`, as {@link queryRecords} reads one. */
+export declare function queryDeclaredRecords(kinds: {
+    declared: RecordKindDeclaration;
+    file: string;
+}[], query: Omit<RecordsQuery, "kind">): Promise<RecordsSetDocument>;
 /** A records read, before provenance. */
 export interface RecordsRead {
     loaded: LoadedRecordKind;
@@ -83,8 +141,16 @@ export interface RecordsRead {
     at: string | null;
     /** Where pinned paths resolve, relative to `root` ("." for the root itself). */
     workspaceRoot: string;
+    /** The workspace root's tree, as read: the working tree, or the revision under `--at`. */
+    tree: WorkspaceTree;
     result: ReadRecordsResult;
 }
+/**
+ * Where a kind's pinned paths resolve: the workspace whose declaration sits
+ * nearest above the kind file, when it is inside the repository, or else the
+ * repository root. Relative to `root`, with / separators.
+ */
+export declare function pinRoot(kindFile: string, root: string): string;
 /**
  * Load the kind and read its records, in the working tree or at `query.at`,
  * with each pin checked in the same tree. Throws a {@link RecordReadError}.
@@ -105,6 +171,7 @@ export declare function pinFile(file: string, cwd: string): {
     error: string;
 };
 export declare function runWorkspaceRecords(ctx: CommandContext): Promise<number>;
+export declare function realpathOr(dir: string): string;
 /** Records whose provenance falls below `required`. Only `attested` can be required. */
 export declare function belowRequired(records: RecordView[], required: ProvenanceLevel): RecordView[];
 /** `chant workspace <anything else>`. */

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

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

package/dist/workspace/records-since.d.ts

@@ -0,0 +1,90 @@
+/**
+ * `chant workspace records --kind <kind file> --since <rev> [--at <rev>]
+ * [--json]` (#2673, #2650 C11): what changed in a kind's records between two
+ * revisions. It reads the records at `<rev>` and at `--at` (the working tree
+ * without it), through the same reader as `records`, and lists new and
+ * removed records, state transitions, new verdicts, new supersessions and
+ * changed pins. Between a review session's open and close commits, that is
+ * what the session did.
+ *
+ * Records are matched by id. A record whose id could not be read is left
+ * out of the comparison, since nothing says which record it was before.
+ */
+import { type RecordEntry, type RecordKind } from "./records.js";
+/** `$id` of the JSON Schema for `records --since --json`, shipped beside this file. */
+export declare const RECORDS_SINCE_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/records-since/v1/records-since.schema.json";
+/** Why a `--since` read failed: any records read error, or a `--since` that names no commit. Closed. */
+export declare const RECORDS_SINCE_ERROR_CODES: readonly ["kind-unreadable", "kind-invalid", "schema-unreadable", "schema-id-mismatch", "schema-invalid", "location-missing", "not-a-git-repository", "revision-unknown", "since-rev-unknown"];
+export type RecordsSinceErrorCode = (typeof RECORDS_SINCE_ERROR_CODES)[number];
+/** The kinds of change, in the order the output lists them. */
+export declare const SINCE_CHANGE_KINDS: readonly ["new", "removed", "state", "verdict", "supersession", "pin"];
+export type SinceChangeKind = (typeof SINCE_CHANGE_KINDS)[number];
+export type SinceChange = {
+    change: "new";
+    id: string;
+    path: string;
+    state: string | null;
+} | {
+    change: "removed";
+    id: string;
+    path: string;
+    state: string | null;
+} | {
+    change: "state";
+    id: string;
+    from: string | null;
+    to: string | null;
+} | {
+    change: "verdict";
+    id: string;
+    principal: string | null;
+    verdict: string | null;
+    index: number;
+    record?: string;
+    session?: string;
+} | {
+    change: "supersession";
+    id: string;
+    supersedes: string;
+} | {
+    change: "pin";
+    id: string;
+    path: string;
+    from: string | null;
+    to: string | null;
+};
+export type RecordsSinceDocument = {
+    $schema: string;
+    contract: number;
+    kind: {
+        name: string;
+        schema: string;
+        file: string;
+    };
+    since: string;
+    at: string | null;
+    changes: SinceChange[];
+    summary: Record<SinceChangeKind, number>;
+} | {
+    $schema: string;
+    contract: number;
+    error: {
+        code: RecordsSinceErrorCode;
+        message: string;
+    };
+};
+export interface RecordsSinceQuery {
+    kind: string;
+    since: string;
+    at?: string;
+    cwd: string;
+}
+/** Run the comparison and build the document `--json` prints. Never throws a read error. */
+export declare function queryRecordsSince(query: RecordsSinceQuery): Promise<RecordsSinceDocument>;
+/** What changed from `before` to `after`, in the order of {@link SINCE_CHANGE_KINDS} and then by id. */
+export declare function compareRecords(kind: RecordKind, before: RecordEntry[], after: RecordEntry[]): SinceChange[];
+/** The text form: one line per change and a summary. */
+export declare function formatSince(doc: Extract<RecordsSinceDocument, {
+    changes: SinceChange[];
+}>): string;
+//# sourceMappingURL=records-since.d.ts.map

package/dist/workspace/records-since.d.ts.map

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

package/dist/workspace/records-write.d.ts

@@ -0,0 +1,171 @@
+/**
+ * `chant workspace records new|amend|review` (#2670): the commands a UI
+ * writes records through, so it never parses or writes a record file itself
+ * (ws-052).
+ *
+ * Each command loads the kind, reads every record it locates, builds the one
+ * file it would write, and reads the records again with that file in place,
+ * through the same {@link readRecords} a read uses. The write goes ahead only
+ * when the written record comes back valid and no other record gains a
+ * reason. So a write is refused for exactly what a later read would report,
+ * plus the rules only a write has: ids are allocated and never reused, a
+ * closed record never changes, an approved one changes only in place of
+ * what the approval rule allows, and a dissent needs a note.
+ *
+ * Every command writes one file or none, never commits, and prints one JSON
+ * document with a closed error code on refusal. `--dry-run` prints the
+ * document and the text it would write, and writes nothing.
+ */
+import type { CommandContext } from "../cli/registry.js";
+import { type RecordEntry, type RecordWarning } from "./records.js";
+/** The version of the write documents this chant prints. */
+export declare const RECORDS_WRITE_CONTRACT_VERSION = 1;
+export declare const RECORDS_NEW_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/records-new/v1/records-new.schema.json";
+export declare const RECORDS_AMEND_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/records-amend/v1/records-amend.schema.json";
+export declare const RECORDS_REVIEW_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/records-review/v1/records-review.schema.json";
+/** Why `records new` wrote nothing. Closed: a reader may switch on it. */
+export declare const NEW_ERROR_CODES: readonly ["kind-unreadable", "kind-invalid", "schema-unreadable", "schema-id-mismatch", "schema-invalid", "location-missing", "write-usage-invalid", "write-input-invalid", "record-id-taken", "record-id-unallocatable", "record-path-unmatched", "record-unparseable", "record-schema-invalid", "record-id-duplicate", "record-supersedes-unknown", "record-supersedes-conflict", "session-seal-mismatch", "session-verdict-unknown-record"];
+/** Why `records amend` wrote nothing. */
+export declare const AMEND_ERROR_CODES: readonly ["kind-unreadable", "kind-invalid", "schema-unreadable", "schema-id-mismatch", "schema-invalid", "location-missing", "write-usage-invalid", "write-input-invalid", "record-not-found", "amend-id-immutable", "record-closed", "amend-supersede-instead", "record-unparseable", "record-schema-invalid", "record-id-duplicate", "record-supersedes-unknown", "record-supersedes-conflict", "session-seal-mismatch", "session-verdict-unknown-record"];
+/** Why `records review` wrote nothing. */
+export declare const REVIEW_ERROR_CODES: readonly ["kind-unreadable", "kind-invalid", "schema-unreadable", "schema-id-mismatch", "schema-invalid", "location-missing", "write-usage-invalid", "record-not-found", "review-unsupported", "record-closed", "review-note-required", "review-sign-failed", "record-unparseable", "record-schema-invalid", "record-id-duplicate", "record-supersedes-unknown", "record-supersedes-conflict", "session-seal-mismatch", "session-verdict-unknown-record"];
+export type NewErrorCode = (typeof NEW_ERROR_CODES)[number];
+export type AmendErrorCode = (typeof AMEND_ERROR_CODES)[number];
+export type ReviewErrorCode = (typeof REVIEW_ERROR_CODES)[number];
+export declare const VERDICTS: readonly ["agree", "dissent", "abstain"];
+export type Verdict = (typeof VERDICTS)[number];
+interface KindView {
+    name: string;
+    schema: string;
+    file: string;
+}
+/** What every write result carries. */
+interface WriteResult {
+    $schema: string;
+    contract: number;
+    kind: KindView;
+    /** The record file, from the repository root (the working directory outside git), with / separators. */
+    path: string;
+    id: string;
+    /** True when nothing was written. */
+    dryRun: boolean;
+    /** The written record's warnings, as `records` would report them. */
+    warnings: RecordWarning[];
+    /** With --dry-run, the whole text the command would write. */
+    text?: string;
+}
+interface WriteFailure<C> {
+    $schema: string;
+    contract: number;
+    error: {
+        code: C;
+        message: string;
+    };
+}
+export type NewDocument = WriteResult | WriteFailure<NewErrorCode>;
+export type AmendDocument = (WriteResult & {
+    changed: string[];
+}) | WriteFailure<AmendErrorCode>;
+export type ReviewDocument = (WriteResult & {
+    review: Record<string, unknown>;
+}) | WriteFailure<ReviewErrorCode>;
+/**
+ * YAML limited to what JSON can say, laid out as the decision README writes a
+ * record: every string double-quoted with JSON escapes, block mappings and
+ * sequences, and `[]` or `{}` for an empty one. `parseFrontMatter` reads it
+ * back to the same value.
+ */
+export declare function toYaml(value: unknown, indent?: number): string;
+/** A record file: the front matter, then `body` as it is. */
+export declare function renderRecord(data: Record<string, unknown>, body: string): string;
+/**
+ * `text` with the top-level fields in `set` replaced in place, and every
+ * other byte kept. A field's block is its key line at column 0 and the lines
+ * after it, up to the closing `---`, that start with a space, a tab, `#` or
+ * `-`: the block {@link recordTextDigest} cuts for the reviews field. Blank
+ * lines ending a block stay where they are. A field the front matter lacks is
+ * added before the closing `---`. Line endings become LF. Returns undefined
+ * when the text has no front matter, or when the result does not read back
+ * as `expected`, so a caller never writes a file it did not mean to.
+ */
+export declare function replaceFields(text: string, set: Record<string, unknown>, expected: Record<string, unknown>): string | undefined;
+/** A file-name slug from a title, as `scripts/import-decisions.mjs` makes one. */
+export declare function slug(title: string): string;
+/**
+ * The next id: `<prefix>-<n>`, one above the highest number any record in the
+ * directory has with that prefix, padded to at least three digits, or to the
+ * widest number those records use. Ids come from the records' own id field
+ * and, for a file that can't be read, from its name, so an id in use is never
+ * handed out again. The shape is derived from the records, with the prefix's
+ * case kept: a work kind's `W-001` and `W-002` give `W-003` (#2683), and a
+ * decision's `ws-052` gives `ws-053`. The kind's schema still judges the id
+ * written. Without `prefix`, every record must share one prefix.
+ */
+export declare function allocateId(entries: RecordEntry[], prefix: string | undefined, kind: string): string;
+export interface NewRecordOptions {
+    /** The kind file, resolved against `cwd`. */
+    kind: string;
+    /** The record's fields, as JSON text. */
+    fields: string;
+    /** The id prefix to allocate under, when the fields hold no id. */
+    prefix?: string;
+    dryRun?: boolean;
+    cwd: string;
+}
+/** `records new`: write one new record from validated fields. */
+export declare function newRecord(opts: NewRecordOptions): Promise<NewDocument>;
+export interface AmendRecordOptions {
+    kind: string;
+    id: string;
+    /** The fields to set, as JSON text. Each replaces the whole top-level field. */
+    fields: string;
+    dryRun?: boolean;
+    cwd: string;
+}
+/**
+ * `records amend`: set top-level fields of one record. A record in a closed
+ * state never changes. With approval ranks, a record ranked above 0 (such as
+ * a decided decision) changes in place only in its state, to one ranked at
+ * least as high, its pins field and its reviews: anything else is a new
+ * decision, written as a record that supersedes it (#2524 D4).
+ */
+export declare function amendRecord(opts: AmendRecordOptions): Promise<AmendDocument>;
+export interface ReviewRecordOptions {
+    kind: string;
+    id: string;
+    verdict: string;
+    /** The reviewer, as the caller names them. chant does not check who it is; a seal does, on read (#2687). */
+    by: string;
+    note?: string;
+    /** The review session the verdict was given in. */
+    session?: string;
+    dryRun?: boolean;
+    cwd: string;
+    /** The date written as `on`, YYYY-MM-DD. Defaults to today, in UTC. */
+    on?: string;
+    /**
+     * Seal the verdict (#2687): a key file, resolved against `cwd`, or true for
+     * git's `user.signingkey`. Without it the verdict is written unsealed.
+     */
+    sign?: string | true;
+}
+/**
+ * `records review`: append one verdict to a record's reviews, with the date
+ * and the digest of the record text it judged ({@link recordTextDigest}).
+ * With `sign`, the verdict carries a seal: an ssh signature over the record
+ * id, the digest, the verdict, the reviewer and the date (`trust/seal.ts`).
+ */
+export declare function reviewRecord(opts: ReviewRecordOptions): Promise<ReviewDocument>;
+export declare const WRITE_USAGE: string;
+/**
+ * The kind file a write names: `arg` itself when it is a file, or else the
+ * declared record kind it names (#2683), by the name the declaration gives it
+ * or its file's name without `.kind.mjs`, so `records new work` finds
+ * `work/work.kind.mjs`. Anything else is returned as given, and loading it
+ * fails with kind-unreadable.
+ */
+export declare function resolveWriteKind(arg: string, cwd: string): string;
+/** `chant workspace records new|amend|review`. Prints one JSON document; exits 0 when it wrote, or would have with --dry-run. */
+export declare function runRecordsWrite(ctx: CommandContext): Promise<number>;
+export {};
+//# sourceMappingURL=records-write.d.ts.map

package/dist/workspace/records-write.d.ts.map

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