@principal-ai/subsystems-core 0.49.2 → 0.51.0

package/dist/validation.js

@@ -14,12 +14,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateSubsystemModelCrossField = void 0;
 function isUngrounded(c) {
-    // 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;
 }
 /**
  * `file` is a path *inside the repo named by `purl`* — it resolves against that
@@ -30,8 +28,7 @@ function isUngrounded(c) {
  * 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.
@@ -78,17 +75,16 @@ function validateSubsystemModelCrossField(doc) {
             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)) {
             problems.push({
@@ -135,6 +131,42 @@ function validateSubsystemModelCrossField(doc) {
             const spanProblem = spanRangeProblem(step.span, `/trails/${ti}/steps/${si}/span`, `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.`,
+                });
+            }
         });
     });
     return problems;

package/dist/validation.js.map

@@ -1 +1 @@
-{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAeH,SAAS,YAAY,CAAC,CAAqB;IACzC,wEAAwE;IACxE,sEAAsE;IACtE,iBAAiB;IACjB,OAAO,CAAC,CAAC,SAAS,KAAK,UAAU,IAAI,CAAC,CAAC,UAAU,KAAK,IAAI,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAS,mBAAmB,CAAC,IAAY;IACvC,OAAO,0BAA0B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;GAKG;AACH,SAAS,gBAAgB,CACvB,IAAqC,EACrC,IAAY,EACZ,KAAa;IAEb,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,IAAI,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,SAAS,EAAE;QACjC,OAAO;YACL,IAAI;YACJ,OAAO,EAAE,GAAG,KAAK,kBAAkB,IAAI,CAAC,OAAO,uBAAuB,IAAI,CAAC,SAAS,yDAAyD;SAC9I,CAAC;KACH;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,SAAgB,gCAAgC,CAC9C,GAA2B;IAE3B,MAAM,QAAQ,GAAiC,EAAE,CAAC;IAClD,MAAM,UAAU,GAAG,GAAG,CAAC,UAAU,IAAI,EAAE,CAAC;IACxC,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC;IAEhC,0EAA0E;IAC1E,mBAAmB;IACnB,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAC1B,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE;YACpB,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,eAAe,CAAC,QAAQ;gBAC9B,OAAO,EAAE,aAAa,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,mBAAmB;aACjE,CAAC,CAAC;SACJ;aAAM;YACL,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;SAClB;QACD,2EAA2E;QAC3E,4CAA4C;QAC5C,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,IAAI,MAAM,IAAI,CAAC,IAAI,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE;YACvC,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,eAAe,CAAC,SAAS;gBAC/B,OAAO,EAAE,aAAa,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,uEAAuE;aACvJ,CAAC,CAAC;SACJ;QACD,IACE,IAAI;YACJ,CAAC,CAAC,UAAU,KAAK,IAAI;YACrB,mBAAmB,CAAC,IAAI,CAAC,EACzB;YACA,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,eAAe,CAAC,OAAO;gBAC7B,OAAO,EAAE,aAAa,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,4OAA4O;aACxT,CAAC,CAAC;SACJ;QACD,MAAM,WAAW,GAAG,gBAAgB,CAClC,CAAC,CAAC,eAAe,EACjB,eAAe,CAAC,kBAAkB,EAClC,aAAa,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CACvC,CAAC;QACF,IAAI,WAAW;YAAE,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,OAAO,CAAC,CAAC,CAAiB,EAAE,EAAE,EAAE,EAAE;QACvC,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE;YACnC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;gBACvB,QAAQ,CAAC,IAAI,CAAC;oBACZ,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO;oBACtC,OAAO,EAAE,SAAS,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,EAAE,SAAS,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,qCAAqC;iBAC1H,CAAC,CAAC;aACJ;YACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE;gBACrB,QAAQ,CAAC,IAAI,CAAC;oBACZ,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,KAAK;oBACpC,OAAO,EAAE,SAAS,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,EAAE,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,qCAAqC;iBACtH,CAAC,CAAC;aACJ;YACD,qEAAqE;YACrE,qEAAqE;YACrE,mBAAmB;YACnB,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE;gBAC5D,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACzD,IAAI,QAAQ,KAAK,IAAI,CAAC,IAAI,EAAE;oBAC1B,QAAQ,CAAC,IAAI,CAAC;wBACZ,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO;wBACtC,OAAO,EAAE,SAAS,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,EAAE,kBAAkB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,6BAA6B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;qBACrJ,CAAC,CAAC;iBACJ;aACF;YACD,IAAI,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;gBAClC,QAAQ,CAAC,IAAI,CAAC;oBACZ,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO;oBACtC,OAAO,EAAE,SAAS,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,EAAE,SAAS,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,uFAAuF;iBAC5K,CAAC,CAAC;aACJ;YACD,MAAM,WAAW,GAAG,gBAAgB,CAClC,IAAI,CAAC,IAAI,EACT,WAAW,EAAE,UAAU,EAAE,OAAO,EAChC,SAAS,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,EAAE,EAAE,CAC5C,CAAC;YACF,IAAI,WAAW;gBAAE,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YAE5C,qEAAqE;YACrE,oEAAoE;YACpE,MAAM,eAAe,GAAG,gBAAgB,CACtC,IAAI,CAAC,IAAI,EAAE,IAAI,EACf,WAAW,EAAE,UAAU,EAAE,YAAY,EACrC,SAAS,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,EAAE,OAAO,CACjD,CAAC;YACF,IAAI,eAAe;gBAAE,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;YACpD,IACE,IAAI,CAAC,IAAI;gBACT,IAAI,CAAC,IAAI,EAAE,IAAI;gBACf,CAAC,CACC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS;oBAC/C,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAC5C,EACD;gBACA,QAAQ,CAAC,IAAI,CAAC;oBACZ,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY;oBAC3C,OAAO,EAAE,SAAS,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,EAAE,cAAc,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,mCAAmC,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,GAAG;iBACjM,CAAC,CAAC;aACJ;YAED,kEAAkE;YAClE,8DAA8D;YAC9D,MAAM,iBAAiB,GAAG,gBAAgB,CACxC,IAAI,CAAC,MAAM,EAAE,IAAI,EACjB,WAAW,EAAE,UAAU,EAAE,cAAc,EACvC,SAAS,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,EAAE,SAAS,CACnD,CAAC;YACF,IAAI,iBAAiB;gBAAE,QAAQ,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;YACxD,IACE,IAAI,CAAC,MAAM;gBACX,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,QAAQ;gBACpC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAC9B;gBACA,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAChE,IAAI,QAAQ,KAAK,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE;oBACjC,QAAQ,CAAC,IAAI,CAAC;wBACZ,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc;wBAC7C,OAAO,EAAE,SAAS,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,EAAE,yBAAyB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,+BAA+B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE;qBACrK,CAAC,CAAC;iBACJ;aACF;YACD,IAAI,IAAI,CAAC,MAAM,IAAI,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE;gBACxD,QAAQ,CAAC,IAAI,CAAC;oBACZ,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc;oBAC7C,OAAO,EAAE,SAAS,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,EAAE,gBAAgB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,0EAA0E;iBAC7K,CAAC,CAAC;aACJ;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,OAAO,QAAQ,CAAC;AAClB,CAAC;AA3ID,4EA2IC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principal-ai/subsystems-core",
-  "version": "0.49.2",
+  "version": "0.51.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

@@ -76,13 +76,9 @@
         "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."
-    },
     "deprecated": {
       "type": "boolean",
-      "description": "The claim was real but its source is gone upstream — deleted or renamed. The inverse of `proposed`; verification skips source checks the same way, so the component stops blocking verification. Transitional: a cleanup pass removes it and repairs the trails that referenced it."
+      "description": "The claim was real but its source is gone upstream — deleted or renamed. Verification skips source checks, so the component stops blocking verification. Transitional: a cleanup pass removes it and repairs the trails that referenced it."
     },
     "removedIn": {
       "type": "object",
@@ -189,9 +185,6 @@
         "role": {
           "$ref": "#/$defs/role"
         },
-        "proposed": {
-          "$ref": "#/$defs/proposed"
-        },
         "deprecated": {
           "$ref": "#/$defs/deprecated"
         },
@@ -272,6 +265,59 @@
           "$ref": "#/$defs/sourceSpan",
           "description": "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. `file` + `symbol` locate the frame."
         },
+        "site": {
+          "type": "object",
+          "description": "The construct containing the seam site, with its full declaration range. Required for `calls`: the caller frame must be housed by the `from` component. For `uses` and data/event seams it is the via-site evidence and is optional. Same file/repo as the step.",
+          "additionalProperties": false,
+          "required": ["symbol", "span"],
+          "properties": {
+            "symbol": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Caller/via construct symbol (e.g. `MaintenanceModelList`, `Registry.start`)."
+            },
+            "span": {
+              "$ref": "#/$defs/sourceSpan",
+              "description": "Full declaration range of the site construct, not just the seam line."
+            },
+            "construct": {
+              "$ref": "#/$defs/construct",
+              "description": "Declaration shape of the site construct, when known."
+            }
+          }
+        },
+        "target": {
+          "type": "object",
+          "description": "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.",
+          "additionalProperties": false,
+          "required": ["purl", "file", "symbol"],
+          "properties": {
+            "purl": {
+              "type": "string",
+              "minLength": 1,
+              "description": "File-anchored purl of the target repo/file."
+            },
+            "file": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "^(?!.*(^|/)node_modules(/|$)).*$",
+              "description": "Repo-root-relative target file."
+            },
+            "symbol": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Callee construct symbol (e.g. `mergeProvenance`, `Store.add`)."
+            },
+            "span": {
+              "$ref": "#/$defs/sourceSpan",
+              "description": "Full declaration range of the target construct, when resolvable."
+            },
+            "construct": {
+              "$ref": "#/$defs/construct",
+              "description": "Declaration shape of the target, when known."
+            }
+          }
+        },
         "purl": {
           "type": "string",
           "minLength": 1,
@@ -282,16 +328,26 @@
           "minLength": 1,
           "description": "Frame name for this step — the function/method on the stack at the site. Required; the Trails list shows this instead of a bare mechanism + filename fallback."
         },
-        "proposed": {
-          "type": "boolean",
-          "description": "Planned seam — the step describes intended behavior through code that is not written yet. Verification skips source checks; viewers tint it like a proposed node. A step is proposed when it says so OR either endpoint component is proposed."
-        },
         "annotation": {
           "type": "string",
           "minLength": 1,
           "description": "Free-text note anchored to this step's site line. Optional, informative only, never verified against source; viewers surface it in the codeview's annotation column."
         }
-      }
+      },
+      "allOf": [
+        {
+          "description": "A calls step claims the site is the caller frame, so it must carry the enclosing site construct. Other mechanisms may use site as evidence but are not required to.",
+          "if": {
+            "required": ["mechanism"],
+            "properties": {
+              "mechanism": { "const": "calls" }
+            }
+          },
+          "then": {
+            "required": ["site"]
+          }
+        }
+      ]
     },
     "trail": {
       "type": "object",

package/src/node.ts

@@ -22,12 +22,8 @@ export type {
   TopicUpdate,
   MigrationResult,
 } from './storage/topicStore';
-export { publishedFromDraft } from './storage/topic-types';
 export type {
   DraftTopic,
-  PublishedTopic,
-  PublishProjection,
-  TopicStatus,
   TopicAsset,
   TopicCreator,
   TopicSubsystemModelRef,

package/src/storage/topic-types.ts

@@ -3,78 +3,25 @@
  * agrees on. Browser-safe (no `node:*`); the file-per-topic store that reads and
  * writes these lives in `./node` (see `topicStore.ts`).
  *
- * A **topic** is a locally authored subject brief that may be published. Two
- * distinct named shapes, split by id-namespace / ownership, with an explicit
- * translation between them — NOT one shared shape. Their `id` fields live in
- * different namespaces (local vs server), so passing one where the other is
- * expected corrupts topic identity.
+ * A **topic** is a locally authored subject brief. {@link DraftTopic} is the
+ * shape desktop persists to `~/.principal/topics/<id>.json` and edits.
  *
- * - {@link DraftTopic}     — locally-authored, what desktop persists + edits.
- * - {@link PublishedTopic} — server-authoritative, what the server returns and
- *                            mobile reads.
- * - {@link publishedFromDraft} — the Draft -> Published projection (one-way;
- *                            there is no reverse hydration).
- *
- * All timestamps are ISO 8601 strings because this contract crosses the
- * desktop/web boundary.
- */
-
-/**
- * Status of a topic — a small structured axis plus optional human nuance.
- *
- * `state` is the machine-meaningful signal (drives badge color, sorting, and
- * filtering). `label` is free-form text shown in place of the default per-state
- * label. `waitingOn` describes an external blocker and is meaningful when
- * `state` is `waiting`.
- *
- * The structured shape is deliberate: it lets automations check and resolve a
- * blocker without parsing prose — e.g. flip `waiting` -> `paused` once `until`
- * passes, or once a referenced PR merges.
+ * All timestamps are ISO 8601 strings.
  */
-export interface TopicStatus {
-  /**
-   * Structured lifecycle axis, ordered by a feature's "aliveness" from nascent
-   * to retired. Readers treat an absent OR unrecognized `state` as
-   * `new-thought`, so legacy topics and renamed values need no migration.
-   */
-  state:
-    'new-thought' | 'working' | 'paused' | 'waiting' | 'done-for-now' | 'deprecated' | 'abandoned';
-  /** Free-form text shown in place of the default label for the state. */
-  label?: string;
-  /** External blocker description. Meaningful when `state` is `waiting`. */
-  waitingOn?: {
-    /** Human description of the blocker, e.g. "design sign-off". */
-    note?: string;
-    /** ISO 8601 — when the hold is expected to lift. */
-    until?: string;
-    /** Structured pointer to the thing being waited on, for automations. */
-    ref?: {
-      kind: 'url' | 'pr' | 'issue' | 'topic';
-      /** The address/id of the referenced thing. */
-      value: string;
-      /** Optional human label for display. */
-      title?: string;
-    };
-  };
-}
 
 /**
  * An image attached to a topic — primarily a screenshot dragged into the
  * description. Bytes live on the topic (referenced from the description via an
  * `asset://<id>` markdown link), not inlined into the description string. A
  * render-time resolver swaps `asset://<id>` for `url` (preferred) or a data-URL
- * built from `data`, keeping a local (data-only) and a published (url-bearing)
- * topic interchangeable on read.
- *
- * Local-only on a {@link DraftTopic}: assets are uploaded/resolved at publish
- * time, so a {@link PublishedTopic} carries the resolved `url`, not raw `data`.
+ * built from `data`.
  */
 export interface TopicAsset {
   /** Content hash — free dedup and the stable `asset://` target. */
   id: string;
   /** MIME type, e.g. "image/png". */
   mime: string;
-  /** Base64-encoded bytes. Present locally and on publish. */
+  /** Base64-encoded bytes. */
   data?: string;
   /** Resolvable URL, when the bytes have been offloaded (e.g. to S3). */
   url?: string;
@@ -87,7 +34,7 @@ export interface TopicAsset {
 /**
  * GitHub identity of a topic's creator. Populated when a signed-in user
  * authors a topic; left undefined for local-only topics created before
- * sign-in. The server requires this on publish.
+ * sign-in.
  */
 export interface TopicCreator {
   githubId: number;
@@ -99,8 +46,8 @@ export interface TopicCreator {
  * specific runtime trails (flows) within that model.
  *
  * The link lives on the **topic** side, in the local store id namespace, and
- * never on the model: a subsystem-model document is a portable, host-free
- * artifact (shared/published) that must not embed local topic or store ids.
+ * never on the model: a subsystem-model document is a portable artifact that
+ * must not embed local topic or store ids.
  */
 export interface TopicSubsystemModelRef {
   /** Store-assigned model id, e.g. "sg-1781...". */
@@ -113,14 +60,9 @@ export interface TopicSubsystemModelRef {
  * Locally-authored topic — the shape desktop persists to
  * `~/.principal/topics/<id>.json` and edits.
  *
- * Local id namespace. `description` / `createdBy` are optional (a Draft may be
- * authored before sign-in). Carries local-only {@link TopicAsset}s
- * (`asset://<id>` screenshots, raw `data`). Has NO `visibility` — that's a
- * published concept.
- *
- * A Draft keeps existing after publish (it can be in a "published state"); its
- * link to the server identity lives in the desktop's `topics-sync.json`
- * sidecar, not in this shape.
+ * `description` / `createdBy` are optional (a Draft may be authored before
+ * sign-in). Carries local-only {@link TopicAsset}s (`asset://<id>` screenshots,
+ * raw `data`).
  */
 export interface DraftTopic {
   /** Unique identifier in the LOCAL id namespace. */
@@ -134,7 +76,7 @@ export interface DraftTopic {
    * `pkg:github/owner/repo`). The topic's own source of truth for "which repos"
    * — portable and machine-independent, matching `WorkspaceMembership.repositoryId`.
    * Machine-local clone paths stay a workspace-membership concern and never
-   * appear here, so this round-trips across machines on publish/fetch.
+   * appear here, so this round-trips across machines.
    */
   repos?: string[];
   /** ISO 8601. */
@@ -143,95 +85,11 @@ export interface DraftTopic {
   updatedAt: string;
   /** Creator identity; undefined for topics authored before sign-in. */
   createdBy?: TopicCreator;
-  /** Optional workflow status. Absent reads as `new-thought`. */
-  status?: TopicStatus;
   /** Local image attachments, referenced from the description via `asset://<id>`. */
   assets?: TopicAsset[];
   /**
-   * Subsystem models this topic concerns, as local store ids. Local-only: not
-   * carried on publish, since the referenced models are a local artifact.
+   * Subsystem models this topic concerns, as local store ids. Local-only, since
+   * the referenced models are a local artifact.
    */
   subsystemModels?: TopicSubsystemModelRef[];
 }
-
-/**
- * Server-authoritative topic — the shape the server returns and mobile reads.
- *
- * Remote id namespace. `description` / `createdBy` are required (publish is the
- * validation gate). Carries `visibility`; assets have been resolved to `url`s.
- *
- * CAVEAT: "Published" means "has a server identity", NOT "public" — a
- * PublishedTopic can be `visibility: 'private'`.
- */
-export interface PublishedTopic {
-  /** Unique identifier in the REMOTE (server) id namespace. */
-  id: string;
-  /** Display title. */
-  title: string;
-  /** Markdown body — required on the server. */
-  description: string;
-  /**
-   * Repositories this topic is about, as PURL strings (e.g.
-   * `pkg:github/owner/repo`). Travels with the topic across the wire so a
-   * received shared topic carries its repos; preserved on publish/fetch.
-   */
-  repos?: string[];
-  /** ISO 8601. */
-  createdAt: string;
-  /** ISO 8601. */
-  updatedAt: string;
-  /** Creator identity — required on the server. */
-  createdBy: TopicCreator;
-  /** Optional workflow status, travels with the topic when published. */
-  status?: TopicStatus;
-  /** Server visibility. "private" is still a PublishedTopic. */
-  visibility: 'private' | 'public';
-}
-
-/**
- * Inputs the {@link DraftTopic} cannot supply on its own — the namespace
- * crossing and the fields publish must enforce. The caller resolves these
- * before projecting:
- * - `createdBy`: required on the server; supplied here if the draft lacks it.
- * - `visibility`: a published concept the draft never carries.
- */
-export interface PublishProjection {
-  createdBy: TopicCreator;
-  visibility: 'private' | 'public';
-}
-
-/**
- * Project a {@link DraftTopic} into a {@link PublishedTopic} — the one-way
- * Draft -> Published translation. It does NOT perform any I/O (no id minting,
- * no asset upload, no network): the caller resolves the namespace-crossing and
- * required fields into {@link PublishProjection} first (uploading assets,
- * choosing visibility), and this enforces the shape.
- *
- * One-way by design: there is no reverse `PublishedTopic -> DraftTopic`
- * hydration. A published topic's edits write through to the server; the local
- * Draft is reconciled from the server's response field-by-field, never by
- * rebuilding a Draft from a Published shape.
- *
- * Throws if `description` is empty — publish is also the validation gate, and
- * the server rejects a description-less topic.
- */
-export function publishedFromDraft(
-  draft: DraftTopic,
-  projection: PublishProjection
-): PublishedTopic {
-  const description = (draft.description ?? '').trim();
-  if (description.length === 0) {
-    throw new Error(`Topic ${draft.id} has no description; a description is required to publish.`);
-  }
-  return {
-    id: draft.id,
-    title: draft.title,
-    description,
-    ...(draft.repos !== undefined ? { repos: draft.repos } : {}),
-    createdAt: draft.createdAt,
-    updatedAt: draft.updatedAt,
-    createdBy: projection.createdBy,
-    ...(draft.status !== undefined ? { status: draft.status } : {}),
-    visibility: projection.visibility,
-  };
-}

package/src/storage/topicStore.test.ts

@@ -7,7 +7,6 @@ import { mkdtempSync, rmSync, writeFileSync, existsSync, readFileSync } from 'fs
 import { tmpdir } from 'os';
 import { join } from 'path';
 import { TopicStore } from './topicStore';
-import { publishedFromDraft, type DraftTopic } from './topic-types';
 
 let dir: string;
 let topicsDir: string;
@@ -74,26 +73,6 @@ describe('CRUD', () => {
     expect(updated.repos).toEqual(['pkg:github/acme/web', 'pkg:github/acme/api']);
   });
 
-  test('publishedFromDraft carries repos through the projection', () => {
-    const draft: DraftTopic = {
-      id: 'topic-pub',
-      title: 'Pub',
-      description: 'has a description',
-      repos: ['pkg:github/acme/web'],
-      subsystemModels: [{ modelId: 'sg-1-abc', trailIds: ['trail-a'] }],
-      createdAt: '2026-01-01T00:00:00.000Z',
-      updatedAt: '2026-01-02T00:00:00.000Z',
-    };
-    const published = publishedFromDraft(draft, {
-      createdBy: { githubId: 1, githubLogin: 'u1' },
-      visibility: 'private',
-    });
-    expect(published.repos).toEqual(['pkg:github/acme/web']);
-    expect(published).not.toHaveProperty('trailIds');
-    // Local-only model refs must not travel on publish.
-    expect(published).not.toHaveProperty('subsystemModels');
-  });
-
   test('subsystemModels persist on create and are updatable', async () => {
     const store = makeStore();
     const created = await store.createTopic({
@@ -188,6 +167,7 @@ describe('index rebuild', () => {
     const legacy = {
       ...JSON.parse(readFileSync(topicPath, 'utf8')),
       trailIds: ['old-trail'],
+      status: { state: 'working', label: 'in flight' },
       description: 'Keep this description',
     };
     writeFileSync(topicPath, JSON.stringify(legacy), 'utf8');
@@ -201,6 +181,9 @@ describe('index rebuild', () => {
       repos: ['pkg:github/a/b'],
     });
     expect(loaded).toHaveProperty('trailIds', ['old-trail']);
+    // `status` was removed from the contract; legacy files still load and are
+    // read back verbatim until the desktop cleans them up.
+    expect(loaded).toHaveProperty('status', { state: 'working', label: 'in flight' });
     expect(JSON.parse(readFileSync(topicPath, 'utf8'))).toHaveProperty('trailIds', ['old-trail']);
   });
 });

package/src/storage/topicStore.ts

@@ -27,7 +27,7 @@
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { mkdir, readFile, writeFile, unlink, readdir, rename, access } from 'node:fs/promises';
-import type { DraftTopic, TopicStatus } from './topic-types';
+import type { DraftTopic } from './topic-types';
 
 /** Root of the global, cross-repo principal narration store. */
 export const PRINCIPAL_DIR = join(homedir(), '.principal');
@@ -48,8 +48,6 @@ export interface TopicIndexEntry {
   id: string;
   title: string;
   descriptionPreview: string;
-  /** `status.state` lifted out for filtering/sorting without a file read. */
-  state?: TopicStatus['state'];
   createdAt: string;
   updatedAt: string;
   createdBy?: { githubId: number; githubLogin: string };
@@ -85,7 +83,6 @@ const buildEntry = (topic: DraftTopic, sizeBytes: number): TopicIndexEntry => ({
   id: topic.id,
   title: topic.title || 'Untitled topic',
   descriptionPreview: descriptionPreview(topic.description),
-  state: topic.status?.state,
   createdAt: topic.createdAt,
   updatedAt: topic.updatedAt,
   createdBy: topic.createdBy,
@@ -118,7 +115,7 @@ export interface MigrationResult {
 export type TopicUpdate = Partial<
   Pick<
     DraftTopic,
-    'title' | 'description' | 'status' | 'createdBy' | 'assets' | 'repos' | 'subsystemModels'
+    'title' | 'description' | 'createdBy' | 'assets' | 'repos' | 'subsystemModels'
   >
 >;
 

package/src/types/subsystem-model.test.ts

@@ -60,6 +60,11 @@ describe("subsystem-model schema", () => {
 		expect(schema.$defs.trailStep?.properties?.line).toBeUndefined();
 	});
 
+	test("trail steps can carry verifiable site and target constructs", () => {
+		expect(schema.$defs.trailStep?.properties?.site).toBeDefined();
+		expect(schema.$defs.trailStep?.properties?.target).toBeDefined();
+	});
+
 	test("a store declares its own value type", () => {
 		// `additionalProperties: false` on the store declaration, so the field
 		// has to be declared here or every typed store would be rejected.