@intentius/chant 0.87.0 → 0.89.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",
@@ -207,7 +215,8 @@
             "work-implements-undecided",
             "work-done-unpinned",
             "work-closed-without-date",
-            "work-done-gap-open"
+            "work-done-gap-open",
+            "record-unattested"
           ]
         },
         "message": { "type": "string" }
@@ -274,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

@@ -110,22 +110,54 @@ export const REVIEW_REASON_CODES = [
 export type ReviewReasonCode = (typeof REVIEW_REASON_CODES)[number];
 
 /**
- * Why a verdict's seal is not attested (#2687). Closed, like the reason
- * codes. Every verdict in the quorum carries one of these in its
- * `attestation`, unless its seal verified.
+ * 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 carries no seal. */
+  /** The verdict or record carries no seal. */
   "seal-missing",
-  /** The reviewer has no key in the signers file at base. */
+  /** 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. */
+  /** 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. */
@@ -136,8 +168,8 @@ export interface VerdictAttestation {
 }
 
 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;
 }
 
@@ -274,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(),
@@ -584,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
@@ -654,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])) {
@@ -876,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[];
@@ -1041,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;