@principal-ai/subsystems-core 0.48.1 → 0.49.0

package/src/types/subsystem-model.ts

@@ -113,13 +113,29 @@ export interface SubsystemDeclToken {
   color?: string;
 }
 
-/** Anchored declaration location (usually from verify tooling). */
-export interface SubsystemDeclarationRef {
-  file: string;
+/**
+ * A content-addressed range of source — the model's identity primitive.
+ *
+ * A span is `startLine` + `endLine` + the hash of the normalized content
+ * across that range. Every claim is *anchored* to a span: a component's
+ * construct declaration (`declarationSpan`) and a trail step's runtime seam
+ * (`span`) are the same shape. `file` / `purl` live on the owner, so a span is
+ * a pure range + fingerprint.
+ *
+ * The hash is the identity: if live content re-hashes to `contentHash`, the
+ * anchored code is byte-identical, which is what lets verification reason about
+ * constructs rather than line changes.
+ */
+export interface SubsystemSourceSpan {
+  /** 1-based first line of the construct/seam within the owner's `file`. */
   startLine: number;
-  lineHash: string;
-  graphifyNodeId?: string;
-  capturedAt: string;
+  /** 1-based last line, inclusive. Always `>= startLine`. */
+  endLine: number;
+  /**
+   * SHA-256 of the normalized content across `[startLine, endLine]`, truncated
+   * to 32 hex chars. Produced by `hashContentRange`.
+   */
+  contentHash: string;
 }
 
 export interface SubsystemParamInfo {
@@ -376,8 +392,12 @@ export interface SubsystemComponent {
    */
   declarationProvenance?: SubsystemDeclarationProvenance;
   tokens?: SubsystemDeclToken[];
-  /** Location anchor (file/line/hash) — distinct from `declaration` (shape). */
-  declarationRef?: SubsystemDeclarationRef;
+  /**
+   * The construct's source span (start/end/content hash) — its anchored
+   * identity. Distinct from `declaration`, which is the structured shape.
+   * Usually captured by verify tooling, not hand-authored.
+   */
+  declarationSpan?: SubsystemSourceSpan;
 }
 
 /**
@@ -399,8 +419,13 @@ export interface SubsystemTrailStep {
   /** Runtime seam label (Set B). */
   mechanism: SubsystemTrailMechanism;
   file: string;
-  /** 1-based line within `file`. */
-  line: number;
+  /**
+   * The seam's source span — the call-site range and its content hash. The
+   * trail-step counterpart of a component's `declarationSpan`, captured by
+   * verify tooling from the call site. `file` + `symbol` locate the frame;
+   * absent until verification anchors it.
+   */
+  span?: SubsystemSourceSpan;
   /**
    * File-anchored purl of the seam site (e.g.
    * `pkg:github/owner/name#path/to/file.ts`), mirroring component `purl`.

package/src/validation.test.ts

@@ -32,7 +32,7 @@ describe('validateSubsystemModelCrossField', () => {
         {
           id: 'w1',
           title: 'flow',
-          steps: [{ from: 'a', to: 'b', mechanism: 'calls', file: 'src/a.ts', line: 1, purl: 'pkg:github/acme/app#src/a.ts', symbol: 'a' }],
+          steps: [{ from: 'a', to: 'b', mechanism: 'calls', file: 'src/a.ts', purl: 'pkg:github/acme/app#src/a.ts', symbol: 'a' }],
         },
       ],
     });
@@ -55,7 +55,7 @@ describe('validateSubsystemModelCrossField', () => {
           {
             id: 'w1',
             title: 'flow',
-            steps: [{ from: 'ghost', to: 'a', mechanism: 'calls', file: 'src/a.ts', line: 1, purl: 'pkg:github/acme/app#src/a.ts', symbol: 'ghost' }],
+            steps: [{ from: 'ghost', to: 'a', mechanism: 'calls', file: 'src/a.ts', purl: 'pkg:github/acme/app#src/a.ts', symbol: 'ghost' }],
           },
         ],
       }),
@@ -72,7 +72,7 @@ describe('validateSubsystemModelCrossField', () => {
           {
             id: 'w1',
             title: 'flow',
-            steps: [{ from: 'a', to: 'a', mechanism: 'calls', file: 'src/a.ts', line: 1, purl: 'pkg:github/acme/app#src/other.ts', symbol: 'a' }],
+            steps: [{ from: 'a', to: 'a', mechanism: 'calls', file: 'src/a.ts', purl: 'pkg:github/acme/app#src/other.ts', symbol: 'a' }],
           },
         ],
       }),
@@ -161,7 +161,6 @@ describe('validateSubsystemModelCrossField', () => {
                 to: 'a',
                 mechanism: 'calls',
                 file: 'packages/react/node_modules/@pierre/diffs/dist/index.js',
-                line: 1,
                 purl: 'pkg:npm/@pierre/diffs#packages/react/node_modules/@pierre/diffs/dist/index.js',
                 symbol: 'a',
               },
@@ -173,4 +172,68 @@ describe('validateSubsystemModelCrossField', () => {
     expect(problems).toHaveLength(1);
     expect(problems[0]!.path).toBe('/trails/0/steps/0/file');
   });
+
+  test('accepts an ordered span on a component and a step', () => {
+    expect(
+      validateSubsystemModelCrossField(
+        doc({
+          components: [
+            comp('a', {
+              declarationSpan: { startLine: 1, endLine: 9, contentHash: 'h' },
+            }),
+          ],
+          trails: [
+            {
+              id: 'w1',
+              title: 'flow',
+              steps: [
+                {
+                  from: 'a',
+                  to: 'a',
+                  mechanism: 'calls',
+                  file: 'src/a.ts',
+                  purl: 'pkg:github/acme/app#src/a.ts',
+                  symbol: 'a',
+                  span: { startLine: 3, endLine: 3, contentHash: 'h' },
+                },
+              ],
+            },
+          ],
+        }),
+      ),
+    ).toEqual([]);
+  });
+
+  test('flags a span whose endLine precedes startLine', () => {
+    const problems = validateSubsystemModelCrossField(
+      doc({
+        components: [
+          comp('a', {
+            declarationSpan: { startLine: 10, endLine: 4, contentHash: 'h' },
+          }),
+        ],
+        trails: [
+          {
+            id: 'w1',
+            title: 'flow',
+            steps: [
+              {
+                from: 'a',
+                to: 'a',
+                mechanism: 'calls',
+                file: 'src/a.ts',
+                purl: 'pkg:github/acme/app#src/a.ts',
+                symbol: 'a',
+                span: { startLine: 8, endLine: 2, contentHash: 'h' },
+              },
+            ],
+          },
+        ],
+      }),
+    );
+    expect(problems).toHaveLength(2);
+    expect(problems[0]!.path).toBe('/components/0/declarationSpan');
+    expect(problems[0]!.message).toContain('precedes startLine');
+    expect(problems[1]!.path).toBe('/trails/0/steps/0/span');
+  });
 });

package/src/validation.ts

@@ -14,6 +14,7 @@
 import type {
   SubsystemModelDocument,
   SubsystemComponent,
+  SubsystemSourceSpan,
   SubsystemTrail,
 } from './types/subsystem-model';
 
@@ -53,6 +54,27 @@ function mentionsNodeModules(path: string): boolean {
   return /(^|\/)node_modules(\/|$)/.test(path);
 }
 
+/**
+ * A span's range must be ordered: `endLine >= startLine`. The schema enforces
+ * that each line is a positive integer but cannot compare two fields, so the
+ * ordering rule lives here. `owner` prefixes the message (e.g.
+ * `component "save"`).
+ */
+function spanRangeProblem(
+  span: SubsystemSourceSpan | undefined,
+  path: string,
+  owner: string,
+): SubsystemValidationProblem | null {
+  if (!span) return null;
+  if (span.endLine < span.startLine) {
+    return {
+      path,
+      message: `${owner}: span endLine ${span.endLine} precedes startLine ${span.startLine} — a span range must be ordered (endLine >= startLine).`,
+    };
+  }
+  return null;
+}
+
 /**
  * Validate the cross-field rules of a subsystem model document. Returns an
  * empty array when the document is consistent.
@@ -97,6 +119,12 @@ export function validateSubsystemModelCrossField(
         message: `component ${JSON.stringify(c.alias)}: file ${JSON.stringify(file)} points into node_modules — installed artifacts are not part of the repo and cannot be verified. Model the dependency as construct "external" with purl "pkg:npm/<package>" and no file, or anchor the claim to the package's real source.`,
       });
     }
+    const spanProblem = spanRangeProblem(
+      c.declarationSpan,
+      `/components/${i}/declarationSpan`,
+      `component ${JSON.stringify(c.alias)}`,
+    );
+    if (spanProblem) problems.push(spanProblem);
   });
 
   trails.forEach((w: SubsystemTrail, ti) => {
@@ -131,6 +159,12 @@ export function validateSubsystemModelCrossField(
           message: `trail ${JSON.stringify(w.id)}: step ${si} file ${JSON.stringify(step.file)} points into node_modules — anchor the seam at the call site inside the repo instead.`,
         });
       }
+      const spanProblem = spanRangeProblem(
+        step.span,
+        `/trails/${ti}/steps/${si}/span`,
+        `trail ${JSON.stringify(w.id)}: step ${si}`,
+      );
+      if (spanProblem) problems.push(spanProblem);
     });
   });