@intentius/chant 0.78.0 → 0.80.0

package/src/op/op-ir.ts

@@ -144,6 +144,8 @@ export interface OpIRGateStep {
    * Absent on a gate that binds no plan.
    */
   plan?: GateStep["plan"];
+  /** Quorum, roles and policy (#2508), carried as authored. Absent on a gate that passes on one approval. */
+  approval?: GateStep["approval"];
 }
 
 export interface OpIREffectStep {
@@ -240,6 +242,7 @@ function irGateStep(step: GateStep): OpIRGateStep {
     timeout: step.timeout ?? "48h",
     ...(step.description ? { description: step.description } : {}),
     ...(step.plan !== undefined ? { plan: step.plan } : {}),
+    ...(step.approval !== undefined ? { approval: step.approval } : {}),
   };
 }
 
@@ -389,6 +392,7 @@ function opStepFromIR(step: OpIRStep): StepDefinition {
       timeout: step.timeout,
       ...(step.description ? { description: step.description } : {}),
       ...(step.plan !== undefined ? { plan: step.plan } : {}),
+      ...(step.approval !== undefined ? { approval: step.approval } : {}),
     };
   }
   return {

package/src/op/runtimes/local.ts

@@ -18,6 +18,7 @@
  * answers.
  */
 
+import { lexiconNames } from "../../lexicon-module";
 import { loadChantConfig } from "../../config";
 import { loadActivities, loadProfiles } from "../activity-registry";
 import { runOpLocally, OpRunFailure, type OpRunResult } from "../local-executor";
@@ -129,7 +130,7 @@ export function createLocalOpRuntime(opts: { projectPath?: string } = {}): OpRun
       // unreadable config just yields the base activities.
       let lexicons: string[] = [];
       try {
-        lexicons = (await loadChantConfig(projectPath)).config.lexicons ?? [];
+        lexicons = lexiconNames((await loadChantConfig(projectPath)).config.lexicons ?? []);
       } catch {
         // No/invalid chant.config — base activities only.
       }

package/src/op/types.ts

@@ -8,6 +8,7 @@
 import type { EffectReceiptRef } from "./receipt-store";
 import type { ActivityProfileName } from "./activity-profiles";
 import type { StepOutputRef } from "./step-output-ref";
+import type { GateApproval } from "./gate-approval";
 
 export interface OpConfig {
   /** Kebab-case identifier. Names the Op's output directory (`dist/ops/<name>/`), and is the name `chant run <name>` and another Op's `depends` refer to. */
@@ -196,6 +197,12 @@ export interface GateStepBase {
    * phase publishes no digest is not thereby unrunnable.
    */
   plan?: string | StepOutputRef;
+  /**
+   * Quorum, roles and a policy for who may pass this gate (#2508). Absent,
+   * the gate passes on one approval, as every gate did before. See
+   * `./gate-approval.ts`.
+   */
+  approval?: GateApproval;
 }
 
 /**

package/src/workspace/record-source.ts

@@ -0,0 +1,117 @@
+/**
+ * Where records are read from: the working tree, or a commit's git objects
+ * (`--at <rev>`, #2536). Reading at a revision needs no checkout and no
+ * network; it asks the local git object store only.
+ */
+
+import { execFileSync } from "node:child_process";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { RecordReadError } from "./records";
+
+export interface RecordSource {
+  /** Appended to messages, such as " at 91c7547e". Empty for the working tree. */
+  label: string;
+  /** File names directly inside `dir` (relative to the root, `/`-separated), or undefined when `dir` is missing. */
+  list(dir: string): string[] | undefined;
+  /** The text of a file listed by `list`. */
+  read(path: string): string;
+}
+
+/** Records in the working tree under `root`. */
+export function workingTreeSource(root: string): RecordSource {
+  return {
+    label: "",
+    list(dir) {
+      try {
+        return readdirSync(join(root, dir), { withFileTypes: true })
+          .filter((d) => d.isFile())
+          .map((d) => d.name);
+      } catch {
+        return undefined;
+      }
+    },
+    read(path) {
+      return readFileSync(join(root, path), "utf-8");
+    },
+  };
+}
+
+function git(cwd: string, args: string[], input?: string): string {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "utf-8",
+    input,
+    stdio: ["pipe", "pipe", "pipe"],
+    maxBuffer: 256 * 1024 * 1024,
+  });
+}
+
+/** The top of the git repository holding `cwd`, or undefined outside one. */
+export function gitRoot(cwd: string): string | undefined {
+  try {
+    return git(cwd, ["rev-parse", "--show-toplevel"]).trim();
+  } catch {
+    return undefined;
+  }
+}
+
+/** The full commit id `rev` names in the repository at `root`. */
+export function resolveRevision(root: string, rev: string): string {
+  if (rev.startsWith("-")) throw new RecordReadError("revision-unknown", `--at ${rev} is not a revision`);
+  try {
+    return git(root, ["rev-parse", "--verify", "--quiet", `${rev}^{commit}`]).trim();
+  } catch {
+    throw new RecordReadError("revision-unknown", `--at ${rev} names no commit in this repository`);
+  }
+}
+
+/** Records as they were at `commit`, read from the object store of the repository at `root`. */
+export function gitRevisionSource(root: string, commit: string): RecordSource {
+  const blobs = new Map<string, string>();
+  return {
+    label: ` at ${commit.slice(0, 8)}`,
+    list(dir) {
+      const treeish = dir === "." ? `${commit}^{tree}` : `${commit}:${dir}`;
+      try {
+        if (git(root, ["cat-file", "-t", treeish]).trim() !== "tree") return undefined;
+      } catch {
+        return undefined;
+      }
+      const entries = git(root, ["ls-tree", "-z", treeish])
+        .split("\0")
+        .filter(Boolean)
+        .map((line) => {
+          const tab = line.indexOf("\t");
+          const [, type, oid] = line.slice(0, tab).split(" ");
+          return { type, oid, name: line.slice(tab + 1) };
+        })
+        .filter((e) => e.type === "blob");
+      // One `cat-file --batch` for the whole directory: records are small, and
+      // one process beats one per file.
+      if (entries.length > 0) {
+        const out = Buffer.from(
+          execFileSync("git", ["cat-file", "--batch"], {
+            cwd: root,
+            input: entries.map((e) => e.oid).join("\n") + "\n",
+            maxBuffer: 256 * 1024 * 1024,
+          }),
+        );
+        let at = 0;
+        for (const e of entries) {
+          const nl = out.indexOf(0x0a, at);
+          const size = Number(out.subarray(at, nl).toString("utf-8").split(" ")[2]);
+          const start = nl + 1;
+          blobs.set(dir === "." ? e.name : `${dir}/${e.name}`, out.subarray(start, start + size).toString("utf-8"));
+          at = start + size + 1;
+        }
+      }
+      return entries.map((e) => e.name);
+    },
+    read(path) {
+      const text = blobs.get(path);
+      if (text === undefined) throw new Error(`${path} was not listed at ${commit}`);
+      return text;
+    },
+  };
+}

package/src/workspace/records-cli.ts

@@ -0,0 +1,126 @@
+/**
+ * `chant workspace records --kind <path> [--current] [--at <rev>] [--json]`,
+ * the first-test slice of the records query (#2546, #2536).
+ *
+ * It reads every record the kind file locates and prints them, with reason
+ * codes for any that are invalid. An invalid record never fails the command:
+ * 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).
+ */
+
+import { relative } from "node:path";
+import { formatError } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { gitRevisionSource, gitRoot, resolveRevision, workingTreeSource } from "./record-source";
+import { loadRecordKind, readRecords, RecordReadError, type ReadErrorCode, type RecordEntry } from "./records";
+
+/** The version of the `records` output this chant writes. */
+export const RECORDS_CONTRACT_VERSION = 1;
+
+/** `$id` of the JSON Schema for the `--json` output, shipped beside this file. */
+export const RECORDS_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/records/v1/records.schema.json";
+
+const USAGE = "chant workspace records --kind <kind file> [--current] [--at <rev>] [--json]";
+
+export interface RecordsQuery {
+  kind: string;
+  current?: boolean;
+  at?: string;
+  /** Where `kind` is resolved from and the repository is found. */
+  cwd: string;
+}
+
+/** The `records` output: a result, or a failure with one error code. */
+export type RecordsDocument =
+  | {
+      $schema: string;
+      contract: number;
+      kind: { name: string; schema: string; file: string };
+      at: string | null;
+      current: boolean;
+      records: RecordEntry[];
+      summary: { total: number; valid: number; invalid: number; superseded: number };
+    }
+  | { $schema: string; contract: number; error: { code: ReadErrorCode; message: string } };
+
+/** Run the query and build the document `--json` prints. Never throws a {@link RecordReadError}. */
+export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument> {
+  const top = gitRoot(query.cwd);
+  const root = top ?? query.cwd;
+  try {
+    const loaded = await loadRecordKind(query.kind, query.cwd);
+    let at: string | null = null;
+    let source = workingTreeSource(root);
+    if (query.at !== undefined) {
+      if (!top) throw new RecordReadError("not-a-git-repository", "--at reads git objects, and this directory is not in a git repository");
+      at = resolveRevision(top, query.at);
+      source = gitRevisionSource(top, at);
+    }
+    const result = await readRecords(loaded, { root, source, current: !!query.current });
+    return {
+      $schema: RECORDS_OUTPUT_SCHEMA_ID,
+      contract: RECORDS_CONTRACT_VERSION,
+      kind: {
+        name: loaded.kind.name,
+        schema: loaded.kind.schema.id,
+        file: relative(root, loaded.file).split("\\").join("/"),
+      },
+      at,
+      current: !!query.current,
+      records: result.records,
+      summary: result.summary,
+    };
+  } catch (err) {
+    if (!(err instanceof RecordReadError)) throw err;
+    return { $schema: RECORDS_OUTPUT_SCHEMA_ID, contract: RECORDS_CONTRACT_VERSION, error: { code: err.code, message: err.message } };
+  }
+}
+
+export async function runWorkspaceRecords(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  if (!args.kind) {
+    console.error(formatError({ message: "--kind <kind file> is required", hint: USAGE }));
+    return 1;
+  }
+  const doc = await queryRecords({ kind: args.kind, current: args.current, at: args.at, cwd: process.cwd() });
+  if (args.json) {
+    console.log(JSON.stringify(doc, null, 2));
+  } else if ("error" in doc) {
+    console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
+  } else {
+    console.log(formatRecords(doc.records, doc.summary, doc.at));
+  }
+  return "error" in doc ? 1 : 0;
+}
+
+function formatRecords(records: RecordEntry[], summary: { total: number; valid: number; invalid: number; superseded: number }, at: string | null): string {
+  const lines: string[] = [];
+  const idWidth = Math.max(2, ...records.map((r) => (r.id ?? "-").length));
+  const stateWidth = Math.max(5, ...records.map((r) => (r.state ?? "-").length));
+  for (const r of records) {
+    const title = typeof r.data?.title === "string" ? r.data.title : r.path;
+    const flag = r.valid ? "" : "  INVALID";
+    const superseded = r.supersededBy ? `  superseded by ${r.supersededBy}` : "";
+    lines.push(`${(r.id ?? "-").padEnd(idWidth)}  ${(r.state ?? "-").padEnd(stateWidth)}  ${title}${superseded}${flag}`);
+    for (const reason of r.reasons) lines.push(`${" ".repeat(idWidth + 2)}${reason.code}: ${reason.message} (${r.path})`);
+  }
+  lines.push(
+    `${summary.total} records${at ? ` at ${at.slice(0, 8)}` : ""}: ${summary.valid} valid, ${summary.invalid} invalid, ${summary.superseded} superseded`,
+  );
+  return lines.join("\n");
+}
+
+/** `chant workspace <anything else>`: only `records` exists so far. */
+export async function runWorkspaceUnknown(ctx: CommandContext): Promise<number> {
+  const sub = ctx.args.path && ctx.args.path !== "." ? ctx.args.path : "";
+  console.error(
+    formatError({
+      message: sub ? `Unknown workspace subcommand: ${sub}` : "chant workspace needs a subcommand",
+      hint: `Only records exists so far: ${USAGE}`,
+    }),
+  );
+  return 1;
+}

package/src/workspace/records-contract.test.ts

@@ -0,0 +1,88 @@
+/**
+ * The read contract for `chant workspace records --json` (#2536): the output
+ * schema is a valid draft 2020-12 document, its closed code lists match the
+ * code, and real output validates against it. The reference workspace (#2543)
+ * doesn't exist yet, so the chant repo's own decision files stand in for it.
+ */
+
+import { cpSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import Ajv2020 from "ajv/dist/2020";
+import { afterAll, describe, expect, test } from "vitest";
+import { queryRecords, RECORDS_CONTRACT_VERSION, RECORDS_OUTPUT_SCHEMA_ID, type RecordsDocument } from "./records-cli";
+import { READ_ERROR_CODES, RECORD_REASON_CODES } from "./records";
+import schema from "./records.schema.json";
+
+const REPO = join(import.meta.dirname, "..", "..", "..", "..");
+const KIND = "docs/design/decisions/decision.kind.mjs";
+
+const ajv = new Ajv2020({ strict: true, allErrors: true });
+const validate = ajv.compile(schema);
+
+function expectValid(doc: RecordsDocument): void {
+  const ok = validate(doc);
+  expect(ok, JSON.stringify(validate.errors, null, 2)).toBe(true);
+}
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+
+/** A directory holding a copy of the decisions, kind and schema, outside any git repository. */
+function copyDecisions(): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-records-contract-")));
+  scratch.push(root);
+  mkdirSync(join(root, "docs", "design"), { recursive: true });
+  cpSync(join(REPO, "docs", "design", "decisions"), join(root, "docs", "design", "decisions"), { recursive: true });
+  return root;
+}
+
+describe("records output schema", () => {
+  test("is a valid draft 2020-12 document with the published $id", () => {
+    expect(schema.$schema).toBe("https://json-schema.org/draft/2020-12/schema");
+    expect(ajv.validateSchema(schema)).toBe(true);
+    expect(schema.$id).toBe(RECORDS_OUTPUT_SCHEMA_ID);
+    expect(RECORDS_CONTRACT_VERSION).toBe(1);
+  });
+
+  test("lists exactly the reason and error codes the code can return", () => {
+    expect(schema.$defs.reason.properties.code.enum).toEqual([...RECORD_REASON_CODES]);
+    expect(schema.$defs.failure.properties.error.properties.code.enum).toEqual([...READ_ERROR_CODES]);
+  });
+
+  test("the chant repo's decisions validate, current and not", async () => {
+    for (const current of [false, true]) {
+      const doc = await queryRecords({ kind: KIND, current, cwd: REPO });
+      expectValid(doc);
+      expect("error" in doc).toBe(false);
+    }
+  });
+
+  test("invalid records validate, each with its reason", async () => {
+    const root = copyDecisions();
+    const dir = join(root, "docs", "design", "decisions");
+    writeFileSync(join(dir, "ws-001-trust-root.md"), "no front matter\n");
+    writeFileSync(join(dir, "ws-900-extra.md"), "---\nid: \"ws-900\"\nstate: \"decided\"\n---\n");
+    const doc = await queryRecords({ kind: KIND, cwd: root });
+    expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.at).toBeNull();
+    expect(doc.summary.invalid).toBe(2);
+  });
+
+  test("every failure validates with its code", async () => {
+    const root = copyDecisions();
+    const docs = [
+      await queryRecords({ kind: "missing.kind.mjs", cwd: root }),
+      await queryRecords({ kind: KIND, at: "HEAD", cwd: root }),
+    ];
+    for (const doc of docs) expectValid(doc);
+    expect(docs.map((d) => ("error" in d ? d.error.code : "ok"))).toEqual(["kind-unreadable", "not-a-git-repository"]);
+  });
+
+  test("a document mixing records and an error is refused", () => {
+    expect(validate({ $schema: RECORDS_OUTPUT_SCHEMA_ID, contract: 1, error: { code: "revision-unknown", message: "x" }, records: [] })).toBe(false);
+  });
+});

package/src/workspace/records.schema.json

@@ -0,0 +1,120 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/records/v1/records.schema.json",
+  "title": "chant workspace records output",
+  "description": "What `chant workspace records --json` prints, version 1 of the read contract for records (#2536). This is the first-test slice (#2546): records are unsealed and there is no workspace declaration yet. Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists: a new code is a new contract version.",
+  "oneOf": [{ "$ref": "#/$defs/result" }, { "$ref": "#/$defs/failure" }],
+  "$defs": {
+    "result": {
+      "description": "The read worked. Exit code 0, even when some records are invalid.",
+      "type": "object",
+      "required": ["$schema", "contract", "kind", "at", "current", "records", "summary"],
+      "properties": {
+        "$schema": { "const": "https://intentius.io/chant/schemas/workspace/records/v1/records.schema.json" },
+        "contract": { "const": 1 },
+        "kind": {
+          "type": "object",
+          "required": ["name", "schema", "file"],
+          "properties": {
+            "name": { "type": "string", "description": "The kind's name, such as \"decision\"." },
+            "schema": { "type": "string", "description": "The `$id` of the schema each record was validated against." },
+            "file": { "type": "string", "description": "The kind file, relative to the repository root, with / separators." }
+          }
+        },
+        "at": {
+          "description": "The full commit id the records were read at (--at), or null for the working tree.",
+          "type": ["string", "null"],
+          "pattern": "^[0-9a-f]{40,64}$"
+        },
+        "error": false,
+        "current": { "type": "boolean", "description": "Whether superseded records were left out (--current)." },
+        "records": {
+          "description": "One entry per file the kind locates, sorted by path.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/record" }
+        },
+        "summary": {
+          "type": "object",
+          "required": ["total", "valid", "invalid", "superseded"],
+          "properties": {
+            "total": { "type": "integer", "minimum": 0, "description": "Entries in records." },
+            "valid": { "type": "integer", "minimum": 0 },
+            "invalid": { "type": "integer", "minimum": 0 },
+            "superseded": { "type": "integer", "minimum": 0, "description": "Records a closed record supersedes, counted before --current leaves them out." }
+          }
+        }
+      }
+    },
+    "record": {
+      "type": "object",
+      "required": ["id", "path", "state", "valid", "reasons", "supersededBy", "data"],
+      "properties": {
+        "id": { "type": ["string", "null"], "description": "Null when the front matter could not be parsed or has no string id." },
+        "path": { "type": "string", "description": "From the repository root, with / separators." },
+        "state": { "type": ["string", "null"], "description": "The state as the record writes it. Supersession is reported in supersededBy, not here." },
+        "valid": { "type": "boolean", "description": "True exactly when reasons is empty." },
+        "reasons": { "type": "array", "items": { "$ref": "#/$defs/reason" } },
+        "supersededBy": {
+          "type": ["string", "null"],
+          "description": "The id of the closed record whose supersedes link replaces this one. Derived from that record's link, never from this record's own fields."
+        },
+        "data": {
+          "type": ["object", "null"],
+          "description": "The front matter as JSON, following the kind's schema when valid is true. Null when it could not be parsed."
+        }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "valid": { "const": true } } },
+          "then": { "properties": { "reasons": { "type": "array", "maxItems": 0 }, "data": { "type": "object" }, "id": { "type": "string" } } },
+          "else": { "properties": { "reasons": { "type": "array", "minItems": 1 } } }
+        }
+      ]
+    },
+    "reason": {
+      "type": "object",
+      "required": ["code", "message"],
+      "properties": {
+        "code": {
+          "enum": [
+            "record-unparseable",
+            "record-schema-invalid",
+            "record-id-duplicate",
+            "record-supersedes-unknown",
+            "record-supersedes-conflict"
+          ]
+        },
+        "message": { "type": "string" }
+      }
+    },
+    "failure": {
+      "description": "The read failed and returned no records. Exit code 1.",
+      "type": "object",
+      "required": ["$schema", "contract", "error"],
+      "properties": {
+        "$schema": { "const": "https://intentius.io/chant/schemas/workspace/records/v1/records.schema.json" },
+        "contract": { "const": 1 },
+        "error": {
+          "type": "object",
+          "required": ["code", "message"],
+          "properties": {
+            "code": {
+              "enum": [
+                "kind-unreadable",
+                "kind-invalid",
+                "schema-unreadable",
+                "schema-id-mismatch",
+                "schema-invalid",
+                "location-missing",
+                "not-a-git-repository",
+                "revision-unknown"
+              ]
+            },
+            "message": { "type": "string" }
+          }
+        },
+        "records": false
+      }
+    }
+  }
+}