@afokapu/atdd-bun 0.10.110 → 0.10.112

package/integrity.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.10.110",
+  "version": "0.10.112",
   "files": {
     "HOOK_AUDIT.md": "5329d840db37671b1918f688ead26865473b87db73dbc75f7c8b2a8bbe8d6d43",
     "README.md": "8aefceaa24bee498f39081b2aaf4c0d5c54bc1ed9849c20e1d98d1427df56eab",
@@ -1033,7 +1033,7 @@
     "lib/frontend.mjs": "d6d9b29c3d7f2d162cda03bb34b20a3224a82887b6be3db7cab375510913c9a3",
     "lib/imports.mjs": "3db4979269488fa26f6e7aefded6ece9c646be6587a10e249821a5a208109962",
     "lib/interlocking.mjs": "d0803d080ac7d7477c51be70112df1e85213d339fd3c6b71f75f26145fa8accd",
-    "lib/journey-chain.mjs": "8ba32f5ab52bec636eb87b97a532427dcca81f3481a588a093ff4b5e643f7c8f",
+    "lib/journey-chain.mjs": "347418f944d92997c7c48913cd17bce99fc28649fa6db2f96bbd1ea8f18052c5",
     "lib/scan.mjs": "b6973e411ecd14c548a055c871e01e948f002b772042136be8401f38d998e687",
     "planner-nodes/ENFORCEMENT_SCOPE.yaml": "47aa9c78a4bb1754c6b435f5e056038baa04a24cd48df2c205db2bc08a3a3cac",
     "planner-nodes/nodes/planner.acceptance.abstract-fields-required.convention.yaml": "bd565693f0ae861f0561ad2f7a91a8c55f9a209c3acd59c5750cfcffd96a85d8",
@@ -1269,7 +1269,7 @@
     "src/cli.ts": "395638ab87565bb10c2beb35988ff1acf686924d13515795156a2e8893b3da88",
     "src/docs-capability.ts": "bdeeb414649049b1cd4fa8008cada3a576318be51c43bec91bfa46a8e250c270",
     "src/enforce.ts": "c4811abe63efe4568f3cf26e21a152d1537e120cb3ce471daca32367cf6e2cda",
-    "src/hooks.ts": "fce67a102fe61c15b4100daddf842ce7264d9e0d0e79ec89c4ed4a0b188967b7",
+    "src/hooks.ts": "bdfc4560351a414741c8a5c94404570522033a92dbaac8079af09fa3847e82bc",
     "src/index.ts": "4081f8b08d1d3ee9e15a9964143e53d9cfb94a5616ab3e58a180d24cc16dc381",
     "src/integrity.ts": "f1ede7cb04924ae88e11917047277e264af6596b9759e381bd9c497cd34a797d",
     "src/journey-docs.ts": "994d229376244c84212cff951032823068a76565dd2fd427b9d44e341bd14853",

package/lib/journey-chain.mjs

@@ -35,7 +35,7 @@
 //        still proven to run on every live path.
 import ts from "typescript";
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { dirname, join, resolve, sep } from "node:path";
+import { dirname, extname, join, resolve, sep } from "node:path";
 
 const programs = new Map();
 
@@ -263,12 +263,38 @@ function optionsFor(file) {
   return resolutionOptions.get(config);
 }
 
+// TypeScript sources a JavaScript-extension specifier may name (`./x.js` -> `./x.ts`), as TypeScript and Bun resolve them.
+const TS_COUNTERPARTS = { ".js": [".ts", ".tsx"], ".mjs": [".mts"], ".cjs": [".cts"], ".jsx": [".tsx"] };
+// Extensions an extensionless specifier may resolve to.
+const MODULE_SUFFIXES = [".ts", ".tsx", ".mts", ".cts", ".js", ".mjs", ".cjs", ".jsx"];
+
+// Every file a relative `target` path can name: itself, each module suffix appended, `index` plus each suffix
+// inside it as a directory, and the TypeScript counterpart of a JavaScript extension.
+function relativeCandidates(target) {
+  const extension = extname(target);
+  const counterparts = (TS_COUNTERPARTS[extension] ?? []).map((replacement) => target.slice(0, -extension.length) + replacement);
+  return [target, ...MODULE_SUFFIXES.map((suffix) => target + suffix),
+    ...MODULE_SUFFIXES.map((suffix) => join(target, `index${suffix}`)), ...counterparts];
+}
+
+// Every local module `specifier` can name when imported from `current`, inside `croot` and outside node_modules.
+// A relative specifier counts every candidate that exists, so a `.js` specifier covers both a real `.js` file and
+// its TypeScript counterpart: neither can hide a module from the closure.
+function resolveLocals(specifier, current, croot) {
+  const root = resolve(croot) + sep;
+  if (specifier.startsWith("."))
+    return relativeCandidates(resolve(dirname(current), specifier))
+      .filter((candidate) => candidate.startsWith(root) && existsSync(candidate) && statSync(candidate).isFile());
+  const resolved = ts.resolveModuleName(specifier, current, optionsFor(current), ts.sys).resolvedModule;
+  const target = resolved && !resolved.isExternalLibraryImport ? resolve(resolved.resolvedFileName) : null;
+  return target && target.startsWith(root) && !target.split(sep).includes("node_modules") && !target.endsWith(".d.ts") ? [target] : [];
+}
+
 // Every local module reachable from `file` through static, side-effect, re-export, dynamic `import()`
 // and `require()` specifiers, including `file` itself. Relative specifiers resolve against the file;
 // non-relative ones (tsconfig path aliases, package.json `#imports`) resolve through the TypeScript
 // resolver and count when they land inside `croot` outside node_modules.
 function localImportClosure(file, croot) {
-  const root = resolve(croot) + sep;
   const seen = new Set([file]);
   const queue = [file];
   while (queue.length) {
@@ -280,20 +306,13 @@ function localImportClosure(file, croot) {
       if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteralLike(node.moduleSpecifier)) specifiers.push(node.moduleSpecifier.text);
       if (ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword || isGlobal(ctx, node.expression, "require")) &&
         node.arguments[0] && ts.isStringLiteralLike(node.arguments[0])) specifiers.push(node.arguments[0].text);
+      if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference) &&
+        ts.isStringLiteralLike(node.moduleReference.expression)) specifiers.push(node.moduleReference.expression.text);
     });
     for (const specifier of specifiers) {
-      let found;
-      if (specifier.startsWith(".")) {
-        const target = resolve(dirname(current), specifier);
-        found = [target, `${target}.ts`, `${target}.tsx`, `${target}.js`, `${target}.mjs`, join(target, "index.ts")]
-          .find((candidate) => existsSync(candidate) && statSync(candidate).isFile() && candidate.startsWith(root));
-      } else {
-        const resolved = ts.resolveModuleName(specifier, current, optionsFor(current), ts.sys).resolvedModule;
-        const target = resolved && !resolved.isExternalLibraryImport ? resolve(resolved.resolvedFileName) : null;
-        found = target && target.startsWith(root) && !target.split(sep).includes("node_modules") && !target.endsWith(".d.ts")
-          ? target : undefined;
+      for (const found of resolveLocals(specifier, current, croot)) {
+        if (!seen.has(found)) { seen.add(found); queue.push(found); }
       }
-      if (found && !seen.has(found)) { seen.add(found); queue.push(found); }
     }
   }
   return seen;
@@ -1096,6 +1115,245 @@ function declaresAction(croot, path, action) {
   }
 }
 
+// ---- Object-form JourneyEntry dataflow -------------------------------------------------------------
+// A journey test may reach its declaration through a static JOURNEY_MAP instead of a path literal:
+//   const entry = <map>[ACTION];  new JourneyRunner(entry.path, ...);  execute({ ..., action: ACTION, ... }, ...)
+// where <map> is a `const JOURNEY_MAP` object literal in the test or exported by a local production module
+// (named or namespace import), ACTION and the key are const string literals, and nothing writes the map.
+
+// The string a literal, or a chain of consts bound to one, evaluates to; else null.
+function staticString(ctx, node, seen = new Set()) {
+  node = node && unwrap(node);
+  if (!node) return null;
+  if (ts.isStringLiteralLike(node)) return node.text;
+  if (!ts.isIdentifier(node) || seen.has(node.text)) return null;
+  return staticString(ctx, constInitializer(ctx, node), new Set([...seen, node.text]));
+}
+
+// The property `name` of an object literal made only of plain `key: value` / shorthand members, else null.
+// A spread, computed key, method, accessor or duplicate could change the value, so each refuses the literal.
+function plainProperty(object, name) {
+  const named = (member) => (ts.isPropertyAssignment(member) || ts.isShorthandPropertyAssignment(member)) && member.name &&
+    (ts.isIdentifier(member.name) || ts.isStringLiteral(member.name)) ? member.name.text : null;
+  if (!ts.isObjectLiteralExpression(object) || object.properties.some((member) => named(member) === null)) return null;
+  const matches = object.properties.filter((member) => named(member) === name);
+  return matches.length === 1 ? matches[0] : null;
+}
+
+// The action of an execute request: a string literal, or an object literal whose sole `action` is static.
+function requestAction(ctx, request) {
+  request = request && unwrap(request);
+  if (!request) return null;
+  if (ts.isStringLiteralLike(request)) return request.text;
+  const member = plainProperty(request, "action");
+  return member && staticString(ctx, ts.isShorthandPropertyAssignment(member) ? member.name : member.initializer);
+}
+
+const isTypeWrapper = (node) => ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isNonNullExpression(node) ||
+  ts.isSatisfiesExpression(node) || ts.isTypeAssertionExpression(node);
+
+// The outermost wrapper/member-access chain around `node` and how many member accesses it holds.
+function climb(node) {
+  let length = 0;
+  for (let parent = node.parent; parent; parent = node.parent) {
+    if (isTypeWrapper(parent) && parent.expression === node) node = parent;
+    else if ((ts.isPropertyAccessExpression(parent) || ts.isElementAccessExpression(parent)) && parent.expression === node) {
+      node = parent;
+      length++;
+    } else break;
+  }
+  return { top: node, length };
+}
+
+// `node` sits in a destructuring-assignment pattern (`({ p: x.y } = v)`, `[x.y] = v`, nested, spread or defaulted)
+// or is the head of a `for (x.y of|in v)`: the pattern or loop writes it.
+function inAssignmentPattern(node) {
+  for (let child = node, parent = child.parent; parent; child = parent, parent = child.parent) {
+    if (ts.isForOfStatement(parent) || ts.isForInStatement(parent)) return parent.initializer === child;
+    if (ts.isBinaryExpression(parent)) return parent.operatorToken.kind === ts.SyntaxKind.EqualsToken && parent.left === child;
+    const transparent = isTypeWrapper(parent) || ts.isSpreadElement(parent) || ts.isSpreadAssignment(parent) ||
+      ts.isArrayLiteralExpression(parent) || ts.isObjectLiteralExpression(parent) ||
+      ((ts.isPropertyAssignment(parent) || ts.isShorthandPropertyAssignment(parent)) && parent.name !== child);
+    if (!transparent) return false;
+  }
+  return false;
+}
+
+function writesTo(node) {
+  const parent = node.parent;
+  return (ts.isBinaryExpression(parent) && parent.left === node &&
+    parent.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && parent.operatorToken.kind <= ts.SyntaxKind.LastAssignment) ||
+    ((ts.isPrefixUnaryExpression(parent) || ts.isPostfixUnaryExpression(parent)) &&
+      (parent.operator === ts.SyntaxKind.PlusPlusToken || parent.operator === ts.SyntaxKind.MinusMinusToken)) ||
+    ts.isDeleteExpression(parent) || inAssignmentPattern(node);
+}
+
+// An identifier occurrence that declares or names the symbol rather than using it.
+function declaresOrNames(node) {
+  const parent = node.parent;
+  return (ts.isVariableDeclaration(parent) && parent.name === node) || ts.isTypeQueryNode(parent) || ts.isExportSpecifier(parent) ||
+    ts.isImportSpecifier(parent) || ts.isNamespaceImport(parent) || (ts.isImportEqualsDeclaration(parent) && parent.name === node);
+}
+
+// A use that only tests the value (`!x`, `if (x)`, `x ? a : b`, `x && y`, `x === y`), never keeps or changes it.
+function testsOnly(node) {
+  const parent = node.parent;
+  return (ts.isPrefixUnaryExpression(parent) && parent.operator === ts.SyntaxKind.ExclamationToken) ||
+    (ts.isIfStatement(parent) && parent.expression === node) || (ts.isConditionalExpression(parent) && parent.condition === node) ||
+    (ts.isBinaryExpression(parent) && [ts.SyntaxKind.AmpersandAmpersandToken, ts.SyntaxKind.BarBarToken, ts.SyntaxKind.QuestionQuestionToken,
+      ts.SyntaxKind.EqualsEqualsToken, ts.SyntaxKind.EqualsEqualsEqualsToken, ts.SyntaxKind.ExclamationEqualsToken,
+      ts.SyntaxKind.ExclamationEqualsEqualsToken].includes(parent.operatorToken.kind));
+}
+
+// Nothing writes the map, an entry of it, or a const alias of either. `depth` is how many members deep the
+// bound value sits (map 0, entry 1; a namespace import -1, with `member` selecting its JOURNEY_MAP member).
+// A map or entry that is passed on, returned or stored anywhere else could be written out of sight: refused.
+// A namespace binding (`member` set) may appear only as `ns.<member>` or `ns.<other export>`; an alias,
+// destructure, element access, argument or export of the namespace itself is refused for the same reason.
+function unwritten(ctx, symbol, depth, member = null, seen = new Set()) {
+  if (seen.has(symbol)) return true;
+  seen.add(symbol);
+  let ok = true;
+  walk(ctx.source, (node) => {
+    if (!ok) return false;
+    if (!ts.isIdentifier(node) || symbolOf(ctx, node) !== symbol || declaresOrNames(node)) return;
+    if (member) {
+      // A namespace may be used only as `ns.<member>` (checked below) or `ns.<other export>`; any other use
+      // (alias, destructure, element access, argument, export) could reach the map out of sight.
+      const access = ts.isPropertyAccessExpression(node.parent) && node.parent.expression === node ? node.parent : null;
+      if (!access) { ok = false; return; }
+      if (access.name.text !== member) return;
+    }
+    const { top, length } = climb(node);
+    const total = depth + length;
+    const alias = ts.isVariableDeclaration(top.parent) && top.parent.initializer === top && ts.isIdentifier(top.parent.name) &&
+      ts.isVariableDeclarationList(top.parent.parent) && Boolean(top.parent.parent.flags & ts.NodeFlags.Const);
+    if (writesTo(top)) ok = false;
+    else if (total >= 2 || testsOnly(top)) return;
+    else if (alias) ok = unwritten(ctx, symbolOf(ctx, top.parent.name), total, null, seen);
+    else ok = false;
+  });
+  return ok;
+}
+
+// The top-level `const JOURNEY_MAP` object literal of `moduleCtx` (exported when it is another module's).
+function mapLiteral(moduleCtx, exported) {
+  for (const statement of moduleCtx.source.statements) {
+    if (!ts.isVariableStatement(statement) || !(statement.declarationList.flags & ts.NodeFlags.Const)) continue;
+    if (exported && !(ts.getCombinedModifierFlags(statement) & ts.ModifierFlags.Export)) continue;
+    const declaration = statement.declarationList.declarations.find((item) => ts.isIdentifier(item.name) && item.name.text === "JOURNEY_MAP");
+    const literal = declaration?.initializer && unwrap(declaration.initializer);
+    if (literal && ts.isObjectLiteralExpression(literal)) return { ctx: moduleCtx, declaration, literal };
+  }
+  return null;
+}
+
+// The local production module a named JOURNEY_MAP import or a namespace import binds to, else null.
+function mapModule(declaration, named, ctx, croot) {
+  const clause = named
+    ? ts.isImportSpecifier(declaration) && !declaration.isTypeOnly && (declaration.propertyName ?? declaration.name).text === "JOURNEY_MAP"
+      ? declaration.parent.parent
+      : null
+    : ts.isNamespaceImport(declaration) ? declaration.parent : null;
+  if (!clause || clause.isTypeOnly || !ts.isStringLiteral(clause.parent.moduleSpecifier)) return null;
+  return productionModule(clause.parent.moduleSpecifier.text, ctx.file, croot);
+}
+
+// The binding `symbol` is re-exported by an `export { ... }` of the module.
+function exportedBinding(ctx, symbol) {
+  let found = false;
+  walk(ctx.source, (child) => {
+    found ||= ts.isExportSpecifier(child) && ctx.checker.getExportSpecifierLocalTargetSymbol(child) === symbol;
+  });
+  return found;
+}
+
+// The import binds JOURNEY_MAP (by name or through a namespace) and nothing writes, hands on or re-exports it.
+function importReadOnly(ctx, node) {
+  const bindings = node.importClause?.namedBindings;
+  if (!bindings || node.importClause.isTypeOnly) return true;
+  if (ts.isNamespaceImport(bindings)) {
+    const symbol = symbolOf(ctx, bindings.name);
+    return !exportedBinding(ctx, symbol) && unwritten(ctx, symbol, -1, "JOURNEY_MAP");
+  }
+  return bindings.elements.every((element) => {
+    if (element.isTypeOnly || (element.propertyName ?? element.name).text !== "JOURNEY_MAP") return true;
+    const symbol = symbolOf(ctx, element.name);
+    return !exportedBinding(ctx, symbol) && unwritten(ctx, symbol, 0);
+  });
+}
+
+// `import ns = require(<map module>)` binds the module namespace: it must stay unexported and be used like a namespace import.
+function importEqualsReadOnly(ctx, node) {
+  if (ts.getCombinedModifierFlags(node) & ts.ModifierFlags.Export) return false;
+  const symbol = symbolOf(ctx, node.name);
+  return !exportedBinding(ctx, symbol) && unwritten(ctx, symbol, -1, "JOURNEY_MAP");
+}
+
+// Whether `node` of a module in the closure leaves the map module's JOURNEY_MAP read-only. A re-export, dynamic
+// `import()` or `require()` of the map module hands the map on out of sight and is refused.
+function readsMapOnly(ctx, node, reaches) {
+  if (ts.isImportDeclaration(node)) return !reaches(node.moduleSpecifier) || importReadOnly(ctx, node);
+  if (ts.isExportDeclaration(node)) return !reaches(node.moduleSpecifier) || node.isTypeOnly;
+  if (ts.isImportEqualsDeclaration(node)) {
+    const reference = node.moduleReference;
+    return node.isTypeOnly || !ts.isExternalModuleReference(reference) || !reaches(reference.expression) || importEqualsReadOnly(ctx, node);
+  }
+  const call = ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword || isGlobal(ctx, node.expression, "require"));
+  return !call || !reaches(node.arguments[0]);
+}
+
+// Every module of the local import closure of `testFile` that reaches the map module `mapFile` only reads
+// JOURNEY_MAP: a side-effect module could otherwise rewrite an entry before the test runs.
+function mapReadOnlyInClosure(testFile, croot, mapFile) {
+  return [...localImportClosure(testFile, croot)].filter((file) => file !== mapFile).every((file) => {
+    const ctx = analyze(file);
+    const reaches = (specifier) => Boolean(specifier) && ts.isStringLiteralLike(specifier) && resolveLocals(specifier.text, file, croot).includes(mapFile);
+    let ok = true;
+    walk(ctx.source, (node) => {
+      ok &&= readsMapOnly(ctx, node, reaches);
+      return ok;
+    });
+    return ok;
+  });
+}
+
+// The JOURNEY_MAP `expression` names ({ ctx, declaration, literal }), provided neither the module that
+// declares it nor the binding that reaches it writes it; else null.
+function resolvedMap(ctx, expression, croot) {
+  expression = unwrap(expression);
+  const namespaced = ts.isPropertyAccessExpression(expression) && expression.name.text === "JOURNEY_MAP";
+  const binding = namespaced ? expression.expression : expression;
+  const named = !namespaced;
+  if (!ts.isIdentifier(binding) || (named && binding.text !== "JOURNEY_MAP")) return null;
+  const declaration = declarationOf(ctx, binding);
+  if (!declaration) return null;
+  if (named && ts.isVariableDeclaration(declaration)) {
+    const local = mapLiteral(ctx, false);
+    return local && local.declaration === declaration && unwritten(ctx, symbolOf(ctx, binding), 0) ? local : null;
+  }
+  const module = mapModule(declaration, named, ctx, croot);
+  const map = module && mapLiteral(analyze(module), true);
+  if (!map || !unwritten(map.ctx, symbolOf(map.ctx, map.declaration.name), 0)) return null;
+  return mapReadOnlyInClosure(ctx.file, croot, module) ? map : null;
+}
+
+// The path of `<entry>.path` where `entry` is a const bound to `<JOURNEY_MAP>[<key>]` and key is `action`;
+// a string literal is its own path. Anything else (dynamic, other field, other action) is null.
+function journeyPath(ctx, node, action, croot) {
+  node = node && unwrap(node);
+  if (!node) return null;
+  if (ts.isStringLiteralLike(node)) return node.text;
+  if (!ts.isPropertyAccessExpression(node) || node.name.text !== "path" || !ts.isIdentifier(unwrap(node.expression))) return null;
+  const lookup = constInitializer(ctx, unwrap(node.expression));
+  const access = lookup && unwrap(lookup);
+  if (!access || !ts.isElementAccessExpression(access) || staticString(ctx, access.argumentExpression) !== action) return null;
+  const map = resolvedMap(ctx, access.expression, croot);
+  const entry = map && plainProperty(map.literal, action);
+  const path = entry && ts.isPropertyAssignment(entry) && plainProperty(unwrap(entry.initializer), "path");
+  return path && ts.isPropertyAssignment(path) ? staticString(map.ctx, path.initializer) : null;
+}
+
 // A test module asserts a production JourneyRunner execution result, proven like provenJourneyAction:
 //   - a live `const` bound to `await <receiver>.execute("<action>", ...)`, the receiver being
 //     `new JourneyRunner("<journey declaration>")` or a const bound to one;
@@ -1114,11 +1372,11 @@ export function assertedJourneyExecution(testText, testFile, croot) {
     if (!ts.isVariableDeclaration(node) || !ts.isIdentifier(node.name) || !node.initializer ||
       !(ts.isVariableDeclarationList(node.parent) && node.parent.flags & ts.NodeFlags.Const)) return;
     const awaited = ts.isAwaitExpression(node.initializer) ? unwrap(node.initializer) : null;
-    const action = awaited && ts.isCallExpression(awaited) && awaited.arguments[0];
-    if (!action || !ts.isStringLiteralLike(action) || dead(node, ctx.source) || insideCatch(node, ctx.source)) return;
+    const action = awaited && ts.isCallExpression(awaited) && requestAction(ctx, awaited.arguments[0]);
+    if (!action || dead(node, ctx.source) || insideCatch(node, ctx.source)) return;
     const fromDeclaration = (construction) => {
-      const path = construction.arguments?.[0];
-      return Boolean(path && ts.isStringLiteralLike(path) && declaresAction(croot, path.text, action.text));
+      const path = journeyPath(ctx, construction.arguments?.[0], action, croot);
+      return path !== null && declaresAction(croot, path, action);
     };
     const modules = new Set();
     if (executesImported(ctx, "JourneyRunner", croot, modules, fromDeclaration)(awaited) &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-bun",
-  "version": "0.10.110",
+  "version": "0.10.112",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/afokapu/atdd-bun.git"

package/src/hooks.ts

@@ -411,14 +411,14 @@ async function branchCommit(root: string, branch: string) {
 
 // A delivery commit must have one unambiguous non-protected exported bookmark.
 // Ref ordering is never used as ownership authority.
-async function branchForCommit(root: string, commit: string, protectedBranches: string[]): Promise<{ error: string } | { branch: string }> {
+async function branchForCommit(root: string, commit: string, protectedBranches: string[]): Promise<{ error: string; count?: number } | { branch: string }> {
   const refs = await git(root, ["for-each-ref", "--format=%(refname:short)", "--points-at", commit, "refs/heads/"]);
   if (refs.code) return { error: refs.err || refs.out };
   const candidates = refs.out.split("\n").map(line => line.trim()).filter(Boolean)
     .filter(name => !protectedBranches.includes(name));
   return candidates.length === 1
     ? { branch: candidates[0]! }
-    : { error: `current Jujutsu revision must have exactly one non-protected exported bookmark; found ${candidates.length}` };
+    : { error: `current Jujutsu revision must have exactly one non-protected exported bookmark; found ${candidates.length}`, count: candidates.length };
 }
 
 // A JJ-colocated primary keeps Git HEAD detached at its working-copy parent, so JJ state decides:
@@ -482,13 +482,16 @@ async function createWorkspace(state: Layout, target: { leaf: string; target: st
   return bad(bookmark.err || bookmark.out || `bookmark ${branch} was not exported to the colocated Git repository`);
 }
 
-async function finishCandidate(state: Layout, cfg: HookPolicy): Promise<{ error: string } | { branch: string; tip: string }> {
+// A branch of null means the delivery bookmark is already gone and the revision is merged.
+type FinishCandidate = { branch: string | null; tip: string };
+async function finishCandidate(state: Layout, cfg: HookPolicy): Promise<{ error: string } | FinishCandidate> {
   if (state.current === state.primary || !inside(state.worktreeRoot, state.current)) return { error: `finish must run from a linked workspace beneath ${state.worktreeRoot}` };
   const conflict = await noConflicts(state.current);
   if (conflict.error !== undefined) return conflict;
   const current = await currentCommit(state.current);
   if (!current) return { error: "could not resolve the current Jujutsu revision" };
   let delivery = current, found = await branchForCommit(state.current, current, cfg.protected_branches);
+  if ("error" in found && found.count === 0 && await mergedIntoPrimary(state, current, cfg)) return { branch: null, tip: current };
   if ("error" in found) {
     const changed = await jj(state.current, ["diff", "-r", "@", "--name-only"]);
     const parent = await jj(state.current, ["log", "-r", "@-", "--no-graph", "-T", "commit_id"]);
@@ -504,6 +507,11 @@ async function finishCandidate(state: Layout, cfg: HookPolicy): Promise<{ error:
   return undelivered ? { error: undelivered } : { branch: found.branch, tip };
 }
 
+// Zero-bookmark retirement is safe only for a revision already equal to or an ancestor of protected main.
+async function mergedIntoPrimary(state: Layout, commit: string, cfg: HookPolicy) {
+  return !(await git(state.primary, ["merge-base", "--is-ancestor", commit, cfg.worktrees.primary_branch])).code;
+}
+
 async function jjRevision(root: string, commit: string): Promise<{ error: string } | { empty: boolean; conflict: boolean; parents: string[] }> {
   const info = await jj(root, ["log", "-r", commit, "--no-graph", "-T", 'if(empty, "empty", "content") ++ " " ++ if(conflict, "conflict", "clean") ++ " " ++ parents.map(|p| p.commit_id()).join(" ")']);
   if (info.code || !info.out) return { error: `could not inspect Jujutsu revision ${commit}: ${info.err || info.out}` };
@@ -520,7 +528,7 @@ async function deliveryError(state: Layout, branch: string, tip: string, cfg: Ho
     const info = await jjRevision(state.primary, commit);
     if ("error" in info) return info.error;
     if (info.conflict) return `bookmark ${branch} has unresolved conflicts`;
-    if (!(await git(state.primary, ["merge-base", "--is-ancestor", commit, cfg.worktrees.primary_branch])).code) return null;
+    if (await mergedIntoPrimary(state, commit, cfg)) return null;
     if (!info.empty || info.parents.length !== 1) return `branch ${branch} is not merged into ${cfg.worktrees.primary_branch} in the primary checkout`;
     commit = info.parents[0]!;
   }
@@ -573,9 +581,10 @@ async function finishJjWorktree(root: string, deleteBranch: boolean, cfg: HookPo
   if ("error" in workspace) return bad(workspace.error);
   const removed = await jj(state.primary, ["workspace", "remove", workspace.name]);
   if (removed.code) return bad(removed.err || removed.out);
-  if (!deleteBranch) return { ok: true, message: `removed merged Jujutsu workspace ${state.current}` };
-  const deletionError = await deleteBookmark(state, candidate, cfg);
-  return deletionError ? bad(deletionError) : { ok: true, message: `removed merged Jujutsu workspace ${state.current} and bookmark ${candidate.branch}` };
+  const { branch } = candidate;
+  if (!deleteBranch || branch === null) return { ok: true, message: `removed merged Jujutsu workspace ${state.current}` };
+  const deletionError = await deleteBookmark(state, { branch, tip: candidate.tip }, cfg);
+  return deletionError ? bad(deletionError) : { ok: true, message: `removed merged Jujutsu workspace ${state.current} and bookmark ${branch}` };
 }