@teamscala/service-boot 0.23.291 → 0.23.293

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

@@ -41,6 +41,15 @@ import { getPlatformOrgId } from "@teamscala/db/registry/platform";
 import { authed, type Context } from "./auth-router.ts";
 import { notifyLaneOfTaskChange } from "./task-sync-dispatch.ts";
 import * as v from "valibot";
+import {
+	STATUS_TO_WORK_ITEM,
+	normalizeStatus,
+	resolveProjectedStatus,
+	subtaskKey,
+	resolveTaskUpdateTarget,
+	planReconcile,
+	type ReconcilePlan,
+} from "./task-sync-projection.ts";
 
 /** A lane's native task-list item, normalized. Every CLI adapter maps to this. */
 export interface TaskListItem {
@@ -92,7 +101,7 @@ export interface LaneIdentity {
 	organisation_id?: string;
 }
 
-interface WorkItem {
+export interface WorkItem {
 	id: string;
 	kind: string;
 	parent_id: string | null;
@@ -127,26 +136,6 @@ export function untrackedRunForPane(pane: string) {
 	};
 }
 
-// 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";
-}
 
 /**
  * Resolve the org a lane's task is created under. Explicit when the lane knows
@@ -372,121 +361,6 @@ export function classifyTaskHookEvent(evt: {
 	return "tool";
 }
 
-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 status = 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);
-			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 {
-			toCreate.push({ content, status, completed, position, kind_data: taskSync });
-		}
-	}
-	const toDelete = existing.filter((s) => !seen.has(s.id)).map((s) => s.id);
-	return { toCreate, toUpdate, toDelete };
-}
 
 /**
  * Execute a reconcile against prisma for a lane's task — the shared write path
@@ -501,10 +375,31 @@ async function reconcileTaskList(
 	laneSession: string,
 	list: TaskListItem[],
 	source?: string,
+	pane?: string | null,
 ): Promise<{ task_id: string; created: number; updated: number; deleted: number; total: number }> {
-	const task = await resolveLaneTask(prisma, laneSession);
+	// BIND ON DEMAND — this path used to `resolveLaneTask` and THROW, which is the
+	// exact failure `ensureLaneTask` was written to make impossible (see its
+	// comment above, and the operator ruling it cites: "ALL lanes can comply,
+	// there is no reason why a tab cant comply"). The backstop existed and this
+	// caller did not use it, so a lane whose SessionStart bindLane never ran — or
+	// ran while the endpoint was failing — could never sync a task list again.
+	// Not degraded: permanently, with a 404 on every attempt and no path to
+	// self-recover.
+	//
+	// Measured 2026-07-30: a live lane reported ~9 consecutive failures over
+	// hours and correctly diagnosed its own lane-compliance flag as a false
+	// positive it was structurally unable to clear. The gate was telling it to
+	// keep a task list while the only endpoint that records one refused it.
+	//
+	// A lane calling this HAS everything the bind needs — its session, its pane,
+	// its list — so requiring a prior call is a sequencing demand with no
+	// informational content. `friction-is-a-stop-condition`: the compliant path
+	// must exist, or the rule is unenforceable against the lane it binds.
+	const task = await ensureLaneTask(prisma, laneSession, pane ?? null);
 	if (!task) {
-		throw new Error(`No task bound to session ${laneSession}. Call taskSync.bindLane first (SessionStart adapter).`);
+		throw new Error(
+			`Could not bind a task for session ${laneSession} — the create failed and no existing task was found.`,
+		);
 	}
 	const existing = await prisma.work_items.findMany({
 		where: { parent_id: task.id, kind: "subtask" },
@@ -701,8 +596,13 @@ export const taskSyncRouter = {
 			const { ORPCError } = await import("@orpc/server");
 			throw new ORPCError("BAD_REQUEST", { message: "upsertFromTaskList requires lane_session" });
 		}
+		// The pane rides in the header the callers already send (`x-lane-pane`),
+		// and it is what lets the on-demand bind link the new task to the lane's
+		// run. Absent, the bind still succeeds — it just cannot link the run — so
+		// this is passed opportunistically rather than required.
+		const headerPane = (context as Context).headers?.get("x-lane-pane") ?? null;
 		try {
-			const res = await reconcileTaskList(prisma, session, list, body.source);
+			const res = await reconcileTaskList(prisma, session, list, body.source, headerPane);
 			log.info("[task-sync] upsertFromTaskList reconciled", { session, ...res });
 			return res;
 		} catch (err) {
@@ -710,6 +610,13 @@ export const taskSyncRouter = {
 				const { ORPCError } = await import("@orpc/server");
 				throw new ORPCError("NOT_FOUND", { message: err.message });
 			}
+			// The 500 body is masked by oRPC (INTERNAL_SERVER_ERROR), so without
+			// this the cause is invisible — measured 2026-07-30:
+			// upsertFromTaskList 500ing consistently with no surfaced error,
+			// blocking task-list projection + the watchdog for every lane. Log
+			// the actual error before re-throwing (protective-layers-fail-
+			// explicitly: a failure with no observability is the worst shape).
+			log.error("[task-sync] upsertFromTaskList FAILED", { session, err: err instanceof Error ? `${err.name}: ${err.message}` : String(err) });
 			throw err;
 		}
 	}),

package/src/pg-boss-handler-registry.d.ts

@@ -17,7 +17,7 @@ import type { ScheduledJobConfig } from "@teamscala/db-validation/registry-schem
 export type PgBossJobHandler = (ctx: {
     config: ScheduledJobConfig;
 }) => Promise<void> | void;
-export declare const pgBossHandlerRegistry: any;
+export declare const pgBossHandlerRegistry: import("@teamscala/generic-registry/create-registry").Registry<PgBossJobHandler>;
 /**
  * Register a handler for a `scheduled_job.handler_slug`. Idempotent on re-import
  * (createRegistry.register overwrites silently — last registration wins).

package/src/register-registry-page-route/graph-cache.d.ts

@@ -7,8 +7,8 @@ type GraphCache = {
         ttlMs?: number;
     }): void;
 };
-export declare const staticShellGraphCache: any;
-export declare const paramRouteGraphCache: any;
+export declare const staticShellGraphCache: import("@teamscala/cache/cache").ManagedCache<unknown>;
+export declare const paramRouteGraphCache: import("@teamscala/cache/cache").ManagedCache<unknown>;
 /**
  * Stale-while-revalidate read of a cached loader graph.
  *

package/src/resource-not-found.test.ts

@@ -0,0 +1,47 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Co-located tests for the resource-not-found public API: the error class +
+ * the response builder are pure (no S3), so the behaviour is exercised directly.
+ */
+import { describe, expect, it } from "bun:test";
+import { PrimaryResourceMissingError, buildResourceNotFoundResponse } from "./resource-not-found.ts";
+
+describe("PrimaryResourceMissingError", () => {
+	it("is an Error carrying resourceType + httpStatus", () => {
+		const err = new PrimaryResourceMissingError("project", 404);
+		expect(err).toBeInstanceOf(Error);
+		expect(err.resourceType).toBe("project");
+		expect(err.httpStatus).toBe(404);
+		expect(err.empty).toBe(false);
+		expect(err.message).toContain("project");
+	});
+
+	it("defaults httpStatus to 404 + supports the empty variant", () => {
+		const dead = new PrimaryResourceMissingError("roadmap");
+		expect(dead.httpStatus).toBe(404);
+		const empty = new PrimaryResourceMissingError("roadmap", 200, { empty: true });
+		expect(empty.httpStatus).toBe(200);
+		expect(empty.empty).toBe(true);
+	});
+});
+
+describe("buildResourceNotFoundResponse", () => {
+	it("returns a 404 Response for a dead link", () => {
+		const res = buildResourceNotFoundResponse("project");
+		expect(res).toBeInstanceOf(Response);
+		expect(res.status).toBe(404);
+	});
+
+	it("returns a 200 Response for the bare root (no resource selected)", () => {
+		const res = buildResourceNotFoundResponse("project", undefined, 200);
+		expect(res.status).toBe(200);
+	});
+
+	it("renders the empty-page surface when opts.empty", () => {
+		const res = buildResourceNotFoundResponse("project", undefined, 200, { empty: true });
+		expect(res.status).toBe(200);
+	});
+});

package/src/resource-not-found.ts

@@ -28,7 +28,7 @@
  * floor that must always exist.
  */
 
-import { getClient } from "@teamscala/aws/create/client/get-client";
+import { getClient } from "@teamscala/object-storage/create/client/get-client";
 import { createCache } from "@teamscala/cache/create-cache";
 import { getServerClient } from "@teamscala/orpc/server-client-registry";
 import { loadRegistryConfig } from "@teamscala/db/registry/load-config";