@principal-ai/subsystems-core 0.31.3 → 0.32.0

package/dist/types/subsystem-model.d.ts

@@ -12,7 +12,8 @@
  *    Used by viewers and stores; not part of the portable standard.
  *
  * Ontology: construct = what a node is, framework + stereotype = which
- * framework pattern it plays, role = where it sits, process = where it runs.
+ * framework pattern it plays, role = where it sits, process = where it runs,
+ * proposed = not yet in source (design / migration placeholder).
  * `symbol` is the code identity; `name` is the display label.
  */
 /** What the node IS as a declaration. `module` is not an authored construct —
@@ -39,9 +40,21 @@ export type SubsystemFramework = string;
  * Empty when no framework pattern applies. Pair with `framework` when set.
  */
 export type SubsystemStereotype = string;
-/** How `from` relates to `to` on an edge. */
-export type SubsystemEdgeMechanism = 'imports' | 'imports_from' | 're_exports' | 'defines' | 'calls' | 'extends' | 'inherits' | 'implements' | 'mixes_in' | 'uses' | 'method' | 'references' | 'contains' | 'feeds' | 'produces' | 'writes' | 'reads' | 'watches' | 'registers-into';
-export type SubsystemCapture = 'edited' | 'analyzed' | 'referenced';
+/**
+ * Topology relation type — structural / module / type claims between
+ * components. Belongs on `relations[]`, not on walkthrough hops.
+ */
+export type SubsystemRelationType = 'imports' | 'imports_from' | 're_exports' | 'defines' | 'extends' | 'inherits' | 'implements' | 'mixes_in' | 'method' | 'references' | 'contains';
+/**
+ * Walkthrough hop mechanism — runtime seams with a `file:line` site.
+ * Belongs on walkthrough steps; graph edges for these are derived.
+ */
+export type SubsystemWalkthroughMechanism = 'calls' | 'uses' | 'feeds' | 'produces' | 'writes' | 'reads' | 'watches' | 'registers-into';
+/**
+ * Union used by derived graph edges / styling (topology relationType or
+ * walkthrough hop mechanism).
+ */
+export type SubsystemEdgeMechanism = SubsystemRelationType | SubsystemWalkthroughMechanism;
 export type SubsystemDeclarationProvenance = 'verified' | 'authored';
 export type SubsystemDeclTokenKind = 'keyword' | 'name' | 'member' | 'type' | 'punctuation' | 'string' | 'newline';
 export interface SubsystemDeclToken {
@@ -120,11 +133,46 @@ export interface SubsystemMethodDeclaration {
     parameters?: SubsystemParamInfo[];
     returnType?: string;
 }
+/** One generic type parameter, e.g. `T` or `K extends keyof StudioMessages`. */
+export interface SubsystemTypeParamInfo {
+    name: string;
+    /** Constraint written after `extends` (or language equivalent). */
+    constraint?: string;
+}
+/** A callable/function type: `(params) => returnType`. */
+export interface SubsystemCallableTypeInfo {
+    parameters?: SubsystemParamInfo[];
+    returnType?: string;
+}
+/** One enum member, with its optional literal value. */
+export interface SubsystemEnumMemberInfo {
+    name: string;
+    value?: string;
+}
+/**
+ * Type-family declaration (interface / type alias / enum). Structured buckets
+ * cover common shapes; `rhs` is the verbatim escape hatch when none fit.
+ */
 export interface SubsystemTypeDeclaration {
     kind: 'type';
     properties: SubsystemPropertyInfo[];
     usedBy: SubsystemReferenceInfo[];
     implementors: string[];
+    /** Generic type parameters, e.g. `<K extends keyof StudioMessages>`. */
+    generics?: SubsystemTypeParamInfo[];
+    /** Callable type — `(params) => returnType`. */
+    signature?: SubsystemCallableTypeInfo;
+    /** Enum members (name, optional literal value). */
+    enumMembers?: SubsystemEnumMemberInfo[];
+    /** Alias whose RHS is a plain reference, e.g. `ServerSessionRow[]`. */
+    aliasOf?: string;
+    /** Simple union of alternatives, e.g. `'started' | 'stopped'`. */
+    unionOf?: string[];
+    /**
+     * Verbatim RHS — escape hatch for shapes the structured fields can't
+     * express. Wins over every shape above when set.
+     */
+    rhs?: string;
 }
 export interface SubsystemModuleDeclaration {
     kind: 'module';
@@ -138,6 +186,11 @@ export interface SubsystemExternalDeclaration {
 }
 export interface SubsystemStoreDeclaration {
     kind: 'store';
+    /** Where retained state lives / who mediates access. Authored, never
+     *  extracted: `memory` (process-lifetime RAM), `disk` (this process
+     *  reads/writes files), or `external` (another system — db/service; carries
+     *  no `process`). */
+    storage?: 'memory' | 'disk' | 'external';
     properties: SubsystemPropertyInfo[];
 }
 /** A single authored attribute on a custom entity — free-form key/value. */
@@ -168,6 +221,13 @@ export interface SubsystemComponent {
     purl: 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;
     /**
      * Framework that owns the stereotype (e.g. `react`, `nestjs`).
      * Orthogonal to `construct` — a React component is still `construct: function`.
@@ -192,7 +252,6 @@ export interface SubsystemComponent {
      */
     color?: string;
     layer?: number;
-    capture?: SubsystemCapture;
     /** Structured declaration shape of the construct (params, members, …). */
     declaration?: SubsystemConstructDeclaration;
     declarationProvenance?: SubsystemDeclarationProvenance;
@@ -200,19 +259,35 @@ export interface SubsystemComponent {
     /** Location anchor (file/line/hash) — distinct from `declaration` (shape). */
     declarationRef?: SubsystemDeclarationRef;
 }
-/** A cross-component edge. */
-export interface SubsystemComponentEdge {
+/** A topology relation between components (structural / module / type). */
+export interface SubsystemRelation {
     id: string;
     /** Source component id. */
     from: string;
     /** Target component id (or external label). */
     to: string;
-    mechanism: SubsystemEdgeMechanism;
+    relationType: SubsystemRelationType;
     /** Concrete file/symbol evidence (often purls). */
     refs?: string[];
 }
-export interface SubsystemThroughlineStep {
-    edgeId: string;
+/**
+ * Derived / display graph edge used by renderers. Built from `relations`
+ * and/or walkthrough hops — not authored as its own document field.
+ */
+export interface SubsystemComponentEdge {
+    id: string;
+    from: string;
+    to: string;
+    mechanism: SubsystemEdgeMechanism;
+    refs?: string[];
+}
+export interface SubsystemWalkthroughStep {
+    /** Source component id. */
+    from: string;
+    /** Target component id. */
+    to: string;
+    /** Runtime seam label (Set B). */
+    mechanism: SubsystemWalkthroughMechanism;
     file: string;
     /** 1-based line within `file`. */
     line: number;
@@ -225,11 +300,11 @@ export interface SubsystemThroughlineStep {
      */
     annotation?: string;
 }
-/** Ordered execution story over existing edges (one per flow). */
-export interface SubsystemThroughline {
+/** Ordered runtime walkthrough (one named behavior story). */
+export interface SubsystemWalkthrough {
     id: string;
     title: string;
-    steps: SubsystemThroughlineStep[];
+    steps: SubsystemWalkthroughStep[];
 }
 export interface SubsystemRepoRef {
     owner: string;
@@ -249,8 +324,10 @@ export interface SubsystemModelDocument {
     title: string;
     description?: string;
     components: SubsystemComponent[];
-    edges: SubsystemComponentEdge[];
-    throughlines?: SubsystemThroughline[];
+    /** Topology relations (structural / module / type). May be empty. */
+    relations: SubsystemRelation[];
+    /** Runtime walkthroughs (ordered hops with sites). */
+    walkthroughs?: SubsystemWalkthrough[];
 }
 /**
  * Host/machine fields layered onto a portable document for local use.
@@ -299,4 +376,14 @@ export declare function isSubsystemModelDocument(value: unknown): value is Subsy
  * share surface that must stay schema-clean.
  */
 export declare function toPortableDocument(doc: SubsystemModelDocument): SubsystemModelDocument;
+/** Stable id for a derived graph edge from a relation or walkthrough hop. */
+export declare function derivedGraphEdgeId(from: string, to: string, mechanism: SubsystemEdgeMechanism): string;
+/**
+ * Build display edges for the graph canvas from topology relations and
+ * walkthrough hops (deduped by from/to/mechanism).
+ */
+export declare function deriveGraphEdges(doc: {
+    relations?: SubsystemRelation[];
+    walkthroughs?: SubsystemWalkthrough[];
+}): SubsystemComponentEdge[];
 //# sourceMappingURL=subsystem-model.d.ts.map

package/dist/types/subsystem-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subsystem-model.d.ts","sourceRoot":"","sources":["../../src/types/subsystem-model.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"subsystem-model.d.ts","sourceRoot":"","sources":["../../src/types/subsystem-model.ts"],"names":[],"mappings":"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"}

package/dist/types/subsystem-model.js

@@ -13,11 +13,12 @@
  *    Used by viewers and stores; not part of the portable standard.
  *
  * Ontology: construct = what a node is, framework + stereotype = which
- * framework pattern it plays, role = where it sits, process = where it runs.
+ * framework pattern it plays, role = where it sits, process = where it runs,
+ * proposed = not yet in source (design / migration placeholder).
  * `symbol` is the code identity; `name` is the display label.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toPortableDocument = exports.isSubsystemModelDocument = void 0;
+exports.deriveGraphEdges = exports.derivedGraphEdgeId = exports.toPortableDocument = exports.isSubsystemModelDocument = void 0;
 /**
  * Type guard: true when the value plausibly conforms to a portable
  * subsystem model. Shallow check — full validation belongs to the schema /
@@ -29,7 +30,7 @@ function isSubsystemModelDocument(value) {
     const v = value;
     return (typeof v.title === 'string' &&
         Array.isArray(v.components) &&
-        Array.isArray(v.edges));
+        Array.isArray(v.relations));
 }
 exports.isSubsystemModelDocument = isSubsystemModelDocument;
 /**
@@ -41,15 +42,54 @@ function toPortableDocument(doc) {
     const out = {
         title: doc.title,
         components: doc.components,
-        edges: doc.edges,
+        relations: doc.relations,
     };
     if (doc.$schema)
         out.$schema = doc.$schema;
     if (doc.description)
         out.description = doc.description;
-    if (doc.throughlines)
-        out.throughlines = doc.throughlines;
+    if (doc.walkthroughs)
+        out.walkthroughs = doc.walkthroughs;
     return out;
 }
 exports.toPortableDocument = toPortableDocument;
+/** Stable id for a derived graph edge from a relation or walkthrough hop. */
+function derivedGraphEdgeId(from, to, mechanism) {
+    return `${from}--${mechanism}-->${to}`;
+}
+exports.derivedGraphEdgeId = derivedGraphEdgeId;
+/**
+ * Build display edges for the graph canvas from topology relations and
+ * walkthrough hops (deduped by from/to/mechanism).
+ */
+function deriveGraphEdges(doc) {
+    const byId = new Map();
+    for (const r of doc.relations ?? []) {
+        const id = r.id || derivedGraphEdgeId(r.from, r.to, r.relationType);
+        if (!byId.has(id)) {
+            byId.set(id, {
+                id,
+                from: r.from,
+                to: r.to,
+                mechanism: r.relationType,
+                refs: r.refs,
+            });
+        }
+    }
+    for (const w of doc.walkthroughs ?? []) {
+        for (const step of w.steps) {
+            const id = derivedGraphEdgeId(step.from, step.to, step.mechanism);
+            if (!byId.has(id)) {
+                byId.set(id, {
+                    id,
+                    from: step.from,
+                    to: step.to,
+                    mechanism: step.mechanism,
+                });
+            }
+        }
+    }
+    return [...byId.values()];
+}
+exports.deriveGraphEdges = deriveGraphEdges;
 //# sourceMappingURL=subsystem-model.js.map

package/dist/types/subsystem-model.js.map

@@ -1 +1 @@
-{"version":3,"file":"subsystem-model.js","sourceRoot":"","sources":["../../src/types/subsystem-model.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;AAkWH;;;;GAIG;AACH,SAAgB,wBAAwB,CAAC,KAAc;IACrD,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,CAAC,GAAG,KAIT,CAAC;IACF,OAAO,CACL,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ;QAC3B,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC;QAC3B,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CACvB,CAAC;AACJ,CAAC;AAZD,4DAYC;AAED;;;;GAIG;AACH,SAAgB,kBAAkB,CAChC,GAA2B;IAE3B,MAAM,GAAG,GAA2B;QAClC,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,KAAK,EAAE,GAAG,CAAC,KAAK;KACjB,CAAC;IACF,IAAI,GAAG,CAAC,OAAO;QAAE,GAAG,CAAC,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IAC3C,IAAI,GAAG,CAAC,WAAW;QAAE,GAAG,CAAC,WAAW,GAAG,GAAG,CAAC,WAAW,CAAC;IACvD,IAAI,GAAG,CAAC,YAAY;QAAE,GAAG,CAAC,YAAY,GAAG,GAAG,CAAC,YAAY,CAAC;IAC1D,OAAO,GAAG,CAAC;AACb,CAAC;AAZD,gDAYC"}
+{"version":3,"file":"subsystem-model.js","sourceRoot":"","sources":["../../src/types/subsystem-model.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAqbH;;;;GAIG;AACH,SAAgB,wBAAwB,CAAC,KAAc;IACrD,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,CAAC,GAAG,KAIT,CAAC;IACF,OAAO,CACL,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ;QAC3B,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC;QAC3B,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAC3B,CAAC;AACJ,CAAC;AAZD,4DAYC;AAED;;;;GAIG;AACH,SAAgB,kBAAkB,CAChC,GAA2B;IAE3B,MAAM,GAAG,GAA2B;QAClC,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,SAAS,EAAE,GAAG,CAAC,SAAS;KACzB,CAAC;IACF,IAAI,GAAG,CAAC,OAAO;QAAE,GAAG,CAAC,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IAC3C,IAAI,GAAG,CAAC,WAAW;QAAE,GAAG,CAAC,WAAW,GAAG,GAAG,CAAC,WAAW,CAAC;IACvD,IAAI,GAAG,CAAC,YAAY;QAAE,GAAG,CAAC,YAAY,GAAG,GAAG,CAAC,YAAY,CAAC;IAC1D,OAAO,GAAG,CAAC;AACb,CAAC;AAZD,gDAYC;AAED,6EAA6E;AAC7E,SAAgB,kBAAkB,CAChC,IAAY,EACZ,EAAU,EACV,SAAiC;IAEjC,OAAO,GAAG,IAAI,KAAK,SAAS,MAAM,EAAE,EAAE,CAAC;AACzC,CAAC;AAND,gDAMC;AAED;;;GAGG;AACH,SAAgB,gBAAgB,CAAC,GAGhC;IACC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkC,CAAC;IACvD,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,SAAS,IAAI,EAAE,EAAE;QACnC,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,IAAI,kBAAkB,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC;QACpE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE;YACjB,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE;gBACX,EAAE;gBACF,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,EAAE,EAAE,CAAC,CAAC,EAAE;gBACR,SAAS,EAAE,CAAC,CAAC,YAAY;gBACzB,IAAI,EAAE,CAAC,CAAC,IAAI;aACb,CAAC,CAAC;SACJ;KACF;IACD,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,YAAY,IAAI,EAAE,EAAE;QACtC,KAAK,MAAM,IAAI,IAAI,CAAC,CAAC,KAAK,EAAE;YAC1B,MAAM,EAAE,GAAG,kBAAkB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;YAClE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE;gBACjB,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE;oBACX,EAAE;oBACF,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,EAAE,EAAE,IAAI,CAAC,EAAE;oBACX,SAAS,EAAE,IAAI,CAAC,SAAS;iBAC1B,CAAC,CAAC;aACJ;SACF;KACF;IACD,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;AAC5B,CAAC;AA/BD,4CA+BC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principal-ai/subsystems-core",
-  "version": "0.31.3",
+  "version": "0.32.0",
   "description": "Subsystem model types and agent-session tooling for Principal AI",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/schemas/subsystem-model.schema.json

@@ -2,12 +2,12 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://principal-ai.dev/schemas/subsystem-model.schema.json",
   "title": "Subsystem Model",
-  "description": "Portable subsystem model — the shareable standard. Construct-tagged components (nodes) plus typed edges describing one subsystem of a codebase. Ontology: construct = what a node is, framework + stereotype = which framework pattern it plays, role = where it sits, process = where it runs. Symbol is the code identity; name is the display label (often derived from symbol). Host-only fields (local path binding, provenance, store ids, verification) are NOT part of this document; they belong on a hydrated envelope around it.",
+  "description": "Portable subsystem model — the shareable standard. Construct-tagged components (nodes) plus topology relations and/or runtime walkthroughs describing one subsystem of a codebase. Ontology: construct = what a node is, framework + stereotype = which framework pattern it plays, role = where it sits, process = where it runs. Symbol is the code identity; name is the display label (often derived from symbol). Host-only fields (local path binding, provenance, store ids, verification) are NOT part of this document; they belong on a hydrated envelope around it.",
   "type": "object",
   "required": [
     "title",
     "components",
-    "edges"
+    "relations"
   ],
   "additionalProperties": false,
   "properties": {
@@ -31,18 +31,18 @@
         "$ref": "#/$defs/component"
       }
     },
-    "edges": {
+    "relations": {
       "type": "array",
-      "description": "Typed interactions between components. `from` / `to` reference component `id`s.",
+      "description": "Topology relations (structural / module / type). `from` / `to` reference component `id`s. Runtime seams belong on walkthrough steps, not here.",
       "items": {
-        "$ref": "#/$defs/edge"
+        "$ref": "#/$defs/relation"
       }
     },
-    "throughlines": {
+    "walkthroughs": {
       "type": "array",
-      "description": "Ordered execution stories over existing edges (one throughline per flow). Each step names an edge id, the concrete file:line where that seam fires, and an optional frame symbol.",
+      "description": "Ordered runtime walkthroughs (one per named behavior). Each step names from/to/mechanism and the concrete file:line where that seam fires.",
       "items": {
-        "$ref": "#/$defs/throughline"
+        "$ref": "#/$defs/walkthrough"
       }
     }
   },
@@ -70,6 +70,10 @@
         "service"
       ]
     },
+    "proposed": {
+      "type": "boolean",
+      "description": "Design / migration placeholder — not a live source declaration yet. Verification skips source checks until promoted. Keep a real construct for the intended shape."
+    },
     "framework": {
       "type": "string",
       "minLength": 1,
@@ -80,15 +84,6 @@
       "minLength": 1,
       "description": "Framework-level pattern stamped on a language construct (open string). Examples: component, hook, middleware, controller, guard. Prefer this over inventing framework-specific constructs. Pair with framework when set."
     },
-    "capture": {
-      "type": "string",
-      "description": "How the authoring session occupied this component.",
-      "enum": [
-        "edited",
-        "analyzed",
-        "referenced"
-      ]
-    },
     "declarationProvenance": {
       "type": "string",
       "description": "Where `declaration` came from. `verified` is reserved for tool-extracted data; hand-authored declarations must be `authored` (also the default when declaration is present without provenance).",
@@ -97,23 +92,29 @@
         "authored"
       ]
     },
-    "mechanism": {
+    "relationType": {
       "type": "string",
-      "description": "How `from` relates to `to`. Pick the closest label; put specifics in `refs`. `uses` = general dependency; `feeds` = data-flow into a processor; `produces` = emits an output; `references` = type/symbol reference that is not a call; `writes`/`reads`/`watches` = retained-state interactions.",
+      "description": "Topology relation type — structural / module / type claim between components.",
       "enum": [
         "imports",
         "imports_from",
         "re_exports",
         "defines",
-        "calls",
         "extends",
         "inherits",
         "implements",
         "mixes_in",
-        "uses",
         "method",
         "references",
-        "contains",
+        "contains"
+      ]
+    },
+    "mechanism": {
+      "type": "string",
+      "description": "Walkthrough hop mechanism — how `from` relates to `to` at a runtime site. `uses` = general dependency; `feeds` = data-flow into a processor; `produces` = emits an output; `writes`/`reads`/`watches` = retained-state interactions.",
+      "enum": [
+        "calls",
+        "uses",
         "feeds",
         "produces",
         "writes",
@@ -136,7 +137,7 @@
         "id": {
           "type": "string",
           "minLength": 1,
-          "description": "Stable unique id. Referenced by edge `from` / `to`; never rename on update."
+          "description": "Stable unique id. Referenced by relation / walkthrough `from` / `to`; never rename on update."
         },
         "name": {
           "type": "string",
@@ -174,6 +175,9 @@
         "role": {
           "$ref": "#/$defs/role"
         },
+        "proposed": {
+          "$ref": "#/$defs/proposed"
+        },
         "framework": {
           "$ref": "#/$defs/framework"
         },
@@ -188,9 +192,6 @@
           "type": "integer",
           "description": "Semantic layout layer/phase (lower = closer to entry). When set, layout places the component in this layer for a left-to-right pipeline."
         },
-        "capture": {
-          "$ref": "#/$defs/capture"
-        },
         "declaration": {
           "$ref": "#/$defs/constructDeclaration",
           "description": "Structured declaration shape of the construct for the click panel (parameters, members, etc.). Hand-author when highlighting specific inputs/outputs; set `declarationProvenance` accordingly."
@@ -211,20 +212,20 @@
         }
       }
     },
-    "edge": {
+    "relation": {
       "type": "object",
       "required": [
         "id",
         "from",
         "to",
-        "mechanism"
+        "relationType"
       ],
       "additionalProperties": false,
       "properties": {
         "id": {
           "type": "string",
           "minLength": 1,
-          "description": "Stable unique edge id. Referenced by throughline steps."
+          "description": "Stable unique relation id."
         },
         "from": {
           "type": "string",
@@ -236,12 +237,12 @@
           "minLength": 1,
           "description": "Target component `id` (or external target label)."
         },
-        "mechanism": {
-          "$ref": "#/$defs/mechanism"
+        "relationType": {
+          "$ref": "#/$defs/relationType"
         },
         "refs": {
           "type": "array",
-          "description": "Concrete file/symbol evidence backing the edge (often purl refs).",
+          "description": "Concrete file/symbol evidence backing the relation (often purl refs).",
           "items": {
             "type": "string",
             "minLength": 1
@@ -249,24 +250,34 @@
         }
       }
     },
-    "throughlineStep": {
+    "walkthroughStep": {
       "type": "object",
       "required": [
-        "edgeId",
+        "from",
+        "to",
+        "mechanism",
         "file",
         "line"
       ],
       "additionalProperties": false,
       "properties": {
-        "edgeId": {
+        "from": {
           "type": "string",
           "minLength": 1,
-          "description": "Id of an existing edge this hop traverses."
+          "description": "Source component `id`."
+        },
+        "to": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Target component `id`."
+        },
+        "mechanism": {
+          "$ref": "#/$defs/mechanism"
         },
         "file": {
           "type": "string",
           "minLength": 1,
-          "description": "Repo-root-relative path where the edge fires for this flow."
+          "description": "Repo-root-relative path where the seam fires for this walkthrough."
         },
         "line": {
           "type": "integer",
@@ -285,7 +296,7 @@
         }
       }
     },
-    "throughline": {
+    "walkthrough": {
       "type": "object",
       "required": [
         "id",
@@ -297,18 +308,18 @@
         "id": {
           "type": "string",
           "minLength": 1,
-          "description": "Stable unique throughline id."
+          "description": "Stable unique walkthrough id."
         },
         "title": {
           "type": "string",
           "minLength": 1,
-          "description": "Flow name (e.g. save flow, load flow)."
+          "description": "Walkthrough name (e.g. save, load, refresh)."
         },
         "steps": {
           "type": "array",
           "description": "Ordered hops; array order is execution order.",
           "items": {
-            "$ref": "#/$defs/throughlineStep"
+            "$ref": "#/$defs/walkthroughStep"
           }
         }
       }
@@ -671,6 +682,35 @@
         }
       }
     },
+    "typeParamInfo": {
+      "type": "object",
+      "required": ["name"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string" },
+        "constraint": { "type": "string" }
+      }
+    },
+    "callableTypeInfo": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "parameters": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/paramInfo" }
+        },
+        "returnType": { "type": "string" }
+      }
+    },
+    "enumMemberInfo": {
+      "type": "object",
+      "required": ["name"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string" },
+        "value": { "type": "string" }
+      }
+    },
     "typeDeclaration": {
       "type": "object",
       "required": [
@@ -680,6 +720,7 @@
         "implementors"
       ],
       "additionalProperties": false,
+      "description": "Type-family declaration (interface / type alias / enum). Prefer structured buckets; use `rhs` when none fit.",
       "properties": {
         "kind": {
           "const": "type"
@@ -701,6 +742,24 @@
           "items": {
             "type": "string"
           }
+        },
+        "generics": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/typeParamInfo" }
+        },
+        "signature": { "$ref": "#/$defs/callableTypeInfo" },
+        "enumMembers": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/enumMemberInfo" }
+        },
+        "aliasOf": { "type": "string" },
+        "unionOf": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "rhs": {
+          "type": "string",
+          "description": "Verbatim RHS escape hatch; wins over structured buckets when set."
         }
       }
     },

package/src/types/subsystem-model.ts

@@ -12,7 +12,8 @@
  *    Used by viewers and stores; not part of the portable standard.
  *
  * Ontology: construct = what a node is, framework + stereotype = which
- * framework pattern it plays, role = where it sits, process = where it runs.
+ * framework pattern it plays, role = where it sits, process = where it runs,
+ * proposed = not yet in source (design / migration placeholder).
  * `symbol` is the code identity; `name` is the display label.
  */
 
@@ -54,21 +55,30 @@ export type SubsystemFramework = string;
  */
 export type SubsystemStereotype = string;
 
-/** How `from` relates to `to` on an edge. */
-export type SubsystemEdgeMechanism =
+/**
+ * Topology relation type — structural / module / type claims between
+ * components. Belongs on `relations[]`, not on walkthrough hops.
+ */
+export type SubsystemRelationType =
   | 'imports'
   | 'imports_from'
   | 're_exports'
   | 'defines'
-  | 'calls'
   | 'extends'
   | 'inherits'
   | 'implements'
   | 'mixes_in'
-  | 'uses'
   | 'method'
   | 'references'
-  | 'contains'
+  | 'contains';
+
+/**
+ * Walkthrough hop mechanism — runtime seams with a `file:line` site.
+ * Belongs on walkthrough steps; graph edges for these are derived.
+ */
+export type SubsystemWalkthroughMechanism =
+  | 'calls'
+  | 'uses'
   | 'feeds'
   | 'produces'
   | 'writes'
@@ -76,7 +86,13 @@ export type SubsystemEdgeMechanism =
   | 'watches'
   | 'registers-into';
 
-export type SubsystemCapture = 'edited' | 'analyzed' | 'referenced';
+/**
+ * Union used by derived graph edges / styling (topology relationType or
+ * walkthrough hop mechanism).
+ */
+export type SubsystemEdgeMechanism =
+  | SubsystemRelationType
+  | SubsystemWalkthroughMechanism;
 
 export type SubsystemDeclarationProvenance = 'verified' | 'authored';
 
@@ -176,11 +192,49 @@ export interface SubsystemMethodDeclaration {
   returnType?: string;
 }
 
+/** One generic type parameter, e.g. `T` or `K extends keyof StudioMessages`. */
+export interface SubsystemTypeParamInfo {
+  name: string;
+  /** Constraint written after `extends` (or language equivalent). */
+  constraint?: string;
+}
+
+/** A callable/function type: `(params) => returnType`. */
+export interface SubsystemCallableTypeInfo {
+  parameters?: SubsystemParamInfo[];
+  returnType?: string;
+}
+
+/** One enum member, with its optional literal value. */
+export interface SubsystemEnumMemberInfo {
+  name: string;
+  value?: string;
+}
+
+/**
+ * Type-family declaration (interface / type alias / enum). Structured buckets
+ * cover common shapes; `rhs` is the verbatim escape hatch when none fit.
+ */
 export interface SubsystemTypeDeclaration {
   kind: 'type';
   properties: SubsystemPropertyInfo[];
   usedBy: SubsystemReferenceInfo[];
   implementors: string[];
+  /** Generic type parameters, e.g. `<K extends keyof StudioMessages>`. */
+  generics?: SubsystemTypeParamInfo[];
+  /** Callable type — `(params) => returnType`. */
+  signature?: SubsystemCallableTypeInfo;
+  /** Enum members (name, optional literal value). */
+  enumMembers?: SubsystemEnumMemberInfo[];
+  /** Alias whose RHS is a plain reference, e.g. `ServerSessionRow[]`. */
+  aliasOf?: string;
+  /** Simple union of alternatives, e.g. `'started' | 'stopped'`. */
+  unionOf?: string[];
+  /**
+   * Verbatim RHS — escape hatch for shapes the structured fields can't
+   * express. Wins over every shape above when set.
+   */
+  rhs?: string;
 }
 
 export interface SubsystemModuleDeclaration {
@@ -197,6 +251,11 @@ export interface SubsystemExternalDeclaration {
 
 export interface SubsystemStoreDeclaration {
   kind: 'store';
+  /** Where retained state lives / who mediates access. Authored, never
+   *  extracted: `memory` (process-lifetime RAM), `disk` (this process
+   *  reads/writes files), or `external` (another system — db/service; carries
+   *  no `process`). */
+  storage?: 'memory' | 'disk' | 'external';
   properties: SubsystemPropertyInfo[];
 }
 
@@ -239,6 +298,13 @@ export interface SubsystemComponent {
   purl: 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;
   /**
    * Framework that owns the stereotype (e.g. `react`, `nestjs`).
    * Orthogonal to `construct` — a React component is still `construct: function`.
@@ -263,7 +329,6 @@ export interface SubsystemComponent {
    */
   color?: string;
   layer?: number;
-  capture?: SubsystemCapture;
   /** Structured declaration shape of the construct (params, members, …). */
   declaration?: SubsystemConstructDeclaration;
   declarationProvenance?: SubsystemDeclarationProvenance;
@@ -272,20 +337,37 @@ export interface SubsystemComponent {
   declarationRef?: SubsystemDeclarationRef;
 }
 
-/** A cross-component edge. */
-export interface SubsystemComponentEdge {
+/** A topology relation between components (structural / module / type). */
+export interface SubsystemRelation {
   id: string;
   /** Source component id. */
   from: string;
   /** Target component id (or external label). */
   to: string;
-  mechanism: SubsystemEdgeMechanism;
+  relationType: SubsystemRelationType;
   /** Concrete file/symbol evidence (often purls). */
   refs?: string[];
 }
 
-export interface SubsystemThroughlineStep {
-  edgeId: string;
+/**
+ * Derived / display graph edge used by renderers. Built from `relations`
+ * and/or walkthrough hops — not authored as its own document field.
+ */
+export interface SubsystemComponentEdge {
+  id: string;
+  from: string;
+  to: string;
+  mechanism: SubsystemEdgeMechanism;
+  refs?: string[];
+}
+
+export interface SubsystemWalkthroughStep {
+  /** Source component id. */
+  from: string;
+  /** Target component id. */
+  to: string;
+  /** Runtime seam label (Set B). */
+  mechanism: SubsystemWalkthroughMechanism;
   file: string;
   /** 1-based line within `file`. */
   line: number;
@@ -299,11 +381,11 @@ export interface SubsystemThroughlineStep {
   annotation?: string;
 }
 
-/** Ordered execution story over existing edges (one per flow). */
-export interface SubsystemThroughline {
+/** Ordered runtime walkthrough (one named behavior story). */
+export interface SubsystemWalkthrough {
   id: string;
   title: string;
-  steps: SubsystemThroughlineStep[];
+  steps: SubsystemWalkthroughStep[];
 }
 
 export interface SubsystemRepoRef {
@@ -326,8 +408,10 @@ export interface SubsystemModelDocument {
   title: string;
   description?: string;
   components: SubsystemComponent[];
-  edges: SubsystemComponentEdge[];
-  throughlines?: SubsystemThroughline[];
+  /** Topology relations (structural / module / type). May be empty. */
+  relations: SubsystemRelation[];
+  /** Runtime walkthroughs (ordered hops with sites). */
+  walkthroughs?: SubsystemWalkthrough[];
 }
 
 /**
@@ -378,12 +462,12 @@ export function isSubsystemModelDocument(value: unknown): value is SubsystemMode
   const v = value as {
     title?: unknown;
     components?: unknown;
-    edges?: unknown;
+    relations?: unknown;
   };
   return (
     typeof v.title === 'string' &&
     Array.isArray(v.components) &&
-    Array.isArray(v.edges)
+    Array.isArray(v.relations)
   );
 }
 
@@ -398,10 +482,56 @@ export function toPortableDocument(
   const out: SubsystemModelDocument = {
     title: doc.title,
     components: doc.components,
-    edges: doc.edges,
+    relations: doc.relations,
   };
   if (doc.$schema) out.$schema = doc.$schema;
   if (doc.description) out.description = doc.description;
-  if (doc.throughlines) out.throughlines = doc.throughlines;
+  if (doc.walkthroughs) out.walkthroughs = doc.walkthroughs;
   return out;
 }
+
+/** Stable id for a derived graph edge from a relation or walkthrough hop. */
+export function derivedGraphEdgeId(
+  from: string,
+  to: string,
+  mechanism: SubsystemEdgeMechanism,
+): string {
+  return `${from}--${mechanism}-->${to}`;
+}
+
+/**
+ * Build display edges for the graph canvas from topology relations and
+ * walkthrough hops (deduped by from/to/mechanism).
+ */
+export function deriveGraphEdges(doc: {
+  relations?: SubsystemRelation[];
+  walkthroughs?: SubsystemWalkthrough[];
+}): SubsystemComponentEdge[] {
+  const byId = new Map<string, SubsystemComponentEdge>();
+  for (const r of doc.relations ?? []) {
+    const id = r.id || derivedGraphEdgeId(r.from, r.to, r.relationType);
+    if (!byId.has(id)) {
+      byId.set(id, {
+        id,
+        from: r.from,
+        to: r.to,
+        mechanism: r.relationType,
+        refs: r.refs,
+      });
+    }
+  }
+  for (const w of doc.walkthroughs ?? []) {
+    for (const step of w.steps) {
+      const id = derivedGraphEdgeId(step.from, step.to, step.mechanism);
+      if (!byId.has(id)) {
+        byId.set(id, {
+          id,
+          from: step.from,
+          to: step.to,
+          mechanism: step.mechanism,
+        });
+      }
+    }
+  }
+  return [...byId.values()];
+}