@afokapu/atdd-flow 0.3.77 → 0.3.78

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-flow",
-  "version": "0.3.77",
+  "version": "0.3.78",
   "description": "Filesystem-first Desk registry for projects, seats, tasks, threads, and handoffs.",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -67,6 +67,7 @@ Usage:
   atdd-flow task respond <project> <task-id> --by <coordinator> --outcome <accept|return> --phase <plan|red|green|refactor>
   atdd-flow task block <project> <task-id> --by <address> --reason <text>
   atdd-flow task supersede|reject <project> <task-id> --by <coordinator-address> --reason <text>
+  atdd-flow task supersede <project> <task-id> --by main@<project> --reason <text> --authorization <operator-message-id>
   atdd-flow task defer <project> <task-id> --by <coordinator-address> --reason <text> --owner <address> --trigger <text> --review-at <ISO-8601>
   atdd-flow task unblock <project> <task-id> --by <coordinator-address>
   atdd-flow task list <project> [--coordinator <address>] [--assignee <address>]
@@ -83,7 +84,7 @@ Usage:
   atdd-flow thread add <thread-id> <address>
   atdd-flow thread open <thread-id>
   atdd-flow message read <message-id>
-  atdd-flow post <thread-id> --from <address> --to <all|address,...> --body <text> [--label <non-sensitive-text>] [--expects-result] [--task-transfer-authorization <json>]
+  atdd-flow post <thread-id> --from <address> --to <all|address,...> --body <text> [--label <non-sensitive-text>] [--expects-result] [--task-transfer-authorization <json>] [--task-supersede-authorization <json>]
   atdd-flow receipt <thread-id> <message-id> --from <address> [--body <text>] [--label <non-sensitive-text>]
   atdd-flow result <thread-id> <message-id> --from <address> --body <text> [--label <non-sensitive-text>]
   atdd-flow status [project <project>|task <project> <task-id>|seat <address>|thread <thread-id>] [--all]

package/src/pi-runtime-launch.ts

@@ -99,7 +99,7 @@ async function isExactNamedCoordinator(root: string, record: Seat, address: stri
   return Boolean(worktree && await hasUniqueCoordinatorPlacement(root, record, worktree));
 }
 
-async function launchEligibleTasks(root: string, record: Seat, address: string) {
+export async function launchEligibleTasks(root: string, record: Seat, address: string) {
   const coordinator = await isExactNamedCoordinator(root, record, address);
   const operator = await isExactOperatorSeat(root, record, address);
   const tasks = await seatTasks(root, record.project, record.address);

package/src/task-supersede-authorization.ts

@@ -0,0 +1,113 @@
+// URN: component:flow:e022:task-supersede-authorization:backend:integration
+// Tested-By:
+// - test:atdd-flow:coordinator-stale-task-supersede-authorization
+// Runtime: bun
+// Purpose: Owner-authorized supersession of a stale coordinator task.
+
+import { createHash } from "node:crypto";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { atomicYaml, paths, readYaml, seat, yaml } from "./core";
+
+/** The one exact tuple an operator@desk message may carry to authorize `task supersede` by main. */
+export type SupersedeAuthorization = {
+  schema: "atdd-workflow/task-supersede-authorization/v1";
+  project: string;
+  task: string;
+  coordinator: string;
+  action: "supersede";
+  reason: string;
+  task_sha256: string;
+};
+
+const sha256 = (content: string) => createHash("sha256").update(content).digest("hex");
+
+/** Locate the one operator@desk message `reference`, addressed to main in a thread main joined, and return its typed payload. */
+export async function operatorAuthorizationPayload(root: string, reference: string, main: string): Promise<unknown> {
+  type Found = { schema?: string; id?: string; from?: string; to?: "all" | string[]; authorization?: unknown };
+  const folders = await readdir(paths(root).threads, { withFileTypes: true });
+  const matches = (await Promise.all(folders.filter((entry) => entry.isDirectory() && entry.name.startsWith("T-"))
+    .map(async (entry) => {
+      try {
+        const [thread, message] = await Promise.all([
+          readYaml<{ schema?: string; participants?: string[] }>(paths(root).threadFile(entry.name)),
+          readYaml<Found>(paths(root).message(entry.name, reference)),
+        ]);
+        return { thread, message };
+      } catch { return undefined; }
+    }))).filter((entry): entry is NonNullable<typeof entry> =>
+      entry?.thread.schema === "atdd-workflow/thread/v1" && entry.thread.participants?.includes(main) === true
+      && entry.message.schema === "atdd-workflow/message/v1" && entry.message.id === reference);
+  if (matches.length !== 1 || matches[0]?.message.from !== "operator@desk") {
+    throw new Error(`Authorization ${reference} is not an owner-authorized topology plan.`);
+  }
+  const message = matches[0].message;
+  if (message.to !== "all" && !message.to?.includes(main)) throw new Error(`Authorization ${reference} is not applicable to ${main}.`);
+  return message.authorization;
+}
+
+/** Create-only evidence: an existing file must hold exactly the same bytes. */
+async function publishOrVerify(file: string, bytes: string) {
+  try { await writeFile(file, bytes, { encoding: "utf8", flag: "wx" }); }
+  catch (error) { if ((error as { code?: string }).code !== "EEXIST") throw error; }
+  if (await readFile(file, "utf8") !== bytes) throw new Error("Task supersede archive collides with different immutable evidence.");
+}
+
+/** Archive the pre-mutation task bytes and the authorization by task hash, create-only. */
+async function archiveEvidence(root: string, projectName: string, id: string, hash: string, taskBytes: string, evidence: Record<string, unknown>) {
+  const folder = join(root, ".atdd-flow", "task-supersede-archive", projectName, id, hash);
+  await mkdir(folder, { recursive: true });
+  await publishOrVerify(join(folder, "task.yaml"), taskBytes);
+  await publishOrVerify(join(folder, "authorization.yaml"), yaml.print(evidence));
+}
+
+/** Exact tuple equality: the same keys with the same values, and nothing more. */
+function sameTuple(actual: unknown, expected: SupersedeAuthorization) {
+  const record = actual && typeof actual === "object" ? actual as Record<string, unknown> : undefined;
+  const keys = Object.keys(expected) as (keyof SupersedeAuthorization)[];
+  return Boolean(record) && Object.keys(record!).length === keys.length && keys.every((key) => record![key] === expected[key]);
+}
+
+type Subject = { project: string; id: string; coordinator: string; reason: string; main: string; reference: string };
+
+async function assertStaleCoordinatorTask(root: string, subject: Subject) {
+  const owner = await seat(root, subject.coordinator).catch(() => undefined);
+  if (owner?.role !== "coordinator" || owner.project !== subject.project) {
+    throw new Error(`Task ${subject.id} is not owned by a named coordinator of ${subject.project}; the owner authorization applies only to coordinator tasks.`);
+  }
+  const { launchEligibleTasks } = await import("./pi-runtime-launch");
+  if ((await launchEligibleTasks(root, owner, subject.coordinator)).length) {
+    throw new Error(`${subject.coordinator} has a launch-eligible task and can supersede task ${subject.id} itself.`);
+  }
+}
+
+/**
+ * Validate every exact owner-authorization and staleness condition, then archive the evidence. Nothing is written until
+ * all checks pass; the caller records the terminal disposition afterwards. Returns the authorization reference.
+ */
+export async function authorizeSupersede(root: string, subject: Subject): Promise<string> {
+  const taskBytes = await readFile(paths(root).taskFile(subject.project, subject.id), "utf8");
+  const expected: SupersedeAuthorization = {
+    schema: "atdd-workflow/task-supersede-authorization/v1", project: subject.project, task: subject.id,
+    coordinator: subject.coordinator, action: "supersede", reason: subject.reason, task_sha256: sha256(taskBytes),
+  };
+  const authorization = await operatorAuthorizationPayload(root, subject.reference, subject.main);
+  if (!sameTuple(authorization, expected)) throw new Error(`Authorization ${subject.reference} is not an exact supersede authorization.`);
+  await assertStaleCoordinatorTask(root, subject);
+  await archiveEvidence(root, subject.project, subject.id, expected.task_sha256, taskBytes, { id: subject.reference, from: "operator@desk", authorization: expected });
+  return subject.reference;
+}
+
+/** Parse `post --task-supersede-authorization`: operator@desk only, one exact task-supersede-authorization/v1 tuple. */
+export function parseSupersedeAuthorization(encoded: string | undefined, from: string): SupersedeAuthorization | undefined {
+  if (!encoded) return undefined;
+  if (from !== "operator@desk") throw new Error("Only operator@desk may create a task supersede authorization.");
+  let value: Partial<SupersedeAuthorization> | undefined;
+  try { value = JSON.parse(encoded); } catch { throw new Error("--task-supersede-authorization must be valid JSON."); }
+  const fields = [value?.project, value?.task, value?.coordinator, value?.reason, value?.task_sha256];
+  if (value?.schema !== "atdd-workflow/task-supersede-authorization/v1" || value.action !== "supersede"
+    || !fields.every((entry) => typeof entry === "string" && entry.length) || !/^[a-f0-9]{64}$/i.test(value.task_sha256!)) {
+    throw new Error("--task-supersede-authorization must contain one exact task-supersede-authorization/v1 tuple.");
+  }
+  return value as SupersedeAuthorization;
+}

package/src/tasks.ts

@@ -3,6 +3,7 @@ import { basename, dirname, join, resolve } from "node:path";
 import {
   type Checkpoint, type Seat, atomicYaml, canonicalAddress, exists, now, paths, project, readYaml, required, runOutput, seat, taskId, values, words,
 } from "./core";
+import { operatorAuthorizationPayload } from "./task-supersede-authorization";
 import { branchCommit, currentCommit, isAncestor, vcsMode, type VcsMode } from "./vcs";
 
 export type TaskStatus = "todo" | "in_progress" | "review" | "done" | "superseded" | "rejected";
@@ -27,7 +28,7 @@ export type CoordinatorTransfer = {
   lineage_ref?: LineageRef;
   effective_at: string;
 };
-export type TerminalDisposition = { kind: "superseded" | "rejected"; by: string; at: string; reason: string };
+export type TerminalDisposition = { kind: "superseded" | "rejected"; by: string; at: string; reason: string; authorization?: string };
 export type DeferredDisposition = { by: string; at: string; reason: string; owner: string; trigger: string; review_at: string };
 export type DispatchAlert = { key: string; message: string; observed_at: string };
 /** Persisted evidence for an immediate assignment; each field is written only by its own typed command. */
@@ -463,28 +464,7 @@ type TransferAuthorization = {
 };
 
 async function operatorAuthorization(root: string, reference: string, main: string, expected: TransferAuthorization) {
-  type AuthorizationMessage = { schema?: string; id?: string; from?: string; to?: "all" | string[]; authorization?: TransferAuthorization };
-  type AuthorizationThread = { schema?: string; participants?: string[] };
-  const folders = await readdir(paths(root).threads, { withFileTypes: true });
-  const matches = (await Promise.all(folders.filter((entry) => entry.isDirectory() && entry.name.startsWith("T-"))
-    .map(async (entry) => {
-      try {
-        const [thread, message] = await Promise.all([
-          readYaml<AuthorizationThread>(paths(root).threadFile(entry.name)),
-          readYaml<AuthorizationMessage>(paths(root).message(entry.name, reference)),
-        ]);
-        return { thread, message };
-      } catch { return undefined; }
-    }))).filter((entry): entry is NonNullable<typeof entry> =>
-      entry?.thread.schema === "atdd-workflow/thread/v1" && entry.thread.participants?.includes(main) === true
-      && entry.message.schema === "atdd-workflow/message/v1" && entry.message.id === reference);
-  if (matches.length !== 1 || matches[0]?.message.from !== "operator@desk") {
-    throw new Error(`Authorization ${reference} is not an owner-authorized topology plan.`);
-  }
-  if (matches[0].message.to !== "all" && !matches[0].message.to?.includes(main)) {
-    throw new Error(`Authorization ${reference} is not applicable to ${main}.`);
-  }
-  const authorization = matches[0].message.authorization;
+  const authorization = await operatorAuthorizationPayload(root, reference, main) as TransferAuthorization | undefined;
   if (!authorization || authorization.schema !== expected.schema
     || authorization.project !== expected.project || authorization.task !== expected.task
     || authorization.from !== expected.from || authorization.to !== expected.to
@@ -721,10 +701,14 @@ export async function block(root: string, projectName: string, id: string, args:
 export async function disposition(root: string, projectName: string, id: string, kind: TerminalDisposition["kind"], args: string[]) {
   const task = await readTask(root, projectName, taskId(id));
   const actor = await canonicalAddress(root, required(words(args, "--by"), "--by"));
-  if (actor !== task.coordinator) throw new Error(`Only ${task.coordinator} may ${kind} task ${id}.`);
+  const owner = kind === "superseded" && actor === `main@${projectName}` && actor !== task.coordinator && Boolean(words(args, "--authorization"));
+  if (actor !== task.coordinator && !owner) throw new Error(`Only ${task.coordinator} may ${kind} task ${id}.`);
   if (task.disposition || task.status === "done") throw new Error(`Task ${id} already has terminal history and cannot be ${kind}.`);
+  const reason = required(words(args, "--reason"), "--reason");
+  const reference = owner ? words(args, "--authorization") : undefined;
+  const authorization = reference ? await (await import("./task-supersede-authorization")).authorizeSupersede(root, { project: projectName, id, coordinator: task.coordinator, reason, main: actor, reference }) : undefined;
   task.status = kind;
-  task.disposition = { kind, by: actor, at: now(), reason: required(words(args, "--reason"), "--reason") };
+  task.disposition = { kind, by: actor, at: now(), reason, ...(authorization ? { authorization } : {}) };
   delete task.blocker;
   await writeTask(root, projectName, taskId(id), task);
   console.log(`${id}  ${kind}`);

package/src/threads.ts

@@ -2,6 +2,7 @@ import { mkdir, readdir, rm, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { notify } from "./adapters";
 import { seatTasks, terminal } from "./tasks";
+import { type SupersedeAuthorization, parseSupersedeAuthorization } from "./task-supersede-authorization";
 import {
   atomicYaml, canonicalAddress, desk, has, id, now, paths, project, readYaml,
   required, runtimeAddress, seat, words,
@@ -29,7 +30,7 @@ export type Message = {
   created_at: string;
   body: string;
   /** Immutable owner authorization for one exact coordinator-transfer tuple. */
-  authorization?: TransferAuthorization;
+  authorization?: TransferAuthorization | SupersedeAuthorization;
 };
 
 async function thread(root: string, threadId: string) {
@@ -280,6 +281,11 @@ function transferAuthorization(args: string[], from: string) {
   return value as TransferAuthorization;
 }
 
+/** The one typed owner authorization a post may carry: a transfer tuple or a supersede tuple. */
+function typedAuthorization(args: string[], from: string) {
+  return transferAuthorization(args, from) ?? parseSupersedeAuthorization(words(args, "--task-supersede-authorization"), from);
+}
+
 async function post(root: string, threadId: string, args: string[], overrides: Partial<Message> = {}) {
   const record = await thread(root, threadId);
   const from = await canonicalAddress(root, required(overrides.from ?? words(args, "--from"), "--from"));
@@ -289,7 +295,7 @@ async function post(root: string, threadId: string, args: string[], overrides: P
   if (recipients.some((address) => !record.participants.includes(address))) throw new Error("Recipients must be thread participants.");
   await assertRoute(root, from, recipients.filter((address) => address !== from));
   const kind = overrides.kind ?? "message";
-  const authorization = overrides.authorization ?? transferAuthorization(args, from);
+  const authorization = overrides.authorization ?? typedAuthorization(args, from);
   // Labels are an explicit, non-sensitive operator hint; message bodies never enter durable IDs.
   const label = words(args, "--label") ?? kind;
   const message: Message = {