@intentius/chant 0.101.0 → 0.104.0

package/src/workspace/conformance/writer-conformance.e2e.test.ts

@@ -0,0 +1,177 @@
+/**
+ * The writer conformance suite run end to end (#3159): a writer that
+ * conforms, with a cache in its state directory, passes every action; a
+ * writer that breaks each rule once is caught at the step that broke it. Both
+ * run on a workspace generated from the shipped fixtures, at the same time.
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import {
+  referenceWriter,
+  runWorkspaceWriterConformance,
+  WRITE_CONTRACT_ACTIONS,
+  WRITE_CONTRACT_JSON_FLAGS,
+  WRITER_INPUTS,
+  WRITER_KINDS,
+  WRITER_SCRIPT,
+  type ChantTransport,
+  type WorkspaceWriterFactory,
+  type WriteStep,
+} from "./index";
+
+/** One call of the step's command, as a writer makes it. */
+const perform = async (chant: ChantTransport, step: WriteStep, extra: string[] = []) => {
+  const run = await chant.run(["workspace", ...step.action.split(" "), ...step.args, ...WRITE_CONTRACT_JSON_FLAGS[step.action][0], ...extra], step.input === undefined ? undefined : { input: step.input });
+  return JSON.parse(run.stdout) as Record<string, unknown>;
+};
+
+/** The reference writer with a cache of its facts in its state directory: rebuilt from chant when it is gone. */
+const cachingWriter: WorkspaceWriterFactory = (chant, { stateDir }) => {
+  const inner = referenceWriter(chant, { stateDir });
+  const cache = join(stateDir, "cache", "facts.json");
+  return {
+    write: (step) => inner.write(step),
+    async facts() {
+      if (existsSync(cache)) return JSON.parse(readFileSync(cache, "utf-8"));
+      const facts = await inner.facts();
+      // A cache is private state the suite allows; the suite deletes it for amnesia.
+      const { mkdirSync } = await import("node:fs");
+      mkdirSync(join(stateDir, "cache"), { recursive: true });
+      writeFileSync(cache, JSON.stringify(facts));
+      return facts;
+    },
+    holds: () => [
+      { record: "fix-002", kind: WRITER_KINDS.decision },
+      { run: "writer-run-1" },
+      { lease: "W-001", kind: WRITER_KINDS.work },
+      { exempt: "cache", what: "cache/facts.json, the facts as last read" },
+    ],
+  };
+};
+
+/** A writer that breaks one rule at each step it performs, and keeps a review only in its own state. */
+const leakyWriter: WorkspaceWriterFactory = (chant, { stateDir }) => {
+  const reviews = join(stateDir, "reviews.json");
+  return {
+    async write(step) {
+      if (step.id === "decision") return { ...(await perform(chant, step)), note: "the writer's own field" };
+      if (step.id === "amend") {
+        const doc = await perform(chant, step);
+        // A second write the step did not ask for: another decision.
+        const extra = WRITER_SCRIPT.find((s) => s.id === "decision")!;
+        await chant.run(["workspace", "records", "new", WRITER_KINDS.decision, "--from", "-"], { input: JSON.stringify({ ...(extra.params({}) as { fields: object }).fields, title: "A decision nobody asked for" }) });
+        return doc;
+      }
+      if (step.id === "review") {
+        const doc = await perform(chant, step);
+        writeFileSync(reviews, JSON.stringify([{ id: doc.id, by: "conformance-reviewer", verdict: "agree" }]));
+        writeFileSync(join(stateDir, "notes.txt"), "kept and not declared");
+        return doc;
+      }
+      if (step.id === "reanswer") return perform(chant, step, ["--dry-run"]);
+      return perform(chant, step);
+    },
+    async facts() {
+      // A write made while reading: refused by chant, still not a read.
+      await chant.run(["workspace", "runs", "start", "--from", "-"], { input: "{}" });
+      return { reviews: existsSync(reviews) ? JSON.parse(readFileSync(reviews, "utf-8")) : [] };
+    },
+    holds: () => [
+      { record: "fix-999", kind: WRITER_KINDS.decision },
+      { exempt: "database" as never, what: "events" },
+    ],
+  };
+};
+
+describe("the writer conformance suite (#3159)", () => {
+  test.concurrent("a writer that writes only through chant passes every action, the amnesia test and its holdings", async () => {
+    const report = await runWorkspaceWriterConformance(cachingWriter, { privateState: [{ path: "cache", is: "cache" }] });
+    expect(report.problems).toEqual([]);
+    expect(report.checked).toEqual([...WRITE_CONTRACT_ACTIONS]);
+    expect(report.skipped).toEqual([]);
+    expect(report.results.map((r) => [r.id, r.by])).toEqual(WRITER_SCRIPT.map((s) => [s.id, "writer"]));
+    expect(report.facts.after).toEqual(report.facts.before);
+    // #3173: three amendments of one record at once, one written, two refused with record-conflict and written on retry.
+    expect(report.after.concurrent).toEqual([]);
+    expect(report.facts.before).toMatchObject({
+      decision: [["fix-001", "decided"], ["fix-002", "proposed"]],
+      session: [["S-0001", "closed"]],
+      // #3403: the ad-hoc question an agent asked, answered from the options it offered.
+      answer: [
+        [expect.stringMatching(/^agent-question-/), "answered"],
+        [expect.stringMatching(/^slice-tier-/), "answered"],
+      ],
+      work: [["W-001", "open"]],
+      runs: [["conformance-run", "ended"], ["writer-run-1", "ended"], ["writer-run-2", "ended"]],
+      // #3308: the box's listing, set through chant with its cover copied in, survives amnesia.
+      listing: {
+        app: {
+          published: true,
+          title: "The writer suite's box",
+          line: "Listed through chant, read back after amnesia.",
+          cover: { path: "app/listing/cover.png", sha256: createHash("sha256").update(WRITER_INPUTS.cover.bytes).digest("hex") },
+        },
+      },
+      // #3172: the checkpoint of the uncommitted work; restoring it to the same tree takes no second one.
+      wip: { main: [["save", "turn:1"]] },
+    });
+  }, 900_000);
+
+  test.concurrent("a writer that breaks the rules is caught at each step and after", async () => {
+    const report = await runWorkspaceWriterConformance(leakyWriter, {
+      actions: ["records new", "records amend", "records review", "points answer"],
+      privateState: [{ path: "reviews.json", is: "cache" }],
+    });
+    expect(report.checked).toEqual(["records new", "records amend", "records review", "points answer"]);
+    const by = Object.fromEntries(report.results.map((r) => [r.id, r]));
+    expect(by.claim.by).toBe("suite");
+    expect(by.listing).toMatchObject({ by: "suite", problems: [] });
+    expect(by.checkpoint).toMatchObject({ by: "suite", problems: [] });
+    expect(by.undo).toMatchObject({ by: "suite", problems: [] });
+    expect(by.session.problems).toEqual([]);
+    expect(by.decision.problems).toEqual(["decision (records new): the writer must return the document chant printed, unchanged, and it returned something else"]);
+    expect(by.amend.problems).toHaveLength(2);
+    expect(by.amend.problems[0]).toMatch(/^amend \(records amend\): made 2 chant calls .* expected exactly one$/);
+    expect(by.amend.problems[1]).toMatch(/^amend \(records amend\): files changed that chant did not report writing: decisions\/fix-003-a-decision-nobody-asked-for\.md \(added\)$/);
+    expect(by.review.problems).toEqual([]);
+    expect(by.answer.problems).toEqual([]);
+    expect(by.retract.by).toBe("suite");
+    expect(by.retract.problems).toEqual([]);
+    expect(by.reanswer.problems).toEqual([expect.stringMatching(/^reanswer \(points answer\): .* it may add only nothing or --json, and it added --dry-run$/)]);
+    expect(report.after.facts).toEqual([
+      "facts: before amnesia, facts() made calls outside the read contract: workspace runs start --from -",
+      "facts: after amnesia, facts() made calls outside the read contract: workspace runs start --from -",
+    ]);
+    expect(report.after.state).toEqual(["state: the writer keeps notes.txt in its state directory, and privateState does not declare it"]);
+    expect(report.after.amnesia).toEqual([expect.stringMatching(/^amnesia: after its private state was deleted, the writer shows other facts; before: \{"reviews":\[\{"id":"fix-002".*after: \{"reviews":\[\]\}$/)]);
+    expect(report.after.holds).toEqual([
+      "holds: the writer holds record fix-999 of decisions/decision.kind.mjs, which the repository does not have",
+      'holds: events is held as "database"; outside the repo a tool keeps only cache, telemetry, secret, runtime (ws-074)',
+    ]);
+    expect(report.after.readBack).toEqual([]);
+    expect(report.after.concurrent).toEqual([]);
+  }, 900_000);
+
+  test.concurrent("a writer that hides a conflict by writing again without --expect is caught (#3173)", async () => {
+    const blindRetry: WorkspaceWriterFactory = (chant, ctx) => {
+      const inner = referenceWriter(chant, ctx);
+      return {
+        async write(step) {
+          const doc = (await inner.write(step)) as { error?: { code: string } };
+          if (doc.error?.code !== "record-conflict" || step.action !== "records amend") return doc;
+          // Overwrites whatever the other writer wrote, and reports success.
+          const args = step.args.filter((a, i, all) => a !== "--expect" && all[i - 1] !== "--expect");
+          return JSON.parse((await chant.run(["workspace", "records", "amend", ...args], { input: step.input })).stdout);
+        },
+        facts: () => inner.facts(),
+      };
+    };
+    const report = await runWorkspaceWriterConformance(blindRetry, { actions: ["records amend"] });
+    expect(report.after.concurrent.length).toBeGreaterThan(0);
+    expect(report.after.concurrent.every((p) => p.startsWith("concurrent: "))).toBe(true);
+    expect(report.after.concurrent.join("\n")).toMatch(/made 2 chant calls/);
+  }, 900_000);
+});

package/src/workspace/conformance/writer.test.ts

@@ -0,0 +1,186 @@
+/**
+ * The writer conformance suite's checks on their own (#3159): the calls a
+ * step may make, the changes a step may leave, the state a writer may keep,
+ * and the fixture it writes to. No chant runs here; the suite run end to end
+ * is writer-conformance.e2e.test.ts.
+ */
+
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { describe, expect, test } from "vitest";
+import {
+  buildStep,
+  isReadCall,
+  reportedWrites,
+  selectActions,
+  undeclaredState,
+  unreportedChanges,
+  WRITE_CONTRACT_ACTIONS,
+  WRITE_CONTRACT_SCHEMAS,
+  writeArgv,
+  writeContractSchema,
+  writerCallProblems,
+  writerDocumentProblems,
+  WRITER_FIXTURE_DIR,
+  WRITER_SCRIPT,
+  type ChantRun,
+  type WriteStep,
+} from "./index";
+
+const repoRoot = resolve(import.meta.dirname, "..", "..", "..", "..", "..");
+
+const review = buildStep(WRITER_SCRIPT.find((s) => s.id === "review")!, { decision: { id: "fix-002" } });
+const decision = buildStep(WRITER_SCRIPT.find((s) => s.id === "decision")!, {});
+const run = (argv: string[], input?: string, stdout = ""): ChantRun => ({ argv, ...(input === undefined ? {} : { input }), status: 0, stdout, stderr: "" });
+
+describe("the script (#3159)", () => {
+  test("covers every write-contract action, and each action has a schema that ships", () => {
+    expect(new Set(WRITER_SCRIPT.map((s) => s.action))).toEqual(new Set(WRITE_CONTRACT_ACTIONS));
+    for (const a of WRITE_CONTRACT_ACTIONS) expect(writeContractSchema(a).schema.$id, a).toMatch(new RegExp(`/${WRITE_CONTRACT_SCHEMAS[a].replace(".", "\\.")}$`));
+  });
+
+  test("writeArgv: fields go on stdin, everything else is a flag", () => {
+    expect(review.args).toEqual(["fix-002", "--kind", "decisions/decision.kind.mjs", "--verdict", "agree", "--by", "conformance-reviewer", "--note", "Written through chant, read back after amnesia."]);
+    expect(review.input).toBeUndefined();
+    expect(decision.args).toEqual(["decisions/decision.kind.mjs", "--from", "-"]);
+    expect(JSON.parse(decision.input!)).toMatchObject({ title: "How a writer writes the workspace", state: "proposed" });
+    expect(writeArgv("work evidence", { id: "W-001", kind: "work/work.kind.mjs", holder: "h", token: "t", entry: { criterion: "AC-1" } })).toEqual({
+      args: ["W-001", "--holder", "h", "--token", "t", "--from", "-", "--kind", "work/work.kind.mjs"],
+      input: '{"criterion":"AC-1"}',
+    });
+    expect(writeArgv("runs end", { id: "r", fields: {} })).toEqual({ args: ["r", "--from", "-"], input: "{}" });
+    expect(writeArgv("box listing set", { member: "app", fields: { title: "T" }, cover: "/in/cover.png" })).toEqual({
+      args: ["app", "--from", "-", "--cover", "/in/cover.png"],
+      input: '{"title":"T"}',
+    });
+    const listing = buildStep(WRITER_SCRIPT.find((s) => s.id === "listing")!, {}, { dir: "/in" });
+    expect(listing.args).toEqual(["app", "--from", "-", "--cover", "/in/cover.png"]);
+    expect(buildStep(WRITER_SCRIPT.find((s) => s.id === "listing")!, {}).args).toEqual(["app", "--from", "-"]);
+    // #3403: an ad-hoc ask reads its question and candidates on stdin, and takes the inputs as JSON.
+    const adhoc = buildStep(WRITER_SCRIPT.find((s) => s.id === "adhoc")!, {});
+    expect(adhoc.args).toEqual(["agent-question", "--inputs", '{"ask.id":"conformance-ask-1","ask.by":"conformance-writer"}', "--candidates", "-", "--subject", "W-001", "--kind", "answers/answer.kind.mjs"]);
+    expect(JSON.parse(adhoc.input!)).toMatchObject({ question: expect.any(String), criteria: { flag: expect.any(String), now: expect.any(String) } });
+    // The inputs may be spelled with other key order or spacing.
+    const respelled = ["workspace", "points", "ask", "agent-question", "--inputs", '{ "ask.by": "conformance-writer", "ask.id": "conformance-ask-1" }', "--candidates", "-", "--subject", "W-001", "--kind", "answers/answer.kind.mjs"];
+    expect(writerCallProblems(adhoc, [run(respelled, adhoc.input)])).toEqual([]);
+    expect(writerCallProblems(adhoc, [run(respelled.map((a) => (a.includes("ask.id") ? '{"ask.id":"other"}' : a)), adhoc.input)])).toHaveLength(1);
+    // #3172: a snapshot takes no stdin, and the restore names the snapshot the save took.
+    expect(writeArgv("wip save", { label: "turn:1", by: "p" })).toEqual({ args: ["--label", "turn:1", "--by", "p"] });
+    expect(writeArgv("wip save", {})).toEqual({ args: [] });
+    expect(buildStep(WRITER_SCRIPT.find((s) => s.id === "undo")!, { checkpoint: { snapshot: { commit: "c0ffee" } } }).args).toEqual(["c0ffee", "--by", "conformance"]);
+  });
+
+  test("a later step's params come from the documents of the steps before it", () => {
+    const renew = buildStep(WRITER_SCRIPT.find((s) => s.id === "renew")!, { claim: { lease: { token: "tok-1" } } });
+    expect(renew.args).toEqual(["W-001", "--holder", "conformance-writer", "--token", "tok-1", "--kind", "work/work.kind.mjs"]);
+  });
+
+  test("selectActions refuses a name that is not an action, and an empty list", () => {
+    expect(selectActions(["records review", "points answer"])).toEqual({
+      checked: ["records review", "points answer"],
+      skipped: WRITE_CONTRACT_ACTIONS.filter((a) => a !== "records review" && a !== "points answer"),
+    });
+    expect(() => selectActions(["records pin" as never])).toThrow(/not write-contract actions: records pin/);
+    expect(() => selectActions([])).toThrow(/actions is empty/);
+  });
+});
+
+describe("writerCallProblems (#3159)", () => {
+  test("exactly one call of the action, its arguments in order, its JSON flag, its fields on stdin", () => {
+    expect(writerCallProblems(review, [run(["workspace", "records", "review", ...review.args])])).toEqual([]);
+    expect(writerCallProblems(review, [run(["workspace", "records", "review", ...review.args, "--json"])])).toEqual([]);
+    expect(writerCallProblems(decision, [run(["workspace", "records", "new", ...decision.args], JSON.stringify(JSON.parse(decision.input!), null, 2))])).toEqual([]);
+  });
+
+  test("a second call, another command, an extra flag, other fields or stdin for a command that reads none", () => {
+    const argv = ["workspace", "records", "review", ...review.args];
+    expect(writerCallProblems(review, [run(["workspace", "ls", "--json"]), run(argv)])[0]).toMatch(/^review \(records review\): made 2 chant calls .* expected exactly one$/);
+    expect(writerCallProblems(review, [run(["workspace", "records", "amend", ...review.args])])[0]).toMatch(/which is not workspace records review/);
+    expect(writerCallProblems(review, [run([...argv, "--dry-run"])])[0]).toMatch(/it may add only nothing or --json, and it added --dry-run/);
+    expect(writerCallProblems(review, [run(argv, "{}")])[0]).toMatch(/gave chant .* something on stdin, and the command reads nothing there/);
+    expect(writerCallProblems(decision, [run(["workspace", "records", "new", ...decision.args], '{"title":"other"}')])[0]).toMatch(/other fields on stdin than the step's/);
+  });
+});
+
+describe("writerDocumentProblems (#3159)", () => {
+  test("a refusal, a changed document and one that does not validate", () => {
+    const refusal = { $schema: writeContractSchema("records review").schema.$id, contract: 1, error: { code: "record-not-found", message: "no fix-002" } };
+    const printed = run(["workspace", "records", "review"], undefined, JSON.stringify(refusal));
+    expect(writerDocumentProblems(review, printed, refusal)).toEqual(["review (records review): chant did not write: record-not-found: no fix-002"]);
+    expect(writerDocumentProblems(review, printed, { ...refusal, extra: 1 }).join("\n")).toMatch(/must return the document chant printed, unchanged/);
+    const bad = { $schema: refusal.$schema, contract: 2 };
+    expect(writerDocumentProblems(review, run([], undefined, JSON.stringify(bad)), bad).join("\n")).toMatch(/does not validate against records-review.schema.json/);
+    expect(writerDocumentProblems(review, run(["workspace"], undefined, ""), undefined)).toEqual(["review (records review): chant workspace printed nothing"]);
+  });
+});
+
+describe("unreportedChanges (#3159)", () => {
+  const files = (o: Record<string, string>) => o;
+  test("a record write may change only the path it reports, and no ref", () => {
+    const doc = { path: "decisions/fix-002-x.md" };
+    expect(unreportedChanges(review, doc, { before: files({ a: "1" }), after: files({ a: "1", "decisions/fix-002-x.md": "2" }) }, { before: { HEAD: "m 1" }, after: { HEAD: "m 1" } })).toEqual([]);
+    expect(unreportedChanges(review, doc, { before: files({ a: "1" }), after: files({ a: "9", "notes.md": "2" }) }, { before: { HEAD: "m 1" }, after: { HEAD: "m 2" } })).toEqual([
+      "review (records review): files changed that chant did not report writing: a (changed), notes.md (added)",
+      "review (records review): git refs changed that chant did not report writing: HEAD",
+    ]);
+  });
+
+  test("a lease may move its ref and chant/lifecycle to the commit it reports; a run only chant/lifecycle", () => {
+    const claim = buildStep(WRITER_SCRIPT.find((s) => s.id === "claim")!, {});
+    const doc = { ref: "refs/chant/lease/work/W-001", history: { commit: "c2" } };
+    expect(reportedWrites("work claim", doc)).toEqual({ paths: [], refs: { "refs/heads/chant/lifecycle": "c2", "refs/chant/lease/work/W-001": "*" } });
+    expect(reportedWrites("wip save", { ref: "refs/chant/wip/main", snapshot: { commit: "s1" }, replication: { remote: "origin", pushed: [{ ref: "refs/chant/wip/main", commit: "s1" }] } })).toEqual({
+      paths: [],
+      refs: { "refs/chant/wip/main": "s1", "refs/chant/replica/origin/chant/wip/main": "s1" },
+    });
+    expect(reportedWrites("wip restore", { ref: "refs/chant/wip/main", checkpoint: { snapshot: { commit: "s2" } }, paths: ["a.txt"] })).toEqual({ paths: ["a.txt"], refs: { "refs/chant/wip/main": "s2" } });
+    expect(reportedWrites("box listing set", { paths: ["app/listing/cover.png", "chant.workspace.json"], declaration: { path: "chant.workspace.json" } })).toEqual({ paths: ["app/listing/cover.png", "chant.workspace.json"], refs: {} });
+    const before = { "refs/heads/chant/lifecycle": "c1", HEAD: "m 1" };
+    expect(unreportedChanges(claim, doc, { before: {}, after: {} }, { before, after: { ...before, "refs/heads/chant/lifecycle": "c2", "refs/chant/lease/work/W-001": "b" } })).toEqual([]);
+    expect(unreportedChanges(claim, doc, { before: {}, after: {} }, { before, after: { ...before, "refs/heads/chant/lifecycle": "c3" } })[0]).toMatch(/git refs changed that chant did not report writing: refs\/heads\/chant\/lifecycle/);
+    const start = { id: "run-start", action: "runs start", params: { run: {} }, args: ["--from", "-"], input: "{}" } as WriteStep;
+    expect(unreportedChanges(start, { ledger: { commit: "c2" } }, { before: {}, after: {} }, { before, after: { ...before, "refs/heads/chant/lifecycle": "c2" } })).toEqual([]);
+  });
+});
+
+describe("state and reads (#3159)", () => {
+  test("undeclaredState: everything in the state directory is declared, as one of ws-074's four", () => {
+    expect(undeclaredState(["hud/events.db", "hud/events.db-wal"], [{ path: "hud", is: "cache" }])).toEqual([]);
+    expect(undeclaredState(["events.db", "notes.json"], [{ path: "events.db", is: ["cache", "telemetry"] }])).toEqual([
+      "state: the writer keeps notes.json in its state directory, and privateState does not declare it",
+    ]);
+    expect(undeclaredState([], [{ path: "db", is: "database" as never }])[0]).toMatch(/private state is cache, telemetry, secret, runtime/);
+  });
+
+  test("isReadCall: the read contract, never a write verb", () => {
+    for (const argv of [["workspace", "wip", "--json"], ["workspace", "records", "--kind", "k", "--json"], ["workspace", "records", "--uncommitted", "--json"], ["workspace", "runs", "--json"], ["workspace", "points", "--open", "--json"], ["workspace", "work", "history", "W-001"], ["workspace", "ls", "--json"]]) {
+      expect(isReadCall(argv), argv.join(" ")).toBe(true);
+    }
+    for (const argv of [["workspace", "wip", "save"], ["workspace", "wip", "restore"], ["workspace", "wip", "push"], ["workspace", "wip", "fetch"], ["workspace", "records", "new"], ["workspace", "runs", "start"], ["workspace", "points", "answer"], ["workspace", "points", "retract"], ["workspace", "work", "claim"], ["workspace", "work", "evidence"], ["build"]]) {
+      expect(isReadCall(argv), argv.join(" ")).toBe(false);
+    }
+  });
+});
+
+describe("the writer fixture (#3159)", () => {
+  test("its kinds, schemas and decision points are the reference workspace's", () => {
+    const same: [string, string][] = [
+      ["work/work.kind.mjs", "work/work.kind.mjs"],
+      ["work/work.schema.json", "work/work.schema.json"],
+      ["answers/answer.kind.mjs", "answers/answer.kind.mjs"],
+      ["answers/answer.schema.json", "answers/answer.schema.json"],
+      ["decisions/points.json", "decisions/points.json"],
+      ["sessions/session.schema.json", "design/sessions/session.schema.json"],
+      // The session kind's other subject kinds (#3148).
+      ["contracts/contract.kind.mjs", "design/contracts/contract.kind.mjs"],
+      ["contracts/contract.schema.json", "design/contracts/contract.schema.json"],
+      ["drivers/driver.kind.mjs", "design/drivers/driver.kind.mjs"],
+      ["drivers/driver.schema.json", "design/drivers/driver.schema.json"],
+    ];
+    for (const [ours, theirs] of same) expect(readFileSync(join(WRITER_FIXTURE_DIR, ours), "utf-8"), ours).toBe(readFileSync(join(repoRoot, "reference-workspace", theirs), "utf-8"));
+    // The session kind sits one directory higher here than in the reference
+    // workspace's design member, so its subjects path is one level shorter.
+    const session = readFileSync(join(repoRoot, "reference-workspace", "design", "sessions", "session.kind.mjs"), "utf-8").replace('"../../decisions/decision.kind.mjs"', '"../decisions/decision.kind.mjs"');
+    expect(readFileSync(join(WRITER_FIXTURE_DIR, "sessions", "session.kind.mjs"), "utf-8")).toBe(session);
+  });
+});