@oscharko-dev/keiko-server 0.2.7 → 0.2.9

package/dist/task-workspace/routes.js

@@ -0,0 +1,481 @@
+// BFF routes for managed task-workspace provisioning + activation (Issue #445, Epic #443).
+//
+//   POST /api/task-workspaces                     provision (create/resume) → { instance, binding }
+//   GET  /api/task-workspaces/:workspaceId        read one persisted instance
+//   POST /api/task-workspaces/:workspaceId/activate   activate/resume → { instance, binding }
+//
+// These are the controlled server-side mutating actions the Issue requires (no broad shell, no generic
+// Git runner). CSRF is enforced by the server's global state-changing-request gate for POST, exactly
+// like the command-runner routes; the GET is read-only. Domain failures map to the structured
+// TaskWorkspaceError taxonomy; the response body is redacted before it reaches the browser.
+import { isTaskWorkspaceLifecycleState, isWorkspaceRecoveryStrategy, } from "@oscharko-dev/keiko-contracts";
+import { errorBody } from "../routes.js";
+import { FilesError, resolveRoot } from "../files.js";
+import { TaskWorkspaceError } from "./errors.js";
+import { assertSafeFieldValue } from "./field-safety.js";
+const MAX_BODY_BYTES = 16_000;
+const MAX_FIELD_LENGTH = 512;
+class WorkspaceBodyTooLargeError extends Error {
+    constructor() {
+        super("task workspace request body too large");
+        this.name = "WorkspaceBodyTooLargeError";
+    }
+}
+function unavailable() {
+    return {
+        status: 503,
+        body: errorBody("WORKSPACE_PROVISIONING_UNAVAILABLE", "Task-workspace provisioning is not configured for this BFF."),
+    };
+}
+function requireService(deps) {
+    return deps.workspaceProvisioning ?? unavailable();
+}
+function requireLifecycle(deps) {
+    return deps.workspaceLifecycle ?? unavailable();
+}
+function requireReconciliation(deps) {
+    return deps.workspaceReconciliation ?? unavailable();
+}
+function requireRepair(deps) {
+    return deps.workspaceRepair ?? unavailable();
+}
+function requireHealth(deps) {
+    return deps.workspaceHealth ?? unavailable();
+}
+function requireCleanup(deps) {
+    return deps.workspaceCleanup ?? unavailable();
+}
+function isRouteResult(value) {
+    return typeof value.status === "number";
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let total = 0;
+        let capped = false;
+        req.on("data", (chunk) => {
+            total += chunk.length;
+            if (total > MAX_BODY_BYTES) {
+                if (!capped) {
+                    capped = true;
+                    chunks.length = 0;
+                    reject(new WorkspaceBodyTooLargeError());
+                    req.resume();
+                }
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => {
+            if (!capped)
+                resolve(Buffer.concat(chunks).toString("utf8"));
+        });
+        req.on("error", reject);
+    });
+}
+async function readJsonObject(req) {
+    const raw = await readBody(req);
+    if (raw.length === 0)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new TaskWorkspaceError("INVALID_REQUEST", "request body is not valid JSON");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new TaskWorkspaceError("INVALID_REQUEST", "request body must be a JSON object");
+    }
+    return parsed;
+}
+function boundedString(value) {
+    return typeof value === "string" && value.length > 0 && value.length <= MAX_FIELD_LENGTH
+        ? value
+        : undefined;
+}
+// Extract a REQUIRED free-form identity field (requestedBy / taskId): length-bounded AND free of
+// control / zero-width / bidirectional-override code points (#449 PR #1587 follow-up). These values
+// flow into the advisory lock owner, the active-pointer setBy, and operator-visible evidence, so the
+// route boundary rejects rather than strips them (see field-safety.ts). Missing/empty/oversized fields
+// keep the existing "missing or invalid field" message; a present-but-unsafe value throws a distinct
+// "forbidden characters" reason.
+function requireSafeField(value, field) {
+    const bounded = boundedString(value);
+    if (bounded === undefined) {
+        throw new TaskWorkspaceError("INVALID_REQUEST", `missing or invalid field: ${field}`);
+    }
+    assertSafeFieldValue(bounded, field);
+    return bounded;
+}
+// As requireSafeField, but for an OPTIONAL field: absent → undefined, present → must be safe.
+function optionalSafeField(value, field) {
+    if (value === undefined)
+        return undefined;
+    const bounded = boundedString(value);
+    if (bounded === undefined) {
+        throw new TaskWorkspaceError("INVALID_REQUEST", `missing or invalid field: ${field}`);
+    }
+    assertSafeFieldValue(bounded, field);
+    return bounded;
+}
+function mapError(error) {
+    if (error instanceof WorkspaceBodyTooLargeError) {
+        return {
+            status: 413,
+            body: errorBody("PAYLOAD_TOO_LARGE", "Request body exceeds the size limit."),
+        };
+    }
+    if (error instanceof TaskWorkspaceError) {
+        const detail = error.reasons.length > 0 ? `${error.message}: ${error.reasons.join("; ")}` : error.message;
+        // Surface the caller-facing failure class (#449, ADR-0093 D3) alongside the code so a BFF/UI caller
+        // can branch on a stable signal (retryable / repairable / blocked / policy-denied / terminal) instead
+        // of the raw code list. The base body stays the redacted { error: { code, message } } envelope.
+        const base = errorBody(error.code, detail);
+        return {
+            status: error.status,
+            body: { ...base, error: { ...base.error, failureClass: error.failureClass } },
+        };
+    }
+    if (error instanceof FilesError) {
+        return { status: error.status, body: errorBody(error.code, error.message) };
+    }
+    return undefined;
+}
+// Error responses are redacted with the SAME defense-in-depth scrubbing as success bodies, so a
+// future failure detail that ever carries a path/secret-shaped value cannot leak to the browser.
+async function runHandler(deps, work) {
+    try {
+        return await work();
+    }
+    catch (error) {
+        const mapped = mapError(error);
+        if (mapped === undefined)
+            throw error;
+        return { status: mapped.status, body: redacted(deps, mapped.body) };
+    }
+}
+function redacted(deps, value) {
+    return deps.redactor(value);
+}
+function parseProvisionBody(body) {
+    const root = boundedString(body.root);
+    const taskId = boundedString(body.taskId);
+    const baseBranch = boundedString(body.baseBranch);
+    const requestedBy = boundedString(body.requestedBy);
+    const missing = [];
+    if (root === undefined)
+        missing.push("root");
+    if (taskId === undefined)
+        missing.push("taskId");
+    if (baseBranch === undefined)
+        missing.push("baseBranch");
+    if (requestedBy === undefined)
+        missing.push("requestedBy");
+    if (root === undefined ||
+        taskId === undefined ||
+        baseBranch === undefined ||
+        requestedBy === undefined) {
+        throw new TaskWorkspaceError("INVALID_REQUEST", `missing or invalid fields: ${missing.join(", ")}`);
+    }
+    // The free-form identity fields additionally reject control / zero-width / bidi code points.
+    assertSafeFieldValue(taskId, "taskId");
+    assertSafeFieldValue(requestedBy, "requestedBy");
+    return { root, taskId, baseBranch, requestedBy };
+}
+function parseExpectedState(value) {
+    if (value === undefined)
+        return undefined;
+    if (!isTaskWorkspaceLifecycleState(value)) {
+        throw new TaskWorkspaceError("INVALID_REQUEST", "expectedLifecycleState is invalid");
+    }
+    return value;
+}
+// POST /api/task-workspaces — provision (create or resume) a managed task workspace.
+export async function handleProvisionTaskWorkspace(ctx, deps) {
+    const guard = requireService(deps);
+    if (isRouteResult(guard))
+        return guard;
+    return runHandler(deps, async () => {
+        const body = await readJsonObject(ctx.req);
+        const parsed = parseProvisionBody(body);
+        const resolvedRoot = await resolveRoot(deps.store, parsed.root, deps.redactor);
+        const request = {
+            repositoryRequestPath: resolvedRoot.realRoot,
+            taskId: parsed.taskId,
+            baseBranch: parsed.baseBranch,
+            requestedBy: parsed.requestedBy,
+        };
+        const result = await guard.provision(request);
+        return {
+            status: result.created ? 201 : 200,
+            body: redacted(deps, {
+                instance: result.instance,
+                binding: result.binding,
+                created: result.created,
+            }),
+        };
+    });
+}
+// GET /api/task-workspaces/:workspaceId — read one persisted WorkspaceInstance.
+export function handleGetTaskWorkspace(ctx, deps) {
+    const guard = requireService(deps);
+    if (isRouteResult(guard))
+        return guard;
+    const workspaceId = ctx.params.workspaceId ?? "";
+    const instance = guard.getInstance(workspaceId);
+    if (instance === undefined) {
+        return { status: 404, body: errorBody("WORKSPACE_NOT_FOUND", "Task workspace not found.") };
+    }
+    return { status: 200, body: redacted(deps, { instance }) };
+}
+// POST /api/task-workspaces/:workspaceId/activate — activate/resume a workspace and yield its binding.
+export async function handleActivateTaskWorkspace(ctx, deps) {
+    const guard = requireService(deps);
+    if (isRouteResult(guard))
+        return guard;
+    return runHandler(deps, async () => {
+        const workspaceId = ctx.params.workspaceId ?? "";
+        const body = await readJsonObject(ctx.req);
+        const requestedBy = requireSafeField(body.requestedBy, "requestedBy");
+        const expectedLifecycleState = parseExpectedState(body.expectedLifecycleState);
+        const request = {
+            workspaceId,
+            taskId: optionalSafeField(body.taskId, "taskId") ?? "",
+            requestedBy,
+            acquireLock: body.acquireLock === true,
+            ...(expectedLifecycleState !== undefined ? { expectedLifecycleState } : {}),
+        };
+        const result = await guard.activate(request);
+        return {
+            status: 200,
+            body: redacted(deps, { instance: result.instance, binding: result.binding }),
+        };
+    });
+}
+// ─── #446 active-binding + lifecycle routes ──────────────────────────────────────────────────────
+// The shared active-workspace binding the Studio/editor/runtime/Git-Delivery surfaces consume. These
+// are registered BEFORE `GET /api/task-workspaces/:workspaceId` so the literal `active` and the
+// collection (`?root`) paths win over the `:workspaceId` param route.
+function parseLifecycleActionBody(workspaceId, body) {
+    const requestedBy = requireSafeField(body.requestedBy, "requestedBy");
+    return { workspaceId, requestedBy };
+}
+// GET /api/task-workspaces?root=<repoRoot> — list the persisted instances for a repository root.
+export async function handleListTaskWorkspaces(ctx, deps) {
+    const guard = requireLifecycle(deps);
+    if (isRouteResult(guard))
+        return guard;
+    return runHandler(deps, async () => {
+        const rootInput = ctx.url.searchParams.get("root");
+        const resolvedRoot = await resolveRoot(deps.store, rootInput, deps.redactor);
+        const instances = guard.list(resolvedRoot.realRoot);
+        return { status: 200, body: redacted(deps, { instances }) };
+    });
+}
+// GET /api/task-workspaces/active — the current active binding, or null in unbound mode.
+export function handleGetActiveTaskWorkspace(_ctx, deps) {
+    const guard = requireLifecycle(deps);
+    if (isRouteResult(guard))
+        return guard;
+    return { status: 200, body: redacted(deps, { active: guard.getActive() ?? null }) };
+}
+// POST /api/task-workspaces/active — atomic switch: activate/resume the target and set it active.
+export async function handleSetActiveTaskWorkspace(ctx, deps) {
+    const guard = requireLifecycle(deps);
+    if (isRouteResult(guard))
+        return guard;
+    return runHandler(deps, async () => {
+        const body = await readJsonObject(ctx.req);
+        const workspaceId = boundedString(body.workspaceId);
+        const requestedBy = boundedString(body.requestedBy);
+        if (workspaceId === undefined || requestedBy === undefined) {
+            throw new TaskWorkspaceError("INVALID_REQUEST", "missing or invalid fields: workspaceId, requestedBy");
+        }
+        // requestedBy is persisted as the active-pointer setBy — reject control/zero-width/bidi chars.
+        assertSafeFieldValue(requestedBy, "requestedBy");
+        const result = await guard.setActive({
+            workspaceId,
+            requestedBy,
+            acquireLock: body.acquireLock === true,
+        });
+        return {
+            status: 200,
+            body: redacted(deps, { instance: result.instance, binding: result.binding }),
+        };
+    });
+}
+// DELETE /api/task-workspaces/active — clear the active pointer → unbound mode.
+export function handleClearActiveTaskWorkspace(_ctx, deps) {
+    const guard = requireLifecycle(deps);
+    if (isRouteResult(guard))
+        return guard;
+    guard.clearActive();
+    return { status: 200, body: redacted(deps, { active: null }) };
+}
+async function runLifecycleAction(ctx, deps, pick) {
+    const guard = requireLifecycle(deps);
+    if (isRouteResult(guard))
+        return guard;
+    return runHandler(deps, async () => {
+        const workspaceId = ctx.params.workspaceId ?? "";
+        const body = await readJsonObject(ctx.req);
+        const request = parseLifecycleActionBody(workspaceId, body);
+        const result = await pick(guard)(request);
+        return {
+            status: 200,
+            body: redacted(deps, { instance: result.instance, binding: result.binding }),
+        };
+    });
+}
+// POST /api/task-workspaces/:workspaceId/pause — active → paused (clears the pointer if it was active).
+export function handlePauseTaskWorkspace(ctx, deps) {
+    return runLifecycleAction(ctx, deps, (lifecycle) => lifecycle.pause);
+}
+// POST /api/task-workspaces/:workspaceId/resume — paused → active (sets the pointer).
+export function handleResumeTaskWorkspace(ctx, deps) {
+    return runLifecycleAction(ctx, deps, (lifecycle) => lifecycle.resume);
+}
+// POST /api/task-workspaces/:workspaceId/handoff — active|paused → handoff-ready (requires clean worktree).
+export function handleHandoffTaskWorkspace(ctx, deps) {
+    return runLifecycleAction(ctx, deps, (lifecycle) => lifecycle.prepareHandoff);
+}
+// ─── #447 reconciliation + repair routes ───────────────────────────────────────────────────────
+// A `root` of undefined reconciles/reports across ALL repositories; a provided root scopes to one
+// repository (resolved + realpath'd through the same containment as the other routes).
+async function resolveOptionalRoot(deps, rootInput) {
+    if (rootInput === null || rootInput === undefined || rootInput.length === 0)
+        return undefined;
+    const resolved = await resolveRoot(deps.store, rootInput, deps.redactor);
+    return resolved.realRoot;
+}
+// GET /api/task-workspaces/reconciliation[?root=<repoRoot>] — read-only reconciliation report derived
+// from the persisted (content-free) instance fields, no filesystem/git IO.
+export async function handleGetTaskWorkspaceReconciliation(ctx, deps) {
+    const guard = requireReconciliation(deps);
+    if (isRouteResult(guard))
+        return guard;
+    return runHandler(deps, async () => {
+        const root = await resolveOptionalRoot(deps, ctx.url.searchParams.get("root"));
+        const report = guard.report(root);
+        return { status: 200, body: redacted(deps, { report }) };
+    });
+}
+// POST /api/task-workspaces/reconciliation — run a live reconciliation pass (verifies disk + git,
+// persists the classification) and return the fresh report. CSRF is enforced for this POST.
+export async function handleReconcileTaskWorkspaces(ctx, deps) {
+    const guard = requireReconciliation(deps);
+    if (isRouteResult(guard))
+        return guard;
+    return runHandler(deps, async () => {
+        const body = await readJsonObject(ctx.req);
+        const root = await resolveOptionalRoot(deps, optionalSafeField(body.root, "root"));
+        const report = await guard.reconcile(root);
+        return { status: 200, body: redacted(deps, { report }) };
+    });
+}
+function parseRepairStrategy(value) {
+    if (!isWorkspaceRecoveryStrategy(value)) {
+        throw new TaskWorkspaceError("INVALID_REQUEST", "missing or invalid field: strategy");
+    }
+    return value;
+}
+// POST /api/task-workspaces/:workspaceId/repair — controlled, operator-approval-gated repair.
+export async function handleRepairTaskWorkspace(ctx, deps) {
+    const guard = requireRepair(deps);
+    if (isRouteResult(guard))
+        return guard;
+    return runHandler(deps, async () => {
+        const workspaceId = ctx.params.workspaceId ?? "";
+        const body = await readJsonObject(ctx.req);
+        const requestedBy = requireSafeField(body.requestedBy, "requestedBy");
+        const result = await guard.repair({
+            workspaceId,
+            requestedBy,
+            strategy: parseRepairStrategy(body.strategy),
+            operatorApproved: body.operatorApproved === true,
+        });
+        return {
+            status: 200,
+            body: redacted(deps, {
+                instance: result.instance,
+                binding: result.binding,
+                strategy: result.strategy,
+                applied: result.applied,
+                outcome: result.outcome,
+                status: result.status,
+                driftMarkers: result.driftMarkers,
+                operatorActionRequired: result.operatorActionRequired,
+            }),
+        };
+    });
+}
+// ─── #448 health + governed cleanup routes ──────────────────────────────────────────────────────
+// The literal `health` and `cleanup/orphans` paths are registered BEFORE `:workspaceId` so they win by
+// literal-segment specificity. A `root` of undefined scopes health/orphan-cleanup across ALL managed
+// repositories; a provided root scopes to one (resolved + realpath'd through the same containment).
+// GET /api/task-workspaces/health[?root=<repoRoot>] — content-free operational health + drift + orphan
+// report (read-only; live filesystem + git probing, no persistence).
+export async function handleGetTaskWorkspaceHealth(ctx, deps) {
+    const guard = requireHealth(deps);
+    if (isRouteResult(guard))
+        return guard;
+    return runHandler(deps, async () => {
+        const root = await resolveOptionalRoot(deps, ctx.url.searchParams.get("root"));
+        const report = await guard.report(root);
+        return { status: 200, body: redacted(deps, { report }) };
+    });
+}
+function parseCleanupMode(value) {
+    if (value === "request" || value === "complete")
+        return value;
+    throw new TaskWorkspaceError("INVALID_REQUEST", "missing or invalid field: mode (expected 'request' or 'complete')");
+}
+// POST /api/task-workspaces/:workspaceId/cleanup — request (settled → cleanup-pending) or complete
+// (governed, live-verified physical removal). Operator-approval gated; CSRF inherited.
+export async function handleCleanupTaskWorkspace(ctx, deps) {
+    const guard = requireCleanup(deps);
+    if (isRouteResult(guard))
+        return guard;
+    return runHandler(deps, async () => {
+        const workspaceId = ctx.params.workspaceId ?? "";
+        const body = await readJsonObject(ctx.req);
+        const requestedBy = requireSafeField(body.requestedBy, "requestedBy");
+        const result = await guard.cleanup({
+            workspaceId,
+            requestedBy,
+            operatorApproved: body.operatorApproved === true,
+            mode: parseCleanupMode(body.mode),
+        });
+        return {
+            status: 200,
+            body: redacted(deps, {
+                outcome: result.outcome,
+                workspaceId: result.workspaceId,
+                ...(result.instance !== undefined ? { instance: result.instance } : {}),
+                ...(result.refusalReason !== undefined ? { refusalReason: result.refusalReason } : {}),
+            }),
+        };
+    });
+}
+// POST /api/task-workspaces/cleanup/orphans — governed removal of orphaned managed worktrees (on-disk
+// directories with no persisted record). Operator-approval gated; CSRF inherited.
+export async function handleCleanupOrphanTaskWorkspaces(ctx, deps) {
+    const guard = requireCleanup(deps);
+    if (isRouteResult(guard))
+        return guard;
+    return runHandler(deps, async () => {
+        const body = await readJsonObject(ctx.req);
+        const requestedBy = requireSafeField(body.requestedBy, "requestedBy");
+        const root = await resolveOptionalRoot(deps, optionalSafeField(body.root, "root"));
+        const result = await guard.cleanupOrphans({
+            ...(root !== undefined ? { repositoryRoot: root } : {}),
+            requestedBy,
+            operatorApproved: body.operatorApproved === true,
+        });
+        return {
+            status: 200,
+            body: redacted(deps, { removed: result.removed, refused: result.refused }),
+        };
+    });
+}

package/dist/task-workspace/store.d.ts

@@ -0,0 +1,12 @@
+import type { DatabaseSync } from "node:sqlite";
+import { type WorkspaceInstance } from "@oscharko-dev/keiko-contracts";
+export interface WorkspaceInstanceStore {
+    readonly getById: (workspaceId: string) => WorkspaceInstance | undefined;
+    readonly findByRepositoryAndTask: (repositoryId: string, taskId: string) => WorkspaceInstance | undefined;
+    readonly listByRepository: (repositoryId: string) => readonly WorkspaceInstance[];
+    readonly listAll: () => readonly WorkspaceInstance[];
+    readonly upsert: (instance: WorkspaceInstance) => WorkspaceInstance;
+    readonly delete: (workspaceId: string) => void;
+}
+export declare function buildWorkspaceInstanceStoreOverDatabase(db: DatabaseSync): WorkspaceInstanceStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/task-workspace/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/task-workspace/store.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAKL,KAAK,iBAAiB,EAGvB,MAAM,+BAA+B,CAAC;AAEvC,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,iBAAiB,GAAG,SAAS,CAAC;IACzE,QAAQ,CAAC,uBAAuB,EAAE,CAChC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,KACX,iBAAiB,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,gBAAgB,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,SAAS,iBAAiB,EAAE,CAAC;IAIlF,QAAQ,CAAC,OAAO,EAAE,MAAM,SAAS,iBAAiB,EAAE,CAAC;IACrD,QAAQ,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,iBAAiB,KAAK,iBAAiB,CAAC;IACpE,QAAQ,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;CAChD;AAyHD,wBAAgB,uCAAuC,CAAC,EAAE,EAAE,YAAY,GAAG,sBAAsB,CAmChG"}

package/dist/task-workspace/store.js

@@ -0,0 +1,128 @@
+// Durable persistence for managed task-workspace instances (Issue #445, Epic #443).
+//
+// A dedicated store composed over the SAME node:sqlite DatabaseSync handle as the UI store and the
+// relationship engine (schema.ts §V7), mirroring the relationship-store composition pattern so the
+// V7 sibling table shares the single-writer transaction model. The store is the durable home for the
+// `WorkspaceInstance` the contract defines; #446 (binding) and #447 (reconcile/repair) read and
+// extend it without a second persistence layer.
+//
+// Every write is gated by the contract's `validateWorkspaceInstance` (content-free closed allowlist,
+// SC3) and every read re-validates the reconstructed row, so a corrupt or smuggled record can neither
+// be stored nor silently trusted on the way out. The unique (repository_id, task_id) index enforces
+// the idempotency invariant at the DB layer (AC3).
+import { validateWorkspaceInstance, } from "@oscharko-dev/keiko-contracts";
+const COLUMNS = `
+  workspace_id, schema_version, task_id, repository_id, repository_root, base_branch, task_branch,
+  managed_worktree_path, gitdir_identity, lifecycle_state, health, lock_json, created_at, updated_at,
+  last_verified_at, last_verified_head, drift_markers_json, recovery_hints_json, audit_correlation_id
+`;
+const SQL_GET_BY_ID = `SELECT ${COLUMNS} FROM task_workspace_instances WHERE workspace_id = ?`;
+const SQL_FIND_BY_REPO_TASK = `SELECT ${COLUMNS} FROM task_workspace_instances WHERE repository_id = ? AND task_id = ?`;
+const SQL_LIST_BY_REPO = `SELECT ${COLUMNS} FROM task_workspace_instances WHERE repository_id = ? ORDER BY updated_at DESC, workspace_id`;
+const SQL_LIST_ALL = `SELECT ${COLUMNS} FROM task_workspace_instances ORDER BY updated_at DESC, workspace_id`;
+const SQL_DELETE = "DELETE FROM task_workspace_instances WHERE workspace_id = ?";
+const SQL_UPSERT = `
+INSERT INTO task_workspace_instances (${COLUMNS})
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ON CONFLICT(workspace_id) DO UPDATE SET
+  schema_version = excluded.schema_version,
+  task_id = excluded.task_id,
+  repository_id = excluded.repository_id,
+  repository_root = excluded.repository_root,
+  base_branch = excluded.base_branch,
+  task_branch = excluded.task_branch,
+  managed_worktree_path = excluded.managed_worktree_path,
+  gitdir_identity = excluded.gitdir_identity,
+  lifecycle_state = excluded.lifecycle_state,
+  health = excluded.health,
+  lock_json = excluded.lock_json,
+  created_at = excluded.created_at,
+  updated_at = excluded.updated_at,
+  last_verified_at = excluded.last_verified_at,
+  last_verified_head = excluded.last_verified_head,
+  drift_markers_json = excluded.drift_markers_json,
+  recovery_hints_json = excluded.recovery_hints_json,
+  audit_correlation_id = excluded.audit_correlation_id
+RETURNING ${COLUMNS}
+`;
+function parseJsonArray(json) {
+    const parsed = JSON.parse(json);
+    return Array.isArray(parsed) ? parsed : [];
+}
+function rowToInstance(row) {
+    const lock = row.lock_json === null ? null : JSON.parse(row.lock_json);
+    const instance = {
+        schemaVersion: row.schema_version,
+        workspaceId: row.workspace_id,
+        taskId: row.task_id,
+        repositoryId: row.repository_id,
+        repositoryRoot: row.repository_root,
+        baseBranch: row.base_branch,
+        taskBranch: row.task_branch,
+        managedWorktreePath: row.managed_worktree_path,
+        gitdirIdentity: row.gitdir_identity,
+        lifecycleState: row.lifecycle_state,
+        health: row.health,
+        lock,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        ...(row.last_verified_at !== null ? { lastVerifiedAt: row.last_verified_at } : {}),
+        ...(row.last_verified_head !== null ? { lastVerifiedHead: row.last_verified_head } : {}),
+        driftMarkers: parseJsonArray(row.drift_markers_json),
+        recoveryHints: parseJsonArray(row.recovery_hints_json),
+        auditCorrelationId: row.audit_correlation_id,
+    };
+    const validation = validateWorkspaceInstance(instance);
+    if (!validation.ok) {
+        throw new Error(`persisted task-workspace instance is invalid (${row.workspace_id}): ${validation.reasons.join("; ")}`);
+    }
+    return instance;
+}
+function upsertParams(instance) {
+    return [
+        instance.workspaceId,
+        instance.schemaVersion,
+        instance.taskId,
+        instance.repositoryId,
+        instance.repositoryRoot,
+        instance.baseBranch,
+        instance.taskBranch,
+        instance.managedWorktreePath,
+        instance.gitdirIdentity,
+        instance.lifecycleState,
+        instance.health,
+        instance.lock === null ? null : JSON.stringify(instance.lock),
+        instance.createdAt,
+        instance.updatedAt,
+        instance.lastVerifiedAt ?? null,
+        instance.lastVerifiedHead ?? null,
+        JSON.stringify(instance.driftMarkers),
+        JSON.stringify(instance.recoveryHints),
+        instance.auditCorrelationId,
+    ];
+}
+export function buildWorkspaceInstanceStoreOverDatabase(db) {
+    return {
+        getById: (workspaceId) => {
+            const row = db.prepare(SQL_GET_BY_ID).get(workspaceId);
+            return row === undefined ? undefined : rowToInstance(row);
+        },
+        findByRepositoryAndTask: (repositoryId, taskId) => {
+            const row = db.prepare(SQL_FIND_BY_REPO_TASK).get(repositoryId, taskId);
+            return row === undefined ? undefined : rowToInstance(row);
+        },
+        listByRepository: (repositoryId) => db.prepare(SQL_LIST_BY_REPO).all(repositoryId).map(rowToInstance),
+        listAll: () => db.prepare(SQL_LIST_ALL).all().map(rowToInstance),
+        upsert: (instance) => {
+            const validation = validateWorkspaceInstance(instance);
+            if (!validation.ok) {
+                throw new Error(`refusing to persist invalid workspace instance: ${validation.reasons.join("; ")}`);
+            }
+            const row = db.prepare(SQL_UPSERT).get(...upsertParams(instance));
+            return rowToInstance(row);
+        },
+        delete: (workspaceId) => {
+            db.prepare(SQL_DELETE).run(workspaceId);
+        },
+    };
+}