@arjunkhera/atlas 0.3.11 → 0.3.13

package/tests/evidence.mjs

@@ -51,9 +51,13 @@ export class Evidence {
       ways: {}, assertions: [], tables: {}, fresh: [], calls: [], notes: [], files: [],
       provided_secrets: providedSecrets, fault_run: process.env.ATLAS_FAULT_RUN || null,
     };
-    for (const way of scenario.through) {
+    // One entry for each assertion and each way in that it belongs to (scenario.mjs, waysOf). An
+    // assertion that reads a result of a step with its own way in (the page) has that way only.
+    for (const way of scenario.ways ?? scenario.through) {
       this.record.ways[way] = { verdict: 'not finished', reason: null, started: null, ended: null };
-      for (const a of scenario.assertions) this.record.assertions.push({ id: a.fullId, way, result: 'not checked', proof: null });
+    }
+    for (const a of scenario.assertions) {
+      for (const way of a.ways ?? scenario.through) this.record.assertions.push({ id: a.fullId, way, result: 'not checked', proof: null });
     }
     mkdirSync(this.dir, { recursive: true });
     this.path = this.claim(scenario.id);

package/tests/index.mjs

@@ -2,7 +2,7 @@
 export { scenario, defineAdapter, waitUntil, RUN_ID } from './contract.mjs';
 export { startEnvironment, parseDotenv, provideSecrets } from './environment.mjs';
 export { createStandIn, serveStandIn, CALLS_PATH, LIBRARY_HEADER } from './stand-in.mjs';
-export { createHttpDriver, createMcpStdioDriver, createFunctionDriver, makeDriver } from './drivers/index.mjs';
+export { createHttpDriver, createMcpStdioDriver, createFunctionDriver, createBrowserDriver, makeDriver } from './drivers/index.mjs';
 export { parseTestsYaml, readTestsYaml, checkTestsYaml, guardParts, compareGuardParts, GUARD_PARTS, looksLikeSecret } from './tests-yaml.mjs';
 export { parseScenario, readScenario, addFingerprints, FINGERPRINT_METHOD } from './scenario.mjs';
 export { Blocked, Unavailable, WaitFailed, WaitTimeout, GateFailed } from './errors.mjs';

package/tests/link-check.mjs

@@ -500,7 +500,7 @@ export function checkRun({ evidenceDir, runId = null, environment = null, scenar
       continue;
     }
     for (const a of s.assertions) {
-      for (const way of s.through) {
+      for (const way of a.ways ?? s.through) {
         const seen = mine.some((r) => r.data.assertions?.some((e) => e.id === a.fullId && e.way === way && reached.has(e.result)));
         if (!seen) findings.push({ file: rel(s.file), line: a.line, code: 'not-checked', message: `no run checked ${s.id}/${a.id}#${a.fp} through ${way}` });
       }

package/tests/scenario.mjs

@@ -271,6 +271,23 @@ export function readScenario(path) {
 
 const runsIn = (scenario) => [].concat(scenario.fields['runs-in'] ?? []).map(String);
 
+// The ways in that an assertion is checked through. An assertion reads a kept result. When the
+// step that kept it names its own way in ("As `owner`, through `page`, ..."), the assertion belongs
+// to that way: the proof table shows it under that column (design section 6.3). An assertion that
+// names no kept result of such a step belongs to every way of `through:`. The ways of `through:`
+// stay first. The words and the fingerprint do not change.
+function waysOf(assertion, scenario, kept) {
+  const named = new Set();
+  let plain = false;
+  for (const name of assertion.names) {
+    const step = kept.get(name);
+    if (!step) continue;
+    if (step.way) named.add(step.way); else plain = true;
+  }
+  if (!named.size || plain) return [...new Set([...scenario.through, ...named])];
+  return [...named];
+}
+
 // Sets `fp` and `fullId` on every assertion. `tests` is the parsed value of
 // tests.yaml. Returns the scenario.
 export function addFingerprints(scenario, tests) {
@@ -315,7 +332,9 @@ export function addFingerprints(scenario, tests) {
     lines.push(`through=${[...scenario.through].sort().join(',')}`, `runs-in=${runsIn(scenario).sort().join(',')}`);
     a.fp = fingerprintOf([a.words, ...lines].join('\n'));
     a.fullId = `${scenario.id}/${a.id}#${a.fp}`;
+    a.ways = waysOf(a, scenario, kept);
   }
+  scenario.ways = [...new Set([...scenario.through, ...scenario.assertions.flatMap((a) => a.ways)])];
   return scenario;
 }
 

package/work/lib/activity.mjs

@@ -0,0 +1,246 @@
+// Work item additions, slice 3: the log of a work item.
+// The design: the work item additions, steps 5, 6, 8 and 9.
+//
+// One record type, entry, holds both a comment and a change. Each entry
+// carries the tag item:<id>, so one list by type and tag finds every entry of
+// an item: no scan of the tenant and no edge walk.
+//
+// The item verbs put a short diff into their own receipt on the item, in the
+// same write (verbs.mjs, patch). After the verb, logEntries copies the diff
+// into an entry. That second write is best effort: a failure is a warning,
+// the diff stays in the receipt, and the next write on the item tries again.
+import { VerbError, refuse, text, oneOf, LIVE_LIFECYCLES } from './verb-fields.mjs';
+import { oneLine, scrubSecrets } from './questions.mjs';
+
+export const ACTIVITY_WRITE_VERBS = Object.freeze(['item_comment']);
+export const ACTIVITY_READ_VERBS = Object.freeze(['item_activity']);
+export const VOICES = Object.freeze(['agent', 'owner']);
+// The item verbs whose writes carry a diff (step 9). item_propose writes a
+// "created" diff when it makes the item.
+export const LOG_VERBS = Object.freeze(['item_lock', 'item_split', 'item_park', 'item_resume', 'item_drop', 'item_edit', 'item_stage', 'item_link', 'item_block', 'item_unblock', 'item_done', 'item_reopen', 'item_adopt']);
+export const ENTRY_VERBS = Object.freeze(['item_propose', ...LOG_VERBS]);
+const MAX_COMMENT = 4000;
+const PREVIEW = 300;
+// How many missing entries one write repairs, beside its own. Only a diff
+// older than REPAIR_AFTER is repaired, so a write running at the same moment
+// on the same item copies its own diff and no other writer copies it too.
+const MAX_REPAIR = 4;
+const REPAIR_AFTER_MS = 120_000;
+const MAX_LIST_ITEMS = 20;
+// Bookkeeping fields and stamps: the entry has its own time, so these are
+// left out of the diff.
+const NOT_LOGGED = new Set(['writer', 'request_id', 'atlas_receipts', 'edits', 'first_title', 'stage_changed_at', 'parked_at', 'resumed_at', 'undropped_at', 'dropped_at']);
+export const itemTag = (id) => `item:${id}`;
+
+// One value as the log keeps it. A text, number, true, false or null up to
+// 300 characters stays whole. A longer text, a list or an object becomes a
+// 300-character preview with cut. The secret filter runs on every value.
+function shown(value) {
+  if (value === undefined) return { value: null, cut: false };
+  if (value === null || typeof value === 'number' || typeof value === 'boolean') return { value, cut: false };
+  const whole = typeof value === 'string' ? value : JSON.stringify(value);
+  // Cut by code point: half an emoji makes Postgres refuse the whole write.
+  const chars = Array.from(scrubSecrets(whole).text);
+  if (typeof value === 'string' && chars.length <= PREVIEW) return { value: chars.join(''), cut: false };
+  return { value: chars.length <= PREVIEW ? chars.join('') : `${chars.slice(0, PREVIEW - 1).join('')}…`, cut: true };
+}
+const same = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+const isList = (value) => Array.isArray(value) || value === undefined || value === null;
+// A list is kept as the members it gained and lost, each shown on its own,
+// so a member at the end of a long list is never cut away.
+function pair(from, to) {
+  if (isList(from) && isList(to) && (Array.isArray(from) || Array.isArray(to))) {
+    const before = from ?? [], after = to ?? [];
+    const gone = before.filter((row) => !after.some((other) => same(row, other)));
+    const come = after.filter((row) => !before.some((other) => same(row, other)));
+    const list = (rows) => rows.slice(0, MAX_LIST_ITEMS).map((row) => shown(row));
+    const added = list(come), removed = list(gone);
+    const cut = come.length > MAX_LIST_ITEMS || gone.length > MAX_LIST_ITEMS || [...added, ...removed].some((row) => row.cut);
+    return { added: added.map((row) => row.value), removed: removed.map((row) => row.value), ...(cut ? { cut: true } : {}) };
+  }
+  const a = shown(from), b = shown(to);
+  return { from: a.value, to: b.value, ...(a.cut || b.cut ? { cut: true } : {}) };
+}
+
+// The diff of one write: each field it changes, as from and to. The title
+// and the tags count as fields.
+export function diffOf(current, next, { title, tags } = {}) {
+  const change = {};
+  for (const [key, value] of Object.entries(next ?? {})) {
+    if (NOT_LOGGED.has(key)) continue;
+    if (!same(current?.fields?.[key], value)) change[key] = pair(current?.fields?.[key], value);
+  }
+  if (title !== undefined && title !== current?.title) change.title = pair(current?.title ?? null, title);
+  if (tags !== undefined && !same(current?.tags ?? [], tags)) change.tags = pair(current?.tags ?? [], tags);
+  return change;
+}
+
+export function createActivityVerbs(core) {
+  const { client, label, now, typeNamed, requireItem, requireOwner, create, alreadyPatched } = core;
+
+  // The entry type, or null before the owner has run setup for 0.7.0.
+  async function entryType() {
+    try { return await typeNamed('entry'); }
+    catch (error) { if (error instanceof VerbError) return null; throw error; }
+  }
+  async function entriesOf(type, itemId) {
+    const rows = await client.listAllEntities({ type: type.name, tag: itemTag(itemId) });
+    return rows.filter((row) => row.fields?.item === itemId);
+  }
+  // The newest entries of an item, one page. An item holds at most 100
+  // receipts, so only its newest entries can match one.
+  async function recentEntries(type, itemId) {
+    if (typeof client.listEntities !== 'function') return entriesOf(type, itemId);
+    const page = await client.listEntities({ type: type.name, tag: itemTag(itemId), order: 'created_at_desc', limit: 200 });
+    return (Array.isArray(page?.entities) ? page.entities : []).filter((row) => row.fields?.item === itemId);
+  }
+  const changeIds = (rows) => new Set(rows.filter((row) => row.fields?.kind === 'change').map((row) => row.fields.request_id));
+  // The request ids that already have a change entry on this item. A failed
+  // read never stops the item write: the trim then goes by size only.
+  async function loggedIds(itemId) {
+    try {
+      const type = await entryType();
+      return type ? changeIds(await recentEntries(type, itemId)) : new Set();
+    } catch { return new Set(); }
+  }
+
+  // Copy the diff of this request into an entry, and repair a few older ones
+  // that never landed. Returns a warning, or null. It never throws: the item
+  // write already landed, so the verb succeeds.
+  async function logEntries(itemId, requestId) {
+    const keep = 'The values stay in the item\'s receipt, and the next write on the item tries again.';
+    try {
+      const type = await entryType();
+      if (!type) return `no log entry was written: the entry type is not registered, so the owner runs setup for manifest 0.7.0. ${keep}`;
+      const item = await client.getEntity(itemId);
+      const receipts = item.fields?.atlas_receipts ?? {};
+      if (!receipts[requestId]?.change) return null;
+      const have = changeIds(await recentEntries(type, item.id));
+      const cutoff = Date.parse(now()) - REPAIR_AFTER_MS;
+      const older = Object.entries(receipts).filter(([id, receipt]) => id !== requestId && receipt?.change && !have.has(id) && Date.parse(receipt.at) < cutoff)
+        .sort(([, a], [, b]) => String(b.at ?? '').localeCompare(String(a.at ?? ''))).slice(0, MAX_REPAIR);
+      const pending = [...(have.has(requestId) ? [] : [[requestId, receipts[requestId]]]), ...older];
+      for (const [id, receipt] of pending) {
+        await create(type, id, receipt.verb, {
+          title: oneLine(`${receipt.verb} · ${item.title ?? item.id}`, 200),
+          fields: { item: item.id, ...(item.fields?.product ? { product: item.fields.product } : {}), kind: 'change', verb: receipt.verb, change: receipt.change, ...(receipt.note ? { text: receipt.note } : {}), at: receipt.at },
+          tags: [itemTag(item.id), ...(item.fields?.product ? [`product:${item.fields.product}`] : [])],
+          readBack: false,
+        });
+      }
+      return null;
+    } catch (error) {
+      return `the log entry was not written: ${error?.message ?? String(error)}. ${keep}`;
+    }
+  }
+
+  const verbs = {
+    // A comment on an item, from the lead or in the owner's words.
+    async item_comment(args, requestId, meta) {
+      const item = await requireItem(args.item_id);
+      const voice = oneOf(args.voice, 'voice', VOICES, 'agent');
+      if (voice === 'owner') requireOwner('item comment in the owner\'s voice');
+      const words = text(args.text, 'text', { max: MAX_COMMENT });
+      const type = await typeNamed('entry');
+      const entries = await entriesOf(type, item.id);
+      const prior = entries.find((row) => row.fields?.request_id === requestId);
+      if (prior && alreadyPatched(prior, requestId, meta)) return { verb: 'item_comment', item_id: item.id, entry_id: prior.id, voice: prior.fields.voice, redactions: prior.fields.redactions ?? 0, ...(prior.fields.corrects ? { corrects: prior.fields.corrects } : {}), replayed_from_graph: true };
+      if (!LIVE_LIFECYCLES.includes(item.fields?.lifecycle)) refuse(`item ${item.id} is ${item.fields?.lifecycle}; only a proposed, active or paused item takes a comment`);
+      let corrects;
+      if (args.corrects !== undefined) {
+        text(args.corrects, 'corrects', { max: 200 });
+        const old = entries.find((row) => row.id === args.corrects && row.fields?.kind === 'comment');
+        if (!old) refuse(`corrects must name a comment on item ${item.id}`);
+        corrects = old.id;
+      }
+      const clean = scrubSecrets(words);
+      const entity = await create(type, requestId, 'item_comment', {
+        digest: meta?.digest, title: oneLine(`comment · ${item.title ?? item.id}`, 200), body: clean.text,
+        fields: { item: item.id, ...(item.fields?.product ? { product: item.fields.product } : {}), kind: 'comment', voice, text: clean.text, ...(corrects ? { corrects } : {}), redactions: clean.redactions, at: now() },
+        tags: [itemTag(item.id), ...(item.fields?.product ? [`product:${item.fields.product}`] : [])],
+      });
+      return { verb: 'item_comment', item_id: item.id, entry_id: entity.id, voice, redactions: clean.redactions, ...(corrects ? { corrects } : {}) };
+    },
+
+    // The feed of one item, newest first: its entries, the receipts that have
+    // no entry yet, and its questions, decisions, delivery marks, pieces and
+    // links.
+    async item_activity(args) {
+      const item = await requireItem(args.item_id);
+      const limit = args.limit === undefined ? 50 : Number(args.limit);
+      if (!Number.isInteger(limit) || limit < 1 || limit > 200) refuse('limit must be a whole number from 1 to 200');
+      const fields = item.fields ?? {};
+      const rows = [];
+      const type = await entryType();
+      const entries = type ? await entriesOf(type, item.id) : [];
+      const logged = new Set();
+      for (const row of entries) {
+        const f = row.fields ?? {};
+        if (f.kind === 'comment') rows.push({ at: f.at, kind: 'comment', entry_id: row.id, voice: f.voice, text: f.text, ...(f.corrects ? { corrects: f.corrects } : {}) });
+        else if (f.kind === 'change') {
+          // Two writers can copy the same diff; the feed shows it once.
+          if (logged.has(f.request_id)) continue;
+          logged.add(f.request_id);
+          rows.push({ at: f.at, kind: 'change', entry_id: row.id, verb: f.verb, change: f.change ?? {}, ...(f.text ? { note: f.text } : {}), values_kept: true });
+        } else rows.push({ at: f.at, kind: 'entry', entry_id: row.id, entry_kind: String(f.kind ?? '') });
+      }
+      for (const [id, receipt] of Object.entries(fields.atlas_receipts ?? {})) {
+        if (logged.has(id) || !receipt?.verb) continue;
+        rows.push(receipt.change
+          ? { at: receipt.at, kind: 'change', verb: receipt.verb, change: receipt.change, ...(receipt.note ? { note: receipt.note } : {}), values_kept: true, from_receipt: true }
+          : { at: receipt.at, kind: 'change', verb: receipt.verb, values_kept: false });
+      }
+      // The history kept on the item before slice 3 stays readable.
+      for (const edit of Array.isArray(fields.edits) ? fields.edits : []) rows.push({ at: edit.at, kind: 'edit', previous: edit.previous ?? {}, ...(edit.reason ? { note: edit.reason } : {}) });
+      const optional = async (name) => { try { return await typeNamed(name); } catch (error) { if (error instanceof VerbError) return null; throw error; } };
+      const listOf = async (name) => { const t = await optional(name); return t ? client.listAllEntities({ type: t.name }) : []; };
+      for (const row of await listOf('question')) {
+        if (row.fields?.item !== item.id) continue;
+        rows.push({ at: row.fields.asked_at, kind: 'question', question_id: row.id, status: row.fields.status, text: oneLine(row.fields.text ?? '', PREVIEW) });
+      }
+      for (const row of await listOf('decision')) {
+        if (!Array.isArray(row.fields?.items) || !row.fields.items.includes(item.id)) continue;
+        // A decision holds a day only; the record's own time places it.
+        rows.push({ at: row.created_at ?? row.fields.date, kind: 'decision', decision_id: row.id, decision_kind: row.fields.kind, text: oneLine(row.fields.text ?? '', PREVIEW) });
+      }
+      for (const row of await listOf('mark')) {
+        if (row.fields?.item !== item.id) continue;
+        rows.push({ at: row.fields.marked_at, kind: 'mark', mark_id: row.id, mark_kind: row.fields.kind, verdict: row.fields.verdict ?? null });
+      }
+      const pieces = await Promise.all((Array.isArray(fields.split_children) ? fields.split_children : []).map((id) => client.getEntity(id).catch(() => null)));
+      for (const piece of pieces) {
+        if (!piece) continue;
+        // The piece's date is the split that made it, not its last write.
+        const made = Object.values(piece.fields?.atlas_receipts ?? {}).filter((receipt) => receipt?.verb === 'item_split').map((receipt) => receipt.at).sort()[0] ?? piece.created_at ?? null;
+        rows.push({ at: made, kind: 'piece', item: piece.id, title: oneLine(piece.title ?? '', 200), split_order: piece.fields?.split_order ?? null });
+      }
+      for (const link of Array.isArray(fields.links) ? fields.links : []) rows.push({ at: link.added_at, kind: 'link', link_kind: link.kind, url: link.url, ...(link.role ? { role: link.role } : {}) });
+      rows.sort((a, b) => String(b.at ?? '').localeCompare(String(a.at ?? '')));
+      const shownRows = rows.slice(0, limit);
+      return { verb: 'item_activity', item_id: item.id, title: item.title, total: rows.length, rows: shownRows, lines: shownRows.map(lineOf),
+        ...(type ? {} : { note: 'the entry type is not registered yet; the owner runs setup for manifest 0.7.0. The feed reads the receipts on the item.' }) };
+    },
+  };
+  return { verbs, logEntries, loggedIds };
+}
+
+// One row as one line, for the lead to show.
+function lineOf(row) {
+  const when = String(row.at ?? '').replace('T', ' ').slice(0, 16) || 'no date';
+  const one = (value) => (value === null || value === undefined ? '—' : typeof value === 'string' ? value : JSON.stringify(value));
+  const values = (change) => Object.entries(change ?? {}).map(([key, value]) => (Array.isArray(value?.added)
+    ? `${key}: ${[...value.added.map((row) => `+${one(row)}`), ...value.removed.map((row) => `−${one(row)}`)].join(', ')}`
+    : `${key}: ${one(value?.from)} → ${one(value?.to)}`)).join('; ');
+  switch (row.kind) {
+    case 'comment': return oneLine(`${when}  comment (${row.voice})  "${row.text}"`);
+    case 'change': return oneLine(row.values_kept ? `${when}  ${row.verb}  ${values(row.change) || 'no field changed'}` : `${when}  ${row.verb}  no values recorded`);
+    case 'edit': return oneLine(`${when}  edit  was ${Object.entries(row.previous ?? {}).map(([key, value]) => `${key}: ${one(value)}`).join('; ')}${row.note ? ` · ${row.note}` : ''}`);
+    case 'entry': return oneLine(`${when}  entry of kind ${row.entry_kind}`);
+    case 'question': return oneLine(`${when}  question (${row.status})  ${row.text}`);
+    case 'decision': return oneLine(`${when}  decision (${row.decision_kind})  "${row.text}"`);
+    case 'mark': return oneLine(`${when}  mark  ${row.mark_kind}${row.verdict ? `: ${row.verdict}` : ''}`);
+    case 'piece': return oneLine(`${when}  piece  ${row.title} · ${row.item}`);
+    case 'link': return oneLine(`${when}  link (${row.link_kind})  ${row.url}`);
+    default: return oneLine(`${when}  ${row.kind}`);
+  }
+}

package/work/lib/questions.mjs

@@ -30,7 +30,10 @@ 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;
+  // Cut by code point, so a cut never leaves half an emoji: Postgres refuses
+  // a lone surrogate, and the whole write with it.
+  const chars = Array.from(flat);
+  return chars.length > max ? `${chars.slice(0, max - 1).join('')}…` : flat;
 };
 
 // R12: a scrub by pattern in receipt keep. The patterns are the ones the

package/work/lib/verbs.mjs

@@ -11,17 +11,19 @@
 // lock block L1, L2 and L3. Every write carries request_id and writer. The
 // server, not the caller, supplies the session. Unknown ids are refused.
 // M2 slice L1 adds the repo kind in 0.5.0, which carries 0.4.0 whole.
-// Stage 1 of the target design adds kinds, a list, in 0.6.0.
-import manifestCurrent from '../manifest-0.6.0.json' with { type: 'json' };
+// Stage 1 of the target design adds kinds, a list, in 0.6.0. The work item
+// additions add entry, the log of an item, in 0.7.0.
+import manifestCurrent from '../manifest-0.7.0.json' with { type: 'json' };
 import { EngramHttpError } from './client.mjs';
 import { VerbError, refuse, canonicalJson, sha256, text, oneOf, origin, url, stringList, LIVE_LIFECYCLES, REPO_KINDS, LIVE_KINDS, repoKinds, kindsFromArgs } from './verb-fields.mjs';
-import { createQuestionVerbs, COSTS, QUESTION_WRITE_VERBS, QUESTION_READ_VERBS } from './questions.mjs';
+import { createQuestionVerbs, COSTS, QUESTION_WRITE_VERBS, QUESTION_READ_VERBS, oneLine, scrubSecrets } from './questions.mjs';
 import { createDeliveryVerbs, DELIVERY_WRITE_VERBS, DELIVERY_READ_VERBS } from './delivery.mjs';
 import { createCapabilityVerbs, CAPABILITY_READ_VERBS, hubOf } from './capability.mjs';
 import { createSweepVerbs, SWEEP_WRITE_VERBS, SWEEP_READ_VERBS } from './sweep.mjs';
+import { createActivityVerbs, diffOf, LOG_VERBS, ENTRY_VERBS, ACTIVITY_WRITE_VERBS, ACTIVITY_READ_VERBS } from './activity.mjs';
 
 export { VerbError, canonicalJson, sha256, COSTS, LIVE_LIFECYCLES, REPO_KINDS, LIVE_KINDS, repoKinds };
-export const MANIFEST_VERSION = '0.6.0';
+export const MANIFEST_VERSION = '0.7.0';
 export const PRODUCT_ID = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
 export const REPO_ID = /^[A-Za-z0-9](?:[A-Za-z0-9_.-]{0,99})\/[A-Za-z0-9_.-]{1,100}$/;
 export const STAGES = Object.freeze(['capture', 'spec', 'build', 'verify', 'learn']);
@@ -33,10 +35,37 @@ export const DRIVERS = Object.freeze(['owner-led', 'agent']);
 export const WAITS_ON = Object.freeze(['owner-decision', 'owner-action', 'gate', 'nothing']);
 // How far the loop check of item_block walks before it stops.
 const MAX_BLOCK_WALK = 200;
-const MAX_EDITS = 20;
+// Work item additions, slice 3. Engram refuses an entity whose fields hold
+// more than 64 KiB of UTF-8 (entity-write-bounds.ts). An item keeps its
+// newest MAX_RECEIPTS receipts. A diff leaves its receipt once its log entry
+// exists. If the whole record is still past FIELDS_LIMIT, the oldest diffs go
+// first, then the oldest receipts. The receipt of this request and the one
+// that made the item are never dropped: a retry needs them.
+const MAX_RECEIPTS = 100;
+const FIELDS_LIMIT = 56 * 1024;
+export function trimReceipts(fields, receipts, logged = new Set(), keep = null) {
+  const pinned = (id, receipt) => id === keep || receipt?.verb === 'item_propose';
+  let rows = Object.entries(receipts ?? {}).sort(([, a], [, b]) => String(a?.at ?? '').localeCompare(String(b?.at ?? '')));
+  while (rows.length > MAX_RECEIPTS) {
+    const index = rows.findIndex(([id, receipt]) => !pinned(id, receipt));
+    if (index < 0) break;
+    rows.splice(index, 1);
+  }
+  const bare = ([id, receipt]) => { const { change, note, ...rest } = receipt ?? {}; return [id, rest]; };
+  rows = rows.map((row) => (row[1]?.change && logged.has(row[0]) ? bare(row) : row));
+  const size = () => Buffer.byteLength(JSON.stringify({ ...fields, atlas_receipts: Object.fromEntries(rows) }));
+  for (let index = 0; index < rows.length && size() > FIELDS_LIMIT; index += 1) {
+    if (rows[index][1]?.change && rows[index][0] !== keep) rows[index] = bare(rows[index]);
+  }
+  for (let index = 0; index < rows.length && size() > FIELDS_LIMIT;) {
+    if (pinned(...rows[index])) index += 1;
+    else rows.splice(index, 1);
+  }
+  return Object.fromEntries(rows);
+}
 // The tags that other verbs own (work item additions, slice 1). item_edit
 // never adds or removes them; item_propose drops them from the caller's list.
-export const OWNED_TAG_PREFIXES = Object.freeze(['product:', 'repo:', 'tier:']);
+export const OWNED_TAG_PREFIXES = Object.freeze(['product:', 'repo:', 'tier:', 'item:']);
 export const OWNED_TAGS = Object.freeze(['atlas-work', 'no-model', 'atlas-registry']);
 // Engram reads no-model with the spaces trimmed and in any case, so the check
 // does the same: No-Model is owned too.
@@ -166,20 +195,32 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
   // recomputes it from the newer record. guard, when given, is checked again on
   // that newer record: a write that another writer made wrong is refused, not
   // forced through (release 0.2.3).
-  async function patch(entity, verb, requestId, fields, { tags, title, digest, guard } = {}) {
+  // An item verb (LOG_VERBS) puts the diff of its write into its own receipt,
+  // in the same write; run() then copies it into a log entry. note is a
+  // reason the log keeps beside the diff (work item additions, slice 3).
+  async function patch(entity, verb, requestId, fields, { tags, title, digest, guard, note, log = LOG_VERBS.includes(verb) } = {}) {
     let current = entity;
+    const logged = log ? await activity.loggedIds(entity.id) : undefined;
     for (let attempt = 0; attempt < 2; attempt += 1) {
       if (attempt > 0 && guard) guard(current);
       const next = typeof fields === 'function' ? fields(current) : fields;
       // A fields function returns null when the newest record already holds
       // the change; then nothing is written.
       if (next === null) return current;
-      const receipts = { ...(current.fields?.atlas_receipts ?? {}), [requestId]: { verb, at: now(), ...(digest ? { digest } : {}) } };
-      const body = { version: current.version, fields: { ...(current.fields ?? {}), ...next, writer: label, request_id: requestId, atlas_receipts: receipts } };
       // tags as a function replaces the list with what it returns, computed
       // from the newest record; a list is added to the tags already there.
-      if (typeof tags === 'function') body.tags = [...new Set(tags(current))];
-      else if (tags) body.tags = [...new Set([...(current.tags ?? []), ...tags])];
+      let nextTags;
+      if (typeof tags === 'function') nextTags = [...new Set(tags(current))];
+      else if (tags) nextTags = [...new Set([...(current.tags ?? []), ...tags])];
+      const change = log ? diffOf(current, next, { title: title || undefined, tags: nextTags }) : null;
+      // A logged write that changes no field is not written: no receipt, no
+      // entry, no new version.
+      if (change && !Object.keys(change).length) return current;
+      const receipt = { verb, at: now(), ...(digest ? { digest } : {}), ...(change ? { change, ...(note ? { note: scrubSecrets(note).text } : {}) } : {}) };
+      const { atlas_receipts: _old, ...rest } = { ...(current.fields ?? {}), ...next, writer: label, request_id: requestId };
+      const receipts = trimReceipts(rest, { ...(current.fields?.atlas_receipts ?? {}), [requestId]: receipt }, logged, requestId);
+      const body = { version: current.version, fields: { ...rest, atlas_receipts: receipts } };
+      if (nextTags) body.tags = nextTags;
       if (title) body.title = title;
       try { await client.updateEntity(current.id, body); return client.getEntity(current.id); }
       catch (error) {
@@ -189,9 +230,9 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
       }
     }
   }
-  async function create(type, requestId, verb, { title, body, fields, tags, digest }) {
-    const receipt = await client.createEntity({ title, ...(body ? { body } : {}), type_id: type.id, fields: { ...fields, writer: label, request_id: requestId, atlas_receipts: { [requestId]: { verb, at: now(), ...(digest ? { digest } : {}) } } }, tags: [...new Set(['atlas-work', 'no-model', ...(tags ?? [])])] });
-    return client.getEntity(receipt.id);
+  async function create(type, requestId, verb, { title, body, fields, tags, digest, change, readBack = true }) {
+    const receipt = await client.createEntity({ title, ...(body ? { body } : {}), type_id: type.id, fields: { ...fields, writer: label, request_id: requestId, atlas_receipts: { [requestId]: { verb, at: now(), ...(digest ? { digest } : {}), ...(change ? { change } : {}) } } }, tags: [...new Set(['atlas-work', 'no-model', ...(tags ?? [])])] });
+    return readBack ? client.getEntity(receipt.id) : receipt;
   }
   async function edge(src, dst, suffix, requestId, props = {}) {
     const intent = await edgeIntent(suffix);
@@ -395,7 +436,7 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
       const type = await typeNamed('container');
       const prior = await landed(type, requestId, meta);
       if (prior) return { verb: 'item_propose', item_id: prior.id, version: prior.version, lifecycle: prior.fields.lifecycle, stage: prior.fields.stage, product: prior.fields.product, repos: prior.fields.repos, replayed_from_graph: true };
-      const entity = await create(type, requestId, 'item_propose', { digest: meta?.digest, title, body: args.body ? text(args.body, 'body') : undefined, fields, tags: [`product:${product.fields.registry_id}`, ...repos.map((id) => `repo:${id}`), `tier:${fields.tier}`, ...(args.tags ? stringList(args.tags, 'tags', { max: 16 }).filter((tag) => !isOwnedTag(tag)) : [])] });
+      const entity = await create(type, requestId, 'item_propose', { change: { created: { from: null, to: scrubSecrets(oneLine(title, 300)).text } }, digest: meta?.digest, title, body: args.body ? text(args.body, 'body') : undefined, fields, tags: [`product:${product.fields.registry_id}`, ...repos.map((id) => `repo:${id}`), `tier:${fields.tier}`, ...(args.tags ? stringList(args.tags, 'tags', { max: 16 }).filter((tag) => !isOwnedTag(tag)) : [])] });
       return { verb: 'item_propose', item_id: entity.id, version: entity.version, lifecycle: 'proposed', stage: 'capture', product: fields.product, repos };
     },
 
@@ -554,7 +595,6 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
       }
       if (args.next_step !== undefined) {
         change.next_step = text(args.next_step, 'next_step', { max: 1000 });
-        previous.next_step = fields.next_step ?? '';
       }
       if (args.waits_on !== undefined) {
         const given = args.waits_on;
@@ -566,7 +606,6 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
         if (given.item !== undefined) refuse('waits_on.item is retired; link the items with item_block');
         if (wait.on !== 'nothing' && !wait.note) refuse(`waits_on.note is required for on: ${wait.on}; say what exactly it waits on`);
         change.waits_on = wait;
-        previous.waits_on = fields.waits_on ?? null;
       }
       const tagsAdd = args.tags_add === undefined ? [] : tagList(args.tags_add, 'tags_add');
       const tagsRemove = args.tags_remove === undefined ? [] : tagList(args.tags_remove, 'tags_remove');
@@ -599,15 +638,14 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
       if (tagEdit && sameList(tagsOf(item), item.tags ?? [])) tagEdit = false;
       if (args.title === undefined && !Object.keys(change).length && !tagEdit && !planGiven) return { verb: 'item_edit', item_id: item.id, version: item.version, title: item.title, next_step: fields.next_step ?? '', waits_on: fields.waits_on ?? null, tags: item.tags ?? [], plan: fields.plan ?? null, changed: [], unchanged: true };
       const reason = text(args.reason, 'reason', { optional: true, max: 1000 });
-      const at = now();
-      // The history keeps the last MAX_EDITS entries. The first title the
-      // owner gave is kept on its own, so a title never falls out of it. The
-      // old tags and dates come from the record the write lands on.
-      const entryOf = (current) => ({ at, by: label.agent, previous: { ...previous, ...(tagEdit ? { tags: current.tags ?? [] } : {}), ...(planGiven ? { plan: current.fields?.plan ?? null } : {}) }, ...(reason ? { reason } : {}) });
+      // Slice 3: the old values go into the diff in the receipt and then into
+      // a log entry, taken from the record the write lands on. edits stops
+      // growing and stays readable. The first title the owner gave is still
+      // kept on its own.
       const entity = await patch(item, 'item_edit', requestId, (current) => ({
-        ...change, ...(planGiven ? { plan: planOf(current) } : {}), edits: [...(Array.isArray(current.fields?.edits) ? current.fields.edits : []), entryOf(current)].slice(-MAX_EDITS),
+        ...change, ...(planGiven ? { plan: planOf(current) } : {}),
         ...(previous.title !== undefined && current.fields?.first_title === undefined ? { first_title: previous.title } : {}),
-      }), { digest: meta?.digest, guard: live, ...(title ? { title } : {}), ...(tagEdit ? { tags: tagsOf } : {}) });
+      }), { digest: meta?.digest, guard: live, note: reason, ...(title ? { title } : {}), ...(tagEdit ? { tags: tagsOf } : {}) });
       return { verb: 'item_edit', item_id: entity.id, version: entity.version, title: entity.title, next_step: entity.fields?.next_step ?? '', waits_on: entity.fields?.waits_on ?? null, tags: entity.tags ?? [], plan: entity.fields?.plan ?? null, changed: [...(args.title !== undefined ? ['title'] : []), ...Object.keys(change), ...(tagEdit ? ['tags'] : []), ...(planGiven ? ['plan'] : [])] };
     },
 
@@ -668,13 +706,11 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
         if (!listOf(current).some((entry) => entry.item === args.blocked_by)) refuse(`item ${current.id} is not blocked by ${args.blocked_by}`);
       };
       guard(item);
-      const at = now();
-      // The removed link goes into the edits, so the history keeps it. It is
-      // taken from the record the write lands on.
+      // The diff keeps the removed link, taken from the record the write
+      // lands on, so the log shows it (slice 3).
       const entity = await patch(item, 'item_unblock', requestId, (current) => ({
         blocked_by: listOf(current).filter((row) => row.item !== args.blocked_by),
-        edits: [...(Array.isArray(current.fields?.edits) ? current.fields.edits : []), { at, by: label.agent, previous: { blocked_by: listOf(current).find((row) => row.item === args.blocked_by) }, ...(reason ? { reason } : {}) }].slice(-MAX_EDITS),
-      }), { digest: meta?.digest, guard });
+      }), { digest: meta?.digest, guard, note: reason });
       return { verb: 'item_unblock', item_id: entity.id, version: entity.version, blocked_by: listOf(entity).map((row) => row.item), removed: args.blocked_by };
     },
 
@@ -715,9 +751,11 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
   Object.assign(verbs, createDeliveryVerbs({ ...core, ownerPresent, readGitHub, readLive }));
   Object.assign(verbs, createCapabilityVerbs({ ...core, readGitHub }));
   Object.assign(verbs, createSweepVerbs({ ...core, requireRepos, inFlight: (args) => verbs.in_flight(args), stages: STAGES, tiers: TIERS, drivers: DRIVERS }));
+  const activity = createActivityVerbs(core);
+  Object.assign(verbs, activity.verbs);
 
-  const WRITE_VERBS = Object.freeze(['setup', 'product_add', 'product_edit', 'repo_add', 'repo_edit', 'item_propose', 'item_lock', 'item_split', 'item_park', 'item_resume', 'item_drop', 'item_edit', 'item_block', 'item_unblock', 'item_stage', 'item_link', ...QUESTION_WRITE_VERBS, ...DELIVERY_WRITE_VERBS, ...SWEEP_WRITE_VERBS]);
-  const READ_VERBS = Object.freeze(['registry_list', ...QUESTION_READ_VERBS, ...DELIVERY_READ_VERBS, ...CAPABILITY_READ_VERBS, ...SWEEP_READ_VERBS]);
+  const WRITE_VERBS = Object.freeze(['setup', 'product_add', 'product_edit', 'repo_add', 'repo_edit', 'item_propose', 'item_lock', 'item_split', 'item_park', 'item_resume', 'item_drop', 'item_edit', 'item_block', 'item_unblock', 'item_stage', 'item_link', ...QUESTION_WRITE_VERBS, ...DELIVERY_WRITE_VERBS, ...SWEEP_WRITE_VERBS, ...ACTIVITY_WRITE_VERBS]);
+  const READ_VERBS = Object.freeze(['registry_list', ...QUESTION_READ_VERBS, ...DELIVERY_READ_VERBS, ...CAPABILITY_READ_VERBS, ...SWEEP_READ_VERBS, ...ACTIVITY_READ_VERBS]);
 
   async function run(verb, args = {}) {
     if (!verbs[verb]) refuse(`unknown verb: ${verb}`);
@@ -744,6 +782,12 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
         await store.put(requestId, { ...record, phase: 'interrupted', error: error.message });
         throw error;
       }
+      // The item write landed. Its diff goes into a log entry now, best
+      // effort: a failure is a warning on the result (slice 3, step 6).
+      if (ENTRY_VERBS.includes(verb) && typeof result?.item_id === 'string') {
+        const warning = await activity.logEntries(result.item_id, requestId);
+        if (warning) result = { ...result, warning };
+      }
       await store.put(requestId, { ...record, phase: 'complete', result, completed_at: now() });
       return { ...copy(result), request_id: requestId, writer: label };
     });