spec 1.4: rules.md, the contract a semantic check runs under (F-Rule-*) (#79) (#102)

Extracted from chant's post-synthesis engine and policy layer the way the
other files were, with inventory rows L11.1 to L11.8 and item 7 of
F-Host-Interface. A check sees the folded namespace and the artifact, runs
after every verdict is final, is a pure function of its input, reports a
finding whose subject is an artifact-side name (a source location is
optional, as provenance is), and comes from the host or the project.
F-Rule-Equivalence is the objective restated for checks. No fixture yet:
the harness half is #101, and the family sits in UNCOVERED.md with that
reason. Version 1.4, packages 1.4.0.

Also: the prose linter blanks YAML frontmatter before reading a file. The
sentences package leaves the --- block in, so every docs page paid for its
own frontmatter (the delimiters as em dashes, key: value as nameplates);
the docs-prose pass (#100) hit that wall with zero body findings left.
Baseline ratcheted down to match.

Author: lex00

docs/scripts/sync-spec.mjs

@@ -30,7 +30,7 @@ const BOLD_ID = /^\*\*((?:[SF]-[A-Za-z0-9-]+))[.\s]/;
 // listed ahead of its arrival (#18): spec/CHANGELOG.md does not exist yet, and
 // naming it here is inert until it does, because the loop below iterates the
 // directory rather than this list.
-const ORDER = ["README", "grammar", "judgments", "values", "divergence", "hosts", "inventory", "CHANGELOG", "prior-art"];
+const ORDER = ["README", "grammar", "judgments", "values", "divergence", "hosts", "rules", "inventory", "CHANGELOG", "prior-art"];
 
 for (const file of readdirSync(specDir).filter((f) => f.endsWith(".md"))) {
   const name = basename(file, ".md");

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/tsad-conformance",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "The conformance suite of the typescript-as-data specification: fixture loader, runner, and the named hosts. An implementation supplies an adapter and gets a report.",
   "license": "Apache-2.0",
   "repository": {
@@ -28,7 +28,7 @@
     "spec/"
   ],
   "scripts": {
-    "build": "rm -rf dist fixtures spec && tsc -p tsconfig.build.json && cp -R ../../spec/fixtures fixtures && mkdir spec && cp ../../spec/VERSION ../../spec/grammar.md ../../spec/judgments.md ../../spec/values.md ../../spec/divergence.md ../../spec/hosts.md spec/",
+    "build": "rm -rf dist fixtures spec && tsc -p tsconfig.build.json && cp -R ../../spec/fixtures fixtures && mkdir spec && cp ../../spec/VERSION ../../spec/grammar.md ../../spec/judgments.md ../../spec/values.md ../../spec/divergence.md ../../spec/hosts.md ../../spec/rules.md spec/",
     "prepack": "npm run build"
   },
   "dependencies": {}

packages/conformance/package.json

@@ -29,7 +29,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
 /** The five files that define rules, in reading order. The same list `spec/fixtures.test.ts` gates on. */
-export const RULE_FILES = ["grammar.md", "judgments.md", "values.md", "divergence.md", "hosts.md"] as const;
+export const RULE_FILES = ["grammar.md", "judgments.md", "values.md", "divergence.md", "hosts.md", "rules.md"] as const;
 
 export interface Rule {
   readonly id: string;

packages/conformance/src/rules.ts

@@ -71,6 +71,10 @@ chant as F-Import's text says; it now does both (#96). A project-local
 function is excluded at the import, since it is a callable rather than a
 value and F-CallLeak decides its edge at the call.
 
+## No rules, and no provenance
+
+`rules.md` (spec `1.4`) specifies the contract a semantic rule runs under. This package runs none: it has no rule hook, and no value provenance, so a finding it produced could name no source line. Both wait on the harness half (#101).
+
 ## No filesystem, no module resolution algorithm
 
 `foldProject` takes a map of path to source. Specifier resolution joins the

packages/reference/CAVEATS.md

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/tsad-reference",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "The reference implementation of the typescript-as-data specification, written from the specification text and nothing else.",
   "license": "Apache-2.0",
   "repository": {
@@ -31,7 +31,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@intentius/tsad-conformance": "^1.3.0",
+    "@intentius/tsad-conformance": "^1.4.0",
     "typescript": "^5.9.0"
   }
 }

packages/reference/package.json

@@ -21,7 +21,7 @@ function adapterFor(profile: Profile): ConformanceAdapter {
   name: profile === "full" ? "reference" : `reference/${profile}`,
   // Bumped by hand when the rule set this package implements moves; the
   // conformance suite fails when it and spec/VERSION disagree (#18).
-  specVersion: "1.3",
+  specVersion: "1.4",
   shape(source, exportName) {
     const v = shapeOfExport(source, exportName, { ...EMPTY_HOST, profile });
     if (v === "no-such-export") return { accepted: false, line: 1, column: 1, message: `no export named ${exportName}` };

packages/reference/src/adapter.ts

@@ -8,7 +8,7 @@ A file in the subset becomes its artifact by being read. Nothing runs, so the ar
 
 ## Semantic rules over values
 
-A syntax linter sees tokens and can say a key is misspelt. A configuration language with constraints in the type can say a port is out of range. Neither can say that two fields of one resource contradict each other, or that a resource in one file makes a resource in another file incoherent, because neither has the values of every file in the build before anything is emitted. The fold does. A rule that runs over folded values is a pure function of its input, deterministic and free of I/O, which is what lets it run in an editor, and it sees the same data in the editor that it sees in CI, because the data is a function of the source. Two phases follow from this: rules over the declared values before serialization, and rules over the emitted artifact after. chant's lexicons carry the first kind and its post-synth checks the second; a governance tool built on the same evaluator carries both without naming them, in its config loader and in its plan guardrails. The contract those rules run under is not yet in the specification and is stated here as a forward reference (typescript-as-data#79).
+A syntax linter sees tokens and can say a key is misspelt. A configuration language with constraints in the type can say a port is out of range. Neither can say that two fields of one resource contradict each other, and neither can say that a resource in one file makes a resource in another file incoherent. They lack the values of every file in the build before anything is emitted. The fold does. A rule that runs over folded values is a pure function of its input, deterministic and free of I/O, which is what lets it run in an editor, and it sees the same data in the editor that it sees in CI, because the data is a function of the source. Two phases follow from this: rules over the declared values before serialization, and rules over the emitted artifact after. chant's lexicons carry the first kind and its post-synth checks the second; a governance tool built on the same evaluator carries both without naming them, in its config loader and in its plan guardrails. The contract those rules run under is `rules.md` (spec `1.4`). It names the input a check sees and when it runs, what a check may do and what a finding carries, and who supplies it. Fixtures for it wait on a harness hook (typescript-as-data#101).
 
 ## Round-trip generation
 

paper/enables.md

@@ -34,8 +34,8 @@
  "spec/judgments.md": {
   "discourse/punchy-fragments": 45,
   "claude/colon-reveal": 21,
-  "repetition/near-duplicate": 19,
-  "anaphora/repeated-opening": 11,
+  "repetition/near-duplicate": 17,
+  "anaphora/repeated-opening": 10,
   "tricolon/comma-series": 12,
   "tricolon/density": 1
  },

scripts/docs-sentences-baseline.json

@@ -58,6 +58,12 @@ function docFiles(dir) {
   return out.sort();
 }
 
+/** The frontmatter block replaced by spaces, so every offset after it is unchanged. */
+function blankFrontmatter(text) {
+  const m = /^---\r?\n[\s\S]*?\r?\n---[ \t]*(\r?\n|$)/.exec(text);
+  return m ? m[0].replace(/[^\n]/g, " ") + text.slice(m[0].length) : text;
+}
+
 /** 1-based line of a prose-text offset — extractProse blanks non-prose but
  * preserves every offset, so spans map straight onto the source file. */
 function lineOf(text, offset) {
@@ -73,7 +79,11 @@ const detail = [];
 for (const file of files) {
   const rel = relative(join(here, ".."), file);
   const text = readFileSync(file, "utf8");
-  const prose = extractProse(text);
+  // YAML frontmatter is metadata, not prose. `extractProse` blanks fences,
+  // tables and inline code but leaves the `---` block, whose delimiters read
+  // as em dashes and whose `key: value` lines read as colon nameplates; every
+  // page was paying for its own frontmatter. Blank it, offsets preserved.
+  const prose = extractProse(blankFrontmatter(text));
   const doc = buildDocAnalysis(prose);
   const { findings, errors } = runRules(RULES, doc);
   for (const e of errors) detail.push(`${rel}: rule ${e.ruleId} errored: ${e.message}`);