dsh-retrace 0.4.2 → 0.4.5

package/lib/forkmap.js

@@ -0,0 +1,106 @@
+/**
+ * dsh-retrace — `retrace/forkmap` pure fold (PLAN §5.2, P2.1).
+ *
+ * The fork map is the BRANCH-TOPOLOGY presentation layer ("how we got here"):
+ * every surface replacement — recall / edit / regenerate / restore markers,
+ * compaction checkpoints, and any other replace — is a FORK POINT that shadows
+ * a range of the old path and continues a new path. This module mirrors the
+ * official `foldSurface` state transition (the same one the versions unit
+ * uses) and additionally records each boundary with the seqs it shadowed, so
+ * the client can render:
+ *
+ *   spine     — the current-surface node flow (markers sit ON the spine),
+ *   branches  — at each boundary, the shadowed (old-path) node cluster.
+ *
+ * Data notes (verified against the official source, 2026-08-26):
+ *   - replace `start`/`end` are EVENT SEQS (not surface indices); the shadowed
+ *     seqs are the surface nodes the splice removed — exactly
+ *     `foldSurface(...).replacements[].shadowedSeqs`.
+ *   - official `traceEvent` does NOT link a marker to its new path
+ *     (new-path events never cite the marker, so `derivedEventSeqs` is empty)
+ *     — the new path IS the spine: the surface nodes after the boundary
+ *     (PLAN.md:295 "标记→新路径无需自解析" corrected by research).
+ *   - boundaries ARE the versions (every replacement closes a version); the
+ *     wire stays lean (no markerText — the client joins it from
+ *     `retrace/versions` by boundarySeq).
+ *
+ * The module is import-free except for the shared boundary predicates, stays
+ * transport-neutral, and is registered alongside `retrace/versions` in the
+ * versioning seam. No side effects: pure fold only.
+ */
+import {
+  classifyBoundaryKind,
+  isReplacementSurfaceEvent,
+  isSurfaceEvent,
+} from './version-index.js'
+
+/** Fork-map fold state (plain JSON — durable checkpoint rows validate it). */
+export function createForkmapState() {
+  return {
+    /** Current surface nodes: `{ seq, type }` in fold order (mirror foldSurface). */
+    nodes: [],
+    /** Replacement boundaries in append order. */
+    boundaries: [],
+  }
+}
+
+/**
+ * Fold one committed event into the fork-map state.
+ *
+ * Performance contract (load-bearing for the projection registry): when the
+ * event changes nothing — no surface move, no boundary — the SAME state
+ * reference is returned (`Object.is` gates the change feed).
+ *
+ * @param {ReturnType<typeof createForkmapState>} state
+ * @param {object} event
+ * @returns the next state (same reference when nothing changed).
+ */
+export function applyForkmap(state, event) {
+  if (!event || typeof event.seq !== 'number') return state
+  let next = state
+  let shadowed = null
+
+  // 1. Surface fold (mirror foldSurface / the versions unit).
+  if (isSurfaceEvent(event)) {
+    const op = event.surfaceOp
+    if (op === 'append') {
+      next = { ...next, nodes: [...next.nodes, { seq: event.seq, type: event.type }] }
+    } else if (op && op.op === 'replace') {
+      const startIdx = next.nodes.findIndex((node) => node.seq === op.start)
+      const endIdx = next.nodes.findIndex((node) => node.seq === op.end)
+      if (startIdx !== -1 && endIdx !== -1 && startIdx <= endIdx) {
+        shadowed = next.nodes.slice(startIdx, endIdx + 1).map((node) => node.seq)
+        const nodes = next.nodes.slice()
+        nodes.splice(startIdx, endIdx - startIdx + 1, { seq: event.seq, type: event.type })
+        next = { ...next, nodes }
+      }
+    }
+  }
+
+  // 2. Boundary (fork point). The shadowed range is the splice's removal when
+  //    the span was live; otherwise fall back to the marker's own citation.
+  if (isReplacementSurfaceEvent(event)) {
+    const cited = Array.isArray(event.sourceEventSeqs) ? event.sourceEventSeqs : []
+    const replacedSeqs = shadowed !== null ? shadowed : cited
+    const boundary = {
+      seq: event.seq,
+      kind: classifyBoundaryKind(event),
+      replacedSeqs,
+    }
+    next = { ...next, boundaries: [...next.boundaries, boundary] }
+  }
+
+  return next
+}
+
+/** The client-visible wire value (what `session/projection` frames serve). */
+export function viewForkmap(state) {
+  return {
+    nodes: state.nodes.map((node) => ({ seq: node.seq, type: node.type })),
+    boundaries: state.boundaries.map((boundary) => ({
+      seq: boundary.seq,
+      kind: boundary.kind,
+      replacedSeqs: boundary.replacedSeqs,
+    })),
+  }
+}

package/lib/http.js

@@ -8,6 +8,9 @@
  *   GET  /api/plugins/retrace/versions?sessionId=
  *     — live projection snapshot (HTTP fallback channel; the push channel is
  *       `session/projection` frames via dsh-host-apiproxy).
+ *   GET  /api/plugins/retrace/forkmap?sessionId=
+ *     — the fork-map projection snapshot (branch topology, P2.1; same
+ *       push-frame + HTTP fallback dual channel as /versions).
  *   GET  /api/plugins/retrace/event?sessionId=&seq=&before=&after=
  *     — one event + context window (sessionQuery.readEvent, lazy reads).
  *   GET  /api/plugins/retrace/surface?sessionId=
@@ -87,6 +90,15 @@ export function createRetraceHttpHandler(ctx, { sessions, agents, seam, rollback
     }
   }
 
+  function handleForkmap(req, res, sessionId, config) {
+    seam.setConfig(sessionId, config)
+    try {
+      sendJson(res, 200, { ok: true, value: seam.snapshotForkmap(sessionId) })
+    } catch (error) {
+      sendError(res, error)
+    }
+  }
+
   async function handleEvent(req, res, searchParams) {
     const sessionId = searchParams.get('sessionId') ?? ''
     const seq = Number(searchParams.get('seq'))
@@ -249,6 +261,8 @@ export function createRetraceHttpHandler(ctx, { sessions, agents, seam, rollback
       switch (op) {
         case 'versions':
           return handleVersions(req, res, sessionId, config)
+        case 'forkmap':
+          return handleForkmap(req, res, sessionId, config)
         case 'event':
           return void handleEvent(req, res, searchParams)
         case 'surface':

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
@@ -243,7 +246,11 @@ export function createVersioningSeam(ctx, log = () => {}, options = {}) {
           const global = opened.global.get()
           if (global) {
             // Seed session configs with the durable defaults (per-request overrides win).
-            for (const [id, config] of configs) setConfig(id, { ...config, ...global })
+            // The domain schema spells the git switch `gitEnabled` (0.4.x review:
+            // it was merged in but never read — consumers use `config.git`).
+            const seeded = { ...global, git: global.gitEnabled ?? configs.get('')?.git ?? true }
+            delete seeded.gitEnabled
+            for (const [id, config] of configs) setConfig(id, { ...config, ...seeded })
           }
         })
         .catch((error) => log(`retrace: versioning disabled: ${String(error)}`))
@@ -255,9 +262,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 +279,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 +381,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.5",
   "packageManager": "pnpm@11.7.0",
   "type": "module",
   "main": "lib/index.js",