@teamscala/service-boot 0.23.291 → 0.23.293

package/src/fn-routers/task-sync-projection.test.ts

@@ -0,0 +1,123 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Co-located tests for the task-sync PROJECTION pure helpers. The module was
+ * split out of task-sync-router.ts precisely so this half — the WHAT-changes
+ * decisions — is unit-testable with no database (the router only EXECUTES the
+ * plan). Covers status mapping, the blocked-row preservation rule, key
+ * resolution, update-target resolution + full reconciliation planning.
+ */
+import { describe, expect, it } from "bun:test";
+import {
+	STATUS_TO_WORK_ITEM,
+	normalizeStatus,
+	planReconcile,
+	resolveProjectedStatus,
+	resolveTaskUpdateTarget,
+	subtaskKey,
+	type ReconcilePlan,
+} from "./task-sync-projection.ts";
+import type { TaskListItem } from "./task-sync-router.ts";
+
+describe("STATUS_TO_WORK_ITEM", () => {
+	it("maps the three CLI statuses to work_items status enum values", () => {
+		expect(STATUS_TO_WORK_ITEM.pending).toBe("todo");
+		expect(STATUS_TO_WORK_ITEM.in_progress).toBe("in-progress");
+		expect(STATUS_TO_WORK_ITEM.completed).toBe("done");
+	});
+});
+
+describe("normalizeStatus", () => {
+	it("maps work_items statuses back to the normalized CLI form", () => {
+		expect(normalizeStatus("todo")).toBe("pending");
+		expect(normalizeStatus("in-progress")).toBe("in_progress");
+		expect(normalizeStatus("done")).toBe("completed");
+	});
+
+	it("collapses unknown / null / internal statuses to pending", () => {
+		expect(normalizeStatus(null)).toBe("pending");
+		expect(normalizeStatus("blocked")).toBe("pending");
+		expect(normalizeStatus("some-internal-state")).toBe("pending");
+	});
+});
+
+describe("resolveProjectedStatus", () => {
+	it("preserves a blocked row when the CLI list can only express it as todo", () => {
+		expect(resolveProjectedStatus("blocked", "todo")).toBe("blocked");
+	});
+
+	it("lets real CLI transitions (in-progress, done) win normally", () => {
+		expect(resolveProjectedStatus("blocked", "in-progress")).toBe("in-progress");
+		expect(resolveProjectedStatus("todo", "done")).toBe("done");
+	});
+});
+
+describe("subtaskKey", () => {
+	it("prefers mark, then content, then title", () => {
+		expect(subtaskKey({ mark: "1", content: "c", title: "t" })).toBe("1");
+		expect(subtaskKey({ content: "c", title: "t" })).toBe("c");
+		expect(subtaskKey({ content: "", title: "t" })).toBe("t");
+	});
+});
+
+describe("resolveTaskUpdateTarget", () => {
+	const existing = [
+		{ id: "a", title: "Alpha", kind_data: { task_sync: { mark: "1" } } },
+		{ id: "b", title: "Beta", kind_data: null },
+	];
+	it("updates by stamped mark", () => {
+		expect(resolveTaskUpdateTarget(existing, { taskId: "1", subject: "anything" })).toEqual({
+			op: "update",
+			id: "a",
+		});
+	});
+	it("updates by exact title when no mark matches", () => {
+		expect(resolveTaskUpdateTarget(existing, { taskId: "9", subject: "Beta" })).toEqual({
+			op: "update",
+			id: "b",
+		});
+	});
+	it("heals when nothing matches but a subject can rebuild the row", () => {
+		expect(resolveTaskUpdateTarget(existing, { taskId: "9", subject: "Gamma" })).toEqual({
+			op: "heal",
+			title: "Gamma",
+		});
+	});
+	it("discards when nothing matches and there is no subject", () => {
+		expect(resolveTaskUpdateTarget(existing, { taskId: "9" })).toEqual({ op: "discard" });
+	});
+});
+
+describe("planReconcile", () => {
+	it("creates new items, updates changed ones, deletes unseen ones", () => {
+		const existing = [
+			{ id: "1", kind: "subtask", parent_id: null, organisation_id: "org", title: "Keep", status: "todo", completed: false, position: "0", kind_data: {} },
+			{ id: "2", kind: "subtask", parent_id: null, organisation_id: "org", title: "Gone", status: "todo", completed: false, position: "1", kind_data: {} },
+		];
+		const incoming: TaskListItem[] = [
+			{ content: "Keep", status: "completed", mark: undefined },
+			{ content: "New", status: "pending", mark: undefined },
+		];
+		const plan: ReconcilePlan = planReconcile(existing, incoming);
+		// "Keep" changed (todo→done) → update; "Gone" absent → delete; "New" → create.
+		expect(plan.toUpdate.map((u) => u.id)).toEqual(["1"]);
+		expect(plan.toUpdate[0]?.status).toBe("done");
+		expect(plan.toCreate.map((c) => c.content)).toEqual(["New"]);
+		expect(plan.toDelete).toEqual(["2"]);
+	});
+
+	it("preserves a blocked existing row against an incoming todo", () => {
+		const existing = [
+			{ id: "1", kind: "subtask", parent_id: null, organisation_id: "org", title: "X", status: "blocked", completed: false, position: "5", kind_data: {} },
+		];
+		// Incoming pending (-> "todo") at a DIFFERENT position so an update fires;
+		// without the preservation rule the row would be rewritten to "todo",
+		// silently destroying the block.
+		const incoming: TaskListItem[] = [{ content: "X", status: "pending", mark: undefined }];
+		const plan = planReconcile(existing, incoming, "src");
+		expect(plan.toUpdate.length).toBe(1);
+		expect(plan.toUpdate[0]?.status).toBe("blocked");
+	});
+});

package/src/fn-routers/task-sync-projection.ts

@@ -0,0 +1,201 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The task-sync PROJECTION: how a CLI's task list maps onto `work_items` rows,
+ * and what reconciling one against the other should do.
+ *
+ * Split out of `task-sync-router.ts`, which had grown past the 1000-line budget
+ * and so could not be committed by anyone touching it. The seam is real rather
+ * than arbitrary: everything here is PURE and decides WHAT should change, while
+ * the router owns the ORPC surface and performs the writes. That is exactly why
+ * this half is directly testable with no database.
+ *
+ * CAPABILITY HARVEST (capability-harvest-on-split): APP-LOCAL, not a capability
+ * candidate. Checked against the 14 platform singletons and the package catalog
+ * — nothing generic to fold into, and the doctrine test fails: no unrelated app
+ * could install this unmodified, because every export is bound to the
+ * `work_items` schema and task-sync's own contract (STATUS_TO_WORK_ITEM encodes
+ * the work_items status enum, subtaskKey is this projection's key convention,
+ * planReconcile diffs against work_items subtask rows).
+ *
+ * The near-miss is worth naming so the next reader does not re-derive it: the
+ * SHAPE — diff a desired list against existing rows into create/update/delete —
+ * is generic, and `document-signing` is precedent for lifting a pure domain half
+ * out of service-boot into a package. It stays here because it has exactly one
+ * consumer; extracting it now would be speculative packaging, which
+ * platform-capabilities treats as drift. Revisit if a SECOND surface needs
+ * list-against-rows reconciliation — then the generic diff core (not the
+ * work_items-specific mapping) is what earns a package.
+ */
+
+import type { TaskListItem, WorkItem } from "./task-sync-router.ts";
+
+// TodoWrite-style status (the normalized form) → work_items.status (DB enum).
+// The DB enum uses a hyphen for the active state ("in-progress"); see
+// COLUMN_ENUMS["work_items.status"] in db-validation.
+export const STATUS_TO_WORK_ITEM: Record<TaskListItem["status"], string> = {
+	pending: "todo",
+	in_progress: "in-progress",
+	completed: "done",
+};
+// work_items.status → normalized. Unknown/internal statuses collapse to pending.
+const WORK_ITEM_TO_STATUS: Record<string, TaskListItem["status"]> = {
+	todo: "pending",
+	"in-progress": "in_progress",
+	active: "in_progress",
+	done: "completed",
+	completed: "completed",
+};
+
+export function normalizeStatus(s: string | null): TaskListItem["status"] {
+	return (s && WORK_ITEM_TO_STATUS[s]) || "pending";
+}
+
+/**
+ * Decide the status to WRITE for an existing row, given what the CLI list says.
+ *
+ * The CLI task list has no `blocked` state, so a blocked row round-trips as
+ * `pending` (via `normalizeStatus`, which collapses unknown/internal statuses)
+ * and then maps back to `todo` — silently destroying the block. That is not a
+ * cosmetic drift: the stop gate reads these rows, so un-blocking one re-blocks
+ * the LANE from stopping, and the lane's only apparent fix is to touch the list
+ * again, which destroys it again.
+ *
+ * A `todo` arriving from the CLI therefore carries NO information: it is what
+ * the projection emits for every status it cannot represent, not an assertion
+ * that the work became un-blocked. `in-progress` and `done` are different —
+ * those are real transitions the CLI CAN express, so they win normally.
+ *
+ * Measured 2026-07-30: a lane set a row to `blocked` with a named blocker, the
+ * next TaskUpdate reset it to `todo`, and the stop gate reported the lane
+ * unfinished again — three turns of ping-pong before the cause was found.
+ */
+export function resolveProjectedStatus(
+	currentStatus: string | null | undefined,
+	incomingStatus: string,
+): string {
+	if (currentStatus === "blocked" && incomingStatus === "todo") return "blocked";
+	return incomingStatus;
+}
+
+export function subtaskKey(item: { mark?: string; content: string; title: string }): string {
+	return item.mark || item.content || item.title;
+}
+
+/**
+ * Pure decision for a TaskUpdate/TaskDelete: which existing subtask does this
+ * event address, and what should happen when none does. Extracted for the same
+ * reason planReconcile was — the handler should only EXECUTE, so the matching
+ * rule is unit-testable.
+ *
+ * Three resolutions:
+ *  - `update` — matched by mark, or (mark absent/unstamped) by exact title.
+ *  - `heal`   — nothing matched but the event carries a subject, so the row can
+ *               be reconstructed. Covers a TaskCreate that silently produced no
+ *               subtask, which previously orphaned the task forever.
+ *  - `discard` — nothing matched and there is no subject to rebuild a title from.
+ *
+ * Measured 2026-07-28: marks "1" and "3" were stamped for one lane while mark
+ * "2" was never written at all, and every later update for it was dropped as
+ * `no-matching-subtask` — 26 of 30 tasksync discards in six hours, across seven
+ * distinct lane sessions, were that one reason.
+ */
+export function resolveTaskUpdateTarget(
+	existing: Array<{ id: string; title: string; kind_data?: Record<string, unknown> | null }>,
+	evt: { taskId: string; subject?: string },
+): { op: "update"; id: string } | { op: "heal"; title: string } | { op: "discard" } {
+	const byMark = existing.find(
+		(s) =>
+			evt.taskId &&
+			(s.kind_data as { task_sync?: { mark?: string } } | null)?.task_sync?.mark === evt.taskId,
+	);
+	if (byMark) return { op: "update", id: byMark.id };
+	const subject = (evt.subject ?? "").trim();
+	if (subject) {
+		const byTitle = existing.find((s) => s.title === subject);
+		if (byTitle) return { op: "update", id: byTitle.id };
+		return { op: "heal", title: subject };
+	}
+	return { op: "discard" };
+}
+
+/**
+ * Pure reconciliation plan: given the lane's EXISTING subtasks and its INCOMING
+ * (current) task list, compute the create/update/delete ops that make the
+ * subtask set match the list — WITHOUT touching prisma. Extracted so the
+ * matching/status/positioning logic is unit-testable (the handler only executes
+ * the plan). Matching is by stable mark when the CLI provides one, else by
+ * content. Position follows incoming index, so a reorder is an update.
+ */
+export interface ReconcilePlan {
+	toCreate: Array<{
+		content: string;
+		status: string;
+		completed: boolean;
+		position: string;
+		kind_data: Record<string, unknown>;
+	}>;
+	toUpdate: Array<{
+		id: string;
+		content: string;
+		status: string;
+		completed: boolean;
+		position: string;
+		kind_data: Record<string, unknown>;
+	}>;
+	toDelete: string[];
+}
+
+export function planReconcile(
+	existing: WorkItem[],
+	incoming: TaskListItem[],
+	source?: string,
+): ReconcilePlan {
+	const byKey = new Map<string, WorkItem>();
+	for (const s of existing) {
+		const mark = (s.kind_data?.task_sync as { mark?: string } | undefined)?.mark;
+		byKey.set(subtaskKey({ mark, content: "", title: s.title }), s);
+	}
+	const toCreate: ReconcilePlan["toCreate"] = [];
+	const toUpdate: ReconcilePlan["toUpdate"] = [];
+	const seen = new Set<string>();
+	for (let i = 0; i < incoming.length; i++) {
+		const item = incoming[i];
+		const content = (item.content ?? "").trim();
+		if (!content) continue;
+		const key = subtaskKey({ mark: item.mark, content, title: content });
+		const incomingStatus = STATUS_TO_WORK_ITEM[item.status] ?? "todo";
+		const completed = item.status === "completed";
+		const position = String(i);
+		const taskSync = { task_sync: { mark: item.mark, source } };
+		const match = byKey.get(key);
+		if (match) {
+			seen.add(match.id);
+			// A blocked row must survive a list the CLI cannot express it in.
+			const status = resolveProjectedStatus(match.status, incomingStatus);
+			const changed =
+				match.title !== content ||
+				match.status !== status ||
+				(match.completed ?? false) !== completed ||
+				match.position !== position;
+			if (changed) {
+				toUpdate.push({
+					id: match.id,
+					content,
+					status,
+					completed,
+					position,
+					kind_data: { ...match.kind_data, ...taskSync },
+				});
+			}
+		} else {
+			// A row being created has no prior status to preserve, so the incoming
+			// one stands unmodified.
+			toCreate.push({ content, status: incomingStatus, completed, position, kind_data: taskSync });
+		}
+	}
+	const toDelete = existing.filter((s) => !seen.has(s.id)).map((s) => s.id);
+	return { toCreate, toUpdate, toDelete };
+}

package/src/fn-routers/task-sync-router.d.ts

@@ -81,7 +81,7 @@ export interface LaneIdentity {
      */
     organisation_id?: string;
 }
-interface WorkItem {
+export interface WorkItem {
     id: string;
     kind: string;
     parent_id: string | null;
@@ -104,8 +104,6 @@ export declare function untrackedRunForPane(pane: string): {
     };
     tracked_task_id: null;
 };
-export declare const STATUS_TO_WORK_ITEM: Record<TaskListItem["status"], string>;
-export declare function normalizeStatus(s: string | null): TaskListItem["status"];
 /**
  * Resolve the org a lane's task is created under. Explicit when the lane knows
  * its org (a dispatched fleet lane carries one); defaults to the platform org
@@ -154,72 +152,6 @@ export declare function classifyTaskHookEvent(evt: {
     hook_event_name?: unknown;
     task_subject?: unknown;
 }): "completed" | "created" | "tool";
-export declare function subtaskKey(item: {
-    mark?: string;
-    content: string;
-    title: string;
-}): string;
-/**
- * Pure decision for a TaskUpdate/TaskDelete: which existing subtask does this
- * event address, and what should happen when none does. Extracted for the same
- * reason planReconcile was — the handler should only EXECUTE, so the matching
- * rule is unit-testable.
- *
- * Three resolutions:
- *  - `update` — matched by mark, or (mark absent/unstamped) by exact title.
- *  - `heal`   — nothing matched but the event carries a subject, so the row can
- *               be reconstructed. Covers a TaskCreate that silently produced no
- *               subtask, which previously orphaned the task forever.
- *  - `discard` — nothing matched and there is no subject to rebuild a title from.
- *
- * Measured 2026-07-28: marks "1" and "3" were stamped for one lane while mark
- * "2" was never written at all, and every later update for it was dropped as
- * `no-matching-subtask` — 26 of 30 tasksync discards in six hours, across seven
- * distinct lane sessions, were that one reason.
- */
-export declare function resolveTaskUpdateTarget(existing: Array<{
-    id: string;
-    title: string;
-    kind_data?: Record<string, unknown> | null;
-}>, evt: {
-    taskId: string;
-    subject?: string;
-}): {
-    op: "update";
-    id: string;
-} | {
-    op: "heal";
-    title: string;
-} | {
-    op: "discard";
-};
-/**
- * Pure reconciliation plan: given the lane's EXISTING subtasks and its INCOMING
- * (current) task list, compute the create/update/delete ops that make the
- * subtask set match the list — WITHOUT touching prisma. Extracted so the
- * matching/status/positioning logic is unit-testable (the handler only executes
- * the plan). Matching is by stable mark when the CLI provides one, else by
- * content. Position follows incoming index, so a reorder is an update.
- */
-export interface ReconcilePlan {
-    toCreate: Array<{
-        content: string;
-        status: string;
-        completed: boolean;
-        position: string;
-        kind_data: Record<string, unknown>;
-    }>;
-    toUpdate: Array<{
-        id: string;
-        content: string;
-        status: string;
-        completed: boolean;
-        position: string;
-        kind_data: Record<string, unknown>;
-    }>;
-    toDelete: string[];
-}
-export declare function planReconcile(existing: WorkItem[], incoming: TaskListItem[], source?: string): ReconcilePlan;
 export declare const taskSyncRouter: {
     /**
      * Bind (create-or-confirm) the task a lane owns. Called from a SessionStart
@@ -373,4 +305,3 @@ export declare const taskSyncRouter: {
         notified: boolean;
     }>, Record<never, never>, Record<never, never>>;
 };
-export {};

package/src/fn-routers/task-sync-router.test.ts

@@ -13,11 +13,11 @@ import {
 	resolveTaskUpdateTarget,
 	planReconcile,
 	normalizeStatus,
+	resolveProjectedStatus,
 	subtaskKey,
 	STATUS_TO_WORK_ITEM,
-	type TaskListItem,
-	upsertFromTaskListInput,
-} from "./task-sync-router.ts";
+} from "./task-sync-projection.ts";
+import { type TaskListItem, upsertFromTaskListInput } from "./task-sync-router.ts";
 import * as v from "valibot";
 
 interface WorkItemLike {
@@ -309,3 +309,41 @@ describe("task-sync upsertFromTaskListInput schema", () => {
 		expect(() => v.parse(upsertFromTaskListInput, { task_list: [] })).toThrow();
 	});
 });
+
+describe("a blocked row survives a CLI list that cannot express it", () => {
+	it("an incoming todo does NOT overwrite a blocked row", () => {
+		// The CLI emits todo/pending for every status it cannot represent, so a
+		// todo arriving for a blocked row asserts nothing about the work.
+		expect(resolveProjectedStatus("blocked", "todo")).toBe("blocked");
+	});
+
+	it("real transitions the CLI CAN express still win", () => {
+		// in-progress and done are genuine user signals, not projection artifacts.
+		expect(resolveProjectedStatus("blocked", "in-progress")).toBe("in-progress");
+		expect(resolveProjectedStatus("blocked", "done")).toBe("done");
+	});
+
+	it("a non-blocked row is unaffected", () => {
+		expect(resolveProjectedStatus("todo", "in-progress")).toBe("in-progress");
+		expect(resolveProjectedStatus("in-progress", "done")).toBe("done");
+		expect(resolveProjectedStatus("done", "todo")).toBe("todo");
+	});
+
+	it("a missing current status never resurrects a block", () => {
+		expect(resolveProjectedStatus(null, "todo")).toBe("todo");
+		expect(resolveProjectedStatus(undefined, "todo")).toBe("todo");
+	});
+
+	it("planReconcile leaves a blocked subtask blocked when the list says pending", () => {
+		// The end-to-end shape: this is what re-blocked the lane three times.
+		const plan = planReconcile(
+			[{ mark: "1", content: "Deploy the fix", status: "pending" }],
+			[{ id: "row-1", title: "Deploy the fix", status: "blocked", completed: false, position: "0", kind_data: { task_sync: { mark: "1" } } }] as never,
+			"claude-code",
+		);
+		const update = plan.toUpdate.find((u) => u.id === "row-1");
+
+		// Either untouched, or updated while KEEPING blocked — never downgraded.
+		expect(update?.status ?? "blocked").toBe("blocked");
+	});
+});