@principal-ai/subsystems-core 0.51.0 → 0.51.2

package/README.md

@@ -6,7 +6,7 @@ Subsystem model types/schema and agent-session tooling for Principal AI.
 
 | Import | Use |
 |---|---|
-| `@principal-ai/subsystems-core` | Browser-safe subsystem model types + `isSubsystemModelDocument` |
+| `@principal-ai/subsystems-core` | Browser-safe subsystem model/topic types, reference links + `isSubsystemModelDocument` |
 | `@principal-ai/subsystems-core/node` | OpenCode store, agent-session list/fetch/normalize, topic store, fixtures |
 | `@principal-ai/subsystems-core/pipeline` | Bun-safe session normalize/accumulate (no `better-sqlite3`) |
 
@@ -14,6 +14,42 @@ Subsystem model types/schema and agent-session tooling for Principal AI.
 
 Portable document schema: `schemas/subsystem-model.schema.json`
 
+## Topic references
+
+`DraftTopic.references` attaches local topics, C4 sketches, and drawings by ID:
+
+```ts
+import {
+  formatTopicReferenceLink,
+  parseTopicReferenceLink,
+  type TopicReference,
+} from '@principal-ai/subsystems-core';
+
+const reference: TopicReference = { kind: 'c4-sketch', sketchId: 'c4s-123-abc' };
+formatTopicReferenceLink(reference); // principal://c4-sketch/c4s-123-abc
+parseTopicReferenceLink('principal://topic/topic-123-abc');
+// { kind: 'topic', topicId: 'topic-123-abc' }
+parseTopicReferenceLink('principal://drawing/0b6f7c1e');
+// { kind: 'drawing', drawingId: '0b6f7c1e' }
+```
+
+A drawing ID is the file name, without extension, of a `.excalidraw` file in the
+host's drawings folder (the desktop app uses `~/.alexandria/drawings/`). Titles
+come from the drawing file's `appState.name` and are resolved by the host.
+
+Create/update accepts `references`; updates replace the whole array (`[]` clears
+it). Existing topics may omit the field. References are directional and local-only.
+Targets stay separate artifacts; deleting a target leaves a missing reference,
+not a cascading deletion. Existing `subsystemModels` associations are unchanged.
+
+Markdown links such as `[Architecture](principal://c4-sketch/c4s-123-abc)`,
+`[Whiteboard](principal://drawing/0b6f7c1e)`, and
+`[Related](principal://topic/topic-123-abc)` use the same target shapes but are
+independent of attachments. Helpers only format/parse hrefs; hosts must allow the
+`principal` protocol in Markdown sanitizers and handle resolution, navigation,
+target validation, deduplication, and self-reference rejection. Sketch references
+do not turn authored hypotheses into evidence.
+
 ## Installation
 
 ```bash

package/dist/index.d.ts

@@ -11,6 +11,8 @@
  *   import { ... } from '@principal-ai/subsystems-core/pipeline'
  */
 export * from './types';
+export type { DraftTopic, TopicAsset, TopicCreator, TopicSubsystemModelRef, TopicReference, } from './storage/topic-types';
+export { formatTopicReferenceLink, parseTopicReferenceLink } from './storage/topic-reference-links';
 export { validateSubsystemModelCrossField } from './validation';
 export type { SubsystemValidationProblem } from './validation';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,SAAS,CAAC;AAKxB,OAAO,EAAE,gCAAgC,EAAE,MAAM,cAAc,CAAC;AAChE,YAAY,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,SAAS,CAAC;AAExB,YAAY,EACV,UAAU,EACV,UAAU,EACV,YAAY,EACZ,sBAAsB,EACtB,cAAc,GACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAKpG,OAAO,EAAE,gCAAgC,EAAE,MAAM,cAAc,CAAC;AAChE,YAAY,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -26,8 +26,11 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateSubsystemModelCrossField = void 0;
+exports.validateSubsystemModelCrossField = exports.parseTopicReferenceLink = exports.formatTopicReferenceLink = void 0;
 __exportStar(require("./types"), exports);
+var topic_reference_links_1 = require("./storage/topic-reference-links");
+Object.defineProperty(exports, "formatTopicReferenceLink", { enumerable: true, get: function () { return topic_reference_links_1.formatTopicReferenceLink; } });
+Object.defineProperty(exports, "parseTopicReferenceLink", { enumerable: true, get: function () { return topic_reference_links_1.parseTopicReferenceLink; } });
 // Cross-field validation (the rules the JSON Schema can't express). Structural
 // (schema) validation is enforced per surface against
 // `schemas/subsystem-model.schema.json`.

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;;;;;;;;;;;;;;;AAEH,0CAAwB;AAExB,+EAA+E;AAC/E,sDAAsD;AACtD,yCAAyC;AACzC,2CAAgE;AAAvD,8HAAA,gCAAgC,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;;;;;;;;;;;;;;;AAEH,0CAAwB;AASxB,yEAAoG;AAA3F,iIAAA,wBAAwB,OAAA;AAAE,gIAAA,uBAAuB,OAAA;AAE1D,+EAA+E;AAC/E,sDAAsD;AACtD,yCAAyC;AACzC,2CAAgE;AAAvD,8HAAA,gCAAgC,OAAA"}

package/dist/node.d.ts

@@ -9,7 +9,8 @@
 export * from './types';
 export { TopicStore, PRINCIPAL_DIR, TOPICS_DIR, LEGACY_TOPICS_BLOB, } from './storage/topicStore';
 export type { TopicIndexEntry, TopicCreate, TopicUpdate, MigrationResult, } from './storage/topicStore';
-export type { DraftTopic, TopicAsset, TopicCreator, TopicSubsystemModelRef, } from './storage/topic-types';
+export type { DraftTopic, TopicAsset, TopicCreator, TopicSubsystemModelRef, TopicReference, } from './storage/topic-types';
+export { formatTopicReferenceLink, parseTopicReferenceLink } from './storage/topic-reference-links';
 export { OpenCodeEventStore, defaultOpenCodeDBPath } from './opencode/OpenCodeEventStore';
 export type { OpenCodeRawEvent, OpenCodeSessionEvents, OpenCodeEventRetriever, OpenCodeStoreOptions, SessionSummary, SessionListResult, } from './opencode/types';
 export { listAgentSessions, detectAgent, fetchRawEvents } from './opencode/agent-sessions';

package/dist/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,SAAS,CAAC;AAGxB,OAAO,EACL,UAAU,EACV,aAAa,EACb,UAAU,EACV,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,eAAe,EACf,WAAW,EACX,WAAW,EACX,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,UAAU,EACV,UAAU,EACV,YAAY,EACZ,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAC1F,YAAY,EACV,gBAAgB,EAChB,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,EACpB,cAAc,EACd,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3F,YAAY,EACV,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,uBAAuB,EACvB,0BAA0B,EAC1B,wBAAwB,EACxB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EACL,4BAA4B,EAC5B,eAAe,EACf,0BAA0B,EAC1B,gBAAgB,EAChB,mBAAmB,EACnB,6BAA6B,GAC9B,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,SAAS,CAAC;AAGxB,OAAO,EACL,UAAU,EACV,aAAa,EACb,UAAU,EACV,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,eAAe,EACf,WAAW,EACX,WAAW,EACX,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,UAAU,EACV,UAAU,EACV,YAAY,EACZ,sBAAsB,EACtB,cAAc,GACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAGpG,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAC1F,YAAY,EACV,gBAAgB,EAChB,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,EACpB,cAAc,EACd,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3F,YAAY,EACV,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,uBAAuB,EACvB,0BAA0B,EAC1B,wBAAwB,EACxB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EACL,4BAA4B,EAC5B,eAAe,EACf,0BAA0B,EAC1B,gBAAgB,EAChB,mBAAmB,EACnB,6BAA6B,GAC9B,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/node.js

@@ -22,7 +22,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.opencodeRowsToUniversalEvents = exports.collectRepositories = exports.accumulateEvents = exports.normalizeEventsWithAdapter = exports.normalizeEvents = exports.NodePathNormalizationAdapter = exports.buildAgentSessionFixture = exports.fetchRawEvents = exports.detectAgent = exports.listAgentSessions = exports.defaultOpenCodeDBPath = exports.OpenCodeEventStore = exports.LEGACY_TOPICS_BLOB = exports.TOPICS_DIR = exports.PRINCIPAL_DIR = exports.TopicStore = void 0;
+exports.opencodeRowsToUniversalEvents = exports.collectRepositories = exports.accumulateEvents = exports.normalizeEventsWithAdapter = exports.normalizeEvents = exports.NodePathNormalizationAdapter = exports.buildAgentSessionFixture = exports.fetchRawEvents = exports.detectAgent = exports.listAgentSessions = exports.defaultOpenCodeDBPath = exports.OpenCodeEventStore = exports.parseTopicReferenceLink = exports.formatTopicReferenceLink = exports.LEGACY_TOPICS_BLOB = exports.TOPICS_DIR = exports.PRINCIPAL_DIR = exports.TopicStore = void 0;
 __exportStar(require("./types"), exports);
 // File-per-topic store (~/.principal/topics) — node:fs only
 var topicStore_1 = require("./storage/topicStore");
@@ -30,6 +30,9 @@ Object.defineProperty(exports, "TopicStore", { enumerable: true, get: function (
 Object.defineProperty(exports, "PRINCIPAL_DIR", { enumerable: true, get: function () { return topicStore_1.PRINCIPAL_DIR; } });
 Object.defineProperty(exports, "TOPICS_DIR", { enumerable: true, get: function () { return topicStore_1.TOPICS_DIR; } });
 Object.defineProperty(exports, "LEGACY_TOPICS_BLOB", { enumerable: true, get: function () { return topicStore_1.LEGACY_TOPICS_BLOB; } });
+var topic_reference_links_1 = require("./storage/topic-reference-links");
+Object.defineProperty(exports, "formatTopicReferenceLink", { enumerable: true, get: function () { return topic_reference_links_1.formatTopicReferenceLink; } });
+Object.defineProperty(exports, "parseTopicReferenceLink", { enumerable: true, get: function () { return topic_reference_links_1.parseTopicReferenceLink; } });
 // OpenCode event retrieval (Node.js only - SQLite)
 var OpenCodeEventStore_1 = require("./opencode/OpenCodeEventStore");
 Object.defineProperty(exports, "OpenCodeEventStore", { enumerable: true, get: function () { return OpenCodeEventStore_1.OpenCodeEventStore; } });

package/dist/node.js.map

@@ -1 +1 @@
-{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;;;;;;;;;;;;;;;AAEH,0CAAwB;AAExB,4DAA4D;AAC5D,mDAK8B;AAJ5B,wGAAA,UAAU,OAAA;AACV,2GAAA,aAAa,OAAA;AACb,wGAAA,UAAU,OAAA;AACV,gHAAA,kBAAkB,OAAA;AAepB,mDAAmD;AACnD,oEAA0F;AAAjF,wHAAA,kBAAkB,OAAA;AAAE,2HAAA,qBAAqB,OAAA;AAUlD,iEAAiE;AACjE,4DAA2F;AAAlF,mHAAA,iBAAiB,OAAA;AAAE,6GAAA,WAAW,OAAA;AAAE,gHAAA,cAAc,OAAA;AAOvD,mDAAmD;AACnD,oDAAoE;AAA3D,mHAAA,wBAAwB,OAAA;AAWjC,sEAAsE;AACtE,gDAO6B;AAN3B,wHAAA,4BAA4B,OAAA;AAC5B,2GAAA,eAAe,OAAA;AACf,sHAAA,0BAA0B,OAAA;AAC1B,4GAAA,gBAAgB,OAAA;AAChB,+GAAA,mBAAmB,OAAA;AACnB,yHAAA,6BAA6B,OAAA"}
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;;;;;;;;;;;;;;;AAEH,0CAAwB;AAExB,4DAA4D;AAC5D,mDAK8B;AAJ5B,wGAAA,UAAU,OAAA;AACV,2GAAA,aAAa,OAAA;AACb,wGAAA,UAAU,OAAA;AACV,gHAAA,kBAAkB,OAAA;AAepB,yEAAoG;AAA3F,iIAAA,wBAAwB,OAAA;AAAE,gIAAA,uBAAuB,OAAA;AAE1D,mDAAmD;AACnD,oEAA0F;AAAjF,wHAAA,kBAAkB,OAAA;AAAE,2HAAA,qBAAqB,OAAA;AAUlD,iEAAiE;AACjE,4DAA2F;AAAlF,mHAAA,iBAAiB,OAAA;AAAE,6GAAA,WAAW,OAAA;AAAE,gHAAA,cAAc,OAAA;AAOvD,mDAAmD;AACnD,oDAAoE;AAA3D,mHAAA,wBAAwB,OAAA;AAWjC,sEAAsE;AACtE,gDAO6B;AAN3B,wHAAA,4BAA4B,OAAA;AAC5B,2GAAA,eAAe,OAAA;AACf,sHAAA,0BAA0B,OAAA;AAC1B,4GAAA,gBAAgB,OAAA;AAChB,+GAAA,mBAAmB,OAAA;AACnB,yHAAA,6BAA6B,OAAA"}

package/dist/storage/topic-reference-links.d.ts

@@ -0,0 +1,10 @@
+import type { TopicReference } from './topic-types';
+/** Format a Markdown-safe href. Does not attach or resolve the target. */
+export declare function formatTopicReferenceLink(reference: TopicReference): string;
+/**
+ * Parse a local topic/sketch/drawing href without I/O. Unknown kinds, malformed
+ * escapes, extra path segments, queries, and fragments return null. Target
+ * existence and navigation belong to the host. Parsing never creates an attachment.
+ */
+export declare function parseTopicReferenceLink(href: string): TopicReference | null;
+//# sourceMappingURL=topic-reference-links.d.ts.map

package/dist/storage/topic-reference-links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic-reference-links.d.ts","sourceRoot":"","sources":["../../src/storage/topic-reference-links.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAmBpD,0EAA0E;AAC1E,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,cAAc,GAAG,MAAM,CAQ1E;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAkB3E"}

package/dist/storage/topic-reference-links.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseTopicReferenceLink = exports.formatTopicReferenceLink = void 0;
+// IDs are opaque single path segments, not paths. Decode exactly once and
+// reject traversal, separators, whitespace, and control characters.
+function isReferenceId(id) {
+    return id.length > 0 && id !== '.' && id !== '..' && !/[/\\\s\u0000-\u001f\u007f]/.test(id);
+}
+function referenceId(reference) {
+    switch (reference.kind) {
+        case 'topic':
+            return reference.topicId;
+        case 'c4-sketch':
+            return reference.sketchId;
+        case 'drawing':
+            return reference.drawingId;
+    }
+}
+/** Format a Markdown-safe href. Does not attach or resolve the target. */
+function formatTopicReferenceLink(reference) {
+    const id = referenceId(reference);
+    if (!isReferenceId(id))
+        throw new Error('Invalid topic reference id');
+    const encoded = encodeURIComponent(id).replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+    return `principal://${reference.kind}/${encoded}`;
+}
+exports.formatTopicReferenceLink = formatTopicReferenceLink;
+/**
+ * Parse a local topic/sketch/drawing href without I/O. Unknown kinds, malformed
+ * escapes, extra path segments, queries, and fragments return null. Target
+ * existence and navigation belong to the host. Parsing never creates an attachment.
+ */
+function parseTopicReferenceLink(href) {
+    const match = /^principal:\/\/(topic|c4-sketch|drawing)\/([^/?#]+)$/.exec(href);
+    if (!match)
+        return null;
+    let id;
+    try {
+        id = decodeURIComponent(match[2]);
+    }
+    catch {
+        return null;
+    }
+    if (!isReferenceId(id))
+        return null;
+    switch (match[1]) {
+        case 'topic':
+            return { kind: 'topic', topicId: id };
+        case 'c4-sketch':
+            return { kind: 'c4-sketch', sketchId: id };
+        default:
+            return { kind: 'drawing', drawingId: id };
+    }
+}
+exports.parseTopicReferenceLink = parseTopicReferenceLink;
+//# sourceMappingURL=topic-reference-links.js.map

package/dist/storage/topic-reference-links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic-reference-links.js","sourceRoot":"","sources":["../../src/storage/topic-reference-links.ts"],"names":[],"mappings":";;;AAEA,0EAA0E;AAC1E,oEAAoE;AACpE,SAAS,aAAa,CAAC,EAAU;IAC/B,OAAO,EAAE,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,IAAI,IAAI,CAAC,4BAA4B,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC9F,CAAC;AAED,SAAS,WAAW,CAAC,SAAyB;IAC5C,QAAQ,SAAS,CAAC,IAAI,EAAE;QACtB,KAAK,OAAO;YACV,OAAO,SAAS,CAAC,OAAO,CAAC;QAC3B,KAAK,WAAW;YACd,OAAO,SAAS,CAAC,QAAQ,CAAC;QAC5B,KAAK,SAAS;YACZ,OAAO,SAAS,CAAC,SAAS,CAAC;KAC9B;AACH,CAAC;AAED,0EAA0E;AAC1E,SAAgB,wBAAwB,CAAC,SAAyB;IAChE,MAAM,EAAE,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;IAClC,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;IACtE,MAAM,OAAO,GAAG,kBAAkB,CAAC,EAAE,CAAC,CAAC,OAAO,CAC5C,UAAU,EACV,CAAC,SAAS,EAAE,EAAE,CAAC,IAAI,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,EAAE,CACxE,CAAC;IACF,OAAO,eAAe,SAAS,CAAC,IAAI,IAAI,OAAO,EAAE,CAAC;AACpD,CAAC;AARD,4DAQC;AAED;;;;GAIG;AACH,SAAgB,uBAAuB,CAAC,IAAY;IAClD,MAAM,KAAK,GAAG,sDAAsD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChF,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,IAAI,EAAU,CAAC;IACf,IAAI;QACF,EAAE,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;KACnC;IAAC,MAAM;QACN,OAAO,IAAI,CAAC;KACb;IACD,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,QAAQ,KAAK,CAAC,CAAC,CAAC,EAAE;QAChB,KAAK,OAAO;YACV,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QACxC,KAAK,WAAW;YACd,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;QAC7C;YACE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;KAC7C;AACH,CAAC;AAlBD,0DAkBC"}

package/dist/storage/topic-types.d.ts

@@ -55,6 +55,22 @@ export interface TopicSubsystemModelRef {
     /** Specific runtime trails (flows) within the model, if narrower than the whole. */
     trailIds?: string[];
 }
+/**
+ * A directional, local-only reference owned by a topic. Targets remain separate
+ * artifacts; their contents and titles are resolved by the host, not copied here.
+ * Referencing a C4 sketch does not make its authored hypothesis evidence.
+ * A drawing ID is the `.excalidraw` file stem under the host's drawings folder.
+ */
+export type TopicReference = {
+    kind: 'c4-sketch';
+    sketchId: string;
+} | {
+    kind: 'drawing';
+    drawingId: string;
+} | {
+    kind: 'topic';
+    topicId: string;
+};
 /**
  * Locally-authored topic — the shape desktop persists to
  * `~/.principal/topics/<id>.json` and edits.
@@ -91,5 +107,11 @@ export interface DraftTopic {
      * the referenced models are a local artifact.
      */
     subsystemModels?: TopicSubsystemModelRef[];
+    /**
+     * Attached topics, C4 sketches, and drawings. Whole-array replacement on update; `[]`
+     * clears attachments. Independent of links in `description`: neither edits
+     * the other. Hosts validate target existence and reject self-references.
+     */
+    references?: TopicReference[];
 }
 //# sourceMappingURL=topic-types.d.ts.map

package/dist/storage/topic-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"topic-types.d.ts","sourceRoot":"","sources":["../../src/storage/topic-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,MAAM,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACtD;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB;IACrC,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,EAAE,EAAE,MAAM,CAAC;IACX,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,gBAAgB;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB,mFAAmF;IACnF,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;IACtB;;;OAGG;IACH,eAAe,CAAC,EAAE,sBAAsB,EAAE,CAAC;CAC5C"}
+{"version":3,"file":"topic-types.d.ts","sourceRoot":"","sources":["../../src/storage/topic-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,MAAM,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACtD;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB;IACrC,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,EAAE,EAAE,MAAM,CAAC;IACX,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,gBAAgB;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB,mFAAmF;IACnF,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;IACtB;;;OAGG;IACH,eAAe,CAAC,EAAE,sBAAsB,EAAE,CAAC;IAC3C;;;;OAIG;IACH,UAAU,CAAC,EAAE,cAAc,EAAE,CAAC;CAC/B"}

package/dist/storage/topicStore.d.ts

@@ -64,7 +64,7 @@ export interface MigrationResult {
  * Fields a caller may set when updating a topic. `id` and `createdAt` are set
  * once at creation and cannot be changed by an update.
  */
-export type TopicUpdate = Partial<Pick<DraftTopic, 'title' | 'description' | 'createdBy' | 'assets' | 'repos' | 'subsystemModels'>>;
+export type TopicUpdate = Partial<Pick<DraftTopic, 'title' | 'description' | 'createdBy' | 'assets' | 'repos' | 'subsystemModels' | 'references'>>;
 /**
  * Fields a caller may set when creating a topic. `id`, `createdAt`,
  * `updatedAt` are filled in when omitted; passing `id` lets a caller control

package/dist/storage/topicStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"topicStore.d.ts","sourceRoot":"","sources":["../../src/storage/topicStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,gEAAgE;AAChE,eAAO,MAAM,aAAa,QAAgC,CAAC;AAC3D,gCAAgC;AAChC,eAAO,MAAM,UAAU,QAAgC,CAAC;AACxD,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,QAAgD,CAAC;AAKhF;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB,EAAE,MAAM,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;CAClB;AA0CD,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,CAC/B,IAAI,CACF,UAAU,EACV,OAAO,GAAG,aAAa,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,GAAG,iBAAiB,CAC/E,CACF,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,EAAE,IAAI,GAAG,WAAW,GAAG,WAAW,CAAC,GAAG;IAC7E,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,KAAK,CAA4B;IACzC,OAAO,CAAC,UAAU,CAAoC;IAEtD;;;;OAIG;gBACS,OAAO,GAAE,MAAmB,EAAE,cAAc,GAAE,MAA2B;IAQrF;;;;;;;;;OASG;IACG,SAAS,CAAC,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAUrE,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAOtD;;;;;OAKG;IACG,IAAI,CAAC,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAKrE,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAkBpD,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAclE,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAa/C;;;;;;;;;;OAUG;IACG,qBAAqB,IAAI,OAAO,CAAC,eAAe,CAAC;YAmEzC,QAAQ;YAQR,YAAY;IAQ1B,4EAA4E;YAC9D,UAAU;YAaV,SAAS;YAUT,cAAc;YAWd,UAAU;YASV,SAAS;IAkBvB,2EAA2E;YAC7D,YAAY;IA2B1B,OAAO,CAAC,YAAY;CAWrB"}
+{"version":3,"file":"topicStore.d.ts","sourceRoot":"","sources":["../../src/storage/topicStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,gEAAgE;AAChE,eAAO,MAAM,aAAa,QAAgC,CAAC;AAC3D,gCAAgC;AAChC,eAAO,MAAM,UAAU,QAAgC,CAAC;AACxD,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,QAAgD,CAAC;AAKhF;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB,EAAE,MAAM,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;CAClB;AA0CD,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,CAC/B,IAAI,CACF,UAAU,EACV,OAAO,GAAG,aAAa,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,GAAG,iBAAiB,GAAG,YAAY,CAC9F,CACF,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,EAAE,IAAI,GAAG,WAAW,GAAG,WAAW,CAAC,GAAG;IAC7E,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,KAAK,CAA4B;IACzC,OAAO,CAAC,UAAU,CAAoC;IAEtD;;;;OAIG;gBACS,OAAO,GAAE,MAAmB,EAAE,cAAc,GAAE,MAA2B;IAQrF;;;;;;;;;OASG;IACG,SAAS,CAAC,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAUrE,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAOtD;;;;;OAKG;IACG,IAAI,CAAC,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAKrE,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAkBpD,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAclE,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAa/C;;;;;;;;;;OAUG;IACG,qBAAqB,IAAI,OAAO,CAAC,eAAe,CAAC;YAmEzC,QAAQ;YAQR,YAAY;IAQ1B,4EAA4E;YAC9D,UAAU;YAaV,SAAS;YAUT,cAAc;YAWd,UAAU;YASV,SAAS;IAkBvB,2EAA2E;YAC7D,YAAY;IA2B1B,OAAO,CAAC,YAAY;CAWrB"}

package/package.json

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

package/src/index.ts

@@ -13,6 +13,15 @@
 
 export * from './types';
 
+export type {
+  DraftTopic,
+  TopicAsset,
+  TopicCreator,
+  TopicSubsystemModelRef,
+  TopicReference,
+} from './storage/topic-types';
+export { formatTopicReferenceLink, parseTopicReferenceLink } from './storage/topic-reference-links';
+
 // Cross-field validation (the rules the JSON Schema can't express). Structural
 // (schema) validation is enforced per surface against
 // `schemas/subsystem-model.schema.json`.

package/src/node.ts

@@ -27,7 +27,9 @@ export type {
   TopicAsset,
   TopicCreator,
   TopicSubsystemModelRef,
+  TopicReference,
 } from './storage/topic-types';
+export { formatTopicReferenceLink, parseTopicReferenceLink } from './storage/topic-reference-links';
 
 // OpenCode event retrieval (Node.js only - SQLite)
 export { OpenCodeEventStore, defaultOpenCodeDBPath } from './opencode/OpenCodeEventStore';

package/src/storage/topic-reference-links.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from 'bun:test';
+import { formatTopicReferenceLink, parseTopicReferenceLink } from './topic-reference-links';
+import type { TopicReference } from './topic-types';
+
+describe('topic reference links', () => {
+  test('formats topic, C4 sketch, and drawing links', () => {
+    expect(formatTopicReferenceLink({ kind: 'topic', topicId: 'topic-123-abc' }))
+      .toBe('principal://topic/topic-123-abc');
+    expect(formatTopicReferenceLink({ kind: 'c4-sketch', sketchId: 'c4s-123-abc' }))
+      .toBe('principal://c4-sketch/c4s-123-abc');
+    expect(formatTopicReferenceLink({ kind: 'drawing', drawingId: '0b6f7c1e-2a4d-4e8f-9c3b-1d2e3f4a5b6c' }))
+      .toBe('principal://drawing/0b6f7c1e-2a4d-4e8f-9c3b-1d2e3f4a5b6c');
+  });
+
+  test('round-trips opaque ids and escapes Markdown delimiters', () => {
+    const references: TopicReference[] = [
+      { kind: 'topic', topicId: 'topic-123-abc' },
+      { kind: 'c4-sketch', sketchId: 'c4s-123-abc' },
+      { kind: 'drawing', drawingId: 'drawing-123' },
+      { kind: 'topic', topicId: "topic-é(1)!'?#%" },
+      { kind: 'topic', topicId: 'topic-%2F' },
+    ];
+    for (const reference of references) {
+      const href = formatTopicReferenceLink(reference);
+      expect(href).not.toMatch(/[()!'?#]/);
+      expect(parseTopicReferenceLink(href)).toEqual(reference);
+    }
+  });
+
+  test('rejects invalid ids when formatting', () => {
+    for (const topicId of ['', '.', '..', 'a/b', 'a\\b', ' a', 'a b', 'a\n', 'a\u0000']) {
+      expect(() => formatTopicReferenceLink({ kind: 'topic', topicId })).toThrow();
+    }
+    expect(() => formatTopicReferenceLink({ kind: 'drawing', drawingId: '../d1' })).toThrow();
+  });
+
+  test('returns null for unsupported or malformed hrefs', () => {
+    for (const href of [
+      '', 'https://example.com', 'pkg:github/acme/repo',
+      'principal://model/sg-1', 'principal://topic/', 'principal://topic',
+      'principal://topic/a/b', 'principal://topic/a/', 'principal://topic/a?q=1',
+      'principal://topic/a#heading', 'principal://topic/..', 'principal://topic/%2e%2e',
+      'principal://topic/%2F', 'principal://topic/%5C', 'principal://topic/%00',
+      'principal://topic/%20', 'principal://topic/a\n', 'principal://topic/%',
+      'principal://topic/%GG', 'principal://topic/%FF',
+      ' principal://topic/a', 'principal://topic@host/a',
+      'principal://drawing/', 'principal://drawing/a/b', 'principal://drawing/..',
+      'principal://drawings/a',
+    ]) {
+      expect(parseTopicReferenceLink(href)).toBeNull();
+    }
+  });
+});

package/src/storage/topic-reference-links.ts

@@ -0,0 +1,54 @@
+import type { TopicReference } from './topic-types';
+
+// IDs are opaque single path segments, not paths. Decode exactly once and
+// reject traversal, separators, whitespace, and control characters.
+function isReferenceId(id: string): boolean {
+  return id.length > 0 && id !== '.' && id !== '..' && !/[/\\\s\u0000-\u001f\u007f]/.test(id);
+}
+
+function referenceId(reference: TopicReference): string {
+  switch (reference.kind) {
+    case 'topic':
+      return reference.topicId;
+    case 'c4-sketch':
+      return reference.sketchId;
+    case 'drawing':
+      return reference.drawingId;
+  }
+}
+
+/** Format a Markdown-safe href. Does not attach or resolve the target. */
+export function formatTopicReferenceLink(reference: TopicReference): string {
+  const id = referenceId(reference);
+  if (!isReferenceId(id)) throw new Error('Invalid topic reference id');
+  const encoded = encodeURIComponent(id).replace(
+    /[!'()*]/g,
+    (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+  return `principal://${reference.kind}/${encoded}`;
+}
+
+/**
+ * Parse a local topic/sketch/drawing href without I/O. Unknown kinds, malformed
+ * escapes, extra path segments, queries, and fragments return null. Target
+ * existence and navigation belong to the host. Parsing never creates an attachment.
+ */
+export function parseTopicReferenceLink(href: string): TopicReference | null {
+  const match = /^principal:\/\/(topic|c4-sketch|drawing)\/([^/?#]+)$/.exec(href);
+  if (!match) return null;
+  let id: string;
+  try {
+    id = decodeURIComponent(match[2]);
+  } catch {
+    return null;
+  }
+  if (!isReferenceId(id)) return null;
+  switch (match[1]) {
+    case 'topic':
+      return { kind: 'topic', topicId: id };
+    case 'c4-sketch':
+      return { kind: 'c4-sketch', sketchId: id };
+    default:
+      return { kind: 'drawing', drawingId: id };
+  }
+}

package/src/storage/topic-types.ts

@@ -56,6 +56,17 @@ export interface TopicSubsystemModelRef {
   trailIds?: string[];
 }
 
+/**
+ * A directional, local-only reference owned by a topic. Targets remain separate
+ * artifacts; their contents and titles are resolved by the host, not copied here.
+ * Referencing a C4 sketch does not make its authored hypothesis evidence.
+ * A drawing ID is the `.excalidraw` file stem under the host's drawings folder.
+ */
+export type TopicReference =
+  | { kind: 'c4-sketch'; sketchId: string }
+  | { kind: 'drawing'; drawingId: string }
+  | { kind: 'topic'; topicId: string };
+
 /**
  * Locally-authored topic — the shape desktop persists to
  * `~/.principal/topics/<id>.json` and edits.
@@ -92,4 +103,10 @@ export interface DraftTopic {
    * the referenced models are a local artifact.
    */
   subsystemModels?: TopicSubsystemModelRef[];
+  /**
+   * Attached topics, C4 sketches, and drawings. Whole-array replacement on update; `[]`
+   * clears attachments. Independent of links in `description`: neither edits
+   * the other. Hosts validate target existence and reject self-references.
+   */
+  references?: TopicReference[];
 }

package/src/storage/topicStore.test.ts

@@ -7,6 +7,7 @@ import { mkdtempSync, rmSync, writeFileSync, existsSync, readFileSync } from 'fs
 import { tmpdir } from 'os';
 import { join } from 'path';
 import { TopicStore } from './topicStore';
+import type { TopicReference } from './topic-types';
 
 let dir: string;
 let topicsDir: string;
@@ -91,6 +92,57 @@ describe('CRUD', () => {
     expect(updated.subsystemModels).toEqual([{ modelId: 'sg-2-def' }]);
   });
 
+  test('references survive fresh reads and unrelated updates, and can be replaced or cleared', async () => {
+    const store = makeStore();
+    const references: TopicReference[] = [
+      { kind: 'c4-sketch', sketchId: 'c4s-1-abc' },
+      { kind: 'drawing', drawingId: 'drawing-1' },
+      { kind: 'topic', topicId: 'topic-related' },
+    ];
+    const created = await store.createTopic({
+      id: 'topic-refs',
+      title: 'Architecture',
+      description: '[Related](principal://topic/topic-related)',
+      subsystemModels: [{ modelId: 'sg-1-abc' }],
+      references,
+    });
+    expect(created.references).toEqual(references);
+    expect((await makeStore().getTopic(created.id))?.references).toEqual(references);
+
+    await store.updateTopic(created.id, { title: 'Renamed' });
+    expect((await makeStore().getTopic(created.id))?.references).toEqual(references);
+
+    const replacement: TopicReference[] = [{ kind: 'topic', topicId: 'topic-other' }];
+    await store.updateTopic(created.id, { references: replacement });
+    expect((await makeStore().getTopic(created.id))?.references).toEqual(replacement);
+
+    await store.updateTopic(created.id, { references: [] });
+    expect(await makeStore().getTopic(created.id)).toMatchObject({
+      references: [],
+      description: created.description,
+      subsystemModels: created.subsystemModels,
+    });
+  });
+
+  test('existing topics need no references migration', async () => {
+    const store = makeStore();
+    const topic = await store.createTopic({ title: 'Without attachments' });
+    expect(topic).not.toHaveProperty('references');
+    await store.updateTopic(topic.id, { description: 'Still without attachments' });
+    expect(await makeStore().getTopic(topic.id)).not.toHaveProperty('references');
+  });
+
+  test('deleting a referenced topic preserves the attachment for missing-target display', async () => {
+    const store = makeStore();
+    const target = await store.createTopic({ title: 'Target' });
+    const owner = await store.createTopic({
+      title: 'Owner',
+      references: [{ kind: 'topic', topicId: target.id }],
+    });
+    await store.deleteTopic(target.id);
+    expect((await makeStore().getTopic(owner.id))?.references).toEqual(owner.references);
+  });
+
   test('delete removes the file and the index entry', async () => {
     const store = makeStore();
     await store.createTopic({ id: 'topic-d', title: 'D' });
@@ -155,37 +207,6 @@ describe('index rebuild', () => {
       'topic-external',
     );
   });
-
-  test('legacy topic files preserve unknown fields verbatim', async () => {
-    const store = makeStore();
-    await store.createTopic({
-      id: 'topic-legacy',
-      title: 'Legacy',
-      repos: ['pkg:github/a/b'],
-    });
-    const topicPath = join(topicsDir, 'topic-legacy.json');
-    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');
-
-    const loaded = await store.getTopic('topic-legacy');
-
-    expect(loaded).toMatchObject({
-      id: 'topic-legacy',
-      title: 'Legacy',
-      description: 'Keep this description',
-      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']);
-  });
 });
 
 describe('migration', () => {

package/src/storage/topicStore.ts

@@ -115,7 +115,7 @@ export interface MigrationResult {
 export type TopicUpdate = Partial<
   Pick<
     DraftTopic,
-    'title' | 'description' | 'createdBy' | 'assets' | 'repos' | 'subsystemModels'
+    'title' | 'description' | 'createdBy' | 'assets' | 'repos' | 'subsystemModels' | 'references'
   >
 >;