@intentius/chant 0.86.0 → 0.88.0

package/src/workspace/records.schema.json

@@ -138,12 +138,12 @@
           "items": { "$ref": "#/$defs/asset" }
         },
         "warnings": {
-          "description": "Added in contract 1 by #2549. Findings that leave the record valid: a pinned file that changed, went missing or did not follow a superseding decision, a supersedes link that has no effect yet, (added by #2654) an evidence list that is empty, (added by #2672) a verdict that names no digest, or (added by #2683) a work record's links and dates. A work record never carries record-no-evidence; a done one with no evidence carries work-done-unpinned. valid and --current do not look at them.",
+          "description": "Added in contract 1 by #2549. Findings that leave the record valid: a pinned file that changed, went missing or did not follow a superseding decision, a supersedes link that has no effect yet, (added by #2654) an evidence list that is empty, (added by #2672) a verdict that names no digest, or (added by #2683) a work record's links and dates, or (added by #2688) a record whose author seal is not attested under a signers file at base. A work record never carries record-no-evidence; a done one with no evidence carries work-done-unpinned. valid and --current do not look at them.",
           "type": "array",
           "items": { "$ref": "#/$defs/warning" }
         },
         "digest": {
-          "description": "Added in contract 1 by #2672. The lowercase hex SHA-256 of the record file's text, with LF line endings and without the kind's reviews block in the front matter, or for a kind of format json without the top-level reviews member and one comma beside it (#2664). A review verdict names it in its digest field, and stops counting once the record's digest moves on. For a kind with no reviews list, the digest of the whole text.",
+          "description": "Added in contract 1 by #2672. The lowercase hex SHA-256 of the record file's text, with LF line endings and without the kind's reviews block and its top-level seal block (#2688) in the front matter, or for a kind of format json without the top-level reviews and seal members, each with one comma beside it (#2664). A record with no seal hashes as it did before #2688. A review verdict names it in its digest field, and stops counting once the record's digest moves on; a record's author seal signs it. For a kind with no reviews list, the digest of the whole text.",
           "type": "string",
           "pattern": "^[0-9a-f]{64}$"
         },
@@ -151,6 +151,14 @@
           "description": "Added in contract 1 by #2671, on every record of a kind with a reviews list. Null when the front matter could not be parsed.",
           "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/quorum" }]
         },
+        "attested": {
+          "description": "Added in contract 1 by #2688, on every parsed record of a kind with a reviews list. true when the record's author seal (its top-level seal field) verifies, against the signers file at base, for the author the kind's reviews.decider field names (decided_by for decisions). false when a signers file is active at base and the record names an author and carries no seal, or when a seal fails. null when nothing here can say: no seal and no signers file, a seal checked with no signers file, no ssh-keygen, or a record that names no author and carries no seal. Independent of provenance, which judges the commit that last changed the file.",
+          "type": ["boolean", "null"]
+        },
+        "attestation": {
+          "description": "Added in contract 1 by #2688, beside attested. What the record's author seal establishes, and why when it is not attested. Under an active signers file, a record that names an author and is not attested also carries the warning record-unattested; it is still read and still valid.",
+          "$ref": "#/$defs/attestation"
+        },
         "citedBy": {
           "description": "Added in contract 1 by #2673, on every record of a session kind and on no other. The review entries of the records the session kind names as its subjects (decisions, for the reference session kind) whose session field names this record's id, in path order and then list order.",
           "type": "array",
@@ -206,7 +214,9 @@
             "work-needs-cycle",
             "work-implements-undecided",
             "work-done-unpinned",
-            "work-closed-without-date"
+            "work-closed-without-date",
+            "work-done-gap-open",
+            "record-unattested"
           ]
         },
         "message": { "type": "string" }
@@ -248,6 +258,20 @@
         "reviewer": { "type": "string", "description": "The reviewer as the record writes it." },
         "verdict": { "enum": ["agree", "dissent", "abstain"] },
         "digest": { "type": ["string", "null"], "description": "The digest the verdict names, or null when it names none (a warning review-undigested on the record)." },
+        "attested": {
+          "type": ["boolean", "null"],
+          "description": "Added in contract 1 by #2687. true when the verdict's seal verifies for its reviewer against the signers file at base. false when a signers file is active at base and the verdict has no seal, or when a seal fails, with or without one. null when nothing here can say: no seal and no signers file, a seal checked with no signers file (its signature is intact, and nothing says whose key it is), or no ssh-keygen. Under an active signers file only true counts."
+        },
+        "attestation": {
+          "description": "Added in contract 1 by #2687. What the verdict's seal establishes, and why when it is not attested.",
+          "type": "object",
+          "required": ["message"],
+          "properties": {
+            "code": { "enum": ["seal-missing", "seal-signer-unlisted", "seal-signature-invalid", "seal-unverifiable"], "description": "Absent exactly when attested is true." },
+            "message": { "type": "string" },
+            "key": { "type": "string", "description": "The fingerprint of the key that made the signature, when the signature was checked." }
+          }
+        },
         "reason": {
           "description": "Why the verdict does not count. Present exactly on the entries in notCounted.",
           "type": "object",
@@ -259,6 +283,16 @@
         }
       }
     },
+    "attestation": {
+      "description": "Added in contract 1 by #2688. What a record's author seal establishes, and why when it is not attested: the same shape as a verdict's attestation (#2687), which is kept inline in verdict.",
+      "type": "object",
+      "required": ["message"],
+      "properties": {
+        "code": { "enum": ["seal-missing", "seal-signer-unlisted", "seal-signature-invalid", "seal-unverifiable"], "description": "Absent exactly when attested is true." },
+        "message": { "type": "string" },
+        "key": { "type": "string", "description": "The fingerprint of the key that made the signature, when the signature was checked." }
+      }
+    },
     "concern": {
       "type": "object",
       "required": ["index", "principal", "reviewer", "note"],

package/src/workspace/records.ts

@@ -100,14 +100,76 @@ export const REVIEW_REASON_CODES = [
   "review-duplicate",
   /** The verdict's digest is not the digest of the record's text now: the record changed after the verdict (#2672). */
   "review-older-digest",
-  /** An attestation policy is active at base, and the verdict carries no seal. */
+  /**
+   * An attestation policy is active at base, and the verdict's seal does not
+   * verify for its reviewer: it has none, the reviewer has no key in the
+   * signers file, or the signature fails (#2687).
+   */
   "review-unattested",
 ] as const satisfies readonly ReasonCode[];
 export type ReviewReasonCode = (typeof REVIEW_REASON_CODES)[number];
 
+/**
+ * Why a seal is not attested: a verdict's (#2687), or a record's author seal
+ * (#2688). Closed, like the reason codes. Every verdict in the quorum, and
+ * every parsed record of a kind with a reviews list, carries one of these in
+ * its `attestation`, unless its seal verified.
+ */
+export const SEAL_REASON_CODES = [
+  /** The verdict or record carries no seal. */
+  "seal-missing",
+  /** The reviewer or author has no key in the signers file at base. */
+  "seal-signer-unlisted",
+  /** The seal is malformed, names another signer, or its signature does not verify over the verdict or record. */
+  "seal-signature-invalid",
+  /** Nothing here can say whose seal it is: there is no signers file at base, or ssh-keygen is not installed. */
+  "seal-unverifiable",
+] as const satisfies readonly ReasonCode[];
+export type SealCode = (typeof SEAL_REASON_CODES)[number];
+
+/**
+ * A warning about a record's own seal (#2688), raised by `records` with the
+ * policy at base, never by a write. Closed, like the reason codes.
+ */
+export const SEAL_WARNING_CODES = [
+  /**
+   * A signers file is active at base, the record names its author (the
+   * kind's `reviews.decider` field), and its seal does not verify for that
+   * author: it has none, the author has no key in the file, or the signature
+   * fails. The record is still read, and still valid.
+   */
+  "record-unattested",
+] as const satisfies readonly ReasonCode[];
+export type SealWarningCode = (typeof SEAL_WARNING_CODES)[number];
+
+/**
+ * The top-level field that holds a record's author seal (#2688), on a kind
+ * with a reviews list. Like the reviews block, the record's digest leaves it
+ * out, so sealing a record never moves its digest.
+ */
+export const RECORD_SEAL_FIELD = "seal";
+
+/**
+ * The top-level fields {@link recordTextDigest} leaves out for a kind: its
+ * reviews list and {@link RECORD_SEAL_FIELD} when it has a reviews list, and
+ * nothing when it has none (#2672, #2688).
+ */
+export function digestFields(kind: Pick<RecordKind, "reviews">): string[] | null {
+  return kind.reviews ? [kind.reviews.field, RECORD_SEAL_FIELD] : null;
+}
+
+/** What a verdict's seal establishes (#2687). See `trust/seal.ts`. */
+export interface VerdictAttestation {
+  /** Why the verdict is not attested. Absent when its seal verified. */
+  code?: SealCode;
+  message: string;
+  /** The fingerprint of the key that made the signature, when it was checked. */
+  key?: string;
+}
+
 export interface RecordWarning {
-  /** A work kind's records also carry the codes of `WORK_WARNING_CODES` (#2683). */
-  code: RecordWarningCode | WorkWarningCode;
+  /** A work kind's records also carry the codes of `WORK_WARNING_CODES` (#2683), and `records` adds `SEAL_WARNING_CODES` (#2688). */
+  code: RecordWarningCode | WorkWarningCode | SealWarningCode;
   message: string;
 }
 
@@ -244,12 +306,21 @@ export const recordKindSchema = z
      * (relative to this kind file's directory). The entries of that kind's
      * reviews list (its `reviews.field`, or `reviews`) name a session in
      * `session`. Optional.
+     *
+     * `openedRev`, `closedRev` and `closedOn` (#2693) name the fields that
+     * hold the commit a session opened at, the commit it closed at, and when
+     * it closed. `records new` writes the first, `records close` the other
+     * two, and `records --since <session id>` reads the revisions. Each is
+     * optional: without it, nothing writes that field.
      */
     session: z
       .object({
         verdicts: z.string().min(1),
         seal: z.string().min(1),
         subjects: z.object({ kind: z.string().min(1) }).strict(),
+        openedRev: z.string().min(1).optional(),
+        closedRev: z.string().min(1).optional(),
+        closedOn: z.string().min(1).optional(),
       })
       .strict()
       .optional(),
@@ -554,34 +625,43 @@ function nonJson(v: unknown, at: string, seen: Set<object>): string | undefined
  * to the file changes it, so a verdict given before an amendment stops
  * counting.
  *
+ * `field` names the top-level fields left out: one name, or a list. For a
+ * kind with a reviews list the list is the reviews field and `seal`, the
+ * record's author seal (#2688; {@link digestFields}), so sealing a record
+ * leaves its digest where it was too. A record with no `seal` hashes exactly
+ * as it did before author seals existed.
+ *
  * The rule, which a hand-editor can follow with a text editor and
  * `sha256sum`:
  *
  * 1. Line endings become LF (CRLF and a lone CR each become one LF).
  * 2. When the text starts with a `---` line and a later line is exactly
- *    `---`, the lines between them are the front matter. In it, the line
- *    that starts, at column 0, with the key `field` (bare, or in single or
+ *    `---`, the lines between them are the front matter. In it, each line
+ *    that starts, at column 0, with one of the keys (bare, or in single or
  *    double quotes), optional spaces or tabs and a `:`, is removed, and so
  *    is every line after it, up to the closing `---`, that is empty or
  *    starts with a space, a tab, `#` or `-`. Removal stops at the first
  *    other line. Everything else, the `---` lines and the body included, is
- *    kept byte for byte.
+ *    kept byte for byte. Which key is removed first makes no difference.
  * 3. The digest is the SHA-256 of the result's UTF-8 bytes.
  *
- * Text with no front matter, or no such key, is hashed after step 1 alone.
- * A writer that adds a verdict must change only the reviews block: a
+ * Text with no front matter, or none of the keys, is hashed after step 1
+ * alone. A writer that adds a verdict must change only the reviews block: a
  * reformatted front matter is a new digest, and every earlier verdict stops
  * counting.
  */
-export function recordTextDigest(text: string, field: string | null = "reviews", format: RecordFormat = "markdown-front-matter"): string {
+export function recordTextDigest(text: string, field: string | readonly string[] | null = "reviews", format: RecordFormat = "markdown-front-matter"): string {
   const lf = text.replace(/\r\n?/g, "\n");
-  const kept = field === null ? lf : format === "json" ? withoutMember(lf, field) : withoutBlock(lf, field);
+  const fields = field === null ? [] : typeof field === "string" ? [field] : field;
+  const kept = format === "json" ? fields.reduce(withoutMember, lf) : withoutBlocks(lf, fields);
   return createHash("sha256").update(kept, "utf8").digest("hex");
 }
 
 /**
  * `text` with the top-level member `field` removed from a JSON record, by the
- * rule a hand-editor follows for a JSON record (ws-053):
+ * rule a hand-editor follows for a JSON record (ws-053). With several fields
+ * (the reviews member, then `seal`, #2688) the rule is applied to each in
+ * turn, to the text the previous one left:
  *
  * 1. Line endings become LF, as for Markdown.
  * 2. When the text is a JSON record (one object, no repeated member name) and
@@ -624,14 +704,15 @@ function withoutMember(text: string, field: string): string {
   return text.slice(0, start) + text.slice(end);
 }
 
-/** `text` with the top-level `field` block removed from its front matter, by the rule {@link recordTextDigest} states. */
-function withoutBlock(text: string, field: string): string {
+/** `text` with the top-level blocks of `fields` removed from its front matter, by the rule {@link recordTextDigest} states. */
+function withoutBlocks(text: string, fields: readonly string[]): string {
+  if (fields.length === 0) return text;
   const lines = text.split("\n");
   if (lines[0] !== "---") return text;
   const close = lines.indexOf("---", 1);
   if (close < 0) return text;
-  const key = field.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const starts = new RegExp(`^(?:${key}|"${key}"|'${key}')[ \\t]*:(?:[ \\t]|$)`);
+  const keys = fields.map((f) => f.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).map((k) => `${k}|"${k}"|'${k}'`);
+  const starts = new RegExp(`^(?:${keys.join("|")})[ \\t]*:(?:[ \\t]|$)`);
   const out: string[] = [];
   for (let i = 0; i < lines.length; i++) {
     if (i > 0 && i < close && starts.test(lines[i])) {
@@ -664,6 +745,13 @@ export interface QuorumVerdict {
   verdict: "agree" | "dissent" | "abstain";
   /** The digest the verdict names, or null when it names none. */
   digest: string | null;
+  /**
+   * true when its seal verifies for the reviewer against the signers at base;
+   * false when a seal is missing under an active policy, or fails; null when
+   * nothing here can say (#2687).
+   */
+  attested: boolean | null;
+  attestation: VerdictAttestation;
   /** Why it does not count. Absent on a counted verdict. */
   reason?: { code: ReviewReasonCode; message: string };
 }
@@ -703,6 +791,30 @@ export interface QuorumOptions {
   agents: ReadonlySet<string>;
   /** Whether an attestation policy is active, so a verdict needs a seal to count. */
   attestation: boolean;
+  /**
+   * Checks one verdict's seal (#2687), as `trust/seal.ts` does against the
+   * policy at base. Without it no seal is checked: a sealed verdict is
+   * `seal-unverifiable`, so under an active policy none counts.
+   */
+  verifySeal?: (v: SealInput) => { attested: boolean | null } & VerdictAttestation;
+}
+
+/** What a seal check reads of one verdict. */
+export interface SealInput {
+  record: string | null;
+  reviewer: string;
+  verdict: string;
+  on: unknown;
+  digest: string | null;
+  seal: unknown;
+}
+
+/** The check used when {@link QuorumOptions.verifySeal} is not given. */
+function uncheckedSeal(attestation: boolean, v: SealInput): { attested: boolean | null } & VerdictAttestation {
+  if (v.seal === undefined || v.seal === null) {
+    return { attested: attestation ? false : null, code: "seal-missing", message: `the verdict by ${v.reviewer} carries no seal` };
+  }
+  return { attested: null, code: "seal-unverifiable", message: `the seal by ${v.reviewer} was not checked` };
 }
 
 const VERDICTS = new Set(["agree", "dissent", "abstain"]);
@@ -713,28 +825,36 @@ const VERDICTS = new Set(["agree", "dissent", "abstain"]);
  * Malformed entries are skipped; the schema reports them.
  *
  * A verdict is not counted when its reviewer is the decider, holds the agent
- * role, names a digest other than the record's own now, or carries no seal
- * under an active attestation policy, in that order. Of the rest, the latest
- * verdict per principal counts and each earlier one is a duplicate. No
- * verdict carries a seal yet (#2546), so under an active policy none counts.
+ * role, names a digest other than the record's own now, or, under an active
+ * attestation policy, carries no seal that verifies for its reviewer (#2687),
+ * in that order. Of the rest, the latest verdict per principal counts and
+ * each earlier one is a duplicate. Every verdict reports its seal's check in
+ * `attested` and `attestation`, whether it counts or not.
  */
-export function computeQuorum(kind: RecordKind, entry: Pick<RecordEntry, "data" | "digest">, options: QuorumOptions): Quorum | null {
+export function computeQuorum(kind: RecordKind, entry: Pick<RecordEntry, "data" | "digest"> & { id?: string | null }, options: QuorumOptions): Quorum | null {
   if (!kind.reviews || entry.data === null) return null;
   const list = entry.data[kind.reviews.field];
   const decidedBy = entry.data[kind.reviews.decider];
   const decider = typeof decidedBy === "string" ? normalisePrincipal(decidedBy) : null;
+  const idValue = entry.id !== undefined ? entry.id : kind.idField !== undefined ? entry.data[kind.idField] : null;
+  const record = typeof idValue === "string" ? idValue : null;
   const verdicts: QuorumVerdict[] = [];
   const openConcerns: OpenConcern[] = [];
   (Array.isArray(list) ? list : []).forEach((raw, index) => {
     if (raw === null || typeof raw !== "object") return;
     const r = raw as Record<string, unknown>;
     if (typeof r.reviewer !== "string" || typeof r.verdict !== "string" || !VERDICTS.has(r.verdict)) return;
+    const digest = typeof r.digest === "string" ? r.digest : null;
+    const input: SealInput = { record, reviewer: r.reviewer, verdict: r.verdict, on: r.on, digest, seal: r.seal };
+    const { attested, ...attestation } = options.verifySeal ? options.verifySeal(input) : uncheckedSeal(options.attestation, input);
     const v: QuorumVerdict = {
       index,
       principal: normalisePrincipal(r.reviewer),
       reviewer: r.reviewer,
       verdict: r.verdict as QuorumVerdict["verdict"],
-      digest: typeof r.digest === "string" ? r.digest : null,
+      digest,
+      attested,
+      attestation,
     };
     if (v.principal === decider) {
       v.reason = { code: "review-decider", message: `${v.reviewer} decided this record, and the quorum counts verdicts besides the decider's` };
@@ -742,8 +862,8 @@ export function computeQuorum(kind: RecordKind, entry: Pick<RecordEntry, "data"
       v.reason = { code: "review-agent", message: `${v.reviewer} holds the agent role in the trust policy at base, and an agent's verdict does not count` };
     } else if (v.digest !== null && v.digest !== entry.digest) {
       v.reason = { code: "review-older-digest", message: `${v.reviewer} judged the text at digest ${v.digest.slice(0, 12)}, and the record's text is now at ${entry.digest.slice(0, 12)}` };
-    } else if (options.attestation) {
-      v.reason = { code: "review-unattested", message: `an attestation policy is active at base, and the verdict by ${v.reviewer} carries no seal` };
+    } else if (options.attestation && attested !== true) {
+      v.reason = { code: "review-unattested", message: `an attestation policy is active at base, and ${attestation.message}` };
     }
     verdicts.push(v);
     if (v.verdict === "dissent" && r.addressed_by == null && r.withdrawn_on == null) {
@@ -807,7 +927,7 @@ export interface RecordEntry {
   assets: AssetPin[];
   /** Findings that leave the record valid, such as a pinned file that changed (#2549). */
   warnings: RecordWarning[];
-  /** {@link recordTextDigest} of the file's text, without the kind's reviews list when it has one (#2672). */
+  /** {@link recordTextDigest} of the file's text, without the kind's reviews list and author seal when it has a reviews list (#2672, #2688). */
   digest: string;
   /** For a session kind only: the subject records' review entries that name this session (#2673). */
   citedBy?: SessionCitation[];
@@ -972,7 +1092,7 @@ export async function readRecords(loaded: LoadedRecordKind, options: ReadRecords
       data: null,
       assets: [],
       warnings: [],
-      digest: recordTextDigest(text, kind.reviews?.field ?? null, kind.format),
+      digest: recordTextDigest(text, digestFields(kind), kind.format),
     };
     entries.push(entry);
     if (kind.session) texts.set(path, text);

package/src/workspace/runtimes.ts

@@ -15,6 +15,7 @@
  */
 
 import { join } from "node:path";
+import type { EnvironmentDeclaration } from "../config";
 import { lexiconNames } from "../lexicon-module";
 import type { ReasonCode } from "./reason-codes";
 
@@ -54,6 +55,11 @@ export interface MemberRuntimes {
   /** The default runtime's name. */
   default: string;
   reasons: RuntimeReason[];
+  /**
+   * The config's `environments`, read in the same load (#2695): `[]` when it
+   * declares none, null when the config couldn't be read.
+   */
+  environments: EnvironmentDeclaration[] | null;
 }
 
 /** Loads a lexicon plugin by name; `loadPlugin` from the CLI unless a test swaps it. */
@@ -65,11 +71,14 @@ const firstLine = (err: unknown): string => (err instanceof Error ? err.message
 export async function readMemberRuntimes(dir: string, load?: PluginLoader): Promise<MemberRuntimes> {
   const reasons: RuntimeReason[] = [];
   let names: string[];
+  let environments: EnvironmentDeclaration[];
   try {
     const { loadChantConfig } = await import("../config");
-    names = lexiconNames((await loadChantConfig(dir)).config.lexicons ?? []);
+    const { config } = await loadChantConfig(dir);
+    names = lexiconNames(config.lexicons ?? []);
+    environments = config.environments ?? [];
   } catch (err) {
-    return { lexicons: [], default: LOCAL_RUNTIME, reasons: [{ code: "runtimes-config-unreadable", message: `chant.config.ts: ${firstLine(err)}` }] };
+    return { lexicons: [], default: LOCAL_RUNTIME, reasons: [{ code: "runtimes-config-unreadable", message: `chant.config.ts: ${firstLine(err)}` }], environments: null };
   }
   const loader = load ?? (await import("../cli/plugins")).loadPlugin;
   const lexicons: string[] = [];
@@ -81,7 +90,7 @@ export async function readMemberRuntimes(dir: string, load?: PluginLoader): Prom
       reasons.push({ code: "runtimes-lexicon-unreadable", message: `lexicon "${name}": ${firstLine(err)}` });
     }
   }
-  return { lexicons, default: LOCAL_RUNTIME, reasons };
+  return { lexicons, default: LOCAL_RUNTIME, reasons, environments };
 }
 
 /** The runtimes one component can deploy on, `local` first, each with its command line. */

package/src/workspace/session-kinds.ts

@@ -0,0 +1,79 @@
+/**
+ * Finding review-session kinds and the commits a session names (#2693), for
+ * the commands that act on a session by its id: `records review --session`,
+ * `records close` and `records --since <session id>`.
+ *
+ * A session kind is found through the workspace declaration nearest above
+ * the working directory, or named directly. Nothing here writes.
+ */
+
+import { execFileSync } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { WorkspaceReadError } from "./declaration";
+import { gitRoot, resolveRevision } from "./record-source";
+import { loadRecordKind, RecordReadError, type LoadedRecordKind } from "./records";
+import { declaredKindFiles, realpathOr } from "./records-cli";
+
+/** The shape of an id `records --since` looks up as a session before reading it as a revision: `S-0002`, `ws-052`. */
+export const SESSION_ID = /^[A-Za-z][A-Za-z0-9]*-[0-9]+$/;
+
+/**
+ * Every session kind among `extra` (kind files, resolved against `cwd`) and
+ * the kinds the declaration nearest above `cwd` names, each once, in that
+ * order. A kind that can't be loaded, or a declaration that can't be read,
+ * adds nothing: the read of that kind reports it.
+ */
+export async function findSessionKinds(cwd: string, extra: string[] = []): Promise<LoadedRecordKind[]> {
+  const files = [...extra.map((f) => resolve(cwd, f))];
+  try {
+    files.push(...declaredKindFiles(cwd).map((k) => k.file));
+  } catch (err) {
+    if (!(err instanceof WorkspaceReadError)) throw err;
+  }
+  const seen = new Set<string>();
+  const out: LoadedRecordKind[] = [];
+  for (const f of files) {
+    const real = realpathOr(f);
+    if (seen.has(real)) continue;
+    seen.add(real);
+    try {
+      const loaded = await loadRecordKind(f, cwd);
+      if (loaded.kind.session) out.push(loaded);
+    } catch (err) {
+      if (!(err instanceof RecordReadError)) throw err;
+    }
+  }
+  return out;
+}
+
+/** The session kinds whose `session.subjects.kind` is the kind file `subjectFile`. */
+export async function sessionKindsFor(subjectFile: string, cwd: string): Promise<LoadedRecordKind[]> {
+  const target = realpathOr(resolve(cwd, subjectFile));
+  return (await findSessionKinds(cwd)).filter((k) => realpathOr(resolve(dirname(k.file), k.kind.session!.subjects.kind)) === target);
+}
+
+/** The full commit id HEAD names in the repository holding `dir`, or null outside git or before the first commit. */
+export function headCommit(dir: string): string | null {
+  const top = gitRoot(realpathOr(dir));
+  if (!top) return null;
+  try {
+    return resolveRevision(top, "HEAD");
+  } catch (err) {
+    if (err instanceof RecordReadError) return null;
+    throw err;
+  }
+}
+
+/**
+ * Commit ids from `git log <args> --format=%H -- <path>` in the repository at
+ * `top`, newest first; empty when git knows nothing of the path.
+ */
+export function commitsTouching(top: string, path: string, args: string[]): string[] {
+  try {
+    return execFileSync("git", ["log", ...args, "--format=%H", "--", path], { cwd: top, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] })
+      .split("\n")
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}

package/src/workspace/status.ts

@@ -91,7 +91,7 @@ export const STATUS_ERROR_CODES = [
 export type StatusErrorCode = (typeof STATUS_ERROR_CODES)[number];
 
 /** Environment names a ledger directory can have: no `/`, no leading `_` or `.` (those are chant's own directories). */
-const ENV_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+export const ENV_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
 
 export interface StatusRelease {
   component: string;