dsh-trivium 0.4.21 → 0.5.0

package/lib/server.js

@@ -19,11 +19,25 @@ import {
 } from "./store.js";
 import { embeddingPublicStatus } from "./embed.js";
 import { chipsEnabledOf, configPanelOpenOf, gitSidecarEnabledOf, listedWorkspaces, pluginLocaleOf, recallModeOf, sessionLayerEnabledOf, writeUiSettings } from "./settings.js";
+import { TURN_ADDITIONAL_BUDGET } from "./context-budget.js";
 import { discoverWorkbuddyFiles, discoverExternalFiles, exportMarkdown, importWorkbuddy, importExternal } from "./markdown.js";
 import { checkNpmUpdate, installedVersion } from "./update.js";
 import { writeGateMessage } from "./hygiene.js";
 import { backfillSessionMap, cutSessionMap, renameEpisode, sessionMapSnapshot } from "./episode.js";
 import { applyPinsUpdate, addChipsFromText, batchChipAction, listChips, readSessionPins } from "./pins.js";
+import {
+  historyOf,
+  nodeDetail,
+  REVISION_CODES,
+  revisionMessage,
+  revokeSupersession,
+  supersede,
+  withWorkspaceQueue,
+} from "./revisions.js";
+import { provenanceOf } from "./provenance.js";
+import { getTrace, listTraces, listTracesForCwd } from "./recall-trace.js";
+import { recallPreview } from "./recall-preview.js";
+import { sidecarHealth } from "./sidecar.js";
 
 export { readUiSettings, writeUiSettings } from "./settings.js";
 
@@ -141,6 +155,22 @@ async function handle(req, res, { liveOptions, status }) {
       lastInjectTokens: status.lastInjectTokens || 0,
       lastInjectAt: status.lastInjectAt || null,
       lastExtract: status.lastExtract || null,
+      // Estimates, not model tokens: the UI must label them as such.
+      mapTokenBudget: opts.mapTokenBudget || 400,
+      turnTokenBudget: TURN_ADDITIONAL_BUDGET,
+      lastContextPlan: status.lastContextPlan
+        ? {
+            at: status.lastContextPlan.at,
+            tokens: status.lastContextPlan.tokens,
+            budget: status.lastContextPlan.budget,
+            records: status.lastContextPlan.records,
+            deferred: status.lastContextPlan.deferred,
+          }
+        : null,
+      preStep: status.preStep || null,
+      lastTrace: status.lastTrace
+        ? { traceId: status.lastTrace.traceId, at: status.lastTrace.at, tokens: status.lastTrace.tokens }
+        : null,
       version: installedVersion(),
       recallMode: mode,
       autoRecall: mode === "auto",
@@ -152,8 +182,10 @@ async function handle(req, res, { liveOptions, status }) {
       pluginLocale: pluginLocaleOf(opts),
       configPanelOpen: configPanelOpenOf(opts),
       writeApproval: !!opts.writeApproval,
-      mapTokenBudget: opts.mapTokenBudget || 400,
       workspaces: listOpenWorkspaces(),
+      // The graph is authoritative; the JSONL file is derived. Report its state
+      // instead of pretending the two files are one atomic unit.
+      derived: { sidecar: sidecarHealth() },
       ...embeddingPublicStatus(),
     });
     return;
@@ -294,6 +326,8 @@ async function handle(req, res, { liveOptions, status }) {
     const q = url.searchParams.get("q") || "";
     const includeArchived = url.searchParams.get("archived") === "1";
     const includeStale = url.searchParams.get("stale") === "1";
+    // "Show expired" and "show replaced" are separate switches.
+    const includeSuperseded = url.searchParams.get("superseded") === "1";
     const about = url.searchParams.get("about") || "";
     sendJson(res, 200, {
       ok: true,
@@ -303,12 +337,115 @@ async function handle(req, res, { liveOptions, status }) {
         q: q || undefined,
         includeArchived,
         includeStale,
+        includeSuperseded,
         aboutId: about || undefined,
       }),
     });
     return;
   }
 
+  /*
+   * Detail / provenance / history are read-on-demand surfaces. The detail
+   * response is a header only; full quotes and full history bodies stay behind
+   * their own endpoints so the list cannot accidentally pull all of it.
+   */
+  const detailMatch = path.match(/^\/api\/dsh-trivium\/nodes\/(\d+)\/detail$/);
+  if (detailMatch && method === "GET") {
+    const { cwd, db } = await dbForRequest(url);
+    if (!db) {
+      sendJson(res, 400, { ok: false, message: "no workspace" });
+      return;
+    }
+    const detail = nodeDetail(db, detailMatch[1]);
+    sendJson(res, detail ? 200 : 404, detail || { ok: false, message: "not found" });
+    return;
+  }
+
+  const provenanceMatch = path.match(/^\/api\/dsh-trivium\/nodes\/(\d+)\/provenance$/);
+  if (provenanceMatch && method === "GET") {
+    const { db } = await dbForRequest(url);
+    if (!db) {
+      sendJson(res, 400, { ok: false, message: "no workspace" });
+      return;
+    }
+    const prov = provenanceOf(db, provenanceMatch[1]);
+    sendJson(res, prov ? 200 : 404, prov || { ok: false, message: "not found" });
+    return;
+  }
+
+  const historyMatch = path.match(/^\/api\/dsh-trivium\/nodes\/(\d+)\/history$/);
+  if (historyMatch && method === "GET") {
+    const { cwd, db } = await dbForRequest(url);
+    if (!db) {
+      sendJson(res, 400, { ok: false, message: "no workspace" });
+      return;
+    }
+    const result = historyOf(db, historyMatch[1], {
+      limit: url.searchParams.get("limit") || 20,
+      cursor: url.searchParams.get("cursor") || "",
+    });
+    if (!result.ok) {
+      sendJson(res, 409, { ok: false, reason: result.reason, message: "version chain unresolved", ...result });
+      return;
+    }
+    sendJson(res, 200, { ok: true, cwd, ...result });
+    return;
+  }
+
+  if (path === "/api/dsh-trivium/recall-traces" && method === "GET") {
+    const cwd = url.searchParams.get("cwd") || getActiveCwd() || "";
+    if (url.searchParams.get("cwd") && !isKnownCwd(cwd)) {
+      sendJson(res, 400, { ok: false, message: "unknown workspace" });
+      return;
+    }
+    const sessionId = url.searchParams.get("session") || "";
+    const limit = url.searchParams.get("limit") || undefined;
+    sendJson(res, 200, {
+      ok: true,
+      cwd,
+      sessionId,
+      // No session filter means "every session of this workspace", which is
+      // still one workspace boundary. A session filter narrows it further.
+      traces: sessionId
+        ? listTraces({ cwd, sessionId, limit })
+        : listTracesForCwd({ cwd, limit }),
+    });
+    return;
+  }
+
+  const traceMatch = path.match(/^\/api\/dsh-trivium\/recall-traces\/([A-Za-z0-9-]+)$/);
+  if (traceMatch && method === "GET") {
+    const cwd = url.searchParams.get("cwd") || getActiveCwd() || "";
+    const found = getTrace(traceMatch[1], { cwd, sessionId: url.searchParams.get("session") || "" });
+    if (!found.ok) {
+      // 410 for an expired id, 404 for another workspace/session: the caller
+      // learns nothing about traces that are not theirs.
+      sendJson(res, found.status, { ok: false, message: found.message });
+      return;
+    }
+    sendJson(res, 200, { ok: true, cwd, trace: found.trace });
+    return;
+  }
+
+  if (path === "/api/dsh-trivium/recall-preview" && method === "POST") {
+    const { cwd, db } = await dbForRequest(url);
+    if (!db) {
+      sendJson(res, 400, { ok: false, message: "no workspace" });
+      return;
+    }
+    const body = JSON.parse((await readBody(req)) || "{}");
+    const sessionId = body.sessionId || url.searchParams.get("sessionId") || "";
+    const opts = liveOptions();
+    const result = recallPreview(db, {
+      cwd,
+      sessionId,
+      query: body.query,
+      mode: body.mode || recallModeOf(opts),
+    });
+    sendJson(res, result.ok ? 200 : result.status || 400, { ...result, cwd, sessionId });
+    return;
+  }
+
   const mergeMatch = path.match(/^\/api\/dsh-trivium\/nodes\/(\d+)\/merge$/);
   if (mergeMatch && method === "POST") {
     const { db } = await dbForRequest(url);
@@ -318,7 +455,61 @@ async function handle(req, res, { liveOptions, status }) {
     }
     const body = JSON.parse((await readBody(req)) || "{}");
     const result = mergeNodes(db, mergeMatch[1], body.dropId);
-    sendJson(res, result.ok ? 200 : 400, result);
+    sendJson(res, result.status || (result.ok ? 200 : 400), result);
+    return;
+  }
+
+  /*
+   * Revision writes. Every one of them is validated server-side inside the
+   * workspace queue: the client's hidden buttons and the prototype's demo
+   * state are not trusted, and the second window always loses on a stale ETag.
+   */
+  const supersedeMatch = path.match(/^\/api\/dsh-trivium\/nodes\/(\d+)\/supersede$/);
+  if (supersedeMatch && method === "POST") {
+    const { cwd, db } = await dbForRequest(url);
+    if (!db) {
+      sendJson(res, 400, { ok: false, message: "no workspace" });
+      return;
+    }
+    const body = JSON.parse((await readBody(req)) || "{}");
+    const result = await withWorkspaceQueue(cwd, () =>
+      supersede(db, {
+        oldId: supersedeMatch[1],
+        successorId: body.successorId,
+        reason: body.reason,
+        expectedEtags: body.expectedEtags,
+        operationId: body.operationId,
+      }),
+    );
+    sendJson(res, result.ok ? 200 : result.status || 400, {
+      ...result,
+      cwd,
+      detail: result.ok ? null : revisionMessage(result.code),
+    });
+    return;
+  }
+
+  const revokeMatch = path.match(/^\/api\/dsh-trivium\/nodes\/(\d+)\/supersession\/revoke$/);
+  if (revokeMatch && method === "POST") {
+    const { cwd, db } = await dbForRequest(url);
+    if (!db) {
+      sendJson(res, 400, { ok: false, message: "no workspace" });
+      return;
+    }
+    const body = JSON.parse((await readBody(req)) || "{}");
+    const result = await withWorkspaceQueue(cwd, () =>
+      revokeSupersession(db, {
+        oldId: revokeMatch[1],
+        successorId: body.successorId,
+        expectedEtags: body.expectedEtags,
+        operationId: body.operationId,
+      }),
+    );
+    sendJson(res, result.ok ? 200 : result.status || 400, {
+      ...result,
+      cwd,
+      detail: result.ok ? null : revisionMessage(result.code),
+    });
     return;
   }
 
@@ -351,8 +542,17 @@ async function handle(req, res, { liveOptions, status }) {
       return;
     }
     const id = Number(nodeMatch[1]);
-    const ok = nodeMatch[2] === "archive" ? archiveNode(db, id) : deleteNode(db, id);
-    sendJson(res, ok ? 200 : 404, { ok, id });
+    try {
+      const ok = nodeMatch[2] === "archive" ? archiveNode(db, id) : deleteNode(db, id);
+      sendJson(res, ok ? 200 : 404, { ok, id });
+    } catch (err) {
+      // A node inside a revision chain needs its relation handled first.
+      if (err?.code === "REVISION_LINKED") {
+        sendJson(res, 409, { ok: false, id, code: err.code, message: revisionMessage(REVISION_CODES.revisionLinked) });
+        return;
+      }
+      throw err;
+    }
     return;
   }
 

package/lib/sidecar.js

@@ -4,7 +4,7 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { atomicWriteFile } from "./atomic.js";
-import { BUSINESS_EDGES } from "./schema.js";
+import { BUSINESS_EDGES, REVISION_EDGES, nowIso, weightOf } from "./schema.js";
 import {
   gitSidecarEnabledOf,
   listedWorkspaces,
@@ -14,13 +14,44 @@ import {
 } from "./settings.js";
 
 export const SIDECAR_FORMAT = "dsh-trivium-jsonl";
-export const SIDECAR_VERSION = 1;
+/**
+ * v2 adds revision relations with their edge metadata. A v1 file is still read:
+ * it simply carries no supersedes rows. Downgrading is not supported in place —
+ * restore the pre-upgrade file group (see README) rather than letting an older
+ * build rewrite the chain away.
+ */
+export const SIDECAR_VERSION = 2;
 export const SIDECAR_DEBOUNCE_MS = 1500;
 export const BUSINESS_NODE_TYPES = Object.freeze(["entity", "preference", "decision", "experience"]);
 
 const timers = new Map();
 const memoryHash = new Map();
 
+/**
+ * Whether the derived JSONL file is currently in step with the graph.
+ *
+ * The graph is authoritative; this file is a projection written after the
+ * fact. A failure here is reported rather than hidden, and the next open
+ * (`syncSidecarOnOpen`) repairs it.
+ */
+const health = { ok: true, error: "", at: "" };
+
+function noteSidecarError(err) {
+  health.ok = false;
+  health.error = String(err?.message || err || "sidecar write failed");
+  health.at = new Date().toISOString();
+}
+
+function noteSidecarOk() {
+  health.ok = true;
+  health.error = "";
+  health.at = new Date().toISOString();
+}
+
+export function sidecarHealth() {
+  return { ...health, enabled: gitSidecarEnabledOf(readUiSettings()) };
+}
+
 export function sidecarPath(cwd) {
   return join(resolve(cwd || ""), ".dsh", "trivium.jsonl");
 }
@@ -116,7 +147,9 @@ export function serializeGraph(db) {
   nodes.sort((a, b) => String(a.uri).localeCompare(String(b.uri)));
   const edges = [];
   const seen = new Set();
-  const want = new Set(BUSINESS_EDGES);
+  // Business edges plus revision relations: a chain has to survive a clone, and
+  // the relation reason lives in the edge metadata.
+  const want = new Set([...BUSINESS_EDGES, ...REVISION_EDGES]);
   for (const id of db.allNodeIds?.() || []) {
     const fromUri = uriOf.get(Number(id));
     if (!fromUri) continue;
@@ -129,7 +162,9 @@ export function serializeGraph(db) {
       const key = `${fromUri}\0${toUri}\0${label}`;
       if (seen.has(key)) continue;
       seen.add(key);
-      edges.push({ op: "edge", from: fromUri, to: toUri, type: label });
+      const row = { op: "edge", from: fromUri, to: toUri, type: label };
+      if (e.metadata && typeof e.metadata === "object") row.meta = e.metadata;
+      edges.push(row);
     }
   }
   edges.sort((a, b) => {
@@ -173,10 +208,15 @@ export function parseSidecar(text) {
     }
     if (op === "edge") {
       const label = row.type || row.label || "";
-      if (!BUSINESS_EDGES.includes(label) || !row.from || !row.to) {
+      if ((!BUSINESS_EDGES.includes(label) && !REVISION_EDGES.includes(label)) || !row.from || !row.to) {
         return { ok: false, message: "invalid edge" };
       }
-      edges.push({ from: row.from, to: row.to, type: label });
+      edges.push({
+        from: row.from,
+        to: row.to,
+        type: label,
+        meta: row.meta && typeof row.meta === "object" ? row.meta : null,
+      });
       continue;
     }
     return { ok: false, message: "unknown jsonl row" };
@@ -276,10 +316,12 @@ export function writeSidecarNow(cwd, db, { force = false } = {}) {
   const hash = hashText(text);
   const file = sidecarPath(cwd);
   if (!force && hash === knownHash(cwd) && existsSync(file)) {
+    noteSidecarOk();
     return { path: file, hash, wrote: false };
   }
   atomicWriteFile(file, text);
   rememberHash(cwd, hash);
+  noteSidecarOk();
   return { path: file, hash, wrote: true };
 }
 
@@ -293,8 +335,11 @@ export function scheduleSidecarWrite(cwd, db) {
     timers.delete(key);
     try {
       writeSidecarNow(key, db);
-    } catch {
-      // disk errors are non-fatal
+      noteSidecarOk();
+    } catch (err) {
+      // Disk errors are non-fatal, but they are visible: status reports them and
+      // reopening the workspace retries the sync.
+      noteSidecarError(err);
     }
   }, SIDECAR_DEBOUNCE_MS);
   timers.set(key, timer);
@@ -314,6 +359,7 @@ export function flushSidecarNow(cwd, db) {
 async function applySidecar(db, parsed) {
   const store = await import("./store.js");
   const uriSet = new Set();
+  const conflicts = [];
   store.runWithoutSidecar(() => {
     const idByUri = new Map();
     for (const row of parsed.nodes) {
@@ -333,27 +379,63 @@ async function applySidecar(db, parsed) {
         createdAt: row.createdAt || "",
         updatedAt: row.updatedAt || "",
       };
-      if (!payload.until) delete payload.until;
+      // Keep the empty label as an explicit clear when reconciling a snapshot.
       if (!payload.untilAt) delete payload.untilAt;
       if (!payload.fail) delete payload.fail;
       if (!payload.fix) delete payload.fix;
       let dest = store.findByUri(db, uri);
-      if (dest == null) dest = store.findMergeTarget(db, payload);
+      if (dest == null) dest = store.findMergeTarget(db, payload, { allowRevisionLinked: true });
       if (dest != null) {
-        store.mergeInto(db, dest, payload);
-        idByUri.set(uri, dest);
+        try {
+          store.mergeInto(db, dest, payload);
+          idByUri.set(uri, dest);
+        } catch (err) {
+          // The file wants to rewrite a body that is confirmed history. Keep the
+          // live text, keep the store usable, and report the conflict.
+          if (err?.code === "REVISION_PROTECTED") {
+            conflicts.push({ code: "chain-body", uri });
+            idByUri.set(uri, dest);
+          } else {
+            throw err;
+          }
+        }
       } else {
         idByUri.set(uri, store.insertNode(db, payload));
       }
     }
     const wantEdges = new Set();
+    const wantRevision = new Set();
+    const revisionOps = [];
     for (const e of parsed.edges) {
       const from = idByUri.get(e.from) ?? store.findByUri(db, e.from);
       const to = idByUri.get(e.to) ?? store.findByUri(db, e.to);
-      if (from == null || to == null || from === to) continue;
+      const revision = REVISION_EDGES.includes(e.type);
+      if (revision) wantRevision.add(`${e.from}\0${e.to}\0${e.type}`);
+      if (from == null || to == null || from === to) {
+        if (revision) conflicts.push({ code: "unmapped-relation", from: e.from, to: e.to });
+        continue;
+      }
+      if (revision) {
+        revisionOps.push({
+          type: "upsertEdge",
+          src: from,
+          dst: to,
+          label: e.type,
+          weight: weightOf(e.type),
+          metadata: e.meta || { at: nowIso(), reason: "", source: "sidecar" },
+        });
+        continue;
+      }
       store.ensureLink(db, from, to, e.type);
       wantEdges.add(`${e.from}\0${e.to}\0${e.type}`);
     }
+    if (revisionOps.length) {
+      try {
+        db.commitTransaction(revisionOps);
+      } catch (err) {
+        conflicts.push({ code: "relation-transaction-failed", message: String(err.message || err) });
+      }
+    }
     const uriById = new Map();
     for (const id of db.allNodeIds?.() || []) {
       const payload = payloadOf(db, id);
@@ -375,6 +457,22 @@ async function applySidecar(db, parsed) {
         }
       }
     }
+    /*
+     * A relation that exists locally but is absent from the file is NOT removed.
+     * Deleting a chain from a pull is a semantic change a snapshot cannot prove,
+     * so it is reported as a conflict and the user revokes it explicitly.
+     */
+    for (const id of db.allNodeIds?.() || []) {
+      const node = db.get(Number(id));
+      const fromUri = uriById.get(Number(id));
+      for (const edge of node?.edges || []) {
+        if (!REVISION_EDGES.includes(String(edge.label))) continue;
+        const toUri = uriById.get(edgeTarget(edge));
+        if (!fromUri || !toUri) continue;
+        if (wantRevision.has(`${fromUri}\0${toUri}\0${edge.label}`)) continue;
+        conflicts.push({ code: "relation-missing-in-file", from: fromUri, to: toUri });
+      }
+    }
     for (const id of db.allNodeIds?.() || []) {
       const payload = payloadOf(db, id);
       if (!isBusinessType(payload.type) || payload.status === "archived") continue;
@@ -382,6 +480,7 @@ async function applySidecar(db, parsed) {
       if (!uri || !uriSet.has(uri)) store.archiveNode(db, id);
     }
   });
+  return { conflicts };
 }
 
 /**
@@ -401,7 +500,15 @@ export async function syncSidecarOnOpen(cwd, db) {
   if (fileHash === knownHash(key)) return { action: "skip" };
   const parsed = parseSidecar(text);
   if (!parsed.ok) return { action: "skip-invalid", message: parsed.message };
-  await applySidecar(db, parsed);
+  const applied = await applySidecar(db, parsed);
   rememberHash(key, fileHash);
-  return { action: "import", hash: fileHash, nodes: parsed.nodes.length, edges: parsed.edges.length };
+  return {
+    action: "import",
+    hash: fileHash,
+    nodes: parsed.nodes.length,
+    edges: parsed.edges.length,
+    version: Number(parsed.header?.v) || 1,
+    // Conflicts are visible; the store stays usable and nothing is half-applied.
+    conflicts: applied?.conflicts || [],
+  };
 }