@teamscala/service-boot 0.23.284 → 0.23.285

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

@@ -0,0 +1,376 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * CLI-AGNOSTIC task-sync CORE — the bridge between a lane's native task list
+ * (Claude Code TodoWrite, OpenCode todowrite, future CLIs) and the `work_items`
+ * table, which is the single source of truth for "what work does this lane
+ * have." Detailed contract + the per-CLI adapter split: apps/agent-fleet.md
+ * (task-sync section).
+ *
+ * Design (operator requirement): work_items is the source; each CLI's task list
+ * is a WRITE-THROUGH PROJECTION, never a peer. One source + write-through
+ * projection cannot diverge by construction — no two-way sync, no conflict
+ * resolution. The lane↔task binding is SYMMETRIC: a lane is a lane whether the
+ * pane is an orchestrator or a supervised agent (both have tasks).
+ *
+ * Mapping: an operator request = a kind='task' work_item; the lane's todo items
+ * = kind='subtask' rows under it via parent_id. The task carries the lane
+ * identity in kind_data.lane = { pane, session, cli_kind, role } so any surface
+ * (fleet UI, another lane) can resolve "who owns this work" and push changes
+ * back. Binding is by pane identity (the stable $TMUX_PANE), not by fleet run —
+ * so it works before/without the fleet_agent_runs.work_item_id join (that column
+ * is a UI convenience for the unified lane+task+subtask view, not a dependency).
+ *
+ * These procedures are the ONLY CLI-agnostic surface an adapter calls:
+ *   bindLane           — bind (create-or-confirm) a lane's task. SessionStart.
+ *   upsertFromTaskList — write a lane's current task list through to subtasks (AGENT→DB leg, OpenCode whole-list).
+ *   upsertFromTaskHook — apply a per-item Claude Code PostToolUse:TaskCreate/Update/Delete (AGENT→DB leg, Claude per-item).
+ *   readTaskList       — read a lane's current subtasks as a normalized list (DB→AGENT backstop).
+ *   applyExternalChange — record an out-of-band subtask change + notify the owning lane (DB→AGENT realtime leg).
+ * A CLI with no native task surface (Codex today — upstream_issue openai-codex-2966)
+ * has NO adapter: it degrades to work_items-only. The work is still tracked and
+ * visible in the projects UI; the lane simply has no live projection. That is a
+ * legitimate end state, not a gap to paper over with a fake adapter.
+ */
+import { type Context } from "./auth-router.ts";
+import * as v from "valibot";
+/** A lane's native task-list item, normalized. Every CLI adapter maps to this. */
+export interface TaskListItem {
+    content: string;
+    status: "pending" | "in_progress" | "completed";
+    /** CLI-native stable id when the CLI provides one (TodoWrite has none; opencode todo row id). */
+    mark?: string;
+}
+/**
+ * Input contract for upsertFromTaskList. oRPC does NOT parse the JSON body into
+ * `input` for a schema-less procedure (see the bindLane comment in this file) —
+ * so without an explicit `.input()` schema, `input.lane_session` is ALWAYS
+ * undefined and the procedure throws "requires lane_session" unconditionally.
+ * Measured 2026-07-29: every pi/opencode whole-list `task_list` publish 400'd
+ * for exactly this reason (the per-item upsertFromTaskHook path worked because
+ * it unwraps `raw.json ?? raw`). Declaring the schema is the documented remedy
+ * and the pattern every other `authed.input(...)` procedure in service-boot
+ * already follows. The pi adapter (scala-hooks.ts syncTaskList) already sends
+ * `{ lane_session, task_list, source }` — it was always valid; the server never
+ * read it.
+ */
+export declare const upsertFromTaskListInput: v.ObjectSchema<{
+    readonly lane_session: v.StringSchema<undefined>;
+    readonly task_list: v.ArraySchema<v.ObjectSchema<{
+        readonly content: v.StringSchema<undefined>;
+        readonly status: v.PicklistSchema<["pending", "in_progress", "completed"], undefined>;
+        readonly mark: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    readonly source: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+/** Who a lane IS — symmetric across orchestrator/agent roles and across CLIs. */
+export interface LaneIdentity {
+    /** "tmux:%42" — authoritative pane identity ($TMUX_PANE). */
+    pane: string;
+    session?: string;
+    /** pane-inventory inferCliKind: claude-code | opencode | codex | unknown. */
+    cli_kind?: string;
+    /** agent | orchestrator — both have tasks; the model does not assume a supervised agent. */
+    role?: string;
+    /**
+     * Optional. work_items.organisation_id is NOT NULL; when the caller omits it
+     * (auto-bind at SessionStart — an adopted or channel-dispatched lane has no
+     * client org), bindLane defaults to the platform org via resolveBindOrg.
+     */
+    organisation_id?: string;
+}
+interface WorkItem {
+    id: string;
+    kind: string;
+    parent_id: string | null;
+    organisation_id: string;
+    title: string;
+    status: string | null;
+    position: string | null;
+    completed: boolean | null;
+    kind_data: Record<string, unknown>;
+}
+/**
+ * A dispatched run already points at its fleet_tasks row. Task-sync may fill
+ * the convenience join for an adopted lane, but must never replace that
+ * dispatch identity with the lane's work_items projection id.
+ */
+export declare function untrackedRunForPane(pane: string): {
+    pane: string;
+    state: {
+        not: 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
+ * otherwise — an adopted or channel-dispatched pane has no client org, and the
+ * platform org is the home for fleet/internal lane tasks (where the operator's
+ * PM view reads), so auto-bind at SessionStart seeds the task there.
+ */
+export declare function resolveBindOrg(explicit?: string): string;
+/**
+ * Record a task-sync hook DISCARD to event_log so it is observable + queryable,
+ * not silently swallowed by the hook command's `>/dev/null 2>&1 || true`. The
+ * endpoint records it server-side regardless of what the hook does with stdout.
+ * Fire-and-forget per event-log-is-the-only-durable-event-log. The headline
+ * discard is "no-task-bound" (lane has no bound parent task — exactly the gap
+ * that SessionStart auto-bind closes; once binding is automatic this becomes a
+ * rare safety signal rather than the default outcome).
+ */
+export declare function recordTaskSyncDiscard(reason: string, pane: string | null, extra?: Record<string, unknown>): void;
+/**
+ * Record a discard AND return the soft {applied:false} body in one step — every
+ * no-op path in upsertFromTaskHook goes through here so none can silently drop
+ * an event. The returned shape matches the prior `{applied:false, reason,...}`.
+ */
+export declare function discardApplied(reason: string, pane: string | null, extra?: Record<string, unknown>): {
+    applied: false;
+    reason: string;
+} & Record<string, unknown>;
+/**
+ * Trim a task subject at the first tool-call marker.
+ *
+ * A subject arriving as `Cut judge false positives</subject>\n<parameter
+ * name="description">Live gate blocks ~half...` is not a title with odd
+ * punctuation — it is the raw tool call, and it renders on the dashboard as a
+ * wall of XML where the operator expects a task name (observed live 2026-07-25,
+ * 3 rows). The malformation happens upstream in the CLI's hook payload, which
+ * this service does not control, so the defence belongs at the WRITE boundary:
+ * `work_items` is the single source of truth for every surface, and once a
+ * corrupted title lands there every reader shows it.
+ *
+ * Truncating rather than rejecting is deliberate: the text BEFORE the marker is
+ * the real subject and is worth keeping. Dropping the row instead would lose a
+ * task the lane genuinely created.
+ */
+export declare function sanitizeTaskSubject(raw: string): string;
+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
+     * adapter so the lane has a durable task row before its first todo write.
+     * Idempotent: re-binding updates the identity (role/cli_kind can change) but
+     * never orphans existing subtasks. After binding, links the lane's
+     * fleet_agent_runs row (matched by pane) to the task via tracked_task_id —
+     * the join the operator's lane-labels monitor + the unified fleet view read.
+     */
+    bindLane: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
+        headers: Headers;
+        resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
+        prisma: any;
+        user: import("./auth-router.ts").User;
+        orgId: string | null | undefined;
+    }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
+        task_id: string;
+        created: boolean;
+    }, {
+        task_id: string;
+        created: boolean;
+    }>, Record<never, never>, Record<never, never>>;
+    /**
+     * AGENT→DB leg. Write a lane's CURRENT task list through to subtasks. The
+     * list is authoritative for this lane (it's what the CLI just rendered), so
+     * this is a full reconcile: create/update/delete to match. Matching is by
+     * stable mark when the CLI provides one, else by content. Does NOT dispatch
+     * a change notification — the lane that authored the list already has it.
+     */
+    upsertFromTaskList: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
+        headers: Headers;
+        resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
+        prisma: any;
+        user: import("./auth-router.ts").User;
+        orgId: string | null | undefined;
+    }>, v.ObjectSchema<{
+        readonly lane_session: v.StringSchema<undefined>;
+        readonly task_list: v.ArraySchema<v.ObjectSchema<{
+            readonly content: v.StringSchema<undefined>;
+            readonly status: v.PicklistSchema<["pending", "in_progress", "completed"], undefined>;
+            readonly mark: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>, undefined>;
+        readonly source: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, import("@orpc/contract").Schema<{
+        task_id: string;
+        created: number;
+        updated: number;
+        deleted: number;
+        total: number;
+    }, {
+        task_id: string;
+        created: number;
+        updated: number;
+        deleted: number;
+        total: number;
+    }>, Record<never, never>, Record<never, never>>;
+    /**
+     * Claude Code PostToolUse:TaskCreate/TaskUpdate hook entry. Claude Code's
+     * todo tool is the per-item Task* family (TaskCreate/TaskUpdate) — TodoWrite
+     * was REMOVED in recent Claude Code; the hook matcher keys on
+     * TaskCreate/TaskUpdate, never TodoWrite. The hook command posts the RAW hook
+     * event (stdin) + an x-lane-pane header (tmux:$TMUX_PANE). Fired as a
+     * PostToolUse:TaskCreate/Update hook (NOT a "TaskCreated" event — that is
+     * not a real Claude Code hook event + never fired); this procedure
+     * applies the per-item change (TaskCreate → new subtask keyed by the harness
+     * task id; TaskUpdate → status/title flip on the matching subtask). Server-
+     * side extraction keeps the hook command a trivial jq|curl. Accepts the event
+     * raw (input.tool_name) OR oRPC-enveloped (input.json.tool_name). Session-
+     * less: fn.taskSync is page-gate-exempt; localhost pane shell authenticates
+     * as super-admin via resolveUser. Soft-returns on any no-op (never throws).
+     */
+    upsertFromTaskHook: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
+        headers: Headers;
+        resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
+        prisma: any;
+        user: import("./auth-router.ts").User;
+        orgId: string | null | undefined;
+    }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
+        applied: boolean;
+        op: string;
+        taskId: string;
+    } | ({
+        applied: false;
+        reason: string;
+    } & Record<string, unknown>), {
+        applied: boolean;
+        op: string;
+        taskId: string;
+    } | ({
+        applied: false;
+        reason: string;
+    } & Record<string, unknown>)>, Record<never, never>, Record<never, never>>;
+    /**
+     * DB→AGENT backstop read. Returns the lane's current subtasks in the
+     * normalized shape every CLI adapter maps to its native list. Called by the
+     * SessionStart/UserPromptSubmit adapters so a pane never opens or continues
+     * on stale tasks, and by a lane after it receives a "your tasks changed"
+     * channel notification.
+     */
+    readTaskList: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
+        headers: Headers;
+        resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
+        prisma: any;
+        user: import("./auth-router.ts").User;
+        orgId: string | null | undefined;
+    }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
+        task_id: null;
+        task_title: null;
+        subtasks: never[];
+    } | {
+        task_id: string;
+        task_title: string;
+        subtasks: TaskListItem[];
+    }, {
+        task_id: null;
+        task_title: null;
+        subtasks: never[];
+    } | {
+        task_id: string;
+        task_title: string;
+        subtasks: TaskListItem[];
+    }>, Record<never, never>, Record<never, never>>;
+    /**
+     * DB→AGENT realtime leg (explicit dispatch path). Record an out-of-band
+     * change to a subtask's status (operator toggles it in the projects UI,
+     * another lane edits a shared task) and notify the OWNING lane's pane that
+     * its projection is stale. The pane's adapter re-reads (readTaskList) and
+     * updates its native list. Symmetric counterpart to upsertFromTaskList:
+     * there the lane is the originator (no self-echo); here the lane is the
+     * recipient.
+     *
+     * COMPLETION STEP (not MVP): this procedure is the explicit trigger. For
+     * FULL coverage — every work_items subtask write, including the projects
+     * UI's generated CRUD — a Postgres trigger + LISTEN subscriber on
+     * scala-channel fires the same publish, so an operator edit reaches the
+     * lane with no explicit call. Tracked in apps/agent-fleet.md task-sync.
+     */
+    applyExternalChange: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
+        headers: Headers;
+        resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
+        prisma: any;
+        user: import("./auth-router.ts").User;
+        orgId: string | null | undefined;
+    }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
+        task_id: string;
+        lane_pane: string | null;
+        notified: boolean;
+    }, {
+        task_id: string;
+        lane_pane: string | null;
+        notified: boolean;
+    }>, Record<never, never>, Record<never, never>>;
+};
+export {};

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

@@ -16,7 +16,9 @@ import {
 	subtaskKey,
 	STATUS_TO_WORK_ITEM,
 	type TaskListItem,
+	upsertFromTaskListInput,
 } from "./task-sync-router.ts";
+import * as v from "valibot";
 
 interface WorkItemLike {
 	id: string;
@@ -277,3 +279,33 @@ describe("a rename cannot orphan an unmarked subtask", () => {
 		expect(src).toContain("...priorSync");
 	});
 });
+
+// --- upsertFromTaskList input schema (added 2026-07-29) ---------------------
+// The gap this closes: upsertFromTaskList read `input.lane_session`, but oRPC
+// leaves `input` empty for a schema-less procedure, so EVERY whole-list publish
+// 400'd with "requires lane_session" — confirmed by curl (a body containing
+// lane_session still 400'd). The pi/opencode adapter was always sending a valid
+// payload; the server never parsed it. Adding `.input()` is the fix.
+describe("task-sync upsertFromTaskListInput schema", () => {
+	it("accepts a valid whole-list payload (the pi/opencode adapter shape)", () => {
+		const out = v.parse(upsertFromTaskListInput, {
+			lane_session: "ses-1",
+			task_list: [{ content: "Do X", status: "in_progress" }],
+			source: "pi",
+		});
+		expect(out.lane_session).toBe("ses-1");
+		expect(out.task_list).toHaveLength(1);
+	});
+
+	it("accepts an optional mark on items", () => {
+		const out = v.parse(upsertFromTaskListInput, {
+			lane_session: "ses-1",
+			task_list: [{ content: "Do X", status: "pending", mark: "m1" }],
+		});
+		expect(out.task_list[0].mark).toBe("m1");
+	});
+
+	it("rejects a payload missing lane_session (the field the procedure requires)", () => {
+		expect(() => v.parse(upsertFromTaskListInput, { task_list: [] })).toThrow();
+	});
+});

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

@@ -40,6 +40,7 @@ import { recordEvent } from "@teamscala/event-log/record-event";
 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";
 
 /** A lane's native task-list item, normalized. Every CLI adapter maps to this. */
 export interface TaskListItem {
@@ -49,6 +50,31 @@ export interface TaskListItem {
 	mark?: string;
 }
 
+/**
+ * Input contract for upsertFromTaskList. oRPC does NOT parse the JSON body into
+ * `input` for a schema-less procedure (see the bindLane comment in this file) —
+ * so without an explicit `.input()` schema, `input.lane_session` is ALWAYS
+ * undefined and the procedure throws "requires lane_session" unconditionally.
+ * Measured 2026-07-29: every pi/opencode whole-list `task_list` publish 400'd
+ * for exactly this reason (the per-item upsertFromTaskHook path worked because
+ * it unwraps `raw.json ?? raw`). Declaring the schema is the documented remedy
+ * and the pattern every other `authed.input(...)` procedure in service-boot
+ * already follows. The pi adapter (scala-hooks.ts syncTaskList) already sends
+ * `{ lane_session, task_list, source }` — it was always valid; the server never
+ * read it.
+ */
+export const upsertFromTaskListInput = v.object({
+	lane_session: v.string(),
+	task_list: v.array(
+		v.object({
+			content: v.string(),
+			status: v.picklist(["pending", "in_progress", "completed"]),
+			mark: v.optional(v.string()),
+		}),
+	),
+	source: v.optional(v.string()),
+});
+
 /** Who a lane IS — symmetric across orchestrator/agent roles and across CLIs. */
 export interface LaneIdentity {
 	/** "tmux:%42" — authoritative pane identity ($TMUX_PANE). */
@@ -665,7 +691,7 @@ export const taskSyncRouter = {
 	 * stable mark when the CLI provides one, else by content. Does NOT dispatch
 	 * a change notification — the lane that authored the list already has it.
 	 */
-	upsertFromTaskList: authed.handler(async ({ input, context }) => {
+	upsertFromTaskList: authed.input(upsertFromTaskListInput).handler(async ({ input, context }) => {
 		const body = input as { lane_session: string; task_list: TaskListItem[]; source?: string };
 		const prisma = (context as Context).prisma as Prisma;
 		const log = getAppLogger();

package/src/fn-routers/tasks-router.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * ORPC procedures for task creation with initial comment.
+ * Extracted from @teamscala/orpc/fn-router — primitives tier must not
+ * contain application-specific work_items logic.
+ */
+import { type Context } from "./auth-router.ts";
+export declare const tasksRouter: {
+    createWithComment: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
+        headers: Headers;
+        resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
+        prisma: any;
+        user: import("./auth-router.ts").User;
+        orgId: string | null | undefined;
+    }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
+        success: boolean;
+        data: any;
+    }, {
+        success: boolean;
+        data: any;
+    }>, Record<never, never>, Record<never, never>>;
+};

package/src/fn-routers/user-preferences-router.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * ORPC procedures for a GENERIC per-user preference store backed by the
+ * `user_preferences` table. The user is resolved from the ORPC session context
+ * (`authed` middleware → `context.user.id`); the client supplies the org + key
+ * + value. This is the DB-durable, user-scoped key/value surface any feature
+ * can use — the AI browser-control focus (key `ai_ui_focus`) is the first
+ * consumer; it is NOT scala-projects-bespoke.
+ *
+ * Why this exists (over the generated `user_preferences` CRUD): the generated
+ * create/update do NOT resolve `user_id` server-side (only `organisation_id`
+ * from ctx.orgId), so a client cannot correctly write a per-user row through
+ * them. This proc stamps `user_id` from the authenticated caller, making the
+ * write safe + per-user. It also emits the `data_change` notify so the
+ * realtime surface (regions.watchDataChange) pushes updates to subscribed
+ * clients — the cross-region channel for the AI focus (the AiChat panel writes
+ * a focus here; the project-list-view in a different region subscribes +
+ * reacts, no shared React-context ancestor needed).
+ *
+ * Ownership is user_id: a caller reads/writes ONLY their own preferences. The
+ * org is part of the compound key (per-org isolation) but is client-supplied
+ * (the session carries the user, not the active org).
+ *
+ * DECISION — host-scoping of `user_preferences`: the table is NOT yet a shared
+ * `@teamscala/db` model (it lives in scala-projects's schema today), so this proc
+ * is genuinely host-scoped: it runs correctly on services whose Prisma client
+ * declares `user_preferences` (scala-projects is the first host) + is inert
+ * elsewhere. `Context.prisma` is `any`-typed, so the proc COMPILES workspace-
+ * wide (no type error on a model a host may not declare) — the `any` is the
+ * deliberate seam that lets one generic proc serve hosts incrementally as they
+ * adopt the table. Per-user preferences are platform-universal, so the tracked
+ * follow-on is to promote `user_preferences` to a shared `@teamscala/db` model
+ * (open-migration: `user_preferences→shared-model`, exit: every kind:ui host
+ * can mount this proc with no schema precondition) — at which point the proc is
+ * universally hostable + the `any` seam can tighten to the shared client. Until
+ * then the proc is opt-in per host (declare the table → get the capability).
+ */
+import * as v from "valibot";
+import { type Context } from "./auth-router.ts";
+export declare const userPreferencesRouter: {
+    upsert: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
+        headers: Headers;
+        resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
+        prisma: any;
+        user: import("./auth-router.ts").User;
+        orgId: string | null | undefined;
+    }>, v.ObjectSchema<{
+        readonly organisationId: v.StringSchema<undefined>;
+        /** The preference key (e.g. `ai_ui_focus`). Namespaced by feature. */
+        readonly key: v.StringSchema<undefined>;
+        /** The JSON value. Arbitrary per feature — typed by the caller. */
+        readonly value: v.AnySchema;
+    }, undefined>, import("@orpc/contract").Schema<{
+        success: boolean;
+    }, {
+        success: boolean;
+    }>, Record<never, never>, Record<never, never>>;
+    get: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
+        headers: Headers;
+        resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
+        prisma: any;
+        user: import("./auth-router.ts").User;
+        orgId: string | null | undefined;
+    }>, v.ObjectSchema<{
+        readonly organisationId: v.StringSchema<undefined>;
+        readonly key: v.StringSchema<undefined>;
+    }, undefined>, import("@orpc/contract").Schema<{
+        value: any;
+        updatedAt: any;
+    }, {
+        value: any;
+        updatedAt: any;
+    }>, Record<never, never>, Record<never, never>>;
+};