@sigloch/contracts 0.7.0

package/dist/se/schema-quality-rules.d.ts

@@ -0,0 +1,11 @@
+/**
+ * SC-01..SC-03 — Schema Quality rules (CR-122).
+ * Complement V3 structural rules with content checks on SCHEMA elements.
+ */
+import type { OntologyGraph } from './ontology.js';
+import type { RuleDefinition, RuleViolation } from './rules.js';
+export declare function sc01HasDefinition(graph: OntologyGraph): RuleViolation[];
+export declare function sc02IsReferenced(graph: OntologyGraph): RuleViolation[];
+export declare function sc03IsImplemented(graph: OntologyGraph): RuleViolation[];
+export declare const SC_RULES: RuleDefinition[];
+export declare function evaluateSCRules(graph: OntologyGraph): RuleViolation[];

package/dist/se/schema-quality-rules.js

@@ -0,0 +1,73 @@
+// ---------------------------------------------------------------------------
+// SC-01: SCHEMA must have zodDefinition attribute
+// ---------------------------------------------------------------------------
+export function sc01HasDefinition(graph) {
+    return graph.elements
+        .filter(e => e.type === 'SCHEMA')
+        .filter(s => {
+        const def = s.attributes?.zodDefinition;
+        return !def || (typeof def === 'string' && def.trim().length === 0);
+    })
+        .map(s => ({
+        rule_id: 'SC-01',
+        severity: 'warning',
+        element_id: s.id,
+        message: `${s.id} has no zodDefinition attribute`,
+        fix_hint: 'Add zodDefinition attribute with Zod schema string',
+        context: {
+            element_type: s.type,
+            element_name: s.name,
+        },
+    }));
+}
+// ---------------------------------------------------------------------------
+// SC-02: SCHEMA must be referenced by at least one FLOW via relation trace
+// ---------------------------------------------------------------------------
+export function sc02IsReferenced(graph) {
+    const flows = graph.elements.filter(e => e.type === 'FLOW');
+    return graph.elements
+        .filter(e => e.type === 'SCHEMA')
+        .filter(s => !graph.traces.some(t => t.target === s.id && t.type === 'relation'))
+        .map(s => ({
+        rule_id: 'SC-02',
+        severity: 'warning',
+        element_id: s.id,
+        message: `${s.id} not referenced by any FLOW`,
+        fix_hint: 'Link at least one FLOW to this SCHEMA via relation trace',
+        context: {
+            element_type: s.type,
+            element_name: s.name,
+            candidate_targets: flows.map(f => ({ id: f.id, type: f.type, name: f.name })),
+        },
+    }));
+}
+// ---------------------------------------------------------------------------
+// SC-03: SCHEMA should have sourceFile (implementation marker)
+// ---------------------------------------------------------------------------
+export function sc03IsImplemented(graph) {
+    return graph.elements
+        .filter(e => e.type === 'SCHEMA')
+        .filter(s => !s.attributes?.sourceFile && !s.attributes?.sourceExport)
+        .map(s => ({
+        rule_id: 'SC-03',
+        severity: 'info',
+        element_id: s.id,
+        message: `${s.id} has no sourceFile/sourceExport (not implemented yet)`,
+        fix_hint: 'Implement the Zod schema in code and set sourceFile/sourceExport',
+        context: {
+            element_type: s.type,
+            element_name: s.name,
+        },
+    }));
+}
+// ---------------------------------------------------------------------------
+// Aggregated array & convenience runner
+// ---------------------------------------------------------------------------
+export const SC_RULES = [
+    { id: 'SC-01', name: 'Schema has definition', severity: 'warning', evaluate: sc01HasDefinition },
+    { id: 'SC-02', name: 'Schema referenced by FLOW', severity: 'warning', evaluate: sc02IsReferenced },
+    { id: 'SC-03', name: 'Schema is implemented', severity: 'info', evaluate: sc03IsImplemented },
+];
+export function evaluateSCRules(graph) {
+    return SC_RULES.flatMap(rule => rule.evaluate(graph));
+}

package/dist/se/semantic-id.d.ts

@@ -0,0 +1,30 @@
+/**
+ * SemanticId — Format-E canonical element ID schema.
+ * Aligned with graphengine CR-052/CR-053.
+ *
+ * Format: {Name}.{TypeAbbr}.{Counter}
+ * Example: ObserveSessions.UC.001
+ *
+ * @sigloch/contracts/se
+ */
+import { z } from 'zod/v4';
+import type { ElementType } from './ontology.js';
+/** 2-char abbreviation → full ElementType. */
+export declare const ABBREV_TO_TYPE: Record<string, ElementType>;
+/** Full ElementType → 2-char abbreviation. */
+export declare const TYPE_TO_ABBREV: Record<string, string>;
+/** SemanticId: `Name.TypeAbbr.Counter` where Counter is 3-digit or 6-char alphanumeric. */
+export declare const SemanticId: z.ZodString;
+export type SemanticId = z.infer<typeof SemanticId>;
+/** Check if a string is a valid SemanticId. */
+export declare function isSemanticId(s: string): boolean;
+/** Extract name, type, and counter from a SemanticId. */
+export declare function extractFromSemanticId(semanticId: string): {
+    name: string;
+    type: ElementType;
+    counter: string;
+};
+/** Build a SemanticId from parts. */
+export declare function toSemanticId(name: string, type: ElementType, counter: string): string;
+/** Get the 2-char abbreviation for an ElementType. */
+export declare function getTypeAbbreviation(type: ElementType): string;

package/dist/se/semantic-id.js

@@ -0,0 +1,90 @@
+/**
+ * SemanticId — Format-E canonical element ID schema.
+ * Aligned with graphengine CR-052/CR-053.
+ *
+ * Format: {Name}.{TypeAbbr}.{Counter}
+ * Example: ObserveSessions.UC.001
+ *
+ * @sigloch/contracts/se
+ */
+import { z } from 'zod/v4';
+// ---------------------------------------------------------------------------
+// Type abbreviation maps (aligned with graphengine semantic-id.ts)
+// ---------------------------------------------------------------------------
+/** 2-char abbreviation → full ElementType. */
+export const ABBREV_TO_TYPE = {
+    SY: 'SYS',
+    UC: 'UC',
+    RQ: 'REQ',
+    FN: 'FUNC',
+    FC: 'FCHAIN',
+    FL: 'FLOW',
+    AC: 'ACTOR',
+    MD: 'MOD',
+    TC: 'TEST',
+    TS: 'TEST', // legacy alias
+    SC: 'SCHEMA',
+    CR: 'CR',
+    MS: 'MS',
+};
+/** Full ElementType → 2-char abbreviation. */
+export const TYPE_TO_ABBREV = {
+    SYS: 'SY',
+    UC: 'UC',
+    REQ: 'RQ',
+    FUNC: 'FN',
+    FCHAIN: 'FC',
+    FLOW: 'FL',
+    ACTOR: 'AC',
+    MOD: 'MD',
+    TEST: 'TC',
+    SCHEMA: 'SC',
+    SESSION: 'SE',
+    CR: 'CR',
+    MS: 'MS',
+};
+// ---------------------------------------------------------------------------
+// Zod schema
+// ---------------------------------------------------------------------------
+/** SemanticId: `Name.TypeAbbr.Counter` where Counter is 3-digit or 6-char alphanumeric. */
+export const SemanticId = z.string().regex(/^[A-Za-z][A-Za-z0-9_+]{0,49}\.[A-Z]{2}\.[a-z0-9]{3,6}$/, 'SemanticId must match {Name}.{TypeAbbr}.{Counter}');
+// ---------------------------------------------------------------------------
+// Pure functions
+// ---------------------------------------------------------------------------
+/** Check if a string is a valid SemanticId. */
+export function isSemanticId(s) {
+    return SemanticId.safeParse(s).success;
+}
+/** Extract name, type, and counter from a SemanticId. */
+export function extractFromSemanticId(semanticId) {
+    const parts = semanticId.split('.');
+    if (parts.length < 3) {
+        throw new Error(`Invalid semanticId: "${semanticId}" — expected Name.TypeAbbr.Counter`);
+    }
+    const name = parts[0];
+    const typeAbbr = parts[1];
+    const type = ABBREV_TO_TYPE[typeAbbr];
+    if (!type) {
+        throw new Error(`Unknown type abbreviation "${typeAbbr}" in: "${semanticId}"`);
+    }
+    return { name, type, counter: parts[2] };
+}
+/** Build a SemanticId from parts. */
+export function toSemanticId(name, type, counter) {
+    const abbr = TYPE_TO_ABBREV[type];
+    if (!abbr)
+        throw new Error(`No abbreviation for type: ${type}`);
+    const sanitized = sanitizeName(name);
+    return `${sanitized}.${abbr}.${counter}`;
+}
+/** Get the 2-char abbreviation for an ElementType. */
+export function getTypeAbbreviation(type) {
+    return TYPE_TO_ABBREV[type] ?? type.slice(0, 2).toUpperCase();
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Sanitize a name for SemanticId: PascalCase, only alnum + underscore + plus, max 50 chars. */
+function sanitizeName(name) {
+    return name.replace(/[^a-zA-Z0-9_+]/g, '').slice(0, 50);
+}

package/dist/se/uc-quality-rules.d.ts

@@ -0,0 +1,13 @@
+/**
+ * UC-01..UC-06 — Use Case quality rules (CR-121 Phase 1).
+ */
+import type { OntologyGraph } from './ontology.js';
+import type { RuleDefinition, RuleViolation } from './rules.js';
+export declare function uc01HasRequirements(graph: OntologyGraph): RuleViolation[];
+export declare function uc02HasActor(graph: OntologyGraph): RuleViolation[];
+export declare function uc03HasScenario(graph: OntologyGraph): RuleViolation[];
+export declare function uc04GoalDefined(graph: OntologyGraph): RuleViolation[];
+export declare function uc05HasPostcondition(graph: OntologyGraph): RuleViolation[];
+export declare function uc06HasPrecondition(graph: OntologyGraph): RuleViolation[];
+export declare const UC_RULES: RuleDefinition[];
+export declare function evaluateUCRules(graph: OntologyGraph): RuleViolation[];

package/dist/se/uc-quality-rules.js

@@ -0,0 +1,123 @@
+// ---------------------------------------------------------------------------
+// UC-01: UC must have compose→REQ trace (CR-165: satisfy UC→REQ is invalid per meta-model)
+// ---------------------------------------------------------------------------
+export function uc01HasRequirements(graph) {
+    return graph.elements
+        .filter(e => e.type === 'UC')
+        .filter(uc => !graph.traces.some(t => t.source === uc.id && t.type === 'compose' && graph.elements.some(e => e.id === t.target && e.type === 'REQ')))
+        .map(uc => ({
+        rule_id: 'UC-01',
+        severity: 'error',
+        element_id: uc.id,
+        message: `${uc.id} has no requirements (compose→REQ)`,
+        fix_hint: 'Add at least one REQ via compose trace',
+        context: { element_type: uc.type, element_name: uc.name },
+    }));
+}
+// ---------------------------------------------------------------------------
+// UC-02: UC FCHAIN must have an ACTOR with io trace
+// ---------------------------------------------------------------------------
+export function uc02HasActor(graph) {
+    return graph.elements
+        .filter(e => e.type === 'UC')
+        .filter(uc => {
+        // Check if any ACTOR has io trace to this UC or to a FCHAIN/FLOW in this UC
+        return !graph.traces.some(t => t.type === 'io' &&
+            graph.elements.some(e => e.id === t.source && e.type === 'ACTOR') &&
+            (t.target === uc.id || graph.traces.some(ct => ct.source === uc.id && ct.type === 'compose' && ct.target === t.target)));
+    })
+        .map(uc => ({
+        rule_id: 'UC-02',
+        severity: 'error',
+        element_id: uc.id,
+        message: `${uc.id} has no ACTOR with io trace`,
+        fix_hint: 'Link an ACTOR via io trace to this UC or its FCHAIN',
+        context: { element_type: uc.type, element_name: uc.name },
+    }));
+}
+// ---------------------------------------------------------------------------
+// UC-03: UC must have compose→FCHAIN (scenario)
+// ---------------------------------------------------------------------------
+export function uc03HasScenario(graph) {
+    return graph.elements
+        .filter(e => e.type === 'UC')
+        .filter(uc => !graph.traces.some(t => t.source === uc.id && t.type === 'compose' &&
+        graph.elements.some(e => e.id === t.target && e.type === 'FCHAIN')))
+        .map(uc => ({
+        rule_id: 'UC-03',
+        severity: 'warning',
+        element_id: uc.id,
+        message: `${uc.id} has no FCHAIN scenario`,
+        fix_hint: 'Add a FCHAIN via compose trace to define behavioral scenario',
+        context: { element_type: uc.type, element_name: uc.name },
+    }));
+}
+// ---------------------------------------------------------------------------
+// UC-04: UC must have meaningful description (CR-150: description = goal)
+// ---------------------------------------------------------------------------
+const UC_DESC_MIN_LEN = 10;
+const PLACEHOLDER_RE = /\b(tbd|todo|fixme|placeholder|xxx)\b/i;
+export function uc04GoalDefined(graph) {
+    return graph.elements
+        .filter(e => e.type === 'UC')
+        .filter(uc => {
+        const d = uc.description?.trim() ?? '';
+        return d.length < UC_DESC_MIN_LEN || PLACEHOLDER_RE.test(d);
+    })
+        .map(uc => ({
+        rule_id: 'UC-04',
+        severity: 'warning',
+        element_id: uc.id,
+        message: `${uc.id} description is missing or contains placeholders (description = goal per CR-150)`,
+        fix_hint: `Provide a meaningful description (min ${UC_DESC_MIN_LEN} chars, no TBD/TODO)`,
+        context: { element_type: uc.type, element_name: uc.name },
+    }));
+}
+// ---------------------------------------------------------------------------
+// UC-05: UC should have postcondition REQ (CR-165: compose only, satisfy UC→REQ invalid)
+// ---------------------------------------------------------------------------
+export function uc05HasPostcondition(graph) {
+    return graph.elements
+        .filter(e => e.type === 'UC')
+        .filter(uc => !graph.traces.some(t => t.source === uc.id && t.type === 'compose' &&
+        graph.elements.some(e => e.id === t.target && e.type === 'REQ' && e.kinds?.includes('postcondition'))))
+        .map(uc => ({
+        rule_id: 'UC-05',
+        severity: 'info',
+        element_id: uc.id,
+        message: `${uc.id} has no postcondition requirement`,
+        fix_hint: 'Add a REQ with kinds=["postcondition"] via compose trace',
+        context: { element_type: uc.type, element_name: uc.name },
+    }));
+}
+// ---------------------------------------------------------------------------
+// UC-06: UC should have precondition REQ (CR-165: compose only, satisfy UC→REQ invalid)
+// ---------------------------------------------------------------------------
+export function uc06HasPrecondition(graph) {
+    return graph.elements
+        .filter(e => e.type === 'UC')
+        .filter(uc => !graph.traces.some(t => t.source === uc.id && t.type === 'compose' &&
+        graph.elements.some(e => e.id === t.target && e.type === 'REQ' && e.kinds?.includes('precondition'))))
+        .map(uc => ({
+        rule_id: 'UC-06',
+        severity: 'info',
+        element_id: uc.id,
+        message: `${uc.id} has no precondition requirement`,
+        fix_hint: 'Add a REQ with kinds=["precondition"] via compose trace',
+        context: { element_type: uc.type, element_name: uc.name },
+    }));
+}
+// ---------------------------------------------------------------------------
+// Aggregated
+// ---------------------------------------------------------------------------
+export const UC_RULES = [
+    { id: 'UC-01', name: 'UC has requirements', severity: 'error', evaluate: uc01HasRequirements },
+    { id: 'UC-02', name: 'UC has actor', severity: 'error', evaluate: uc02HasActor },
+    { id: 'UC-03', name: 'UC has scenario', severity: 'warning', evaluate: uc03HasScenario },
+    { id: 'UC-04', name: 'UC has goal', severity: 'warning', evaluate: uc04GoalDefined },
+    { id: 'UC-05', name: 'UC has postcondition', severity: 'info', evaluate: uc05HasPostcondition },
+    { id: 'UC-06', name: 'UC has precondition', severity: 'info', evaluate: uc06HasPrecondition },
+];
+export function evaluateUCRules(graph) {
+    return UC_RULES.flatMap(rule => rule.evaluate(graph));
+}

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

@@ -0,0 +1,11 @@
+/**
+ * CR-184: View-related quality rules.
+ * VR-01: TEST without testResult attribute (info).
+ * CL-01: ACTOR without UCs in at least 2 distinct operatingModes (warning).
+ */
+import type { OntologyGraph } from './ontology.js';
+import type { RuleViolation, RuleDefinition } from './rules.js';
+export declare function vr01TestNoResult(graph: OntologyGraph): RuleViolation[];
+export declare function cl01ConopsCompleteness(graph: OntologyGraph): RuleViolation[];
+export declare const VIEW_RULES: RuleDefinition[];
+export declare function evaluateViewRules(graph: OntologyGraph): RuleViolation[];

package/dist/se/view-rules.js

@@ -0,0 +1,56 @@
+// ---------------------------------------------------------------------------
+// VR-01: TEST without testResult
+// ---------------------------------------------------------------------------
+export function vr01TestNoResult(graph) {
+    return graph.elements
+        .filter(e => e.type === 'TEST' && e.attributes?.['testResult'] == null)
+        .map(e => ({
+        rule_id: 'VR-01',
+        severity: 'info',
+        element_id: e.id,
+        message: `${e.id} has no testResult — assumed pending`,
+    }));
+}
+// ---------------------------------------------------------------------------
+// CL-01: ACTOR without UCs in >= 2 distinct operatingModes
+// ---------------------------------------------------------------------------
+export function cl01ConopsCompleteness(graph) {
+    // Only fire when at least one UC has an operatingMode attribute
+    const anyUcHasMode = graph.elements.some(e => e.type === 'UC' && e.attributes?.['operatingMode'] != null);
+    if (!anyUcHasMode)
+        return [];
+    const actors = graph.elements.filter(e => e.type === 'ACTOR');
+    const violations = [];
+    for (const actor of actors) {
+        // Find all UCs linked via io trace
+        const ucIds = graph.traces
+            .filter(t => t.type === 'io' && t.source === actor.id)
+            .map(t => t.target);
+        const modes = new Set();
+        for (const ucId of ucIds) {
+            const uc = graph.elements.find(e => e.id === ucId && e.type === 'UC');
+            const mode = uc?.attributes?.['operatingMode'];
+            if (mode != null)
+                modes.add(String(mode));
+        }
+        if (modes.size < 2) {
+            violations.push({
+                rule_id: 'CL-01',
+                severity: 'warning',
+                element_id: actor.id,
+                message: `${actor.id} has UCs in only ${modes.size} distinct operatingMode(s) — expected at least 2`,
+            });
+        }
+    }
+    return violations;
+}
+// ---------------------------------------------------------------------------
+// Aggregated array & convenience runner
+// ---------------------------------------------------------------------------
+export const VIEW_RULES = [
+    { id: 'VR-01', name: 'TestNoResult', severity: 'info', evaluate: vr01TestNoResult },
+    { id: 'CL-01', name: 'ConopsCompleteness', severity: 'warning', evaluate: cl01ConopsCompleteness },
+];
+export function evaluateViewRules(graph) {
+    return VIEW_RULES.flatMap(rule => rule.evaluate(graph));
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@sigloch/contracts",
+  "version": "0.7.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./se": {
+      "types": "./dist/se/index.d.ts",
+      "default": "./dist/se/index.js"
+    },
+    "./harness": {
+      "types": "./dist/harness/index.d.ts",
+      "default": "./dist/harness/index.js"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "license": "MIT",
+  "description": "Zod contracts for the SE model layer — ontology, rules and harness schemas (single source of truth)",
+  "author": "sigloch-consulting",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andreassigloch/sigloch-modules.git",
+    "directory": "packages/contracts"
+  },
+  "homepage": "https://github.com/andreassigloch/sigloch-modules#readme",
+  "bugs": {
+    "url": "https://github.com/andreassigloch/sigloch-modules/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}