@sigloch/contracts 0.7.0 → 1.0.0

package/dist/se/conformance-rules.d.ts

@@ -1,6 +1,6 @@
 /**
  * RC conformance rules (CR-GC-253) — graph↔code resolution, the RESOLUTION
- * twins of the presence rules R-20 (codeRef) / R-19 (testRef).
+ * twins of the presence rules R-20 (FUNC realRef) / R-19 (testRef).
  *
  * Rules stay in THIS library (one rule base per onto set — no rule definitions
  * in executor codebases). They are pure functions over (graph, facts): all
@@ -8,7 +8,7 @@
  * from the repo), so this module stays I/O-free and browser-bundlable.
  *
  * CodeFacts semantics: `files` is keyed by repo-relative path and MUST contain
- * an entry for every file referenced by a codeRef/testRef the extractor saw.
+ * an entry for every file referenced by a realRef/testRef the extractor saw.
  * A MISSING key is treated like `exists:false` — an extractor gap must surface
  * loudly as a violation, never as a silent pass.
  *

package/dist/se/conformance-rules.js

@@ -1,6 +1,6 @@
 /**
  * RC conformance rules (CR-GC-253) — graph↔code resolution, the RESOLUTION
- * twins of the presence rules R-20 (codeRef) / R-19 (testRef).
+ * twins of the presence rules R-20 (FUNC realRef) / R-19 (testRef).
  *
  * Rules stay in THIS library (one rule base per onto set — no rule definitions
  * in executor codebases). They are pure functions over (graph, facts): all
@@ -8,14 +8,14 @@
  * from the repo), so this module stays I/O-free and browser-bundlable.
  *
  * CodeFacts semantics: `files` is keyed by repo-relative path and MUST contain
- * an entry for every file referenced by a codeRef/testRef the extractor saw.
+ * an entry for every file referenced by a realRef/testRef the extractor saw.
  * A MISSING key is treated like `exists:false` — an extractor gap must surface
  * loudly as a violation, never as a silent pass.
  *
  * @sigloch/contracts/se — single source of truth for SE validation rules.
  */
 import { z } from 'zod/v4';
-import { CodeRefSchema, TestRefSchema, SchemaRefSchema } from './ontology.js';
+import { RealRefSchema, TestRefSchema } from './ontology.js';
 /** Parser facts about one source file (extracted by the executor). */
 export const FileFactsSchema = z.object({
     /** File exists on disk (repo-relative path). */
@@ -50,10 +50,11 @@ export const CodeFactsSchema = z.object({
     importEdges: z.array(ImportEdgeSchema).optional(),
 });
 const missingFile = (facts, file) => facts.files[file]?.exists !== true;
-// RC-01: every valid codeRef must resolve — file on disk, symbol declared in it.
-// Presence is R-20's concern (incl. concept/external/decomposition-parent
+// RC-01: every valid FUNC realRef must resolve — file on disk, symbol declared in
+// it. Presence is R-20's concern (incl. concept/external/decomposition-parent
 // exemptions, CR-GC-244); RC-01 only judges bindings that exist. `lang:'prompt'`
-// is realized by a skill file — file-exists is the whole binding.
+// is realized by a skill file — file-exists is the whole binding. A realRef with
+// no `symbol` (CR-228) is also file-only: resolution stops at file-exists.
 function codeRefMustResolve(graph, facts) {
     const violations = [];
     for (const el of graph.elements) {
@@ -61,7 +62,7 @@ function codeRefMustResolve(graph, facts) {
             continue;
         if (el.attributes?.concept === true || el.attributes?.external === true)
             continue;
-        const parsed = CodeRefSchema.safeParse(el.attributes?.codeRef);
+        const parsed = RealRefSchema.safeParse(el.attributes?.realRef);
         if (!parsed.success)
             continue; // no/invalid binding → R-20 territory
         const ref = parsed.data;
@@ -70,20 +71,20 @@ function codeRefMustResolve(graph, facts) {
                 rule_id: 'RC-01',
                 severity: 'error',
                 element_id: el.id,
-                message: `${el.id} codeRef.file '${ref.file}' does not exist on disk`,
+                message: `${el.id} realRef.file '${ref.file}' does not exist on disk`,
                 fix_hint: 'Re-realize the FUNC (graph_realize) against the current source tree, or fix the moved/renamed file path',
                 context: { element_type: el.type, element_name: el.name },
             });
             continue;
         }
-        if (ref.lang === 'prompt')
-            continue; // skill file existing IS the binding
+        if (ref.lang === 'prompt' || ref.symbol === undefined)
+            continue; // skill/file-only binding IS the binding
         if (!facts.files[ref.file].declaredSymbols.includes(ref.symbol)) {
             violations.push({
                 rule_id: 'RC-01',
                 severity: 'error',
                 element_id: el.id,
-                message: `${el.id} codeRef.symbol '${ref.symbol}' is not declared in '${ref.file}'`,
+                message: `${el.id} realRef.symbol '${ref.symbol}' is not declared in '${ref.file}'`,
                 fix_hint: 'The symbol was renamed or removed — re-realize the FUNC against the current code',
                 context: { element_type: el.type, element_name: el.name },
             });
@@ -131,11 +132,11 @@ function testRefMustResolve(graph, facts) {
     }
     return violations;
 }
-// RC-03: every valid SCHEMA schemaRef must resolve — file on disk, symbol declared
-// in it (CR-211). Presence (a SCHEMA with NO schemaRef) is the concern of the
-// R-26 presence rule, not RC-03; concept/external SCHEMAs are exempt there and
-// here. Severity error, like RC-01: a bound-but-broken schema IS a defect. Fires
-// 0× until schemaRefs exist (it only judges SCHEMAs that carry one).
+// RC-03: every valid SCHEMA realRef must resolve — file on disk, symbol declared
+// in it (CR-211, unified CR-228). Presence (a SCHEMA with NO realRef) is the
+// concern of the R-26 presence rule, not RC-03; concept/external SCHEMAs are exempt
+// there and here. Severity error, like RC-01: a bound-but-broken schema IS a defect.
+// A symbol-less realRef stops at file-exists. Fires 0× until realRefs exist.
 function schemaRefMustResolve(graph, facts) {
     const violations = [];
     for (const el of graph.elements) {
@@ -143,7 +144,7 @@ function schemaRefMustResolve(graph, facts) {
             continue;
         if (el.attributes?.concept === true || el.attributes?.external === true)
             continue;
-        const parsed = SchemaRefSchema.safeParse(el.attributes?.schemaRef);
+        const parsed = RealRefSchema.safeParse(el.attributes?.realRef);
         if (!parsed.success)
             continue; // no/invalid binding → R-26 territory
         const ref = parsed.data;
@@ -152,18 +153,20 @@ function schemaRefMustResolve(graph, facts) {
                 rule_id: 'RC-03',
                 severity: 'error',
                 element_id: el.id,
-                message: `${el.id} schemaRef.file '${ref.file}' does not exist on disk`,
+                message: `${el.id} realRef.file '${ref.file}' does not exist on disk`,
                 fix_hint: 'Re-bind the SCHEMA (graph_realize) to the current source tree, or fix the moved/renamed file path',
                 context: { element_type: el.type, element_name: el.name },
             });
             continue;
         }
+        if (ref.symbol === undefined)
+            continue; // file-only binding
         if (!facts.files[ref.file].declaredSymbols.includes(ref.symbol)) {
             violations.push({
                 rule_id: 'RC-03',
                 severity: 'error',
                 element_id: el.id,
-                message: `${el.id} schemaRef.symbol '${ref.symbol}' is not a declared export in '${ref.file}'`,
+                message: `${el.id} realRef.symbol '${ref.symbol}' is not a declared export in '${ref.file}'`,
                 fix_hint: 'The schema export was renamed or removed — re-bind the SCHEMA against the current code',
                 context: { element_type: el.type, element_name: el.name },
             });
@@ -174,11 +177,11 @@ function schemaRefMustResolve(graph, facts) {
 // RC-04: a bound SCHEMA that the graph says is realized at an interface must
 // actually be parsed there (CR-211). The graph gives the check LOCATIONS: FUNCs
 // io-connected to a FLOW whose data format IS this SCHEMA (FUNC ─io→ FLOW
-// ─relation→ SCHEMA) and that carry a resolvable codeRef. If ≥1 such FUNC exists
-// but NONE of their codeRef files import AND parse (`.parse`/`.safeParse`) the
+// ─relation→ SCHEMA) and that carry a resolvable realRef. If ≥1 such FUNC exists
+// but NONE of their realRef files import AND parse (`.parse`/`.safeParse`) the
 // schema symbol, the modelled validation is missing. Severity warn (the parse may
 // legitimately sit in a framework layer, not the FUNC's own file). Skips when the
-// SCHEMA has no schemaRef, or no io-connected realized FUNC to check against.
+// SCHEMA has no realRef (or a symbol-less one), or no io-connected realized FUNC.
 function schemaRefMustBeUsed(graph, facts) {
     const typeOf = new Map(graph.elements.map(e => [e.id, e.type]));
     const violations = [];
@@ -187,8 +190,8 @@ function schemaRefMustBeUsed(graph, facts) {
             continue;
         if (el.attributes?.concept === true || el.attributes?.external === true)
             continue;
-        const parsed = SchemaRefSchema.safeParse(el.attributes?.schemaRef);
-        if (!parsed.success)
+        const parsed = RealRefSchema.safeParse(el.attributes?.realRef);
+        if (!parsed.success || parsed.data.symbol === undefined)
             continue;
         const ref = parsed.data;
         // The FLOWs whose data format is this SCHEMA (FLOW ─relation→ SCHEMA).
@@ -203,11 +206,11 @@ function schemaRefMustBeUsed(graph, facts) {
             ((flowIds.has(t.target) && typeOf.get(t.source) === 'FUNC') ||
                 (flowIds.has(t.source) && typeOf.get(t.target) === 'FUNC')))
             .map(t => (flowIds.has(t.target) ? t.source : t.target)));
-        // Realized FUNCs among them: a resolvable codeRef whose file exists.
+        // Realized FUNCs among them: a resolvable realRef whose file exists.
         const realizedFiles = [];
         for (const fnId of funcIds) {
             const fn = graph.elements.find(e => e.id === fnId);
-            const cr = CodeRefSchema.safeParse(fn?.attributes?.codeRef);
+            const cr = RealRefSchema.safeParse(fn?.attributes?.realRef);
             if (cr.success && !missingFile(facts, cr.data.file))
                 realizedFiles.push(cr.data.file);
         }
@@ -255,12 +258,12 @@ function importDriftConformance(graph, facts) {
     const modIds = graph.elements.filter(e => e.type === 'MOD').map(e => e.id);
     if (modIds.length === 0)
         return [];
-    // 1. file → MOD. Direct codeRef bindings first.
+    // 1. file → MOD. Direct realRef bindings first.
     const fileToMod = new Map();
     for (const el of graph.elements) {
         if (el.type !== 'FUNC')
             continue;
-        const cr = CodeRefSchema.safeParse(el.attributes?.codeRef);
+        const cr = RealRefSchema.safeParse(el.attributes?.realRef);
         if (!cr.success)
             continue;
         const modTrace = graph.traces.find(t => t.source === el.id && t.type === 'allocate' && typeOf.get(t.target) === 'MOD');
@@ -352,10 +355,10 @@ function importDriftConformance(graph, facts) {
 }
 /** All RC conformance rules — evaluated by executors that can supply CodeFacts. */
 export const CODE_CONFORMANCE_RULES = [
-    { id: 'RC-01', name: 'codeRef resolves to a declared symbol', severity: 'error', evaluate: codeRefMustResolve },
+    { id: 'RC-01', name: 'FUNC realRef resolves to a declared symbol', severity: 'error', evaluate: codeRefMustResolve },
     { id: 'RC-02', name: 'testRef resolves to a runnable test', severity: 'error', evaluate: testRefMustResolve },
-    { id: 'RC-03', name: 'schemaRef resolves to a declared export', severity: 'error', evaluate: schemaRefMustResolve },
-    { id: 'RC-04', name: 'schemaRef is parsed at its interface', severity: 'warning', evaluate: schemaRefMustBeUsed },
+    { id: 'RC-03', name: 'SCHEMA realRef resolves to a declared export', severity: 'error', evaluate: schemaRefMustResolve },
+    { id: 'RC-04', name: 'SCHEMA realRef is parsed at its interface', severity: 'warning', evaluate: schemaRefMustBeUsed },
     { id: 'RC-05', name: 'cross-module import drift', severity: 'warning', evaluate: importDriftConformance },
 ];
 /** Run all RC rules against a graph + extracted code facts. */

package/dist/se/element-uid.d.ts

@@ -0,0 +1,59 @@
+/**
+ * ElementUid — the family's canonical element id form (CR-SM-217).
+ *
+ *     <TYPE>-<slug>        ACTOR-claude-code · REQ-safety · MOD-harness
+ *
+ * Decided on 2026-07-27 over the previous `Name.TypeAbbr.Counter` schema, in this order:
+ *
+ * 1. **Token-neutral.** Measured on the graphcode SSOT graph (1871 uid occurrences,
+ *    cl100k_base): `ACTOR-claude-code.ACTOR` 5.28 tok/uid vs `claudecode.ACTOR.001`
+ *    5.30 — 0.3 % apart. The spelling costs nothing, so it is decided on correctness.
+ * 2. **It is what the real graphs use.** 626 of 1145 family elements are already
+ *    `TYPE-slug`; the schema's declared canon had 89.
+ * 3. **It keeps a free type cross-check.** CR-SM-216 moved the type into the `### <TYPE>`
+ *    section, which removes the "type appears twice" redundancy that used to catch a
+ *    mis-sectioned node. A `TYPE-slug` uid carries the type in its prefix without paying
+ *    for it (`REQ-safety` = 3 tokens, `REQ-safety.REQ` = 5), so the check survives.
+ *
+ * `parseElementUid` exists **only** for that cross-check. It is never a type source —
+ * the type comes from the graph or from the Format-E section (CR-SM-216 contract).
+ *
+ * **Not every id is an ElementUid, and that is allowed.** Ids that mirror an external
+ * identifier live in their own namespace and are simply unchecked, never rejected:
+ * CR elements carry their change-request number (`CR-GC-100`, 88 in graphcode, 123 in
+ * graph-view-edit) and graphify's pre-gate candidates are `cand_<hex>`. The canon binds
+ * *new* ids minted through `toElementUid`; existing ids stay until their repo touches
+ * them.
+ */
+import { z } from 'zod/v4';
+import { ElementType } from './ontology.js';
+/** Longest slug we accept; keeps ids readable and index-friendly. */
+export declare const MAX_SLUG_LENGTH = 60;
+export declare const ElementUid: z.ZodString;
+export type ElementUid = z.infer<typeof ElementUid>;
+/**
+ * Build a canonical uid. Pure and deterministic — the same (type, name) always yields
+ * the same uid.
+ *
+ * Collisions are the **caller's** problem: only the caller knows the namespace, so
+ * disambiguation (`-2`, `-3`) belongs there. Documented rather than hidden behind a
+ * counter that would make this function stateful.
+ */
+export declare function toElementUid(type: ElementType, name: string): string;
+/**
+ * Split a uid into its parts. Throws when the prefix is not an ElementType.
+ *
+ * ⚠️ For the prefix↔section cross-check only — **never** as a type source. Deriving a
+ * type from an id's spelling is what made aimpro CR-230 drop an entire graph silently.
+ */
+export declare function parseElementUid(uid: string): {
+    type: ElementType;
+    slug: string;
+};
+/** Non-throwing variant: `undefined` for ids of any other convention (legacy, graphify candidates). */
+export declare function tryParseElementUid(uid: string): {
+    type: ElementType;
+    slug: string;
+} | undefined;
+/** True when `uid` is a canonical ElementUid. */
+export declare function isElementUid(uid: string): boolean;

package/dist/se/element-uid.js

@@ -0,0 +1,74 @@
+/**
+ * ElementUid — the family's canonical element id form (CR-SM-217).
+ *
+ *     <TYPE>-<slug>        ACTOR-claude-code · REQ-safety · MOD-harness
+ *
+ * Decided on 2026-07-27 over the previous `Name.TypeAbbr.Counter` schema, in this order:
+ *
+ * 1. **Token-neutral.** Measured on the graphcode SSOT graph (1871 uid occurrences,
+ *    cl100k_base): `ACTOR-claude-code.ACTOR` 5.28 tok/uid vs `claudecode.ACTOR.001`
+ *    5.30 — 0.3 % apart. The spelling costs nothing, so it is decided on correctness.
+ * 2. **It is what the real graphs use.** 626 of 1145 family elements are already
+ *    `TYPE-slug`; the schema's declared canon had 89.
+ * 3. **It keeps a free type cross-check.** CR-SM-216 moved the type into the `### <TYPE>`
+ *    section, which removes the "type appears twice" redundancy that used to catch a
+ *    mis-sectioned node. A `TYPE-slug` uid carries the type in its prefix without paying
+ *    for it (`REQ-safety` = 3 tokens, `REQ-safety.REQ` = 5), so the check survives.
+ *
+ * `parseElementUid` exists **only** for that cross-check. It is never a type source —
+ * the type comes from the graph or from the Format-E section (CR-SM-216 contract).
+ *
+ * **Not every id is an ElementUid, and that is allowed.** Ids that mirror an external
+ * identifier live in their own namespace and are simply unchecked, never rejected:
+ * CR elements carry their change-request number (`CR-GC-100`, 88 in graphcode, 123 in
+ * graph-view-edit) and graphify's pre-gate candidates are `cand_<hex>`. The canon binds
+ * *new* ids minted through `toElementUid`; existing ids stay until their repo touches
+ * them.
+ */
+import { z } from 'zod/v4';
+import { ElementType } from './ontology.js';
+/** Longest slug we accept; keeps ids readable and index-friendly. */
+export const MAX_SLUG_LENGTH = 60;
+/** Built from the live ElementType enum — there is no second type catalogue. */
+const UID_RE = new RegExp(`^(${ElementType.options.join('|')})-([a-z0-9]+(?:-[a-z0-9]+)*)$`);
+export const ElementUid = z.string()
+    .regex(UID_RE, 'ElementUid must match <TYPE>-<kebab-slug>')
+    .refine(uid => (uid.split('-').slice(1).join('-')).length <= MAX_SLUG_LENGTH, `slug must be at most ${MAX_SLUG_LENGTH} characters`);
+/**
+ * Build a canonical uid. Pure and deterministic — the same (type, name) always yields
+ * the same uid.
+ *
+ * Collisions are the **caller's** problem: only the caller knows the namespace, so
+ * disambiguation (`-2`, `-3`) belongs there. Documented rather than hidden behind a
+ * counter that would make this function stateful.
+ */
+export function toElementUid(type, name) {
+    const slug = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, MAX_SLUG_LENGTH)
+        .replace(/-+$/, '');
+    return `${type}-${slug}`;
+}
+/**
+ * Split a uid into its parts. Throws when the prefix is not an ElementType.
+ *
+ * ⚠️ For the prefix↔section cross-check only — **never** as a type source. Deriving a
+ * type from an id's spelling is what made aimpro CR-230 drop an entire graph silently.
+ */
+export function parseElementUid(uid) {
+    const m = UID_RE.exec(uid);
+    if (!m)
+        throw new Error(`Not an ElementUid: "${uid}" — expected <TYPE>-<kebab-slug>`);
+    return { type: m[1], slug: m[2] };
+}
+/** Non-throwing variant: `undefined` for ids of any other convention (legacy, graphify candidates). */
+export function tryParseElementUid(uid) {
+    const m = UID_RE.exec(uid);
+    return m ? { type: m[1], slug: m[2] } : undefined;
+}
+/** True when `uid` is a canonical ElementUid. */
+export function isElementUid(uid) {
+    return ElementUid.safeParse(uid).success;
+}

package/dist/se/evaluate-all.js

@@ -23,7 +23,9 @@ export const ALL_RULE_DEFS = [
     ...FM_RULES.map(r => ({ id: r.id, name: r.name, severity: r.severity })),
     ...VIEW_RULES.map(r => ({ id: r.id, name: r.name, severity: r.severity })),
 ];
-const SE_PREFIXES = ['R-', 'UC-', 'FC-', 'SC-', 'MT-', 'CR-', 'AO-', 'FM-', 'NFR-', 'RT-', 'PH-', 'CA-', 'IO-', 'VR-', 'CL-'];
+// CR-SM-221: 'RD-' was missing — 'RD-01'.startsWith('R-') is false, so the
+// decomposition rules ran in `default` only and never in the `se` profile.
+const SE_PREFIXES = ['R-', 'RD-', 'UC-', 'FC-', 'SC-', 'MT-', 'CR-', 'AO-', 'FM-', 'NFR-', 'RT-', 'PH-', 'CA-', 'IO-', 'VR-', 'CL-'];
 const CODING_PREFIXES = ['BQ-', 'ND-'];
 export function getRuleDefsForProfile(profile) {
     if (profile === 'se')

package/dist/se/format-e-parser.d.ts

@@ -1,17 +1,33 @@
 /**
  * Format E Parser — Graph mutations from compact text format.
  * SE-relevant subset: nodes (+/-/~) and edges (+/-), no chat-canvas or views.
- * ~150 LOC, no external dependencies beyond @sigloch/contracts/se.
+ *
+ * CR-SM-216 (Format-E v2): the element type comes from the `### <TYPE>` section a node
+ * is declared under, never from the spelling of its id. The old id-derived typing made
+ * every consumer with a different id convention fail *silently* — aimpro CR-230 lost a
+ * whole graph that way (`TYPE-slug` ids rejected, result empty, no error).
  *
  * @sigloch/contracts/se
  */
+import { ElementType } from './ontology.js';
 import type { TraceType, OntologyGraph } from './ontology.js';
 export interface FormatEOperation {
     type: 'add_node' | 'remove_node' | 'update_node' | 'add_edge' | 'remove_edge' | 'strict_add_node' | 'strict_add_edge';
     semanticId: string;
+    /**
+     * CR-SM-216: the element type, taken from the node's `### <TYPE>` section. Set on
+     * every node-creating operation — consumers must read it instead of re-deriving a
+     * type from the id.
+     */
+    elementType?: ElementType;
     description?: string;
-    /** CR-147: Parsed @key value attributes from lines below the node entry. */
-    attributes?: Record<string, string>;
+    /**
+     * CR-147: Parsed @key value attributes from lines below the node entry.
+     * Values are strings, EXCEPT JSON object/array literals which are hydrated
+     * (BOK-CR-026) — object-valued bindings like `realRef`/`testRef` must reach
+     * `attributes` as objects or R-26/R-19 reject them as invalid.
+     */
+    attributes?: Record<string, unknown>;
     sourceId?: string;
     targetId?: string;
     traceType?: TraceType;
@@ -22,7 +38,23 @@ export interface FormatEDiff {
 }
 /** Extract a ```format-e block from LLM output. Returns null if not found. */
 export declare function extractFormatE(llmOutput: string): string | null;
+export interface ParseFormatEOptions {
+    /**
+     * CR-SM-216: resolve the type of a uid that this text does not declare. A mutation
+     * diff adding edges between existing nodes carries no `## Nodes` block, so the
+     * caller binds this to its store. Without it such a diff is an error, never a
+     * silent skip.
+     */
+    resolveType?: (uid: string) => ElementType | undefined;
+}
 /** Parse a Format E text block into validated operations. */
-export declare function parseFormatE(input: string): FormatEDiff;
-/** Serialize an OntologyGraph to compact Format E text. */
+export declare function parseFormatE(input: string, options?: ParseFormatEOptions): FormatEDiff;
+/**
+ * Serialize an OntologyGraph to compact Format E text.
+ *
+ * CR-SM-216: nodes are written under `### <TYPE>` sections — the type is declared once
+ * per section instead of once per id. Measured on the graphcode SSOT graph (369
+ * elements), 12 section headers cost ~48 tokens where a per-node type attribute would
+ * have cost ~1476.
+ */
 export declare function serializeToFormatE(graph: OntologyGraph): string;