@cavelang/canonical 0.1.0

package/dist/src/prelude.js

@@ -0,0 +1,38 @@
+/**
+ * The shared standard prelude (spec §5.5).
+ *
+ * Standard verbs SHOULD carry inverse declarations; emitters MAY prepend
+ * them to a document or keep them in a shared prelude. This module is that
+ * shared prelude: the spec's declaration block as CAVE text, plus a
+ * pre-built registry for callers that want inverse-aware reads without
+ * ingesting the text first.
+ */
+import * as Registry from "./registry.js";
+/** The spec §5.5 declaration block, verbatim. */
+export const standardPrelude = `REVERSE IS verb ; declares that two verbs name the same edge read in opposite directions
+REVERSE HAS arity: 2
+CONTAINS REVERSE PART-OF
+CAUSE REVERSE CAUSED-BY
+PRECEDES REVERSE FOLLOWS
+USES REVERSE USED-BY
+NEEDS REVERSE NEEDED-BY
+ENABLES REVERSE ENABLED-BY
+BLOCKS REVERSE BLOCKED-BY
+EXTENDS REVERSE EXTENDED-BY
+`;
+const standardPairs = [
+    ['CONTAINS', 'PART-OF'],
+    ['CAUSE', 'CAUSED-BY'],
+    ['PRECEDES', 'FOLLOWS'],
+    ['USES', 'USED-BY'],
+    ['NEEDS', 'NEEDED-BY'],
+    ['ENABLES', 'ENABLED-BY'],
+    ['BLOCKS', 'BLOCKED-BY'],
+    ['EXTENDS', 'EXTENDED-BY']
+];
+/** Registry with the standard §5.5 inverse pairs declared. */
+export const standardRegistry = standardPairs.reduce((registry, [primary, inverse]) => {
+    const declared = Registry.declareReverse(registry, primary, inverse);
+    return declared.registry;
+}, Registry.declareVerb(Registry.empty, 'REVERSE'));
+//# sourceMappingURL=prelude.js.map

package/dist/src/prelude.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prelude.js","sourceRoot":"","sources":["../../src/prelude.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC,iDAAiD;AACjD,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;CAU9B,CAAA;AAED,MAAM,aAAa,GAAgC;IACjD,CAAC,UAAU,EAAE,SAAS,CAAC;IACvB,CAAC,OAAO,EAAE,WAAW,CAAC;IACtB,CAAC,UAAU,EAAE,SAAS,CAAC;IACvB,CAAC,MAAM,EAAE,SAAS,CAAC;IACnB,CAAC,OAAO,EAAE,WAAW,CAAC;IACtB,CAAC,SAAS,EAAE,YAAY,CAAC;IACzB,CAAC,QAAQ,EAAE,YAAY,CAAC;IACxB,CAAC,SAAS,EAAE,aAAa,CAAC;CAC3B,CAAA;AAED,8DAA8D;AAC9D,MAAM,CAAC,MAAM,gBAAgB,GAC3B,aAAa,CAAC,MAAM,CAAa,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE;IAChE,MAAM,QAAQ,GAAG,QAAQ,CAAC,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;IACpE,OAAO,QAAQ,CAAC,QAAQ,CAAA;AAC1B,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAA"}

package/dist/src/registry.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Verb registry (spec §5.4, §5.5).
+ *
+ * Tracks in-band verb knowledge: extension verb declarations (`MIGRATES IS
+ * verb`) and inverse pairs (`CONTAINS REVERSE PART-OF`). No verb is born
+ * with an inverse — a relation without a `REVERSE` declaration simply has
+ * no reverse name.
+ *
+ * The registry is an immutable value; declaring returns a new registry, so
+ * the canonicalization pipeline can thread it through a document and
+ * declarations take effect for subsequent lines only.
+ */
+/** An inverse pair. The primary is the left side of the first declaration (spec §5.5). */
+export type Pair = {
+    readonly primary: string;
+    readonly inverse: string;
+};
+export type Registry = {
+    /** Every verb of every pair → its pair. */
+    readonly pairs: ReadonlyMap<string, Pair>;
+    /** Extension verbs declared via `X IS verb`. */
+    readonly declared: ReadonlySet<string>;
+};
+export type t = Registry;
+/** Registry with no declarations. */
+export declare const empty: Registry;
+export type Declared = {
+    readonly ok: true;
+    readonly registry: Registry;
+} | {
+    readonly ok: false;
+    readonly registry: Registry;
+    readonly problem: string;
+};
+/**
+ * Declares `a REVERSE b`: `a` is primary, `b` its inverse (spec §5.5).
+ * Redeclaring an existing pair in either direction is a no-op; a
+ * declaration that conflicts with an existing pair is rejected — the first
+ * declaration wins.
+ */
+export declare const declareReverse: (registry: Registry, a: string, b: string) => Declared;
+/** Declares an extension verb (`X IS verb`, spec §5.4). */
+export declare const declareVerb: (registry: Registry, verb: string) => Registry;
+/**
+ * @returns the canonical primary of `verb` and whether `verb` is the
+ * inverse side. An unpaired verb is its own primary.
+ */
+export declare const primaryOf: (registry: Registry, verb: string) => {
+    primary: string;
+    isInverse: boolean;
+};
+/**
+ * @returns the opposite name of `verb` — `CONTAINS` → `PART-OF`,
+ * `PART-OF` → `CONTAINS` — or `undefined` when no inverse is declared
+ * (reverse reads then fall back to an un-named object-side scan, spec §5.5).
+ */
+export declare const inverseOf: (registry: Registry, verb: string) => undefined | string;
+/** @returns `true` if `verb` was declared as an extension verb. */
+export declare const isDeclared: (registry: Registry, verb: string) => boolean;
+/** All pairs, deduplicated, in insertion order. */
+export declare const allPairs: (registry: Registry) => Pair[];
+//# sourceMappingURL=registry.d.ts.map

package/dist/src/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,0FAA0F;AAC1F,MAAM,MAAM,IAAI,GAAG;IACjB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,QAAQ,GAAG;IACrB,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IACzC,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CACvC,CAAA;AAED,MAAM,MAAM,CAAC,GAAG,QAAQ,CAAA;AAExB,qCAAqC;AACrC,eAAO,MAAM,KAAK,EAAE,QAGnB,CAAA;AAED,MAAM,MAAM,QAAQ,GAChB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GAClD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAEjF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,UAAU,QAAQ,EAAE,GAAG,MAAM,EAAE,GAAG,MAAM,KAAG,QAyBzE,CAAA;AAED,2DAA2D;AAC3D,eAAO,MAAM,WAAW,GAAI,UAAU,QAAQ,EAAE,MAAM,MAAM,KAAG,QAO9D,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,SAAS,GAAI,UAAU,QAAQ,EAAE,MAAM,MAAM,KAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAMjG,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,UAAU,QAAQ,EAAE,MAAM,MAAM,KAAG,SAAS,GAAG,MAMxE,CAAA;AAED,mEAAmE;AACnE,eAAO,MAAM,UAAU,GAAI,UAAU,QAAQ,EAAE,MAAM,MAAM,KAAG,OACjC,CAAA;AAE7B,mDAAmD;AACnD,eAAO,MAAM,QAAQ,GAAI,UAAU,QAAQ,KAAG,IAAI,EACX,CAAA"}

package/dist/src/registry.js

@@ -0,0 +1,86 @@
+/**
+ * Verb registry (spec §5.4, §5.5).
+ *
+ * Tracks in-band verb knowledge: extension verb declarations (`MIGRATES IS
+ * verb`) and inverse pairs (`CONTAINS REVERSE PART-OF`). No verb is born
+ * with an inverse — a relation without a `REVERSE` declaration simply has
+ * no reverse name.
+ *
+ * The registry is an immutable value; declaring returns a new registry, so
+ * the canonicalization pipeline can thread it through a document and
+ * declarations take effect for subsequent lines only.
+ */
+import { Verb } from '@cavelang/core';
+/** Registry with no declarations. */
+export const empty = {
+    pairs: new Map(),
+    declared: new Set()
+};
+/**
+ * Declares `a REVERSE b`: `a` is primary, `b` its inverse (spec §5.5).
+ * Redeclaring an existing pair in either direction is a no-op; a
+ * declaration that conflicts with an existing pair is rejected — the first
+ * declaration wins.
+ */
+export const declareReverse = (registry, a, b) => {
+    if (!Verb.isVerbToken(a) || !Verb.isVerbToken(b)) {
+        return { ok: false, registry, problem: `REVERSE operands must be UPPERCASE verbs, got ${a} REVERSE ${b}` };
+    }
+    const existingA = registry.pairs.get(a);
+    const existingB = registry.pairs.get(b);
+    const existing = existingA ?? existingB;
+    if (existing !== undefined) {
+        const same = (existing.primary === a && existing.inverse === b) ||
+            (existing.primary === b && existing.inverse === a);
+        if (same && existingA === existingB) {
+            return { ok: true, registry };
+        }
+        return {
+            ok: false,
+            registry,
+            problem: `${a} REVERSE ${b} conflicts with existing ${existing.primary} REVERSE ${existing.inverse} — first declaration wins (spec §5.5)`
+        };
+    }
+    const pair = { primary: a, inverse: b };
+    const pairs = new Map(registry.pairs);
+    pairs.set(a, pair);
+    pairs.set(b, pair);
+    return { ok: true, registry: { pairs, declared: registry.declared } };
+};
+/** Declares an extension verb (`X IS verb`, spec §5.4). */
+export const declareVerb = (registry, verb) => {
+    if (registry.declared.has(verb)) {
+        return registry;
+    }
+    const declared = new Set(registry.declared);
+    declared.add(verb);
+    return { pairs: registry.pairs, declared };
+};
+/**
+ * @returns the canonical primary of `verb` and whether `verb` is the
+ * inverse side. An unpaired verb is its own primary.
+ */
+export const primaryOf = (registry, verb) => {
+    const pair = registry.pairs.get(verb);
+    if (pair === undefined || pair.primary === verb) {
+        return { primary: verb, isInverse: false };
+    }
+    return { primary: pair.primary, isInverse: true };
+};
+/**
+ * @returns the opposite name of `verb` — `CONTAINS` → `PART-OF`,
+ * `PART-OF` → `CONTAINS` — or `undefined` when no inverse is declared
+ * (reverse reads then fall back to an un-named object-side scan, spec §5.5).
+ */
+export const inverseOf = (registry, verb) => {
+    const pair = registry.pairs.get(verb);
+    if (pair === undefined) {
+        return undefined;
+    }
+    return pair.primary === verb ? pair.inverse : pair.primary;
+};
+/** @returns `true` if `verb` was declared as an extension verb. */
+export const isDeclared = (registry, verb) => registry.declared.has(verb);
+/** All pairs, deduplicated, in insertion order. */
+export const allPairs = (registry) => [...new Set(registry.pairs.values())];
+//# sourceMappingURL=registry.js.map

package/dist/src/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAA;AAiBrC,qCAAqC;AACrC,MAAM,CAAC,MAAM,KAAK,GAAa;IAC7B,KAAK,EAAE,IAAI,GAAG,EAAE;IAChB,QAAQ,EAAE,IAAI,GAAG,EAAE;CACpB,CAAA;AAMD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,QAAkB,EAAE,CAAS,EAAE,CAAS,EAAY,EAAE;IACnF,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;QACjD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,iDAAiD,CAAC,YAAY,CAAC,EAAE,EAAE,CAAA;IAC5G,CAAC;IACD,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;IACvC,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;IACvC,MAAM,QAAQ,GAAG,SAAS,IAAI,SAAS,CAAA;IACvC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,IAAI,GACR,CAAC,QAAQ,CAAC,OAAO,KAAK,CAAC,IAAI,QAAQ,CAAC,OAAO,KAAK,CAAC,CAAC;YAClD,CAAC,QAAQ,CAAC,OAAO,KAAK,CAAC,IAAI,QAAQ,CAAC,OAAO,KAAK,CAAC,CAAC,CAAA;QACpD,IAAI,IAAI,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YACpC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAA;QAC/B,CAAC;QACD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,QAAQ;YACR,OAAO,EAAE,GAAG,CAAC,YAAY,CAAC,4BAA4B,QAAQ,CAAC,OAAO,YAAY,QAAQ,CAAC,OAAO,uCAAuC;SAC1I,CAAA;IACH,CAAC;IACD,MAAM,IAAI,GAAS,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAA;IAC7C,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;IACrC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAA;IAClB,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAA;IAClB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAA;AACvE,CAAC,CAAA;AAED,2DAA2D;AAC3D,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAAkB,EAAE,IAAY,EAAY,EAAE;IACxE,IAAI,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QAChC,OAAO,QAAQ,CAAA;IACjB,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;IAC3C,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAClB,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAA;AAC5C,CAAC,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,QAAkB,EAAE,IAAY,EAA2C,EAAE;IACrG,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IACrC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,CAAA;IAC5C,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAA;AACnD,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,QAAkB,EAAE,IAAY,EAAsB,EAAE;IAChF,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IACrC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,OAAO,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAA;AAC5D,CAAC,CAAA;AAED,mEAAmE;AACnE,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,QAAkB,EAAE,IAAY,EAAW,EAAE,CACtE,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AAE7B,mDAAmD;AACnD,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,QAAkB,EAAU,EAAE,CACrD,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@cavelang/canonical",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "CAVE canonicalization — verb registry, REVERSE inverse resolution, continuation expansion, canonical emitter.",
+  "license": "CC0-1.0",
+  "author": "Mirek Rusin (https://github.com/mirek)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mirek/cave.git",
+    "directory": "packages/canonical"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/test",
+    "!dist/tsconfig.tsbuildinfo",
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "License.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@cavelang/core": "0.1.0",
+    "@cavelang/parser": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "node --disable-warning=ExperimentalWarning --test 'test/*.test.ts'",
+    "typecheck": "tsc -b"
+  }
+}

package/src/canonicalize.ts

@@ -0,0 +1,272 @@
+/**
+ * Canonicalization pipeline (spec §13.4).
+ *
+ * Turns a parsed document into canonical claims plus qualifier edges:
+ *
+ * 1. verbs are already uppercase (parser enforces the lexical shape);
+ * 2. inverse verbs swap subject/object and substitute the primary (§5.5);
+ * 3. continuation lines fill their inherited endpoint from the parent (§8.3);
+ * 4. entity whitespace normalizes to `-`, proper-noun casing preserved;
+ * 5. `raw` keeps the line exactly as written;
+ * 6–10. confidence, `~`, multipliers, tag splitting are handled by the
+ *    parser and `@cavelang/core`;
+ * 11. claim keys are computed on the canonical form (`Key.of`);
+ * 12. contexts/tags ride on each claim for the store's side tables.
+ *
+ * Qualifier lines become claim nodes joined to their parent by edges
+ * (§8.1); `UNLESS x` normalizes to `WHEN` + negated condition (§8.2);
+ * grouped full claims link to their parent with the `QUALIFIES` role
+ * (§13.2). `REVERSE` and extension-verb declarations update the registry
+ * in-band, affecting subsequent lines (§5.4, §5.5).
+ */
+
+import { Claim, Entity, Value, Verb } from '@cavelang/core'
+import { parseDocument, type Ast } from '@cavelang/parser'
+import * as Registry from './registry.ts'
+
+/** Edge roles persisted in `cave_edge` (spec §13.2). */
+export type EdgeRole = 'WHEN' | 'VIA' | 'BECAUSE' | 'QUALIFIES'
+
+/** A canonical claim with its 1-based source line. */
+export type Entry = {
+  readonly claim: Claim.t
+  readonly line: number
+}
+
+/** Edge between claim indices (into `Result.claims`). */
+export type Edge = {
+  readonly parent: number
+  readonly role: EdgeRole
+  readonly child: number
+}
+
+export type Problem = {
+  readonly line: number
+  readonly message: string
+}
+
+export type Result = {
+  readonly claims: readonly Entry[]
+  readonly edges: readonly Edge[]
+  /** Registry after processing — input registry plus in-band declarations. */
+  readonly registry: Registry.t
+  readonly problems: readonly Problem[]
+}
+
+const roleOf: Record<Verb.Qualifier, EdgeRole> = {
+  WHEN: 'WHEN',
+  UNLESS: 'WHEN',
+  VIA: 'VIA',
+  BECAUSE: 'BECAUSE'
+}
+
+/** `>` maps to the standard `EXCEEDS`; other operators keep their symbol. */
+const comparisonVerb = (op: Ast.ComparisonOp): string =>
+  op === '>' ? 'EXCEEDS' : op
+
+const normalizeTerm = (term: Claim.Term): Claim.Term =>
+  term.kind === 'entity' ? Claim.entity(Entity.normalize(term.text)) : term
+
+/**
+ * Term ↔ payload conversion for the §5.5 inverse swap. The parser
+ * classifies a date/number endpoint as a metric payload but a subject is
+ * always a term; swapping must re-classify both directions the same way,
+ * or `deploy PRECEDES 2026-01-01` and `2026-01-01 FOLLOWS deploy` would
+ * key differently — two keys for one fact.
+ */
+const termOfPayload = (payload: Claim.Payload): undefined | Claim.Term => {
+  switch (payload.kind) {
+    case 'relation':
+      return payload.object
+    case 'metric':
+      return payload.value.kind === 'code' ? Claim.code(payload.value.raw) :
+        payload.value.kind === 'text' ? Claim.text(payload.value.raw) :
+        Claim.entity(Entity.normalize(payload.value.raw))
+    default:
+      return undefined
+  }
+}
+
+const payloadOfTerm = (term: Claim.Term): Claim.Payload => {
+  if (term.kind === 'entity') {
+    const value = Value.parse(term.text)
+    if (value.kind === 'number' || value.kind === 'date') {
+      return Claim.metric(value)
+    }
+  }
+  return Claim.relation(term)
+}
+
+const initOf = (meta: Ast.Meta): Partial<Claim.Init> => ({
+  contexts: meta.contexts,
+  tags: meta.tags,
+  importance: meta.importance,
+  ...meta.conf !== undefined ? { conf: meta.conf } : {},
+  ...meta.delta !== undefined ? { delta: meta.delta } : {},
+  ...meta.sigmaLevel !== undefined ? { sigmaLevel: meta.sigmaLevel } : {},
+  ...meta.comment !== undefined ? { comment: meta.comment } : {}
+})
+
+/** Canonicalizes a parsed document. */
+export const canonicalize = (document: Ast.Document, registry: Registry.t = Registry.empty): Result => {
+  const claims: Entry[] = []
+  const edges: Edge[] = []
+  const problems: Problem[] = []
+  /** line index → claim index + the subject as (virtually) written, for §8.3 inheritance. */
+  const byLine = new Map<number, { index: number, writtenSubject: Claim.Term }>()
+
+  const problem = (line: number, message: string): void => {
+    problems.push({ line, message })
+  }
+
+  /** Canonicalizes one full claim body — §13.4 steps 2 and 4 plus assembly. */
+  const buildClaim = (full: Ast.Full, raw: string, line: number): { claim: Claim.t, writtenSubject: Claim.Term } => {
+    const writtenSubject = normalizeTerm(full.subject)
+    let subject = writtenSubject
+    let verb = full.verb
+    let payload: Claim.Payload = full.payload
+    if (payload.kind === 'relation') {
+      payload = Claim.relation(normalizeTerm(payload.object))
+    }
+    const { primary, isInverse } = Registry.primaryOf(registry, verb)
+    if (isInverse) {
+      const objectTerm = termOfPayload(payload)
+      if (objectTerm === undefined) {
+        problem(line, `inverse verb ${verb} needs an object to swap with — keeping the line as written (spec §5.5)`)
+      } else {
+        payload = payloadOfTerm(subject)
+        subject = objectTerm
+        verb = primary
+      }
+    }
+    const claim = Claim.of({
+      subject,
+      verb,
+      negated: full.negated,
+      payload,
+      raw,
+      ...initOf(full.meta)
+    })
+    return { claim, writtenSubject }
+  }
+
+  const append = (claim: Claim.t, line: number, writtenSubject: Claim.Term, lineIndex: number): number => {
+    const index = claims.length
+    claims.push({ claim, line })
+    byLine.set(lineIndex, { index, writtenSubject })
+    return index
+  }
+
+  /** In-band declarations take effect for subsequent lines (spec §5.4, §5.5). */
+  const applyDeclarations = (claim: Claim.t, line: number): void => {
+    if (claim.payload.kind !== 'relation' || claim.negated) {
+      return
+    }
+    const object = claim.payload.object
+    if (claim.verb === Verb.REVERSE && claim.subject.kind === 'entity' && object.kind === 'entity') {
+      const declared = Registry.declareReverse(registry, claim.subject.text, object.text)
+      registry = declared.registry
+      if (!declared.ok) {
+        problem(line, declared.problem)
+      }
+      return
+    }
+    if (claim.verb === 'IS' && object.kind === 'entity' && object.text === 'verb' &&
+        claim.subject.kind === 'entity' && Verb.isVerbToken(claim.subject.text)) {
+      registry = Registry.declareVerb(registry, claim.subject.text)
+    }
+  }
+
+  /** Builds the condition claim of a qualifier line (spec §8.2). */
+  const conditionOf = (payload: Ast.QualifierPayload, unless: boolean): Ast.Full => {
+    switch (payload.kind) {
+      case 'claim':
+        return {
+          ...payload.claim,
+          negated: payload.claim.negated !== (payload.negated !== unless)
+        }
+      case 'entity':
+        return {
+          subject: payload.term,
+          verb: 'EXISTS',
+          negated: payload.negated !== unless,
+          payload: Claim.none,
+          meta: payload.meta
+        }
+      case 'comparison':
+        return {
+          subject: payload.left,
+          verb: comparisonVerb(payload.op),
+          negated: payload.negated !== unless,
+          payload: Claim.metric(payload.value),
+          meta: payload.meta
+        }
+    }
+  }
+
+  document.lines.forEach((line, lineIndex) => {
+    switch (line.kind) {
+      case 'claim': {
+        const { claim, writtenSubject } = buildClaim(line.claim, line.raw, line.line)
+        const index = append(claim, line.line, writtenSubject, lineIndex)
+        if (line.parent !== undefined) {
+          const parent = byLine.get(line.parent)
+          if (parent !== undefined) {
+            edges.push({ parent: parent.index, role: 'QUALIFIES', child: index })
+          }
+        }
+        applyDeclarations(claim, line.line)
+        return
+      }
+      case 'continuation': {
+        const parent = byLine.get(line.parent!)
+        if (parent === undefined) {
+          problem(line.line, 'continuation has no canonicalized parent')
+          return
+        }
+        const full: Ast.Full = { subject: parent.writtenSubject, ...line.body }
+        const { claim, writtenSubject } = buildClaim(full, line.raw, line.line)
+        append(claim, line.line, writtenSubject, lineIndex)
+        // §8.3: each continuation is an ordinary independent claim, so an
+        // in-band declaration works here exactly as on a full line (§5.4).
+        applyDeclarations(claim, line.line)
+        return
+      }
+      case 'qualifier': {
+        const parent = byLine.get(line.parent!)
+        if (parent === undefined) {
+          problem(line.line, 'qualifier has no canonicalized parent')
+          return
+        }
+        const full = conditionOf(line.payload, line.qualifier === 'UNLESS')
+        const { claim, writtenSubject } = buildClaim(full, line.raw, line.line)
+        const index = append(claim, line.line, writtenSubject, lineIndex)
+        edges.push({ parent: parent.index, role: roleOf[line.qualifier], child: index })
+        return
+      }
+      default:
+        return
+    }
+  })
+
+  return { claims, edges, registry, problems }
+}
+
+/**
+ * Parses and canonicalizes CAVE text in one step. Parser diagnostics merge
+ * into `problems`.
+ */
+export const canonicalizeText = (input: string, registry: Registry.t = Registry.empty): Result => {
+  const document = parseDocument(input)
+  const result = canonicalize(document, registry)
+  if (document.diagnostics.length === 0) {
+    return result
+  }
+  return {
+    ...result,
+    problems: [
+      ...document.diagnostics.map(diagnostic => ({ line: diagnostic.line, message: diagnostic.message })),
+      ...result.problems
+    ]
+  }
+}

package/src/emit.ts

@@ -0,0 +1,116 @@
+/**
+ * Canonical emitter.
+ *
+ * Emits canonical CAVE text from canonical claims: colon attribute form
+ * (§3.4 — emitters MUST produce it), primary verb direction (§5.5),
+ * `WHEN NOT` rather than `UNLESS` (§8.2), metadata in the §3.2 anatomy
+ * order. Qualifier edges re-indent under their parent; grouped claims
+ * (`QUALIFIES` edges) re-indent as full lines.
+ */
+
+import { Claim, Confidence, Tag, Value } from '@cavelang/core'
+import type * as Canonicalize from './canonicalize.ts'
+
+const payloadText = (payload: Claim.Payload): undefined | string => {
+  switch (payload.kind) {
+    case 'relation':
+      return Claim.formatTerm(payload.object)
+    case 'attribute':
+      return `${payload.attribute}: ${Value.format(payload.value)}`
+    case 'metric':
+      return Value.format(payload.value)
+    case 'none':
+      return undefined
+  }
+}
+
+const metaText = (claim: Claim.t): string[] => {
+  const parts: string[] = []
+  if (claim.delta !== undefined) {
+    parts.push(`+/- ${Value.format(claim.delta)}`)
+  }
+  if (claim.sigmaLevel !== undefined) {
+    parts.push(`(${claim.sigmaLevel}σ)`)
+  }
+  for (const context of claim.contexts) {
+    parts.push(`@${context}`)
+  }
+  for (const tag of claim.tags) {
+    parts.push(Tag.format(tag))
+  }
+  if (claim.conf !== 1) {
+    parts.push(`@ ${Confidence.format(claim.conf)}`)
+  }
+  if (claim.importance) {
+    parts.push('!')
+  }
+  if (claim.comment !== undefined) {
+    parts.push(`; ${claim.comment}`)
+  }
+  return parts
+}
+
+/** @returns one canonical line for a claim (no indentation). */
+export const emitClaim = (claim: Claim.t): string => {
+  const parts = [Claim.formatTerm(claim.subject), claim.verb]
+  if (claim.negated) {
+    parts.push('NOT')
+  }
+  const payload = payloadText(claim.payload)
+  if (payload !== undefined) {
+    parts.push(payload)
+  }
+  parts.push(...metaText(claim))
+  return parts.join(' ')
+}
+
+/**
+ * @returns the qualifier-payload text of a condition claim. Negation always
+ * emits as a `NOT` *prefix* — the §8.2 canonical `WHEN NOT x` shape — never
+ * as the claim-internal `VERB NOT` form: a postfix `NOT` after a symbolic
+ * comparison verb (`WHEN cpu >= NOT 900`) would be unreadable to the
+ * parser and silently invert the condition on round trip.
+ */
+const conditionText = (claim: Claim.t): string => {
+  const body = claim.verb === 'EXISTS' && claim.payload.kind === 'none' ?
+    [Claim.formatTerm(claim.subject), ...metaText(claim)].join(' ') :
+    emitClaim({ ...claim, negated: false })
+  return claim.negated ? `NOT ${body}` : body
+}
+
+/**
+ * Emits a whole canonicalization result as canonical CAVE text: top-level
+ * claims in claim order, children indented two spaces per level.
+ */
+export const emit = (result: Pick<Canonicalize.Result, 'claims' | 'edges'>): string => {
+  const childEdges = new Map<number, Canonicalize.Edge[]>()
+  const isChild = new Set<number>()
+  for (const edge of result.edges) {
+    isChild.add(edge.child)
+    const existing = childEdges.get(edge.parent)
+    if (existing === undefined) {
+      childEdges.set(edge.parent, [edge])
+    } else {
+      existing.push(edge)
+    }
+  }
+  const lines: string[] = []
+  const emitAt = (index: number, depth: number, role: undefined | Canonicalize.EdgeRole): void => {
+    const { claim } = result.claims[index]!
+    const indent = '  '.repeat(depth)
+    if (role === undefined || role === 'QUALIFIES') {
+      lines.push(`${indent}${emitClaim(claim)}`)
+    } else {
+      lines.push(`${indent}${role} ${conditionText(claim)}`)
+    }
+    for (const edge of childEdges.get(index) ?? []) {
+      emitAt(edge.child, depth + 1, edge.role)
+    }
+  }
+  result.claims.forEach((_, index) => {
+    if (!isChild.has(index)) {
+      emitAt(index, 0, undefined)
+    }
+  })
+  return lines.length === 0 ? '' : `${lines.join('\n')}\n`
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+/**
+ * `@cavelang/canonical` — the CAVE semantic layer (spec §5.4, §5.5, §8, §13.4).
+ *
+ * Verb registry with in-band `REVERSE`/extension declarations, the
+ * canonicalization pipeline (inverse resolution, continuation expansion,
+ * qualifier edges, `UNLESS` normalization), the shared standard prelude and
+ * the canonical emitter.
+ *
+ * ```ts
+ * import { canonicalizeText, standardRegistry, emit } from '@cavelang/canonical'
+ *
+ * const result = canonicalizeText('packages/api PART-OF monorepo', standardRegistry)
+ * result.claims[0].claim // monorepo CONTAINS packages/api — one fact, two names
+ * emit(result)           // canonical text, primary direction
+ * ```
+ */
+
+export * as Registry from './registry.ts'
+export { canonicalize, canonicalizeText } from './canonicalize.ts'
+export type { Edge, EdgeRole, Entry, Problem, Result } from './canonicalize.ts'
+export { emit, emitClaim } from './emit.ts'
+export { standardPrelude, standardRegistry } from './prelude.ts'