@principal-ai/subsystems-core 0.49.2 → 0.51.0

package/src/types/subsystem-model.ts

@@ -13,8 +13,7 @@
  *
  * Ontology: construct = what a node is, framework + stereotype = which
  * framework pattern it plays, role = where it sits, process = where it runs,
- * module = which source file/module the export belongs to,
- * proposed = not yet in source (design / migration placeholder).
+ * module = which source file/module the export belongs to.
  * Package (repo) frames are derived from component `purl` when a graph spans
  * multiple repos — there is no separate `package` field.
  * `symbol` is the code identity; `name` is the display label.
@@ -325,19 +324,10 @@ export interface SubsystemComponent {
   logo?: string;
   purpose?: string;
   role?: SubsystemComponentRole;
-  /**
-   * Design / migration placeholder — participates in edges and flows but is
-   * not a live source declaration yet. Verification skips source checks until
-   * promoted (`proposed` cleared, `file` + `symbol` filled). Orthogonal to
-   * `construct` (intended shape) and `role` (topology).
-   */
-  proposed?: boolean;
   /**
    * The claim was real but its source is gone — deleted or renamed upstream.
-   * The inverse of `proposed`: instead of "not built yet", this is "built once,
-   * removed since". Verification skips source checks exactly as it does for
-   * `proposed`, so a model carrying deprecations is no longer wedged on
-   * unfixable `missing_file` findings.
+   * Verification skips source checks so a model carrying deprecations is no
+   * longer wedged on unfixable `missing_file` findings.
    *
    * This is a transitional marker, not a resting state. A cleanup pass removes
    * the component and repairs the trails that referenced it; the field exists so
@@ -411,6 +401,37 @@ export interface SubsystemComponentEdge {
   mechanism: SubsystemEdgeMechanism;
 }
 
+/**
+ * The construct that contains a seam site. The site is always in the step's
+ * own file/repo (`step.file` / `step.purl`), so it carries only the construct
+ * identity and its full declaration range.
+ */
+export interface SubsystemSiteConstruct {
+  /** Caller construct symbol (e.g. `MaintenanceModelList`, `Registry.start`). */
+  symbol: string;
+  /** Full declaration range of the construct, not just the seam line. */
+  span: SubsystemSourceSpan;
+  /** Declaration shape, when known (function, method, class, …). */
+  construct?: SubsystemConstruct;
+}
+
+/**
+ * The construct a seam reaches. Unlike `site`, the target can live in another
+ * repo, so it carries its own purl + file. `span` is the target declaration
+ * range when it resolves; it can be absent for externals or unresolved targets.
+ */
+export interface SubsystemTargetConstruct {
+  /** File-anchored purl of the target repo/file. */
+  purl: string;
+  file: string;
+  /** Callee construct symbol (e.g. `mergeProvenance`, `Store.add`). */
+  symbol: string;
+  /** Full declaration range of the target, when resolvable. */
+  span?: SubsystemSourceSpan;
+  /** Declaration shape, when known. */
+  construct?: SubsystemConstruct;
+}
+
 export interface SubsystemTrailStep {
   /** Source component alias. */
   from: string;
@@ -428,6 +449,19 @@ export interface SubsystemTrailStep {
    * unverified and the Trails view has no line to highlight.
    */
   span?: SubsystemSourceSpan;
+  /**
+   * The construct containing the seam site, with its full declaration range.
+   * Required when `mechanism` is `calls`: the caller frame must be housed by
+   * the `from` component. For `uses` and data/event seams it is the via-site
+   * evidence and remains optional.
+   */
+  site?: SubsystemSiteConstruct;
+  /**
+   * The construct the seam reaches. Distinct from `to` (a component alias):
+   * the target can be a method on a modeled component, or a construct that is
+   * not a node at all. Optional; populated from accepted call-site evidence.
+   */
+  target?: SubsystemTargetConstruct;
   /**
    * File-anchored purl of the seam site (e.g.
    * `pkg:github/owner/name#path/to/file.ts`), mirroring component `purl`.
@@ -441,14 +475,6 @@ export interface SubsystemTrailStep {
    * mechanism + filename fallback.
    */
   symbol: string;
-  /**
-   * Planned seam — the step describes intended behavior through code that is
-   * not written yet. Orthogonal to (and redundant with) the endpoints' own
-   * `proposed` flags: a step is proposed when it says so OR either endpoint
-   * is proposed. Verification skips source checks either way, and viewers
-   * tint it exactly like a proposed node.
-   */
-  proposed?: boolean;
   /**
    * Free-text note anchored to this step's site line. Optional — informative
    * only, never verified against source; viewers surface it via the codeview's

package/src/validation.test.ts

@@ -81,7 +81,70 @@ describe('validateSubsystemModelCrossField', () => {
     expect(problems[0]!.path).toBe('/trails/0/steps/0/purl');
   });
 
-  test('module implies file, exempting external/proposed', () => {
+  test('flags a site construct that does not contain the seam span', () => {
+    const problems = validateSubsystemModelCrossField(
+      doc({
+        components: [comp('a'), comp('b')],
+        trails: [
+          {
+            id: 'w1',
+            title: 'flow',
+            steps: [
+              {
+                from: 'a',
+                to: 'b',
+                mechanism: 'calls',
+                file: 'src/a.ts',
+                purl: 'pkg:github/acme/app#src/a.ts',
+                symbol: 'a',
+                span: { startLine: 20, endLine: 20, contentHash: 'h' },
+                site: {
+                  symbol: 'a',
+                  span: { startLine: 1, endLine: 10, contentHash: 'h' },
+                },
+              },
+            ],
+          },
+        ],
+      }),
+    );
+    expect(problems.some((p) => p.path === '/trails/0/steps/0/site/span')).toBe(true);
+    expect(problems.find((p) => p.path === '/trails/0/steps/0/site/span')!.message).toContain(
+      'does not contain the seam span',
+    );
+  });
+
+  test('flags a target purl fragment that mismatches the target file', () => {
+    const problems = validateSubsystemModelCrossField(
+      doc({
+        components: [comp('a'), comp('b')],
+        trails: [
+          {
+            id: 'w1',
+            title: 'flow',
+            steps: [
+              {
+                from: 'a',
+                to: 'b',
+                mechanism: 'calls',
+                file: 'src/a.ts',
+                purl: 'pkg:github/acme/app#src/a.ts',
+                symbol: 'a',
+                target: {
+                  purl: 'pkg:github/acme/app#src/b-other.ts',
+                  file: 'src/b.ts',
+                  symbol: 'b',
+                },
+              },
+            ],
+          },
+        ],
+      }),
+    );
+    expect(problems.some((p) => p.path === '/trails/0/steps/0/target/purl')).toBe(true);
+  });
+
+  test('module implies file, exempting external', () => {
     const bad = validateSubsystemModelCrossField(
       doc({ components: [comp('a', { module: 'src/host', file: '' })] }),
     );
@@ -93,7 +156,6 @@ describe('validateSubsystemModelCrossField', () => {
         doc({
           components: [
             comp('ext', { module: 'pkg:npm/x', construct: 'external', file: '' }),
-            comp('plan', { module: 'src/host', file: '', proposed: true }),
             comp('ok', { module: 'src/host', file: 'src/host/main.ts' }),
           ],
         }),
@@ -126,7 +188,7 @@ describe('validateSubsystemModelCrossField', () => {
     expect(problems[2]!.path).toBe('/components/2/file');
   });
 
-  test('accepts node_modules only as an external/proposed component identity', () => {
+  test('accepts an external identity and a node_modulesx directory', () => {
     expect(
       validateSubsystemModelCrossField(
         doc({
@@ -137,8 +199,6 @@ describe('validateSubsystemModelCrossField', () => {
               file: '',
               purl: 'pkg:npm/@pierre/diffs',
             }),
-            // A planned in-repo component may sit where it will live.
-            comp('plan', { file: 'packages/x/node_modules/y/z.ts', proposed: true }),
             // `node_modulesx` is an ordinary directory, not the install root.
             comp('ok', { file: 'packages/node_modulesx/z.ts' }),
           ],

package/src/validation.ts

@@ -25,14 +25,10 @@ export interface SubsystemValidationProblem {
 }
 
 function isUngrounded(c: SubsystemComponent): boolean {
-  // Deprecated components are exempt for the same reason proposed ones are: the
-  // file is a historical pointer to source that is gone, so it cannot resolve
-  // and its absence is not an inconsistency.
-  return (
-    c.construct === 'external' ||
-    c.proposed === true ||
-    c.deprecated === true
-  );
+  // Deprecated components are exempt: the file is a historical pointer to
+  // source that is gone, so it cannot resolve and its absence is not an
+  // inconsistency.
+  return c.construct === 'external' || c.deprecated === true;
 }
 
 /**
@@ -44,8 +40,7 @@ function isUngrounded(c: SubsystemComponent): boolean {
  * Such a component is a third-party dependency: model it as `construct:
  * 'external'` with `purl: 'pkg:npm/<package>'` and no file. Applies to externals
  * too — they carry no file by design, so an install path there is dead weight
- * that draws a link nothing can open. `proposed` is exempt like every other
- * grounding rule: its file is a placeholder for something not placed yet.
+ * that draws a link nothing can open.
  *
  * The same rule covers trail step files — a seam into an external belongs
  * at the call site in the caller, which *is* in the repo.
@@ -99,18 +94,17 @@ export function validateSubsystemModelCrossField(
       ids.add(c.alias);
     }
     // A grounded component that claims a `module` needs a `file` to ground the
-    // frame. Externals / proposed carry no file by design.
+    // frame. Externals carry no file by design.
     const module = typeof c.module === 'string' ? c.module.trim() : '';
     const file = typeof c.file === 'string' ? c.file.trim() : '';
     if (module && !file && !isUngrounded(c)) {
       problems.push({
         path: `/components/${i}/module`,
-        message: `component ${JSON.stringify(c.alias)}: module ${JSON.stringify(module)} is set but file is empty — a module frame needs a file to ground it (mark the component proposed if it is not placed yet).`,
+        message: `component ${JSON.stringify(c.alias)}: module ${JSON.stringify(module)} is set but file is empty — a module frame needs a file to ground it.`,
       });
     }
     if (
       file &&
-      c.proposed !== true &&
       c.deprecated !== true &&
       mentionsNodeModules(file)
     ) {
@@ -165,6 +159,56 @@ export function validateSubsystemModelCrossField(
         `trail ${JSON.stringify(w.id)}: step ${si}`,
       );
       if (spanProblem) problems.push(spanProblem);
+
+      // The site construct is the enclosing frame; the seam line must live
+      // inside it. The schema can enforce each range but not containment.
+      const siteSpanProblem = spanRangeProblem(
+        step.site?.span,
+        `/trails/${ti}/steps/${si}/site/span`,
+        `trail ${JSON.stringify(w.id)}: step ${si} site`,
+      );
+      if (siteSpanProblem) problems.push(siteSpanProblem);
+      if (
+        step.span &&
+        step.site?.span &&
+        !(
+          step.site.span.startLine <= step.span.startLine &&
+          step.span.endLine <= step.site.span.endLine
+        )
+      ) {
+        problems.push({
+          path: `/trails/${ti}/steps/${si}/site/span`,
+          message: `trail ${JSON.stringify(w.id)}: step ${si} site span ${step.site.span.startLine}-${step.site.span.endLine} does not contain the seam span ${step.span.startLine}-${step.span.endLine}.`,
+        });
+      }
+
+      // The target is a construct in its own file, so its span and purl
+      // fragment are checked independently of the step's site file.
+      const targetSpanProblem = spanRangeProblem(
+        step.target?.span,
+        `/trails/${ti}/steps/${si}/target/span`,
+        `trail ${JSON.stringify(w.id)}: step ${si} target`,
+      );
+      if (targetSpanProblem) problems.push(targetSpanProblem);
+      if (
+        step.target &&
+        typeof step.target.purl === 'string' &&
+        step.target.purl.includes('#')
+      ) {
+        const fragment = step.target.purl.split('#').slice(1).join('#');
+        if (fragment !== step.target.file) {
+          problems.push({
+            path: `/trails/${ti}/steps/${si}/target/purl`,
+            message: `trail ${JSON.stringify(w.id)}: step ${si} target purl fragment ${JSON.stringify(fragment)} does not match target file ${JSON.stringify(step.target.file)}`,
+          });
+        }
+      }
+      if (step.target && mentionsNodeModules(step.target.file)) {
+        problems.push({
+          path: `/trails/${ti}/steps/${si}/target/file`,
+          message: `trail ${JSON.stringify(w.id)}: step ${si} target file ${JSON.stringify(step.target.file)} points into node_modules — model the dependency as an external instead.`,
+        });
+      }
     });
   });