@intentius/tsad-conformance 1.4.0

package/spec/rules.md

@@ -0,0 +1,102 @@
+# Rules over values
+
+Normative. The contract a semantic check runs under. It names the input a
+check sees and when it runs, what a check may do and what it reports, and
+who supplies it. The identifiers are `F-Rule-*` (#79). This is neither a
+language for writing checks nor any particular check; those are host
+vocabulary, a lexicon's or a governance tool's. What is specified is the
+guarantee the fold provides and nothing else does. A check sees the values
+of every file in the build before anything is emitted, so the check at the
+keystroke is the check in CI, over real data and across resources.
+
+Derived from chant's post-synthesis engine (`packages/core/src/lint/post-synth.ts`),
+its policy layer (`lint/policy.ts`), and its severity configuration
+(`lint/config.ts`), at `chant-v0.71.0`. chant's declarative `rule({…})`
+format matches AST nodes and is the classifier's territory (grammar.md);
+it is not a rule over values and is not covered here.
+
+## F-Rule-Input (what a rule sees)
+
+A check receives one or both of two inputs and nothing else about the
+build. The first is the folded namespace, every file's `X(f)` after J2 and
+J3 have disposed of every verdict, as final values; in chant this is
+`PostSynthContext.entities`, every declared entity by name (L11.1). The
+second is the artifact, the serializer's output as text and the same output
+parsed once per build into documents (rows `L11.2` and `L11.3`). The name of the
+environment or stack being built may be supplied as well, which is what
+lets an organisational policy vary by environment (L11.4).
+
+## F-Rule-Phase (when a rule runs)
+
+Checks run after every verdict is final and before anything is applied. A check over the folded namespace is **pre-synthesis**; a check over the
+artifact is **post-synthesis**. One hook may serve both, as chant's
+does: the phase is named by the input the rule reads, not by a separate
+entry point.
+
+## F-Rule-Pure (what a rule may do)
+
+A check is a function of its input. No execution of project code, no
+environment read beyond the name F-Rule-Input supplies, no network,
+deterministic across runs. This is F-Host-Admission's third clause applied
+to rules, and it is what lets a check run in an editor. Under
+`ι = isolated`, a check the project supplies is itself project code and runs
+where the fallback runs, never in the evaluator's own process (L11.7).
+
+## F-Rule-Finding (what a rule reports)
+
+A finding carries the rule's identifier, a severity from a closed set
+(`error`, `warning`, `info`), a message, and a **subject**: the name of the
+entity in the namespace or artifact it concerns, or the statement that
+something is missing when there is nothing to attach it to (L11.5). The
+message is not normative (F-Obs-Messages). A source location is part of a
+finding when the implementation has value provenance (F-Obs-Provenance);
+it is not required, because chant's findings name the artifact's entity and
+not a line, and a rule that reaches through the artifact has no line to
+name. A configured severity may override the rule's own (L11.6).
+
+## F-Rule-Equivalence (the guarantee)
+
+For conforming source, a rule's findings are the same whether the build
+folded the file or ran it. This follows from the objective (judgments.md)
+and from F-Rule-Pure: the inputs are equal on both paths and the rule is a
+function of them. It is what "the check at the keystroke is the check in
+CI" means, stated as a property.
+
+## F-Rule-Supply (who supplies a rule)
+
+Rules come from the host, as part of a lexicon (F-Host-Interface item 7),
+or from the project, as a policy the build loads by path. A supplied rule is
+identified by its identifier; two suppliers may not claim one (L11.8). The
+profile decides the language: in `data-host` a rule is code in the
+evaluator's own language, since there is no JavaScript to run.
+
+---
+
+## Rationale
+
+Non-normative, as in the other rule files: the reasoning behind each rule, keyed by the rules it supports.
+
+**F-Rule-Input, F-Rule-Phase.** The fold's user-facing consequence, and the
+one the paper had not stated: a syntax linter sees tokens and a
+configuration language with constraints in the type sees one field; neither
+has the values of every file in the build. chant's post-synthesis checks
+read `ctx.entities` for the values and `ctx.outputs` or `ctx.docs` for the
+artifact, from one hook, which is why the phase is named by the input.
+
+**F-Rule-Finding.** The subject is an artifact-side name on purpose. chant's
+own comment says a finding names an identifier from the synthesized output
+such as a CloudFormation logical id and never a source line, and it carries
+a missing-resource form for the case where nothing exists to attach to
+(chant#2113, Snyk's policy-engine archetype).
+Requiring a source line would require value provenance everywhere, which
+`F-Obs-Provenance` deliberately leaves optional.
+
+**F-Rule-Pure, F-Rule-Supply.** A project policy is project code. chant
+refuses to load one into its own process while the sandbox is armed and
+runs it in the child instead (chant#1131), which is the isolation mode's
+boundary drawn once more around rules.
+
+**Fixtures.** No `F-Rule-*` rule has a fixture yet: the harness has no hook
+that runs a rule and no fixture kind whose expectation is a finding. That
+work is #101; until it lands the family is listed in `fixtures/UNCOVERED.md`
+with that reason.

package/spec/values.md

@@ -0,0 +1,247 @@
+# The value domain
+
+Normative draft (#39). What a fold produces. Rules are `F-Val-*`: the value
+domain is a property of folding's output, not of syntax, so it takes the
+`F-*` prefix (noted for #46). Derived from `FoldedValue` and its cases
+(`fold.ts:116–300`), `FoldableFunction` (`fold.ts:378`), `carriesLiveObject`
+(`fold.ts:411`), `isFoldSymbolicEnvelope`, and `reviveFoldedValue`
+(`fold-import.ts:2643`), at `e4074c17`.
+
+---
+
+## F-Val-Domain (the closed union)
+
+A folded value `v` is exactly one of:
+
+| Case | Form | Row |
+|---|---|---|
+| scalar | `string` \| `number` \| `boolean` \| `null` \| `undefined` | L4.1 |
+| array | `v[]` | L4.1 |
+| object | `{ [k: string]: v }` with prototype `Object` | L4.1 |
+| attribute reference | `{ __attrRef: { entity, attribute } }` | L3.9 |
+| intrinsic, tag form | `{ __intrinsic, strings: string[], values: v[] }` | L6.3 |
+| intrinsic, call form | `{ __intrinsic, args: v[] }` | L6.3 |
+| helper call | `{ __helper, args: v[] }` | L6.4 |
+| resource | `{ __resource, props, attributes?, args? }` | L6.6 |
+| composite step | `{ __compositeStep, args: v[] }` | L6.5 |
+| symbol | `{ __symbol: string }` | L6.2 |
+
+Nothing else. In particular no function is a `v` (F-Val-Callable), and no
+live instance is a `v`, a live instance is what an envelope becomes
+(F-Val-Live).
+
+## F-Val-Envelope (six envelopes, recognised by key)
+
+A value is an *envelope* iff it is a non-array object carrying one of the keys
+`__attrRef`, `__intrinsic`, `__helper`, `__resource`, `__compositeStep`,
+`__symbol` (`isFoldSymbolicEnvelope`). An envelope is a finished value that
+*denotes* something not yet constructed (R1.1); it is never a thunk, and an
+implementation must not attempt to force it.
+
+## F-Val-Fate (what happens to each envelope)
+
+Revival (R7.1, `reviveFoldedValue`) walks a folded tree and replaces
+envelopes:
+
+| Envelope | Fate |
+|---|---|
+| `__attrRef` | **passes through unchanged** — the serializer accepts the plain envelope (L6.7) |
+| `__intrinsic` (both forms) | revived: the intrinsic function the file's import names is invoked — `Name(strings, ...values)` or `Name(...args)` (L6.3) |
+| `__helper` | revived: the helper the file's import names is invoked with the revived args (L6.4) |
+| `__resource` | revived: the class the file's import names is constructed — from `props`/`attributes`, or by spreading `args` when present (L6.6, F-Val-Arity) |
+| `__compositeStep` | revived: the composite is resolved (J2 F-Call), then `.step` is read off the real result (L6.5) |
+| `__symbol` | revived: the text must match a simple dotted chain; its root resolves through the file's imports and the rest is real property access (L6.2) |
+
+In the `data-host` profile (F-Profile-DataHost, judgments.md) none of these
+fates runs: revival is serialization, every envelope is the output, and the
+host's serialization mapping is what turns it into the artifact.
+
+**Exactly one envelope survives to serialization: `__attrRef`.** The other
+five must never reach a serializer (R1.2). An implementation that emits a
+`__resource` envelope has produced wrong output, not a placeholder.
+
+## F-Val-Position (validity is position-dependent)
+
+Revival carries a flag `requireLiveRefs`. It is **true** inside the
+arguments of an `__intrinsic` or `__helper`, the receiving function inspects
+what it is given (`instanceof`, `WeakRef` derefs), and there a `__attrRef`
+envelope is **rejected**, not passed (L6.8): a look-alike plain object would
+produce wrong output rather than absent output. It is **false** for the
+arguments of a `__compositeStep` and for a top-level resource's props (L6.9):
+a composite stores its props rather than inspecting them, and the serializer
+resolves the envelope by name.
+
+So the same `v` is valid in one position and a rejection in another. A
+specification of the domain alone does not capture this; the rule is part of
+the domain.
+
+## F-Val-Live (liveness)
+
+A value *carries a live object* iff it, or anything reachable through plain
+objects and arrays, has a prototype other than `Object`, `Array`, or `null`
+- or is a function (`carriesLiveObject`; R1.4, L4.5). Live objects reached
+through cross-file resolution, an `AttrRef` instance, a `Declarable`, a
+`CompositeInstance`, an `Intrinsic` instance, **pass through revival
+unchanged** (L6.1): the generic walk would rebuild a plain copy and destroy
+the identity J3 exists to preserve. `isIntrinsic` is keyed on a global
+`Symbol.for`, so this holds across separately loaded copies of the core.
+
+Liveness is the *entity test* of F-Identity (J3), and is what F-CallLeak
+tests. F-Capture and F-Import test something broader; F-Identity says which
+is normative and what the difference costs.
+
+## F-Val-Callable (functions are callable, never values)
+
+`FoldableFunction` (R1.3) is a marker for a project-local function J1 may
+*call*. It is **not** a `v`, never appears inside a folded tree, and is
+refused anywhere a value is required: `{ resolver: φ }` does not fold though
+`φ(x)` does (L3.1, L4.4). An eagerly-evaluated lexicon function referenced
+without calling it is refused likewise, with "call it instead" (L3.17).
+
+## F-Val-Serializable (the sub-domain that may reach output)
+
+A value may reach a serializer iff it is: a scalar; an array or object all of
+whose members may; an `__attrRef` envelope; or a live instance produced by
+revival. Every other envelope, and every callable, may not. The objective's
+"byte-identical serialized output" is stated over this sub-domain.
+
+## F-Val-Arity (a resource's constructor arguments)
+
+`__resource.props` is the first object-literal argument. When the argument
+list is not `(props)` or `(props, attributes)`, e.g. `new Parameter("String",
+{…})`, `args` is present and **authoritative**: the entity is constructed by
+spreading it, and `props` is reported for readers but never re-passed (L4.2,
+R10.8, R1.5).
+
+## F-Val-Undefined (`undefined` in the domain)
+
+`undefined` is a scalar of the domain (L4.3). A property whose value is
+`undefined` is **present** in the folded namespace, with that value, and a
+spread copies it like any other own entry; the namespace therefore keeps the
+distinction between an absent key and an `undefined` one, which a consumer
+whose contract is selective-by-omission depends on (#82). Emission is where
+the key is dropped, and an `undefined` array element becomes `null` there,
+for both JSON and YAML, because YAML is round-tripped through the JSON
+emitter (R10.7). For a lexicon that serializes YAML itself, the rule is that
+serializer's own.
+
+## F-Val-Symbol-Scope (where `__symbol` may appear)
+
+Only inside an intrinsic's interior, a tag's interpolations or a call form's
+arguments (`foldIntrinsicValue`). Anywhere else an unresolved chain is a
+located rejection (F-Reference, J2). A `__symbol` therefore never appears at
+the top of a folded tree.
+
+---
+
+## Rationale
+
+Non-normative. The reasoning that motivated each rule, carried over from the retired `requirements.md` (#46). Keyed by the rule(s) each note supports.
+
+**F-Val-Domain** *(was R1. The value domain is closed, and its symbolic cases are finished values)*
+
+The spec must define what a fold produces. Every other requirement quantifies
+over it, and it is currently defined only by a TypeScript union
+(`FoldedValue`, `fold.ts:116`; L4.1).
+
+Nine cases. Six are ordinary JSON, string, number, boolean, null, undefined,
+arrays and plain objects. The rest carry envelopes:
+
+| Case | Envelope key | Denotes | Fate (R1.2) |
+|---|---|---|---|
+| `AttrRefValue` | `__attrRef` | an attribute of another entity, resolved at apply | survives |
+| `FoldedIntrinsicTag` | `__intrinsic` | registered intrinsic, tagged-template form | revived |
+| `FoldedIntrinsicCall` | `__intrinsic` | registered intrinsic, call form | revived |
+| `FoldedHelperCall` | `__helper` | registered authoring helper call | revived |
+| `FoldedResource` | `__resource` | a construction, top-level or nested as a value | revived |
+| `FoldedCompositeStepCall` | `__compositeStep` | `<Identifier>(...).step`, member fixed | revived |
+| `SymbolicValue` | `__symbol` | source text preserved inside an intrinsic interior | revived |
+
+**F-Val-Envelope** *(was R1.1. Symbolic is not unevaluated)*
+
+An `__attrRef` is not a thunk. It is the envelope `AttrRef.prototype.toJSON()`
+produces at runtime, and the serializer accepts it without a live instance. A
+specification that describes these as "unevaluated" invites an implementation
+that tries to force them, which is precisely wrong: the denoted value does not
+exist at build time in either path.
+
+**F-Val-Fate, F-Val-Position** *(was R1.2. Exactly one envelope survives to serialization, and its validity is position-dependent)*
+
+This corrects the first revision, which had it backwards.
+
+`reviveFoldedValue` (L6.1–L6.9) resolves every envelope *except* `__attrRef`
+through the folding file's own imports and invokes the real function or
+constructor: `__intrinsic` in both forms (L6.3), `__helper` (L6.4),
+`__compositeStep` (L6.5), `__resource` (L6.6), `__symbol` via a dotted-chain
+regex (L6.2). None of those may reach a serializer.
+
+`__attrRef` passes through unrevived (L6.7), **except** inside an intrinsic's
+or authoring helper's arguments, where it is rejected (L6.8, `requireLiveRefs`)
+because the receiver performs `instanceof` checks and `WeakRef` derefs and a
+look-alike plain object would produce wrong output rather than absent output.
+Composite-step arguments revive with `requireLiveRefs: false` because a
+composite stores its props rather than inspecting them (L6.9).
+
+So the spec must say: the same value is valid in one position and invalid in
+another, and which positions are which. A domain definition alone does not
+capture this.
+
+**F-Val-Callable** *(was R1.3. Callables are in the domain but are not values)*
+
+`FoldableFunction` (L4.4) lets a call to a project-local function fold, and is
+explicitly *not* a `FoldedValue`: it never appears inside a folded tree. A
+function used as a value is refused (L3.1), a `FoldableFunction` reached as a
+bare identifier is refused, and an eagerly-evaluated lexicon function
+referenced without calling it is refused with "call it instead" (L3.17).
+
+The specification must therefore define a **serializable sub-domain** and say
+which positions require it.
+
+**F-Val-Live** *(was R1.4. Liveness is observable and the spec must say so)*
+
+`carriesLiveObject` (L4.5) distinguishes folded data from a live instance by
+prototype, anything other than `Object`/`Array`/`null`, and additionally
+treats `typeof value === "function"` as live. That predicate is what makes the
+identity rules in R4 and R5 statable: without a definition of "this value is a
+live entity rather than plain data," there is nothing for identity to be a
+property of.
+
+**F-Val-Arity** *(was R1.5. Constructor arity is contractual)*
+
+`FoldedResource.args` (L4.2) is present when the argument list is not the
+classic `(props)` / `(props, attributes)` shape, and is then authoritative:
+the entity is constructed by spreading it. `props` is a view. The
+`undefined` case in the union (L4.3) has no rule today. Both are #42's.
+
+---
+
+**F-Val-Fate** *(was R7.1. Envelope, then revive)*
+
+The default for everything R1's table marks *revived*: `fold()` executes
+nothing and records what was named; the bridge resolves the name through the
+folding file's imports and invokes it (R1.2, R2).
+
+**F-Val-Undefined** *(was R10.7, `undefined` is absent, not `null`, in a property; and is `null` in an array)*
+
+The domain admits `undefined` (L4.3). The serializer walker passes it through
+unchanged and keeps the key (`serializer-walker.ts:33`, `:117`); the drop
+happens at emission, and, verified, it happens for both formats because
+YAML is produced by round-tripping the sorted JSON (`build.ts:743–746`), so
+`JSON.stringify` has already removed an `undefined`-valued key and turned an
+`undefined` array element into `null` before any YAML exists. That is what
+makes chant's build-parameters documentation true ("dropped from the output
+in both JSON and YAML rather than shipped as `null`"). Both facts must be
+stated because they are the difference between "absent" and "null", which
+platforms treat differently, and for the six YAML-native lexicons above the
+walker's `undefined` reaches *their* emitter directly, so the rule there is
+each serializer's, not `JSON.stringify`'s.
+
+**F-Val-Arity** *(was R10.8. Constructor arity)*
+
+`FoldedResource.args` (L4.2, R1.5): present when the argument list is not
+`(props)` or `(props, attributes)`, authoritative when present, the entity
+constructed by spreading it; `props` is a view, never re-passed. An
+implementation that assumed the props object is always first would construct
+`new Parameter("String", {...})` wrongly.
+
+---

package/src/adapter.ts

@@ -0,0 +1,52 @@
+/**
+ * The adapter an implementation under test provides. Deliberately narrow so a
+ * foreign implementation (chant, or one in another language behind a shim)
+ * can satisfy it without exposing internals: source in, verdict out.
+ */
+import type { ConformanceHost } from "./host.js";
+
+export type ShapeResult =
+  | { accepted: true }
+  | { accepted: false; rule?: string; line: number; column: number; message: string }
+  | "unavailable";
+export type FoldResult =
+  | { ok: true; value: unknown }
+  | { ok: false; rule?: string; line: number; column: number; message: string };
+/** A whole-build verdict (J2 + J3). `rule` and `reason` are diagnostic; only `kind` is compared. */
+export type ProjectVerdict =
+  | { kind: "fold"; exports: Record<string, unknown> }
+  | { kind: "run"; rule?: string; reason: string };
+export interface ProjectResult {
+  verdicts: Record<string, ProjectVerdict>;
+  /** J2's proposal, before J3 disposed of it. Omitted by an implementation that cannot separate the two phases. */
+  tentative?: Record<string, "fold" | "run">;
+  /** For a file J3 tainted, the file whose taint reached it. */
+  taintedBy?: Record<string, string>;
+}
+
+export interface ConformanceAdapter {
+  readonly name: string;
+  /**
+   * The specification version this implementation declares it implements,
+   * as `spec/VERSION` spells it (`"1.0"`), or `"undeclared"`. Compared, never
+   * assumed: the suite checks the reference's declaration against `VERSION`,
+   * and reports an implementation that declares nothing as such (#18).
+   */
+  readonly specVersion: string;
+  /** S-* verdict on the initializer of `exportName`. "unavailable" if the implementation exposes no shape classifier. */
+  shape(source: string, exportName: string): ShapeResult;
+  /** F-* verdict: fold the initializer of `exportName` to a JSON-comparable value, or a located rejection. */
+  foldExport(source: string, exportName: string): FoldResult;
+  /**
+   * J2 + J3 over a whole build: every file's final verdict. Optional, and
+   * "unavailable" when the implementation cannot answer — no whole-build
+   * entry at all, or a host it has no way to install. Such a fixture is
+   * reported skipped rather than silently passing.
+   *
+   * May be async: a real implementation resolves modules from a filesystem.
+   */
+  foldProject?(
+    files: Map<string, string>,
+    host?: ConformanceHost,
+  ): ProjectResult | "unavailable" | Promise<ProjectResult | "unavailable">;
+}

package/src/adapters/chant.ts

@@ -0,0 +1,125 @@
+/**
+ * #11 — chant as an implementation under test, through its PUBLIC entry only:
+ * `fold`, `collectConsts`, `FoldError`, and — since chant-v0.64.0 (chant#2362)
+ * — `findSubsetViolation` for the shape half. If an older chant is pinned the
+ * adapter reports shape "unavailable" rather than guessing.
+ */
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
+import * as ts from "typescript";
+import * as chant from "@intentius/chant";
+import type { ConformanceAdapter, ProjectResult, ProjectVerdict } from "../adapter.js";
+
+function exportInitializer(sf: ts.SourceFile, name: string): ts.Expression | undefined {
+  for (const st of sf.statements) {
+    if (name === "default" && ts.isExportAssignment(st) && !st.isExportEquals) return st.expression;
+    if (!ts.isVariableStatement(st) || !st.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) continue;
+    for (const d of st.declarationList.declarations) if (ts.isIdentifier(d.name) && d.name.text === name) return d.initializer;
+  }
+  return undefined;
+}
+const parse = (src: string) => ts.createSourceFile("fixture.ts", src, ts.ScriptTarget.Latest, true);
+function chantVersion(): string {
+  const declared = (chant as unknown as { VERSION?: string }).VERSION;
+  if (typeof declared === "string") return declared;
+  // The package does not export its own manifest, so walk up from the resolved
+  // entry to the nearest one.
+  let dir = dirname(createRequire(import.meta.url).resolve("@intentius/chant"));
+  for (;;) {
+    const candidate = join(dir, "package.json");
+    if (existsSync(candidate)) {
+      const version = (JSON.parse(readFileSync(candidate, "utf8")) as { version?: string }).version;
+      if (typeof version === "string") return version;
+    }
+    const up = dirname(dir);
+    if (up === dir) throw new Error("cannot determine the pinned chant version");
+    dir = up;
+  }
+}
+
+const shapeFn = (chant as unknown as { findSubsetViolation?: (n: ts.Node) => { node: ts.Node; ruleId: string; message: string } | undefined }).findSubsetViolation;
+
+/**
+ * The whole-build entry, chant-v0.70.1+ (chant#2408). Absent on an older pin,
+ * in which case the project fixtures report "unavailable" rather than passing
+ * vacuously.
+ */
+type ChantVerdict = {
+  verdict: "fold" | "run";
+  tentative: "fold" | "run";
+  reason?: string;
+  taintedBy?: { from: string; kind: "importer" | "capture" };
+  exports?: ReadonlyMap<string, unknown>;
+};
+const projectFn = (
+  chant as unknown as {
+    foldProject?: (files: readonly string[], intrinsics?: readonly unknown[]) => Promise<Map<string, ChantVerdict>>;
+  }
+).foldProject;
+
+/** chant resolves modules from disk, so a fixture's sources are written out and the paths handed over. */
+async function foldOnDisk(files: Map<string, string>): Promise<ProjectResult> {
+  const root = mkdtempSync(join(tmpdir(), "tsad-conformance-"));
+  try {
+    const paths: string[] = [];
+    for (const [rel, source] of files) {
+      const abs = join(root, rel);
+      mkdirSync(dirname(abs), { recursive: true });
+      writeFileSync(abs, source, "utf8");
+      paths.push(abs);
+    }
+    const verdicts = await projectFn!(paths, []);
+    const out: ProjectResult = { verdicts: {}, tentative: {}, taintedBy: {} };
+    const relOf = (abs: string) => abs.slice(root.length + 1).split(/[\\/]/).join("/");
+    for (const [abs, v] of verdicts) {
+      const key = relOf(abs);
+      out.verdicts[key] =
+        v.verdict === "fold"
+          ? ({ kind: "fold", exports: Object.fromEntries(v.exports ?? new Map()) } as ProjectVerdict)
+          : ({ kind: "run", reason: v.reason ?? "tainted" } as ProjectVerdict);
+      out.tentative![key] = v.tentative;
+      if (v.taintedBy) out.taintedBy![key] = relOf(v.taintedBy.from);
+    }
+    return out;
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+export const chantAdapter: ConformanceAdapter = {
+  // Read from the installed package, never a literal: a hardcoded fallback
+  // silently misreports the pin, and this name is what the paper's measurement
+  // table cites.
+  name: `chant@${chantVersion()}`,
+  // chant declares the specification version it implements in its own tree
+  // once it does so at all; a pin that exports none is reported as undeclared
+  // rather than assumed current (#18).
+  specVersion: (chant as unknown as { SPEC_VERSION?: string }).SPEC_VERSION ?? "undeclared",
+  shape(source, exportName) {
+    if (!shapeFn) return "unavailable";
+    const sf = parse(source); const init = exportInitializer(sf, exportName);
+    if (!init) return { accepted: false, line: 1, column: 1, message: `no export named ${exportName}` };
+    const v = shapeFn(init); if (!v) return { accepted: true };
+    const { line, character } = sf.getLineAndCharacterOfPosition(v.node.getStart());
+    return { accepted: false, rule: v.ruleId, line: line + 1, column: character + 1, message: v.message };
+  },
+  async foldProject(files, host) {
+    if (!projectFn) return "unavailable";
+    // A named host's entity classes come from a package chant cannot resolve,
+    // and its entry takes an intrinsic registry rather than a whole host, so a
+    // host-dependent fixture is not answerable here.
+    if (host) return "unavailable";
+    return foldOnDisk(files);
+  },
+  foldExport(source, exportName) {
+    const sf = parse(source); const init = exportInitializer(sf, exportName);
+    if (!init) return { ok: false, line: 1, column: 1, message: `no export named ${exportName}` };
+    try { return { ok: true, value: chant.fold(init, chant.collectConsts(sf), [], undefined) }; }
+    catch (e) {
+      if (e instanceof chant.FoldError) return { ok: false, rule: e.ruleId, line: e.line, column: e.column, message: e.message };
+      throw e;
+    }
+  },
+};

package/src/bundled.ts

@@ -0,0 +1,27 @@
+/**
+ * Where the published package keeps the fixtures. `spec/fixtures/` is copied
+ * in at build time (see `package.json`'s build script), so an implementation
+ * that installed this package from npm has the same fixtures the repository
+ * gates on, at the version the package declares.
+ */
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** The bundled rule files and `VERSION`, or the repository's own `spec/` when running from source. */
+export function bundledSpecDir(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  for (const candidate of [join(here, "..", "spec"), join(here, "..", "..", "..", "spec")]) {
+    if (existsSync(join(candidate, "VERSION"))) return candidate;
+  }
+  throw new Error("no spec directory: the package was built without one, and this is not the repository");
+}
+
+/** The bundled fixtures directory, or the repository's own when running from source. */
+export function bundledFixturesDir(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  for (const candidate of [join(here, "..", "fixtures"), join(here, "..", "..", "..", "spec", "fixtures")]) {
+    if (existsSync(join(candidate, "UNCOVERED.md"))) return candidate;
+  }
+  throw new Error("no fixtures directory: the package was built without one, and this is not the repository");
+}

package/src/chant-agreement.test.ts

@@ -0,0 +1,67 @@
+/** #11 — chant must pass the fixtures, and must agree with the reference implementation on every one. */
+import { describe, test, expect } from "vitest";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadFixtures, runFixtures, runProjectFixture, compareAdapters, expressionFixtures, projectFixtures } from "./index";
+import { chantAdapter } from "./adapters/chant";
+import { referenceAdapter } from "@intentius/tsad-reference";
+
+// chant implements the full profile; a fixture tagged for data-host only
+// (S-ExportDefault, which full keeps under S-Disqualify until chant admits it)
+// is not chant's to answer.
+const all = loadFixtures(join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "spec", "fixtures")).filter((f) => f.profiles.includes("full"));
+// chant's classifier rejects every project-local call the build folds
+// (chant#2435), the direction F-Direction forbids; spec 1.2's S-CallLocal
+// names the form. Fixtures citing it are held out of the shape comparison,
+// and only that: their fold half is still compared below.
+const knownShapeDivergence = new Set(["S-CallLocal"]);
+const heldOut = all.filter((f) => f.rules.some((r) => knownShapeDivergence.has(r)));
+const fixtures = all.filter((f) => !heldOut.includes(f));
+
+describe("chant cross-check (#11)", () => {
+  test("chant passes every fixture through its public fold API", async () => {
+    const failed = (await runFixtures(chantAdapter, fixtures)).filter((r) => !r.pass).map((r) => `${r.fixture}: ${r.failures.join("; ")}`);
+    expect(failed, failed.join("\n")).toEqual([]);
+  });
+  test("chant and the reference implementation agree on every fixture", async () => {
+    const dis = await compareAdapters(referenceAdapter, chantAdapter, fixtures);
+    expect(dis, dis.join("\n")).toEqual([]);
+  });
+  test("the whole-build fixtures reach chant, or say why not (#62)", async () => {
+    // Two reasons a project fixture can be skipped, and both must be visible.
+    // An older pin has no whole-build entry at all (chant#2408); a fixture
+    // naming a host asks for entity classes from a package chant cannot
+    // resolve. Anything else has to be answered.
+    const projects = projectFixtures(fixtures);
+    expect(projects.length).toBeGreaterThan(0);
+    const reports = await Promise.all(projects.map((f) => runProjectFixture(chantAdapter, f)));
+    const skipped = reports.filter((r) => r.skipped).map((r) => r.fixture);
+    const hosted = new Set(projects.filter((f) => f.host).map((f) => f.id));
+    const unexpected = skipped.filter((id) => !hosted.has(id));
+    expect(unexpected, `skipped without a host to explain it:\n${unexpected.join("\n")}`).toEqual([]);
+    // The pin carries the entry, so "unavailable" everywhere would mean the
+    // comparison silently stopped happening. Asserted, not assumed.
+    expect(skipped.length, "every hostless whole-build fixture must reach chant").toBeLessThan(projects.length);
+  });
+
+  test("chant and the reference agree on every whole-build fixture chant can answer (#62)", async () => {
+    const dis = await compareAdapters(referenceAdapter, chantAdapter, projectFixtures(fixtures));
+    expect(dis, dis.join("\n")).toEqual([]);
+  });
+  test("the held-out fixtures still agree on the fold half, and the hold-out is not empty (chant#2435)", () => {
+    expect(heldOut.length).toBeGreaterThan(0);
+    for (const f of expressionFixtures(heldOut)) {
+      const a = referenceAdapter.foldExport(f.input, f.exportName), b = chantAdapter.foldExport(f.input, f.exportName);
+      expect(a.ok, `${f.id}: reference ${a.ok ? "folds" : "runs"}, chant ${b.ok ? "folds" : "runs"}`).toBe(b.ok);
+    }
+  });
+  test("chant's shape classifier is available (chant-v0.64.0+, chant#2362) and agrees on every fixture", async () => {
+    // The pinned chant carries the export, so "unavailable" would mean the adapter
+    // silently stopped comparing the shape half — a real regression, asserted.
+    for (const f of expressionFixtures(fixtures)) {
+      const s = chantAdapter.shape(f.input, f.exportName);
+      expect(s, `${f.id}: chant shape classifier unavailable`).not.toBe("unavailable");
+      if (s !== "unavailable") expect(s.accepted, `${f.id}: chant shape ${s.accepted ? "accept" : "reject"} ≠ expected ${f.shape}`).toBe(f.shape === "accept");
+    }
+  });
+});