@afokapu/atdd-bun 0.10.111 → 0.10.113

package/integrity.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.10.111",
+  "version": "0.10.113",
   "files": {
     "HOOK_AUDIT.md": "5329d840db37671b1918f688ead26865473b87db73dbc75f7c8b2a8bbe8d6d43",
     "README.md": "8aefceaa24bee498f39081b2aaf4c0d5c54bc1ed9849c20e1d98d1427df56eab",
@@ -1269,7 +1269,7 @@
     "src/cli.ts": "395638ab87565bb10c2beb35988ff1acf686924d13515795156a2e8893b3da88",
     "src/docs-capability.ts": "bdeeb414649049b1cd4fa8008cada3a576318be51c43bec91bfa46a8e250c270",
     "src/enforce.ts": "c4811abe63efe4568f3cf26e21a152d1537e120cb3ce471daca32367cf6e2cda",
-    "src/hooks.ts": "fce67a102fe61c15b4100daddf842ce7264d9e0d0e79ec89c4ed4a0b188967b7",
+    "src/hooks.ts": "7e1310502c3f8959fcfaad9f4e5747d146f4f8bb91a14a8722fa207bd2a48629",
     "src/index.ts": "4081f8b08d1d3ee9e15a9964143e53d9cfb94a5616ab3e58a180d24cc16dc381",
     "src/integrity.ts": "f1ede7cb04924ae88e11917047277e264af6596b9759e381bd9c497cd34a797d",
     "src/journey-docs.ts": "994d229376244c84212cff951032823068a76565dd2fd427b9d44e341bd14853",

package/package.json

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

package/src/hooks.ts

@@ -259,6 +259,130 @@ const cachedEntry = (text: string, key: string): FindingIdentity[] | null => {
   const valid = entry.findings.every(finding => finding && typeof finding.rule_id === "string" && typeof finding.file === "string" && findingFingerprint(finding));
   return valid ? entry.findings : null;
 };
+// Owner-authorized, single-use relaxation of the staged-file-count limit for one atomic delivery (and only that limit).
+// Authorization M-20261104T155526Z-owner-authorization_3fd46f1c; evidence M-20261104T120517Z-atomic-decision-evidence_a871b6f0.
+// The pin lives in reviewed package source, so a consumer-side activation record can only confirm it, never widen it.
+const exceptionSchema = "atdd-bun.staged-file-limit-exception/v1";
+const exceptionPin: Record<string, string> = { project: "score-os", task: "wagon-control-implementation-v2", scope: "staged-file-count", owner_authorization: "M-20261104T155526Z-owner-authorization_3fd46f1c", decision_evidence: "M-20261104T120517Z-atomic-decision-evidence_a871b6f0" };
+const exceptionInventory = [
+  "contracts/score-provider/v1/inspection/descriptor.json",
+  "contracts/score-provider/v1/inspection/fixture.json",
+  "contracts/score-provider/v1/inspection/integrity.json",
+  "contracts/score-provider/v1/manifest.json",
+  "contracts/score-provider/v1/schemas.json",
+  "docs/purpose/journeys/index.adoc",
+  "docs/purpose/journeys/svg/journey-control-assessment.svg",
+  "docs/purpose/journeys/svg/path-control-assessment-nominal.svg",
+  "docs/purpose/journeys/svg/train-score-evaluate-control-refused.svg",
+  "docs/purpose/journeys/svg/train-score-evaluate-control-technical-failure.svg",
+  "docs/purpose/journeys/svg/train-score-evaluate-control.svg",
+  "e2e/interlockings/control-assessment/control-nominal.routes.test.ts",
+  "e2e/interlockings/control-assessment/control-refused.routes.test.ts",
+  "e2e/interlockings/control-assessment/control-technical-failure.routes.test.ts",
+  "plan/_journeys/control-assessment.yaml",
+  "plan/_themes.yaml",
+  "plan/_trains.yaml",
+  "plan/_trains/_interlockings/control-assessment.yaml",
+  "plan/_trains/train:score:evaluate-control-refused.yaml",
+  "plan/_trains/train:score:evaluate-control-technical-failure.yaml",
+  "plan/_trains/train:score:evaluate-control.yaml",
+  "plan/control/_control.yaml",
+  "plan/control/assess-joint-feasibility.yaml",
+  "plan/control/C001.yaml",
+  "plan/control/D001.yaml",
+  "plan/control/E001.yaml",
+  "plan/control/estimate-respite.yaml",
+  "plan/control/estimate-response-time.yaml",
+  "plan/control/evaluate-required-predicates.yaml",
+  "plan/control/P001.yaml",
+  "plan/control/publish-control-diagnostics.yaml",
+  "plan/control/R001.yaml",
+  "plan/control/Y001.yaml",
+  "src/composition.ts",
+  "src/wagons/control/features/assess-joint-feasibility/domain/canonical-joint-feasibility.ts",
+  "src/wagons/control/features/estimate-respite/domain/canonical-respite.ts",
+  "src/wagons/control/features/estimate-response-time/domain/canonical-response-time.ts",
+  "src/wagons/control/features/evaluate-required-predicates/application/evaluate-control.ts",
+  "src/wagons/control/features/evaluate-required-predicates/domain/canonical-vector.ts",
+  "src/wagons/control/features/publish-control-diagnostics/application/publish-control-diagnostics.ts",
+  "tests/fixtures/decision-control-evaluator/v1/canonical-vector.json",
+  "tests/trains/score:evaluate-control/canonical-routes.test.ts",
+  "tests/wagons/commons/features/measured-aspect/unit/provider-inspection-descriptor.contract.test.ts",
+  "tests/wagons/commons/features/measured-aspect/unit/provider-manifest.contract.test.ts",
+  "tests/wagons/control/features/assess-joint-feasibility/unit/canonical-joint-feasibility.test.ts",
+  "tests/wagons/control/features/estimate-respite/unit/canonical-timeliness.test.ts",
+  "tests/wagons/control/features/estimate-response-time/unit/canonical-response-time.test.ts",
+  "tests/wagons/control/features/evaluate-required-predicates/unit/canonical-vector.test.ts",
+  "tests/wagons/control/features/evaluate-required-predicates/unit/noncanonical.test.ts",
+  "tests/wagons/control/features/publish-control-diagnostics/integration/publish-control-diagnostics.test.ts",
+];
+const exceptionFields = ["schema", "inventory", "inventory_sha256", ...Object.keys(exceptionPin)];
+const inventoryHash = (paths: string[]) => new Bun.CryptoHasher("sha256").update([...paths].sort().join("\n")).digest("hex");
+const exceptionInventoryHash = inventoryHash(exceptionInventory);
+/** `reason: null` means no activation record exists: the exception is not in play and the ordinary rejection stands unchanged. */
+type StagedFileExceptionGrant = { ok: true; owner_authorization: string; inventory_sha256: string };
+type StagedFileExceptionDecision = StagedFileExceptionGrant | { ok: false; reason: string | null };
+const refuseException = (reason: string | null): StagedFileExceptionDecision => ({ ok: false, reason });
+type ExceptionRecord = Record<string, unknown> | "missing" | "malformed";
+
+async function readExceptionRecord(file: string): Promise<ExceptionRecord> {
+  const text = await readFile(file, "utf8").catch(() => null);
+  if (text === null) return "missing";
+  try { const data = Bun.YAML.parse(text) as unknown; return data && typeof data === "object" && !Array.isArray(data) ? data as Record<string, unknown> : "malformed"; } catch { return "malformed"; }
+}
+const wellFormedExceptionRecord = (record: Record<string, unknown>) => Object.keys(record).length === exceptionFields.length && exceptionFields.every(key => key in record)
+  && record.schema === exceptionSchema && exceptionFields.filter(key => key !== "inventory").every(key => typeof record[key] === "string")
+  && Array.isArray(record.inventory) && record.inventory.every(path => typeof path === "string");
+function exceptionRecordRefusal(record: Record<string, unknown> | "malformed"): string | null {
+  if (record === "malformed" || !wellFormedExceptionRecord(record)) return "authorization record is malformed";
+  if (Object.entries(exceptionPin).some(([key, value]) => record[key] !== value)) return "authorization record does not match the pinned authorization";
+  if (record.inventory_sha256 !== inventoryHash(record.inventory as string[])) return "authorization record inventory hash does not match its inventory";
+  return record.inventory_sha256 === exceptionInventoryHash ? null : "authorization record does not match the pinned authorization";
+}
+/** Whether the exact staged path set may exceed the staged-file-count limit. Any doubt refuses. */
+async function authorizeStagedFileException(root: string, staged: string[]): Promise<StagedFileExceptionDecision> {
+  const directory = await stagedExceptionDirectory(root), record = directory ? await readExceptionRecord(join(directory, "authorization.yaml")) : "missing";
+  if (!directory || record === "missing") return refuseException(null);
+  const refusal = exceptionRecordRefusal(record);
+  if (refusal) return refuseException(refusal);
+  if ((await readExceptionRecord(join(directory, "consumed.yaml"))) !== "missing") return refuseException("authorization was already consumed");
+  const outside = staged.filter(path => !exceptionInventory.includes(path)), absent = exceptionInventory.filter(path => !staged.includes(path));
+  if (outside.length) return refuseException(`staged paths outside the authorized inventory: ${outside.join(", ")}`);
+  if (absent.length) return refuseException(`authorized inventory paths missing from the staged set: ${absent.join(", ")}`);
+  return { ok: true, owner_authorization: exceptionPin.owner_authorization!, inventory_sha256: exceptionInventoryHash };
+}
+/** Remember that the exception admitted a commit, so post-commit can consume it only if that exact inventory landed. */
+async function recordPendingException(root: string, grant: StagedFileExceptionGrant) {
+  const directory = await stagedExceptionDirectory(root);
+  if (!directory) return;
+  await mkdir(directory, { recursive: true });
+  await writeFile(join(directory, "pending.yaml"), JSON.stringify({ owner_authorization: grant.owner_authorization, inventory_sha256: grant.inventory_sha256 }));
+}
+/** Consume the authorization when HEAD carries exactly the pinned inventory; any pending marker is discarded either way. */
+async function consumePendingException(root: string) {
+  const directory = await stagedExceptionDirectory(root);
+  if (!directory) return;
+  const pending = join(directory, "pending.yaml"), marker = await readExceptionRecord(pending);
+  if (marker === "missing") return;
+  await rm(pending, { force: true });
+  const head = (await git(root, ["rev-parse", "HEAD"])).out, committed = await files(root, ["show", "--pretty=format:", "--name-only", "HEAD"]);
+  if (marker === "malformed" || marker.owner_authorization !== exceptionPin.owner_authorization || marker.inventory_sha256 !== exceptionInventoryHash || inventoryHash(committed) !== exceptionInventoryHash) return;
+  const temporary = join(directory, `consumed.yaml.${process.pid}.tmp`);
+  await writeFile(temporary, JSON.stringify({ schema: exceptionSchema, owner_authorization: exceptionPin.owner_authorization, commit: head, inventory_sha256: exceptionInventoryHash, consumed_at: new Date().toISOString() }));
+  await rename(temporary, join(directory, "consumed.yaml"));
+}
+/** The staged-file-count gate: the ordinary rejection, unless the pinned exception admits exactly this staged set. */
+async function stagedCountGate(root: string, staged: string[], counted: number, limit: number): Promise<{ rejection: string | null; grant: StagedFileExceptionGrant | null }> {
+  if (counted <= limit) return { rejection: null, grant: null };
+  const decision = await authorizeStagedFileException(root, staged);
+  if (decision.ok) return { rejection: null, grant: decision };
+  return { rejection: `staged files ${counted} exceed ${limit}${decision.reason ? `; staged-file exception refused: ${decision.reason}` : ""}`, grant: null };
+}
+/** Where the owner-authorized staged-file exception keeps its record and single-use ledger: the Git common directory, shared by every worktree. */
+async function stagedExceptionDirectory(root: string): Promise<string | null> {
+  const common = await git(root, ["rev-parse", "--git-common-dir"]);
+  return common.code || !common.out ? null : join(resolve(root, common.out), "atdd-bun", "staged-file-limit-exception");
+}
 /** Findings for one exact tree: reuse a valid entry, otherwise compute and record the result for the next push. */
 async function findingsCacheDirectory(root: string): Promise<string | null> {
   const common = await git(root, ["rev-parse", "--git-common-dir"]);
@@ -352,10 +476,10 @@ export async function runHook(event: HookEvent, root = process.cwd(), args: stri
   const cfg = await policy(root), branch = (await git(root, ["symbolic-ref", "--quiet", "--short", "HEAD"])).out;
   if (["pre-commit", "pre-merge-commit"].includes(event) && cfg.protected_branches.includes(branch)) return bad(`protected branch ${branch} is blocked`);
   if (["pre-commit", "pre-merge-commit"].includes(event)) { const violation = await worktreeCommitPolicy(root, cfg.worktrees); if (violation) return bad(violation); }
-  if (event === "pre-commit") { const staged = await files(root, ["diff", "--cached", "--name-only"]), registries = staged.filter(path => isRegistry(cfg, path)), generated = staged.filter(isGeneratedView), counted = staged.length - registries.length - generated.length, lines = (await stagedLineStats(root)).filter(row => !isRegistry(cfg, row.path) && !isGeneratedView(row.path)).reduce((n, row) => n + row.added + row.removed, 0); if (counted > cfg.max_staged_files) return bad(`staged files ${counted} exceed ${cfg.max_staged_files}`); if (lines > cfg.max_staged_changed_lines) return bad(`staged changed lines ${lines} exceed ${cfg.max_staged_changed_lines}`); const ratchet = await ratchetCommitGate(root, staged, registries.length > 0); if (ratchet) return ratchet; return cfg.require_traceability || registries.length || generated.length ? validation(root, staged, false, registries.length > 0) : { ok: true, message: "ok" }; }
+  if (event === "pre-commit") { const staged = await files(root, ["diff", "--cached", "--name-only"]), registries = staged.filter(path => isRegistry(cfg, path)), generated = staged.filter(isGeneratedView), counted = staged.length - registries.length - generated.length, lines = (await stagedLineStats(root)).filter(row => !isRegistry(cfg, row.path) && !isGeneratedView(row.path)).reduce((n, row) => n + row.added + row.removed, 0); const count = await stagedCountGate(root, staged, counted, cfg.max_staged_files); if (count.rejection) return bad(count.rejection); if (lines > cfg.max_staged_changed_lines) return bad(`staged changed lines ${lines} exceed ${cfg.max_staged_changed_lines}`); const ratchet = await ratchetCommitGate(root, staged, registries.length > 0); if (ratchet) return ratchet; const checked = cfg.require_traceability || registries.length || generated.length ? await validation(root, staged, false, registries.length > 0) : { ok: true, message: "ok" }; if (checked.ok && count.grant) await recordPendingException(root, count.grant); return checked; }
   if (event === "commit-msg") { const deleted = (await files(root, ["diff", "--cached", "--name-only", "--diff-filter=D"])).length, stats = await stagedStats(root), lines = stats.reduce((n, row) => n + row.removed, 0), registryRemoved = stats.filter(row => isRegistry(cfg, row.path)).reduce((n, row) => n + row.removed - row.added, 0), message = args[0] && existsSync(args[0]) ? await readFile(args[0], "utf8") : "", approved = message.includes("[mass-delete-approved]"); if ((deleted > 50 || lines > 10_000) && !approved) return bad("mass delete requires [mass-delete-approved]"); return registryRemoved > cfg.max_registry_removed_lines && !approved ? bad(`registry removal of ${registryRemoved} net lines exceeds ${cfg.max_registry_removed_lines}; requires [mass-delete-approved]`) : { ok: true, message: "ok" }; }
   if (event === "pre-push") { const reports: string[] = []; let exclusions: Awaited<ReturnType<typeof countExclusionTips>> | undefined; for (const row of stdin.split("\n").filter(Boolean).map(row => row.split(/\s+/))) { const [, local, remote, remoteSha] = row, target = remote?.replace("refs/heads/", ""); if (target && cfg.protected_branches.includes(target)) return bad(`protected branch ${target} is blocked`); if (!local) return bad("pre-push update has no local object id"); if (/^0+$/.test(local)) { const deletion = await deletionPushGate(root, remoteSha); if (!deletion.ok) return deletion; continue; } const isNew = !remoteSha || /^0+$/.test(remoteSha), range = isNew ? `${local}^..${local}` : `${remoteSha}..${local}`, shared = exclusions ??= await countExclusionTips(root, cfg.protected_branches, args[0]); if ("error" in shared) return bad(`could not list remote branch tips for the pushed range ${range}: ${shared.error}`); const counted = await git(root, ["rev-list", "--count", ...(shared.tips.length ? [isNew ? local : range, "--not", ...shared.tips] : [range])]); if (counted.code || !/^\d+$/.test(counted.out)) return bad(`could not count commits in pushed range ${range}: ${counted.err || counted.out}`); if (Number(counted.out) > cfg.max_commits_per_push) return bad(`commits per push ${counted.out} exceed ${cfg.max_commits_per_push}`); const ratchet = remote?.startsWith("refs/heads/") ? await ratchetPushGate(root, remoteSha ?? "", local, cfg.protected_branches, args[0]) : null; if (ratchet) { if (!ratchet.ok) return ratchet; reports.push(ratchet.message); continue; } const strict = await strictPushGate(root, local, range); if (!strict.ok) return strict; } return reports.length ? { ok: true, message: reports.length === 1 ? reports[0]! : `[${reports.join(",")}]` } : { ok: true, message: "validation clean" }; }
-  if (event === "post-commit") { const result = await validation(root, await files(root, ["show", "--pretty=format:", "--name-only", "HEAD"]), false); return { ok: true, message: result.ok ? result.message : `advisory: ${result.message}` }; }
+  if (event === "post-commit") { await consumePendingException(root); const result = await validation(root, await files(root, ["show", "--pretty=format:", "--name-only", "HEAD"]), false); return { ok: true, message: result.ok ? result.message : `advisory: ${result.message}` }; }
   return { ok: true, message: "ok" };
 }
 
@@ -411,14 +535,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 +606,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 +631,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 +652,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 +705,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}` };
 }