clay-server 4.0.0-beta.16 → 4.0.0-beta.18

package/lib/project-logs-query.js

@@ -62,6 +62,19 @@ function page(items, args) {
   };
 }
 
+function contextMode(options) {
+  var value = options && options.contextMode;
+  return value === "all" || value === "current" || value === "project" ? value : "all";
+}
+
+function matchesContext(entry, options) {
+  var mode = contextMode(options);
+  var changeSetId = entry && entry.context && entry.context.changeSetId;
+  if (mode === "all") return true;
+  if (mode === "project") return !changeSetId;
+  return !changeSetId || changeSetId === options.currentChangeSetId;
+}
+
 function listEntries(entries, args, cleanLine, validateKind) {
   var options = args || {};
   var kind = options.kind ? validateKind(options.kind, null) : null;
@@ -73,6 +86,7 @@ function listEntries(entries, args, cleanLine, validateKind) {
     if (kind && entry.category !== kind) return false;
     if (priority && entry.priority !== priority) return false;
     if (tag && entry.tags.indexOf(tag) === -1) return false;
+    if (!matchesContext(entry, options)) return false;
     return true;
   });
   var result = page(filtered, options);
@@ -116,6 +130,7 @@ function summarize(entry) {
     // How many comments still await Driver review. A count only: the ledger
     // never carries comment bodies.
     pendingFeedbackCount: entry.pendingFeedbackCount || 0,
+    context: entry.context || null,
   };
 }
 
@@ -128,6 +143,7 @@ function searchEntries(entries, args, cleanLine, validateKind) {
   var candidates = entries.filter(function (entry) {
     if (kind && entry.category !== kind) return false;
     if (priority && entry.priority !== priority) return false;
+    if (!matchesContext(entry, options)) return false;
     return true;
   });
 
@@ -161,6 +177,8 @@ module.exports = {
   encodeCursor: encodeCursor,
   decodeCursor: decodeCursor,
   page: page,
+  contextMode: contextMode,
+  matchesContext: matchesContext,
   summarize: summarize,
   listEntries: listEntries,
   searchEntries: searchEntries,

package/lib/project-logs-root.js

@@ -60,8 +60,16 @@ function scopeIdForRoot(root) {
   return "project/" + utils.encodeCwd(root);
 }
 
+function scopeIdForKnowledgeId(knowledgeId) {
+  if (typeof knowledgeId !== "string" || !/^[A-Za-z0-9_-]{1,120}$/.test(knowledgeId)) {
+    throw new Error("Invalid project knowledge id.");
+  }
+  return "project/" + knowledgeId;
+}
+
 module.exports = {
   resolveProjectRoot: resolveProjectRoot,
   scopeIdForRoot: scopeIdForRoot,
+  scopeIdForKnowledgeId: scopeIdForKnowledgeId,
   canonicalPath: canonicalPath,
 };

package/lib/project-logs-service.js

@@ -13,7 +13,7 @@
 //   - 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 log is the agent's record of the work.
+//     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
@@ -21,6 +21,7 @@
 
 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.");
@@ -39,6 +40,10 @@ 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.
@@ -51,11 +56,17 @@ function attachProjectLogsService(ctx) {
   var findUserById = context.findUserById || function () { return null; };
   var storeCache = new Map();
 
-  var openStore = context.openStore || function (cwd) {
-    if (!storeCache.has(cwd)) {
-      storeCache.set(cwd, logsStore.createProjectLogsStore({ cwd: cwd, baseDir: context.baseDir }));
+  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(cwd);
+    return storeCache.get(key);
   };
 
   function projectFor(slug) {
@@ -98,7 +109,26 @@ function attachProjectLogsService(ctx) {
   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);
+    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) {
@@ -205,6 +235,7 @@ function attachProjectLogsService(ctx) {
     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; });
   }
@@ -279,40 +310,85 @@ function attachProjectLogsService(ctx) {
       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) { return live().list(args || {}); },
-      searchLogs: function (args) { return live().search(args || {}); },
+      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()); },
+      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()); } : 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()); }
+        ? 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()); } : agentOnly,
-      updateLog: canonical ? function (args) { return live().update(args && args.ref, args || {}, author()); } : agentOnly,
-      linkLog: canonical ? function (args) { return live().link(args && args.ref, args && args.links, author()); } : agentOnly,
-      removeLog: canonical ? function (args) { return live().remove(args && args.ref, author()); } : agentOnly,
+      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();
@@ -321,10 +397,38 @@ function attachProjectLogsService(ctx) {
       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 || {}); },
@@ -337,6 +441,7 @@ function attachProjectLogsService(ctx) {
       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,
@@ -351,6 +456,7 @@ function attachProjectLogsService(ctx) {
     bindProjectSession: bindProjectSession,
     bindUser: bindUser,
     bindMate: bindMate,
+    setContextState: setContextState,
   };
 }
 

package/lib/project-logs-snapshot.js

@@ -15,6 +15,7 @@
 // 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.
@@ -146,6 +147,7 @@ function revisions(chain, maxLinks) {
       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.
@@ -176,6 +178,7 @@ function describeRevision(entry) {
     op: entry.op,
     at: entry.at,
     author: entry.author,
+    context: logContext.normalizeRecordContext(entry.context),
     changed: entry.changed,
     revertedFrom: entry.revertedFrom,
     reason: entry.reason,

package/lib/project-logs-store.js

@@ -1,13 +1,4 @@
 // Project Logs projection over the Clay-wide knowledge record backend.
-//
-// Project Logs are dry, factual project records: decisions, investigations,
-// session notes, runbooks, references, incidents, and progress. They carry no
-// persona and no autobiographical memory; that separation is a product rule,
-// not a storage detail, so nothing here writes identity-shaped content.
-//
-// A worktree shares its parent project's Logs. The store root is resolved
-// through Git's common directory, so a worktree session and a parent session
-// read and write the same record file instead of forking project knowledge.
 
 var fs = require("fs");
 var path = require("path");
@@ -19,6 +10,8 @@ var logsSnapshot = require("./project-logs-snapshot");
 var logsComments = require("./project-logs-comments");
 var logsVersioning = require("./project-logs-versioning");
 var logsRoot = require("./project-logs-root");
+var logContext = require("./project-log-context");
+var contextState = require("./project-logs-context-state");
 
 var MAX_SUMMARY_CHARS = logsSchema.MAX_SUMMARY_CHARS;
 var MAX_COMMENT_CHARS = 4000;
@@ -56,18 +49,17 @@ function validateKind(kind, fallback) {
 function createProjectLogsStore(opts) {
   var options = opts || {};
   var root = options.root ? path.resolve(options.root) : logsRoot.resolveProjectRoot(options.cwd, options.runGit);
-  var scopeId = logsRoot.scopeIdForRoot(root);
+  var scopeId = options.projectKnowledgeId
+    ? logsRoot.scopeIdForKnowledgeId(options.projectKnowledgeId)
+    : logsRoot.scopeIdForRoot(root);
   var store = recordStore.createRecordStore({ scopeId: scopeId, baseDir: options.baseDir });
+  var contexts = contextState.attachContextState(store, scopeId);
 
-  // Stable across every revision of an entry: derived from the scope and the
-  // chain root, never from a path or an internal record id.
   function refFor(rootId) {
     var digest = crypto.createHash("sha256").update(scopeId + "\u0000" + String(rootId)).digest("base64url");
     return "log:" + digest.substring(0, 24);
   }
 
-  // File order is causal order. Wall-clock timestamps are recorded but never
-  // used to order a chain, so a skewed clock cannot reorder a revision.
   function chains() {
     var records = store.all();
     var byRoot = new Map();
@@ -80,24 +72,19 @@ function createProjectLogsStore(opts) {
     return byRoot;
   }
 
-  // The canonical record is reconstructed from its revision chain, and the
-  // discussion is folded separately. Neither comments nor a clarify/decline
-  // review touch the canonical state or the revision count.
-  function fold(rootId, chain) {
+  function fold(rootId, chain, knownContextStates) {
     var history = logsSnapshot.revisions(chain, MAX_LINKS);
     if (!history.started || history.revisions.length === 0) return null;
     var last = history.revisions[history.revisions.length - 1];
     var first = history.revisions[0];
+    var originRecord = null;
+    for (var ci = 0; ci < chain.length; ci++) {
+      if (chain[ci].id === first.sourceRecordId) { originRecord = chain[ci]; break; }
+    }
 
-    // A create record that does not carry the minimum a log entry needs is not
-    // a log entry. Hand-edited files and torn writes that were later completed
-    // can look structurally valid without being usable.
     if (!logsSchema.safeCategory(first.snapshot.category)) return null;
     if (!first.snapshot.title || !first.snapshot.title.trim()) return null;
 
-    // Each reconstructed revision knows exactly which record produced it, so
-    // an incorporating review maps to its revision by identity. Two reviews
-    // sharing a millisecond cannot be confused for one another.
     var revisionForRecordId = {};
     for (var v = 0; v < history.revisions.length; v++) {
       var source = history.revisions[v].sourceRecordId;
@@ -128,7 +115,12 @@ function createProjectLogsStore(opts) {
       deleted: !!history.deleted,
       deletedAt: history.deleted ? history.deleted.at : null,
       deletedBy: history.deleted ? history.deleted.author : null,
+      context: logContext.normalizeRecordContext(originRecord && originRecord.context),
     };
+    if (entry.context.changeSetId) {
+      var states = knownContextStates || contexts.states();
+      entry.context.status = states[entry.context.changeSetId] || entry.context.status;
+    }
     // Entries written before summaries existed get a deterministic one derived
     // from their own body. Nothing on disk is rewritten.
     entry.summary = logsSchema.fallbackSummary(entry);
@@ -142,8 +134,9 @@ function createProjectLogsStore(opts) {
 
   function entries(includeDeleted) {
     var out = [];
+    var states = contexts.states();
     chains().forEach(function (chain, rootId) {
-      var entry = fold(rootId, chain);
+      var entry = fold(rootId, chain, states);
       if (!entry) return;
       if (entry.deleted && !includeDeleted) return;
       out.push(entry);
@@ -181,7 +174,7 @@ function createProjectLogsStore(opts) {
     return located;
   }
 
-  function create(input, author) {
+  function create(input, author, context) {
     var data = input || {};
     var validated = logsSchema.validateNewRecord(data);
     var title = cleanLine(data.title || "", MAX_TITLE_CHARS);
@@ -213,6 +206,7 @@ function createProjectLogsStore(opts) {
       links: snapshot.links,
       snapshot: snapshot,
       author: normalizeAuthor(author),
+      context: logContext.normalizeRecordContext(context),
       at: Date.now(),
     });
     return read(refFor(id), false);
@@ -243,7 +237,7 @@ function createProjectLogsStore(opts) {
     return logsSnapshot.cloneSnapshot(entry);
   }
 
-  function update(ref, changes, author) {
+  function update(ref, changes, author, context) {
     var located = requireLive(ref);
     var data = changes || {};
     var validated = logsSchema.validateRevision(data);
@@ -252,7 +246,7 @@ function createProjectLogsStore(opts) {
     if (logsSnapshot.sameSnapshot(current, snapshot)) {
       throw new Error("An update requires at least one changed field.");
     }
-    appendRevision(located.rootId, "update", snapshot, author, {});
+    appendRevision(located.rootId, "update", snapshot, author, { context: logContext.normalizeRecordContext(context) });
     return read(ref, false);
   }
 
@@ -284,7 +278,7 @@ function createProjectLogsStore(opts) {
   // Human participation. Append-only for this slice: no edit, no delete, and
   // never a canonical revision. The author is supplied by the authorization
   // layer, never by the caller's payload.
-  function comment(ref, input, author) {
+  function comment(ref, input, author, context) {
     var located = requireLive(ref);
     var data = input || {};
     var body = cleanText(data.body || "", MAX_COMMENT_CHARS);
@@ -300,12 +294,13 @@ function createProjectLogsStore(opts) {
       scope: scopeId,
       body: body,
       author: normalizeAuthor(author),
+      context: logContext.normalizeRecordContext(context),
       at: Date.now(),
     });
     return read(ref, false);
   }
 
-  function link(ref, links, author) {
+  function link(ref, links, author, context) {
     var located = requireLive(ref);
     var normalized = normalizeLinks(links);
     if (normalized.length === 0) throw new Error("At least one link reference is required.");
@@ -321,11 +316,11 @@ function createProjectLogsStore(opts) {
     if (logsSnapshot.sameSnapshot(current, snapshot)) {
       throw new Error("Those links are already attached to this entry.");
     }
-    appendRevision(located.rootId, "link", snapshot, author, {});
+    appendRevision(located.rootId, "link", snapshot, author, { context: logContext.normalizeRecordContext(context) });
     return read(ref, false);
   }
 
-  function remove(ref, author) {
+  function remove(ref, author, context) {
     var located = requireLive(ref);
     store.append({
       id: recordStore.newRecordId(),
@@ -333,6 +328,7 @@ function createProjectLogsStore(opts) {
       op: "delete",
       scope: scopeId,
       author: normalizeAuthor(author),
+      context: logContext.normalizeRecordContext(context),
       at: Date.now(),
     });
     return read(ref, true);
@@ -473,6 +469,7 @@ function createProjectLogsStore(opts) {
     readRevision: versioning.readRevision,
     link: link,
     remove: remove,
+    setContextState: contexts.set,
     read: read,
     list: list,
     search: search,

package/lib/project-logs-versioning.js

@@ -9,6 +9,7 @@ var logsSchema = require("./project-logs-schema");
 var logsSnapshot = require("./project-logs-snapshot");
 var logsComments = require("./project-logs-comments");
 var recordStore = require("./knowledge-record-store");
+var logContext = require("./project-log-context");
 
 function attachVersioning(ctx) {
   var read = ctx.read;
@@ -27,7 +28,7 @@ function attachVersioning(ctx) {
   // create no canonical revision. `incorporate` appends exactly one record that
   // both resolves the comment and carries the new canonical snapshot, so the
   // two can never drift apart.
-  function review(ref, input, author) {
+  function review(ref, input, author, context) {
     var located = requireLive(ref);
     var data = input || {};
     if (!logsComments.isAction(data.action)) {
@@ -56,6 +57,7 @@ function attachVersioning(ctx) {
         commentId: data.commentId,
         response: response,
         author: normalizeAuthor(author),
+        context: logContext.normalizeRecordContext(context),
         at: Date.now(),
       });
       return read(ref, false);
@@ -71,13 +73,14 @@ function attachVersioning(ctx) {
       action: "incorporate",
       commentId: data.commentId,
       response: response,
+      context: logContext.normalizeRecordContext(context),
     });
     return read(ref, false);
   }
 
   // Restore an earlier revision by appending a new one. Later history is never
   // erased: a revert is itself a revision, with the source recorded.
-  function revert(ref, revision, reason, author) {
+  function revert(ref, revision, reason, author, context) {
     var located = requireLive(ref);
     var target = Number(revision);
     if (!Number.isInteger(target) || target < 1) throw new Error("A revision number is required.");
@@ -96,6 +99,7 @@ function attachVersioning(ctx) {
     appendRevision(located.rootId, "revert", logsSnapshot.cloneSnapshot(source.snapshot), author, {
       revertedFrom: target,
       reason: trimmedReason,
+      context: logContext.normalizeRecordContext(context),
     });
     return read(ref, false);
   }