@michelj/context-guard 0.4.4 → 0.6.1

package/scripts/shared/map-model.mjs

@@ -0,0 +1,506 @@
+// Shared by the workbench and Node service. Unknown stored fields are retained.
+export const editableFields = ['title', 'purpose', 'kind', 'state', 'memoryDocument', 'memories', 'ideas', 'todos', 'bugs', 'messages', 'access', 'dormant', 'files', 'owns', 'proposal', 'isNew'];
+// Transport JSON stays open/fixed/resolved plus Unfixable as an end state.
+// `fixed` is agent-complete and still reviewable. Do not add deferred/wontfix as
+// live write values; leftover stored ones stay closed.
+export const WRITABLE_BUG_STATUSES = Object.freeze(['open', 'fixed', 'resolved', 'unfixable']);
+export const CLOSED_BUG_STATUSES = Object.freeze(['resolved', 'unfixable', 'dormant', 'deferred', 'wontfix']);
+export function isWritableBugStatus(status) {
+  return WRITABLE_BUG_STATUSES.includes(status);
+}
+export function isClosedBugStatus(status) {
+  return CLOSED_BUG_STATUSES.includes(status);
+}
+export class MapError extends Error {
+  constructor(code, message, status = 400, details = {}) { super(message); Object.assign(this, { code, status, details }); }
+}
+export const copy = value => JSON.parse(JSON.stringify(value));
+export const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+export function filterNodeAccess(document, grants, agentId, mode = 'write') {
+  if (!document?.root) return [];
+  const index = entries(document.root);
+  return grants.filter(id => {
+    const node = index.get(id)?.node;
+    if (!node) return false;
+    const rule = node.access?.find(item => item.agentId === agentId);
+    return !rule || rule.allow === 'write' || mode === 'read' && rule.allow === 'read';
+  });
+}
+const object = x => x && typeof x === 'object' && !Array.isArray(x);
+const proposalBases = new Set(['new-module', 'new-interface', 'new-component', 'new-responsibility']);
+function proposalPath(value) {
+  if (typeof value !== 'string') return '';
+  let file = value.trim().replaceAll('\\', '/');
+  while (file.startsWith('./')) file = file.slice(2);
+  const parts = file.split('/').filter(Boolean);
+  if (!file || file.length > 500 || file.startsWith('/') || file.startsWith('~') || /^[A-Za-z]:\//.test(file) || !parts.length || parts.some(part => part === '.' || part === '..')) return '';
+  return parts.join('/') + (file.endsWith('/') ? '/' : '');
+}
+function supportOnlyPath(file) {
+  const lower = file.toLowerCase(), parts = lower.split('/'), basename = parts.at(-1);
+  if (['test', 'tests', '__tests__', 'docs', 'doc', 'references', '.github'].includes(parts[0])) return true;
+  if (/^(readme|changelog|contributing|license|todo)(\.|$)/.test(basename) || basename === 'skill.md') return true;
+  if (/^(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|package\.json)$/.test(basename)) return true;
+  if (/(^|[._-])(test|tests|spec)([._-]|$)/.test(basename)) return true;
+  return /(^|\/)([^/]*\.config\.[^/]+|[^/]*rc(?:\.[^/]+)?)$/.test(lower);
+}
+function validateAgentProposalNode(node, parentId) {
+  const title = String(node?.title || '').trim(), purpose = String(node?.purpose || '').trim();
+  const owns = Array.isArray(node?.owns) ? [...new Set(node.owns.map(proposalPath))] : [];
+  const evidence = (Array.isArray(node?.memories) ? node.memories : []).map(memory => memory?.proposalEvidence).find(object);
+  if (!title || title.length > 120 || !purpose || purpose.length > 500) throw new MapError('INVALID_PROPOSAL', 'Agent node proposals need a concise title and purpose');
+  if (!owns.length || owns.some(path => !path)) throw new MapError('INVALID_PROPOSAL', 'Agent node proposals need valid repo-relative owns paths');
+  if (!evidence) throw new MapError('INVALID_PROPOSAL', 'Agent node proposals need proposalEvidence');
+  const reason = String(evidence.reason || '').trim(), basis = String(evidence.basis || '').trim();
+  const files = Array.isArray(evidence.files) ? [...new Set(evidence.files.map(proposalPath))] : [];
+  if (String(evidence.parentId || '').trim() !== parentId) throw new MapError('INVALID_PROPOSAL', 'Proposal evidence parentId must match the create parent');
+  if (!reason || reason.length > 1000 || !proposalBases.has(basis)) throw new MapError('INVALID_PROPOSAL', 'Proposal evidence needs a valid basis and reason');
+  if (!files.length || files.some(path => !path) || files.every(supportOnlyPath)) throw new MapError('INVALID_PROPOSAL', 'Proposal evidence needs at least one implementation file');
+  if (files.some(file => !owns.some(owned => owned === file || file.startsWith(owned.endsWith('/') ? owned : `${owned}/`)))) throw new MapError('INVALID_PROPOSAL', 'Proposal evidence files must be covered by the proposed owns paths');
+}
+export function entries(root) {
+  const found = new Map();
+  function visit(node, parent = null, bucket = 'children', depth = 0) {
+    if (depth > 128 || found.size >= 10000) throw new MapError('INVALID_MAP', 'Map exceeds depth/node limits');
+    if (!object(node) || typeof node.id !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(node.id)) throw new MapError('INVALID_MAP', 'Invalid node ID');
+    if (found.has(node.id)) throw new MapError('INVALID_MAP', `Duplicate node: ${node.id}`);
+    found.set(node.id, { node, parent, bucket });
+    for (const key of ['children', '_inbox']) {
+      if (node[key] !== undefined && !Array.isArray(node[key])) throw new MapError('INVALID_MAP', `${node.id}.${key} must be an array`);
+      for (const child of node[key] || []) visit(child, node, key, depth + 1);
+    }
+  }
+  visit(root); return found;
+}
+export function validate(doc) {
+  if (object(doc) && doc.root === null && doc.bootstrap === 'pending' && !(doc.flows || []).length) return new Map();
+  if (!object(doc) || !object(doc.root)) throw new MapError('INVALID_MAP', 'Map requires a root node');
+  const index = entries(doc.root);
+  if (doc.unassigned_bugs !== undefined && !Array.isArray(doc.unassigned_bugs)) throw new MapError('INVALID_MAP', 'unassigned_bugs must be an array');
+  if ((doc.unassigned_bugs || []).some(item => !object(item))) throw new MapError('INVALID_MAP', 'Unassigned bug must be an object');
+  for (const { node } of index.values()) {
+    if (typeof node.title !== 'string' || node.title.length > 10000) throw new MapError('INVALID_MAP', `${node.id}: invalid title`);
+    if (node.purpose !== undefined && typeof node.purpose !== 'string') throw new MapError('INVALID_MAP', 'purpose must be text');
+    if (node.memoryDocument !== undefined && (typeof node.memoryDocument !== 'string' || node.memoryDocument.length > 12000)) {
+      throw new MapError('INVALID_MAP', `${node.id}: memory document must be text within 12000 characters`);
+    }
+    for (const key of ['memories', 'ideas', 'todos', 'bugs', 'messages', 'access', 'dormant', 'files', 'owns']) {
+      if (node[key] !== undefined && !Array.isArray(node[key])) throw new MapError('INVALID_MAP', `${key} must be an array`);
+    }
+    if (node.kind && !['module', 'work'].includes(node.kind)) throw new MapError('INVALID_MAP', 'Invalid kind');
+    if (node.state && !['dirty', 'untested', 'success', 'failed'].includes(node.state)) throw new MapError('INVALID_MAP', 'Invalid state');
+    if (node.proposal && !['proposed', 'accepted', 'cancelled'].includes(node.proposal)) throw new MapError('INVALID_MAP', 'Invalid proposal');
+    for (const item of [...(node.memories || []), ...(node.ideas || []), ...(node.todos || []), ...(node.bugs || [])]) {
+      if (!object(item)) throw new MapError('INVALID_MAP', 'Memory/idea/todo/bug must be an object');
+      const refs = Array.isArray(item.also) ? item.also : typeof item.also === 'string' ? item.also.split(/[,，]/).map(x => x.trim()).filter(Boolean) : [];
+      if (refs.some(id => !index.has(id))) throw new MapError('INVALID_REFERENCE', `${node.id}: missing also reference`);
+    }
+    for (const todo of node.todos || []) {
+      if (typeof todo.title !== 'string' || todo.title.length > 10000) throw new MapError('INVALID_MAP', `${node.id}: invalid TODO title`);
+      if (todo.status && !['pending', 'processing', 'done'].includes(todo.status)) throw new MapError('INVALID_MAP', `${node.id}: invalid TODO status`);
+      validateAttempts(todo, 'Todo');
+    }
+    for (const bug of node.bugs || []) validateAttempts(bug, 'Bug');
+  }
+  for (const bug of doc.unassigned_bugs || []) validateAttempts(bug, 'Bug');
+  for (const { node } of index.values()) {
+    for (const message of node.messages || []) if (!object(message) || typeof message.text !== 'string') throw new MapError('INVALID_MAP', 'Message must contain text');
+    const agents = new Set();
+    for (const rule of node.access || []) {
+      if (!object(rule) || typeof rule.agentId !== 'string' || !rule.agentId || !['read', 'write', 'none'].includes(rule.allow) || agents.has(rule.agentId)) throw new MapError('INVALID_MAP', 'Invalid or duplicate node access rule');
+      agents.add(rule.agentId);
+    }
+  }
+  for (const flow of doc.flows || []) {
+    if (!index.has(flow.from) || !index.has(flow.to)) throw new MapError('INVALID_REFERENCE', 'Flow endpoint is missing');
+  }
+  return index;
+}
+
+function validateAttempts(item, kind) {
+  if (item.attempts === undefined) return;
+  if (!Array.isArray(item.attempts) || !item.attempts.length) throw new MapError('INVALID_ATTEMPT', `${kind} attempts must be a nonempty list`);
+  for (const [index, attempt] of item.attempts.entries()) {
+    if (!object(attempt) || !['Confirmed', 'Refuted'].includes(attempt.status)) throw new MapError('INVALID_ATTEMPT', `${kind} attempt needs Confirmed or Refuted status`);
+    if (attempt.status === 'Refuted') {
+      const target = /^A([1-9]\d*)$/.exec(attempt.refutedBy || '');
+      if (!target || Number(target[1]) <= index + 1 || Number(target[1]) > item.attempts.length || !String(attempt.reason || '').trim()) {
+        throw new MapError('INVALID_ATTEMPT', `${kind} refutation needs a later attempt and reason`);
+      }
+    } else if (attempt.refutedBy !== undefined || attempt.reason !== undefined) throw new MapError('INVALID_ATTEMPT', `${kind} confirmed attempt cannot carry refutation fields`);
+    for (const field of ['reproduction', 'acceptance', 'cause', 'solution', 'resolution', 'event', 'eventSource']) {
+      if (attempt[field] !== undefined && typeof attempt[field] !== 'string') throw new MapError('INVALID_ATTEMPT', `${kind} ${field} must be text`);
+    }
+    if (attempt.codeIndex !== undefined && (!Array.isArray(attempt.codeIndex) || attempt.codeIndex.some(entry => !object(entry) || typeof entry.path !== 'string' || !entry.path || typeof entry.summary !== 'string'))) {
+      throw new MapError('INVALID_ATTEMPT', `${kind} code index is invalid`);
+    }
+    if (attempt.test !== undefined && (!object(attempt.test) || typeof attempt.test.summary !== 'string' || typeof attempt.test.content !== 'string')) {
+      throw new MapError('INVALID_ATTEMPT', `${kind} test evidence is invalid`);
+    }
+    if (attempt.sessionIds !== undefined && (!Array.isArray(attempt.sessionIds) || attempt.sessionIds.some(id => typeof id !== 'string' || !id.trim()))) {
+      throw new MapError('INVALID_ATTEMPT', `${kind} Session references are invalid`);
+    }
+  }
+}
+
+function relatedIds(node) {
+  const out = new Set();
+  const values = [node, ...(node.memories || []), ...(node.ideas || []), ...(node.todos || []), ...(node.bugs || [])];
+  for (const value of values) {
+    const refs = Array.isArray(value?.also)
+      ? value.also
+      : typeof value?.also === 'string'
+        ? value.also.split(/[,，]/).map(id => id.trim()).filter(Boolean)
+        : [];
+    refs.forEach(id => out.add(id));
+  }
+  return out;
+}
+
+export function assignmentScope(doc, nodeId) {
+  const index = validate(doc);
+  if (!index.has(nodeId)) throw new MapError('NOT_FOUND', `Node ${nodeId} is missing`, 404);
+  const related = new Set([nodeId]);
+  for (const flow of doc.flows || []) {
+    if (flow.from === nodeId) related.add(flow.to);
+    if (flow.to === nodeId) related.add(flow.from);
+  }
+  for (const [id, { node }] of index) {
+    const refs = relatedIds(node);
+    if (id === nodeId) refs.forEach(ref => related.add(ref));
+    if (refs.has(nodeId)) related.add(id);
+  }
+  const scope = new Set();
+  for (const id of related) {
+    let entry = index.get(id);
+    while (entry) {
+      if (!['cancelled', 'proposed'].includes(entry.node.proposal)) scope.add(entry.node.id);
+      entry = entry.parent ? index.get(entry.parent.id) : null;
+    }
+  }
+  return [...scope];
+}
+
+const assignedSessions = item => Array.isArray(item?.sessions)
+  ? [...new Set(item.sessions.map(value => String(value || '').trim()).filter(Boolean))]
+  : [];
+
+export function workItemAssignedTo(item, sessionId) {
+  return Boolean(sessionId) && (assignedSessions(item).includes(sessionId) || String(item?.target_session || '').trim() === sessionId);
+}
+
+function visibleWorkItem(item, sessionId) {
+  const scoped = copy(item);
+  scoped.sessions = [sessionId];
+  if (Object.hasOwn(scoped, 'target_session')) scoped.target_session = sessionId;
+  if (scoped.dispatch?.session_id && scoped.dispatch.session_id !== sessionId) delete scoped.dispatch;
+  return scoped;
+}
+
+function scopedWorkItems(items, sessionId) {
+  return (items || []).filter(item => workItemAssignedTo(item, sessionId)).map(item => visibleWorkItem(item, sessionId));
+}
+
+export function scopeDocumentToSession(document, sessionId) {
+  const scoped = copy(document);
+  if (!scoped?.root || !sessionId) return scoped;
+  for (const { node } of entries(scoped.root).values()) {
+    if (Array.isArray(node.bugs)) node.bugs = scopedWorkItems(node.bugs, sessionId);
+    if (Array.isArray(node.todos)) node.todos = scopedWorkItems(node.todos, sessionId);
+  }
+  if (Array.isArray(scoped.unassigned_bugs)) scoped.unassigned_bugs = [];
+  return scoped;
+}
+
+function restoreWorkItems(existing = [], incoming = [], sessionId) {
+  const current = new Map(existing.map(item => [item?.id, item]));
+  const next = [];
+  const incomingIds = new Set(incoming.map(item => item?.id).filter(Boolean));
+  for (const item of existing) {
+    if (!workItemAssignedTo(item, sessionId)) next.push(copy(item));
+    else if (!incomingIds.has(item?.id)) {
+      const otherSessions = assignedSessions(item).filter(id => id !== sessionId);
+      if (otherSessions.length) next.push({ ...copy(item), sessions: otherSessions });
+    }
+  }
+  for (const item of incoming) {
+    const before = current.get(item?.id);
+    if (before && !workItemAssignedTo(before, sessionId)) throw new MapError('FORBIDDEN_WORK_ITEM', 'Session cannot replace a hidden work item', 403);
+    const otherSessions = assignedSessions(before).filter(id => id !== sessionId);
+    const keepsCurrent = !before || assignedSessions(item).includes(sessionId) || String(item?.target_session || '') === sessionId;
+    const restored = { ...copy(item), sessions: [...otherSessions, ...(keepsCurrent ? [sessionId] : [])] };
+    if (before && before.target_session && before.target_session !== sessionId && !keepsCurrent) restored.target_session = before.target_session;
+    else if (keepsCurrent && Object.hasOwn(item, 'target_session')) restored.target_session = sessionId;
+    if (before?.dispatch?.session_id && before.dispatch.session_id !== sessionId && !restored.dispatch) restored.dispatch = copy(before.dispatch);
+    next.push(restored);
+  }
+  return next;
+}
+
+function assignedBug(document, bugId, sessionId) {
+  if (!document?.root) return false;
+  for (const { node } of entries(document.root).values()) {
+    const bug = (node.bugs || []).find(item => item?.id === bugId);
+    if (bug) return workItemAssignedTo(bug, sessionId);
+  }
+  return false;
+}
+
+function assertOperations(operations) {
+  if (!Array.isArray(operations) || operations.length < 1 || operations.length > 2000) throw new MapError('INVALID_OPERATIONS', 'Expected 1–2000 operations');
+}
+
+export function restoreSessionWorkItemOperations(document, operations, sessionId) {
+  assertOperations(operations);
+  if (!sessionId) return copy(operations);
+  const index = document?.root ? entries(document.root) : new Map();
+  return operations.map(operation => {
+    const op = copy(operation);
+    const node = index.get(op.id)?.node;
+    if (op.type === 'update' && node) {
+      if (Array.isArray(op.fields?.bugs)) op.fields.bugs = restoreWorkItems(node.bugs, op.fields.bugs, sessionId);
+      if (Array.isArray(op.fields?.todos)) op.fields.todos = restoreWorkItems(node.todos, op.fields.todos, sessionId);
+    }
+    if (op.type === 'create') for (const key of ['bugs', 'todos']) if (Array.isArray(op.node?.[key])) {
+      op.node[key] = op.node[key].map(item => ({ ...item, sessions: [sessionId], ...(Object.hasOwn(item, 'target_session') ? { target_session: sessionId } : {}) }));
+    }
+    if (op.type === 'attach-bug') op.bug = { ...op.bug, sessions: [sessionId] };
+    if (op.type === 'update-bug' && !assignedBug(document, op.bug?.id, sessionId)) throw new MapError('FORBIDDEN_WORK_ITEM', 'Session can only update bugs assigned to it', 403);
+    return op;
+  });
+}
+
+export function scopeChangesToSession(result, document, sessionId) {
+  const visibleBugIds = new Set();
+  if (document?.root) for (const { node } of entries(document.root).values()) {
+    for (const bug of node.bugs || []) if (workItemAssignedTo(bug, sessionId)) visibleBugIds.add(bug.id);
+  }
+  const changes = (result.changes || []).map(change => {
+    const operations = (change.operations || []).flatMap(operation => {
+      const op = copy(operation);
+      if (op.type === 'attach-bug' || op.type === 'recover-bug') return workItemAssignedTo(op.bug, sessionId) ? [{ ...op, bug: visibleWorkItem(op.bug, sessionId) }] : [];
+      if (op.type === 'update-bug') return visibleBugIds.has(op.bug?.id) ? [op] : [];
+      if (op.type === 'update') for (const key of ['bugs', 'todos']) if (Array.isArray(op.fields?.[key])) op.fields[key] = scopedWorkItems(op.fields[key], sessionId);
+      if (op.type === 'create') for (const key of ['bugs', 'todos']) if (Array.isArray(op.node?.[key])) op.node[key] = scopedWorkItems(op.node[key], sessionId);
+      return [op];
+    });
+    return { ...change, operations, fields: (change.fields || []).filter(field => field !== 'unassigned_bugs') };
+  });
+  return { ...result, changes };
+}
+function checkFields(fields, allowed = editableFields) {
+  if (!object(fields) || Object.keys(fields).some(key => !allowed.includes(key))) throw new MapError('INVALID_FIELDS', 'Unsupported field');
+}
+export function applyOperations(document, operations, actor, grants = []) {
+  assertOperations(operations);
+  const doc = copy(document), resultIds = [];
+  const human = actor.kind === 'human';
+  const developer = actor.kind === 'developer';
+  const coordinator = actor.kind === 'coordinator';
+  const ideaWriter = human || coordinator;
+  const directStructure = human || developer || coordinator;
+  const allowed = node => directStructure || grants.includes(node.id) || (node.proposal === 'proposed' && node.proposedBy === actor.sessionId);
+  for (const op of operations) {
+    if (op.type === 'initialize') {
+      if (doc.root !== null || typeof op.project !== 'string' || !op.project.trim()) throw new MapError('INVALID_INITIALIZATION', 'Only an empty legacy pending map can be initialized');
+      checkFields(op.node, ['id', ...editableFields, 'children', '_inbox']);
+      if (!ideaWriter && Object.hasOwn(op.node, 'memoryDocument')) throw new MapError('FORBIDDEN', 'Only the workbench or Coordinator can write memory documents', 403);
+      if (!ideaWriter && op.node.ideas?.length) throw new MapError('FORBIDDEN', 'Only Coordinator can write Ideas', 403);
+      if (!human && op.node.access?.length) throw new MapError('FORBIDDEN', 'Agent cannot set node access', 403);
+      if (!human && (op.node.children?.length || op.node._inbox?.length)) throw new MapError('FORBIDDEN', 'Only the workbench can initialize a complete map', 403);
+      doc.project = op.project;
+      doc.root = { id: 'T0', title: op.project, kind: 'module', state: 'dirty', children: [], ...copy(op.node), origin: actor.kind, proposal: human ? 'accepted' : 'proposed', proposedBy: actor.sessionId };
+      doc.bootstrap = 'proposed'; resultIds.push(doc.root.id); continue;
+    }
+    if (!doc.root) throw new MapError('INITIALIZATION_REQUIRED', 'Initialize this legacy empty map before adding nodes');
+    const index = entries(doc.root);
+    const target = index.get(op.id);
+    if (op.type === 'create') {
+      const parent = index.get(op.parentId)?.node;
+      if (!parent) throw new MapError('NOT_FOUND', 'Parent is missing', 404);
+      checkFields(op.node, ['id', ...editableFields]);
+      if (!ideaWriter && Object.hasOwn(op.node, 'memoryDocument')) throw new MapError('FORBIDDEN', 'Only the workbench or Coordinator can write memory documents', 403);
+      if (!ideaWriter && op.node.ideas?.length) throw new MapError('FORBIDDEN', 'Only Coordinator can write Ideas', 403);
+      const id = op.node.id;
+      if (!id || index.has(id)) throw new MapError('DUPLICATE_ID', 'Node ID already exists or is empty', 409);
+      if (!directStructure) {
+        if (op.node.access?.length) throw new MapError('FORBIDDEN', 'Agent cannot set node access', 403);
+        validateAgentProposalNode(op.node, op.parentId);
+        const title = String(op.node.title).trim().toLocaleLowerCase();
+        const owns = new Set(op.node.owns.map(proposalPath));
+        for (const { node: existing } of index.values()) {
+          if (existing.proposal === 'cancelled') continue;
+          if (String(existing.title || '').trim().toLocaleLowerCase() === title) throw new MapError('DUPLICATE_PROPOSAL', 'A non-cancelled node already has this title', 409);
+          if (existing.proposal === 'proposed' && (existing.owns || []).some(file => owns.has(proposalPath(file)))) throw new MapError('DUPLICATE_PROPOSAL', 'A pending proposal already covers this path', 409);
+        }
+      }
+      const node = { title: '', kind: 'work', state: 'dirty', purpose: '', memories: [], ideas: [], todos: [], bugs: [], dormant: [], files: [], owns: [], children: [], ...copy(op.node), origin: actor.kind, proposedBy: actor.sessionId };
+      if (!directStructure) { node.proposal = 'proposed'; node.isNew = true; }
+      else { node.proposal ||= 'accepted'; node.isNew = node.proposal === 'proposed'; }
+      const children = parent.children ||= [];
+      if (op.order !== undefined && (!Number.isSafeInteger(op.order) || op.order < 0 || op.order > children.length)) throw new MapError('INVALID_ORDER', 'Sibling position is outside the list');
+      children.splice(op.order ?? children.length, 0, node); resultIds.push(id);
+    } else if (op.type === 'relation') {
+      const flows = doc.flows ||= [];
+      const position = op.legacyIndex === undefined ? flows.findIndex(flow => flow.id === op.id)
+        : Number.isSafeInteger(op.legacyIndex) && op.legacyIndex >= 0 && !flows[op.legacyIndex]?.id ? op.legacyIndex : -1;
+      const prior = flows[position];
+      if (!['create', 'update', 'delete'].includes(op.action)) throw new MapError('INVALID_OPERATION', 'Invalid relation action');
+      if (op.action === 'create' ? !!prior : !prior) throw new MapError('VERSION_CONFLICT', 'Relation no longer matches the operation', 409);
+      checkFields(op.fields || {}, ['from', 'to', 'label']);
+      const next = { ...prior, ...copy(op.fields || {}), id: op.id };
+      for (const id of new Set([prior?.from, prior?.to, next.from, next.to].filter(Boolean))) {
+        const node = index.get(id)?.node;
+        if (!node) throw new MapError('NOT_FOUND', 'Relation endpoint is missing', 404);
+        if (!allowed(node)) throw new MapError('FORBIDDEN', 'Relation endpoint is not authorized', 403);
+        resultIds.push(id);
+      }
+      if (op.action === 'create') flows.push(next);
+      else if (op.action === 'delete') flows.splice(position, 1);
+      else flows[position] = next;
+    } else if (op.type === 'document') {
+      if (!human) throw new MapError('FORBIDDEN', 'Only the workbench can change document metadata', 403);
+      checkFields(op.fields, ['bootstrap', 'flows', 'unassigned_bugs']); Object.assign(doc, copy(op.fields));
+    } else if (op.type === 'recover-bug') {
+      if (actor.kind !== 'recovery' || !actor.sessionId) throw new MapError('FORBIDDEN_RECOVERY', 'Bug recovery requires a verified original receipt', 403);
+      if (!target || !allowed(target.node) || !object(op.bug) || !/^B[0-9]+$/.test(op.bug.id || '')) throw new MapError('INVALID_BUG_RECOVERY', 'Invalid bug recovery', 403);
+      let existing = null;
+      for (const { node } of index.values()) {
+        const found = (node.bugs || []).find(item => item?.id === op.bug.id);
+        if (found) existing ||= found;
+        if (Array.isArray(node.bugs)) node.bugs = node.bugs.filter(item => item?.id !== op.bug.id);
+      }
+      const unassigned = (doc.unassigned_bugs || []).find(item => item?.id === op.bug.id);
+      existing ||= unassigned;
+      if (Array.isArray(doc.unassigned_bugs)) doc.unassigned_bugs = doc.unassigned_bugs.filter(item => item?.id !== op.bug.id);
+      const bug = { ...copy(existing || {}), ...copy(op.bug), sessions: [...new Set([...assignedSessions(existing), actor.sessionId])] };
+      (target.node.bugs ||= []).push(bug); resultIds.push(op.id);
+    } else if (op.type === 'attach-bug') {
+      // Compatibility operation only adds a bug stub; it cannot confirm or rewrite nodes.
+      if (!object(op.bug) || !/^B[0-9]+$/.test(op.bug.id || '')) throw new MapError('INVALID_BUG', 'Invalid bug');
+      if (op.bug.status !== undefined && !isWritableBugStatus(op.bug.status)) {
+        throw new MapError('INVALID_BUG', 'Bugs cannot be deferred; delete the record or close it as unfixable');
+      }
+      const list = target ? (target.node.bugs ||= []) : (doc.unassigned_bugs ||= []);
+      const existing = list.find(x => x.id === op.bug.id);
+      if (existing && !same(existing, op.bug)) throw new MapError('DUPLICATE_ID', 'Bug ID already exists', 409);
+      if (!existing) list.push(copy(op.bug));
+      resultIds.push(op.id || doc.root.id);
+    } else if (op.type === 'delete-work-item') {
+      if (!human && !coordinator) throw new MapError('FORBIDDEN', 'Only the workbench or Coordinator can delete TODO/Bug records', 403);
+      if (!['todo', 'bug'].includes(op.kind) || typeof op.itemId !== 'string' || !op.itemId || (op.nodeId !== undefined && (typeof op.nodeId !== 'string' || !op.nodeId))) {
+        throw new MapError('INVALID_OPERATION', 'Invalid work item deletion');
+      }
+      const field = `${op.kind}s`;
+      let owner = op.nodeId ? index.get(op.nodeId)?.node : null, ownerId = op.nodeId || '';
+      if (op.nodeId && !owner) throw new MapError('NOT_FOUND', `Node ${op.nodeId} is missing`, 404);
+      if (!owner) {
+        const matches = [...index.entries()].filter(([, entry]) => (entry.node[field] || []).some(item => item?.id === op.itemId));
+        if (matches.length > 1) throw new MapError('CONFLICT', `${op.kind} ${op.itemId} has multiple owners`, 409);
+        if (matches.length === 1) { ownerId = matches[0][0]; owner = matches[0][1].node; }
+      }
+      if (owner) {
+        const list = owner[field] || [], position = list.findIndex(item => item?.id === op.itemId);
+        if (position < 0) throw new MapError('NOT_FOUND', `${op.kind} ${op.itemId} is missing`, 404);
+        owner[field] = list.filter((_, current) => current !== position);
+        resultIds.push(ownerId);
+      } else if (op.kind === 'bug' && Array.isArray(doc.unassigned_bugs)) {
+        const position = doc.unassigned_bugs.findIndex(item => item?.id === op.itemId);
+        if (position < 0) throw new MapError('NOT_FOUND', `${op.kind} ${op.itemId} is missing`, 404);
+        doc.unassigned_bugs.splice(position, 1); resultIds.push(doc.root.id);
+      } else throw new MapError('NOT_FOUND', `${op.kind} ${op.itemId} is missing`, 404);
+    } else if (op.type === 'update-bug') {
+      if (!object(op.bug) || !/^B[0-9]+$/.test(op.bug.id || '') || !isWritableBugStatus(op.bug.status)) {
+        throw new MapError('INVALID_BUG', 'Bugs cannot be deferred; delete the record or close it as unfixable');
+      }
+      let found = null, owner = doc.root.id;
+      for (const [id, entry] of index) {
+        found = (entry.node.bugs || []).find(item => item.id === op.bug.id);
+        if (found) { owner = id; break; }
+      }
+      if (!found) found = (doc.unassigned_bugs || []).find(item => item.id === op.bug.id);
+      if (!found) throw new MapError('NOT_FOUND', `Bug ${op.bug.id} is missing`, 404);
+      found.status = op.bug.status; resultIds.push(owner);
+    } else {
+      if (!target) throw new MapError('NOT_FOUND', `Node ${op.id} is missing`, 404);
+      if (!allowed(target.node)) throw new MapError('FORBIDDEN', `Session is not authorized for ${op.id}`, 403);
+      if (op.type === 'update') {
+        checkFields(op.fields);
+        if (!ideaWriter && Object.hasOwn(op.fields, 'memoryDocument')) throw new MapError('FORBIDDEN', 'Only the workbench or Coordinator can write memory documents', 403);
+        if (!ideaWriter && Object.hasOwn(op.fields, 'ideas')) throw new MapError('FORBIDDEN', 'Only Coordinator can write Ideas', 403);
+        if (!human && ['proposal', 'isNew', 'access'].some(key => Object.hasOwn(op.fields, key))) throw new MapError('FORBIDDEN', 'Agent cannot confirm proposals or change node access', 403);
+        Object.assign(target.node, copy(op.fields));
+      } else if (op.type === 'move') {
+        const parent = index.get(op.parentId)?.node;
+        if (!target.parent || !parent || entries(target.node).has(parent.id)) throw new MapError('INVALID_MOVE', 'Missing parent, root move or tree cycle');
+        if (!allowed(parent)) throw new MapError('FORBIDDEN', 'Destination is not authorized', 403);
+        target.parent[target.bucket] = target.parent[target.bucket].filter(x => x.id !== op.id);
+        const children = parent.children ||= [];
+        if (op.order !== undefined && (!Number.isSafeInteger(op.order) || op.order < 0 || op.order > children.length)) throw new MapError('INVALID_ORDER', 'Sibling position is outside the list');
+        children.splice(op.order ?? children.length, 0, target.node);
+      } else if (op.type === 'delete') {
+        if ((!human && !coordinator) || !target.parent) throw new MapError('FORBIDDEN', 'Only the workbench or Coordinator can remove a non-root node', 403);
+        const removed = new Set(entries(target.node).keys());
+        target.parent[target.bucket] = target.parent[target.bucket].filter(x => x.id !== op.id);
+        if (Array.isArray(doc.flows)) doc.flows = doc.flows.filter(flow => !removed.has(flow.from) && !removed.has(flow.to));
+        for (const { node } of entries(doc.root).values()) for (const field of ['memories', 'ideas', 'todos', 'bugs']) {
+          for (const item of node[field] || []) if (Array.isArray(item.also)) item.also = item.also.filter(id => !removed.has(id));
+        }
+        for (const id of removed) resultIds.push(id);
+      } else throw new MapError('INVALID_OPERATION', 'Unknown operation type');
+      resultIds.push(op.id);
+    }
+  }
+  const layer = [...(doc.root.children || []), ...(doc.root._inbox || [])].filter(n => n.proposal !== 'cancelled');
+  if (layer.length) doc.bootstrap = layer.every(n => n.proposal !== 'proposed') ? 'ready' : 'proposed';
+  validate(doc); return { doc, resultIds: [...new Set(resultIds)] };
+}
+// Ignore canvas-only inbox expansion and absent empty arrays. Compare only fields
+// the editor owns, so merely drawing a legacy map never rewrites its metadata.
+export function diffTrees(before, after) {
+  const a = entries(before), b = entries(after), ops = [];
+  for (const [id, { node, parent }] of b) {
+    const old = a.get(id);
+    if (!old) {
+      const fields = Object.fromEntries(['id', ...editableFields].filter(k => node[k] !== undefined).map(k => [k, copy(node[k])]));
+      ops.push({ type: 'create', parentId: parent?.id, node: fields }); continue;
+    }
+    if (old.parent?.id !== parent?.id) ops.push({ type: 'move', id, parentId: parent?.id });
+    const fields = {};
+    for (const key of editableFields) {
+      if (node[key] === undefined) continue;
+      if (old.node[key] === undefined && (Array.isArray(node[key]) && !node[key].length || node[key] === '')) continue;
+      if (!same(old.node[key], node[key])) fields[key] = copy(node[key]);
+    }
+    if (Object.keys(fields).length) ops.push({ type: 'update', id, fields });
+  }
+  for (const [id, { parent }] of a) if (!b.has(id) && parent && b.has(parent.id)) ops.push({ type: 'delete', id });
+  // Reconstruct the child order after structural operations before emitting
+  // positional moves. This also handles inserts before existing siblings.
+  const lists = new Map([...a].map(([id, { node }]) => [id, (node.children || []).map(child => child.id)]));
+  const owners = new Map([...a].filter(([, item]) => item.parent && item.bucket === 'children').map(([id, item]) => [id, item.parent.id]));
+  const detach = id => {
+    const list = lists.get(owners.get(id));
+    if (list?.includes(id)) list.splice(list.indexOf(id), 1);
+    owners.delete(id);
+  };
+  for (const op of ops) {
+    if (op.type === 'delete') detach(op.id);
+    if (op.type === 'move' || op.type === 'create') {
+      const id = op.id || op.node.id;
+      detach(id);
+      if (!lists.has(op.parentId)) lists.set(op.parentId, []);
+      lists.get(op.parentId).push(id); owners.set(id, op.parentId);
+      if (!lists.has(id)) lists.set(id, []);
+    }
+  }
+  for (const [parentId, { node }] of b) {
+    const list = lists.get(parentId) || [];
+    for (const [order, child] of (node.children || []).entries()) {
+      if (list[order] === child.id) continue;
+      detach(child.id); list.splice(order, 0, child.id); owners.set(child.id, parentId);
+      ops.push({ type: 'move', id: child.id, parentId, order });
+    }
+  }
+  return ops;
+}

package/scripts/shared/memory-schema.mjs

@@ -0,0 +1,13 @@
+import { MapError, validate } from './map-model.mjs';
+export function validateMemory(value) {
+  if (!value || typeof value !== 'object' || !value.map) throw new MapError('INVALID_MEMORY', 'A map and records are required');
+  validate(value.map);
+  if (value.display !== undefined && (!value.display || typeof value.display !== 'object' || Array.isArray(value.display)
+      || Object.keys(value.display).some(key => !['name', 'platform'].includes(key))
+      || typeof value.display.name !== 'string' || !value.display.name.trim() || value.display.name.length > 200
+      || typeof value.display.platform !== 'string' || value.display.platform.length > 30)) throw new MapError('INVALID_MEMORY', 'Invalid Session display metadata');
+  if (!value.records || typeof value.records !== 'object' || Array.isArray(value.records)) throw new MapError('INVALID_MEMORY', 'records must be an object');
+  for (const [file, content] of Object.entries(value.records)) {
+    if (!/^(?:(?:sessions|bugs|fixes|tasks|cards)\/[A-Za-z0-9_.-]+\.md|(?:index|FIND|user-messages|architecture|l1-candidates)\.md|(?:preferences|bugs-index|bad-case-events|jump-index|owns-index|tasks-index|l1-candidates)\.json|sessions\.jsonl)$/.test(file) || file.split('/').includes('..') || typeof content !== 'string') throw new MapError('PRIVATE_PATH', 'Only development records may be uploaded; private/runtime files are excluded');
+  }
+}

package/scripts/shared/protocol-blobs.mjs

@@ -0,0 +1,112 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { atomicWrite, encode, hash, readJSON, withFileLock } from './io.mjs';
+import { canonical, fail, payloadRules } from './protocol.mjs';
+
+const CHUNK = 1024 * 1024;
+// Authentication and binding checks belong to the caller, before any body is read.
+export async function serveBlob(req, res, { blobs, principal, session, blobId }) {
+  if (req.method === 'PUT') {
+    const chunks = []; let size = 0;
+    for await (const chunk of req) {
+      size += chunk.length;
+      if (size > CHUNK) fail('TOO_LARGE', 'Chunk exceeds 1 MiB');
+      chunks.push(chunk);
+    }
+    const result = await blobs.put(principal, session, blobId, req.headers['content-range'], Buffer.concat(chunks));
+    res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+    return res.end(JSON.stringify(result));
+  }
+  if (req.method !== 'GET') fail('INVALID_ARGUMENT', 'Use PUT or GET');
+  const data = await blobs.read(principal, session, blobId, req.headers.range);
+  res.writeHead(req.headers.range ? 206 : 200, {
+    'Content-Type': 'application/octet-stream', 'X-Content-Type-Options': 'nosniff', 'Cache-Control': 'no-store',
+    ETag: `"${data.sha256}"`, 'Accept-Ranges': 'bytes', 'Content-Length': data.bytes.length,
+    ...(req.headers.range ? { 'Content-Range': `bytes ${data.start}-${data.end}/${data.size}` } : {}),
+  });
+  return res.end(data.bytes);
+}
+// Private, content-addressed chunks are immutable. Metadata advances only after
+// each chunk is fsynced. A lost reply can safely resend the same byte range.
+export class ProtocolBlobs {
+  constructor(directory) { this.directory = path.resolve(directory); }
+  owner(principal, session) { return hash(canonical([principal.repositoryId, session.id, session.generation])); }
+  directoryFor(principal, session, blobId) {
+    if (!/^[a-f0-9]{64}$/.test(blobId)) fail('INVALID_ARGUMENT', 'Invalid blob ID');
+    return path.join(this.directory, this.owner(principal, session), blobId);
+  }
+  async register(principal, session, metadata) {
+    payloadRules['blob.put'](metadata);
+    const blobId = hash(canonical(metadata)), directory = this.directoryFor(principal, session, blobId);
+    return withFileLock(path.join(directory, 'lock'), async () => {
+      const file = path.join(directory, 'metadata.json');
+      let record = await readJSON(file, null);
+      if (!record) {
+        if (metadata.size === 0 && metadata.sha256 !== hash(Buffer.alloc(0))) fail('INVALID_ARGUMENT', 'Empty file hash mismatch');
+        record = { ...metadata, offset: 0, complete: metadata.size === 0, chunks: [] };
+        await atomicWrite(file, encode(record));
+      }
+      return { blobId, uploadPath: `/api/v2/blobs/${blobId}`, offset: record.offset };
+    });
+  }
+  async put(principal, session, blobId, range, bytes) {
+    const directory = this.directoryFor(principal, session, blobId);
+    const match = /^bytes (\d+)-(\d+)\/(\d+)$/.exec(range || '');
+    if (!match || !Buffer.isBuffer(bytes) || bytes.length > CHUNK || bytes.length === 0) fail('INVALID_ARGUMENT', 'Expected a Content-Range and at most 1 MiB');
+    const [start, end, total] = match.slice(1).map(Number);
+    if (![start, end, total].every(Number.isSafeInteger) || end - start + 1 !== bytes.length || end >= total) fail('INVALID_ARGUMENT', 'Invalid byte range');
+    return withFileLock(path.join(directory, 'lock'), async () => {
+      const file = path.join(directory, 'metadata.json'), record = await readJSON(file, null);
+      if (!record) fail('NOT_FOUND', 'Blob is not registered in this Session');
+      if (total !== record.size) fail('CONFLICT', 'Blob length differs from registration');
+      const digest = hash(bytes), previous = record.chunks.find(c => c.start === start);
+      if (previous) {
+        if (previous.end !== end || previous.digest !== digest) fail('CONFLICT', 'Repeated chunk differs');
+        return { offset: record.offset, complete: record.complete };
+      }
+      if (start !== record.offset) fail('CONFLICT', 'Send the next contiguous range', { offset: record.offset });
+      const chunkFile = path.join(directory, `${start}-${digest}.chunk`);
+      if (end + 1 === record.size) {
+        const full = createHash('sha256');
+        for (const chunk of record.chunks) {
+          const data = await fs.readFile(path.join(directory, `${chunk.start}-${chunk.digest}.chunk`));
+          if (hash(data) !== chunk.digest) fail('UNAVAILABLE', 'Stored chunk is corrupt');
+          full.update(data);
+        }
+        full.update(bytes);
+        if (full.digest('hex') !== record.sha256) fail('CONFLICT', 'Completed file hash does not match registration');
+        record.complete = true;
+      }
+      await atomicWrite(chunkFile, bytes);
+      record.chunks.push({ start, end, digest }); record.offset = end + 1;
+      await atomicWrite(file, encode(record));
+      return { offset: record.offset, complete: record.complete };
+    });
+  }
+  async metadata(principal, session, blobId) {
+    const record = await readJSON(path.join(this.directoryFor(principal, session, blobId), 'metadata.json'), null);
+    if (!record?.complete) fail('NOT_FOUND', 'Blob is missing or incomplete');
+    return { downloadPath: `/api/v2/blobs/${blobId}`, size: record.size, sha256: record.sha256, mediaType: record.mediaType };
+  }
+  async read(principal, session, blobId, range) {
+    const directory = this.directoryFor(principal, session, blobId);
+    const metadata = await this.metadata(principal, session, blobId);
+    let start = 0, end = metadata.size - 1;
+    if (range) {
+      const match = /^bytes=(\d+)-(\d*)$/.exec(range);
+      if (!match) fail('INVALID_ARGUMENT', 'Use a single byte range');
+      start = Number(match[1]); end = match[2] ? Number(match[2]) : end;
+      if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start > end || end >= metadata.size) fail('INVALID_ARGUMENT', 'Range is outside the file');
+    }
+    const record = await readJSON(path.join(directory, 'metadata.json'));
+    const chunks = [];
+    for (const chunk of record.chunks) {
+      if (chunk.end < start || chunk.start > end) continue;
+      const bytes = await fs.readFile(path.join(directory, `${chunk.start}-${chunk.digest}.chunk`));
+      if (hash(bytes) !== chunk.digest) fail('UNAVAILABLE', 'Stored chunk is corrupt');
+      chunks.push(bytes.subarray(Math.max(0, start - chunk.start), Math.min(bytes.length, end - chunk.start + 1)));
+    }
+    return { bytes: Buffer.concat(chunks), start, end, ...metadata };
+  }
+}