@intentius/chant 0.79.0 → 0.80.0

package/src/op/activity-contract-registry.ts

@@ -36,6 +36,7 @@
 
 import * as coreContracts from "./activities/activity-contracts";
 import { collectActivityContracts, type ActivityContract } from "./activity-contract";
+import { importLexiconModule } from "../lexicon-module";
 
 /**
  * The shape {@link loadActivityContracts} reads off a plugin: an optional
@@ -74,16 +75,29 @@ export async function loadActivityContracts(
 
   for (const entry of lexicons) {
     const name = typeof entry === "string" ? entry : entry.name;
+    let contributor: LexiconActivityContractContributor | undefined = typeof entry === "string" ? undefined : entry;
     try {
-      const spec = `@intentius/chant-lexicon-${name}/op/activity-contracts`;
-      collectActivityContracts((await import(spec)) as Record<string, unknown>, contracts);
+      // chant #2520 — a lexicon declared by module path has no subpath to
+      // import. Its plugin's `activityContracts()` member stands in for it;
+      // given only the name, the plugin is read from the declared module.
+      const local = await importLexiconModule(name);
+      if (local !== undefined) {
+        contributor ??= Object.values(local).find(
+          (v): v is LexiconActivityContractContributor =>
+            typeof v === "object" && v !== null && (v as { name?: unknown }).name === name &&
+            typeof (v as { activityContracts?: unknown }).activityContracts === "function",
+        );
+      } else {
+        const spec = `@intentius/chant-lexicon-${name}/op/activity-contracts`;
+        collectActivityContracts((await import(spec)) as Record<string, unknown>, contracts);
+      }
     } catch {
       // Lexicon absent or declares no contracts at the conventional subpath.
     }
 
-    if (typeof entry !== "string" && typeof entry.activityContracts === "function") {
+    if (contributor !== undefined && typeof contributor.activityContracts === "function") {
       try {
-        for (const contract of entry.activityContracts()) contracts.set(contract.name, contract);
+        for (const contract of contributor.activityContracts()) contracts.set(contract.name, contract);
       } catch {
         // A plugin member that throws contributes nothing, the same as one that is absent.
       }

package/src/op/activity-registry.ts

@@ -12,6 +12,7 @@
 
 import * as baseActivities from "./activities";
 import { ACTIVITY_PROFILES, type ActivityProfile } from "./activity-profiles";
+import { importLexiconModule } from "../lexicon-module";
 
 export type { ActivityProfile } from "./activity-profiles";
 
@@ -52,6 +53,16 @@ export async function loadActivities(lexicons: string[] = []): Promise<Map<strin
 
   for (const name of lexicons) {
     try {
+      // chant #2520 — a lexicon declared by module path has no subpath to
+      // import; its plugin's `activities()` member stands in for it.
+      const local = await importLexiconModule(name);
+      if (local !== undefined) {
+        const plugin = Object.values(local).find((v) => isActivityContributor(v) && v.name === name) as
+          | ActivityContributor
+          | undefined;
+        if (plugin) collectActivities(await plugin.activities(), activities);
+        continue;
+      }
       const spec = `@intentius/chant-lexicon-${name}/op/activities`;
       collectActivities((await import(spec)) as Record<string, unknown>, activities);
     } catch {
@@ -62,6 +73,21 @@ export async function loadActivities(lexicons: string[] = []): Promise<Map<strin
   return activities;
 }
 
+/** A plugin-shaped export with an `activities()` member (`LexiconPlugin.activities`). Structural, so this layer does not import `../lexicon.ts`. */
+interface ActivityContributor {
+  name: string;
+  activities(): Record<string, unknown> | Promise<Record<string, unknown>>;
+}
+
+function isActivityContributor(value: unknown): value is ActivityContributor {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { name?: unknown }).name === "string" &&
+    typeof (value as { activities?: unknown }).activities === "function"
+  );
+}
+
 /**
  * The built-in profile table. Kept async because it is awaited on the CLI's
  * run path alongside {@link loadActivities}, and because a hosted runtime may

package/src/op/discover-convergence.test.ts

@@ -0,0 +1,70 @@
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { discoverOps } from "./discover";
+import { resetDiscoveryWarnings } from "../discovery/convergence";
+
+/**
+ * chant#2527's warning release for Op discovery. The upward search for the
+ * Op root stays as it is; what changes next release is the downward walk,
+ * which stops at child projects. Today an Op in a child project is
+ * discovered, and it still is here, with a warning naming it.
+ */
+let fakeGitRoot = "";
+vi.mock("../runtime-adapter", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../runtime-adapter")>()),
+  getRuntime: () => ({
+    spawn: async (cmd: string[]) =>
+      cmd[0] === "git" && cmd[1] === "rev-parse"
+        ? { stdout: fakeGitRoot, stderr: "", exitCode: 0 }
+        : { stdout: "", stderr: "", exitCode: 0 },
+  }),
+}));
+
+const OP_FILE = (name: string): string =>
+  `export default { props: { name: ${JSON.stringify(name)}, overview: "t", phases: [{ name: "Run", steps: [] }] } };\n`;
+
+describe("discoverOps — an Op in a child project (#2527 warning release)", () => {
+  let root: string;
+  let stderr: string[];
+
+  beforeEach(() => {
+    root = realpathSync(mkdtempSync(join(tmpdir(), "chant-2527-ops-")));
+    fakeGitRoot = root;
+    resetDiscoveryWarnings();
+    stderr = [];
+    vi.spyOn(console, "error").mockImplementation((...args: unknown[]) => void stderr.push(args.join(" ")));
+    vi.spyOn(process, "cwd").mockReturnValue(root);
+    writeFileSync(join(root, "chant.config.json"), JSON.stringify({ lexicons: ["aws"] }));
+    mkdirSync(join(root, "ops"), { recursive: true });
+    writeFileSync(join(root, "ops", "mine.op.ts"), OP_FILE("mine"));
+    mkdirSync(join(root, "child", "ops"), { recursive: true });
+    writeFileSync(join(root, "child", "chant.config.json"), JSON.stringify({ lexicons: ["aws"] }));
+    writeFileSync(join(root, "child", "ops", "theirs.op.ts"), OP_FILE("theirs"));
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  test("is still discovered, and the warning names it with the include glob", async () => {
+    const { ops, errors } = await discoverOps({ cwd: root });
+    expect(errors).toEqual([]);
+    expect([...ops.keys()].sort()).toEqual(["mine", "theirs"]);
+    expect(stderr).toEqual([
+      "warning: Op discovery under the current directory changes in the next release (chant#2527):\n" +
+        "  child/ops/theirs.op.ts: child/ is a child project with its own chant.config. " +
+        "Discovery stops at child projects from the next release. " +
+        'To keep reading it after the change, add "child" to include in chant.config.json, which the next release honours.',
+    ]);
+  });
+
+  test("with the glob in the config, nothing is printed", async () => {
+    writeFileSync(join(root, "chant.config.json"), JSON.stringify({ lexicons: ["aws"], include: ["child"] }));
+    const { ops } = await discoverOps({ cwd: root });
+    expect([...ops.keys()].sort()).toEqual(["mine", "theirs"]);
+    expect(stderr).toEqual([]);
+  });
+});

package/src/op/discover.ts

@@ -3,6 +3,7 @@ import { readdir } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import type { OpConfig } from "./types";
+import { warnDiscoveryChanges } from "../discovery/convergence";
 
 export interface DiscoveredOp {
   config: OpConfig;
@@ -148,6 +149,9 @@ export async function discoverOps(opts?: { cwd?: string }): Promise<OpDiscoveryR
 
   const root = await findDiscoveryRoot(opts?.cwd);
   const files = await collectOpFiles(root);
+  // #2527's warning release: Op discovery stops at child projects below the
+  // root next release, and skips git-ignored files. `files` is unchanged.
+  await warnDiscoveryChanges({ walker: "ops", root, files });
 
   const nameToFile = new Map<string, string>();
 

package/src/op/gate-approval.ts

@@ -32,6 +32,7 @@
  */
 
 import { createHash } from "node:crypto";
+import { lexiconModulePath } from "../lexicon-module";
 import { isStepOutputRef, type StepOutputRef } from "./step-output-ref";
 
 /** What a policy's decision does to the gate. */
@@ -221,7 +222,8 @@ function isContextValue(value: unknown): boolean {
 
 /** Import `lexicon`'s evaluator. Throws a message that names the package when it is not installed or exports none. */
 export async function loadGatePolicyEvaluator(lexicon: string): Promise<GatePolicyEvaluator> {
-  const spec = `@intentius/chant-lexicon-${lexicon}/gate-policy`;
+  // chant #2520 — a lexicon declared by module path exports its evaluator from that module.
+  const spec = lexiconModulePath(lexicon) ?? `@intentius/chant-lexicon-${lexicon}/gate-policy`;
   let mod: Partial<GatePolicyEvaluator>;
   try {
     mod = (await import(spec)) as Partial<GatePolicyEvaluator>;

package/src/op/generate-pipeline.ts

@@ -17,6 +17,7 @@
  */
 
 import { discoverOps, type DiscoveredOp } from "./discover";
+import { lexiconModulePath } from "../lexicon-module";
 import {
   isLexiconPlugin,
   type LexiconPlugin,
@@ -36,7 +37,7 @@ import {
 async function loadLexiconPlugin(name: string): Promise<LexiconPlugin | null> {
   let mod: Record<string, unknown>;
   try {
-    mod = (await import(`@intentius/chant-lexicon-${name}`)) as Record<string, unknown>;
+    mod = (await import(lexiconModulePath(name) ?? `@intentius/chant-lexicon-${name}`)) as Record<string, unknown>;
   } catch {
     return null;
   }

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/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);
+  });
+});