@arjunkhera/atlas 0.0.0 → 0.2.0

package/work/lib/mcp-stdio.mjs

@@ -0,0 +1,68 @@
+// A small MCP server over stdio: JSON-RPC 2.0, one JSON message per line.
+// No dependency. Supports initialize, notifications/initialized, ping,
+// tools/list and tools/call. The server binds to the first client that
+// initializes it and refuses a second initialize (lock block L1: "refuses a
+// call from another session").
+import { createInterface } from 'node:readline';
+
+export const PROTOCOL_VERSIONS = Object.freeze(['2025-06-18', '2025-03-26', '2024-11-05']);
+const MAX_LINE = 4 * 1024 * 1024;
+
+export function createMcpServer({ name, version, instructions, tools, call, input = process.stdin, output = process.stdout, log = () => {} }) {
+  if (!Array.isArray(tools) || typeof call !== 'function') throw new TypeError('tools and call are required');
+  let bound = null;
+  const write = (message) => output.write(`${JSON.stringify(message)}\n`);
+  const reply = (id, result) => write({ jsonrpc: '2.0', id, result });
+  const fail = (id, code, message, data) => write({ jsonrpc: '2.0', id, error: { code, message, ...(data === undefined ? {} : { data }) } });
+
+  async function handle(message) {
+    if (!message || typeof message !== 'object' || message.jsonrpc !== '2.0') { fail(message?.id ?? null, -32600, 'invalid JSON-RPC 2.0 request'); return; }
+    const { id, method, params } = message;
+    const isNotification = id === undefined;
+    try {
+      if (method === 'initialize') {
+        if (bound) { fail(id, -32600, `this server is bound to session ${bound.session}; start a new server for another session`); return; }
+        const requested = params?.protocolVersion;
+        bound = { session: `${params?.clientInfo?.name ?? 'client'}:${Date.now()}`, client: params?.clientInfo ?? null, at: new Date().toISOString() };
+        log(`bound to ${bound.session}`);
+        reply(id, { protocolVersion: PROTOCOL_VERSIONS.includes(requested) ? requested : PROTOCOL_VERSIONS[0], capabilities: { tools: { listChanged: false } }, serverInfo: { name, version }, ...(instructions ? { instructions } : {}) });
+        return;
+      }
+      if (method === 'notifications/initialized' || method === 'notifications/cancelled') return;
+      if (method === 'ping') { if (!isNotification) reply(id, {}); return; }
+      if (!bound) { if (!isNotification) fail(id, -32002, 'initialize first; this server serves one session'); return; }
+      if (method === 'tools/list') { reply(id, { tools: tools.map(({ name: toolName, description, inputSchema }) => ({ name: toolName, description, inputSchema })) }); return; }
+      if (method === 'tools/call') {
+        const toolName = params?.name;
+        if (!tools.some((tool) => tool.name === toolName)) { fail(id, -32602, `unknown tool: ${toolName}`); return; }
+        const args = params?.arguments ?? {};
+        try {
+          const result = await call(toolName, args, bound);
+          reply(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], structuredContent: result, isError: false });
+        } catch (error) {
+          const refused = error?.name === 'VerbError';
+          reply(id, { content: [{ type: 'text', text: JSON.stringify({ refused, error: error?.message ?? String(error) }, null, 2) }], isError: true });
+        }
+        return;
+      }
+      if (!isNotification) fail(id, -32601, `method not found: ${method}`);
+    } catch (error) {
+      if (!isNotification) fail(id, -32603, error?.message ?? 'internal error');
+    }
+  }
+
+  function start() {
+    const lines = createInterface({ input, crlfDelay: Infinity });
+    let chain = Promise.resolve();
+    lines.on('line', (line) => {
+      if (!line.trim()) return;
+      if (line.length > MAX_LINE) { fail(null, -32600, 'message too large'); return; }
+      let message;
+      try { message = JSON.parse(line); } catch { fail(null, -32700, 'parse error'); return; }
+      const batch = Array.isArray(message) ? message : [message];
+      for (const item of batch) chain = chain.then(() => handle(item));
+    });
+    return new Promise((resolve) => lines.on('close', () => chain.then(resolve)));
+  }
+  return Object.freeze({ start, handle, bound: () => bound });
+}

package/work/lib/questions.mjs

@@ -0,0 +1,278 @@
+// Atlas M1 slice L2: questions, decisions, receipts and the "Needs me" view.
+// Design: the Atlas M1 study, D1 (the records), D2
+// (the verbs and the door), D3 (the views), D6 findings R5, R8, R12 and R15,
+// and the frozen L2 paragraph of the lock block.
+// The verbs run behind the same door, the same journal and the same registry
+// checks as slice L1. Every record carries request_id and writer.
+import protectedPaths from '../protected-paths.json' with { type: 'json' };
+import { refuse, text, oneOf, isoDate, url, stringList } from './verb-fields.mjs';
+
+// R5: the cost of waiting is a closed vocabulary, ranked. Index 0 costs most.
+export const COSTS = Object.freeze(['blocked-merge', 'paused-item', 'spend', 'date']);
+export const COST_MEANING = Object.freeze({
+  'blocked-merge': 'a merge waits on the answer',
+  'paused-item': 'the item is stopped until the answer comes',
+  spend: 'money runs while the answer waits',
+  date: 'a date is at risk',
+});
+// 'sweep' is the kind the slice L5 sweep record carries. It is a decision like
+// any other: the owner's words, dated, listing the items (design finding R7).
+export const DECISION_KINDS = Object.freeze(['decision', 'priority', 'answer', 'sweep']);
+export const QUESTION_STATUS = Object.freeze(['open', 'answered']);
+export const QUESTION_WRITE_VERBS = Object.freeze(['question_ask', 'question_answer', 'decision_record', 'receipt_keep']);
+export const QUESTION_READ_VERBS = Object.freeze(['needs_me']);
+
+// R8: the row budget. Three visible lines; everything else folds under it.
+export const ROW_LINES = 3;
+export const ROW_LINE_MAX = 160;
+const MAX_OPEN_QUESTIONS = 500;
+const MAX_RENDERED = 20_000;
+
+export const oneLine = (value, max = ROW_LINE_MAX) => {
+  const flat = String(value ?? '').replace(/\s+/g, ' ').trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+};
+
+// R12: a scrub by pattern in receipt keep. The patterns are the ones the
+// sub-agents deny, in work/protected-paths.json. A (?i) prefix is Python and
+// Go spelling; JavaScript takes it as a flag.
+export function scrubSecrets(value) {
+  let out = String(value ?? '');
+  let redactions = 0;
+  for (const source of protectedPaths.secret_patterns ?? []) {
+    const insensitive = source.startsWith('(?i)');
+    const pattern = new RegExp(insensitive ? source.slice(4) : source, insensitive ? 'gi' : 'g');
+    out = out.replace(pattern, () => { redactions += 1; return '[REDACTED]'; });
+  }
+  return { text: out, redactions };
+}
+
+function questionContext(value) {
+  if (value === undefined || value === null) return {};
+  if (typeof value !== 'object' || Array.isArray(value)) refuse('context must be an object: current_behavior, change, affected, options, consequences');
+  const context = {};
+  for (const key of ['current_behavior', 'change', 'consequences']) {
+    const line = text(value[key], `context.${key}`, { optional: true, max: 4000 });
+    if (line !== undefined) context[key] = line;
+  }
+  for (const key of ['affected', 'options']) {
+    if (value[key] !== undefined) context[key] = stringList(value[key], `context.${key}`, { max: 32 }).map((entry) => text(entry, `context.${key}`, { max: 2000 }));
+  }
+  if (value.sources !== undefined) context.sources = stringList(value.sources, 'context.sources', { max: 16 }).map((entry) => url(entry, 'context.sources'));
+  return context;
+}
+
+// Row line two: the id is the citation a reader types back, so the title gives
+// way to it, not the other way round (review G6).
+export function itemLine(item, product) {
+  // Each part is flattened on its own, so no field in the graph can add a
+  // fourth line to a three-line row (review G8). The separator is added after
+  // the flattening, because flattening also trims the ends.
+  const tail = oneLine(`${product} · ${item.fields?.stage ?? 'unknown stage'} · ${item.id}`);
+  const budget = ROW_LINE_MAX - tail.length - 3;
+  if (budget < 1) return oneLine(`${oneLine(item.title)} · ${tail}`);
+  return `${oneLine(item.title, budget)} · ${tail}`;
+}
+
+export function createQuestionVerbs(core) {
+  const { client, label, now, typeNamed, kindOf, registry, requireProduct, requireItem, requireOwner, patch, create, edge, landed, alreadyPatched, findCreated } = core;
+
+  async function recordOfKind(id, kind, name) {
+    text(id, name, { max: 200 });
+    let entity;
+    try { entity = await client.getEntity(id); }
+    catch (error) { if (error?.status === 404) refuse(`unknown ${kind} id: ${id}`); throw error; }
+    if ((await kindOf(entity)) !== kind) refuse(`entity ${id} is not a ${kind} record`);
+    if (entity.state && entity.state !== 'active') refuse(`${kind} ${id} is ${entity.state}, not active in the graph`);
+    return entity;
+  }
+
+  // The sweep of slice L5 lists every active item of a product, so this cap is
+  // the sweep's real ceiling, and work/lib/sweep.mjs reads back the same
+  // number (architect review of Batch 15, finding 5). Every id is verified,
+  // so a long list costs one read each.
+  async function itemsTouched(value, reg, fallback) {
+    if (value === undefined) return fallback ? [fallback] : [];
+    const ids = stringList(value, 'items', { max: 200 });
+    for (const id of ids) await requireItem(id);
+    return ids;
+  }
+
+  // R15 and the L2 text: the receipt is written in the same call as the answer.
+  async function writeReceipt({ decision, question, rendered, view, requestId, meta, product }) {
+    const clean = scrubSecrets(text(rendered, 'receipt.rendered', { max: MAX_RENDERED }));
+    const type = await typeNamed('receipt');
+    const prior = (await findCreated(type, requestId))[0];
+    if (prior) return prior;
+    const entity = await create(type, requestId, meta?.verb ?? 'receipt_keep', {
+      digest: meta?.digest,
+      title: `Receipt · ${oneLine(view || 'answer', 80)} · ${(question ?? decision).id.slice(0, 8)}`,
+      body: clean.text,
+      fields: {
+        decision: decision.id, ...(question ? { question: question.id } : {}), ...(product ? { product } : {}),
+        view: view || '', rendered: clean.text, kept_at: now(), redactions: clean.redactions,
+      },
+      tags: ['atlas-receipt', ...(product ? [`product:${product}`] : [])],
+    });
+    await edge(decision, entity, 'references', requestId);
+    return entity;
+  }
+
+  const verbs = {
+    // Any in-session agent may ask. D2: refuses with no item id, no product id, no cost of waiting.
+    async question_ask(args, requestId, meta) {
+      const questionText = text(args.text, 'text', { max: 8000 });
+      const itemId = text(args.item_id, 'item_id', { max: 200 });
+      const productId = text(args.product, 'product', { max: 64 });
+      const cost = oneOf(args.cost, 'cost', COSTS);
+      const reg = await registry();
+      const product = await requireProduct(productId, reg);
+      const item = await requireItem(itemId);
+      if (item.fields?.product && item.fields.product !== product.fields.registry_id) refuse(`item ${itemId} belongs to product ${item.fields.product}, not ${productId}`);
+      const context = questionContext(args.context);
+      const type = await typeNamed('question');
+      const prior = await landed(type, requestId, meta);
+      // A retry after an interrupted write finds the record and re-makes the edge it lost (review G1).
+      if (prior) { await edge(prior, item, 'references', requestId); return { verb: 'question_ask', question_id: prior.id, version: prior.version, status: prior.fields.status, item: prior.fields.item, product: prior.fields.product, cost: prior.fields.cost, replayed_from_graph: true }; }
+      const entity = await create(type, requestId, 'question_ask', {
+        digest: meta?.digest, title: oneLine(questionText, 200), body: questionText,
+        fields: {
+          text: questionText, item: item.id, product: product.fields.registry_id,
+          asked_by: { agent: label.agent, session: label.session }, asked_at: now(),
+          cost, cost_rank: COSTS.indexOf(cost), context, status: 'open',
+        },
+        tags: ['atlas-question', `product:${product.fields.registry_id}`, `cost:${cost}`],
+      });
+      await edge(entity, item, 'references', requestId);
+      return { verb: 'question_ask', question_id: entity.id, version: entity.version, status: 'open', item: item.id, product: product.fields.registry_id, cost, cost_rank: COSTS.indexOf(cost) };
+    },
+
+    // The owner answers. One call writes the decision, the receipt, and closes the question.
+    async question_answer(args, requestId, meta) {
+      requireOwner('question answer');
+      const question = await recordOfKind(args.question_id, 'question', 'question_id');
+      const answer = text(args.text, 'text', { max: MAX_RENDERED });
+      const date = isoDate(args.date, 'date');
+      const source = text(args.source, 'source', { optional: true, max: 500 }) ?? '';
+      const kind = oneOf(args.kind, 'kind', DECISION_KINDS, 'answer');
+      if (alreadyPatched(question, requestId, meta)) {
+        return { verb: 'question_answer', question_id: question.id, version: question.version, status: question.fields.status, decision_id: question.fields.answer ?? null, receipt_id: question.fields.receipt ?? null, replayed_from_graph: true };
+      }
+      if (question.fields?.status !== 'open') refuse(`question ${question.id} is already ${question.fields?.status} (decision ${question.fields?.answer ?? 'unknown'}); reopen is not an L2 verb`);
+      const reg = await registry();
+      const productId = question.fields.product;
+      await requireProduct(productId, reg);
+      const items = await itemsTouched(args.items, reg, question.fields.item);
+      const priorityOrder = args.priority_order === undefined ? undefined : (await itemsTouched(args.priority_order, reg, null));
+      let replaced = null;
+      if (args.replaces !== undefined) replaced = await recordOfKind(args.replaces, 'decision', 'replaces');
+      const decisionType = await typeNamed('decision');
+      const decision = (await landed(decisionType, requestId, meta)) ?? await create(decisionType, requestId, 'question_answer', {
+        digest: meta?.digest, title: oneLine(`${kind}: ${answer}`, 200), body: answer,
+        fields: {
+          kind, text: answer, date, source, product: productId, answers: question.id, items,
+          ...(priorityOrder ? { priority_order: priorityOrder } : {}), ...(replaced ? { replaces: replaced.id } : {}),
+        },
+        tags: ['atlas-decision', `product:${productId}`],
+      });
+      await edge(decision, question, 'references', requestId);
+      if (replaced) await edge(replaced, decision, 'replaced_by', requestId);
+      const rendered = args.rendered === undefined ? `${question.fields.text}\n\nOwner, ${date}: ${answer}` : args.rendered;
+      const receipt = await writeReceipt({ decision, question, rendered, view: args.view ?? 'needs-me', requestId, meta, product: productId });
+      const closed = await patch(question, 'question_answer', requestId, { status: 'answered', answer: decision.id, answered_at: now(), receipt: receipt.id }, { digest: meta?.digest });
+      return { verb: 'question_answer', question_id: closed.id, version: closed.version, status: 'answered', decision_id: decision.id, receipt_id: receipt.id, items, redactions: receipt.fields.redactions ?? 0 };
+    },
+
+    // The owner speaks outside a question. D2: refuses with no verbatim text, no date.
+    async decision_record(args, requestId, meta) {
+      requireOwner('decision record');
+      const decisionText = text(args.text, 'text', { max: MAX_RENDERED });
+      const date = isoDate(args.date, 'date');
+      const source = text(args.source, 'source', { optional: true, max: 500 }) ?? '';
+      const kind = oneOf(args.kind, 'kind', DECISION_KINDS, 'decision');
+      const reg = await registry();
+      let productId = '';
+      if (args.product !== undefined) productId = (await requireProduct(args.product, reg)).fields.registry_id;
+      const items = await itemsTouched(args.items, reg, null);
+      const priorityOrder = args.priority_order === undefined ? undefined : (await itemsTouched(args.priority_order, reg, null));
+      let replaced = null;
+      if (args.replaces !== undefined) replaced = await recordOfKind(args.replaces, 'decision', 'replaces');
+      const type = await typeNamed('decision');
+      // A retry after an interrupted write reuses the record that landed, then finishes
+      // the edge and the receipt the first attempt never reached (review G2).
+      const prior = await landed(type, requestId, meta);
+      const decision = prior ?? await create(type, requestId, 'decision_record', {
+        digest: meta?.digest, title: oneLine(`${kind}: ${decisionText}`, 200), body: decisionText,
+        fields: {
+          kind, text: decisionText, date, source, ...(productId ? { product: productId } : {}), items,
+          ...(priorityOrder ? { priority_order: priorityOrder } : {}), ...(replaced ? { replaces: replaced.id } : {}),
+        },
+        tags: ['atlas-decision', ...(productId ? [`product:${productId}`] : [])],
+      });
+      if (replaced) await edge(replaced, decision, 'replaced_by', requestId);
+      let receipt = null;
+      if (args.rendered !== undefined) receipt = await writeReceipt({ decision, question: null, rendered: args.rendered, view: args.view ?? '', requestId, meta, product: productId });
+      return { verb: 'decision_record', decision_id: decision.id, version: decision.version, kind: decision.fields.kind, date: decision.fields.date, items: decision.fields.items ?? [], receipt_id: receipt?.id ?? null, redactions: receipt?.fields.redactions ?? 0, ...(prior ? { replayed_from_graph: true } : {}) };
+    },
+
+    // Keep the rendered answer the owner acted on. D2: refuses with no decision to attach to.
+    async receipt_keep(args, requestId, meta) {
+      requireOwner('receipt keep');
+      const decision = await recordOfKind(args.decision_id, 'decision', 'decision_id');
+      const rendered = text(args.rendered, 'rendered', { max: MAX_RENDERED });
+      const view = text(args.view, 'view', { optional: true, max: 200 }) ?? '';
+      const type = await typeNamed('receipt');
+      const prior = await landed(type, requestId, meta);
+      if (prior) { await edge(decision, prior, 'references', requestId); return { verb: 'receipt_keep', receipt_id: prior.id, version: prior.version, decision_id: decision.id, redactions: prior.fields.redactions ?? 0, replayed_from_graph: true }; }
+      const receipt = await writeReceipt({ decision, question: null, rendered, view, requestId, meta, product: decision.fields?.product ?? '' });
+      return { verb: 'receipt_keep', receipt_id: receipt.id, version: receipt.version, decision_id: decision.id, redactions: receipt.fields.redactions ?? 0 };
+    },
+
+    // D3: the "Needs me" view. Computed at question time, per product, never stored.
+    async needs_me(args = {}) {
+      const reg = await registry();
+      let only = null;
+      if (args.product !== undefined) only = (await requireProduct(args.product, reg)).fields.registry_id;
+      const type = await typeNamed('question');
+      const rows = await client.listAllEntities({ type: type.name, state: 'active' });
+      const open = rows.filter((row) => row.fields?.status === 'open' && (!only || row.fields?.product === only));
+      // The bound is on the open questions. An answered question costs the view nothing (review G3).
+      if (open.length > MAX_OPEN_QUESTIONS) refuse(`${open.length} questions are open; the view reads at most ${MAX_OPEN_QUESTIONS}. Answer some, or narrow the view with a product id.`);
+      const items = new Map(), unreadable = new Map();
+      for (const row of open) {
+        const id = row.fields?.item;
+        if (typeof id !== 'string' || items.has(id)) continue;
+        try { items.set(id, await client.getEntity(id)); }
+        catch (error) { items.set(id, null); unreadable.set(id, error?.status === 404 ? 'the item is not in the graph' : `the graph did not answer: ${error?.message ?? String(error)}`); }
+      }
+      const readAt = now();
+      const kept = [], omitted = [];
+      for (const row of open) {
+        const item = items.get(row.fields.item) ?? null;
+        const lifecycle = item?.fields?.lifecycle ?? 'unknown';
+        // D3 rule 1: active items only. A question on any other item is named, not dropped in silence.
+        if (lifecycle !== 'active') { omitted.push({ question_id: row.id, item: row.fields.item, item_lifecycle: lifecycle, reason: item ? `the item is ${lifecycle}; paused and proposed items are backlog` : (unreadable.get(row.fields.item) ?? 'the item cannot be read') }); continue; }
+        const cost = row.fields.cost;
+        const rank = COSTS.indexOf(cost);
+        const asked = row.fields.asked_by ?? {};
+        kept.push({
+          question_id: row.id, product: row.fields.product, item: item.id, cost, cost_rank: rank === -1 ? COSTS.length : rank,
+          asked_at: row.fields.asked_at ?? row.created_at ?? '', asked_by: asked.agent ?? 'unknown',
+          lines: [
+            oneLine(row.fields.text),
+            itemLine(item, row.fields.product),
+            oneLine(`${cost}: ${COST_MEANING[cost] ?? 'cost outside the vocabulary'} · asked by ${asked.agent ?? 'unknown'} on ${(row.fields.asked_at ?? '').slice(0, 10)}`),
+          ],
+          folded: { question: row.fields.text, context: row.fields.context ?? {}, asked_by: asked, item_title: item.title, item_stage: item.fields.stage ?? '', item_next_step: item.fields.next_step ?? '' },
+          citation: { question: row.id, item: item.id, read_at: readAt },
+        });
+      }
+      kept.sort((a, b) => a.cost_rank - b.cost_rank || String(a.asked_at).localeCompare(String(b.asked_at)) || a.question_id.localeCompare(b.question_id));
+      const products = [...new Set(kept.map((row) => row.product))].sort();
+      const byProduct = products.map((product) => ({ product, rows: kept.filter((row) => row.product === product) }));
+      const render = byProduct.map((group) => [`${group.product} — needs you (${group.rows.length})`, ...group.rows.flatMap((row, index) => row.lines.map((line, position) => `${position === 0 ? `${index + 1}. ` : '   '}${line}`))].join('\n')).join('\n\n');
+      return { verb: 'needs_me', read_at: readAt, product: only, row_budget: ROW_LINES, rows: kept.length, products: byProduct, omitted, text: render || 'Nothing needs you: no open question on an active item.' };
+    },
+  };
+  return verbs;
+}

package/work/lib/sweep.mjs

@@ -0,0 +1,189 @@
+// Atlas M1 slice L5: the one-time sweep.
+// Design: the Atlas M1 study, D5 slice L5, design
+// finding R7, and the frozen L5 paragraph of the lock block.
+//
+// The frozen text asks for two things and nothing else:
+//   1. The owner's one-time sweep, written as a decision record that lists the
+//      active items. That record is the oracle (R7). It is written by the
+//      decision_record verb of slice L2 with kind "sweep"; this module adds no
+//      second way to write a decision.
+//   2. The "In flight" view equal to that list. sweep_check reads the view of
+//      slice L3 and compares it with the record. It writes nothing.
+//
+// One write verb stands between the two: item_adopt. The sweep gives an item a
+// product, and until now no verb could. item_propose and item_lock name a
+// product when they make or lock an item; items made before the registry
+// existed carry no product at all. Both L3 and L4 views say so on every read.
+import { refuse, text, oneOf, stringList } from './verb-fields.mjs';
+import { oneLine, scrubSecrets, ROW_LINE_MAX } from './questions.mjs';
+import { listLine } from './delivery.mjs';
+
+export const SWEEP_WRITE_VERBS = Object.freeze(['item_adopt']);
+export const SWEEP_READ_VERBS = Object.freeze(['sweep_check']);
+// The kind that marks a decision record as a sweep. `kind` is a free string in
+// the manifest, so this costs no manifest version (the M2 lane holds it).
+export const SWEEP_KIND = 'sweep';
+
+// A sweep record can hold at most this many item ids, because decision_record
+// verifies each one. The same number bounds what the check reads back, so the
+// two can never disagree (architect review, finding 5).
+export const MAX_SWEPT = 200;
+const MAX_SWEEPS = 300;
+const TITLES_FETCHED = 25;
+
+export function createSweepVerbs(core) {
+  const { client, now, typeNamed, registry, requireProduct, requireRepos, requireItem, requireOwner, patch, alreadyPatched, inFlight, stages, tiers, drivers } = core;
+
+  const verbs = {
+    // Give an existing item its product and repos. Owner present, because the
+    // sweep is the owner's own list (R7) and a product is a name the owner owns.
+    async item_adopt(args, requestId, meta) {
+      requireOwner('item adopt');
+      const item = await requireItem(args.item_id);
+      const fields = item.fields ?? {};
+      if (alreadyPatched(item, requestId, meta)) {
+        return { verb: 'item_adopt', item_id: item.id, version: item.version, product: fields.product ?? null, repos: fields.repos ?? [], lifecycle: fields.lifecycle ?? null, stage: fields.stage ?? null, replayed_from_graph: true };
+      }
+      const reg = await registry();
+      const product = await requireProduct(args.product, reg);
+      const productId = product.fields.registry_id;
+      const named = typeof fields.product === 'string' ? fields.product : '';
+      // An item is named once. Moving it between registered products is not a
+      // sweep, and no verb of M1 does it: the reader of any view would see the
+      // work change product with nothing on the record to say why.
+      if (named && named !== productId && reg.products.has(named)) refuse(`item ${item.id} already names the registered product ${named}, not ${productId}; the sweep names an item once`);
+      // `repos` is required, and an empty list is how a caller says "this item
+      // has no repo" — a container root is the real case. Leaving the argument
+      // out used to fall back to whatever survived the product filter, which
+      // could silently empty the field and leave an item no other verb could
+      // have written (architect review, finding 4).
+      if (args.repos === undefined) {
+        const kept = (Array.isArray(fields.repos) ? fields.repos : []).filter((id) => reg.repos.get(id)?.fields?.product === productId);
+        refuse(`repos is required: name the repo ids under ${productId}, or pass an empty list for an item with no repo.${kept.length ? ` This item already names ${kept.join(', ')}.` : ''}`);
+      }
+      const asked = stringList(args.repos, 'repos', { max: 16 });
+      const repos = asked.length ? await requireRepos(asked, reg, productId) : [];
+      const dropped = (Array.isArray(fields.repos) ? fields.repos : []).filter((id) => !repos.includes(id));
+      const change = { product: productId, repos };
+      if (args.tier !== undefined) change.tier = oneOf(args.tier, 'tier', tiers);
+      if (args.driver !== undefined) change.driver = oneOf(args.driver, 'driver', drivers);
+      if (args.next_step !== undefined) change.next_step = text(args.next_step, 'next_step', { max: 1000 });
+      if (args.stage !== undefined) {
+        const stage = oneOf(args.stage, 'stage', stages);
+        if (fields.lifecycle !== 'active') refuse(`item ${item.id} is ${fields.lifecycle ?? 'unknown'}; only an active item carries a stage`);
+        change.stage = stage;
+      }
+      const same = named === productId && [...repos].sort().join(' ') === [...(Array.isArray(fields.repos) ? fields.repos : [])].sort().join(' ');
+      if (same && Object.keys(change).length === 2) return { verb: 'item_adopt', item_id: item.id, version: item.version, product: productId, repos, lifecycle: fields.lifecycle ?? null, stage: fields.stage ?? null, unchanged: true };
+      // The audit stamps say when the sweep NAMED this item and what it came
+      // from. A later call that only sets a stage or a next step must not move
+      // them, or "adopted_from: engram" ends up on an item already in engram
+      // and the sweep's own date is lost (architect review, finding 3).
+      const stamps = named === productId ? {} : { adopted_at: now(), adopted_from: named || null };
+      const entity = await patch(item, 'item_adopt', requestId, { ...change, ...stamps }, {
+        digest: meta?.digest,
+        tags: [`product:${productId}`, ...repos.map((id) => `repo:${id}`), ...(change.tier ? [`tier:${change.tier}`] : [])],
+      });
+      return { verb: 'item_adopt', item_id: entity.id, version: entity.version, product: productId, repos, lifecycle: entity.fields?.lifecycle ?? null, stage: entity.fields?.stage ?? null, previous_product: named || null, ...(dropped.length ? { dropped_repos: dropped } : {}) };
+    },
+
+    // R7 made mechanical: the sweep record is the oracle, so the check reads
+    // the record and the view and names every difference. Read only.
+    async sweep_check(args = {}) {
+      const reg = await registry();
+      let only = null;
+      if (args.product !== undefined) only = (await requireProduct(args.product, reg)).fields.registry_id;
+      const type = await typeNamed('decision');
+      const decisions = await client.listAllEntities({ type: type.name, state: 'active' });
+      // Filter to sweeps BEFORE bounding. Every answered question writes a
+      // decision, so a count over all decisions would one day refuse the verb
+      // with no argument that helps (architect review, finding 6).
+      const sweeps = decisions.filter((row) => row.fields?.kind === SWEEP_KIND && typeof row.fields?.product === 'string' && row.fields.product && (!only || row.fields.product === only));
+      if (sweeps.length > MAX_SWEEPS) refuse(`${sweeps.length} sweep records are on record; the check reads at most ${MAX_SWEEPS}. Narrow it with a product id.`);
+      // A sweep for a product the registry does not hold cannot be checked: the
+      // view shows rows only for registered products, so every listed item
+      // would read as missing for ever (architect review, finding 7).
+      const orphaned = [...new Set(sweeps.filter((row) => !reg.products.has(row.fields.product)).map((row) => row.fields.product))].sort();
+      // One sweep stands per product. A sweep that names another with
+      // `replaces` supersedes it outright; otherwise the newest by the owner's
+      // date wins, then by write time, then by id so a tie is never decided by
+      // list order (architect review, findings 12 and 13).
+      const replaced = new Set(sweeps.map((row) => row.fields?.replaces).filter(Boolean));
+      const latest = new Map();
+      for (const row of sweeps) {
+        if (!reg.products.has(row.fields.product)) continue;
+        if (replaced.has(row.id)) continue;
+        const at = `${String(row.fields.date ?? '')} ${String(row.created_at ?? row.updated_at ?? '')} ${row.id}`;
+        const held = latest.get(row.fields.product);
+        if (!held || at > held.at) latest.set(row.fields.product, { row, at, superseded: held ? [...held.superseded, held.row.id] : [] });
+        else held.superseded.push(row.id);
+      }
+      for (const [product, held] of latest) held.superseded = [...new Set([...held.superseded, ...sweeps.filter((row) => row.fields.product === product && replaced.has(row.id)).map((row) => row.id)])];
+      const view = await inFlight(only ? { product: only } : {});
+      const inView = new Map(view.products.map((group) => [group.product, group.rows.map((row) => row.item)]));
+      const titles = new Map(view.products.flatMap((group) => group.rows.map((row) => [row.item, row.folded?.title ?? row.lines[0]])));
+
+      const checks = [];
+      const unreadable = [];
+      for (const productId of [...latest.keys()].sort()) {
+        const { row, superseded } = latest.get(productId);
+        // A malformed record must not make a read verb refuse: it is reported
+        // as unreadable and the other products still answer (finding 12).
+        let listed;
+        try { listed = [...new Set(stringList(row.fields.items ?? [], 'items', { max: MAX_SWEPT }))]; }
+        catch (error) { unreadable.push({ product: productId, decision: row.id, reason: error?.message ?? 'items is not a list of ids' }); continue; }
+        const seen = inView.get(productId) ?? [];
+        const missing = listed.filter((id) => !seen.includes(id));
+        const extra = seen.filter((id) => !listed.includes(id));
+        // A missing id is not in the view, so the view carries no title for it.
+        // The owner reads titles, not ids, so the check fetches the few it needs.
+        for (const [index, id] of missing.entries()) {
+          if (titles.has(id)) continue;
+          if (index >= TITLES_FETCHED) { titles.set(id, 'title not read: past the fetch bound of this check'); continue; }
+          try { const entity = await client.getEntity(id); titles.set(id, entity?.title ?? ''); }
+          catch { titles.set(id, 'the graph did not answer for this id'); }
+        }
+        checks.push({
+          product: productId, decision: row.id, date: row.fields.date ?? null, source: row.fields.source ?? '',
+          listed: listed.length, in_view: seen.length,
+          missing_from_view: missing.map((id) => ({ item: id, title: oneLine(titles.get(id) ?? '', 120) })),
+          extra_in_view: extra.map((id) => ({ item: id, title: oneLine(titles.get(id) ?? '', 120) })),
+          matches: !missing.length && !extra.length, items: listed, ...(superseded.length ? { superseded } : {}),
+        });
+      }
+      const notSwept = [...reg.products.keys()].filter((id) => (!only || id === only) && !latest.has(id)).sort();
+      // `matches` answers one narrow question: does each product's view hold
+      // exactly what its sweep lists? `complete` answers the wider one the
+      // owner actually asked: is every item in the tenant on a registered
+      // product? An item nobody adopted is missing from the record AND from
+      // the view, so the two sides agree by omission, and a headline reading
+      // "equal" over a fifth of the corpus would be a lie (architect review,
+      // finding 2). The two are reported apart, and the text says both.
+      const matches = checks.length > 0 && !notSwept.length && !unreadable.length && !orphaned.length && checks.every((check) => check.matches);
+      const outside = view.unregistered_total ?? 0;
+      const complete = matches && outside === 0;
+
+      const block = [
+        `Sweep check — ${only ?? 'every registered product'} · read ${String(view.read_at).slice(0, 19)}Z · ${matches ? 'the view equals the sweep' : 'the view and the sweep differ'}${matches ? (complete ? ', and every item in the tenant is on a registered product' : `, but ${outside} item${outside === 1 ? '' : 's'} sit outside every product, so the sweep is not complete`) : ''}`,
+        ...checks.map((check) => [
+          `${check.product} — sweep ${String(check.date ?? 'no date')} lists ${check.listed}, the view shows ${check.in_view} · ${check.matches ? 'equal' : 'not equal'}`,
+          `   decision ${check.decision}`,
+          ...check.missing_from_view.map((row) => listLine(`listed, not in flight: ${row.title}`, row.item)),
+          ...check.extra_in_view.map((row) => listLine(`in flight, not listed: ${row.title}`, row.item)),
+        ].join('\n')),
+        ...(notSwept.length ? [`no sweep on record (${notSwept.length})\n${notSwept.map((id) => `   ${id}`).join('\n')}`] : []),
+        ...(orphaned.length ? [`a sweep names a product the registry does not hold (${orphaned.length})\n${orphaned.map((id) => `   ${id} — the view can show no row for it, so its items would read as missing for ever`).join('\n')}`] : []),
+        ...(unreadable.length ? [`unreadable sweep record (${unreadable.length})\n${unreadable.map((row) => `   ${row.product} · ${row.decision} — ${row.reason}`).join('\n')}`] : []),
+        ...(outside ? [oneLine(`${outside} item${outside === 1 ? '' : 's'} still name no registered product, so the sweep is not complete. Each one is invisible to both sides of this check.`, ROW_LINE_MAX)] : []),
+        ...((view.repo_errors ?? []).length ? [`GitHub did not answer for ${view.repo_errors.length} repo${view.repo_errors.length === 1 ? '' : 's'}; the movement half of the view came from the graph alone\n${view.repo_errors.map((row) => `   ${row.repo} — ${row.reason}`).join('\n')}`] : []),
+      ].join('\n\n');
+      const rendered = scrubSecrets(block);
+      return {
+        verb: 'sweep_check', read_at: view.read_at, product: only, matches, complete, checks, not_swept: notSwept,
+        ...(orphaned.length ? { product_not_registered: orphaned } : {}), ...(unreadable.length ? { unreadable } : {}),
+        unregistered_total: outside, repo_errors: view.repo_errors ?? [], redactions: rendered.redactions, text: rendered.text,
+      };
+    },
+  };
+  return verbs;
+}

package/work/lib/verb-fields.mjs

@@ -0,0 +1,53 @@
+// Field checks shared by every Atlas work verb. Moved here unchanged in M1
+// slice L2 so the registry verbs (verbs.mjs) and the question, decision and
+// receipt verbs (questions.mjs) read the same rules.
+// Design: the Atlas M1 study, pages D1 and D2.
+import { createHash } from 'node:crypto';
+
+export const MAX_TEXT = 20_000;
+
+export class VerbError extends Error {
+  constructor(message, code = 'refused') { super(message); this.name = 'VerbError'; this.code = code; }
+}
+export const refuse = (message) => { throw new VerbError(message); };
+
+export function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (value && typeof value === 'object') return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`;
+  return JSON.stringify(value ?? null);
+}
+export const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+
+export function text(value, name, { max = MAX_TEXT, optional = false } = {}) {
+  if (value === undefined || value === null) { if (optional) return undefined; refuse(`${name} is required`); }
+  if (typeof value !== 'string' || !value.trim()) refuse(`${name} must be a non-empty string`);
+  if (value.length > max) refuse(`${name} is longer than ${max} characters`);
+  return value;
+}
+export function oneOf(value, name, allowed, fallback) {
+  if (value === undefined || value === null) { if (fallback !== undefined) return fallback; refuse(`${name} is required`); }
+  if (!allowed.includes(value)) refuse(`${name} must be one of: ${allowed.join(', ')}`);
+  return value;
+}
+export function isoDate(value, name) {
+  text(value, name, { max: 40 });
+  if (!/^\d{4}-\d{2}-\d{2}(?:T[\d:.]+Z)?$/.test(value) || Number.isNaN(Date.parse(value))) refuse(`${name} must be an ISO date, for example 2026-09-16`);
+  return value;
+}
+export function origin(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) refuse('origin must be an object with text, source and date, in the owner\'s words');
+  return { text: text(value.text, 'origin.text'), source: text(value.source, 'origin.source', { max: 500 }), date: isoDate(value.date, 'origin.date') };
+}
+export function url(value, name) {
+  text(value, name, { max: 2000 });
+  let parsed;
+  try { parsed = new URL(value); } catch { refuse(`${name} must be an absolute http or https URL`); }
+  if (!['http:', 'https:'].includes(parsed.protocol)) refuse(`${name} must be an http or https URL`);
+  return value;
+}
+export function stringList(value, name, { max = 64 } = {}) {
+  if (!Array.isArray(value)) refuse(`${name} must be an array of strings`);
+  if (value.length > max) refuse(`${name} holds more than ${max} entries`);
+  for (const item of value) if (typeof item !== 'string' || !item.trim()) refuse(`${name} must hold non-empty strings`);
+  return [...new Set(value)];
+}