@arjunkhera/atlas 0.0.0 → 0.2.1

package/work/lib/delivery.mjs

@@ -0,0 +1,624 @@
+// Atlas M1 slice L3: delivery, reopen and movement.
+// Design: the Atlas M1 study, D1 (the delivery and
+// reopen marks), D2 (the verbs and the door), D3 (the "In flight" view),
+// D6 findings R1, R2, R9, R10, R14, and the frozen L3 paragraph of the lock
+// block. The verbs run behind the same door, the same journal, the same
+// registry checks and the same writer stamp as slices L1 and L2.
+//
+// Three rules hold this slice together:
+//   1. The done verb runs the three live checks itself, with GET only. The
+//      caller never supplies a merge state, a gate run or a verdict (R10).
+//   2. A reopen never rewrites a delivery. Each mark is its own record; a
+//      reopen points at the delivery it corrects with the corrects edge (R9).
+//   3. Movement is read, never stored. The view computes it at question time
+//      from the marks and from the repos' pull requests (D3 rule 5, R1).
+import { refuse, text, isoDate, url, stringList, sha256 } from './verb-fields.mjs';
+import { oneLine, ROW_LINE_MAX } from './questions.mjs';
+
+export const DELIVERY_WRITE_VERBS = Object.freeze(['item_done', 'item_reopen']);
+export const DELIVERY_READ_VERBS = Object.freeze(['in_flight']);
+
+// A check run that concluded one of these did not pass the gate. GitHub's own
+// vocabulary; neutral, skipped and stale are not failures.
+export const FATAL_CONCLUSIONS = Object.freeze(['failure', 'timed_out', 'action_required', 'cancelled', 'startup_failure']);
+const PASSING_CONCLUSION = 'success';
+
+const MAX_PRS = 32;
+const MAX_REPOS = 16;
+const MAX_ITEMS = 500;
+const PRS_PER_REPO = 100;
+const CHECK_RUNS = 100;
+const UNREGISTERED_SHOWN = 5;
+const UNREGISTERED_KEPT = 25;
+
+// One list line: the tail is what the reader needs, so the title yields to it
+// inside the budget, and the indent goes on afterwards (reviews H10 and H20).
+export function listLine(head, tail, indent = '   ', max = ROW_LINE_MAX) {
+  const end = oneLine(tail, max - indent.length);
+  const budget = max - end.length - indent.length - 3;
+  return budget < 1 ? `${indent}${end}` : `${indent}${oneLine(head, budget)} · ${end}`;
+}
+const DAY = 86_400_000;
+
+const PR_URL = /^https:\/\/github\.com\/([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)\/pull\/(\d+)(?:[/?#].*)?$/;
+// A deploy identity as a health endpoint reports it: "sha-3cceb68", "3cceb68",
+// "git-3cceb68". Anything else is not a commit and is refused.
+const COMMIT = /^(?:sha-|commit-|git-|rev-)?([0-9a-f]{7,40})$/;
+const COMMIT_FIELDS = ['commit', 'sha', 'revision', 'version', 'build', 'git_sha'];
+
+export const parsePullUrl = (value, name) => {
+  const match = PR_URL.exec(text(value, name, { max: 500 }).trim());
+  if (!match) refuse(`${name} must be a GitHub pull request URL, for example https://github.com/owner/repo/pull/12`);
+  return { repo: match[1], number: Number(match[2]), url: `https://github.com/${match[1]}/pull/${match[2]}` };
+};
+
+// The deployed commit, read from the health endpoint's own answer. The caller
+// never supplies it; a health endpoint that names no commit fails the check.
+export function deployedCommitOf(body) {
+  let parsed;
+  try { parsed = JSON.parse(body); } catch { return null; }
+  if (!parsed || typeof parsed !== 'object') return null;
+  for (const key of COMMIT_FIELDS) {
+    const value = parsed[key];
+    if (typeof value !== 'string') continue;
+    const match = COMMIT.exec(value.trim().toLowerCase());
+    if (match) return { commit: match[1], field: key, reported: value };
+  }
+  return null;
+}
+
+// GitHub lists every check run a commit ever had, re-runs included. Only the
+// last run of each name says what the gate concluded.
+export function latestCheckRuns(runs) {
+  const byName = new Map();
+  for (const run of runs ?? []) {
+    const name = typeof run?.name === 'string' ? run.name : '';
+    if (!name) continue;
+    if (!byName.has(name)) byName.set(name, []);
+    byName.get(name).push(run);
+  }
+  const order = (run) => `${String(run.completed_at ?? run.started_at ?? '')}#${String(run.id ?? 0).padStart(24, '0')}`;
+  return [...byName.entries()]
+    .map(([name, list]) => {
+      const sorted = [...list].sort((a, b) => order(a).localeCompare(order(b)));
+      const last = sorted.at(-1);
+      // Every earlier run of this name that concluded fatally. A red run that a
+      // later run superseded is recorded, never dropped: only a later SUCCESS
+      // clears it, and any other later conclusion leaves it standing.
+      const superseded = sorted.slice(0, -1).filter((run) => FATAL_CONCLUSIONS.includes(run.conclusion ?? ''))
+        .map((run) => ({ conclusion: run.conclusion, url: run.html_url ?? '', completed_at: run.completed_at ?? null }));
+      return { name, conclusion: last.conclusion ?? null, status: last.status ?? null, url: last.html_url ?? '', completed_at: last.completed_at ?? null, attempts: sorted.length, ...(superseded.length ? { superseded_failures: superseded } : {}) };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export const daysBetween = (from, to) => {
+  const start = Date.parse(from ?? ''), end = Date.parse(to ?? '');
+  if (Number.isNaN(start) || Number.isNaN(end)) return null;
+  return Math.max(0, Math.floor((end - start) / DAY));
+};
+
+// The legacy seal of the first slice, read as a delivery mark (R14). The seal
+// is never rewritten; the view reads it where it lies.
+export function legacySealOf(item) {
+  const sealed = item.fields?.sealed_at;
+  if (typeof sealed !== 'string' || !sealed) return null;
+  return {
+    mark_id: null, kind: 'delivery', verdict: 'legacy', marked_at: sealed,
+    item: item.id, product: item.fields?.product ?? '', prs: [],
+    source: `legacy seal, verdict ${item.fields?.seal_verdict ?? 'unknown'}`,
+  };
+}
+
+// The marks of each item, oldest first. One read of the mark records serves
+// every item in a view.
+export function marksByItem(rows, itemIds) {
+  const byItem = new Map();
+  for (const row of rows ?? []) {
+    const id = row.fields?.item;
+    if (typeof id !== 'string' || (itemIds && !itemIds.has(id))) continue;
+    if (!byItem.has(id)) byItem.set(id, []);
+    byItem.get(id).push(row);
+  }
+  for (const list of byItem.values()) list.sort((a, b) => String(a.fields.marked_at ?? '').localeCompare(String(b.fields.marked_at ?? '')));
+  return byItem;
+}
+
+// Movement, read at question time and never stored (D3 rule 5). The three
+// helpers below are what the "In flight" view computes movement with. Slice L4
+// calls the same three for part 3 of the six-part answer, so one rule about
+// what counts as movement serves both views.
+
+// Every repo in view, its recent pull requests, read once and shared by every
+// item. A repo GitHub could not read is named; the view still answers from the
+// graph (review H11).
+export async function readPullsByRepo(repoIds, readGitHub, perRepo = PRS_PER_REPO) {
+  const pullsByRepo = new Map(), repoErrors = [];
+  for (const repo of repoIds) {
+    try {
+      const rows = await readGitHub(`repos/${repo}/pulls?state=all&sort=updated&direction=desc&per_page=${perRepo}`);
+      pullsByRepo.set(repo, (Array.isArray(rows) ? rows : []).map((pr) => ({
+        repo, number: pr.number, url: pr.html_url ?? `https://github.com/${repo}/pull/${pr.number}`, title: oneLine(pr.title ?? '', 200),
+        branch: pr.head?.ref ?? '', merged_at: pr.merged_at ?? null, updated_at: pr.updated_at ?? pr.created_at ?? '',
+        state: pr.merged_at ? 'merged' : (pr.state ?? 'open'), names: `${pr.title ?? ''}\n${pr.body ?? ''}\n${pr.head?.ref ?? ''}`,
+      })));
+    } catch (error) { pullsByRepo.set(repo, []); repoErrors.push({ repo, reason: `GitHub did not answer: ${error?.message ?? String(error)}` }); }
+  }
+  return { pullsByRepo, repoErrors };
+}
+
+// A pull request belongs to an item when the item links it (item_link, kind
+// pr) or when its title, body or branch names the item id (R1).
+export function pullsOfItem(item, pullsByRepo, fallbackRepos = []) {
+  const fields = item.fields ?? {};
+  const linked = new Set((Array.isArray(fields.links) ? fields.links : []).filter((link) => link?.kind === 'pr').map((link) => link.url));
+  const mine = [];
+  for (const repo of (Array.isArray(fields.repos) ? fields.repos : fallbackRepos)) {
+    for (const pull of pullsByRepo.get(repo) ?? []) {
+      const how = linked.has(pull.url) ? 'link' : (pull.names.includes(item.id) ? 'names the item id' : null);
+      if (how) mine.push({ ...pull, names: undefined, matched_by: how });
+    }
+  }
+  return mine;
+}
+
+// The last thing that moved on an item: its own dates, its marks, its legacy
+// seal and its pull requests, newest first.
+export function movementOf({ item, marks = [], pulls = [], legacy = null, readAt }) {
+  const fields = item.fields ?? {};
+  const moments = [
+    { at: fields.locked_at, source: 'locked' }, { at: fields.stage_changed_at, source: `stage ${fields.stage ?? ''}` },
+    { at: fields.resumed_at, source: 'resumed' }, { at: fields.parked_at, source: 'parked' },
+    { at: fields.delivered_at, source: 'delivered' }, { at: fields.reopened_at, source: 'reopened' },
+    ...marks.map((mark) => ({ at: mark.fields?.marked_at, source: `${mark.fields?.kind} mark` })),
+    ...(legacy ? [{ at: legacy.marked_at, source: 'legacy seal' }] : []),
+    ...pulls.map((pull) => ({ at: pull.merged_at ?? pull.updated_at, source: `${pull.state} #${pull.number}` })),
+    { at: item.updated_at, source: 'record' }, { at: item.created_at, source: 'created' },
+  ].filter((moment) => typeof moment.at === 'string' && moment.at && !Number.isNaN(Date.parse(moment.at)));
+  moments.sort((a, b) => String(b.at).localeCompare(String(a.at)));
+  const last = moments[0] ?? null;
+  return { last, days: last ? daysBetween(last.at, readAt) : null, moments };
+}
+
+// A reopen corrects the delivery it names. The first reopen of a delivery is
+// the correction; a later one is refused by the verb, so an older record with
+// two is read this way too (review H7).
+export function correctionsOf(marks = []) {
+  const correctedBy = new Map();
+  for (const mark of marks) {
+    const corrects = mark.fields?.corrects;
+    if (mark.fields?.kind === 'reopen' && typeof corrects === 'string' && !correctedBy.has(corrects)) correctedBy.set(corrects, mark.id);
+  }
+  return correctedBy;
+}
+
+export function createDeliveryVerbs(core) {
+  const { client, label, now, typeNamed, registry, requireProduct, requireItem, ownerPresent, patch, create, edge, landed, alreadyPatched, readGitHub, readLive } = core;
+
+  const github = async (path) => {
+    if (typeof readGitHub !== 'function') refuse('this verb needs a GitHub reader; the server supplies one');
+    try { return await readGitHub(path); }
+    catch (error) { refuse(`GitHub could not read ${path}: ${error?.message ?? 'unknown error'}`); }
+  };
+  const live = async (target, name) => {
+    if (typeof readLive !== 'function') refuse('this verb needs a live reader; the server supplies one');
+    try { return await readLive(target); }
+    catch (error) { refuse(`${name} did not answer: ${error?.message ?? 'unknown error'}`); }
+  };
+  // The reopen door (R9). The owner-present flag, or the lead in this session.
+  const requireOwnerOrLead = (verb) => { if (!ownerPresent && label.agent !== 'lead') refuse(`${verb} is for the owner or the lead in session; this session is agent "${label.agent}"`); };
+
+  const markOf = async (id, itemId) => {
+    const type = await typeNamed('mark');
+    let entity;
+    try { entity = await client.getEntity(id); }
+    catch (error) { if (error?.status === 404) refuse(`unknown mark id: ${id}`); throw error; }
+    if (entity.type_id !== type.id) refuse(`entity ${id} is not a delivery or reopen mark`);
+    if (itemId && entity.fields?.item !== itemId) refuse(`mark ${id} belongs to item ${entity.fields?.item}, not ${itemId}`);
+    return entity;
+  };
+
+  async function marksOf(itemIds) {
+    const type = await typeNamed('mark');
+    return marksByItem(await client.listAllEntities({ type: type.name, state: 'active' }), itemIds);
+  }
+
+  // ---------------------------------------------------------------------
+  // The three live checks. Every one is a GET. They all run before any write,
+  // so a failed check leaves nothing behind.
+  // ---------------------------------------------------------------------
+  function functionalSpec(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) refuse('functional is required: { url, contains, status? }. The verb GETs that URL and checks the answer.');
+    for (const key of ['method', 'body', 'headers', 'data', 'json']) if (key in value) refuse(`functional.${key} is not accepted; the live checks are GET only and send no body`);
+    const target = url(value.url, 'functional.url');
+    // A check that asserts nothing is not a check. It must say what the answer
+    // has to carry, or the verb would pass on any 200.
+    if (value.contains === undefined) refuse('functional.contains is required: name at least one string the answer must carry, so the check says something about the change');
+    const contains = stringList(value.contains, 'functional.contains', { max: 16 }).map((entry) => text(entry, 'functional.contains', { max: 500 }));
+    if (!contains.length) refuse('functional.contains must name at least one string the answer must carry');
+    let status = 200;
+    if (value.status !== undefined) {
+      // A delivery is proven by an answer, not by an error. 404 is not a pass.
+      if (!Number.isInteger(value.status) || value.status < 200 || value.status > 299) refuse('functional.status must be a 2xx status; a delivery is proven by an answer, not by an error');
+      status = value.status;
+    }
+    return { url: target, contains, status };
+  }
+
+  // Where the functional check may go. The owner writes check_paths on the
+  // product; without it the verb may read only the health endpoint's own path.
+  // The check runs with the Engram credential, so an open origin would let any
+  // in-session agent read any path and learn from the refusal what it holds.
+  function allowedPath(spec, product, healthUrl) {
+    const health = new URL(healthUrl);
+    const target = new URL(spec.url);
+    if (target.origin !== health.origin) refuse(`functional.url must be on the same origin as the product's health endpoint (${health.origin}); the check runs against the deployed app, not another host`);
+    const allowed = Array.isArray(product.fields?.check_paths) ? product.fields.check_paths.filter((path) => typeof path === 'string' && path.startsWith('/')) : [];
+    const paths = allowed.length ? allowed : [health.pathname];
+    const under = (prefix) => target.pathname === prefix || target.pathname.startsWith(prefix.endsWith('/') ? prefix : `${prefix}/`);
+    if (!paths.some(under)) refuse(`functional.url path ${target.pathname} is not one the owner opened for checks on product ${product.fields.registry_id}. Allowed: ${paths.join(', ')}. The owner adds a path with product edit, check_paths.`);
+    // The path alone decides. An earlier draft compared the query too, so
+    // /healthz?probe=1 passed as a functional check (review H15).
+    if (target.pathname === health.pathname) refuse('functional.url must not be the health endpoint itself; the functional check is scoped to the change, and the health endpoint is check two');
+  }
+
+  async function checkHealth(healthUrl) {
+    const answer = await live(healthUrl, 'the health endpoint');
+    const ok = answer.status >= 200 && answer.status < 300;
+    const found = ok ? deployedCommitOf(answer.body) : null;
+    return {
+      name: 'health-endpoint-answers', result: ok && found ? 'pass' : 'fail', url: healthUrl, status: answer.status,
+      ...(found ? { deployed_commit: found.commit, reported: found.reported, field: found.field } : {}),
+      detail: !ok ? `the health endpoint answered ${answer.status}` : (found ? `${healthUrl} answered ${answer.status}; deployed commit ${found.commit}` : 'the health endpoint answered, but named no commit in commit, sha, revision, version, build or git_sha'),
+      checked_at: now(),
+    };
+  }
+
+  async function checkContains(pulls, deployed) {
+    const detail = [];
+    let result = 'pass';
+    for (const pull of pulls) {
+      const compare = await github(`repos/${pull.repo}/compare/${pull.merge_commit_sha}...${deployed}`);
+      const status = compare?.status ?? 'unknown';
+      const contains = status === 'identical' || status === 'ahead';
+      if (!contains) result = 'fail';
+      detail.push({ pr: pull.url, merge_commit_sha: pull.merge_commit_sha, deployed, compare: status, behind_by: compare?.behind_by ?? null, contains });
+    }
+    return { name: 'deployed-commit-contains-the-prs', result, deployed_commit: deployed, prs: detail, checked_at: now(),
+      detail: result === 'pass' ? `the deployed commit ${deployed} carries all ${pulls.length} merged pull request${pulls.length === 1 ? '' : 's'}` : `the deployed commit ${deployed} does not carry ${detail.filter((row) => !row.contains).map((row) => row.pr).join(', ')}` };
+  }
+
+  async function checkFunctional(spec, healthUrl) {
+    const answer = await live(spec.url, 'the functional check');
+    const body = String(answer.body ?? '');
+    const missing = spec.contains.filter((needle) => !body.includes(needle));
+    const statusOk = answer.status === spec.status;
+    const result = statusOk && !missing.length ? 'pass' : 'fail';
+    return {
+      name: 'read-only-functional-check', result, url: spec.url, method: 'GET', status: answer.status, expected_status: spec.status,
+      // The answer itself never enters the graph: a digest, its size, and which
+      // strings the caller asked for were found.
+      body_sha256: sha256(body), body_bytes: Buffer.byteLength(body), contains: spec.contains, missing,
+      detail: result === 'pass' ? `GET ${spec.url} answered ${answer.status}${spec.contains.length ? ` and carried ${spec.contains.length} expected string${spec.contains.length === 1 ? '' : 's'}` : ''}` : (!statusOk ? `GET ${spec.url} answered ${answer.status}, not ${spec.status}` : `GET ${spec.url} did not carry: ${missing.join(', ')}`),
+      checked_at: now(),
+    };
+  }
+
+  const verbs = {
+    // The delivering agent marks its own change done, after the verb runs the
+    // three live checks itself. No owner flag: the agent that shipped it calls
+    // this, and the lead catches up a delivery made outside a session (R2).
+    async item_done(args, requestId, meta) {
+      const item = await requireItem(args.item_id);
+      const fields = item.fields ?? {};
+      const replay = alreadyPatched(item, requestId, meta);
+      if (!replay && fields.lifecycle !== 'active') refuse(`item ${item.id} is ${fields.lifecycle}; only an active item is marked done`);
+      const reg = await registry();
+      const product = await requireProduct(fields.product, reg);
+      // A retry of an interrupted write finishes what landed, and it is read
+      // FIRST, before any refusal that depends on registry state. A repo kind
+      // edited between two attempts would otherwise send the retry down the
+      // strict path, refuse it for a missing health endpoint, and strand the
+      // mark this same request already wrote (architect review, finding 8).
+      // It runs no check again: the checks proved THIS delivery when the mark
+      // was written, and a check that has since gone red would otherwise
+      // strand a mark the item never points at (reviews G1 and G2 of Batch 11,
+      // finding H5 of Batch 13).
+      const type = await typeNamed('mark');
+      const standing = await landed(type, requestId, meta);
+      if (standing) {
+        await edge(standing, item, 'references', requestId);
+        const held = Array.isArray(fields.delivery_marks) ? fields.delivery_marks : [];
+        const finished = held.includes(standing.id) ? item : await patch(item, 'item_done', requestId, {
+          lifecycle: 'done', delivery_state: 'delivered', delivered_at: standing.fields.marked_at, delivery_marks: [...held, standing.id],
+        }, { digest: meta?.digest });
+        return { verb: 'item_done', item_id: finished.id, version: finished.version, lifecycle: finished.fields.lifecycle, mark_id: standing.id,
+          delivered_at: standing.fields.marked_at, prs: (standing.fields.prs ?? []).map((pull) => pull.url), deployed_commit: standing.fields.deployed?.commit ?? null,
+          checks: (standing.fields.checks ?? []).map((check) => ({ name: check.name, result: check.result, detail: check.detail })),
+          verified_by: (standing.fields.verified_by ?? []).map((row) => ({ pr: row.pr, passed: row.passed })), gate_warnings: standing.fields.gate_warnings ?? [],
+          replayed_from_graph: true };
+      }
+
+      // F4, ordered by the owner: what proves a delivery follows the repo,
+      // not one product's shape. Amendment A1.7.
+      //
+      // Only a `library` is relaxed. A library's merge IS its delivery: there
+      // is nothing after it. A `schema` repo is the opposite: this system's
+      // own release procedure applies a migration to the node AFTER the merge,
+      // so a merge-proved "delivered" would be false about production. A
+      // `schema` repo therefore stays on the strict path with `service`
+      // (architect review of this batch, finding 1).
+      //
+      // The strict path is also the default: an item with no registered repo,
+      // or a repo whose kind was never set, keeps the three checks. Nothing
+      // weakens by omission, and a mixed-kind item takes the strict path
+      // because one of its repos demands it.
+      const named = (Array.isArray(fields.repos) ? fields.repos : []).map((id) => reg.repos.get(id)).filter(Boolean);
+      const unset = named.filter((repo) => !repo.fields?.kind).map((repo) => repo.fields.registry_id);
+      const strictKinds = named.filter((repo) => repo.fields?.kind && repo.fields.kind !== 'library').map((repo) => `${repo.fields.registry_id} is a ${repo.fields.kind}`);
+      const live = !named.length || unset.length > 0 || strictKinds.length > 0;
+      const healthUrl = text(product.fields?.health_url, `product ${product.fields.registry_id} health_url`, { optional: true, max: 2000 });
+      if (live && !healthUrl) {
+        const why = !named.length ? 'the item names no registered repo' : (unset.length ? `repo ${unset.join(', ')} carries no kind` : `${strictKinds.join(', ')}`);
+        refuse(`product ${product.fields.registry_id} has no health_url, and the live checks apply because ${why}; the owner sets it with product edit, or sets the repo kind to library, which is the one kind whose merge is its delivery`);
+      }
+      // Which pull requests deliver this item. The caller names them, always.
+      // An earlier draft fell back to the item's own pr links, and the first
+      // live run marked the wrong item done: that item's one pr link was the
+      // pull request that LOCKED its design, with role "lock". A link says a
+      // pull request belongs to the item; it does not say the item shipped.
+      // The delivering agent knows what it delivered, so it says so.
+      if (args.prs === undefined) refuse('prs is required: name the merged pull requests this delivery shipped. The item\'s pr links are not read, because a link can be a design or a lock, not a delivery.');
+      const given = stringList(args.prs, 'prs', { max: MAX_PRS });
+      if (!given.length) refuse('prs must name at least one merged pull request');
+      let spec = null;
+      if (live) { spec = functionalSpec(args.functional); allowedPath(spec, product, healthUrl); }
+      else if (args.functional !== undefined) refuse(`functional is not accepted for this delivery: ${named.map((repo) => `${repo.fields.registry_id} is a ${repo.fields.kind}`).join(', ')}, so there is no deployed page to read. The merge and the gate prove it.`);
+      const note = text(args.note, 'note', { optional: true, max: 2000 }) ?? '';
+
+      const repos = new Set(Array.isArray(fields.repos) ? fields.repos : []);
+      const pulls = [];
+      for (const entry of given) {
+        const parsed = parsePullUrl(entry, 'prs');
+        if (!reg.repos.has(parsed.repo)) refuse(`pull request ${parsed.url} is in ${parsed.repo}, which is not a registered repo`);
+        if (repos.size && !repos.has(parsed.repo)) refuse(`pull request ${parsed.url} is in ${parsed.repo}, which is not one of the item's repos (${[...repos].join(', ')})`);
+        // The merge state comes from GitHub, never from the caller (R10).
+        const pr = await github(`repos/${parsed.repo}/pulls/${parsed.number}`);
+        if (pr?.merged !== true) refuse(`pull request ${parsed.url} is not merged on GitHub; a delivery is marked after the merge`);
+        const mergeCommit = text(pr.merge_commit_sha, `merge_commit_sha of ${parsed.url}`, { max: 64 });
+        pulls.push({ ...parsed, title: oneLine(pr.title ?? '', 200), merged_at: pr.merged_at ?? '', merge_commit_sha: mergeCommit, branch: pr.head?.ref ?? '', base: pr.base?.ref ?? '' });
+      }
+
+      // The three live checks, for a delivery that reaches a running service.
+      let health = null, contains = null, functional = null;
+      if (live) {
+        // Check one: the health endpoint answers, and says which commit is live.
+        health = await checkHealth(healthUrl);
+        if (health.result !== 'pass') refuse(`the live check failed: ${health.detail}`);
+        // Check two: that commit carries every pull request.
+        contains = await checkContains(pulls, health.deployed_commit);
+        if (contains.result !== 'pass') refuse(`the live check failed: ${contains.detail}`);
+        // Check three: a read-only functional check scoped to the change.
+        functional = await checkFunctional(spec, healthUrl);
+        if (functional.result !== 'pass') refuse(`the live check failed: ${functional.detail}`);
+      }
+
+      // The gate run, fetched from GitHub for each merge commit (R10).
+      const verified = [], warnings = [];
+      for (const pull of pulls) {
+        const answer = await github(`repos/${pull.repo}/commits/${pull.merge_commit_sha}/check-runs?per_page=${CHECK_RUNS}`);
+        const runs = latestCheckRuns(answer?.check_runs);
+        const failed = runs.filter((run) => FATAL_CONCLUSIONS.includes(run.conclusion ?? ''));
+        const passed = runs.filter((run) => run.conclusion === PASSING_CONCLUSION);
+        if (failed.length) refuse(`the merge gate is red for ${pull.url}: ${failed.map((run) => `${run.name} ${run.conclusion} (${run.url})`).join(', ')}`);
+        if (!passed.length) refuse(`no check run succeeded for ${pull.url}; the merge gate is the independent record and it says nothing`);
+        // A check name whose LATEST run succeeded is green. A name whose earlier
+        // run was red and whose later run was skipped or neutral is not red and
+        // not green: the verb cannot tell a re-run that fixed it from a gate
+        // that was switched off. It does not guess. It marks the delivery and
+        // writes the warning on the mark, where the owner reads it and can
+        // reopen. The lock text does not set a gate policy; this is the lead's
+        // rule for M1, and it is recorded, never silent.
+        for (const run of runs) {
+          if (!run.superseded_failures || run.conclusion === PASSING_CONCLUSION) continue;
+          const last = run.superseded_failures.at(-1);
+          warnings.push({ pr: pull.url, check: run.name, earlier: last.conclusion, earlier_url: last.url, latest: run.conclusion, latest_url: run.url,
+            detail: `${run.name} concluded ${last.conclusion} for ${pull.url}, and its later run concluded ${run.conclusion}, not success. The verb cannot tell a fixed gate from a gate that was switched off.` });
+        }
+        verified.push({ pr: pull.url, commit: pull.merge_commit_sha, runs, passed: passed.map((run) => run.name) });
+      }
+
+      // One row per check that ran. For a repo with no deploy target the row
+      // says what was proven instead: every named pull request is merged, and
+      // the gate below is green. The merge commits are on the mark's prs.
+      const checks = live ? [contains, health, functional] : [{
+        name: 'every named pull request is merged',
+        result: 'pass',
+        detail: `${pulls.length} pull request${pulls.length === 1 ? '' : 's'} merged on GitHub: ${pulls.map((pull) => `${pull.url} at ${pull.merge_commit_sha.slice(0, 7)}`).join(', ')}. No live check ran: ${named.map((repo) => `${repo.fields.registry_id} is a ${repo.fields.kind}`).join(', ')}, so the product has no deployed endpoint to read (amendment A1.7).`,
+        checked_at: now(),
+      }];
+      const mark = await create(type, requestId, 'item_done', {
+        digest: meta?.digest,
+        title: oneLine(`Delivered · ${item.title} · ${pulls.map((pull) => `#${pull.number}`).join(' ')}`, 200),
+        body: checks.map((check) => `${check.name}: ${check.result} — ${check.detail}`).join('\n'),
+        fields: {
+          kind: 'delivery', verdict: 'delivered', item: item.id, product: product.fields.registry_id, marked_at: now(),
+          prs: pulls.map((pull) => ({ url: pull.url, repo: pull.repo, number: pull.number, title: pull.title, branch: pull.branch, merged_at: pull.merged_at, merge_commit_sha: pull.merge_commit_sha })),
+          ...(live ? { deployed: { health_url: healthUrl, commit: health.deployed_commit, reported: health.reported, status: health.status, checked_at: health.checked_at } } : {}),
+          checks, verified_by: verified, ...(warnings.length ? { gate_warnings: warnings } : {}), ...(note ? { note } : {}),
+        },
+        tags: ['atlas-mark', `product:${product.fields.registry_id}`, ...pulls.map((pull) => `repo:${pull.repo}`)],
+      });
+      await edge(mark, item, 'references', requestId);
+      const marks = Array.isArray(fields.delivery_marks) ? fields.delivery_marks : [];
+      const patched = replay ? item : await patch(item, 'item_done', requestId, {
+        lifecycle: 'done', delivery_state: 'delivered', delivered_at: mark.fields.marked_at,
+        delivery_marks: marks.includes(mark.id) ? marks : [...marks, mark.id],
+      }, { digest: meta?.digest });
+      return {
+        verb: 'item_done', item_id: patched.id, version: patched.version, lifecycle: patched.fields.lifecycle, mark_id: mark.id,
+        delivered_at: mark.fields.marked_at, prs: pulls.map((pull) => pull.url), deployed_commit: health?.deployed_commit ?? null,
+        proof: live ? 'live-checks' : 'merge-and-gate',
+        checks: checks.map((check) => ({ name: check.name, result: check.result, detail: check.detail })),
+        verified_by: verified.map((row) => ({ pr: row.pr, passed: row.passed })), gate_warnings: warnings,
+        ...(replay ? { replayed_from_graph: true } : {}),
+      };
+    },
+
+    // Reopen: the owner or the lead in session, with a reason and the failed
+    // check as a URL. It appends a mark that corrects the delivery. The
+    // delivery mark is never touched (R9).
+    async item_reopen(args, requestId, meta) {
+      requireOwnerOrLead('item reopen');
+      const item = await requireItem(args.item_id);
+      const fields = item.fields ?? {};
+      const reason = text(args.reason, 'reason', { max: 4000 });
+      const failedCheck = url(args.failed_check, 'failed_check');
+      if (alreadyPatched(item, requestId, meta)) return { verb: 'item_reopen', item_id: item.id, version: item.version, lifecycle: fields.lifecycle, delivery_state: fields.delivery_state ?? null, reason, replayed_from_graph: true };
+      const marks = Array.isArray(fields.delivery_marks) ? fields.delivery_marks : [];
+      if (!marks.length) refuse(`item ${item.id} carries no delivery mark; there is nothing to reopen`);
+      // One reopen per delivery. A delivery that is already corrected cannot be
+      // corrected again: the second live run of Batch 12 stacked two reopens on
+      // one delivery because the default kept choosing the same mark.
+      const held = [];
+      for (const id of marks) held.push(await markOf(id, item.id));
+      const alreadyCorrected = new Map();
+      for (const mark of held) if (mark.fields?.kind === 'reopen' && typeof mark.fields.corrects === 'string' && !alreadyCorrected.has(mark.fields.corrects)) alreadyCorrected.set(mark.fields.corrects, mark.id);
+      let corrected;
+      if (args.corrects !== undefined) corrected = await markOf(text(args.corrects, 'corrects', { max: 200 }), item.id);
+      else corrected = [...held].reverse().find((mark) => mark.fields?.kind === 'delivery' && !alreadyCorrected.has(mark.id));
+      if (!corrected) refuse(`item ${item.id} has no standing delivery mark to correct; every delivery on it is already corrected`);
+      if (corrected.fields?.kind !== 'delivery') refuse(`mark ${corrected.id} is a ${corrected.fields?.kind} mark; a reopen corrects a delivery mark`);
+      if (alreadyCorrected.has(corrected.id)) refuse(`delivery mark ${corrected.id} is already corrected by ${alreadyCorrected.get(corrected.id)}; mark the item done again before reopening it again`);
+      const type = await typeNamed('mark');
+      const prior = await landed(type, requestId, meta);
+      const mark = prior ?? await create(type, requestId, 'item_reopen', {
+        digest: meta?.digest, title: oneLine(`Reopened · ${item.title}`, 200), body: `${reason}\n\nFailed check: ${failedCheck}\nCorrects delivery mark ${corrected.id}.`,
+        fields: {
+          kind: 'reopen', verdict: 'reopened', item: item.id, product: fields.product ?? '', marked_at: now(),
+          reason, failed_check: failedCheck, corrects: corrected.id,
+        },
+        tags: ['atlas-mark', ...(fields.product ? [`product:${fields.product}`] : [])],
+      });
+      // The corrects edge of 0.2.0, from the reopen to the delivery it corrects.
+      await edge(mark, corrected, 'corrects', requestId);
+      await edge(mark, item, 'references', requestId);
+      const patched = await patch(item, 'item_reopen', requestId, {
+        lifecycle: 'active', delivery_state: 'reopened', reopened_at: mark.fields.marked_at,
+        delivery_marks: marks.includes(mark.id) ? marks : [...marks, mark.id],
+      }, { digest: meta?.digest });
+      return { verb: 'item_reopen', item_id: patched.id, version: patched.version, lifecycle: 'active', delivery_state: 'reopened', mark_id: mark.id, corrects: corrected.id, failed_check: failedCheck, reason, ...(prior ? { replayed_from_graph: true } : {}) };
+    },
+
+    // D3: the "In flight" view. Computed at question time, per product, never
+    // stored. Movement comes from the marks and from the repos' pull requests.
+    async in_flight(args = {}) {
+      const reg = await registry();
+      let only = null;
+      if (args.product !== undefined) only = (await requireProduct(args.product, reg)).fields.registry_id;
+      const since = args.since === undefined ? null : isoDate(args.since, 'since');
+      const container = await typeNamed('container');
+      const all = await client.listAllEntities({ type: container.name, state: 'active' });
+      const registered = (row) => typeof row.fields?.product === 'string' && reg.products.has(row.fields.product);
+      const items = all.filter((row) => registered(row) && (!only || row.fields.product === only));
+      // D3 rule 2: a row names its product. An item with no registered product
+      // cannot be a row, so it is named here instead of dropped in silence.
+      // Slice L5's sweep is what gives these items a product.
+      const unnamed = all.filter((row) => !registered(row)).map((row) => ({
+        item: row.id, title: oneLine(row.title, 120), lifecycle: row.fields?.lifecycle ?? 'unknown',
+        ...(row.fields?.sealed_at ? { legacy_seal: { sealed_at: row.fields.sealed_at, verdict: row.fields.seal_verdict ?? 'unknown' } } : {}),
+        reason: typeof row.fields?.product === 'string' && row.fields.product ? `product "${row.fields.product}" is not in the registry` : 'the item names no product; the slice L5 sweep gives it one',
+      }));
+      // The tenant holds dozens of these. The view keeps a bounded sample, the
+      // sealed ones first, and reports the true count (review H16).
+      // A product-scoped read gets the count and no rows: an item with no
+      // product cannot belong to the product the reader asked about.
+      const unregistered = only ? [] : [...unnamed.filter((row) => row.legacy_seal), ...unnamed.filter((row) => !row.legacy_seal)].slice(0, UNREGISTERED_KEPT);
+      const unregisteredTotal = unnamed.length;
+      if (items.length > MAX_ITEMS) refuse(`${items.length} items are registered; the view reads at most ${MAX_ITEMS}. Narrow it with a product id.`);
+      const byId = new Map(items.map((row) => [row.id, row]));
+      const marks = await marksOf(new Set(byId.keys()));
+
+      // Movement from git: every registered repo of the products in view, its
+      // recent pull requests, once per repo and shared by every item.
+      const repoIds = [...reg.repos.values()].filter((repo) => !only || repo.fields.product === only).map((repo) => repo.fields.registry_id).sort();
+      if (repoIds.length > MAX_REPOS) refuse(`${repoIds.length} repos are registered for this view; it reads at most ${MAX_REPOS}. Narrow it with a product id.`);
+      const { pullsByRepo, repoErrors } = await readPullsByRepo(repoIds, readGitHub);
+
+      const readAt = now();
+      const rows = [], delivered = [], notMarked = [];
+      for (const item of items) {
+        const fields = item.fields ?? {};
+        const own = marks.get(item.id) ?? [];
+        // R14: only a delivery mark replaces a legacy seal. A reopen mark, or
+        // any later mark kind, must not erase it (review H9, batch 13).
+        const legacy = own.some((mark) => mark.fields?.kind === 'delivery') ? null : legacySealOf(item);
+        // A reopen corrects the delivery it names. The corrected delivery stays
+        // in the graph and stays visible here, but it no longer stands: its
+        // pull requests go back to "merged, not marked" (design finding R9).
+        const correctedBy = correctionsOf(own);
+        const deliveries = own.filter((mark) => mark.fields.kind === 'delivery');
+        const standing = deliveries.filter((mark) => !correctedBy.has(mark.id));
+        const mine = pullsOfItem(item, pullsByRepo, repoIds);
+        const markedUrls = new Set(standing.flatMap((mark) => (mark.fields.prs ?? []).map((pull) => pull.url)));
+        const merged = mine.filter((pull) => pull.state === 'merged');
+        // R2: a delivery made outside a session shows as "merged, not marked"
+        // until the lead catches it up with the same done verb.
+        const open = merged.filter((pull) => !markedUrls.has(pull.url));
+        const { last, days } = movementOf({ item, marks: own, pulls: mine, legacy, readAt });
+        const state = fields.lifecycle === 'done' ? 'delivered' : (fields.delivery_state === 'reopened' ? 'reopened' : fields.lifecycle);
+
+        const inScope = fields.lifecycle === 'active' || fields.lifecycle === 'done';
+        for (const pull of (inScope ? open : [])) notMarked.push({ item: item.id, item_title: oneLine(item.title, 120), product: fields.product, pr: pull.url, title: pull.title, merged_at: pull.merged_at, days: daysBetween(pull.merged_at, readAt), matched_by: pull.matched_by, note: 'merged, not marked' });
+        for (const mark of deliveries) if (!since || String(mark.fields.marked_at ?? '') >= since) delivered.push({ item: item.id, item_title: oneLine(item.title, 120), product: fields.product, mark_id: mark.id, verdict: correctedBy.has(mark.id) ? 'corrected' : (mark.fields.verdict ?? 'delivered'), ...(correctedBy.has(mark.id) ? { corrected_by: correctedBy.get(mark.id) } : {}), delivered_at: mark.fields.marked_at, prs: (mark.fields.prs ?? []).map((pull) => pull.url), deployed_commit: mark.fields.deployed?.commit ?? null, gate_warnings: mark.fields.gate_warnings ?? [] });
+        if (legacy && (!since || String(legacy.marked_at) >= since)) delivered.push({ item: item.id, item_title: oneLine(item.title, 120), product: fields.product, mark_id: null, verdict: 'legacy', delivered_at: legacy.marked_at, prs: [], deployed_commit: null, source: legacy.source });
+
+        // D3 rule 1: in flight is active work. Delivered and paused items leave
+        // the rows; what was delivered since a date has its own list.
+        if (fields.lifecycle !== 'active') continue;
+        rows.push({
+          item: item.id, product: fields.product, stage: fields.stage ?? '', driver: fields.driver ?? '', days_since_last_change: days,
+          last_change_at: last?.at ?? null, last_change_source: last?.source ?? 'nothing recorded', delivery_state: state,
+          lines: [
+            // The id is what a reader types back, so the title gives way to it
+            // inside the line budget, as the "Needs me" row does (review G6).
+            oneLine(`${oneLine(item.title, Math.max(1, ROW_LINE_MAX - item.id.length - 3))} · ${item.id}`),
+            oneLine(`${fields.product} · ${fields.stage ?? 'no stage'} · ${fields.driver ?? 'no driver'} · next: ${fields.next_step || 'not set'}`),
+            oneLine(`${days === null ? 'no movement on record' : `${days} day${days === 1 ? '' : 's'} since last change`} (${last?.source ?? 'nothing recorded'}) · ${mine.length} pull request${mine.length === 1 ? '' : 's'}${open.length ? ` · ${open.length} merged, not marked` : ''}`),
+          ],
+          folded: { title: item.title, next_step: fields.next_step ?? '', scope: fields.scope?.text ?? '', pieces: fields.split_children ?? [], prs: mine.map((pull) => ({ url: pull.url, state: pull.state, matched_by: pull.matched_by, merged_at: pull.merged_at, updated_at: pull.updated_at })), marks: own.map((mark) => ({ id: mark.id, kind: mark.fields.kind, verdict: mark.fields.verdict, at: mark.fields.marked_at })) },
+          citation: { item: item.id, read_at: readAt, repos: [...new Set(mine.map((pull) => pull.repo))] },
+        });
+      }
+      // The owner's rule: order by days since last change, latest on top, and
+      // show the days on the row.
+      rows.sort((a, b) => (a.days_since_last_change ?? Number.MAX_SAFE_INTEGER) - (b.days_since_last_change ?? Number.MAX_SAFE_INTEGER) || a.item.localeCompare(b.item));
+      delivered.sort((a, b) => String(b.delivered_at ?? '').localeCompare(String(a.delivered_at ?? '')));
+      notMarked.sort((a, b) => (a.days ?? 0) - (b.days ?? 0));
+      const products = [...new Set(rows.map((row) => row.product))].sort();
+      const byProduct = products.map((product) => ({ product, rows: rows.filter((row) => row.product === product) }));
+      const block = byProduct.map((group) => [`${group.product} — in flight (${group.rows.length})`, ...group.rows.flatMap((row, index) => row.lines.map((line, position) => `${position === 0 ? `${index + 1}. ` : '   '}${line}`))].join('\n'));
+      if (notMarked.length) block.push([`merged, not marked (${notMarked.length})`, ...notMarked.map((row) => listLine(row.title, `${row.pr} · ${row.item} · merged ${row.days} day${row.days === 1 ? '' : 's'} ago`))].join('\n'));
+      if (repoErrors.length) block.push([`GitHub did not answer for ${repoErrors.length} repo${repoErrors.length === 1 ? '' : 's'}; movement below is from the graph only`, ...repoErrors.map((row) => oneLine(`   ${row.repo} — ${row.reason}`, ROW_LINE_MAX))].join('\n'));
+      if (unregisteredTotal && !only) {
+        // The list can be long, and a long list is not a view. The sealed ones
+        // come first, because a legacy seal is a delivery the owner may want to
+        // see; the rest are a count and a pointer to the slice L5 sweep.
+        const sealed = unnamed.filter((row) => row.legacy_seal);
+        const shown = unregistered.slice(0, UNREGISTERED_SHOWN);
+        block.push([
+          `not in the registry (${unregisteredTotal}${sealed.length ? `, ${sealed.length} with a legacy seal` : ''}); the slice L5 sweep gives them a product`,
+          ...shown.map((row) => listLine(row.title, `${row.item} · ${row.legacy_seal ? `legacy seal ${String(row.legacy_seal.sealed_at).slice(0, 10)}, verdict ${row.legacy_seal.verdict}` : row.lifecycle}`)),
+          ...(unregisteredTotal > shown.length ? [`   and ${unregisteredTotal - shown.length} more, ${unregistered.length - shown.length} of them in this answer`] : []),
+        ].join('\n'));
+      }
+      if (since && delivered.length) block.push([`delivered since ${since} (${delivered.length})`, ...delivered.map((row) => listLine(row.item_title, `${row.verdict}${(row.gate_warnings ?? []).length ? `, gate warning on ${row.gate_warnings.map((warning) => warning.check).join(' ')}` : ''} · ${String(row.delivered_at ?? '').slice(0, 10)} · ${row.prs.join(' ') || 'no pull request on the mark'}`))].join('\n'));
+      return {
+        verb: 'in_flight', read_at: readAt, product: only, since, rows: rows.length, products: byProduct,
+        merged_not_marked: notMarked, delivered: since ? delivered : delivered.slice(0, 20), unregistered, unregistered_total: unregisteredTotal, repos_read: repoIds, repo_errors: repoErrors,
+        text: block.join('\n\n') || 'Nothing is in flight: no active item on a registered product.',
+      };
+    },
+  };
+  return verbs;
+}