@sigloch/graphcode-client 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -19,5 +19,5 @@
 export { HOST_SOCK_BASENAME, callHost, type ShimRequest, type ShimResponse, } from './host-client.js';
 export { MARKDOWN_VIEWS, VIEW_FILENAMES, type MarkdownView } from './view-catalog.js';
 export { GRAPHCODE_INCOSE_SCOPE, PHASE_GATE_RULES, PHASE_GATE_LABELS, PHASE_GATE_CREATIONS, IMPL_GATE_PHASE, IMPL_GATE_MILESTONES, IMPL_GATE_RULES, ABSENT_CREATION_PROVIDER, creationBlockingMsg, summarizeReadiness, computeReadiness, scoreReadiness, getFamilyRuleIds, type IncoseScope, type CreationCurrency, type CreationCurrencyProvider, type ReadinessDimension, type ReadinessGate, type ReadinessReport, } from './readiness.js';
-export { NEUTRAL_COMPLETENESS, COMPLETENESS_SLICES, scoreCompleteness, typeOf, hasOutTo, refFile, hasTestRef, hasCodeRef, isLeafFunc, fchainActorBounded, type CGraph, type CNode, type GateCompleteness, type CompletenessLeg, } from './readiness-completeness.js';
+export { NEUTRAL_COMPLETENESS, COMPLETENESS_SLICES, scoreCompleteness, typeOf, type CGraph, type CNode, type GateCompleteness, type CompletenessLeg, } from './readiness-completeness.js';
 export * from './panels.js';

package/dist/index.js

@@ -19,5 +19,5 @@
 export { HOST_SOCK_BASENAME, callHost, } from './host-client.js';
 export { MARKDOWN_VIEWS, VIEW_FILENAMES } from './view-catalog.js';
 export { GRAPHCODE_INCOSE_SCOPE, PHASE_GATE_RULES, PHASE_GATE_LABELS, PHASE_GATE_CREATIONS, IMPL_GATE_PHASE, IMPL_GATE_MILESTONES, IMPL_GATE_RULES, ABSENT_CREATION_PROVIDER, creationBlockingMsg, summarizeReadiness, computeReadiness, scoreReadiness, getFamilyRuleIds, } from './readiness.js';
-export { NEUTRAL_COMPLETENESS, COMPLETENESS_SLICES, scoreCompleteness, typeOf, hasOutTo, refFile, hasTestRef, hasCodeRef, isLeafFunc, fchainActorBounded, } from './readiness-completeness.js';
+export { NEUTRAL_COMPLETENESS, COMPLETENESS_SLICES, scoreCompleteness, typeOf, } from './readiness-completeness.js';
 export * from './panels.js';

package/dist/panels.d.ts

@@ -16,6 +16,7 @@
  */
 import type { ReadinessReport, ReadinessGate, CreationCurrency, CreationCurrencyProvider } from './readiness.js';
 import type { RuleViolation, LiveUpdateEvent } from '@sigloch/contracts/harness';
+import type { Graph } from '@sigloch/graph-api-core';
 export interface GatePanel {
     id: string;
     label: string;
@@ -125,6 +126,23 @@ export declare function creationCurrencyProvider(analysis: Array<{
     id: string;
     currency: CreationCurrency;
 }>): CreationCurrencyProvider;
+/**
+ * Real scope-currency for the 5 analysis artifacts (CR-SM-227) — replaces the
+ * `ABSENT_CREATION_PROVIDER` placeholder (CR-GVE-225 F10: GVE showed `absent`
+ * correctly because no scope-currency check existed yet). Reads the
+ * `graphVersion` freshness stamp AF-01..05 (contracts) check for presence of
+ * (`SYS.attributes.analysisFreshness.<id>`) and classifies it against the
+ * live graphVersion: missing/invalid stamp → absent; stamp older than the
+ * current graphVersion → stale; stamp at (or ahead of) it → current.
+ * Grober Graph-Versions-Stempel only, no scope-hash — CR-SM-227's declared
+ * first-cut limitation ("Achtung" section), not full scope-precise staleness.
+ */
+export declare function computeAnalysisCurrency(graph: Pick<Graph, 'nodes'>, currentGraphVersion: number): Array<{
+    id: string;
+    currency: CreationCurrency;
+}>;
+/** Convenience: build the real CreationCurrencyProvider straight off the graph + its live version. */
+export declare function analysisCreationCurrencyProvider(graph: Pick<Graph, 'nodes'>, currentGraphVersion: number): CreationCurrencyProvider;
 export interface ImpactPanel {
     root: string;
     blastRadiusNodes: number;

package/dist/panels.js

@@ -1,3 +1,4 @@
+import { AnalysisArtifactId, AnalysisFreshnessStampSchema } from '@sigloch/contracts/se';
 function toGatePanel(g) {
     return { id: g.id, label: g.label, passed: g.passed, score: g.score, blocking: g.blocking, completeness: g.completeness };
 }
@@ -94,6 +95,34 @@ export function creationCurrencyProvider(analysis) {
     const m = new Map(analysis.map((a) => [a.id, a.currency]));
     return (creation) => m.get(creation) ?? 'absent';
 }
+/**
+ * Real scope-currency for the 5 analysis artifacts (CR-SM-227) — replaces the
+ * `ABSENT_CREATION_PROVIDER` placeholder (CR-GVE-225 F10: GVE showed `absent`
+ * correctly because no scope-currency check existed yet). Reads the
+ * `graphVersion` freshness stamp AF-01..05 (contracts) check for presence of
+ * (`SYS.attributes.analysisFreshness.<id>`) and classifies it against the
+ * live graphVersion: missing/invalid stamp → absent; stamp older than the
+ * current graphVersion → stale; stamp at (or ahead of) it → current.
+ * Grober Graph-Versions-Stempel only, no scope-hash — CR-SM-227's declared
+ * first-cut limitation ("Achtung" section), not full scope-precise staleness.
+ */
+export function computeAnalysisCurrency(graph, currentGraphVersion) {
+    const sys = graph.nodes.find((n) => n.type === 'SYS');
+    const stamps = (sys?.attributes?.analysisFreshness ?? {});
+    return AnalysisArtifactId.options.map((id) => {
+        const parsed = AnalysisFreshnessStampSchema.safeParse(stamps[id]);
+        const currency = !parsed.success
+            ? 'absent'
+            : parsed.data.graphVersion >= currentGraphVersion
+                ? 'current'
+                : 'stale';
+        return { id, currency };
+    });
+}
+/** Convenience: build the real CreationCurrencyProvider straight off the graph + its live version. */
+export function analysisCreationCurrencyProvider(graph, currentGraphVersion) {
+    return creationCurrencyProvider(computeAnalysisCurrency(graph, currentGraphVersion));
+}
 export function impactPanel(impact) {
     return { root: impact.rootId, blastRadiusNodes: impact.nodeCount, blastRadiusEdges: impact.edgeCount };
 }

package/dist/readiness-completeness.d.ts

@@ -1,17 +1,28 @@
 /**
  * readiness-completeness.ts — the COMPLETENESS dimension of readiness (CR-GC-250,
- * split out of readiness.ts by CR-GC-260).
+ * split out of readiness.ts by CR-GC-260; rebuilt on the rule stream CR-SM-226).
  *
  * Its own module because it answers a different question than the rest of readiness:
  * compliance/gates ask "does any element violate a rule", completeness asks "is the
  * structural chain covered at all" — the absence case rules cannot see (0 FCHAIN → a
  * per-element warning rule fires 0 times and the gate reads green).
  *
+ * CR-SM-226: every leg now reads off a named `@sigloch/contracts` rule instead of
+ * re-walking the graph locally. The former local out-edge/actor-boundary/testRef/
+ * codeRef/leaf-function helpers were a SECOND, drifting implementation of exactly
+ * what R-15/UC-01/UC-03/FC-04/SC-04/R-19/R-20 already check in `@sigloch/contracts/se`
+ * — deleted. The rule engine stays the single source of truth; this file only
+ * re-groups its violations by the DRIVING population per leg, so an EMPTY
+ * population still counts against the gate (the vacuous-complete case a
+ * per-element warning rule cannot see on its own — closed for real by
+ * `@sigloch/contracts/se`'s R-28 Ebenen-Präsenz, CR-SM-226).
+ *
  * BROWSER-SAFE — no `node:*` import may enter this file: the panels layer builds on it.
  *
  * @author andreas@siglochconsulting
  */
 import type { Graph } from '@sigloch/graph-api-core';
+import type { RuleViolation } from '@sigloch/contracts/harness';
 export type CGraph = Pick<Graph, 'nodes' | 'edges'>;
 export type CNode = Graph['nodes'][number];
 /** A gate's structural completeness over its driving population. */
@@ -25,40 +36,34 @@ export interface GateCompleteness {
 }
 /** Neutral completeness for gates that carry no chain slice (impl gates). */
 export declare const NEUTRAL_COMPLETENESS: GateCompleteness;
+export declare const typeOf: (byId: Map<string, CNode>, id: string) => string | undefined;
 /**
  * One completeness leg: every node of `sourceType` (the driving population)
- * must satisfy `holds`, else it is a `missing` source for the owning gate.
- * Cardinality legs use the id `"<SRC>→<TGT>"` so the drift test can match them
- * against the meta-model's `1..*` patterns.
+ * must carry NO violation of `ruleId` (its `@sigloch/contracts` rule twin),
+ * else it is a `missing` source for the owning gate. Cardinality legs use the
+ * id `"<SRC>→<TGT>"` so the drift test can match them against the
+ * meta-model's `1..*` patterns.
  */
 export interface CompletenessLeg {
     id: string;
     sourceType: string;
-    holds: (node: CNode, graph: CGraph, byId: Map<string, CNode>) => boolean;
+    ruleId: string;
 }
-export declare const typeOf: (byId: Map<string, CNode>, id: string) => string | undefined;
-/** True iff `src` has ≥1 out-edge of `edgeType` to a node of `targetType`. */
-export declare function hasOutTo(g: CGraph, byId: Map<string, CNode>, src: string, edgeType: string, targetType: string): boolean;
-export declare const refFile: (ref: unknown) => string | undefined;
-export declare const hasTestRef: (n: CNode) => boolean;
-export declare const hasCodeRef: (n: CNode) => boolean;
-/** A leaf FUNC has no `compose→FUNC` children (parents are realized by children — meta-model §28). */
-export declare const isLeafFunc: (n: CNode, g: CGraph, byId: Map<string, CNode>) => boolean;
-/**
- * A FCHAIN is actor-bounded iff its function set has a trigger AND a consumer:
- * `ACTOR —io→ FLOW —io→ FUNC∈chain` (entry) and `FUNC∈chain —io→ FLOW —io→ ACTOR`
- * (exit). Catches the "hollow chain" — functions with no who-triggers / who-consumes.
- */
-export declare function fchainActorBounded(fchain: CNode, g: CGraph, byId: Map<string, CNode>): boolean;
 /**
- * Phase-gate → chain legs that must be complete AT THAT PHASE. `concept:true`
- * stays valid through CDR (spec allows unbound tests/funcs); only TRR demands
- * real bindings. The `1..*` cardinality legs (SYS→UC, UC→FCHAIN, UC→REQ,
- * FCHAIN→FUNC) are drift-locked against the meta-model by TEST-readiness-completeness.
+ * Phase-gate → chain legs that must be complete AT THAT PHASE, each backed by
+ * its `@sigloch/contracts` rule twin (CR-SM-226):
+ *   SRR: SYS→UC ≈ R-17 (SYS must have compose; not UC-typed specifically —
+ *        no dedicated SYS→UC rule exists, R-17 is the closest twin),
+ *        UC→FCHAIN = UC-03, UC→REQ = UC-01.
+ *   PDR: FCHAIN→FUNC = R-15, FCHAIN-actor-bounded = FC-04 (trigger+consumer).
+ *   CDR: FLOW→SCHEMA = SC-04 (sharp per-FLOW version of SC-02).
+ *   TRR: TEST.testRef = R-19, FUNC.realRef = R-20.
  */
 export declare const COMPLETENESS_SLICES: Record<string, CompletenessLeg[]>;
 /**
  * Score one phase gate's structural completeness over its driving population.
  * `total === 0` (no source elements to cover) → vacuously complete (ratio 1).
+ * `violations` is the full rule-stream output (e.g. `harness.evaluateRules()`);
+ * only the leg's own `ruleId` is consulted per node.
  */
-export declare function scoreCompleteness(gateId: string, graph: CGraph): GateCompleteness;
+export declare function scoreCompleteness(gateId: string, graph: CGraph, violations: RuleViolation[]): GateCompleteness;

package/dist/readiness-completeness.js

@@ -1,78 +1,62 @@
 /** Neutral completeness for gates that carry no chain slice (impl gates). */
 export const NEUTRAL_COMPLETENESS = { covered: 0, total: 0, missing: [] };
 export const typeOf = (byId, id) => byId.get(id)?.type;
-/** True iff `src` has ≥1 out-edge of `edgeType` to a node of `targetType`. */
-export function hasOutTo(g, byId, src, edgeType, targetType) {
-    return g.edges.some((e) => e.sourceId === src && e.edgeType === edgeType && typeOf(byId, e.targetId) === targetType);
-}
-export const refFile = (ref) => ref?.file;
-export const hasTestRef = (n) => !!refFile(n.attributes?.testRef);
-export const hasCodeRef = (n) => !!refFile(n.attributes?.realRef);
-/** A leaf FUNC has no `compose→FUNC` children (parents are realized by children — meta-model §28). */
-export const isLeafFunc = (n, g, byId) => !hasOutTo(g, byId, n.uid, 'compose', 'FUNC');
-/**
- * A FCHAIN is actor-bounded iff its function set has a trigger AND a consumer:
- * `ACTOR —io→ FLOW —io→ FUNC∈chain` (entry) and `FUNC∈chain —io→ FLOW —io→ ACTOR`
- * (exit). Catches the "hollow chain" — functions with no who-triggers / who-consumes.
- */
-export function fchainActorBounded(fchain, g, byId) {
-    const funcs = new Set(g.edges.filter((e) => e.sourceId === fchain.uid && e.edgeType === 'compose' && typeOf(byId, e.targetId) === 'FUNC').map((e) => e.targetId));
-    if (funcs.size === 0)
-        return false;
-    const io = g.edges.filter((e) => e.edgeType === 'io');
-    const entry = io.some((e) => funcs.has(e.targetId) && typeOf(byId, e.sourceId) === 'FLOW' &&
-        io.some((a) => a.targetId === e.sourceId && typeOf(byId, a.sourceId) === 'ACTOR'));
-    const exit = io.some((e) => funcs.has(e.sourceId) && typeOf(byId, e.targetId) === 'FLOW' &&
-        io.some((a) => a.sourceId === e.targetId && typeOf(byId, a.targetId) === 'ACTOR'));
-    return entry && exit;
-}
 /**
- * Phase-gate → chain legs that must be complete AT THAT PHASE. `concept:true`
- * stays valid through CDR (spec allows unbound tests/funcs); only TRR demands
- * real bindings. The `1..*` cardinality legs (SYS→UC, UC→FCHAIN, UC→REQ,
- * FCHAIN→FUNC) are drift-locked against the meta-model by TEST-readiness-completeness.
+ * Phase-gate → chain legs that must be complete AT THAT PHASE, each backed by
+ * its `@sigloch/contracts` rule twin (CR-SM-226):
+ *   SRR: SYS→UC ≈ R-17 (SYS must have compose; not UC-typed specifically —
+ *        no dedicated SYS→UC rule exists, R-17 is the closest twin),
+ *        UC→FCHAIN = UC-03, UC→REQ = UC-01.
+ *   PDR: FCHAIN→FUNC = R-15, FCHAIN-actor-bounded = FC-04 (trigger+consumer).
+ *   CDR: FLOW→SCHEMA = SC-04 (sharp per-FLOW version of SC-02).
+ *   TRR: TEST.testRef = R-19, FUNC.realRef = R-20.
  */
 export const COMPLETENESS_SLICES = {
     // Behavioral spine exists: system has use cases, every UC derives a chain AND requirements.
     SRR: [
-        { id: 'SYS→UC', sourceType: 'SYS', holds: (n, g, b) => hasOutTo(g, b, n.uid, 'compose', 'UC') },
-        { id: 'UC→FCHAIN', sourceType: 'UC', holds: (n, g, b) => hasOutTo(g, b, n.uid, 'compose', 'FCHAIN') },
-        { id: 'UC→REQ', sourceType: 'UC', holds: (n, g, b) => hasOutTo(g, b, n.uid, 'compose', 'REQ') },
+        { id: 'SYS→UC', sourceType: 'SYS', ruleId: 'R-17' },
+        { id: 'UC→FCHAIN', sourceType: 'UC', ruleId: 'UC-03' },
+        { id: 'UC→REQ', sourceType: 'UC', ruleId: 'UC-01' },
     ],
     // Functional architecture: every chain has functions AND is actor-bounded (trigger + consumer).
     PDR: [
-        { id: 'FCHAIN→FUNC', sourceType: 'FCHAIN', holds: (n, g, b) => hasOutTo(g, b, n.uid, 'compose', 'FUNC') },
-        { id: 'FCHAIN-actor-bounded', sourceType: 'FCHAIN', holds: (n, g, b) => fchainActorBounded(n, g, b) },
+        { id: 'FCHAIN→FUNC', sourceType: 'FCHAIN', ruleId: 'R-15' },
+        { id: 'FCHAIN-actor-bounded', sourceType: 'FCHAIN', ruleId: 'FC-04' },
     ],
     // Interfaces carry a data contract: every FLOW has a SCHEMA (CR-GC-106 schema-before-code).
     CDR: [
-        { id: 'FLOW→SCHEMA', sourceType: 'FLOW', holds: (n, g, b) => hasOutTo(g, b, n.uid, 'relation', 'SCHEMA') },
+        { id: 'FLOW→SCHEMA', sourceType: 'FLOW', ruleId: 'SC-04' },
     ],
-    // Binding: tests are runnable and leaf functions carry code — concept no longer counts here.
+    // Binding: tests are runnable and functions carry code — concept/external exemptions
+    // are R-19/R-20's own business now (single source of truth), not re-decided here.
     TRR: [
-        { id: 'TEST.testRef', sourceType: 'TEST', holds: (n) => hasTestRef(n) },
-        { id: 'FUNC.realRef', sourceType: 'FUNC', holds: (n, g, b) => !isLeafFunc(n, g, b) || hasCodeRef(n) },
+        { id: 'TEST.testRef', sourceType: 'TEST', ruleId: 'R-19' },
+        { id: 'FUNC.realRef', sourceType: 'FUNC', ruleId: 'R-20' },
     ],
 };
 /**
  * Score one phase gate's structural completeness over its driving population.
  * `total === 0` (no source elements to cover) → vacuously complete (ratio 1).
+ * `violations` is the full rule-stream output (e.g. `harness.evaluateRules()`);
+ * only the leg's own `ruleId` is consulted per node.
  */
-export function scoreCompleteness(gateId, graph) {
+export function scoreCompleteness(gateId, graph, violations) {
     const legs = COMPLETENESS_SLICES[gateId] ?? [];
-    const byId = new Map(graph.nodes.map((n) => [n.uid, n]));
     let covered = 0;
     let total = 0;
     const missing = [];
     for (const leg of legs) {
+        const violatingIds = new Set(violations
+            .filter((v) => v.ruleId === leg.ruleId && v.elementId !== undefined)
+            .map((v) => v.elementId));
         for (const node of graph.nodes) {
             if (node.type !== leg.sourceType)
                 continue;
             total += 1;
-            if (leg.holds(node, graph, byId))
-                covered += 1;
-            else
+            if (violatingIds.has(node.uid))
                 missing.push(`${leg.id}: ${node.uid}`);
+            else
+                covered += 1;
         }
     }
     return { covered, total, missing };

package/dist/readiness.js

@@ -142,7 +142,8 @@ function scorePhaseGate(id, ruleIds, violations, creations, graph, currency) {
         ? creations.filter((c) => currency(c) !== 'current').map((c) => creationBlockingMsg(c, id))
         : [];
     // Structural completeness (CR-GC-250): one aggregated blocking line, not N warnings.
-    const completeness = scoreCompleteness(id, graph);
+    // CR-SM-226: reads off the SAME violations array (the rule stream), no re-walk.
+    const completeness = scoreCompleteness(id, graph, violations);
     const complete = completeness.covered === completeness.total;
     const completenessBlocking = complete
         ? []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigloch/graphcode-client",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,7 +17,7 @@
     "prepublishOnly": "npm run build && npm run test"
   },
   "dependencies": {
-    "@sigloch/contracts": "^2.0.0",
+    "@sigloch/contracts": "^3.0.0",
     "@sigloch/graph-api-core": "^2.0.0"
   },
   "license": "MIT",