@intentius/chant 0.85.0 → 0.87.0

package/src/workspace/conformance/__fixture__/decisions/decision.schema.json

@@ -0,0 +1,376 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "urn:intentius:chant:decision:1",
+  "title": "Decision file front matter",
+  "description": "The front matter of one decision file in docs/design/decisions/. The format is described in README.md beside this file. Values stay within what YAML and JSON share, so a file can be sealed later (#2524 D4).",
+  "type": "object",
+  "additionalProperties": false,
+  "patternProperties": {
+    "^x-": {}
+  },
+  "required": [
+    "schema",
+    "id",
+    "title",
+    "state",
+    "area",
+    "source",
+    "question",
+    "options",
+    "choice",
+    "rejected",
+    "supersedes",
+    "evidence",
+    "decided_by",
+    "decided_on",
+    "reviews",
+    "constrains"
+  ],
+  "properties": {
+    "schema": {
+      "description": "Format version of this file. Bumped only by a change to this schema.",
+      "const": 1
+    },
+    "id": {
+      "description": "Stable id: a lowercase prefix per epic, a dash and three or more digits. Never reused, never renumbered.",
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]{0,15}-[0-9]{3,}$"
+    },
+    "title": {
+      "description": "Short topic, as the source table names it, without revision markers.",
+      "type": "string",
+      "minLength": 1
+    },
+    "state": {
+      "description": "Lifecycle state, from #2555.",
+      "enum": ["proposed", "decided", "ratified", "superseded", "withdrawn"]
+    },
+    "area": {
+      "description": "The design section the decision belongs to, such as \"D5\". Groups the review queue. Null only in an importer draft.",
+      "type": ["string", "null"]
+    },
+    "source": {
+      "description": "Where the decision was first recorded: a row of an issue's decisions table, or the workspace itself when no issue holds the decision (#2654).",
+      "oneOf": [{ "$ref": "#/definitions/sourceIssue" }, { "$ref": "#/definitions/sourceWorkspace" }]
+    },
+    "question": {
+      "description": "One sentence. Null only in an importer draft.",
+      "type": ["string", "null"]
+    },
+    "options": {
+      "description": "Every option considered, the chosen one included.",
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/definitions/option" }
+    },
+    "choice": {
+      "description": "The chosen option and why. Null in state proposed or withdrawn.",
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["option", "reason"],
+          "properties": {
+            "option": { "$ref": "#/definitions/optionId" },
+            "reason": { "type": ["string", "null"] }
+          }
+        }
+      ]
+    },
+    "rejected": {
+      "description": "The options not chosen, kept on the record.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["option", "why"],
+        "properties": {
+          "option": { "$ref": "#/definitions/optionId" },
+          "why": { "type": ["string", "null"] }
+        }
+      }
+    },
+    "supersedes": {
+      "description": "Earlier choices this decision replaced: another decision file, or an option chosen in an earlier revision of the same design before decision files existed.",
+      "type": "array",
+      "items": {
+        "oneOf": [
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["decision"],
+            "properties": {
+              "decision": { "$ref": "#/definitions/decisionId" }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["revision", "option"],
+            "properties": {
+              "revision": { "type": "string", "pattern": "^v[0-9]+$" },
+              "option": { "$ref": "#/definitions/optionId" }
+            }
+          }
+        ]
+      }
+    },
+    "evidence": {
+      "description": "The research, audits, design sections and workspace files behind the decision. A public link carries a url; a file in the workspace carries a path and the hash of its bytes (#2549). May be empty when the decision cites nothing; chant workspace records then warns decision-no-evidence (#2654).",
+      "type": "array",
+      "items": {
+        "oneOf": [{ "$ref": "#/definitions/evidenceLink" }, { "$ref": "#/definitions/evidencePin" }]
+      }
+    },
+    "decided_by": {
+      "description": "Who chose. A forge login. Null in state proposed or withdrawn.",
+      "type": ["string", "null"]
+    },
+    "decided_on": {
+      "description": "When the choice was made, as YYYY-MM-DD. Quoted, so YAML reads it as a string.",
+      "type": ["string", "null"],
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
+    },
+    "reviews": {
+      "description": "Each reviewer's verdict. Empty until a review happens.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["reviewer", "verdict", "on"],
+        "properties": {
+          "reviewer": { "type": "string", "minLength": 1 },
+          "verdict": { "enum": ["agree", "dissent", "abstain"] },
+          "note": { "type": ["string", "null"] },
+          "on": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+          "digest": {
+            "description": "The digest of the record text the verdict judged: the lowercase hex SHA-256 of the file with LF line endings and without its reviews block (#2672). A verdict whose digest is not the record's digest now stops counting toward the quorum. A verdict without one still counts, with the warning review-undigested.",
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$"
+          },
+          "session": {
+            "description": "The id of the review session the verdict was given in, as the session names it (#2650 C10). chant workspace records review --session writes it (#2670).",
+            "type": "string",
+            "minLength": 1
+          },
+          "seal": {
+            "description": "The reviewer's ssh signature over the verdict (#2687): the bytes <id>\\n<digest>\\n<verdict>\\n<reviewer>\\n<on>, in the ssh-keygen namespace chant-review. chant workspace records review --sign writes it. Once a signers file is active at base, a verdict counts toward the quorum only when its seal verifies for its reviewer against that file. A seal needs a digest.",
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["signer", "key", "signature"],
+            "properties": {
+              "signer": { "description": "Who signed: the reviewer, as the signers file names them.", "type": "string", "minLength": 1 },
+              "key": { "description": "The signing key's fingerprint. Reported, never trusted: the signature is the proof.", "type": "string", "pattern": "^SHA256:[A-Za-z0-9+/]+=*$" },
+              "signature": { "description": "The armored ssh signature, as ssh-keygen -Y sign prints it.", "type": "string", "pattern": "^-----BEGIN SSH SIGNATURE-----\\n" }
+            }
+          },
+          "proposes": {
+            "description": "With a dissent, the id of a new proposed decision the reviewer opened.",
+            "$ref": "#/definitions/decisionId"
+          },
+          "addressed_by": {
+            "description": "With a dissent, where the decider or the group answered the concern: a decision id, an issue or pull request (owner/repo#n) or an https link. An answer addresses a concern without necessarily accommodating it (RFC 7282, section 3).",
+            "anyOf": [
+              { "$ref": "#/definitions/decisionId" },
+              { "$ref": "#/definitions/issueRef" },
+              { "type": "string", "pattern": "^https://" }
+            ]
+          },
+          "withdrawn_on": {
+            "description": "With a dissent, the date its author withdrew the concern. Only the reviewer who raised a concern withdraws it.",
+            "type": "string",
+            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
+          }
+        },
+        "dependencies": { "seal": ["digest"] },
+        "if": {
+          "required": ["verdict"],
+          "properties": { "verdict": { "const": "dissent" } }
+        },
+        "then": {
+          "description": "A dissent needs a reason: the dissent by {reviewer} has no note.",
+          "required": ["note"],
+          "properties": { "note": { "type": "string", "pattern": "\\S" } }
+        },
+        "else": {
+          "description": "Only a dissent is a concern: the {verdict} by {reviewer} cannot carry addressed_by or withdrawn_on.",
+          "properties": { "addressed_by": false, "withdrawn_on": false }
+        }
+      }
+    },
+    "constrains": {
+      "description": "What this decision governs: issues (owner/repo#n), other decisions (their ids), workspace members (member:<name>) or files and directories in the workspace (path:<path>, the grammar of an evidence path, #2549). At least one entry: a decision that governs nothing is refused.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "pattern": "^([A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+#[0-9]+|[a-z][a-z0-9]{0,15}-[0-9]{3,}|member:[a-z0-9][a-z0-9-]{0,39}|path:(?!/)(?!(?:[^/]*/)*\\.{1,2}(?:/|$))(?!.*//)[^\\\\\\u0000-\\u001f]*[^/\\\\\\u0000-\\u001f])$"
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "state": { "enum": ["decided", "ratified", "superseded"] } }
+      },
+      "then": {
+        "properties": {
+          "area": { "type": "string" },
+          "question": { "type": "string", "minLength": 1 },
+          "choice": {
+            "type": "object",
+            "properties": { "reason": { "type": "string", "minLength": 1 } }
+          },
+          "rejected": {
+            "items": { "properties": { "why": { "type": "string", "minLength": 1 } } }
+          },
+          "options": {
+            "items": {
+              "properties": {
+                "how": { "type": "string", "minLength": 1 },
+                "tradeoff": { "type": "string", "minLength": 1 }
+              }
+            }
+          },
+          "decided_by": { "type": "string" },
+          "decided_on": { "type": "string" }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": { "state": { "enum": ["proposed", "withdrawn"] } }
+      },
+      "then": {
+        "properties": { "choice": { "type": "null" } }
+      }
+    }
+  ],
+  "definitions": {
+    "workspacePath": {
+      "description": "A path from the workspace root, with / separators: no leading /, no . or .. segment, no empty segment, no backslash and no trailing /.",
+      "type": "string",
+      "pattern": "^(?!/)(?!(?:[^/]*/)*\\.{1,2}(?:/|$))(?!.*//)[^\\\\\\u0000-\\u001f]*[^/\\\\\\u0000-\\u001f]$"
+    },
+    "evidenceLink": {
+      "description": "A public link.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["title", "url"],
+      "properties": {
+        "title": { "type": "string", "minLength": 1 },
+        "url": { "type": "string", "pattern": "^https://" },
+        "as_of": {
+          "description": "When the linked text was read, as an ISO 8601 timestamp. Lets a reader flag evidence that changed afterwards.",
+          "type": ["string", "null"]
+        },
+        "sha256": {
+          "description": "Hex SHA-256 of the linked content, once evidence is pinned by hash (#2555). Null until then.",
+          "type": ["string", "null"],
+          "pattern": "^[0-9a-f]{64}$"
+        }
+      }
+    },
+    "evidencePin": {
+      "description": "A file in the workspace, pinned by the hash of its bytes (#2524 D18, #2549). chant workspace records reports a file that changed or went missing since.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["title", "path", "sha256"],
+      "properties": {
+        "title": { "type": "string", "minLength": 1 },
+        "path": {
+          "description": "The file, from the workspace root. It sits inside a member, such as design/screens/home.json.",
+          "$ref": "#/definitions/workspacePath"
+        },
+        "sha256": {
+          "description": "Hex SHA-256 of the file's bytes when the decision was written. chant workspace records pin <path> prints it.",
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "as_of": {
+          "description": "When the file was read, as an ISO 8601 timestamp.",
+          "type": ["string", "null"]
+        }
+      }
+    },
+    "sourceIssue": {
+      "description": "A row of the decisions table in an issue.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["issue", "row"],
+      "properties": {
+        "issue": { "$ref": "#/definitions/issueRef" },
+        "row": {
+          "description": "The row's topic cell, verbatim, including any revision marker.",
+          "type": "string"
+        },
+        "revision": {
+          "description": "The design revision that last changed this row, such as \"v8\". Null when the row carries no marker.",
+          "type": ["string", "null"]
+        }
+      }
+    },
+    "sourceWorkspace": {
+      "description": "A decision made in the workspace, such as in a product's own design flow, with no issue behind it (#2654).",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "member"],
+      "properties": {
+        "kind": { "const": "workspace" },
+        "member": {
+          "description": "The workspace member the decision was made in, by its name in the declaration.",
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9-]{0,39}$"
+        },
+        "session": {
+          "description": "The id of the session the decision was made in, as the member names it. Null or absent when there was none.",
+          "type": ["string", "null"],
+          "minLength": 1
+        },
+        "issue": {
+          "description": "An issue the decision relates to, when there is one.",
+          "$ref": "#/definitions/issueRef"
+        }
+      }
+    },
+    "issueRef": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+#[0-9]+$"
+    },
+    "decisionId": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]{0,15}-[0-9]{3,}$"
+    },
+    "optionId": {
+      "type": "string",
+      "pattern": "^[a-z]$"
+    },
+    "option": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "label", "how", "tradeoff"],
+      "properties": {
+        "id": { "$ref": "#/definitions/optionId" },
+        "label": {
+          "description": "The option as the source table words it, without revision markers.",
+          "type": "string",
+          "minLength": 1
+        },
+        "how": {
+          "description": "How the option works.",
+          "type": ["string", "null"]
+        },
+        "tradeoff": {
+          "description": "What choosing it costs or gains.",
+          "type": ["string", "null"]
+        },
+        "chosen_in": {
+          "description": "The earlier design revision that had chosen this option, when a later revision replaced it.",
+          "type": "string",
+          "pattern": "^v[0-9]+$"
+        }
+      }
+    }
+  }
+}

package/src/workspace/conformance/__fixture__/decisions/fix-001-how-the-app-is-deployed.md

@@ -0,0 +1,40 @@
+---
+schema: 1
+id: "fix-001"
+title: "How the app is deployed"
+state: "decided"
+area: "delivery"
+source:
+  kind: "workspace"
+  member: "delivery"
+question: "What declares the app's deployment?"
+options:
+  - id: "a"
+    label: "a chant member with a composite and a component"
+    how: "The delivery member declares the app as a WebService composite instance, and a component whose contract names WebService deploys it."
+    tradeoff: "chant workspace graph --composites has a row to join, and the member needs no package beyond @intentius/chant."
+  - id: "b"
+    label: "no deployment member"
+    how: "The workspace holds the app and its decisions only."
+    tradeoff: "One member fewer, and the composites read has nothing to join."
+choice:
+  option: "a"
+  reason: "A reader of graph --composites is only tested when the join has a row."
+rejected:
+  - option: "b"
+    why: "It leaves graph --composites with an empty join."
+supersedes: []
+evidence:
+  - title: "INTENTIUS/chant#2679, the reader conformance suite outside the chant repo"
+    url: "https://github.com/INTENTIUS/chant/issues/2679"
+decided_by: "lex00"
+decided_on: "2026-09-24"
+reviews: []
+constrains:
+  - "member:app"
+  - "member:delivery"
+---
+
+# How the app is deployed
+
+This workspace is generated by `@intentius/chant/workspace/conformance` for a reader's conformance run. The delivery member declares the app as a composite, and a component deploys it.

package/src/workspace/conformance/__fixture__/delivery/chant.config.ts

@@ -0,0 +1,7 @@
+import type { ChantConfig } from "@intentius/chant";
+
+// The member's one lexicon is declared by path (#2520), so the workspace
+// needs no package beyond @intentius/chant.
+export default {
+  lexicons: [{ name: "fixture", module: "./lexicon/index.ts" }],
+} satisfies ChantConfig;

package/src/workspace/conformance/__fixture__/delivery/lexicon/index.ts

@@ -0,0 +1,26 @@
+/**
+ * A lexicon of one resource and one composite, declared by path in
+ * chant.config.ts, so the reader conformance workspace (#2679) has a
+ * composite instance without installing a lexicon package.
+ */
+import { Composite, createResource } from "@intentius/chant";
+
+export const Service = createResource("Fixture::Service", "fixture", {});
+
+export const WebService = Composite<{ port: number }>((props) => {
+  const service = new Service({ port: props.port });
+  return { service };
+}, "WebService");
+
+export const fixturePlugin = {
+  name: "fixture",
+  serializer: {
+    name: "fixture",
+    rulePrefix: "FIX",
+    serialize: (entities: Map<string, unknown>) => JSON.stringify(Array.from(entities.keys()).sort()),
+  },
+  generate: async () => {},
+  validate: async () => {},
+  coverage: async () => {},
+  package: async () => {},
+};

package/src/workspace/conformance/__fixture__/delivery/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "delivery",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Declares the reader conformance workspace's app as a composite, with the component that deploys it."
+}

package/src/workspace/conformance/__fixture__/delivery/src/app.component.ts

@@ -0,0 +1,14 @@
+/**
+ * The component that deploys the app. Its contract names the composite kind
+ * it deploys, so `chant workspace graph --composites` joins it to the `app`
+ * instance in app.ts.
+ */
+import type { Component } from "@intentius/chant/components/component";
+
+export const appComponent: Component = {
+  name: "app",
+  archetype: "service",
+  composites: ["WebService"],
+  dependsOn: [],
+  deploy: [],
+};

package/src/workspace/conformance/__fixture__/delivery/src/app.ts

@@ -0,0 +1,4 @@
+import { WebService } from "../lexicon/index";
+
+/** The app, as one WebService composite instance. */
+export const app = WebService({ port: 8080 });

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

@@ -0,0 +1,149 @@
+/**
+ * The reader conformance suite as a reader outside the chant repository runs
+ * it (#2679): on the workspace generated from `__fixture__/`, with no
+ * test runner, for a subset of the commands, and from the files the package
+ * ships.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import {
+  checkReaderRead,
+  CONFORMANCE_FIXTURE_DIR,
+  createConformanceWorkspace,
+  READ_CONTRACT_COMMANDS,
+  REFERENCE_READS,
+  runWorkspaceReaderConformance,
+  selectCommands,
+  type ChantRun,
+  type ChantTransport,
+  type ConformanceWorkspace,
+  type ReadContractCommand,
+} from "./index";
+import * as suite from "./index";
+
+const coreRoot = resolve(import.meta.dirname, "..", "..", "..");
+const repoRoot = resolve(coreRoot, "..", "..");
+
+const JSON_FLAG: Record<ReadContractCommand, string[]> = {
+  ls: ["--json"],
+  graph: [],
+  check: ["--format", "json"],
+  status: ["--json"],
+  records: ["--json"],
+  "graph --intent": ["--json"],
+  "graph --composites": ["--json"],
+};
+
+/** The smallest reader that conforms, with a hook to misbehave. */
+function reader(twist: (doc: Record<string, unknown>, chant: ChantTransport) => unknown = (doc) => doc) {
+  return (chant: ChantTransport) => ({
+    async read(command: ReadContractCommand, args: string[]) {
+      const run = await chant.run(["workspace", ...command.split(" "), ...args, ...JSON_FLAG[command]]);
+      return twist(JSON.parse(run.stdout) as Record<string, unknown>, chant);
+    },
+  });
+}
+
+let ws: ConformanceWorkspace;
+beforeAll(() => {
+  ws = createConformanceWorkspace();
+}, 300_000);
+afterAll(() => ws?.dispose());
+
+describe("the generated conformance workspace (#2679)", () => {
+  test("a conforming reader passes every command, graph --composites included, with nothing skipped", async () => {
+    const report = await runWorkspaceReaderConformance(reader(), { workspaceDir: ws.dir });
+    expect(report.problems).toEqual([]);
+    expect(report.checked).toEqual([...READ_CONTRACT_COMMANDS]);
+    expect(report.skipped).toEqual([]);
+  }, 300_000);
+
+  test("graph --composites joins the fixture's composite to its component", async () => {
+    const docs: Record<string, unknown>[] = [];
+    await runWorkspaceReaderConformance(reader((doc) => (docs.push(doc), doc)), { workspaceDir: ws.dir, commands: ["graph --composites"] });
+    expect(docs[0]).toMatchObject({
+      composites: [{ id: "delivery/app", kinds: ["WebService"], components: [{ component: "delivery/app", by: "composites", via: "member" }] }],
+      summary: { composites: 1, withComponent: 1 },
+    });
+  }, 300_000);
+
+  test("the decision record and the region the intent read names are in the workspace", async () => {
+    const docs: Record<string, unknown>[] = [];
+    await runWorkspaceReaderConformance(reader((doc) => (docs.push(doc), doc)), { workspaceDir: ws.dir, commands: ["records", "graph --intent"] });
+    expect((docs[0].records as { id: string }[]).map((r) => r.id)).toEqual(["fix-001"]);
+    expect(docs[1].region).toBe(`region:${REFERENCE_READS["graph --intent"][0]}`);
+  }, 300_000);
+});
+
+describe("commands (#2679)", () => {
+  test("only the listed commands are read, and the report names the rest as skipped", async () => {
+    const read: string[] = [];
+    const report = await runWorkspaceReaderConformance(
+      (chant) => ({ read: (command, args) => (read.push(command), reader()(chant).read(command, args)) }),
+      { workspaceDir: ws.dir, commands: ["status", "ls", "graph --composites"] },
+    );
+    expect(report.problems).toEqual([]);
+    expect(read).toEqual(["ls", "status", "graph --composites"]);
+    expect(report.checked).toEqual(["ls", "status", "graph --composites"]);
+    expect(report.skipped).toEqual(["graph", "check", "records", "graph --intent"]);
+  }, 300_000);
+
+  test("a name that is not a contract command, or an empty list, is refused", () => {
+    expect(() => selectCommands(["graph --kind" as ReadContractCommand])).toThrow(/not read-contract commands: graph --kind/);
+    expect(() => selectCommands([])).toThrow(/commands is empty/);
+  });
+});
+
+describe("what the runner-neutral suite catches (#2679)", () => {
+  test("a changed document, a reader that throws and a write to the workspace", async () => {
+    const changed = await runWorkspaceReaderConformance(reader((doc) => ({ ...doc, extra: 1 })), { workspaceDir: ws.dir, commands: ["ls"] });
+    expect(changed.problems.join("\n")).toMatch(/ls: the reader must return the document chant printed, unchanged/);
+
+    const thrown = await runWorkspaceReaderConformance(() => ({ read: () => { throw new Error("no chant"); } }), { workspaceDir: ws.dir, commands: ["status"] });
+    expect(thrown.problems).toEqual(["status: the reader threw: no chant"]);
+
+    const wrote = await runWorkspaceReaderConformance(
+      reader((doc) => (writeFileSync(join(ws.dir, "cache.json"), "{}"), doc)),
+      { workspaceDir: ws.dir, commands: ["ls"] },
+    );
+    expect(wrote.problems).toEqual(["workspace: the reads changed files: cache.json (added)"]);
+  }, 300_000);
+
+  test("checkReaderRead: the schema, the $schema id and the contract version", () => {
+    const argv = ["workspace", "ls", "--json"];
+    const doc = { $schema: "https://intentius.io/chant/schemas/workspace/ls/v1/ls.schema.json", contract: 2 };
+    const printed: ChantRun[] = [{ argv, status: 0, stdout: JSON.stringify(doc), stderr: "" }];
+    const problems = checkReaderRead("ls", [], [argv], printed, doc);
+    expect(problems.join("\n")).toMatch(/ls: the document does not validate against ls.schema.json/);
+    expect(problems.join("\n")).toMatch(/ls: contract is 2, expected 1/);
+    expect(checkReaderRead("ls", [], [argv], [{ ...printed[0], stdout: "" }], doc)).toEqual(["ls: chant workspace ls --json printed nothing"]);
+  });
+});
+
+describe("what the package ships (#2679)", () => {
+  const pkg = JSON.parse(readFileSync(join(coreRoot, "package.json"), "utf-8")) as { files: string[]; exports: Record<string, Record<string, string>> };
+
+  test("the fixture and both entries are in the package's files and exports", () => {
+    expect(pkg.files).toContain("src/");
+    for (const key of ["./workspace/conformance", "./workspace/conformance/vitest"]) {
+      const entry = pkg.exports[key];
+      for (const cond of ["development", "default"]) expect(existsSync(join(coreRoot, entry[cond])), `${key} ${cond}`).toBe(true);
+      expect(entry.types).toMatch(/^\.\/dist\/workspace\/conformance\/.+\.d\.ts$/);
+    }
+    expect(CONFORMANCE_FIXTURE_DIR).toBe(join(coreRoot, "src", "workspace", "conformance", "__fixture__"));
+  });
+
+  test("the plain-Node entry re-exports every runtime export of the suite", () => {
+    const text = readFileSync(join(import.meta.dirname, "index.mjs"), "utf-8");
+    const listed = [.../export const \{([^}]+)\}/.exec(text)![1].matchAll(/[A-Za-z_]+/g)].map((m) => m[0]).sort();
+    expect(listed).toEqual(Object.keys(suite).sort());
+  });
+
+  test("the fixture's decision kind and schema are the reference workspace's", () => {
+    for (const f of ["decision.kind.mjs", "decision.schema.json"]) {
+      expect(readFileSync(join(CONFORMANCE_FIXTURE_DIR, "decisions", f), "utf-8"), f).toBe(readFileSync(join(repoRoot, "reference-workspace", "decisions", f), "utf-8"));
+    }
+  });
+});

package/src/workspace/conformance/index.mjs

@@ -0,0 +1,31 @@
+// The entry of `@intentius/chant/workspace/conformance` for plain Node
+// (#2679). The suite is written in TypeScript like the rest of the package,
+// and Node does not strip types under node_modules, so this file loads it
+// through tsx, a dependency of this package. `node --test` runs a reader's
+// test file that imports it with no loader flag. Types come from
+// dist/workspace/conformance/index.d.ts.
+
+import { tsImport } from "tsx/esm/api";
+
+const suite = await tsImport("./index.ts", import.meta.url);
+
+export const {
+  READ_CONTRACT_COMMANDS,
+  READ_CONTRACT_SCHEMAS,
+  READ_CONTRACT_JSON_FLAGS,
+  REFERENCE_READS,
+  CONFORMANCE_FIXTURE_DIR,
+  defaultChantCommand,
+  referenceWorkspaceDir,
+  readContractSchema,
+  treeDigest,
+  treeChanges,
+  readerCallProblems,
+  checkReaderRead,
+  selectCommands,
+  createConformanceWorkspace,
+  conformanceTarget,
+  recordingTransport,
+  readAndCheck,
+  runWorkspaceReaderConformance,
+} = suite;