dsh-retrace 0.4.26 → 0.4.28

package/lib/boundary-now.js

@@ -0,0 +1,139 @@
+/**
+ * dsh-retrace — lib/boundary-now.js
+ *
+ * READ-SIDE "现在这条" (the counterpart that lives in the conversation TODAY).
+ *
+ * Why this exists (real-machine reading order, 2026-09-15): an entry could say
+ * WHAT it replaced ("原来的内容：…") but never WHERE it was replaced FROM. The
+ * user's words: 「这个条目，现在是什么我并不知道」. The anchor is the message the
+ * action left behind — for an edit/resend it is OUR own `retrace-resend-*` node
+ * (measured: boundary #8699 → #8706), for a regenerate it is the assistant reply
+ * the host produced afterwards.
+ *
+ * What this module deliberately does NOT do: reconstruct the round's input. The
+ * conversation itself is readable — only the REPLACED copy is ours to keep.
+ *
+ * Rules (measured on a 27k-event / 34-boundary session):
+ *  - only `edit` / `regenerate` have a counterpart. A pure `recall` retracts and
+ *    is followed by later, unrelated input — picking that would be a lie.
+ *  - the counterpart must be a LIVE node: anything a later boundary already
+ *    replaced (`shadowedSeqs`) is excluded, otherwise the entry would point at
+ *    a message that is no longer on the surface.
+ *  - the boundary's OWN carrier / audit events are never the counterpart: they
+ *    are the marker, not the new content.
+ *
+ * Pure (no I/O, no host access): the caller passes the log array and the shadowed
+ * set, so the seam, the HTTP route and the tests all drive the same rule.
+ */
+import { eventText, excerpt, roleOf } from './boundary-what.js'
+import { isReplacementSurfaceEvent, replacedSeqsOfBoundary } from './version-index.js'
+
+/** Our own resend node: written by the edit/resend op. */
+export const RESEND_ID_PREFIX = 'retrace-resend-'
+
+/** Any id we write (marker / carrier / resend / fold) — never a counterpart. */
+const OUR_ID_PREFIX = 'retrace-'
+
+/** `<id>` of a surface event, whichever slot the host used. */
+function idOf(event) {
+  const id = event?.data?.id ?? event?.data?.message?.id
+  return typeof id === 'string' ? id : ''
+}
+
+/** One counterpart candidate as the reader needs it (no raw seq shown). */
+function nowOf(event) {
+  return {
+    seq: event.seq,
+    role: roleOf(event),
+    excerpt: excerpt(eventText(event)),
+  }
+}
+
+/**
+ * Index the log once: the counterpart candidates, in ascending seq order.
+ *
+ * @param {object[]} events - the session's events (ascending seq)
+ * @param {Set<number>} [shadowedSeqs] - seqs replaced by SOME boundary (ours or
+ *   the host's). Those are off the surface and cannot be "现在这条".
+ * @returns {{resends: object[], replies: object[]}}
+ */
+export function buildNowIndex(events, shadowedSeqs = new Set()) {
+  const list = Array.isArray(events) ? events : []
+  const shadowed = shadowedSeqs instanceof Set ? shadowedSeqs : new Set()
+  const resends = []
+  const replies = []
+  for (const event of list) {
+    const seq = event?.seq
+    if (!Number.isSafeInteger(seq) || shadowed.has(seq)) continue
+    const id = idOf(event)
+    if (id.startsWith(RESEND_ID_PREFIX)) {
+      resends.push(nowOf(event))
+      continue
+    }
+    // A regenerate's counterpart is the host's new assistant reply. Our own
+    // `retrace-*` nodes are markers, never the reply itself.
+    if (event.type === 'assistant/message' && !id.startsWith(OUR_ID_PREFIX)) replies.push(nowOf(event))
+  }
+  resends.sort((a, b) => a.seq - b.seq)
+  replies.sort((a, b) => a.seq - b.seq)
+  return { resends, replies }
+}
+
+/**
+ * The counterpart of ONE boundary, or null when there is honestly none.
+ *
+ * @param {string} kind - `classifyBoundaryKind` result (`edit` / `regenerate` /
+ *   `recall` / `compaction` / `replace`)
+ * @param {number} boundarySeq
+ * @param {{resends: object[], replies: object[]}} index - from `buildNowIndex`
+ * @returns {{seq:number, role:string, excerpt:string}|null}
+ */
+export function nowOfBoundary(kind, boundarySeq, index) {
+  if (kind !== 'edit' && kind !== 'regenerate') return null
+  if (!Number.isSafeInteger(boundarySeq) || index === null || index === undefined) return null
+  const candidates = kind === 'edit' ? index.resends : index.replies
+  if (!Array.isArray(candidates)) return null
+  for (const candidate of candidates) {
+    if (Number.isSafeInteger(candidate?.seq) && candidate.seq > boundarySeq) return candidate
+  }
+  return null
+}
+
+/**
+ * Every seq that some SURFACE REPLACEMENT took off the surface (ours AND the
+ * host's). Used to keep a counterpart from pointing at a message that is no
+ * longer live.
+ *
+ * Scope = THIS PLUGIN's own replacements (`retrace-*` markers). Two things stay
+ * out, both measured on the real session:
+ *
+ *  - ordinary events that merely CITE their precursors (`tool/result` → its
+ *    `tool/call`). Counting those marked 14644 seqs "shadowed" instead of 107.
+ *  - other surface owners' bulk operations (another plugin's fold ranges, the
+ *    host's compaction checkpoints). They hide ranges from the VIEW/CONTEXT
+ *    while the messages stay in the log. Counting them made every one of the 23
+ *    real edits report "the counterpart is no longer in the log", including the
+ *    case this reading order was specified from: boundary #8699 → the resend
+ *    node #8706.
+ *
+ * Our own later replacement is different: the marker stands in that node's place
+ * for good, so that node can never be "现在这条" again.
+ *
+ * @param {object[]} events
+ * @param {(event:object)=>boolean} [isOurs] - id predicate for this plugin's
+ *   markers (defaults to the `retrace-` prefix).
+ * @returns {Set<number>}
+ */
+export function shadowedSeqsOf(events, isOurs = null) {
+  const owns = typeof isOurs === 'function' ? isOurs : (event) => idOf(event).startsWith(OUR_ID_PREFIX)
+  const shadowed = new Set()
+  if (!Array.isArray(events)) return shadowed
+  for (const event of events) {
+    if (!isReplacementSurfaceEvent(event)) continue
+    if (!owns(event)) continue
+    for (const seq of replacedSeqsOfBoundary(event, null)) {
+      if (Number.isSafeInteger(seq)) shadowed.add(seq)
+    }
+  }
+  return shadowed
+}

package/lib/boundary-tree.js

@@ -0,0 +1,126 @@
+/**
+ * dsh-retrace — lib/boundary-tree.js
+ *
+ * The read-point outline forest: "which change landed inside which discarded
+ * set". Derived from our own boundary artifact (one record per boundary, each
+ * carrying `discardedSeqs` — the exact surface nodes that operation removed),
+ * so the client can indent nested branches without touching the projection wire.
+ *
+ * RULE (frozen 2026-09-14, corrected by measurement; DO NOT change back to set
+ * inclusion):
+ *   parent(C) = the boundary B whose discarded set CONTAINS C's own event seq,
+ *   `C.seq ∈ S(B)`, choosing the SMALLEST such |S(B)|.
+ *
+ * Why NOT `S(C) ⊆ S(B)` (the rule first written into the contract): measured on
+ * a real 24k-event session, the child's discarded nodes were **already dead**
+ * when the parent replaced its range (the child ran FIRST), so
+ * `|S(child) ∩ S(parent)| = 0` for every one of the 8 links of the real 9-layer
+ * chain. The parent's set only holds the child's MARKER event seq — that node was
+ * still on the surface at that moment. Inclusion therefore yields a degenerate
+ * forest (1 parent / depth 1) instead of 14 parents / depth 9. Membership is
+ * still an EXACT SET operation: no numeric interval is ever enumerated, and no
+ * `start ≤ end` ordering is assumed — a reversed range (`[16093..15458]`, real
+ * data) never enters this module.
+ *
+ * The discarded sets may be STORED SLIMMED (`S ∩ allBoundarySeqs`, see
+ * lib/versioning.js) because membership only ever asks about another boundary's
+ * seq; `discardedCount` then carries the exact `|S|`. Both forms must yield a
+ * byte-identical tree (pinned by a test).
+ *
+ * Zero imports (pure): the host, the route and the tests all share one rule.
+ */
+
+/** Parse one record's discarded seqs into a Set (invalid entries dropped). */
+function discardedSetOf(record) {
+  const raw = record?.discardedSeqs
+  if (!Array.isArray(raw)) return null
+  const set = new Set()
+  for (const seq of raw) if (Number.isSafeInteger(seq) && seq >= 0) set.add(seq)
+  return set
+}
+
+/** Exact `|S|`: the stored `discardedCount` when present, else the set's size. */
+function discardedCountOf(record, set) {
+  return Number.isSafeInteger(record?.discardedCount) && record.discardedCount >= 0 ? record.discardedCount : set.size
+}
+
+/** Distance used to break equal-size parent candidates (nearest ancestor wins). */
+function tieBreak(childSeq, a, b) {
+  const da = Math.abs(a.seq - childSeq)
+  const db = Math.abs(b.seq - childSeq)
+  if (da !== db) return da - db
+  return a.seq - b.seq
+}
+
+/**
+ * Build the outline forest from artifact records.
+ *
+ * @param {object[]} records - artifact lines ({ boundarySeq, discardedSeqs, ... })
+ * @returns {{
+ *   tree: Record<string, {parent:number|null, children:number[], discardedCount:number}>,
+ *   maxDepth: number,
+ *   withChildren: number,
+ *   nodes: number
+ * } | null} null when no record carries a usable `discardedSeqs`
+ *   (old artifacts, or a session that never recorded one) — the caller then
+ *   OMITS the field and the client falls back to a flat list.
+ */
+export function boundaryTreeOf(records) {
+  if (!Array.isArray(records)) return null
+  // Latest record wins per boundary (the artifact is append-only).
+  const latest = new Map()
+  for (const record of records) {
+    if (!Number.isSafeInteger(record?.boundarySeq)) continue
+    latest.set(record.boundarySeq, record)
+  }
+  const entries = []
+  for (const [seq, record] of latest) {
+    const set = discardedSetOf(record)
+    if (set === null) continue
+    entries.push({ seq, set, count: discardedCountOf(record, set) })
+  }
+  if (entries.length === 0) return null
+
+  const childrenBySeq = new Map(entries.map((entry) => [entry.seq, []]))
+  const parentBySeq = new Map()
+  for (const child of entries) {
+    let best = null
+    for (const candidate of entries) {
+      if (candidate.seq === child.seq) continue
+      if (!candidate.set.has(child.seq)) continue
+      // Smallest containing set = the direct parent; an intermediate D would be
+      // smaller and would have won. Equal sizes fall back to the nearest seq.
+      if (best === null || candidate.count < best.count || (candidate.count === best.count && tieBreak(child.seq, candidate, best) < 0)) {
+        best = candidate
+      }
+    }
+    parentBySeq.set(child.seq, best === null ? null : best.seq)
+    if (best !== null) childrenBySeq.get(best.seq).push(child.seq)
+  }
+
+  const tree = {}
+  for (const entry of entries) {
+    tree[String(entry.seq)] = {
+      parent: parentBySeq.get(entry.seq) ?? null,
+      children: (childrenBySeq.get(entry.seq) ?? []).slice().sort((a, b) => a - b),
+      discardedCount: entry.count,
+    }
+  }
+
+  const depthMemo = new Map()
+  const depthOf = (seq) => {
+    if (depthMemo.has(seq)) return depthMemo.get(seq)
+    depthMemo.set(seq, 0) // cycle guard (a parent always has a larger discarded set)
+    const kids = childrenBySeq.get(seq) ?? []
+    const depth = kids.length === 0 ? 0 : 1 + Math.max(...kids.map(depthOf))
+    depthMemo.set(seq, depth)
+    return depth
+  }
+  let maxDepth = 0
+  let withChildren = 0
+  for (const entry of entries) {
+    maxDepth = Math.max(maxDepth, depthOf(entry.seq))
+    if ((childrenBySeq.get(entry.seq) ?? []).length > 0) withChildren += 1
+  }
+  return { tree, maxDepth, withChildren, nodes: entries.length }
+}

package/lib/boundary-what.js

@@ -0,0 +1,140 @@
+/**
+ * dsh-retrace — lib/boundary-what.js
+ *
+ * The boundary digest — "what did this boundary change?" (the data gap behind the
+ * unreadable version/fork rows: the projection wire carried only `{seq, type}` /
+ * `{kind, replacedSeqs}`).
+ *
+ * It is built at OPERATION TIME, where the log is still readable: the caller
+ * passes the replaced span events it already resolved to write the marker, this
+ * module turns them into a small `what` payload, and the payload is stored in the
+ * plugin's own artifact (`lib/summary-store.js`) — NOT in the host session log
+ * (a plugin-owned event type without the `ignorable` marker makes the host
+ * persistence reader refuse the whole log) and NOT in the projection wire or the
+ * durable checkpoint (that tax is paid on every append; measured +70.8%/+93.7%).
+ *
+ * Frozen shape (2026-09-14):
+ *   {
+ *     op,                                  // recall|edit|regenerate|restore|compaction|replace
+ *     at?,                                 // boundary time (epoch ms) when known
+ *     new:      { excerpt },               // the action's own NEW text, verbatim
+ *     replaced: [ { seq, role, excerpt, summary? } ],   // ≤ REPLACED_MAX
+ *     replacedMore?,                       // count beyond the listed entries
+ *     artifacts?: { created, modified, deleted }        // counts only
+ *   }
+ *
+ * Only the OLD content is summarized (the new content is still in the
+ * conversation — summarizing it would be parroting). `excerpt` and `summary` are
+ * SEPARATE fields: `excerpt` is verbatim capped log text, `summary` is filled by
+ * the optional LLM half (lib/llm-summary.js) and may be absent.
+ *
+ * Zero imports (pure) so every realm (host, dynamic sandbox, browser) can use it.
+ */
+
+/**
+ * Excerpt cap in characters (before the appended ellipsis).
+ *
+ * 60 fits one timeline/fork row on the target UI width without wrapping and keeps
+ * a full boundary payload (`replaced` × 3) around ~250 bytes. The long-form text
+ * stays reachable through the snapshot / event readers. Truncation appends `…` so
+ * a clipped excerpt is obvious. Note: UTF-16 code units are sliced, so a
+ * surrogate pair at the boundary can be split — acceptable for a display hint.
+ */
+export const EXCERPT_MAX = 60
+
+/** How many replaced entries travel per boundary; the rest become `replacedMore`. */
+export const REPLACED_MAX = 3
+
+/** Message-source roles the payload reports. */
+const ROLE_BY_TYPE = Object.freeze({
+  'user/message': 'user',
+  'assistant/message': 'assistant',
+  'tool/result': 'tool',
+})
+
+/** Collapse whitespace so an excerpt is always a single line (verbatim otherwise). */
+function flatten(text) {
+  return typeof text === 'string' ? text.replace(/\s+/g, ' ').trim() : ''
+}
+
+/** Join an event's text blocks (verbatim characters, no rewriting). */
+function textBlocks(content) {
+  if (!Array.isArray(content)) return ''
+  let out = ''
+  for (const block of content) {
+    if (block && block.type === 'text' && typeof block.text === 'string') out += (out ? ' ' : '') + block.text
+  }
+  return out
+}
+
+/** The role reported for one surface event (`unknown` when unrecognised). */
+export function roleOf(event) {
+  return ROLE_BY_TYPE[event?.type] ?? 'unknown'
+}
+
+/**
+ * The verbatim text carried by one event:
+ *   user/message      → `data.content`
+ *   assistant/message → `data.message.content`, else `data.content`
+ *   tool/result       → `data.message.content`, else the tool name
+ * Returns '' when the event carries no text (image-only prompt, bare tool row…).
+ * @param {object} event
+ * @returns {string}
+ */
+export function eventText(event) {
+  const type = event?.type
+  const data = event?.data
+  if (!data || typeof data !== 'object') return ''
+  if (type === 'user/message') return textBlocks(data.content)
+  if (type === 'assistant/message') return textBlocks(data.message?.content) || textBlocks(data.content)
+  if (type === 'tool/result') return textBlocks(data.message?.content) || textBlocks(data.content) || (typeof data.name === 'string' ? data.name : '')
+  return ''
+}
+
+/**
+ * Truncate one string to the payload cap. `null`/undefined → ''. Whitespace is
+ * flattened first, so the result is always a single line.
+ * @param {unknown} text
+ * @returns {string}
+ */
+export function excerpt(text) {
+  const flat = flatten(text)
+  return flat.length > EXCERPT_MAX ? `${flat.slice(0, EXCERPT_MAX)}…` : flat
+}
+
+/**
+ * Assemble the boundary `what` payload from the replaced span.
+ *
+ * @param {object} input
+ * @param {string} input.op - boundary kind
+ * @param {number} [input.at] - boundary time (epoch ms)
+ * @param {object[]} [input.spanEvents] - the replaced surface events, surface order
+ * @param {number[]} [input.replacedSeqs] - explicit seq list (citation fallback);
+ *   defaults to the span's own seqs
+ * @param {string} [input.newText] - the action's own new text (verbatim; capped)
+ * @param {{created:number, modified:number, deleted:number}} [input.artifacts]
+ */
+export function makeWhat({ op, at, spanEvents = [], replacedSeqs = null, newText = '', artifacts = null }) {
+  const events = Array.isArray(spanEvents) ? spanEvents.filter((event) => event && typeof event.seq === 'number') : []
+  const bySeq = new Map(events.map((event) => [event.seq, event]))
+  const seqs = Array.isArray(replacedSeqs) ? replacedSeqs : events.map((event) => event.seq)
+  const listed = seqs.slice(0, REPLACED_MAX).map((seq) => {
+    const event = bySeq.get(seq)
+    return {
+      seq,
+      role: event === undefined ? 'unknown' : roleOf(event),
+      excerpt: event === undefined ? '' : excerpt(eventText(event)),
+    }
+  })
+  const what = { op: String(op) }
+  if (Number.isSafeInteger(at) && at > 0) what.at = at
+  what.new = { excerpt: excerpt(newText) }
+  what.replaced = listed
+  // Only present when something was cut off (the field is optional; omitting the
+  // zero keeps ~18 bytes off every payload).
+  if (seqs.length > listed.length) what.replacedMore = seqs.length - listed.length
+  if (artifacts && (artifacts.created > 0 || artifacts.modified > 0 || artifacts.deleted > 0)) {
+    what.artifacts = { created: artifacts.created, modified: artifacts.modified, deleted: artifacts.deleted }
+  }
+  return what
+}