clay-server 4.0.0-beta.8 → 4.0.0

package/lib/project-logs-service.js

@@ -0,0 +1,463 @@
+// Authorization and binding layer for Project Logs.
+//
+// Modeled on workspace-query-service.js: a caller never states who it is.
+// Every binder re-derives the principal from authoritative server state and
+// returns null when anything fails to line up, so an unbound or stale caller
+// gets no capability rather than a degraded one.
+//
+// Product rules enforced here:
+//   - Project Logs are project records. Mate projects have none.
+//   - Ordinary Mates cannot reach project Logs at all.
+//   - Authoritative builtin Clay may read Logs, and only for projects the
+//     owning user is authorized to see. It may never write.
+//   - A project session is bound to exactly its own project's Logs.
+//   - Canonical authorship belongs to Project Driver sessions alone. A human,
+//     however privileged, may read and comment but may never create or revise
+//     a canonical entry. The project owner may delete an entry.
+//   - Members of a shared project read each other's entries and comments with
+//     attribution.
+//   - A worktree resolves to its parent project for both authorization and
+//     storage, so worktree work never forks project knowledge.
+
+var builtinMates = require("./builtin-mates");
+var logsStore = require("./project-logs-store");
+var LOG_REF_PATTERN = /^log:[A-Za-z0-9_-]{24}$/;
+
+function readOnly() {
+  throw new Error("Project Logs are read-only for builtin Clay.");
+}
+
+// Canonical entries are written by the project's own agent sessions. A human
+// participates by commenting, which is a separate, append-only surface.
+function agentOnly() {
+  throw new Error("Project Logs are written by this project's agent sessions. Add a comment instead.");
+}
+
+// Reviewing feedback and moving the record between revisions are the Driver's
+// judgement calls. A human cannot review their own comment into the record,
+// and Clay cannot review another project's.
+function driverOnly() {
+  throw new Error("Only this project's agent sessions can review feedback or change revisions.");
+}
+
+function ownerOnly() {
+  throw new Error("Only the project owner can delete Project Logs.");
+}
+
+// Bounded discovery of comments still waiting on the Driver. The store owns the
+// one-pass scan over every live entry, so nothing here imposes a ceiling that
+// could hide a pending comment on an older record.
+function attachProjectLogsService(ctx) {
+  var context = ctx || {};
+  var getProjects = context.getProjects;
+  var isMultiUser = context.isMultiUser;
+  var resolveMate = context.resolveMate;
+  var canAccessProject = context.canAccessProject;
+  var findUserById = context.findUserById || function () { return null; };
+  var storeCache = new Map();
+
+  var openStore = context.openStore || function (cwd, storeOptions) {
+    var options = storeOptions || {};
+    var key = options.projectKnowledgeId || cwd;
+    if (!storeCache.has(key)) {
+      storeCache.set(key, logsStore.createProjectLogsStore({
+        cwd: cwd,
+        baseDir: context.baseDir,
+        projectKnowledgeId: options.projectKnowledgeId || null,
+      }));
+    }
+    return storeCache.get(key);
+  };
+
+  function projectFor(slug) {
+    if (!slug || typeof slug !== "string") return null;
+    var projects = getProjects();
+    return (projects && projects.get(slug)) || null;
+  }
+
+  // A worktree inherits its parent's visibility, so authorization is decided
+  // against the parent whenever the parent is registered.
+  function effectiveStatus(status) {
+    if (!status || status.isWorktree !== true || !status.parentSlug) return status;
+    var parent = projectFor(status.parentSlug);
+    if (!parent) return status;
+    var parentStatus = parent.getStatus();
+    return parentStatus || status;
+  }
+
+  function ownsProject(principal, status) {
+    if (!status) return false;
+    if (isMultiUser()) return !!principal.userId && status.projectOwnerId === principal.userId;
+    return !status.projectOwnerId || (!!principal.singleUserOwnerId && status.projectOwnerId === principal.singleUserOwnerId);
+  }
+
+  function authorizedProject(principal, status) {
+    if (!status) return false;
+    if (status.isMate === true) return false;
+    var governing = effectiveStatus(status);
+    if (ownsProject(principal, governing)) return true;
+    if (isMultiUser() && principal.userId && typeof canAccessProject === "function") {
+      return canAccessProject(principal.userId, governing) === true;
+    }
+    return false;
+  }
+
+  // Open the store for the governing project. When a worktree's parent is
+  // registered, its path is authoritative, so worktree Logs are shared without
+  // depending on a Git subprocess. The store's own root resolution remains the
+  // fallback for unregistered parents and for subdirectories of a checkout.
+  function storeForStatus(status) {
+    var governing = effectiveStatus(status);
+    if (!governing || !governing.path) throw new Error("Project Logs are unavailable for this project.");
+    return openStore(governing.path, { projectKnowledgeId: governing.projectKnowledgeId || null });
+  }
+
+  function recordContext(status) {
+    if (!status || status.isWorktree !== true || !status.changeSetId) return null;
+    return {
+      kind: "worktree",
+      changeSetId: status.changeSetId,
+      branch: status.branch || null,
+      baseCommit: status.baseCommit || null,
+      headCommit: status.headCommit || null,
+      status: "active",
+    };
+  }
+
+  function scopedArgs(args, status) {
+    var out = Object.assign({}, args || {});
+    if (!out.contextMode) out.contextMode = status && status.isWorktree ? "current" : "project";
+    out.currentChangeSetId = status && status.changeSetId || null;
+    return out;
+  }
+
+  function statusFor(principal, slug) {
+    var project = projectFor(slug);
+    if (!project) throw new Error("Project not found.");
+    var status = project.getStatus();
+    if (!authorizedProject(principal, status)) throw new Error("Project Logs are not available for this project.");
+    return status;
+  }
+
+  function displayNameFor(userId) {
+    if (!userId) return null;
+    var user = findUserById(userId);
+    if (!user) return null;
+    return user.displayName || user.username || null;
+  }
+
+  function sessionAuthor(session) {
+    return {
+      type: "session",
+      userId: session.ownerId || null,
+      displayName: displayNameFor(session.ownerId),
+      sessionKey: session.cliSessionId || "local:" + session.localId,
+      vendor: session.vendor || null,
+    };
+  }
+
+  function userAuthor(user) {
+    return {
+      type: "user",
+      userId: (user && user.id) || null,
+      displayName: (user && (user.displayName || user.username)) || null,
+      sessionKey: null,
+      vendor: null,
+    };
+  }
+
+  // --- Binders ---------------------------------------------------------
+
+  // Exact session object identity, not a caller-supplied session id. A session
+  // handed in from a stale or forged reference is rejected even when its
+  // localId matches a live session.
+  function resolveProjectSession(source) {
+    if (!source || !source.projectSlug || !source.session) return null;
+    var project = projectFor(source.projectSlug);
+    if (!project) return null;
+    var status = project.getStatus();
+    if (!status || status.isMate === true) return null;
+    var manager = project.getSessionManager ? project.getSessionManager() : project.sm;
+    if (!manager || !manager.sessions || manager.sessions.get(source.session.localId) !== source.session) return null;
+
+    var principal;
+    if (isMultiUser()) {
+      // Fail closed: an unattributed session in multi-user mode gets nothing.
+      if (!source.session.ownerId) return null;
+      principal = { userId: source.session.ownerId, singleUserOwnerId: null };
+    } else {
+      if (source.session.ownerId && status.projectOwnerId && source.session.ownerId !== status.projectOwnerId) return null;
+      principal = { userId: null, singleUserOwnerId: source.session.ownerId || status.projectOwnerId || null };
+    }
+    if (!authorizedProject(principal, status)) return null;
+
+    principal.kind = "session";
+    principal.projectSlug = source.projectSlug;
+    principal.isClay = false;
+    return { principal: principal, status: status, author: sessionAuthor(source.session) };
+  }
+
+  // A tool handler captured earlier stays valid only while its exact source
+  // still resolves. Session identity and project authorization are both
+  // re-derived on every call, so a session dropped from the manager, or
+  // replaced by a different object with the same id, loses the capability
+  // immediately rather than continuing to work through a captured handler.
+  function bindProjectSession(source) {
+    var initial = resolveProjectSession(source);
+    if (!initial) return null;
+    function revalidate() {
+      var current = resolveProjectSession(source);
+      if (!current || current.principal.projectSlug !== initial.principal.projectSlug) {
+        throw new Error("This Project Logs binding is no longer valid for the current session.");
+      }
+      return current;
+    }
+    return createProjectBound(initial, revalidate);
+  }
+
+  function bindUser(source) {
+    if (!source || !source.projectSlug) return null;
+    var project = projectFor(source.projectSlug);
+    if (!project) return null;
+    var status = project.getStatus();
+    if (!status || status.isMate === true) return null;
+    var user = source.user || null;
+
+    var principal;
+    if (isMultiUser()) {
+      if (!user || !user.id) return null;
+      principal = { userId: user.id, singleUserOwnerId: null };
+    } else {
+      principal = { userId: null, singleUserOwnerId: (user && user.id) || status.projectOwnerId || null };
+    }
+    if (!authorizedProject(principal, status)) return null;
+
+    principal.kind = "user";
+    principal.projectSlug = source.projectSlug;
+    principal.isClay = false;
+    principal.isProjectOwner = ownsProject(principal, status);
+    var envelope = { principal: principal, status: status, author: userAuthor(user) };
+    return createProjectBound(envelope, function () { return envelope; });
+  }
+
+  // Ordinary Mates get null. Only the authoritative builtin Clay host agent,
+  // confirmed against the server Mate registry rather than a project flag,
+  // receives a read-only cross-project binding.
+  function resolveMateSource(source) {
+    if (!source || source.isMate !== true || !source.mateId || typeof resolveMate !== "function") return null;
+    var sourceProject = projectFor(source.projectSlug);
+    if (!sourceProject) return null;
+    var sourceStatus = sourceProject.getStatus();
+    if (!sourceStatus || sourceStatus.isMate !== true) return null;
+    if (sourceStatus.mateId !== source.mateId || sourceStatus.projectOwnerId !== source.projectOwnerId) return null;
+    if (source.session) {
+      var manager = sourceProject.getSessionManager ? sourceProject.getSessionManager() : sourceProject.sm;
+      if (!manager || !manager.sessions || manager.sessions.get(source.session.localId) !== source.session) return null;
+    }
+    var mate = resolveMate(source.projectOwnerId || null, source.mateId);
+    if (!mate || mate.id !== source.mateId) return null;
+    if (isMultiUser() && (!source.projectOwnerId || mate.createdBy !== source.projectOwnerId)) return null;
+
+    var def = mate.builtinKey ? builtinMates.getBuiltinByKey(mate.builtinKey) : null;
+    var isClay = !!(mate.builtinKey === "clay" && def && def.hostAgent === true);
+    if (!isClay) return null;
+    if (isMultiUser() && !source.projectOwnerId) return null;
+
+    return {
+      kind: "clay",
+      userId: isMultiUser() ? source.projectOwnerId : null,
+      singleUserOwnerId: isMultiUser() ? null : (source.projectOwnerId || null),
+      projectSlug: null,
+      mateId: mate.id,
+      isClay: true,
+    };
+  }
+
+  // Clay keeps its authoritative registry and user authorization checks on
+  // every call, so a Mate that is deleted, demoted out of builtin Clay, or
+  // reassigned to another user loses the read view immediately.
+  function bindMate(source) {
+    var initial = resolveMateSource(source);
+    if (!initial) return null;
+    function revalidate() {
+      var current = resolveMateSource(source);
+      if (!current || current.mateId !== initial.mateId || current.userId !== initial.userId) {
+        throw new Error("This Project Logs binding is no longer valid for the current session.");
+      }
+      return current;
+    }
+    return createClayBound(revalidate);
+  }
+
+  // --- Bound capability surfaces ---------------------------------------
+
+  function createProjectBound(initial, revalidate) {
+    var store = storeForStatus(initial.status);
+
+    // Identity, authorization, and the target store are all re-derived per
+    // call. revalidate() re-checks exact session identity where there is one;
+    // the project authorization check then catches a visibility change.
+    function live() {
+      var current = revalidate();
+      var project = projectFor(current.principal.projectSlug);
+      if (!project) throw new Error("Project not found.");
+      var currentStatus = project.getStatus();
+      if (!authorizedProject(current.principal, currentStatus)) throw new Error("Project Logs are not available for this project.");
+      return storeForStatus(currentStatus);
+    }
+
+    function author() {
+      return revalidate().author;
+    }
+
+    function currentStatus() {
+      var current = revalidate();
+      var project = projectFor(current.principal.projectSlug);
+      if (!project) throw new Error("Project not found.");
+      return project.getStatus();
+    }
+
+    function mutationContext() {
+      return recordContext(currentStatus());
+    }
+
+    // A session may write canonically; a user may only comment. The capability
+    // is decided by the binder that produced this envelope, never by a flag on
+    // the request.
+    var canonical = initial.principal.kind === "session";
+    var canDelete = canonical || initial.principal.isProjectOwner === true;
+    return {
+      isClay: false,
+      canWrite: canonical,
+      canComment: true,
+      canDelete: canDelete,
+      projectSlug: initial.principal.projectSlug,
+      scopeId: store.scopeId,
+      root: store.root,
+      author: initial.author,
+      listLogs: function (args) {
+        var status = currentStatus();
+        var options = scopedArgs(args, status);
+        var result = live().list(options);
+        result.contextMode = options.contextMode;
+        result.currentChangeSetId = status.changeSetId || null;
+        result.isWorktree = status.isWorktree === true;
+        return result;
+      },
+      searchLogs: function (args) {
+        var status = currentStatus();
+        var options = scopedArgs(args, status);
+        var result = live().search(options);
+        result.contextMode = options.contextMode;
+        result.currentChangeSetId = status.changeSetId || null;
+        result.isWorktree = status.isWorktree === true;
+        return result;
+      },
+      readLog: function (args) {
+        var entry = live().read(args && args.ref, false);
+        if (!entry) throw new Error("Log entry not found.");
+        return entry;
+      },
+      logHistory: function (args) { return live().history(args && args.ref, args || {}); },
+      commentLog: function (args) { return live().comment(args && args.ref, args || {}, author(), mutationContext()); },
+      readLogRevision: function (args) { return live().readRevision(args && args.ref, args && args.revision); },
+      listLogFeedback: canonical ? function (args) { return live().feedback(args || {}); } : driverOnly,
+      reviewLogComment: canonical ? function (args) { return live().review(args && args.ref, args || {}, author(), mutationContext()); } : driverOnly,
+      revertLog: canonical
+        ? function (args) { return live().revert(args && args.ref, args && args.revision, args && args.reason, author(), mutationContext()); }
+        : driverOnly,
+      createLog: canonical ? function (args) { return live().create(args || {}, author(), mutationContext()); } : agentOnly,
+      updateLog: canonical ? function (args) { return live().update(args && args.ref, args || {}, author(), mutationContext()); } : agentOnly,
+      linkLog: canonical ? function (args) { return live().link(args && args.ref, args && args.links, author(), mutationContext()); } : agentOnly,
+      removeLog: canDelete ? function (args) {
+        var current = revalidate();
+        var project = projectFor(current.principal.projectSlug);
+        var currentStatus = project && project.getStatus();
+        if (!project || !authorizedProject(current.principal, currentStatus)) {
+          throw new Error("Project Logs are not available for this project.");
+        }
+        if (current.principal.kind !== "session" && !ownsProject(current.principal, currentStatus)) ownerOnly();
+        return storeForStatus(currentStatus).remove(args && args.ref, current.author, recordContext(currentStatus));
+      } : ownerOnly,
+    };
+  }
+
+  function setContextState(projectSlug, status) {
+    var project = projectFor(projectSlug);
+    var projectStatus = project && project.getStatus();
+    if (!projectStatus || !projectStatus.isWorktree || !projectStatus.changeSetId) return false;
+    return storeForStatus(projectStatus).setContextState(recordContext(projectStatus), status);
+  }
+
+  function createClayBound(revalidate) {
+    function target(args) {
+      var principal = revalidate();
+      var slug = args && args.projectSlug;
+      if (!slug) throw new Error("An exact project slug is required.");
+      return storeForStatus(statusFor(principal, slug));
+    }
+
+    function resolveLogNavigation(args) {
+      var principal = revalidate();
+      var ref = args && args.ref;
+      if (!LOG_REF_PATTERN.test(ref || "")) throw new Error("Invalid log reference.");
+      var projects = getProjects();
+      var seenScopes = new Set();
+      var match = null;
+      if (!projects || typeof projects.forEach !== "function") throw new Error("Project Logs are unavailable.");
+      projects.forEach(function (project, slug) {
+        if (!project || typeof project.getStatus !== "function") return;
+        var status = project.getStatus();
+        if (!authorizedProject(principal, status)) return;
+        var governing = effectiveStatus(status);
+        var scope = governing && (governing.projectKnowledgeId || governing.path);
+        if (!scope || seenScopes.has(scope)) return;
+        seenScopes.add(scope);
+        var entry = null;
+        try { entry = storeForStatus(status).read(ref, false); } catch (e) { return; }
+        if (!entry) return;
+        var targetSlug = status.isWorktree && status.parentSlug && projectFor(status.parentSlug) ? status.parentSlug : slug;
+        if (match && match.projectSlug !== targetSlug) throw new Error("Log reference is ambiguous.");
+        match = { projectSlug: targetSlug, ref: ref };
+      });
+      if (!match) throw new Error("Log entry not found.");
+      return match;
+    }
+
+    return {
+      isClay: true,
+      canWrite: false,
+      canComment: false,
+      canDelete: false,
+      projectSlug: null,
+      author: null,
+      listLogs: function (args) { return target(args).list(args || {}); },
+      searchLogs: function (args) { return target(args).search(args || {}); },
+      readLog: function (args) {
+        var entry = target(args).read(args && args.ref, false);
+        if (!entry) throw new Error("Log entry not found.");
+        return entry;
+      },
+      logHistory: function (args) { return target(args).history(args && args.ref, args || {}); },
+      commentLog: readOnly,
+      readLogRevision: function (args) { return target(args).readRevision(args && args.ref, args && args.revision); },
+      resolveLogNavigation: resolveLogNavigation,
+      listLogFeedback: readOnly,
+      reviewLogComment: readOnly,
+      revertLog: readOnly,
+      createLog: readOnly,
+      updateLog: readOnly,
+      linkLog: readOnly,
+      removeLog: readOnly,
+    };
+  }
+
+  return {
+    bindProjectSession: bindProjectSession,
+    bindUser: bindUser,
+    bindMate: bindMate,
+    setContextState: setContextState,
+  };
+}
+
+module.exports = { attachProjectLogsService: attachProjectLogsService };

package/lib/project-logs-snapshot.js

@@ -0,0 +1,205 @@
+// Canonical snapshots and revision reconstruction for Project Logs.
+//
+// Split from project-logs-store.js so the store stays inside the module size
+// limit and so version control has one place to live.
+//
+// Every NEW canonical edit stores a complete immutable snapshot of the record:
+// category, priority, title, summary, body, tags, links. That makes a revision
+// self-contained, so reading revision N never depends on replaying everything
+// before it.
+//
+// Records written before snapshots existed carry only the fields that changed.
+// They are never rewritten. Instead, reconstruction folds forward: a record
+// with a `snapshot` replaces the state outright, and a legacy partial record
+// applies its deltas onto the state built so far. Both paths produce the same
+// shape, so history is deterministic across the boundary.
+
+var logsSchema = require("./project-logs-schema");
+var logContext = require("./project-log-context");
+
+// Ops that advance the canonical record. `comment` and a non-incorporating
+// `review` are participation, not revisions, and never appear here.
+var CANONICAL_OPS = ["create", "update", "link", "revert"];
+
+var SNAPSHOT_FIELDS = ["category", "priority", "title", "summary", "body", "tags", "links"];
+
+function emptySnapshot() {
+  return {
+    category: "",
+    priority: logsSchema.DEFAULT_PRIORITY,
+    title: "",
+    summary: "",
+    body: "",
+    tags: [],
+    links: [],
+  };
+}
+
+function cloneSnapshot(snapshot) {
+  var source = snapshot || {};
+  return {
+    category: source.category || "",
+    priority: logsSchema.normalizePriority(source.priority),
+    title: typeof source.title === "string" ? source.title : "",
+    summary: typeof source.summary === "string" ? source.summary : "",
+    body: typeof source.body === "string" ? source.body : "",
+    tags: Array.isArray(source.tags) ? source.tags.slice() : [],
+    links: Array.isArray(source.links) ? source.links.slice() : [],
+  };
+}
+
+// True when this record carries a complete canonical snapshot.
+function hasSnapshot(record) {
+  return !!(record && record.snapshot && typeof record.snapshot === "object");
+}
+
+// A canonical op, including an incorporating review. A review that clarifies or
+// declines resolves a comment without changing the record.
+function isCanonical(record) {
+  if (!record) return false;
+  if (record.op === "review") return record.action === "incorporate";
+  return CANONICAL_OPS.indexOf(record.op) !== -1;
+}
+
+// Apply a legacy partial record onto the running state. Only used for records
+// written before snapshots; a snapshot-bearing record never takes this path.
+function applyPartial(state, record, maxLinks) {
+  var next = cloneSnapshot(state);
+  if (record.op === "create") {
+    next.category = record.kind || "";
+    next.priority = logsSchema.normalizePriority(record.priority);
+    next.title = typeof record.title === "string" ? record.title : "";
+    next.summary = typeof record.summary === "string" ? record.summary : "";
+    next.body = typeof record.body === "string" ? record.body : "";
+    next.tags = Array.isArray(record.tags) ? record.tags.slice() : [];
+    next.links = Array.isArray(record.links) ? record.links.slice() : [];
+    return next;
+  }
+  if (record.op === "link") {
+    var added = Array.isArray(record.links) ? record.links : [];
+    for (var i = 0; i < added.length && next.links.length < maxLinks; i++) {
+      var exists = false;
+      for (var j = 0; j < next.links.length; j++) {
+        if (next.links[j].ref === added[i].ref) { exists = true; break; }
+      }
+      if (!exists) next.links.push(added[i]);
+    }
+    return next;
+  }
+  if (record.kind) next.category = record.kind;
+  if (record.priority) next.priority = logsSchema.normalizePriority(record.priority);
+  if (typeof record.title === "string") next.title = record.title;
+  if (typeof record.summary === "string") next.summary = record.summary;
+  if (typeof record.body === "string") next.body = record.body;
+  if (Array.isArray(record.tags)) next.tags = record.tags.slice();
+  if (Array.isArray(record.links)) next.links = record.links.slice();
+  return next;
+}
+
+function sameSnapshot(a, b) {
+  var left = cloneSnapshot(a);
+  var right = cloneSnapshot(b);
+  for (var i = 0; i < SNAPSHOT_FIELDS.length; i++) {
+    var field = SNAPSHOT_FIELDS[i];
+    if (JSON.stringify(left[field]) !== JSON.stringify(right[field])) return false;
+  }
+  return true;
+}
+
+function changedFields(previous, next) {
+  var changed = [];
+  if (!previous) return SNAPSHOT_FIELDS.slice();
+  for (var i = 0; i < SNAPSHOT_FIELDS.length; i++) {
+    var field = SNAPSHOT_FIELDS[i];
+    if (JSON.stringify(previous[field]) !== JSON.stringify(next[field])) changed.push(field);
+  }
+  return changed;
+}
+
+// Every canonical revision of one entry, in causal order, each with the exact
+// snapshot as of that revision. Deleting is a tombstone rather than a
+// revision, so it is reported separately.
+function revisions(chain, maxLinks) {
+  var out = [];
+  var state = emptySnapshot();
+  var deleted = null;
+  var started = false;
+
+  for (var i = 0; i < chain.length; i++) {
+    var record = chain[i];
+    if (record.op === "delete") {
+      if (started && !deleted) deleted = { at: record.at || 0, author: record.author || null };
+      continue;
+    }
+    if (deleted) continue;
+    if (!isCanonical(record)) continue;
+    if (record.op === "create") {
+      if (started) continue;
+      started = true;
+    } else if (!started) {
+      continue;
+    }
+
+    var previous = out.length ? out[out.length - 1].snapshot : null;
+    state = hasSnapshot(record) ? cloneSnapshot(record.snapshot) : applyPartial(state, record, maxLinks);
+    out.push({
+      revision: out.length + 1,
+      op: record.op === "review" ? "incorporate" : record.op,
+      at: record.at || 0,
+      author: record.author || null,
+      context: record.context || null,
+      snapshot: state,
+      changed: record.op === "create" ? [] : changedFields(previous, state),
+      // Present only on a revert, so a reader can see where it came from.
+      revertedFrom: record.revertedFrom || null,
+      reason: typeof record.reason === "string" ? record.reason : null,
+      // Present only on an incorporation, linking the revision to the comment
+      // that prompted it.
+      commentId: record.op === "review" ? (record.commentId || null) : null,
+      // Whether this revision was reconstructed from a legacy partial record.
+      reconstructed: !hasSnapshot(record),
+      // The record that produced this revision. Internal: it exists so a
+      // review can be linked to its exact revision by identity rather than by
+      // matching timestamps, and describeRevision deliberately drops it so no
+      // internal record id reaches a public response.
+      sourceRecordId: record.id,
+    });
+  }
+  return { revisions: out, deleted: deleted, started: started };
+}
+
+// Revision metadata without any body, for history listings and for the bounded
+// timeline the detail view shows. `sourceRecordId` is intentionally not copied:
+// the only identifiers a caller ever sees are the opaque entry ref and comment
+// id.
+function describeRevision(entry) {
+  return {
+    revision: entry.revision,
+    op: entry.op,
+    at: entry.at,
+    author: entry.author,
+    context: logContext.normalizeRecordContext(entry.context),
+    changed: entry.changed,
+    revertedFrom: entry.revertedFrom,
+    reason: entry.reason,
+    commentId: entry.commentId,
+    reconstructed: entry.reconstructed,
+    title: entry.snapshot.title,
+    category: entry.snapshot.category,
+    priority: entry.snapshot.priority,
+  };
+}
+
+module.exports = {
+  CANONICAL_OPS: CANONICAL_OPS,
+  SNAPSHOT_FIELDS: SNAPSHOT_FIELDS,
+  emptySnapshot: emptySnapshot,
+  cloneSnapshot: cloneSnapshot,
+  hasSnapshot: hasSnapshot,
+  isCanonical: isCanonical,
+  applyPartial: applyPartial,
+  sameSnapshot: sameSnapshot,
+  changedFields: changedFields,
+  revisions: revisions,
+  describeRevision: describeRevision,
+};