kankaku 0.5.0 → 0.6.0

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,14 @@
+import type { Client, 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` and
+ * `projects` record (no `active` filter, so the domain resolver can tell
+ * "deleted" from "inactive"; see `domain/work-target.ts`), sorted by name.
+ * `signal`, when given, bounds both fetches (see
+ * `pocketbase-client.ts#request`).
+ */
+export declare function createPocketBaseCatalogFetcher(client: PocketBaseClient): (signal?: AbortSignal) => Promise<{
+    clients: Client[];
+    projects: Project[];
+}>;

package/dist/adapters/pocketbase-catalog.js

@@ -0,0 +1,39 @@
+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,
+    };
+}
+/**
+ * Build the `fetchCatalog` function {@link CachedCatalog} (`cached-catalog.ts`)
+ * needs, backed by a {@link PocketBaseClient}. Fetches every `clients` and
+ * `projects` record (no `active` filter, so the domain resolver can tell
+ * "deleted" from "inactive"; see `domain/work-target.ts`), sorted by name.
+ * `signal`, when given, bounds both fetches (see
+ * `pocketbase-client.ts#request`).
+ */
+export function createPocketBaseCatalogFetcher(client) {
+    return async (signal) => {
+        const [clientRecords, projectRecords] = await Promise.all([
+            client.list("clients", { sort: "name" }, signal),
+            client.list("projects", { sort: "name" }, signal),
+        ]);
+        return {
+            clients: clientRecords.map(mapClient),
+            projects: projectRecords.map(mapProject),
+        };
+    };
+}

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,52 @@
+/**
+ * {@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, 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[];
+    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,180 @@
+/**
+ * {@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,
+            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);
+        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;
+    }
+}

package/dist/adapters/sync-runner.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Orchestrates one sync run: read every record, build tasks (never
+ * re-implementing the aggregation — `buildTasks` is the only place it
+ * lives), plan what needs pushing, push it, and persist the new state.
+ * Never throws to its caller: every failure mode is folded into the
+ * returned {@link SyncSummary}.
+ */
+import type { TaskView } from "../domain/task-view.ts";
+import type { Clock } from "../ports/clock.ts";
+import type { WorkLog } from "../ports/work-log.ts";
+import type { WorkSink } from "../ports/work-sink.ts";
+import type { SyncStateStore } from "./sync-state-store.ts";
+export interface SyncSummary {
+    uploaded: number;
+    updated: number;
+    skipped: number;
+    failed: Array<{
+        id: string;
+        reason: string;
+    }>;
+    /** Count of tasks routed to the unassigned client this run, grouped by their historical free-text label. */
+    unassigned: Record<string, number>;
+    syncedThrough: string | undefined;
+    durationMs: number;
+    /** Set when a network/timeout/5xx/auth failure stopped the run before every candidate task was attempted. */
+    error?: string;
+    /** `true` when another sync already holds the lock; nothing was attempted this run. */
+    locked?: boolean;
+}
+/**
+ * Which automatic trigger asked for this run, or `undefined` for a manual
+ * one (`/kankaku sync`, `sync all`, `backfill`) — see `runSync`'s
+ * short-circuit and throttle, which apply only to the automatic path.
+ * `session_shutdown` (pi awaits this handler — see `adapters/pi-tracker.ts`)
+ * is, like `session_start`, never throttled: only `agent_settled` is.
+ */
+export type SyncTrigger = "session_start" | "agent_settled" | "session_shutdown";
+export interface SyncRunnerDeps {
+    log: WorkLog;
+    sink: WorkSink;
+    stateStore: SyncStateStore;
+    clock: Clock;
+    /** The configured hub URL — a state file synced against a different one triggers a full sync. */
+    target: string;
+    windowHours?: number;
+    /**
+     * `KANKAKU_SYNC_MIN_INTERVAL_MINUTES`, already converted to ms. Only
+     * applies to the automatic path (`options.trigger` set). Defaults to 5
+     * minutes; `0` disables throttling.
+     */
+    minAutoIntervalMs?: number;
+}
+/**
+ * Run one sync pass. Acquires the cross-process lock for the whole run
+ * (never held across `await` boundaries outside this function) so two pi
+ * processes never race on the same `sync-state.json`.
+ *
+ * When `options.trigger` is set (the automatic `session_start`/
+ * `agent_settled`/`session_shutdown` path, as opposed to a manual
+ * `/kankaku sync`), two cheap gates run before any `WorkLog.readAll()` or
+ * network call: (a) if the log's `version()` is unchanged since the last
+ * successful sync and that sync did not error, skip entirely, for every
+ * trigger; otherwise (b) throttle to at most one real attempt per
+ * `minAutoIntervalMs`, but only for `agent_settled` — fired once per
+ * prompt, so `version()` almost always differs right after it appended a
+ * record. `session_start` and `session_shutdown` never throttle (see
+ * `isThrottled`). Neither gate ever applies to a manual sync.
+ */
+export declare function runSync(deps: SyncRunnerDeps, options?: {
+    full?: boolean;
+    trigger?: SyncTrigger;
+}): Promise<SyncSummary>;
+/** Number of tasks pending a sync right now, for `/kankaku sync status` — computed locally, no network. */
+export declare function pendingCount(tasks: TaskView[], state: ReturnType<SyncStateStore["read"]>, target: string, windowHours?: number): number;
+/**
+ * `/kankaku sync status`: the persisted state, a locally-computed pending
+ * count, and (R3) how many tasks changed since their last sync but fall
+ * outside this run's revisit window — a `sync all` needed to pick them up
+ * (see `domain/sync-plan.ts#SyncPlan.staleOutsideWindow`, and README "Hub
+ * (PocketBase)" > "Sync" > "Limitations"). No network.
+ */
+export declare function computeSyncStatus(log: WorkLog, stateStore: SyncStateStore, target: string, windowHours?: number): {
+    state: ReturnType<SyncStateStore["read"]>;
+    pending: number;
+    staleOutsideWindow: number;
+};
+/**
+ * Wrap an async function so concurrent callers share one in-flight call
+ * instead of starting a new one each — kankaku's single-flight guard for
+ * sync: `/kankaku sync`, the `session_start` auto-sync and the
+ * `agent_settled` auto-sync all go through the same wrapped function, so
+ * only one sync is ever running at a time within this process. (The
+ * cross-process case is covered separately by `SyncStateStore`'s lock
+ * file.) A caller that arrives while one is in flight joins its result
+ * rather than queuing a fresh run — the next trigger (the next
+ * `session_start` or `agent_settled`) will pick up anything missed, since
+ * every sync also revisits the trailing window.
+ */
+export declare function singleFlight<Args extends unknown[], T>(fn: (...args: Args) => Promise<T>): (...args: Args) => Promise<T>;