npm - @principal-ai/subsystems-core - Versions diffs - 0.31.4 → 0.32.0 - Mend

@principal-ai/subsystems-core 0.31.4 → 0.32.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/dist/types/subsystem-model.d.ts +93 -12
package/dist/types/subsystem-model.d.ts.map +1 -1
package/dist/types/subsystem-model.js +44 -5
package/dist/types/subsystem-model.js.map +1 -1
package/package.json +1 -1
package/schemas/subsystem-model.schema.json +93 -29
package/src/types/subsystem-model.ts +144 -19

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

@@ -40,8 +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';
+/**
+ * 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. */
@@ -206,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;
@@ -231,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;
@@ -255,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.
@@ -305,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 CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"subsystem-model.d.ts","sourceRoot":"","sources":["../../src/types/subsystem-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;0CAE0C;AAC1C,MAAM,MAAM,kBAAkB,GAC1B,OAAO,GACP,UAAU,GACV,QAAQ,GACR,WAAW,GACX,YAAY,GACZ,MAAM,GACN,OAAO,GACP,UAAU,GACV,eAAe,CAAC;AAEpB,oEAAoE;AACpE,MAAM,MAAM,sBAAsB,GAAG,OAAO,GAAG,SAAS,CAAC;AAEzD;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAEzC;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAExC;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAEzC~~,6CAA6C~~;~~AAC7C~~,MAAM,MAAM,~~sBAAsB~~,~~GAC9B~~,SAAS,GACT,cAAc,GACd,YAAY,GACZ,SAAS,GACT,~~OAAO,GACP,~~SAAS,GACT,UAAU,GACV,YAAY,GACZ,UAAU,GACV,~~MAAM,GACN,~~QAAQ,GACR,YAAY,GACZ,UAAU,~~GACV~~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~~CACxB~~;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,qBAAqB,EAAE,CAAC;CACrC;AAED,4EAA4E;AAC5E,MAAM,WAAW,8BAA8B;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,gCAAgC;IAC/C,IAAI,EAAE,eAAe,CAAC;IACtB,UAAU,EAAE,8BAA8B,EAAE,CAAC;CAC9C;AAED,mDAAmD;AACnD,MAAM,MAAM,6BAA6B,GACrC,yBAAyB,GACzB,4BAA4B,GAC5B,0BAA0B,GAC1B,wBAAwB,GACxB,0BAA0B,GAC1B,4BAA4B,GAC5B,yBAAyB,GACzB,gCAAgC,CAAC;AAErC,2DAA2D;AAC3D,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,kBAAkB,CAAC;IAC9B,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,sBAAsB,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B;;;OAGG;IACH,UAAU,CAAC,EAAE,mBAAmB,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,UAAU,CAAC,EAAE,mBAAmB,CAAC;IACjC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,WAAW,CAAC,EAAE,6BAA6B,CAAC;IAC5C,qBAAqB,CAAC,EAAE,8BAA8B,CAAC;IACvD,MAAM,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC9B,8EAA8E;IAC9E,cAAc,CAAC,EAAE,uBAAuB,CAAC;CAC1C;AAED,~~8BAA8B~~;~~AAC9B~~,MAAM,WAAW,~~sBAAsB~~;~~IACrC~~,EAAE,EAAE,MAAM,CAAC;IACX,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,EAAE,EAAE,MAAM,CAAC;IACX,~~SAAS~~,EAAE,~~sBAAsB~~,CAAC;~~IAClC~~,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;~~IACf~~,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,~~kEAAkE~~;~~AAClE~~,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,wBAAwB,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,~~KAAK~~,EAAE,~~sBAAsB~~,EAAE,CAAC;~~IAChC~~,YAAY,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACvC;AAED;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,sBACf,SAAQ,sBAAsB,EAAE,yBAAyB;IACzD,wCAAwC;IACxC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,sBAAsB,CAYxF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,sBAAsB,GAC1B,sBAAsB,CAUxB"}
1	+ {"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 CHANGED Viewed

@@ -18,7 +18,7 @@
  * `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 /
@@ -30,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;
 /**
@@ -42,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 CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"subsystem-model.js","sourceRoot":"","sources":["../../src/types/subsystem-model.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;~~AAsWH~~;;;;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"}
1	+ {"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 CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@principal-ai/subsystems-core",
-  "version": "0.31.4",
+  "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 CHANGED Viewed

@@ -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"
       }
     }
   },
@@ -92,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",
@@ -131,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",
@@ -206,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",
@@ -231,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
@@ -244,24 +250,34 @@
         }
       }
     },
-    "throughlineStep": {
+    "walkthroughStep": {
       "type": "object",
       "required": [
-        "edgeId",
+        "from",
+        "to",
+        "mechanism",
         "file",
         "line"
       ],
       "additionalProperties": false,
       "properties": {
-        "edgeId": {
+        "from": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Source component `id`."
+        },
+        "to": {
           "type": "string",
           "minLength": 1,
-          "description": "Id of an existing edge this hop traverses."
+          "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",
@@ -280,7 +296,7 @@
         }
       }
     },
-    "throughline": {
+    "walkthrough": {
       "type": "object",
       "required": [
         "id",
@@ -292,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"
           }
         }
       }
@@ -666,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": [
@@ -675,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"
@@ -696,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 CHANGED Viewed

@@ -55,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'
@@ -77,6 +86,14 @@ export type SubsystemEdgeMechanism =
   | '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 =
@@ -175,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 {
@@ -196,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[];
 }
@@ -277,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;
@@ -304,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 {
@@ -331,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[];
 }
 /**
@@ -383,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)
   );
 }
@@ -403,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()];
+}