dsh-retrace 0.4.2 → 0.4.3

package/lib/projection/forkmap.js

@@ -0,0 +1,69 @@
+/**
+ * dsh-retrace — `retrace/forkmap` projection unit definition.
+ *
+ * Registered on the official `ctx.sessionProjections` registry alongside
+ * `retrace/versions` (PLAN §5.2, P2.1). Same contract as the versions unit:
+ *
+ *   - `stateSchema` — zod schema of the RAW fold state (plain JSON; the
+ *     durable checkpoint validates rows against it),
+ *   - `init` / `apply` — the deterministic fold (lib/forkmap.js),
+ *   - `wire` — the client-visible view ({viewSchema, view}); a unit WITHOUT
+ *     `wire` registers as checkpoint-only and is never served in
+ *     `session/projection` push frames or `snapshot()` (the framework
+ *     contract the P0 versions definition missed; found by the P1 smoke).
+ *
+ * Unlike the versions unit, the fork-map state is NOT truncated: the whole
+ * branch topology must survive (VERSION_LIMIT=200 truncation would drop old
+ * fork points). Per-boundary payloads are tiny (seqs only), so the projection
+ * stays small even for long sessions; node content stays out of the fold
+ * (lazy reads via the HTTP surface when the client needs detail).
+ */
+import { z } from 'zod'
+import {
+  applyForkmap,
+  createForkmapState,
+  viewForkmap,
+} from '../forkmap.js'
+
+const FORK_KINDS = ['recall', 'edit', 'regenerate', 'restore', 'compaction', 'replace']
+
+const forkmapNodeSchema = z.object({
+  seq: z.number().int().nonnegative(),
+  type: z.string(),
+})
+
+const forkmapBoundarySchema = z.object({
+  seq: z.number().int().nonnegative(),
+  kind: z.enum(FORK_KINDS),
+  replacedSeqs: z.array(z.number().int().nonnegative()),
+})
+
+/** Raw fold-state schema (durable checkpoint rows validate against it). */
+export const forkmapStateSchema = z.object({
+  nodes: z.array(forkmapNodeSchema),
+  boundaries: z.array(forkmapBoundarySchema),
+})
+
+/** The wire view schema (what the registry validates and clients receive). */
+export const forkmapViewSchema = forkmapStateSchema
+
+/**
+ * The `retrace/forkmap` unit — register via
+ * `ctx.sessionProjections.register(forkmapProjectionDefinition)`.
+ */
+export const forkmapProjectionDefinition = {
+  key: 'retrace/forkmap',
+  stateSchema: forkmapStateSchema,
+  init: () => createForkmapState(),
+  apply: (state, event) => applyForkmap(state, event),
+  wire: {
+    viewSchema: forkmapViewSchema,
+    view: (state) => viewForkmap(state),
+  },
+  /** Bump when the serialized fold state or fold semantics change. */
+  stateVersion: 1,
+}
+
+// Top-level aliases (unit tests drive the definition directly).
+forkmapProjectionDefinition.schema = forkmapProjectionDefinition.wire.viewSchema
+forkmapProjectionDefinition.view = forkmapProjectionDefinition.wire.view

package/lib/versioning.js

@@ -24,6 +24,7 @@ import {
   retraceDomainSpec,
 } from './artifact-store.js'
 import { versionsProjectionDefinition } from './projection/versions.js'
+import { forkmapProjectionDefinition } from './projection/forkmap.js'
 import { createGitAdapter, createSubprocessRunner } from './git-adapter.js'
 
 /** Max bytes snapshotted per touched file (over → file skipped, version kept). */
@@ -221,6 +222,8 @@ export function createVersioningSeam(ctx, log = () => {}, options = {}) {
     ctx.inject(['sessionProjections', 'sessionQuery', 'storageDomain'], (seam) => {
       seamCtx = seam
       disposers.push(seam.sessionProjections.register(versionsProjectionDefinition))
+      // P2.1 — the fork-map unit: pure fold (branch topology), no side effects.
+      disposers.push(seam.sessionProjections.register(forkmapProjectionDefinition))
       disposers.push(
         seam.sessionProjections.onChanged((session, key, value, seq) => {
           if (key !== 'retrace/versions') return
@@ -255,9 +258,16 @@ export function createVersioningSeam(ctx, log = () => {}, options = {}) {
 
   /** HTTP fallback channel: the live projection snapshot for one session. */
   function snapshot(sessionId) {
-    if (!available()) {
-      return { enabled: false, versions: [] }
-    }
+    return snapshotKey(sessionId, 'retrace/versions', { enabled: false, versions: [] })
+  }
+
+  /** HTTP fallback channel: the fork-map projection snapshot (P2.1). */
+  function snapshotForkmap(sessionId) {
+    return snapshotKey(sessionId, 'retrace/forkmap', { enabled: false, nodes: [], boundaries: [] })
+  }
+
+  function snapshotKey(sessionId, key, empty) {
+    if (!available()) return empty
     const session = ctx.sessions.get(sessionId)
     if (!session) {
       const error = new Error(`session "${sessionId}" not found`)
@@ -265,8 +275,8 @@ export function createVersioningSeam(ctx, log = () => {}, options = {}) {
       throw error
     }
     const cut = seamCtx.sessionProjections.snapshot(session)
-    const value = cut.values['retrace/versions']
-    if (!value) return { enabled: false, versions: [] }
+    const value = cut.values[key]
+    if (!value) return empty
     return { enabled: configFor(sessionId).versioning, ...value }
   }
 
@@ -367,6 +377,7 @@ export function createVersioningSeam(ctx, log = () => {}, options = {}) {
     configFor,
     setConfig,
     snapshot,
+    snapshotForkmap,
     readEvent,
     readSurface,
     agentOf,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-retrace",
   "description": "Retrace · 回溯 — Recall, edit-and-resend, regenerate, and conversation/artifact versioning (timeline, rollback, fork map) for DeepSeek Harness — Web and Desktop",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "packageManager": "pnpm@11.7.0",
   "type": "module",
   "main": "lib/index.js",