@arjunkhera/atlas 0.0.0 → 0.2.1

package/work/lib/verbs.mjs

@@ -0,0 +1,511 @@
+// Atlas M1 slice L1: the registry and item verbs behind the local MCP door.
+// Slice L2 adds the question, decision and receipt verbs and the "Needs me"
+// view from questions.mjs, through the same door and the same journal.
+// Slice L3 adds the done and reopen verbs and the "In flight" view from
+// delivery.mjs, through the same door again. Slice L4 adds the code-read
+// brief, the six-part answer and the "Built, pending, possible" view from
+// capability.mjs: three read verbs that write nothing. Slice L5 adds the
+// sweep from sweep.mjs: item_adopt, which gives an existing item a product,
+// and sweep_check, which reads the sweep record against the "In flight" view.
+// Design: the Atlas M1 study, pages D1, D2, D3 and D6,
+// 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.
+import manifestCurrent from '../manifest-0.5.0.json' with { type: 'json' };
+import { EngramHttpError } from './client.mjs';
+import { VerbError, refuse, canonicalJson, sha256, text, oneOf, origin, url, stringList } from './verb-fields.mjs';
+import { createQuestionVerbs, COSTS, QUESTION_WRITE_VERBS, QUESTION_READ_VERBS } from './questions.mjs';
+import { createDeliveryVerbs, DELIVERY_WRITE_VERBS, DELIVERY_READ_VERBS } from './delivery.mjs';
+import { createCapabilityVerbs, CAPABILITY_READ_VERBS } from './capability.mjs';
+import { createSweepVerbs, SWEEP_WRITE_VERBS, SWEEP_READ_VERBS } from './sweep.mjs';
+
+export { VerbError, canonicalJson, sha256, COSTS };
+export const MANIFEST_VERSION = '0.5.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']);
+export const TIERS = Object.freeze(['hotfix', 'standard', 'initiative']);
+export const DRIVERS = Object.freeze(['owner-led', 'agent']);
+// The repo kind of M2 amendment A1.5. The repo-shape check reads it to decide
+// which of the seven files a repo needs.
+export const REPO_KINDS = Object.freeze(['service', 'library', 'schema']);
+export const LINK_KINDS = Object.freeze(['pr', 'issue', 'artifact', 'design-doc', 'conversation', 'research', 'slack', 'drive', 'other']);
+export const AUTHORITY_FIELDS = Object.freeze(['writer', 'session', 'actor', 'owner_present', 'agent', 'token_id']);
+const MAX_CHILDREN = 32;
+const copy = (value) => structuredClone(value);
+// The paths of a product the functional check of item_done may read. Absolute
+// paths only, so a caller cannot smuggle a host or a query in.
+const absolutePaths = (value) => stringList(value, 'check_paths', { max: 16 }).map((path) => {
+  text(path, 'check_paths', { max: 500 });
+  if (!path.startsWith('/') || /[?#]/.test(path) || path.includes('..')) refuse('each check_paths entry must be an absolute path with no query and no "..", for example /v1/housekeeping');
+  return path;
+});
+const renderHandle = (value, handle) => JSON.parse(JSON.stringify(value).replaceAll('{{handle}}', handle));
+// Sortable form of a three-part version, for "is the tenant ahead of us?".
+const semver = (value) => String(value).split('.').map((part) => String(Number(part) || 0).padStart(6, '0')).join('.');
+
+export function createVerbs({ client, store, writer, session, agent = 'lead', boundClient = null, ownerPresent = false, readGitHub, readLive, now = () => new Date().toISOString() } = {}) {
+  if (!client) throw new TypeError('client is required');
+  if (!store) throw new TypeError('store (the request journal) is required');
+  if (typeof writer?.token_id !== 'string' || !writer.token_id) throw new TypeError('writer.token_id is required');
+  if (typeof session !== 'string' || !session.trim()) throw new TypeError('session is required; the server supplies it');
+  const label = Object.freeze({ token_id: writer.token_id, session, agent, ...(boundClient ? { client: String(boundClient) } : {}) });
+  let handleCache = null, typesCache = null;
+
+  async function handle() {
+    if (!handleCache) {
+      const publisher = await client.getPublisher();
+      handleCache = publisher?.publisher?.handle;
+      if (!/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(handleCache ?? '')) throw new Error('The tenant has no valid publisher handle.');
+    }
+    return handleCache;
+  }
+  async function types() {
+    if (!typesCache) {
+      const response = await client.listTypes();
+      const rows = Array.isArray(response) ? response : response?.types;
+      typesCache = Array.isArray(rows) ? rows : [];
+    }
+    const byName = new Map(typesCache.map((type) => [type.name, type]));
+    const names = new Map(typesCache.map((type) => [type.id, type.name]));
+    return { byName, names };
+  }
+  async function typeNamed(suffix) {
+    const name = `@${await handle()}/${suffix}`;
+    const { byName } = await types();
+    const type = byName.get(name);
+    if (!type) refuse(`type ${name} is not registered; run setup first`);
+    return type;
+  }
+  async function edgeIntent(suffix) {
+    const { byName } = await types();
+    const scoped = `@${await handle()}/${suffix}`;
+    if (byName.get(scoped)?.kind === 'edge') return scoped;
+    if (byName.get(suffix)?.kind === 'edge') return suffix;
+    refuse(`edge type ${suffix} is not registered; run setup first`);
+  }
+  const kindOf = async (entity) => (await types()).names.get(entity?.type_id)?.split('/').at(-1) ?? null;
+
+  async function registry() {
+    const [product, repo] = await Promise.all([typeNamed('product'), typeNamed('repo')]);
+    const [products, repos] = await Promise.all([
+      client.listAllEntities({ type: product.name, state: 'active' }),
+      client.listAllEntities({ type: repo.name, state: 'active' }),
+    ]);
+    const byId = (rows) => {
+      const map = new Map();
+      for (const row of rows) {
+        const id = row.fields?.registry_id;
+        if (typeof id !== 'string') continue;
+        if (map.has(id)) refuse(`registry id ${id} is ambiguous: two records carry it; reconcile before writing`);
+        map.set(id, row);
+      }
+      return map;
+    };
+    return { products: byId(products), repos: byId(repos) };
+  }
+  async function requireProduct(id, reg) {
+    text(id, 'product', { max: 64 });
+    const record = reg.products.get(id);
+    if (!record) refuse(`unknown product id: ${id}. Known: ${[...reg.products.keys()].sort().join(', ') || 'none'}`);
+    return record;
+  }
+  async function requireRepos(ids, reg, productId) {
+    const list = stringList(ids, 'repos', { max: 16 });
+    if (!list.length) refuse('repos must name at least one registered repo id');
+    for (const id of list) {
+      const record = reg.repos.get(id);
+      if (!record) refuse(`unknown repo id: ${id}. Known: ${[...reg.repos.keys()].sort().join(', ') || 'none'}`);
+      if (productId && record.fields?.product !== productId) refuse(`repo ${id} belongs to product ${record.fields?.product}, not ${productId}`);
+    }
+    return list;
+  }
+  async function requireItem(id) {
+    text(id, 'item_id', { max: 200 });
+    let entity;
+    try { entity = await client.getEntity(id); }
+    catch (error) { if (error instanceof EngramHttpError && error.status === 404) refuse(`unknown item id: ${id}`); throw error; }
+    if ((await kindOf(entity)) !== 'container') refuse(`entity ${id} is not a work item (container)`);
+    if (entity.state && entity.state !== 'active') refuse(`item ${id} is ${entity.state}, not active in the graph`);
+    return entity;
+  }
+  const requireOwner = (verb) => { if (!ownerPresent) refuse(`${verb} needs the owner-present flag on the server host (ATLAS_WORK_OWNER_PRESENT=1)`); };
+
+  async function patch(entity, verb, requestId, fields, { tags, title, digest } = {}) {
+    let current = entity;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      const receipts = { ...(current.fields?.atlas_receipts ?? {}), [requestId]: { verb, at: now(), ...(digest ? { digest } : {}) } };
+      const body = { version: current.version, fields: { ...(current.fields ?? {}), ...fields, writer: label, request_id: requestId, atlas_receipts: receipts } };
+      if (tags) body.tags = [...new Set([...(current.tags ?? []), ...tags])];
+      if (title) body.title = title;
+      try { await client.updateEntity(current.id, body); return client.getEntity(current.id); }
+      catch (error) {
+        if (!(error instanceof EngramHttpError) || error.status !== 409 || attempt === 1) throw error;
+        current = await client.getEntity(current.id);
+        if (current.fields?.atlas_receipts?.[requestId]) return current;
+      }
+    }
+  }
+  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 edge(src, dst, suffix, requestId, props = {}) {
+    const intent = await edgeIntent(suffix);
+    const existing = await client.listAllEdges(src.id, { direction: 'out', intent });
+    const match = existing.find((row) => row.dst === dst.id);
+    if (match) return match;
+    return client.createEdge({ src: src.id, dst: dst.id, intent, props: { ...props, writer: label, request_id: requestId } });
+  }
+  async function findCreated(type, requestId) {
+    const rows = await client.listAllEntities({ type: type.name, state: 'any' });
+    return rows.filter((row) => row.fields?.request_id === requestId || row.fields?.atlas_receipts?.[requestId]);
+  }
+  // Idempotency from the graph, not only the journal: a record stamped with this request id already landed.
+  async function landed(type, requestId, meta) {
+    const rows = await findCreated(type, requestId);
+    if (rows.length > 1) refuse(`request_id ${requestId} is stamped on ${rows.length} records; reconcile before retrying`);
+    if (rows[0]) sameRequest(rows[0].fields?.atlas_receipts?.[requestId], requestId, meta);
+    return rows[0] ?? null;
+  }
+  // A receipt names the verb and the argument digest. The same id for another request is refused, journal or not (review F11).
+  const sameRequest = (receipt, requestId, meta) => {
+    if (!receipt) return false;
+    if (meta && (receipt.verb !== meta.verb || (receipt.digest && receipt.digest !== meta.digest))) refuse(`request_id ${requestId} was already used on this record for a different request (${receipt.verb}); choose a new id`);
+    return true;
+  };
+  const alreadyPatched = (entity, requestId, meta) => sameRequest(entity.fields?.atlas_receipts?.[requestId], requestId, meta);
+
+  const verbs = {
+    async setup(args) {
+      requireOwner('setup');
+      const publisherHandle = await handle();
+      const rendered = renderHandle(manifestCurrent, publisherHandle);
+      if (rendered.name !== 'atlas-work' || rendered.version !== MANIFEST_VERSION) throw new Error(`local manifest must be atlas-work ${MANIFEST_VERSION}`);
+      let published = false;
+      // Registering is the step that can take a field back, and it needs an
+      // enumerable version list to be safe. Without one, setup may still
+      // publish, but it must not register (review H22).
+      let mayRegister = true;
+      try {
+        const artifact = await client.getForgeArtifact(publisherHandle, 'atlas-work');
+        const listed = artifact?.versions ?? artifact?.artifact?.versions;
+        // A guard that cannot read the answer fails closed. If the Forge stops
+        // naming its versions, the verb stops rather than register blind and
+        // take back what a later version added (review H18). The one exception
+        // is an artifact with nothing of ours published yet: there is then no
+        // later version to take back, so the first publish goes through
+        // (review H18's residual).
+        // A 404 on our own version does not prove nothing later exists, so the
+        // fallback never registers. It only lets a first publish through.
+        if (!Array.isArray(listed)) mayRegister = false;
+        const newer = (Array.isArray(listed) ? listed : []).map((row) => String(row?.version ?? '')).filter((version) => semver(version) > semver(MANIFEST_VERSION));
+        // Another lane published a later manifest. Registering this one would
+        // take back the fields that lane added, so the verb stops instead.
+        if (newer.length) refuse(`the tenant already has atlas-work ${newer.sort((a, b) => semver(a).localeCompare(semver(b))).at(-1)}, later than this checkout's ${MANIFEST_VERSION}; registering ${MANIFEST_VERSION} would take back the types that version added. Rebase on the branch that published it.`);
+      }
+      catch (error) {
+        if (error instanceof VerbError) throw error;
+        if (!(error instanceof EngramHttpError) || error.status !== 404) throw error;
+        try { await client.createForgeArtifact({ name: 'atlas-work', kind: rendered.kind, description: rendered.description, categories: ['work'], tags: ['atlas'] }); }
+        catch (createError) { if (!(createError instanceof EngramHttpError) || createError.status !== 409) throw createError; }
+      }
+      try {
+        const stored = await client.getForgeVersion(publisherHandle, 'atlas-work', MANIFEST_VERSION);
+        if (canonicalJson(stored?.manifest) !== canonicalJson(rendered)) refuse(`published atlas-work ${MANIFEST_VERSION} differs from the local manifest; a changed manifest needs a new version`);
+      } catch (error) {
+        if (!(error instanceof EngramHttpError) || error.status !== 404) throw error;
+        await client.publishForgeVersion(publisherHandle, 'atlas-work', { version: MANIFEST_VERSION, manifest: rendered });
+        published = true;
+      }
+      if (!mayRegister) {
+        return { verb: 'setup', manifest: `atlas-work ${MANIFEST_VERSION}`, published, registered: null, types: rendered.contributes.types.map((type) => type.name),
+          note: `the Forge did not list the published versions of atlas-work, so this verb cannot tell whether the tenant is ahead of ${MANIFEST_VERSION}. It published nothing it had to take back, and it registered no type: registering ${MANIFEST_VERSION} could take back what a later version added. Register by hand once the version list reads, or fix the reader.` };
+      }
+      const registered = await client.registerTypes(publisherHandle, 'atlas-work', MANIFEST_VERSION);
+      typesCache = null;
+      return { verb: 'setup', manifest: `atlas-work ${MANIFEST_VERSION}`, published, registered, types: rendered.contributes.types.map((type) => type.name) };
+    },
+
+    async registry_list() {
+      const reg = await registry();
+      const products = [...reg.products.values()].map((row) => ({ registry_id: row.fields.registry_id, name: row.fields.name, entity_id: row.id, project_id: row.fields.project_id ?? null, notes: row.fields.notes ?? '',
+        repos: [...reg.repos.values()].filter((repo) => repo.fields.product === row.fields.registry_id).map((repo) => ({ registry_id: repo.fields.registry_id, entity_id: repo.id, kind: repo.fields.kind ?? null, default_branch: repo.fields.default_branch, notes: repo.fields.notes ?? '' })) }));
+      return { verb: 'registry_list', products, read_at: now() };
+    },
+
+    async product_add(args, requestId, meta) {
+      requireOwner('product add');
+      const registryId = text(args.registry_id, 'registry_id', { max: 64 });
+      if (!PRODUCT_ID.test(registryId)) refuse('registry_id must be a lowercase slug: letters, digits and hyphens, for example "engram"');
+      const name = text(args.name, 'name', { max: 200 });
+      const notes = text(args.notes, 'notes', { optional: true, max: 4000 }) ?? '';
+      // Where the product's deployed app answers. The done verb reads the
+      // health endpoint from this record, never from the caller (D6 R10).
+      const healthUrl = args.health_url === undefined ? '' : url(args.health_url, 'health_url');
+      const checkPaths = args.check_paths === undefined ? [] : absolutePaths(args.check_paths);
+      const reg = await registry();
+      if (reg.products.has(registryId) && !alreadyPatched(reg.products.get(registryId), requestId)) refuse(`product id ${registryId} already exists (entity ${reg.products.get(registryId).id}); use product edit`);
+      let project = null;
+      if (args.project_id !== undefined) {
+        text(args.project_id, 'project_id', { max: 200 });
+        try { project = await client.getEntity(args.project_id); } catch (error) { if (error instanceof EngramHttpError && error.status === 404) refuse(`unknown project entity: ${args.project_id}`); throw error; }
+        if ((await kindOf(project)) !== 'project') refuse(`entity ${args.project_id} is not a project`);
+      }
+      const type = await typeNamed('product');
+      const prior = await landed(type, requestId, meta);
+      if (prior) { if (project) await edge(prior, project, 'references', requestId); return { verb: 'product_add', registry_id: prior.fields.registry_id, entity_id: prior.id, version: prior.version, project_id: prior.fields.project_id ?? null, replayed_from_graph: true }; }
+      const entity = await create(type, requestId, 'product_add', { digest: meta?.digest, title: name, body: `Atlas product record for ${name}. Registry id: ${registryId}.`, fields: { registry_id: registryId, name, notes, ...(healthUrl ? { health_url: healthUrl } : {}), ...(checkPaths.length ? { check_paths: checkPaths } : {}), ...(project ? { project_id: project.id } : {}) }, tags: ['atlas-registry', `product:${registryId}`] });
+      if (project) await edge(entity, project, 'references', requestId);
+      return { verb: 'product_add', registry_id: registryId, entity_id: entity.id, version: entity.version, project_id: project?.id ?? null, health_url: healthUrl || null };
+    },
+
+    async product_edit(args, requestId, meta) {
+      requireOwner('product edit');
+      const registryId = text(args.registry_id, 'registry_id', { max: 64 });
+      const reg = await registry();
+      const record = await requireProduct(registryId, reg);
+      const fields = {};
+      if (args.name !== undefined) fields.name = text(args.name, 'name', { max: 200 });
+      if (args.notes !== undefined) fields.notes = text(args.notes, 'notes', { max: 4000 });
+      if (args.health_url !== undefined) fields.health_url = url(args.health_url, 'health_url');
+      if (args.check_paths !== undefined) fields.check_paths = absolutePaths(args.check_paths);
+      if (args.project_id !== undefined) {
+        let project;
+        try { project = await client.getEntity(text(args.project_id, 'project_id', { max: 200 })); } catch (error) { if (error instanceof EngramHttpError && error.status === 404) refuse(`unknown project entity: ${args.project_id}`); throw error; }
+        if ((await kindOf(project)) !== 'project') refuse(`entity ${args.project_id} is not a project`);
+        fields.project_id = project.id;
+        await edge(record, project, 'references', requestId);
+      }
+      if (alreadyPatched(record, requestId, meta)) return { verb: 'product_edit', registry_id: registryId, entity_id: record.id, version: record.version, changed: [], replayed_from_graph: true };
+      if (!Object.keys(fields).length) refuse('product edit needs at least one of name, notes, health_url, check_paths, project_id; registry_id is immutable');
+      const entity = await patch(record, 'product_edit', requestId, fields, { title: fields.name, digest: meta?.digest });
+      return { verb: 'product_edit', registry_id: registryId, entity_id: entity.id, version: entity.version, changed: Object.keys(fields) };
+    },
+
+    async repo_add(args, requestId, meta) {
+      requireOwner('repo add');
+      if (typeof readGitHub !== 'function') refuse('repo add needs a GitHub reader for the push-rights check');
+      const registryId = text(args.registry_id, 'registry_id', { max: 200 });
+      if (!REPO_ID.test(registryId)) refuse('registry_id must be a GitHub "owner/repo" name');
+      const kind = oneOf(args.kind, 'kind', REPO_KINDS);
+      const notes = text(args.notes, 'notes', { optional: true, max: 4000 }) ?? '';
+      const reg = await registry();
+      const product = await requireProduct(args.product, reg);
+      if (reg.repos.has(registryId) && !alreadyPatched(reg.repos.get(registryId), requestId)) refuse(`repo id ${registryId} already exists (entity ${reg.repos.get(registryId).id}); repo ids are immutable`);
+      let github;
+      try { github = await readGitHub(`repos/${registryId}`); } catch (error) { refuse(`GitHub could not read ${registryId}: ${error?.message ?? 'unknown error'}`); }
+      if (github?.full_name !== registryId) refuse(`GitHub names this repo ${github?.full_name ?? 'nothing'}; use that exact spelling as the registry id`);
+      if (github?.permissions?.push !== true) refuse(`the owner has no push rights on ${registryId}; only repos the owner can push to are registered`);
+      const defaultBranch = text(github.default_branch, 'GitHub default_branch', { max: 200 });
+      const type = await typeNamed('repo');
+      const prior = await landed(type, requestId, meta);
+      if (prior) { await edge(prior, product, 'part_of', requestId); return { verb: 'repo_add', registry_id: prior.fields.registry_id, product: prior.fields.product, kind: prior.fields.kind ?? null, default_branch: prior.fields.default_branch, entity_id: prior.id, version: prior.version, push_rights: true, replayed_from_graph: true }; }
+      const entity = await create(type, requestId, 'repo_add', { digest: meta?.digest, title: registryId, body: `Atlas repo record for ${registryId}, product ${product.fields.registry_id}. Kind: ${kind}. Default branch: ${defaultBranch}.`, fields: { registry_id: registryId, product: product.fields.registry_id, kind, default_branch: defaultBranch, notes, github_url: github.html_url ?? `https://github.com/${registryId}` }, tags: ['atlas-registry', `product:${product.fields.registry_id}`, `repo:${registryId}`] });
+      await edge(entity, product, 'part_of', requestId);
+      return { verb: 'repo_add', registry_id: registryId, product: product.fields.registry_id, kind, default_branch: defaultBranch, entity_id: entity.id, version: entity.version, push_rights: true };
+    },
+
+    async repo_edit(args, requestId, meta) {
+      requireOwner('repo edit');
+      const registryId = text(args.registry_id, 'registry_id', { max: 200 });
+      const reg = await registry();
+      const record = reg.repos.get(registryId);
+      if (!record) refuse(`unknown repo id: ${registryId}`);
+      await requireProduct(record.fields.product, reg);
+      const fields = {};
+      if (args.notes !== undefined) fields.notes = text(args.notes, 'notes', { max: 4000 });
+      if (args.kind !== undefined) fields.kind = oneOf(args.kind, 'kind', REPO_KINDS);
+      if (args.refresh_default_branch === true) {
+        if (typeof readGitHub !== 'function') refuse('refreshing the default branch needs a GitHub reader');
+        const github = await readGitHub(`repos/${registryId}`);
+        if (github?.full_name !== registryId || github?.permissions?.push !== true) refuse(`GitHub no longer reports ${registryId} with push rights`);
+        fields.default_branch = text(github.default_branch, 'GitHub default_branch', { max: 200 });
+      }
+      if (alreadyPatched(record, requestId, meta)) return { verb: 'repo_edit', registry_id: registryId, entity_id: record.id, version: record.version, changed: [], replayed_from_graph: true };
+      if (!Object.keys(fields).length) refuse('repo edit needs kind, notes or refresh_default_branch; registry_id and product are immutable');
+      // The kind is a field, not a tag: repo edit may change it, and a tag cannot be dropped.
+      const entity = await patch(record, 'repo_edit', requestId, fields, { digest: meta?.digest });
+      return { verb: 'repo_edit', registry_id: registryId, entity_id: entity.id, version: entity.version, kind: entity.fields.kind ?? null, changed: Object.keys(fields) };
+    },
+
+    async item_propose(args, requestId, meta) {
+      requireOwner('item propose');
+      const title = text(args.title, 'title', { max: 300 });
+      const reg = await registry();
+      const product = await requireProduct(args.product, reg);
+      const repos = await requireRepos(args.repos, reg, product.fields.registry_id);
+      const fields = {
+        lifecycle: 'proposed', stage: 'capture', product: product.fields.registry_id, repos, tier: oneOf(args.tier, 'tier', TIERS, 'standard'),
+        origin: origin(args.origin), driver: oneOf(args.driver, 'driver', DRIVERS, 'owner-led'), next_step: text(args.next_step, 'next_step', { optional: true, max: 1000 }) ?? '',
+        summary: text(args.summary, 'summary', { optional: true, max: 4000 }) ?? '', external_refs: [], links: [],
+      };
+      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) => !/^(?:product|repo|tier):|^atlas-registry$/.test(tag)) : [])] });
+      return { verb: 'item_propose', item_id: entity.id, version: entity.version, lifecycle: 'proposed', stage: 'capture', product: fields.product, repos };
+    },
+
+    async item_lock(args, requestId, meta) {
+      requireOwner('item lock');
+      const item = await requireItem(args.item_id);
+      const fields = item.fields ?? {};
+      if (alreadyPatched(item, requestId, meta)) return { verb: 'item_lock', item_id: item.id, version: item.version, lifecycle: fields.lifecycle, stage: fields.stage, product: fields.product, repos: fields.repos, scope_hash: fields.scope_hash, locked_at: fields.locked_at, replayed_from_graph: true };
+      if (fields.scope_hash) refuse(`item ${item.id} is already locked (scope ${fields.scope_hash.slice(0, 12)}); split it or propose a new item`);
+      if (!['proposed', 'active'].includes(fields.lifecycle)) refuse(`item ${item.id} is ${fields.lifecycle}; only a proposed or active item can be locked`);
+      const reg = await registry();
+      const product = await requireProduct(args.product, reg);
+      const repos = await requireRepos(args.repos, reg, product.fields.registry_id);
+      if (!args.scope || typeof args.scope !== 'object' || Array.isArray(args.scope)) refuse('scope is required: { text, design_doc?, acceptance_criteria_hash? }');
+      const scope = { text: text(args.scope.text, 'scope.text') };
+      if (args.scope.design_doc !== undefined) scope.design_doc = url(args.scope.design_doc, 'scope.design_doc');
+      if (args.scope.acceptance_criteria_hash !== undefined) {
+        text(args.scope.acceptance_criteria_hash, 'scope.acceptance_criteria_hash', { max: 64 });
+        if (!/^[a-f0-9]{64}$/.test(args.scope.acceptance_criteria_hash)) refuse('scope.acceptance_criteria_hash must be a 64-hex sha256');
+        scope.acceptance_criteria_hash = args.scope.acceptance_criteria_hash;
+      }
+      const scopeHash = scope.acceptance_criteria_hash ?? sha256(scope.text);
+      const stage = oneOf(args.stage, 'stage', STAGES, fields.lifecycle === 'active' && fields.stage ? fields.stage : 'build');
+      const change = {
+        lifecycle: 'active', stage, product: product.fields.registry_id, repos, tier: oneOf(args.tier, 'tier', TIERS, fields.tier ?? 'standard'),
+        scope, scope_hash: scopeHash, origin: origin(args.origin), locked_at: now(),
+        driver: oneOf(args.driver, 'driver', DRIVERS, fields.driver ?? 'owner-led'), next_step: text(args.next_step, 'next_step', { optional: true, max: 1000 }) ?? fields.next_step ?? '',
+        links: Array.isArray(fields.links) ? fields.links : [],
+      };
+      const entity = await patch(item, 'item_lock', requestId, change, { digest: meta?.digest, tags: [`product:${product.fields.registry_id}`, ...repos.map((id) => `repo:${id}`), `tier:${change.tier}`] });
+      return { verb: 'item_lock', item_id: entity.id, version: entity.version, lifecycle: 'active', stage, product: change.product, repos, scope_hash: scopeHash, locked_at: change.locked_at };
+    },
+
+    async item_split(args, requestId, meta) {
+      requireOwner('item split');
+      const parent = await requireItem(args.item_id);
+      const reason = text(args.reason, 'reason', { max: 2000 });
+      if (alreadyPatched(parent, requestId, meta)) return { verb: 'item_split', item_id: parent.id, version: parent.version, reason, children: (parent.fields.split_children ?? []).map((id) => ({ item_id: id })), replayed_from_graph: true };
+      if (!['proposed', 'active'].includes(parent.fields?.lifecycle)) refuse(`item ${parent.id} is ${parent.fields?.lifecycle}; only a proposed or active item can be split`);
+      if (!Array.isArray(args.children) || !args.children.length) refuse('children must list at least one piece: { title, origin?, repos?, tier?, next_step?, driver? }');
+      if (args.children.length > MAX_CHILDREN) refuse(`children holds more than ${MAX_CHILDREN} pieces`);
+      const reg = await registry();
+      const productId = parent.fields?.product;
+      if (!productId) refuse(`item ${parent.id} has no registry product; lock it with product and repos before splitting`);
+      const product = await requireProduct(productId, reg);
+      const type = await typeNamed('container');
+      const specs = args.children.map((child, index) => ({
+        title: text(child?.title, `children[${index}].title`, { max: 300 }),
+        repos: child?.repos === undefined ? stringList(parent.fields.repos ?? [], 'parent repos') : null,
+        givenRepos: child?.repos, tier: oneOf(child?.tier, `children[${index}].tier`, TIERS, parent.fields.tier ?? 'standard'),
+        origin: child?.origin === undefined ? parent.fields.origin : origin(child.origin),
+        driver: oneOf(child?.driver, `children[${index}].driver`, DRIVERS, parent.fields.driver ?? 'owner-led'),
+        next_step: text(child?.next_step, `children[${index}].next_step`, { optional: true, max: 1000 }) ?? '',
+        summary: text(child?.summary, `children[${index}].summary`, { optional: true, max: 4000 }) ?? '',
+      }));
+      for (const spec of specs) {
+        if (spec.givenRepos !== undefined) spec.repos = await requireRepos(spec.givenRepos, reg, product.fields.registry_id);
+        if (!spec.origin) refuse('each child needs an origin in the owner\'s words when the parent has none');
+      }
+      const already = await findCreated(type, requestId);
+      const children = [];
+      for (const [index, spec] of specs.entries()) {
+        const existing = already.find((row) => row.fields?.split_index === index);
+        const child = existing ?? await create(type, requestId, 'item_split', { digest: meta?.digest, title: spec.title, fields: { lifecycle: 'proposed', stage: 'capture', product: product.fields.registry_id, repos: spec.repos, tier: spec.tier, origin: spec.origin, driver: spec.driver, next_step: spec.next_step, summary: spec.summary, external_refs: [], links: [], split_index: index, split_from: parent.id, split_reason: reason }, tags: [`product:${product.fields.registry_id}`, ...spec.repos.map((id) => `repo:${id}`), `tier:${spec.tier}`] });
+        await edge(child, parent, 'spun_out_of', requestId, { reason });
+        children.push({ item_id: child.id, title: spec.title, repos: spec.repos });
+      }
+      const entity = await patch(parent, 'item_split', requestId, { split_children: [...new Set([...(parent.fields.split_children ?? []), ...children.map((child) => child.item_id)])] }, { digest: meta?.digest });
+      return { verb: 'item_split', item_id: entity.id, version: entity.version, reason, children };
+    },
+
+    async item_park(args, requestId, meta) {
+      requireOwner('item park');
+      const item = await requireItem(args.item_id);
+      const reason = text(args.reason, 'reason', { max: 2000 });
+      if (alreadyPatched(item, requestId, meta)) return { verb: 'item_park', item_id: item.id, version: item.version, lifecycle: item.fields.lifecycle, reason, replayed_from_graph: true };
+      if (!['proposed', 'active'].includes(item.fields?.lifecycle)) refuse(`item ${item.id} is ${item.fields?.lifecycle}; only a proposed or active item can be parked`);
+      const entity = await patch(item, 'item_park', requestId, { lifecycle: 'paused', pause_reason: reason, parked_at: now(), parked_from: item.fields.lifecycle }, { digest: meta?.digest });
+      return { verb: 'item_park', item_id: entity.id, version: entity.version, lifecycle: 'paused', reason };
+    },
+
+    async item_resume(args, requestId, meta) {
+      requireOwner('item resume');
+      const item = await requireItem(args.item_id);
+      const reason = text(args.reason, 'reason', { max: 2000 });
+      if (alreadyPatched(item, requestId, meta)) return { verb: 'item_resume', item_id: item.id, version: item.version, lifecycle: item.fields.lifecycle, reason, replayed_from_graph: true };
+      if (item.fields?.lifecycle !== 'paused') refuse(`item ${item.id} is ${item.fields?.lifecycle}; only a paused item can be resumed`);
+      const lifecycle = item.fields.parked_from === 'proposed' ? 'proposed' : 'active';
+      const entity = await patch(item, 'item_resume', requestId, { lifecycle, pause_reason: '', resume_reason: reason, resumed_at: now(), parked_from: null }, { digest: meta?.digest });
+      return { verb: 'item_resume', item_id: entity.id, version: entity.version, lifecycle, reason };
+    },
+
+    async item_stage(args, requestId, meta) {
+      const item = await requireItem(args.item_id);
+      const stage = oneOf(args.stage, 'stage', STAGES);
+      if (alreadyPatched(item, requestId, meta)) return { verb: 'item_stage', item_id: item.id, version: item.version, stage: item.fields.stage, replayed_from_graph: true };
+      if (item.fields?.lifecycle !== 'active') refuse(`item ${item.id} is ${item.fields?.lifecycle}; only an active item moves stage`);
+      if (item.fields.stage === stage) return { verb: 'item_stage', item_id: item.id, version: item.version, stage, unchanged: true };
+      const note = text(args.note, 'note', { optional: true, max: 1000 });
+      const entity = await patch(item, 'item_stage', requestId, { stage, stage_changed_at: now(), ...(note ? { stage_note: note } : {}) }, { digest: meta?.digest });
+      return { verb: 'item_stage', item_id: entity.id, version: entity.version, stage, previous: item.fields.stage };
+    },
+
+    async item_link(args, requestId, meta) {
+      const item = await requireItem(args.item_id);
+      const link = { kind: oneOf(args.kind, 'kind', LINK_KINDS), url: url(args.url, 'url'), role: text(args.role, 'role', { optional: true, max: 200 }) ?? '', note: text(args.note, 'note', { optional: true, max: 1000 }) ?? '', added_at: now(), added_by: label.agent };
+      const links = Array.isArray(item.fields?.links) ? item.fields.links : [];
+      if (alreadyPatched(item, requestId, meta)) return { verb: 'item_link', item_id: item.id, version: item.version, link, links: links.length, replayed_from_graph: true };
+      if (links.some((row) => row.kind === link.kind && row.url === link.url)) return { verb: 'item_link', item_id: item.id, version: item.version, link, unchanged: true };
+      const refs = Array.isArray(item.fields?.external_refs) ? item.fields.external_refs : [];
+      const entity = await patch(item, 'item_link', requestId, { links: [...links, link], external_refs: refs.includes(link.url) ? refs : [...refs, link.url] }, { digest: meta?.digest });
+      return { verb: 'item_link', item_id: entity.id, version: entity.version, link, links: links.length + 1 };
+    },
+  };
+
+  // Slices L2, L3 and L4: the question, decision, receipt, delivery and
+  // reopen verbs and the four views share this door, this journal, this
+  // registry and this writer stamp. The delivery verbs also get the two
+  // read-only readers: GitHub through the gh CLI, and one GET against the
+  // deployed app. Slice L4 adds three read verbs, which write nothing. Slice
+  // L5 adds item_adopt, the one verb that gives an existing item a product,
+  // and sweep_check, which reads the sweep record against the "In flight"
+  // view. The sweep record itself is written by decision_record with kind
+  // "sweep": slice L5 adds no second way to write a decision.
+  const core = { client, label, now, typeNamed, kindOf, registry, requireProduct, requireItem, requireOwner, patch, create, edge, landed, alreadyPatched, findCreated };
+  Object.assign(verbs, createQuestionVerbs(core));
+  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 WRITE_VERBS = Object.freeze(['setup', 'product_add', 'product_edit', 'repo_add', 'repo_edit', 'item_propose', 'item_lock', 'item_split', 'item_park', 'item_resume', '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]);
+
+  async function run(verb, args = {}) {
+    if (!verbs[verb]) refuse(`unknown verb: ${verb}`);
+    if (!args || typeof args !== 'object' || Array.isArray(args)) refuse('arguments must be an object');
+    for (const key of AUTHORITY_FIELDS) if (key in args) refuse(`the request cannot supply ${key}; the server stamps the writer and session`);
+    if (READ_VERBS.includes(verb)) return verbs[verb](args);
+    const requestId = text(args.request_id, 'request_id', { max: 200 });
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(requestId)) refuse('request_id may hold letters, digits, dots, colons, underscores and hyphens');
+    const digest = sha256(canonicalJson({ verb, args, token_id: label.token_id }));
+    return store.withLock(requestId, async () => {
+      const existing = await store.get(requestId);
+      if (existing) {
+        if (existing.digest !== digest) refuse(`request_id ${requestId} was already used for a different request; choose a new id`);
+        if (existing.phase === 'complete') return { ...copy(existing.result), replayed: true };
+        if (existing.phase === 'refused') refuse(`request_id ${requestId} was refused before any write (${existing.error}); fix the request and use a new id`);
+        // prepared or interrupted: run again. Each verb first looks for its own request id in the graph and replays from it.
+      }
+      const record = { request: { requestId, verb, args: copy(args) }, digest, writer: label, phase: 'prepared', at: now(), attempts: (existing?.attempts ?? 0) + 1 };
+      await store.put(requestId, record);
+      let result;
+      try { result = await verbs[verb](args, requestId, { verb, digest }); }
+      catch (error) {
+        if (error instanceof VerbError && record.attempts === 1) { await store.put(requestId, { ...record, phase: 'refused', error: error.message }); throw error; }
+        await store.put(requestId, { ...record, phase: 'interrupted', error: error.message });
+        throw error;
+      }
+      await store.put(requestId, { ...record, phase: 'complete', result, completed_at: now() });
+      return { ...copy(result), request_id: requestId, writer: label };
+    });
+  }
+
+  return Object.freeze({ run, verbs: Object.freeze([...WRITE_VERBS, ...READ_VERBS]), writer: label });
+}