@sigloch/contracts 0.7.0 → 0.8.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/index.d.ts

@@ -3,9 +3,9 @@
  * Single source of truth for SE ontology schemas across all projects.
  */
 /** Ontology schema version (element types + trace types). */
-export declare const ONTOLOGY_VERSION = "3.8.0";
+export declare const ONTOLOGY_VERSION = "3.9.0";
 /** Rules engine version (validation rules incl. RC conformance). */
-export declare const RULES_VERSION = "2.17.0";
+export declare const RULES_VERSION = "2.18.0";
 /** Meta-model version (trace pattern constraints + format-e parser). */
 export declare const META_MODEL_VERSION = "1.4.0";
 export * from './ontology.js';

package/dist/se/index.js

@@ -3,9 +3,9 @@
  * Single source of truth for SE ontology schemas across all projects.
  */
 /** Ontology schema version (element types + trace types). */
-export const ONTOLOGY_VERSION = '3.8.0'; // +RepoRelativePathSchema on testRef/codeRef/schemaRef .file — no absolute/`..` paths (CR-GC-255)
+export const ONTOLOGY_VERSION = '3.9.0'; // realRef unifies codeRef+schemaRef (+physical-MOD CAD ref), symbol optional; testRef stays separate (CR-228 C); +RepoRelativePathSchema on testRef/realRef .file — no absolute/`..` paths (CR-GC-255)
 /** Rules engine version (validation rules incl. RC conformance). */
-export const RULES_VERSION = '2.17.0'; // -R-24/R-25 REQ→MOD allocation rules deleted (CR-228 A: REQ→MOD allocate no longer a valid pattern, R-18 flags residual edges); NFR-01 budget target split physical→MOD / behavioral→FCHAIN; RULE_TO_DIMENSION completeness (R-18..R-23/R-26/MS-03/CR-R04 mapped, no advisory fall-through) (CR-228 B/D); +BQ-01/02/04/06/07 base-quality rules promoted from aimpro (K2-b, completes rule consolidation); +ND-01/02 near-duplicate + AO-D01/D03/CR-01/RT-01/PH-01/CA-01/IO-01 architecture rules promoted from aimpro (K2-b); +CR-R01..04/MS-03 change-request rules promoted from aimpro (K2-b); +FM-01..03/NFR-01 FMEA + VR-01/CL-01 view rules promoted from aimpro (K2-b); +MT-01..03 architecture metrics promoted from aimpro (K2-b); +SC-01..03/UC-01..06/FC-01..03 quality rules promoted from aimpro (K2-a); +RC-05 cross-module import drift (CR-212); +R-26/RC-03/RC-04 schemaRef (CR-211); +R-22..R-25/R-10/R-20 (CR-201/202/208/209/210)
+export const RULES_VERSION = '2.18.0'; // R-20/R-26/RC-01/RC-03/RC-04 read realRef (unified codeRef+schemaRef); +R-27 physical-MOD realRef presence (CR-228 C); -R-24/R-25 REQ→MOD allocation rules deleted (CR-228 A: REQ→MOD allocate no longer a valid pattern, R-18 flags residual edges); NFR-01 budget target split physical→MOD / behavioral→FCHAIN; RULE_TO_DIMENSION completeness (R-18..R-23/R-26/MS-03/CR-R04 mapped, no advisory fall-through) (CR-228 B/D); +BQ-01/02/04/06/07 base-quality rules promoted from aimpro (K2-b, completes rule consolidation); +ND-01/02 near-duplicate + AO-D01/D03/CR-01/RT-01/PH-01/CA-01/IO-01 architecture rules promoted from aimpro (K2-b); +CR-R01..04/MS-03 change-request rules promoted from aimpro (K2-b); +FM-01..03/NFR-01 FMEA + VR-01/CL-01 view rules promoted from aimpro (K2-b); +MT-01..03 architecture metrics promoted from aimpro (K2-b); +SC-01..03/UC-01..06/FC-01..03 quality rules promoted from aimpro (K2-a); +RC-05 cross-module import drift (CR-212); +R-26/RC-03/RC-04 schemaRef (CR-211); +R-22..R-25/R-10/R-20 (CR-201/202/208/209/210)
 /** Meta-model version (trace pattern constraints + format-e parser). */
 export const META_MODEL_VERSION = '1.4.0'; // -REQ→MOD allocate pattern removed (CR-228 A); +FUNC→FUNC compose (blackbox function decomposition)
 export * from './ontology.js';

package/dist/se/meta-model.js

@@ -8,7 +8,7 @@ export const TRACE_PATTERNS = [
     { source: 'UC', target: 'FCHAIN', type: 'compose', cardinality: '1..*', description: 'UC behavioral scenarios' },
     { source: 'UC', target: 'REQ', type: 'compose', cardinality: '1..*', description: 'UC functional/non-functional requirements' },
     { source: 'FCHAIN', target: 'FUNC', type: 'compose', cardinality: '1..*', description: 'Functions participating in chain' },
-    { source: 'FUNC', target: 'FUNC', type: 'compose', cardinality: '0..*', description: 'Function (blackbox architecture block) decomposes into sub-functions one level deeper; leaf FUNCs carry codeRef, the parent is realized by its children' },
+    { source: 'FUNC', target: 'FUNC', type: 'compose', cardinality: '0..*', description: 'Function (blackbox architecture block) decomposes into sub-functions one level deeper; leaf FUNCs carry realRef, the parent is realized by its children' },
     { source: 'REQ', target: 'REQ', type: 'compose', cardinality: '0..*', description: 'Requirement decomposes into sub-requirements (incl. mitigation)' },
     // ── io (data exchange, always through FLOW) ──
     { source: 'ACTOR', target: 'FLOW', type: 'io', description: 'Actor triggers/receives via flow' },

package/dist/se/ontology.d.ts

@@ -110,40 +110,27 @@ export declare const TestRefSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type TestRef = z.infer<typeof TestRefSchema>;
 /**
- * Code binding for a FUNC element (CR-GC-205 Item 5, ontology bump 3.6.0).
- * Resolves a FUNC node to the concrete code symbol that realizes it, enabling
- * graph<->code conformance: every non-concept/non-external FUNC must resolve to a
- * real symbol in its allocated MOD's file, and (via the consumer's LSP-backed
- * check) every cross-module-called symbol must itself be a FUNC node.
- *   - `file`   : implementation file path, e.g. `src/harness.ts` (the symbol's home).
- *   - `symbol` : the exported symbol (function/method/class) name realizing the FUNC.
- *   - `lang`   : optional language id (default `ts`) — selects the LSP/engine the
- *               conformance check drives, so the binding is language-agnostic.
- * Stored under `OntologyElement.attributes.codeRef` (additive, opt-in validation).
+ * Realization binding for an element (CR-228, ontology bump 3.9.0) — unifies the
+ * byte-identical former `codeRef` (FUNC → code symbol) and `schemaRef` (SCHEMA →
+ * Zod export), and extends to MOD (physical part → CAD/geometry artefact). The
+ * *type* of the pointing element disambiguates what kind of realization it is:
+ * FUNC→code, SCHEMA→Zod-def, physical MOD→CAD. TEST keeps its own `testRef`
+ * (a TEST is not just located but *executed* — the runner is the extra value).
+ *   - `file`   : realization file path, e.g. `src/harness.ts`, `part.step`.
+ *   - `symbol` : the realizing symbol (function/class/Zod export). Optional — a
+ *               geometry artefact (CAD) has no symbol; file-exists is the binding.
+ *   - `lang`   : optional language/format id (default `ts`) — selects the
+ *               conformance engine, so the binding is language-agnostic.
+ * Stored under `OntologyElement.attributes.realRef` (additive, opt-in validation).
+ * The free-text SCHEMA `contract` attribute stays a human description, not the
+ * conformance basis: RC-01/RC-03 resolve this binding, RC-04 checks it is parsed.
  */
-export declare const CodeRefSchema: z.ZodObject<{
+export declare const RealRefSchema: z.ZodObject<{
     file: z.ZodString;
-    symbol: z.ZodString;
+    symbol: z.ZodOptional<z.ZodString>;
     lang: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-export type CodeRef = z.infer<typeof CodeRefSchema>;
-/**
- * Binding of a SCHEMA node to the Zod schema that defines it (CR-211), analogous
- * to CodeRefSchema for FUNC:
- *   - `file`   : the source file declaring the Zod schema, e.g. `src/se/ontology.ts`.
- *   - `symbol` : the exported schema symbol, e.g. `CodeRefSchema`.
- *   - `lang`   : optional language id (default `ts`).
- * Stored under `OntologyElement.attributes.schemaRef`. The free-text `contract`
- * attribute stays as a human description but is no longer the conformance basis:
- * RC-03 resolves this binding to a declared export, RC-04 checks it is parsed at
- * the modelled interface.
- */
-export declare const SchemaRefSchema: z.ZodObject<{
-    file: z.ZodString;
-    symbol: z.ZodString;
-    lang: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export type SchemaRef = z.infer<typeof SchemaRefSchema>;
+export type RealRef = z.infer<typeof RealRefSchema>;
 /**
  * An element (node) in the SE ontology graph.
  * `attributes` holds type-specific properties (e.g. FUNC.safety_relevant).

package/dist/se/ontology.js

@@ -72,36 +72,24 @@ export const TestRefSchema = z.object({
     level: z.string().optional(),
 });
 /**
- * Code binding for a FUNC element (CR-GC-205 Item 5, ontology bump 3.6.0).
- * Resolves a FUNC node to the concrete code symbol that realizes it, enabling
- * graph<->code conformance: every non-concept/non-external FUNC must resolve to a
- * real symbol in its allocated MOD's file, and (via the consumer's LSP-backed
- * check) every cross-module-called symbol must itself be a FUNC node.
- *   - `file`   : implementation file path, e.g. `src/harness.ts` (the symbol's home).
- *   - `symbol` : the exported symbol (function/method/class) name realizing the FUNC.
- *   - `lang`   : optional language id (default `ts`) — selects the LSP/engine the
- *               conformance check drives, so the binding is language-agnostic.
- * Stored under `OntologyElement.attributes.codeRef` (additive, opt-in validation).
+ * Realization binding for an element (CR-228, ontology bump 3.9.0) — unifies the
+ * byte-identical former `codeRef` (FUNC → code symbol) and `schemaRef` (SCHEMA →
+ * Zod export), and extends to MOD (physical part → CAD/geometry artefact). The
+ * *type* of the pointing element disambiguates what kind of realization it is:
+ * FUNC→code, SCHEMA→Zod-def, physical MOD→CAD. TEST keeps its own `testRef`
+ * (a TEST is not just located but *executed* — the runner is the extra value).
+ *   - `file`   : realization file path, e.g. `src/harness.ts`, `part.step`.
+ *   - `symbol` : the realizing symbol (function/class/Zod export). Optional — a
+ *               geometry artefact (CAD) has no symbol; file-exists is the binding.
+ *   - `lang`   : optional language/format id (default `ts`) — selects the
+ *               conformance engine, so the binding is language-agnostic.
+ * Stored under `OntologyElement.attributes.realRef` (additive, opt-in validation).
+ * The free-text SCHEMA `contract` attribute stays a human description, not the
+ * conformance basis: RC-01/RC-03 resolve this binding, RC-04 checks it is parsed.
  */
-export const CodeRefSchema = z.object({
+export const RealRefSchema = z.object({
     file: RepoRelativePathSchema,
-    symbol: z.string(),
-    lang: z.string().optional(),
-});
-/**
- * Binding of a SCHEMA node to the Zod schema that defines it (CR-211), analogous
- * to CodeRefSchema for FUNC:
- *   - `file`   : the source file declaring the Zod schema, e.g. `src/se/ontology.ts`.
- *   - `symbol` : the exported schema symbol, e.g. `CodeRefSchema`.
- *   - `lang`   : optional language id (default `ts`).
- * Stored under `OntologyElement.attributes.schemaRef`. The free-text `contract`
- * attribute stays as a human description but is no longer the conformance basis:
- * RC-03 resolves this binding to a declared export, RC-04 checks it is parsed at
- * the modelled interface.
- */
-export const SchemaRefSchema = z.object({
-    file: RepoRelativePathSchema,
-    symbol: z.string(),
+    symbol: z.string().optional(),
     lang: z.string().optional(),
 });
 /**
@@ -188,8 +176,8 @@ export const ELEMENT_ATTRIBUTES = {
         { key: 'timingBudgetMs', type: 'number', description: 'NFR timing budget in ms' },
         { key: 'measuredMs', type: 'number', description: 'Measured execution time in ms' },
         { key: 'sourceFile', type: 'string', description: 'Implementation source file' },
-        { key: 'codeRef', type: 'object', description: 'Code binding {file, symbol, lang?} — the symbol that realizes this FUNC; see CodeRefSchema (CR-GC-205)' },
-        { key: 'external', type: 'boolean', description: 'Externally-realized FUNC (e.g. a renderer in another package): exempt from the R-20 codeRef-binding requirement (CR-GC-205)' },
+        { key: 'realRef', type: 'object', description: 'Realization binding {file, symbol?, lang?} — the code symbol that realizes this FUNC; see RealRefSchema (CR-228, was codeRef)' },
+        { key: 'external', type: 'boolean', description: 'Externally-realized FUNC (e.g. a renderer in another package): exempt from the R-20 realRef-binding requirement (CR-GC-205)' },
         { key: 'concept', type: 'boolean', description: 'Concept-only FUNC: specified, no implementation yet; exempt from R-20 (CR-GC-205)' },
     ],
     UC: [
@@ -206,11 +194,15 @@ export const ELEMENT_ATTRIBUTES = {
     ],
     MOD: [
         { key: 'path', type: 'string', description: 'Source file or glob the module owns, e.g. src/harness.ts — anchors the MOD<->file mapping for graph<->code conformance (CR-GC-205)' },
+        { key: 'kind', type: 'string', description: "Module kind, e.g. 'physical' for a machine part (Bauteil) — physical MODs are realized by a CAD/geometry realRef (R-27), logical MODs by their FUNCs' code (CR-191/228)" },
+        { key: 'realRef', type: 'object', description: 'Realization binding {file, symbol?, lang?} — CAD/geometry artefact realizing a physical MOD; see RealRefSchema (CR-228, symbol optional)' },
+        { key: 'external', type: 'boolean', description: 'Externally-realized MOD: exempt from the R-27 realRef-presence requirement (CR-228)' },
+        { key: 'concept', type: 'boolean', description: 'Concept-only MOD: modelled, no realization yet; exempt from R-27 (CR-228)' },
     ],
     SCHEMA: [
         { key: 'contract', type: 'string', description: 'Free-text contract description, e.g. "@sigloch/contracts LiveUpdateEventSchema" — human hint only, not the conformance basis (CR-211)' },
-        { key: 'schemaRef', type: 'object', description: 'Schema binding {file, symbol, lang?} — the Zod export defining this SCHEMA; see SchemaRefSchema (CR-211)' },
-        { key: 'external', type: 'boolean', description: 'Externally-defined SCHEMA (e.g. a foreign-API contract): exempt from the schemaRef-presence requirement (CR-211)' },
-        { key: 'concept', type: 'boolean', description: 'Concept-only SCHEMA: modelled, no Zod export yet; exempt from the schemaRef-presence requirement (CR-211)' },
+        { key: 'realRef', type: 'object', description: 'Realization binding {file, symbol?, lang?} — the Zod export defining this SCHEMA; see RealRefSchema (CR-228, was schemaRef)' },
+        { key: 'external', type: 'boolean', description: 'Externally-defined SCHEMA (e.g. a foreign-API contract): exempt from the realRef-presence requirement (CR-211)' },
+        { key: 'concept', type: 'boolean', description: 'Concept-only SCHEMA: modelled, no Zod export yet; exempt from the realRef-presence requirement (CR-211)' },
     ],
 };

package/dist/se/readiness.js

@@ -39,7 +39,7 @@ export const RULE_TO_DIMENSION = {
     'RD-01': 'req', 'RD-02': 'req', 'RD-03': 'req',
     // trace/realization/allocation completeness rules (CR-228 D: previously unmapped → advisory fall-through)
     'R-18': 'arch', 'R-19': 'ver', 'R-20': 'arch', 'R-21': 'ver',
-    'R-22': 'alloc', 'R-23': 'alloc', 'R-26': 'schema',
+    'R-22': 'alloc', 'R-23': 'alloc', 'R-26': 'schema', 'R-27': 'arch',
     // uc
     'UC-01': 'uc', 'UC-02': 'uc', 'UC-03': 'uc', 'UC-04': 'uc',
     'UC-05': 'uc', 'UC-06': 'uc',

package/dist/se/rules.js

@@ -4,7 +4,7 @@
  * @sigloch/contracts/se — single source of truth for SE validation rules.
  */
 import { z } from 'zod/v4';
-import { ElementType, TraceType, TestRefSchema, CodeRefSchema, SchemaRefSchema } from './ontology.js';
+import { ElementType, TraceType, TestRefSchema, RealRefSchema } from './ontology.js';
 import { isValidTrace } from './meta-model.js';
 export const RuleSeverity = z.enum(['error', 'warning', 'info']);
 /** Candidate target for resolving a violation (e.g. a REQ to satisfy, a TEST to link). */
@@ -581,10 +581,10 @@ function testMustHaveRunnableBinding(graph) {
     }));
 }
 // ---------------------------------------------------------------------------
-// R-20: FUNC code binding (CR-GC-205 Item 5, extended by CR-210) — a FUNC that
-// is not explicitly concept-only (attributes.concept === true) or externally
-// realized (attributes.external === true) counts as BOUND when it EITHER carries
-// a valid codeRef {file, symbol} OR is a blackbox parent whose compose→FUNC
+// R-20: FUNC realRef binding (CR-GC-205 Item 5, extended by CR-210, unified CR-228)
+// — a FUNC that is not explicitly concept-only (attributes.concept === true) or
+// externally realized (attributes.external === true) counts as BOUND when it EITHER
+// carries a valid realRef {file, symbol?} OR is a blackbox parent whose compose→FUNC
 // children are ALL (recursively) bound — the parent is realized by its children
 // (e.g. FUNC-gesture-capture, gve CR-GVE-150). A partially-bound parent fires
 // R-20 naming the still-unbound leaves in the fix_hint, so drift on a child is
@@ -598,7 +598,7 @@ function funcMustHaveCodeBinding(graph) {
     const composeFuncChildren = (id) => graph.traces
         .filter(t => t.source === id && t.type === 'compose' && funcById.has(t.target))
         .map(t => t.target);
-    const hasCodeRef = (el) => CodeRefSchema.safeParse(el.attributes?.codeRef).success;
+    const hasCodeRef = (el) => RealRefSchema.safeParse(el.attributes?.realRef).success;
     const isExempt = (el) => el.attributes?.concept === true || el.attributes?.external === true;
     // A FUNC is bound iff it is exempt, has a codeRef, or is a parent whose
     // compose→FUNC children are all bound (recursive, cycle-safe).
@@ -662,8 +662,8 @@ function funcMustHaveCodeBinding(graph) {
                 rule_id: 'R-20',
                 severity: 'warning',
                 element_id: fn.id,
-                message: `${fn.id} is a FUNC without a valid codeRef binding`,
-                fix_hint: 'Add attributes.codeRef {file, symbol, lang?}, or set attributes.concept:true (spec-only) / attributes.external:true (realized in another package)',
+                message: `${fn.id} is a FUNC without a valid realRef binding`,
+                fix_hint: 'Add attributes.realRef {file, symbol, lang?}, or set attributes.concept:true (spec-only) / attributes.external:true (realized in another package)',
                 context: { element_type: fn.type, element_name: fn.name },
             });
         }
@@ -800,28 +800,52 @@ function modMustHaveAllocatedFunc(graph) {
 // MOD→satisfy→REQ, behavioral NFRs FCHAIN→satisfy→REQ. R-18 now flags any residual
 // REQ→MOD allocate edge as an invalid trace pattern.
 // ---------------------------------------------------------------------------
-// R-26: SCHEMA schemaRef presence (CR-211) — a SCHEMA that is not explicitly
-// concept-only or external should carry a valid schemaRef {file, symbol} so its
-// Zod definition is machine-resolvable (RC-03 then checks it resolves, RC-04 that
-// it is parsed at the interface). WARNING, not error: the 9 currently-unbound
-// SCHEMAs on the reference model must not turn readiness red before any binding
-// exists — the presence signal mirrors R-20 (codeRef) / R-19 (testRef). Symbol
-// RESOLUTION is out of scope here (pure, no I/O — that is RC-03's job).
+// R-26: SCHEMA realRef presence (CR-211, unified CR-228) — a SCHEMA that is not
+// explicitly concept-only or external should carry a valid realRef {file, symbol?}
+// so its Zod definition is machine-resolvable (RC-03 then checks it resolves, RC-04
+// that it is parsed at the interface). WARNING, not error: currently-unbound SCHEMAs
+// on the reference model must not turn readiness red before any binding exists — the
+// presence signal mirrors R-20 (FUNC realRef) / R-19 (testRef). Symbol RESOLUTION is
+// out of scope here (pure, no I/O — that is RC-03's job).
 // ---------------------------------------------------------------------------
 function schemaMustHaveSchemaRef(graph) {
     return graph.elements
         .filter(e => e.type === 'SCHEMA')
         .filter(e => e.attributes?.concept !== true && e.attributes?.external !== true)
-        .filter(e => !SchemaRefSchema.safeParse(e.attributes?.schemaRef).success)
+        .filter(e => !RealRefSchema.safeParse(e.attributes?.realRef).success)
         .map(sc => ({
         rule_id: 'R-26',
         severity: 'warning',
         element_id: sc.id,
-        message: `${sc.id} is a SCHEMA without a valid schemaRef binding`,
-        fix_hint: 'Add attributes.schemaRef {file, symbol, lang?}, or set attributes.concept:true (spec-only) / attributes.external:true (foreign-API contract)',
+        message: `${sc.id} is a SCHEMA without a valid realRef binding`,
+        fix_hint: 'Add attributes.realRef {file, symbol, lang?}, or set attributes.concept:true (spec-only) / attributes.external:true (foreign-API contract)',
         context: { element_type: sc.type, element_name: sc.name },
     }));
 }
+// ---------------------------------------------------------------------------
+// R-27: physical MOD realRef presence (CR-228) — the MOD arm of the unified
+// "element must have a realRef" rule (FUNC=R-20, SCHEMA=R-26, physical MOD=R-27).
+// A physical MOD (kind='physical') is a Bauteil realized by a CAD/geometry
+// artefact, not by code (RT-01: FUNCs never allocate directly to it). Logical/SW
+// MODs are realized through their FUNCs' code (R-20) and are NOT in scope here.
+// WARNING (presence signal like R-20/R-26); concept/external MODs are exempt.
+// Symbol is optional on a realRef (a geometry file has none) — presence = a valid
+// realRef with a file. RESOLUTION (file on disk) is a consumer/RC concern.
+// ---------------------------------------------------------------------------
+function physicalModMustHaveRealRef(graph) {
+    return graph.elements
+        .filter(e => e.type === 'MOD' && e.attributes?.kind === 'physical')
+        .filter(e => e.attributes?.concept !== true && e.attributes?.external !== true)
+        .filter(e => !RealRefSchema.safeParse(e.attributes?.realRef).success)
+        .map(mod => ({
+        rule_id: 'R-27',
+        severity: 'warning',
+        element_id: mod.id,
+        message: `${mod.id} is a physical MOD without a valid realRef (CAD/geometry) binding`,
+        fix_hint: 'Add attributes.realRef {file, symbol?, lang?} pointing at the CAD/geometry artefact, or set attributes.concept:true / attributes.external:true',
+        context: { element_type: mod.type, element_name: mod.name },
+    }));
+}
 export const V3_RULES = [
     { id: 'R-01', name: 'REQ must have verification', severity: 'error', evaluate: reqMustHaveVerification },
     { id: 'R-02', name: 'FUNC must satisfy REQ', severity: 'warning', evaluate: funcMustSatisfyReq },
@@ -837,11 +861,12 @@ export const V3_RULES = [
     { id: 'R-12', name: 'No circular dependencies', severity: 'warning', evaluate: noDirectCircular },
     { id: 'R-18', name: 'Valid trace pattern', severity: 'error', evaluate: validTracePattern },
     { id: 'R-19', name: 'Runnable TEST binding', severity: 'warning', evaluate: testMustHaveRunnableBinding },
-    { id: 'R-20', name: 'FUNC code binding', severity: 'warning', evaluate: funcMustHaveCodeBinding },
+    { id: 'R-20', name: 'FUNC realRef binding', severity: 'warning', evaluate: funcMustHaveCodeBinding },
     { id: 'R-21', name: 'FUNC↔FUNC connection needs integration test', severity: 'warning', evaluate: fchainMustHaveIntegrationTest },
     { id: 'R-22', name: 'FUNC must be allocated to MOD', severity: 'warning', evaluate: funcMustBeAllocated },
     { id: 'R-23', name: 'MOD must have allocated FUNC', severity: 'warning', evaluate: modMustHaveAllocatedFunc },
-    { id: 'R-26', name: 'SCHEMA must have schemaRef', severity: 'warning', evaluate: schemaMustHaveSchemaRef },
+    { id: 'R-26', name: 'SCHEMA must have realRef', severity: 'warning', evaluate: schemaMustHaveSchemaRef },
+    { id: 'R-27', name: 'Physical MOD must have realRef', severity: 'warning', evaluate: physicalModMustHaveRealRef },
     { id: 'RD-01', name: 'Unresolved requirement', severity: 'warning', evaluate: unresolvedRequirement },
     { id: 'RD-02', name: 'Decomposition consistency', severity: 'warning', evaluate: decompositionConsistency },
     { id: 'RD-03', name: 'No premature decomposition', severity: 'info', evaluate: noPrematureDecomposition },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigloch/contracts",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",