@principal-ai/subsystems-core 0.48.1 → 0.49.0

package/schemas/subsystem-model.schema.json

@@ -32,7 +32,7 @@
     },
     "trails": {
       "type": "array",
-      "description": "Ordered runtime trails (one per named behavior). Each step names from/to/mechanism and the concrete file:line where that seam fires.",
+      "description": "Ordered runtime trails (one per named behavior). Each step names from/to/mechanism and the concrete file where that seam fires; the seam's source span is captured by verification.",
       "items": {
         "$ref": "#/$defs/trail"
       }
@@ -231,9 +231,9 @@
             "$ref": "#/$defs/declToken"
           }
         },
-        "declarationRef": {
-          "$ref": "#/$defs/declarationRef",
-          "description": "Anchored declaration location (start line + line hash). Usually populated by verify tooling, not hand-authored. Distinct from `declaration`, which is the structured shape."
+        "declarationSpan": {
+          "$ref": "#/$defs/sourceSpan",
+          "description": "The construct's source span (start/end/content hash) — its anchored identity. Usually populated by verify tooling, not hand-authored. Distinct from `declaration`, which is the structured shape."
         }
       }
     },
@@ -244,7 +244,6 @@
         "to",
         "mechanism",
         "file",
-        "line",
         "purl",
         "symbol"
       ],
@@ -269,10 +268,9 @@
           "pattern": "^(?!.*(^|/)node_modules(/|$)).*$",
           "description": "Repo-root-relative path where the seam fires for this trail."
         },
-        "line": {
-          "type": "integer",
-          "minimum": 1,
-          "description": "1-based line of the site within `file`."
+        "span": {
+          "$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."
         },
         "purl": {
           "type": "string",
@@ -352,36 +350,30 @@
         }
       }
     },
-    "declarationRef": {
+    "sourceSpan": {
       "type": "object",
+      "description": "A content-addressed range of source — the model's identity primitive. startLine/endLine are 1-based inclusive lines within the owner's `file`; contentHash is the hash of the normalized content across that range. `file` / `purl` live on the owner, so a span is a pure range + fingerprint.",
       "required": [
-        "file",
         "startLine",
-        "lineHash",
-        "capturedAt"
+        "endLine",
+        "contentHash"
       ],
       "additionalProperties": false,
       "properties": {
-        "file": {
-          "type": "string",
-          "description": "Repo-root-relative path (matches component.file)."
-        },
         "startLine": {
           "type": "integer",
           "minimum": 1,
-          "description": "1-based declaration start line."
+          "description": "1-based first line of the construct/seam within the owner's file."
         },
-        "lineHash": {
-          "type": "string",
-          "description": "Hash of the normalized declaration line at capture time (drift detection)."
-        },
-        "graphifyNodeId": {
-          "type": "string",
-          "description": "Graphify node id when captured from an exact anchor."
+        "endLine": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "1-based last line, inclusive. Always >= startLine (cross-field rule enforced by validation)."
         },
-        "capturedAt": {
+        "contentHash": {
           "type": "string",
-          "description": "ISO timestamp when this ref was recorded."
+          "minLength": 1,
+          "description": "SHA-256 of the normalized content across [startLine, endLine], truncated to 32 hex chars. The span's identity."
         }
       }
     },

package/src/storage/topic-types.ts

@@ -3,11 +3,11 @@
  * 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 curated bundle of trails on one subject. Two distinct named
- * shapes, split by id-namespace / ownership, with an explicit translation
- * between them — NOT one shared shape. They share most field names, but `id`
- * and `trailIds` live in different namespaces (local vs server), so passing one
- * where the other is expected corrupts the trail foreign-keys.
+ * 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.
  *
  * - {@link DraftTopic}     — locally-authored, what desktop persists + edits.
  * - {@link PublishedTopic} — server-authoritative, what the server returns and
@@ -15,10 +15,8 @@
  * - {@link publishedFromDraft} — the Draft -> Published projection (one-way;
  *                            there is no reverse hydration).
  *
- * The shapes mirror the over-the-wire form used by the sharing API (web-ade) so
- * a published topic and a locally stored one stay interchangeable on read. All
- * timestamps are ISO 8601 strings because this contract crosses the desktop/web
- * boundary.
+ * All timestamps are ISO 8601 strings because this contract crosses the
+ * desktop/web boundary.
  */
 
 /**
@@ -40,13 +38,7 @@ export interface TopicStatus {
    * `new-thought`, so legacy topics and renamed values need no migration.
    */
   state:
-    | 'new-thought'
-    | 'working'
-    | 'paused'
-    | 'waiting'
-    | 'done-for-now'
-    | 'deprecated'
-    | 'abandoned';
+    '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`. */
@@ -57,7 +49,7 @@ export interface TopicStatus {
     until?: string;
     /** Structured pointer to the thing being waited on, for automations. */
     ref?: {
-      kind: 'url' | 'pr' | 'issue' | 'topic' | 'trail';
+      kind: 'url' | 'pr' | 'issue' | 'topic';
       /** The address/id of the referenced thing. */
       value: string;
       /** Optional human label for display. */
@@ -122,8 +114,6 @@ export interface DraftTopic {
   title: string;
   /** Optional markdown body. */
   description?: string;
-  /** Ordered list of LOCAL trail ids — foreign keys into the local trail store. */
-  trailIds: string[];
   /**
    * Repositories this topic is about, as PURL strings (e.g.
    * `pkg:github/owner/repo`). The topic's own source of truth for "which repos"
@@ -160,8 +150,6 @@ export interface PublishedTopic {
   title: string;
   /** Markdown body — required on the server. */
   description: string;
-  /** Ordered list of REMOTE trail ids. */
-  trailIds: string[];
   /**
    * Repositories this topic is about, as PURL strings (e.g.
    * `pkg:github/owner/repo`). Travels with the topic across the wire so a
@@ -184,13 +172,10 @@ export interface PublishedTopic {
  * Inputs the {@link DraftTopic} cannot supply on its own — the namespace
  * crossing and the fields publish must enforce. The caller resolves these
  * before projecting:
- * - `trailIds`: LOCAL trail ids remapped to REMOTE ids (web-ade references
- *   trails by their server id; see desktop's `resolveRemoteTrailIds`).
  * - `createdBy`: required on the server; supplied here if the draft lacks it.
  * - `visibility`: a published concept the draft never carries.
  */
 export interface PublishProjection {
-  trailIds: string[];
   createdBy: TopicCreator;
   visibility: 'private' | 'public';
 }
@@ -199,8 +184,8 @@ export interface PublishProjection {
  * 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 (remapping trail ids,
- * uploading assets, choosing visibility), and this enforces the shape.
+ * 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
@@ -212,19 +197,16 @@ export interface PublishProjection {
  */
 export function publishedFromDraft(
   draft: DraftTopic,
-  projection: PublishProjection,
+  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.`,
-    );
+    throw new Error(`Topic ${draft.id} has no description; a description is required to publish.`);
   }
   return {
     id: draft.id,
     title: draft.title,
     description,
-    trailIds: projection.trailIds,
     ...(draft.repos !== undefined ? { repos: draft.repos } : {}),
     createdAt: draft.createdAt,
     updatedAt: draft.updatedAt,

package/src/storage/topicStore.test.ts

@@ -28,7 +28,7 @@ afterEach(() => {
 describe('CRUD', () => {
   test('create generates an id, persists a file, and reads back', async () => {
     const store = makeStore();
-    const created = await store.createTopic({ title: 'Auth flow', trailIds: [] });
+    const created = await store.createTopic({ title: 'Auth flow' });
     expect(created.id).toMatch(/^topic-/);
     expect(existsSync(join(topicsDir, `${created.id}.json`))).toBe(true);
 
@@ -38,20 +38,22 @@ describe('CRUD', () => {
 
   test('create honors an explicit id and rejects duplicates', async () => {
     const store = makeStore();
-    await store.createTopic({ id: 'topic-x', title: 'A', trailIds: [] });
-    await expect(
-      store.createTopic({ id: 'topic-x', title: 'B', trailIds: [] }),
-    ).rejects.toThrow(/already exists/);
+    await store.createTopic({ id: 'topic-x', title: 'A' });
+    await expect(store.createTopic({ id: 'topic-x', title: 'B' })).rejects.toThrow(
+      /already exists/
+    );
   });
 
-  test('update changes fields but never id/createdAt/trailIds', async () => {
+  test('update changes fields but never id/createdAt', async () => {
     const store = makeStore();
-    const t = await store.createTopic({ id: 'topic-u', title: 'A', trailIds: ['t1'] });
-    const updated = await store.updateTopic('topic-u', { title: 'B', description: 'hi' });
+    const t = await store.createTopic({ id: 'topic-u', title: 'A' });
+    const updated = await store.updateTopic('topic-u', {
+      title: 'B',
+      description: 'hi',
+    });
     expect(updated.title).toBe('B');
     expect(updated.description).toBe('hi');
     expect(updated.createdAt).toBe(t.createdAt);
-    expect(updated.trailIds).toEqual(['t1']);
   });
 
   test('repos (PURL strings) persist on create and are updatable', async () => {
@@ -59,7 +61,6 @@ describe('CRUD', () => {
     const created = await store.createTopic({
       id: 'topic-repos',
       title: 'Repo-scoped',
-      trailIds: [],
       repos: ['pkg:github/acme/web'],
     });
     expect(created.repos).toEqual(['pkg:github/acme/web']);
@@ -78,22 +79,21 @@ describe('CRUD', () => {
       id: 'topic-pub',
       title: 'Pub',
       description: 'has a description',
-      trailIds: ['local-1'],
       repos: ['pkg:github/acme/web'],
       createdAt: '2026-01-01T00:00:00.000Z',
       updatedAt: '2026-01-02T00:00:00.000Z',
     };
     const published = publishedFromDraft(draft, {
-      trailIds: ['remote-1'],
       createdBy: { githubId: 1, githubLogin: 'u1' },
       visibility: 'private',
     });
     expect(published.repos).toEqual(['pkg:github/acme/web']);
+    expect(published).not.toHaveProperty('trailIds');
   });
 
   test('delete removes the file and the index entry', async () => {
     const store = makeStore();
-    await store.createTopic({ id: 'topic-d', title: 'D', trailIds: [] });
+    await store.createTopic({ id: 'topic-d', title: 'D' });
     expect(await store.deleteTopic('topic-d')).toBe(true);
     expect(existsSync(join(topicsDir, 'topic-d.json'))).toBe(false);
     expect(await store.getTopic('topic-d')).toBeNull();
@@ -103,7 +103,7 @@ describe('CRUD', () => {
   test('no eviction cap — many topics all survive', async () => {
     const store = makeStore();
     for (let i = 0; i < 120; i++) {
-      await store.createTopic({ id: `topic-${i}`, title: `T${i}`, trailIds: [] });
+      await store.createTopic({ id: `topic-${i}`, title: `T${i}` });
     }
     expect((await store.getTopics()).length).toBe(120);
   });
@@ -112,30 +112,60 @@ describe('CRUD', () => {
 describe('index rebuild', () => {
   test('a corrupt _index.json is rebuilt by scanning topic files', async () => {
     const store = makeStore();
-    await store.createTopic({ id: 'topic-r', title: 'R', trailIds: ['z'] });
+    await store.createTopic({ id: 'topic-r', title: 'R' });
 
     // Corrupt the manifest and force a fresh store to rebuild from disk.
     writeFileSync(join(topicsDir, '_index.json'), 'not json', 'utf8');
     const fresh = makeStore();
     const list = await fresh.list();
     expect(list.map((e) => e.id)).toContain('topic-r');
-    expect(list.find((e) => e.id === 'topic-r')?.trailCount).toBe(1);
+    expect(list.find((e) => e.id === 'topic-r')).not.toHaveProperty('trailCount');
+    expect(readFileSync(join(topicsDir, '_index.json'), 'utf8')).not.toContain('trailCount');
+  });
+
+  test('legacy topic files drop trailIds but preserve other fields', 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'],
+      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).not.toHaveProperty('trailIds');
+    expect(JSON.parse(readFileSync(topicPath, 'utf8'))).not.toHaveProperty('trailIds');
   });
 });
 
 describe('migration', () => {
-  const seedLegacy = (topics: Partial<DraftTopic>[]) => {
-    writeFileSync(
-      legacyBlob,
-      JSON.stringify({ version: '1.0.0', topics }, null, 2),
-      'utf8',
-    );
+  const seedLegacy = (topics: Record<string, unknown>[]) => {
+    writeFileSync(legacyBlob, JSON.stringify({ version: '1.0.0', topics }, null, 2), 'utf8');
   };
 
   test('fans the blob out to file-per-topic and backs up the blob', async () => {
     seedLegacy([
-      { id: 'topic-1', title: 'One', trailIds: ['a'], createdAt: '2026-01-01T00:00:00.000Z', updatedAt: '2026-01-02T00:00:00.000Z' },
-      { id: 'topic-2', title: 'Two', trailIds: [] },
+      {
+        id: 'topic-1',
+        title: 'One',
+        trailIds: ['a'],
+        createdAt: '2026-01-01T00:00:00.000Z',
+        updatedAt: '2026-01-02T00:00:00.000Z',
+      },
+      { id: 'topic-2', title: 'Two', trailIds: [], repos: ['pkg:github/a/b'] },
     ]);
     const store = makeStore();
     const result = await store.migrateFromLegacyBlob();
@@ -149,6 +179,12 @@ describe('migration', () => {
     const one = await store.getTopic('topic-1');
     expect(one?.title).toBe('One');
     expect(one?.createdAt).toBe('2026-01-01T00:00:00.000Z');
+    expect(one).not.toHaveProperty('trailIds');
+    expect(await store.getTopic('topic-2')).toMatchObject({
+      title: 'Two',
+      repos: ['pkg:github/a/b'],
+    });
+    expect(await store.getTopic('topic-2')).not.toHaveProperty('trailIds');
     expect(existsSync(join(topicsDir, 'topic-1.json'))).toBe(true);
   });
 

package/src/storage/topicStore.ts

@@ -26,15 +26,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 { mkdir, readFile, writeFile, unlink, readdir, rename, access } from 'node:fs/promises';
 import type { DraftTopic, TopicStatus } from './topic-types';
 
 /** Root of the global, cross-repo principal narration store. */
@@ -56,7 +48,6 @@ export interface TopicIndexEntry {
   id: string;
   title: string;
   descriptionPreview: string;
-  trailCount: number;
   /** `status.state` lifted out for filtering/sorting without a file read. */
   state?: TopicStatus['state'];
   createdAt: string;
@@ -75,8 +66,7 @@ interface IndexFileV1 {
 
 const emptyIndex = (): IndexFileV1 => ({ version: 1, entries: [] });
 
-const sanitizeSegment = (value: string): string =>
-  value.replace(/[^A-Za-z0-9._-]/g, '_');
+const sanitizeSegment = (value: string): string => value.replace(/[^A-Za-z0-9._-]/g, '_');
 
 const nowIso = (): string => new Date().toISOString();
 
@@ -91,11 +81,16 @@ const descriptionPreview = (description?: string): string => {
   return `${trimmed.slice(0, DESCRIPTION_PREVIEW_MAX - 1)}…`;
 };
 
+/** Strip the removed topic-to-trail field from data written by older versions. */
+const withoutLegacyTrailIds = (topic: object): Record<string, unknown> => {
+  const { trailIds: _trailIds, ...canonical } = topic as Record<string, unknown>;
+  return canonical;
+};
+
 const buildEntry = (topic: DraftTopic, sizeBytes: number): TopicIndexEntry => ({
   id: topic.id,
   title: topic.title || 'Untitled topic',
   descriptionPreview: descriptionPreview(topic.description),
-  trailCount: topic.trailIds.length,
   state: topic.status?.state,
   createdAt: topic.createdAt,
   updatedAt: topic.updatedAt,
@@ -108,7 +103,7 @@ const buildEntry = (topic: DraftTopic, sizeBytes: number): TopicIndexEntry => ({
 /** Shape the legacy `~/.alexandria/topics.json` blob is parsed as. */
 interface LegacyTopicsBlob {
   version?: string;
-  topics?: DraftTopic[];
+  topics?: unknown[];
 }
 
 export interface MigrationResult {
@@ -123,10 +118,8 @@ export interface MigrationResult {
 }
 
 /**
- * Fields a caller may set when updating a topic. `id`, `createdAt`, and
- * `trailIds` are immutable here — `id`/`createdAt` are set once at creation, and
- * `trailIds` is foreign-keyed membership owned by the desktop's trail store, so
- * a topic update here can never rewrite it.
+ * 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' | 'status' | 'createdBy' | 'assets' | 'repos'>
@@ -142,10 +135,7 @@ export type TopicUpdate = Partial<
  * onto a still-required `id: string` would NOT widen it — an intersection keeps
  * the stricter member — which would leave `id` wrongly required for callers.
  */
-export type TopicCreate = Omit<
-  DraftTopic,
-  'id' | 'createdAt' | 'updatedAt'
-> & {
+export type TopicCreate = Omit<DraftTopic, 'id' | 'createdAt' | 'updatedAt'> & {
   id?: string;
   createdAt?: string;
   updatedAt?: string;
@@ -191,9 +181,7 @@ export class TopicStore {
   /** Cheap listing straight off the manifest — no per-topic file read. */
   async list(): Promise<TopicIndexEntry[]> {
     const idx = await this.getIndex();
-    return idx.entries
-      .slice()
-      .sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : -1));
+    return idx.entries.slice().sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : -1));
   }
 
   async createTopic(input: TopicCreate): Promise<DraftTopic> {
@@ -203,14 +191,13 @@ export class TopicStore {
     if (idx.entries.some((e) => e.id === id)) {
       throw new Error(`Topic with id '${id}' already exists`);
     }
-    const topic: DraftTopic = {
+    const topic = {
       ...input,
       id,
       title: input.title || 'Untitled topic',
-      trailIds: input.trailIds ?? [],
       createdAt: input.createdAt ?? now,
       updatedAt: input.updatedAt ?? now,
-    };
+    } as DraftTopic;
     await this.writeTopic(topic, idx);
     return topic;
   }
@@ -222,7 +209,6 @@ export class TopicStore {
       ...existing,
       ...updates,
       id: existing.id,
-      trailIds: existing.trailIds,
       createdAt: existing.createdAt,
       updatedAt: nowIso(),
     };
@@ -267,26 +253,31 @@ export class TopicStore {
       blob = JSON.parse(raw) as LegacyTopicsBlob;
     } catch {
       throw new Error(
-        `Legacy topics blob at ${this.legacyBlobPath} is not valid JSON; not migrating.`,
+        `Legacy topics blob at ${this.legacyBlobPath} is not valid JSON; not migrating.`
       );
     }
 
     const idx = await this.getIndex();
     let migrated = 0;
     let skipped = 0;
-    for (const legacy of blob.topics ?? []) {
-      if (!legacy?.id) {
+    const legacyTopics = Array.isArray(blob.topics) ? blob.topics : [];
+    for (const legacyValue of legacyTopics) {
+      if (!legacyValue || typeof legacyValue !== 'object' || Array.isArray(legacyValue)) {
+        skipped++;
+        continue;
+      }
+      const legacy = legacyValue as Record<string, unknown>;
+      if (typeof legacy.id !== 'string' || !legacy.id) {
         skipped++;
         continue;
       }
       const now = nowIso();
-      const topic: DraftTopic = {
+      const topic = {
         ...legacy,
-        title: legacy.title || 'Untitled topic',
-        trailIds: legacy.trailIds ?? [],
-        createdAt: legacy.createdAt ?? now,
-        updatedAt: legacy.updatedAt ?? now,
-      };
+        title: typeof legacy.title === 'string' && legacy.title ? legacy.title : 'Untitled topic',
+        createdAt: typeof legacy.createdAt === 'string' ? legacy.createdAt : now,
+        updatedAt: typeof legacy.updatedAt === 'string' ? legacy.updatedAt : now,
+      } as DraftTopic;
       try {
         await this.writeTopic(topic, idx);
         migrated++;
@@ -334,13 +325,14 @@ export class TopicStore {
 
   /** Write a topic file and upsert its index entry. Does not generate ids. */
   private async writeTopic(topic: DraftTopic, idx: IndexFileV1): Promise<void> {
-    const fileName = `${sanitizeSegment(topic.id)}.json`;
+    const canonicalTopic = withoutLegacyTrailIds(topic) as unknown as DraftTopic;
+    const fileName = `${sanitizeSegment(canonicalTopic.id)}.json`;
     const file = join(this.baseDir, fileName);
     await mkdir(dirname(file), { recursive: true });
-    const serialized = JSON.stringify(topic, null, 2);
+    const serialized = JSON.stringify(canonicalTopic, null, 2);
     await writeFile(file, serialized, 'utf8');
-    const entry = buildEntry(topic, Buffer.byteLength(serialized, 'utf8'));
-    const at = idx.entries.findIndex((e) => e.id === topic.id);
+    const entry = buildEntry(canonicalTopic, Buffer.byteLength(serialized, 'utf8'));
+    const at = idx.entries.findIndex((e) => e.id === canonicalTopic.id);
     if (at >= 0) idx.entries[at] = entry;
     else idx.entries.push(entry);
     await this.persistIndex();
@@ -349,7 +341,16 @@ export class TopicStore {
   private async readTopic(fileName: string): Promise<DraftTopic | null> {
     try {
       const raw = await readFile(join(this.baseDir, fileName), 'utf8');
-      return JSON.parse(raw) as DraftTopic;
+      const parsed = JSON.parse(raw) as Record<string, unknown>;
+      const topic = withoutLegacyTrailIds(parsed) as unknown as DraftTopic;
+      if ('trailIds' in parsed) {
+        try {
+          await writeFile(join(this.baseDir, fileName), JSON.stringify(topic, null, 2), 'utf8');
+        } catch (err) {
+          console.warn('[TopicStore] Failed to remove legacy trailIds from', fileName, err);
+        }
+      }
+      return topic;
     } catch (err) {
       console.error('[TopicStore] Failed to read topic', fileName, err);
       return null;
@@ -381,7 +382,20 @@ export class TopicStore {
       const raw = await readFile(this.indexPath, 'utf8');
       const parsed = JSON.parse(raw) as Partial<IndexFileV1>;
       if (parsed?.version === 1 && Array.isArray(parsed.entries)) {
-        return { version: 1, entries: parsed.entries as TopicIndexEntry[] };
+        let hadLegacyTrailCount = false;
+        const entries = parsed.entries.map((entry) => {
+          hadLegacyTrailCount ||= Boolean(
+            entry && typeof entry === 'object' && 'trailCount' in entry
+          );
+          const { trailCount: _trailCount, ...canonical } = entry as TopicIndexEntry & {
+            trailCount?: number;
+          };
+          return canonical;
+        });
+        if (hadLegacyTrailCount) {
+          await writeFile(this.indexPath, JSON.stringify({ version: 1, entries }, null, 2), 'utf8');
+        }
+        return { version: 1, entries };
       }
     } catch (err) {
       const code = (err as NodeJS.ErrnoException).code;
@@ -408,13 +422,12 @@ export class TopicStore {
       const topic = await this.readTopic(name);
       if (!topic?.id) continue;
       const createdAt = topic.createdAt ?? nowIso();
-      const stamped: DraftTopic = {
+      const stamped = {
         ...topic,
         createdAt,
         updatedAt: topic.updatedAt ?? createdAt,
         title: topic.title || 'Untitled topic',
-        trailIds: topic.trailIds ?? [],
-      };
+      } as DraftTopic;
       const raw = JSON.stringify(stamped, null, 2);
       idx.entries.push(buildEntry(stamped, Buffer.byteLength(raw, 'utf8')));
     }

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

@@ -46,8 +46,18 @@ describe("subsystem-model schema", () => {
 		expect(schema.properties.verifiedAtCommits).toBeDefined();
 	});
 
-	test("no longer carries per-declaration revision (superseded by the model-level pin)", () => {
-		expect(schema.$defs.declarationRef?.properties?.revision).toBeUndefined();
+	test("declares a content-addressed source span", () => {
+		// The identity primitive: start + end + content hash. Replaces the old
+		// start-line-only `declarationRef`.
+		expect(schema.$defs.sourceSpan?.properties?.startLine).toBeDefined();
+		expect(schema.$defs.sourceSpan?.properties?.endLine).toBeDefined();
+		expect(schema.$defs.sourceSpan?.properties?.contentHash).toBeDefined();
+		expect(schema.$defs.declarationRef).toBeUndefined();
+	});
+
+	test("trail steps carry a span, not a bare line", () => {
+		expect(schema.$defs.trailStep?.properties?.span).toBeDefined();
+		expect(schema.$defs.trailStep?.properties?.line).toBeUndefined();
 	});
 
 	test("a store declares its own value type", () => {