kankaku-pi 1.0.0

package/dist/adapters/kankaku-dir.js

@@ -0,0 +1,85 @@
+import { mkdirSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+/**
+ * Resolve the kankaku data directory: an absolute `dirOrRelative` is used
+ * as-is, a relative one is joined against `cwd`. Shared by every lazy
+ * adapter so the rule lives in exactly one place.
+ */
+export function resolveKankakuDir(dirOrRelative, cwd) {
+    return isAbsolute(dirOrRelative) ? dirOrRelative : join(cwd, dirOrRelative);
+}
+/** Matches this probe's own marker filename: `.kankaku-write-probe.<pid>.<timestamp>.tmp`. */
+const PROBE_NAME_PATTERN = /^\.kankaku-write-probe\.\d+\.(\d+)\.tmp$/;
+/** A marker older than this is assumed abandoned (its writer was SIGKILLed between the write and its own unlink) — R4. */
+const PROBE_STALE_MS = 60_000;
+/**
+ * Best-effort removal of a stale writability-probe marker (R4): a probe
+ * that gets SIGKILLed between its `writeFileSync` and its own `unlinkSync`
+ * leaves `.kankaku-write-probe.<pid>.<timestamp>.tmp` behind forever —
+ * nothing else in `dir` ever looks at it again otherwise. Runs
+ * opportunistically every time the probe itself runs (mirrors
+ * `machine-process-registry.ts`'s own-write-time sweep pattern), so no
+ * separate cleanup process is needed. Only removes a marker whose
+ * filename-embedded timestamp (not the file's mtime, so this stays
+ * deterministic and easy to test) is older than a minute — never a fresh
+ * one, including this call's own marker (written after this sweep runs) or
+ * a concurrent process's own in-flight probe.
+ */
+function sweepStaleWriteProbes(dir, now) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return; // dir just created and already empty, or unreadable — nothing to sweep.
+    }
+    for (const name of names) {
+        const match = PROBE_NAME_PATTERN.exec(name);
+        if (!match)
+            continue;
+        const timestamp = Number(match[1]);
+        if (!Number.isFinite(timestamp) || now - timestamp <= PROBE_STALE_MS)
+            continue;
+        try {
+            unlinkSync(join(dir, name));
+        }
+        catch {
+            // Best effort: already gone, or a concurrent sweep got there first.
+        }
+    }
+}
+/** `mkdirSync` + a temp marker file write/unlink: proves both creatability and write permission, not just existence (a read-only *existing* directory would otherwise pass a bare `mkdirSync` check silently, since recursive mkdir on an existing dir never fails). Also sweeps any stale marker left behind by an earlier, SIGKILLed probe (R4) before writing its own. */
+function defaultWritabilityProbe(dir) {
+    mkdirSync(dir, { recursive: true });
+    sweepStaleWriteProbes(dir, Date.now());
+    const marker = join(dir, `.kankaku-write-probe.${process.pid}.${Date.now()}.tmp`);
+    writeFileSync(marker, "");
+    unlinkSync(marker);
+}
+/**
+ * Resolve the target directory for a write that would normally go to
+ * `candidateDir` (F1: routing a verified subagent's work log/inflight
+ * checkpoints to its orchestrator's kankaku directory instead of its own
+ * cwd-relative one — ADR 0023's rewrite): `candidateDir` when it can be
+ * proven writable — created if it does not exist yet — `fallbackDir` (the
+ * process's own local directory) otherwise, so a parent directory that no
+ * longer exists, or that this process lacks permission to write to,
+ * degrades to a safe, local fallback instead of throwing and losing the
+ * record entirely. `usedFallback` lets the caller surface this (`/kankaku
+ * doctor`) so a human can notice and reunite the record manually — the
+ * append-only log can never be rewritten to fix it after the fact. Never
+ * throws: `fallbackDir` itself is never probed here — its own writability
+ * is handled the ordinary way, by whichever adapter eventually writes to
+ * it, exactly as it always has been for a process that never needed to
+ * route anywhere.
+ */
+export function resolveWritableTarget(candidateDir, fallbackDir, deps = {}) {
+    const probe = deps.probe ?? defaultWritabilityProbe;
+    try {
+        probe(candidateDir);
+        return { dir: candidateDir, usedFallback: false };
+    }
+    catch {
+        return { dir: fallbackDir, usedFallback: true };
+    }
+}

package/dist/adapters/lazy-jsonl-work-log.d.ts

@@ -0,0 +1,17 @@
+import type { WorkRecord } from "../domain/work-record.ts";
+import type { WorkLog } from "../ports/work-log.ts";
+/**
+ * {@link WorkLog} that resolves a relative log directory lazily: against the
+ * project of the first appended record, or against `fallbackCwd()` when a
+ * read happens before any record was written in this process.
+ */
+export declare class LazyJsonlWorkLog implements WorkLog {
+    private readonly dirOrRelative;
+    private readonly fallbackCwd;
+    private resolved;
+    constructor(dirOrRelative: string, fallbackCwd?: () => string);
+    private resolveFor;
+    append(record: WorkRecord): void;
+    readAll(): WorkRecord[];
+    version(): string;
+}

package/dist/adapters/lazy-jsonl-work-log.js

@@ -0,0 +1,31 @@
+import { JsonlWorkLog } from "./jsonl-work-log.js";
+import { resolveKankakuDir } from "./kankaku-dir.js";
+/**
+ * {@link WorkLog} that resolves a relative log directory lazily: against the
+ * project of the first appended record, or against `fallbackCwd()` when a
+ * read happens before any record was written in this process.
+ */
+export class LazyJsonlWorkLog {
+    dirOrRelative;
+    fallbackCwd;
+    resolved;
+    constructor(dirOrRelative, fallbackCwd = () => process.cwd()) {
+        this.dirOrRelative = dirOrRelative;
+        this.fallbackCwd = fallbackCwd;
+    }
+    resolveFor(cwd) {
+        if (!this.resolved) {
+            this.resolved = new JsonlWorkLog(resolveKankakuDir(this.dirOrRelative, cwd));
+        }
+        return this.resolved;
+    }
+    append(record) {
+        this.resolveFor(record.project).append(record);
+    }
+    readAll() {
+        return this.resolveFor(this.fallbackCwd()).readAll();
+    }
+    version() {
+        return this.resolveFor(this.fallbackCwd()).version();
+    }
+}

package/dist/adapters/pocketbase-catalog.d.ts

@@ -0,0 +1,16 @@
+import type { Client, HubTask, Project } from "../domain/work-target.ts";
+import type { PocketBaseClient } from "./pocketbase-client.ts";
+/**
+ * Build the `fetchCatalog` function {@link CachedCatalog} (`cached-catalog.ts`)
+ * needs, backed by a {@link PocketBaseClient}. Fetches every `clients`,
+ * `projects` and `tasks` record in parallel (no `active`/`status` filter,
+ * so the domain resolver can tell "deleted" from "inactive"/"done"; see
+ * `domain/work-target.ts`), clients/projects sorted by name and tasks by
+ * title. `signal`, when given, bounds every fetch (see
+ * `pocketbase-client.ts#request`).
+ */
+export declare function createPocketBaseCatalogFetcher(client: PocketBaseClient): (signal?: AbortSignal) => Promise<{
+    clients: Client[];
+    projects: Project[];
+    tasks: HubTask[];
+}>;

package/dist/adapters/pocketbase-catalog.js

@@ -0,0 +1,56 @@
+const TASK_STATUSES = new Set(["open", "doing", "done"]);
+function mapClient(record) {
+    return {
+        id: record.id,
+        name: record.name,
+        code: record.code,
+        active: record.active === true,
+        ...(record.unassigned === true ? { unassigned: true } : {}),
+    };
+}
+function mapProject(record) {
+    return {
+        id: record.id,
+        name: record.name,
+        ...(record.code !== undefined ? { code: record.code } : {}),
+        clientId: record.client,
+        repoPaths: Array.isArray(record.repo_paths) ? record.repo_paths.filter((path) => typeof path === "string") : [],
+        active: record.active === true,
+    };
+}
+/** `open` on any unrecognised or missing status, rather than dropping the task. */
+function mapTaskStatus(status) {
+    return status !== undefined && TASK_STATUSES.has(status) ? status : "open";
+}
+function mapTask(record) {
+    return {
+        id: record.id,
+        title: record.title ?? "",
+        projectId: record.project,
+        status: mapTaskStatus(record.status),
+        ...(typeof record.external_ref === "string" && record.external_ref !== "" ? { externalRef: record.external_ref } : {}),
+    };
+}
+/**
+ * Build the `fetchCatalog` function {@link CachedCatalog} (`cached-catalog.ts`)
+ * needs, backed by a {@link PocketBaseClient}. Fetches every `clients`,
+ * `projects` and `tasks` record in parallel (no `active`/`status` filter,
+ * so the domain resolver can tell "deleted" from "inactive"/"done"; see
+ * `domain/work-target.ts`), clients/projects sorted by name and tasks by
+ * title. `signal`, when given, bounds every fetch (see
+ * `pocketbase-client.ts#request`).
+ */
+export function createPocketBaseCatalogFetcher(client) {
+    return async (signal) => {
+        const [clientRecords, projectRecords, taskRecords] = await Promise.all([
+            client.list("clients", { sort: "name" }, signal),
+            client.list("projects", { sort: "name" }, signal),
+            client.list("tasks", { sort: "title" }, signal),
+        ]);
+        return {
+            clients: clientRecords.map(mapClient),
+            projects: projectRecords.map(mapProject),
+            tasks: taskRecords.map(mapTask),
+        };
+    };
+}

package/dist/adapters/pocketbase-client.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Reusable, minimal PocketBase HTTP client: auth (with a single re-auth on
+ * 401), pagination, timeouts, and typed errors, built around an injected
+ * `fetch`. No pi imports, no domain knowledge — this is a general-purpose
+ * adapter meant to be reused by the sync push (a later phase) for
+ * create/update calls through the same `request()` primitive.
+ */
+export type PocketBaseFetch = typeof fetch;
+export interface PocketBaseRecord {
+    id: string;
+    [key: string]: unknown;
+}
+export interface PocketBaseListResult<T> {
+    page: number;
+    perPage: number;
+    totalItems: number;
+    totalPages: number;
+    items: T[];
+}
+export interface PocketBaseClientOptions {
+    /** Base URL, e.g. `https://pb.example.com` (no trailing slash required). */
+    url: string;
+    email: string;
+    password: string;
+    /** Injectable for tests; defaults to `globalThis.fetch`. */
+    fetch?: PocketBaseFetch;
+    /** Per-request timeout in ms. Defaults to 3000. */
+    timeoutMs?: number;
+}
+export type PocketBaseErrorKind = "network" | "timeout" | "http" | "auth";
+export declare class PocketBaseError extends Error {
+    readonly kind: PocketBaseErrorKind;
+    readonly status: number | undefined;
+    constructor(kind: PocketBaseErrorKind, message: string, status?: number);
+}
+/**
+ * Minimal PocketBase client: lazily authenticates on the first request,
+ * reuses the token, and re-authenticates exactly once on a 401 before
+ * failing cleanly. `request` is the generic primitive other adapters (and
+ * a future sync sink) build on; `list` is a pagination convenience for
+ * read-only catalog fetches.
+ */
+export declare class PocketBaseClient {
+    private readonly baseUrl;
+    private readonly email;
+    private readonly password;
+    private readonly doFetch;
+    private readonly timeoutMs;
+    private token;
+    /** Single-flight guard: concurrent callers with no token share this in-flight authentication instead of each posting their own. Cleared on settle (success or failure) so a failed auth never poisons a later attempt. */
+    private authInFlight;
+    constructor(options: PocketBaseClientOptions);
+    /** Perform `request` with the current token (authenticating first if there is none). `signal` bounds the underlying fetch when starting a fresh authentication; ignored by a caller that joins one already in flight. */
+    private authenticate;
+    private doAuthenticate;
+    /** `signal`, when given, is composed with this call's own per-request timeout signal (`AbortSignal.any`) so a caller can additionally bound a whole sequence of calls with one overall deadline. */
+    private rawFetch;
+    /**
+     * Generic request primitive: `method`/`path` (e.g. `/api/collections/clients/records`)
+     * with an optional JSON `body`. Authenticates lazily, retries exactly
+     * once on a 401 after re-authenticating, and throws a typed
+     * {@link PocketBaseError} on network failure, timeout, auth failure, or
+     * any other non-2xx response. `signal`, when given, is composed with
+     * every underlying request's own per-request timeout, so a caller can
+     * bound this whole call (including a lazy auth and the 401 retry) with
+     * one overall deadline; an abort surfaces as a `"timeout"` error, same as
+     * a per-request timeout.
+     */
+    request<T = unknown>(method: string, path: string, body?: unknown, signal?: AbortSignal): Promise<T>;
+    /**
+     * Fetch every record of `collection`, paginating until every page is
+     * read. `perPage` defaults to 200; `filter`/`sort` are passed through
+     * verbatim as PocketBase filter/sort expressions. `signal`, when given,
+     * bounds the whole pagination loop (see {@link request}).
+     */
+    list<T extends PocketBaseRecord = PocketBaseRecord>(collection: string, opts?: {
+        filter?: string;
+        sort?: string;
+        perPage?: number;
+    }, signal?: AbortSignal): Promise<T[]>;
+}

package/dist/adapters/pocketbase-client.js

@@ -0,0 +1,148 @@
+/**
+ * Reusable, minimal PocketBase HTTP client: auth (with a single re-auth on
+ * 401), pagination, timeouts, and typed errors, built around an injected
+ * `fetch`. No pi imports, no domain knowledge — this is a general-purpose
+ * adapter meant to be reused by the sync push (a later phase) for
+ * create/update calls through the same `request()` primitive.
+ */
+export class PocketBaseError extends Error {
+    kind;
+    status;
+    constructor(kind, message, status) {
+        super(message);
+        this.name = "PocketBaseError";
+        this.kind = kind;
+        this.status = status;
+    }
+}
+const DEFAULT_TIMEOUT_MS = 3000;
+const AUTH_PATH = "/api/collections/users/auth-with-password";
+function isAbortError(error) {
+    return error instanceof Error && error.name === "AbortError";
+}
+/** Build a `records` list path with pagination/filter/sort query params. */
+function listPath(collection, page, perPage, filter, sort) {
+    const params = new URLSearchParams({ page: String(page), perPage: String(perPage) });
+    if (filter)
+        params.set("filter", filter);
+    if (sort)
+        params.set("sort", sort);
+    return `/api/collections/${encodeURIComponent(collection)}/records?${params.toString()}`;
+}
+/**
+ * Minimal PocketBase client: lazily authenticates on the first request,
+ * reuses the token, and re-authenticates exactly once on a 401 before
+ * failing cleanly. `request` is the generic primitive other adapters (and
+ * a future sync sink) build on; `list` is a pagination convenience for
+ * read-only catalog fetches.
+ */
+export class PocketBaseClient {
+    baseUrl;
+    email;
+    password;
+    doFetch;
+    timeoutMs;
+    token;
+    /** Single-flight guard: concurrent callers with no token share this in-flight authentication instead of each posting their own. Cleared on settle (success or failure) so a failed auth never poisons a later attempt. */
+    authInFlight;
+    constructor(options) {
+        this.baseUrl = options.url.replace(/\/+$/, "");
+        this.email = options.email;
+        this.password = options.password;
+        this.doFetch = options.fetch ?? fetch;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    /** Perform `request` with the current token (authenticating first if there is none). `signal` bounds the underlying fetch when starting a fresh authentication; ignored by a caller that joins one already in flight. */
+    authenticate(signal) {
+        if (!this.authInFlight) {
+            this.authInFlight = this.doAuthenticate(signal).finally(() => {
+                this.authInFlight = undefined;
+            });
+        }
+        return this.authInFlight;
+    }
+    async doAuthenticate(signal) {
+        const response = await this.rawFetch("POST", AUTH_PATH, { identity: this.email, password: this.password }, undefined, signal);
+        if (!response.ok) {
+            throw new PocketBaseError("auth", `kankaku: hub authentication failed (${response.status})`, response.status);
+        }
+        const body = (await response.json());
+        this.token = body.token;
+    }
+    /** `signal`, when given, is composed with this call's own per-request timeout signal (`AbortSignal.any`) so a caller can additionally bound a whole sequence of calls with one overall deadline. */
+    async rawFetch(method, path, body, token, signal) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        const requestSignal = signal ? AbortSignal.any([controller.signal, signal]) : controller.signal;
+        try {
+            return await this.doFetch(`${this.baseUrl}${path}`, {
+                method,
+                headers: {
+                    "content-type": "application/json",
+                    ...(token !== undefined ? { Authorization: token } : {}),
+                },
+                ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+                signal: requestSignal,
+            });
+        }
+        catch (error) {
+            if (isAbortError(error)) {
+                throw new PocketBaseError("timeout", `kankaku: hub request timed out after ${this.timeoutMs}ms: ${method} ${path}`);
+            }
+            throw new PocketBaseError("network", `kankaku: hub request failed: ${method} ${path}: ${error.message}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Generic request primitive: `method`/`path` (e.g. `/api/collections/clients/records`)
+     * with an optional JSON `body`. Authenticates lazily, retries exactly
+     * once on a 401 after re-authenticating, and throws a typed
+     * {@link PocketBaseError} on network failure, timeout, auth failure, or
+     * any other non-2xx response. `signal`, when given, is composed with
+     * every underlying request's own per-request timeout, so a caller can
+     * bound this whole call (including a lazy auth and the 401 retry) with
+     * one overall deadline; an abort surfaces as a `"timeout"` error, same as
+     * a per-request timeout.
+     */
+    async request(method, path, body, signal) {
+        if (this.token === undefined) {
+            await this.authenticate(signal);
+        }
+        let response = await this.rawFetch(method, path, body, this.token, signal);
+        if (response.status === 401) {
+            this.token = undefined;
+            await this.authenticate(signal);
+            response = await this.rawFetch(method, path, body, this.token, signal);
+        }
+        if (!response.ok) {
+            if (response.status === 401) {
+                throw new PocketBaseError("auth", `kankaku: hub rejected credentials for ${method} ${path}`, response.status);
+            }
+            throw new PocketBaseError("http", `kankaku: hub request failed: ${method} ${path} (${response.status})`, response.status);
+        }
+        if (response.status === 204)
+            return undefined;
+        return (await response.json());
+    }
+    /**
+     * Fetch every record of `collection`, paginating until every page is
+     * read. `perPage` defaults to 200; `filter`/`sort` are passed through
+     * verbatim as PocketBase filter/sort expressions. `signal`, when given,
+     * bounds the whole pagination loop (see {@link request}).
+     */
+    async list(collection, opts = {}, signal) {
+        const perPage = opts.perPage ?? 200;
+        const items = [];
+        let page = 1;
+        for (;;) {
+            const result = await this.request("GET", listPath(collection, page, perPage, opts.filter, opts.sort), undefined, signal);
+            items.push(...result.items);
+            if (page >= result.totalPages || result.items.length === 0)
+                break;
+            page += 1;
+        }
+        return items;
+    }
+}

package/dist/adapters/pocketbase-sink.d.ts

@@ -0,0 +1,53 @@
+/**
+ * {@link WorkSink} backed by a real PocketBase instance: upserts one
+ * `task_entries` row per task (create-only assignment, see
+ * `domain/hub-entry.ts`) and, when enabled, its `work_records` children.
+ *
+ * PocketBase has no native upsert (contract.md "Upsert by task_id"): look
+ * up existing rows by their unique key in chunks, then create or patch.
+ * A unique-violation on create (approximated here as any 400 on create,
+ * since `PocketBaseError` does not carry the response body — see the
+ * `isLikelyUniqueViolation` note below) is treated as "already exists":
+ * look it up and patch instead.
+ */
+import type { PromptPrivacyMode } from "../domain/hub-entry.ts";
+import type { TaskView } from "../domain/task-view.ts";
+import type { Client, HubTask, Project } from "../domain/work-target.ts";
+import type { PushTaskResult, WorkSink } from "../ports/work-sink.ts";
+import type { PocketBaseClient } from "./pocketbase-client.ts";
+export interface PocketBaseSinkDeps {
+    client: PocketBaseClient;
+    /** Catalog snapshot to resolve assignment against; see `domain/hub-entry.ts#resolveTaskAssignment`. */
+    clients: Client[];
+    projects: Project[];
+    tasks: HubTask[];
+    machine: string;
+    promptMode: PromptPrivacyMode;
+    /** Coding agent that produced these rows; see `domain/hub-entry.ts#HubEntryContext.agent`. Defaults to `"pi"`. */
+    agent?: string;
+    agentVersion?: string;
+    /** The integration that wrote these rows; see `domain/hub-entry.ts#HubEntryContext.plugin`. Defaults to `"kankaku"`. */
+    plugin?: string;
+    pluginVersion?: string;
+    /** `KANKAKU_SYNC_RECORDS` (default enabled): also upsert each task's raw `work_records`. */
+    syncRecords: boolean;
+    /** ids per lookup request. Defaults to 30, per contract.md's guidance. */
+    chunkSize?: number;
+}
+/** Escape a value for PocketBase's filter string-literal syntax (`field="value"`). Exported for direct unit testing. */
+export declare function escapeFilterValue(value: string): string;
+export declare class PocketBaseSink implements WorkSink {
+    private readonly deps;
+    constructor(deps: PocketBaseSinkDeps);
+    private get chunkSize();
+    /** Look up existing records by a unique field, chunked to ~30 ids per request; returns a map of that field's value to the record's PocketBase id. */
+    private lookupExisting;
+    private findOne;
+    private get entryContext();
+    /** Create-or-patch one task_entries row. Returns its PocketBase record id and whether it was created or updated. */
+    private upsertTaskEntry;
+    /** Best-effort upsert of one task's work_records children. A per-record validation failure is swallowed (the task_entries row already succeeded); a fatal error propagates so the whole run stops. */
+    private upsertWorkRecords;
+    private pushOne;
+    push(tasks: TaskView[]): Promise<PushTaskResult[]>;
+}

package/dist/adapters/pocketbase-sink.js

@@ -0,0 +1,181 @@
+/**
+ * {@link WorkSink} backed by a real PocketBase instance: upserts one
+ * `task_entries` row per task (create-only assignment, see
+ * `domain/hub-entry.ts`) and, when enabled, its `work_records` children.
+ *
+ * PocketBase has no native upsert (contract.md "Upsert by task_id"): look
+ * up existing rows by their unique key in chunks, then create or patch.
+ * A unique-violation on create (approximated here as any 400 on create,
+ * since `PocketBaseError` does not carry the response body — see the
+ * `isLikelyUniqueViolation` note below) is treated as "already exists":
+ * look it up and patch instead.
+ */
+import { buildTaskEntryCreatePayload, buildTaskEntryUpdatePayload, buildWorkRecordPayload, resolveTaskAssignment, taskWorkRecords } from "../domain/hub-entry.js";
+import { PocketBaseError } from "./pocketbase-client.js";
+const DEFAULT_CHUNK_SIZE = 30;
+/** Escape a value for PocketBase's filter string-literal syntax (`field="value"`). Exported for direct unit testing. */
+export function escapeFilterValue(value) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+/** Fatal (systemic) errors stop the whole sync run rather than failing one task. */
+function isFatalError(error) {
+    if (!(error instanceof PocketBaseError))
+        return true;
+    if (error.kind === "network" || error.kind === "timeout" || error.kind === "auth")
+        return true;
+    if (error.kind === "http" && error.status !== undefined && error.status >= 500)
+        return true;
+    return false;
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * `PocketBaseError` for a create only carries `status`/`kind`, not the
+ * parsed response body, so we cannot check `data.<field>.code ===
+ * "validation_not_unique"` directly (contract.md "What a unique-violation
+ * response actually looks like"). Instead, any 400 on a create is treated
+ * as a possible race and re-looked-up: if the row now exists, it was a
+ * duplicate (patch it); if not, it was a genuine validation error (the
+ * original message is kept).
+ */
+function isLikelyUniqueViolation(error) {
+    return error instanceof PocketBaseError && error.kind === "http" && error.status === 400;
+}
+export class PocketBaseSink {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    get chunkSize() {
+        return this.deps.chunkSize ?? DEFAULT_CHUNK_SIZE;
+    }
+    /** Look up existing records by a unique field, chunked to ~30 ids per request; returns a map of that field's value to the record's PocketBase id. */
+    async lookupExisting(collection, field, values) {
+        const found = new Map();
+        const chunkSize = this.chunkSize;
+        for (let i = 0; i < values.length; i += chunkSize) {
+            const chunk = values.slice(i, i + chunkSize);
+            if (chunk.length === 0)
+                continue;
+            const filter = chunk.map((value) => `${field}="${escapeFilterValue(value)}"`).join("||");
+            const items = await this.deps.client.list(collection, { filter, perPage: chunkSize });
+            for (const item of items) {
+                const value = item[field];
+                if (typeof value === "string")
+                    found.set(value, item.id);
+            }
+        }
+        return found;
+    }
+    async findOne(collection, field, value) {
+        const found = await this.lookupExisting(collection, field, [value]);
+        return found.get(value);
+    }
+    get entryContext() {
+        return {
+            clients: this.deps.clients,
+            projects: this.deps.projects,
+            tasks: this.deps.tasks,
+            machine: this.deps.machine,
+            promptMode: this.deps.promptMode,
+            agent: this.deps.agent ?? "pi",
+            ...(this.deps.agentVersion !== undefined ? { agentVersion: this.deps.agentVersion } : {}),
+            plugin: this.deps.plugin ?? "kankaku",
+            ...(this.deps.pluginVersion !== undefined ? { pluginVersion: this.deps.pluginVersion } : {}),
+        };
+    }
+    /** Create-or-patch one task_entries row. Returns its PocketBase record id and whether it was created or updated. */
+    async upsertTaskEntry(task, existingId) {
+        const ctx = this.entryContext;
+        if (existingId) {
+            await this.deps.client.request("PATCH", `/api/collections/task_entries/records/${existingId}`, buildTaskEntryUpdatePayload(task, ctx));
+            return { id: existingId, created: false };
+        }
+        try {
+            const created = await this.deps.client.request("POST", "/api/collections/task_entries/records", buildTaskEntryCreatePayload(task, ctx));
+            return { id: created.id, created: true };
+        }
+        catch (error) {
+            if (!isLikelyUniqueViolation(error))
+                throw error;
+            const found = await this.findOne("task_entries", "task_id", task.id);
+            if (!found)
+                throw error;
+            await this.deps.client.request("PATCH", `/api/collections/task_entries/records/${found}`, buildTaskEntryUpdatePayload(task, ctx));
+            return { id: found, created: false };
+        }
+    }
+    /** Best-effort upsert of one task's work_records children. A per-record validation failure is swallowed (the task_entries row already succeeded); a fatal error propagates so the whole run stops. */
+    async upsertWorkRecords(task, taskEntryRecordId) {
+        const records = taskWorkRecords(task);
+        const existing = await this.lookupExisting("work_records", "kankaku_id", records.map((record) => record.id));
+        for (const record of records) {
+            const payload = buildWorkRecordPayload(record, taskEntryRecordId, { machine: this.deps.machine, promptMode: this.deps.promptMode });
+            const existingId = existing.get(record.id);
+            try {
+                if (existingId) {
+                    await this.deps.client.request("PATCH", `/api/collections/work_records/records/${existingId}`, payload);
+                }
+                else {
+                    try {
+                        await this.deps.client.request("POST", "/api/collections/work_records/records", payload);
+                    }
+                    catch (error) {
+                        if (!isLikelyUniqueViolation(error))
+                            throw error;
+                        const found = await this.findOne("work_records", "kankaku_id", record.id);
+                        if (!found)
+                            throw error;
+                        await this.deps.client.request("PATCH", `/api/collections/work_records/records/${found}`, payload);
+                    }
+                }
+            }
+            catch (error) {
+                if (isFatalError(error))
+                    throw error;
+                // Non-fatal: this one child row failed validation; the task_entries
+                // row it belongs to already succeeded, so skip it and keep going.
+            }
+        }
+    }
+    async pushOne(task, existingId) {
+        const assignment = resolveTaskAssignment(task, this.deps.clients, this.deps.projects, this.deps.tasks);
+        const pushAssignment = { unassigned: assignment.routedToUnassigned, ...(assignment.legacyClientLabel ? { legacyLabel: assignment.legacyClientLabel } : {}) };
+        try {
+            const { id, created } = await this.upsertTaskEntry(task, existingId);
+            if (this.deps.syncRecords) {
+                await this.upsertWorkRecords(task, id);
+            }
+            return created ? { kind: "created", ...pushAssignment } : { kind: "updated", ...pushAssignment };
+        }
+        catch (error) {
+            if (isFatalError(error))
+                return { kind: "error", reason: describeError(error) };
+            return { kind: "failed", reason: describeError(error) };
+        }
+    }
+    async push(tasks) {
+        const results = [];
+        if (tasks.length === 0)
+            return results;
+        // One chunked lookup for every task up front (contract.md: "one list
+        // request per ~30 ids"), rather than one lookup per task.
+        let existingByTaskId;
+        try {
+            existingByTaskId = await this.lookupExisting("task_entries", "task_id", tasks.map((task) => task.id));
+        }
+        catch (error) {
+            const outcome = isFatalError(error) ? { kind: "error", reason: describeError(error) } : { kind: "failed", reason: describeError(error) };
+            results.push({ taskId: tasks[0].id, outcome });
+            return results;
+        }
+        for (const task of tasks) {
+            const outcome = await this.pushOne(task, existingByTaskId.get(task.id));
+            results.push({ taskId: task.id, outcome });
+            if (outcome.kind === "error")
+                break;
+        }
+        return results;
+    }
+}