@indigoai-us/hq-cloud 6.2.7 → 6.3.1

package/dist/operation-lock.js

@@ -0,0 +1,256 @@
+/**
+ * Per-HQ-root mutual exclusion for the long-running operations
+ * (`sync`, `rescue`, `reindex`).
+ *
+ * Contract:
+ *   - At most ONE of sync / rescue / reindex runs at a time **per HQ root**.
+ *     The lock is shared across all three (keyed only by the root, not the
+ *     command), so e.g. a rescue refuses while a sync holds it. Different HQ
+ *     roots are fully independent — they hash to different lock files.
+ *   - The push watcher / watch+event-push runner is EXEMPT: it never calls in
+ *     here, so it neither takes the lock nor is blocked by it (its targeted
+ *     in-process push passes are likewise lock-free).
+ *
+ * ## Where the lock lives — and why
+ *
+ * `<stateDir>/locks/operation-<hash(canonicalRoot)>.lock`, where
+ * `stateDir = $HQ_STATE_DIR || ~/.hq`. This is deliberately NOT inside the HQ
+ * root:
+ *   - It must never round-trip to the cloud. A lock is machine-local, per-run
+ *     state; syncing it to S3 (and thence to other machines/roots) would be a
+ *     correctness bug. `~/.hq` is the established machine-local state dir
+ *     (journals already live there) and is never synced.
+ *   - `rescue` repairs a possibly-broken HQ root; a lock that depends on the
+ *     root being healthy is exactly backwards. `~/.hq` is independent of the
+ *     root's health.
+ *   - Keying the filename by a hash of the *canonical* root path makes the
+ *     lock per-root and prevents leakage across roots, while keeping the path
+ *     short and filesystem-safe.
+ *
+ * ## Atomicity, liveness, takeover
+ *
+ *   - Acquisition uses `open(…, "wx")` (O_CREAT | O_EXCL) — an atomic
+ *     create-if-absent. Exactly one racer can create the file; the loser sees
+ *     EEXIST and re-evaluates.
+ *   - The lock records the holder's `{ pid, command, startedAt, hqRoot }`. On
+ *     EEXIST we test the recorded PID with `process.kill(pid, 0)`:
+ *       * ESRCH  → the holder is gone (crashed / killed -9 / stale file) →
+ *                  reclaim the lock.
+ *       * EPERM  → the PID exists but is owned by another user → treat as ALIVE
+ *                  (conservative: refuse rather than risk two concurrent ops).
+ *       * success → alive → refuse fast with {@link OperationLockedError}
+ *                  naming the holding command + PID.
+ *   - PID reuse is an inherent, un-eliminable race for any PID-based scheme: if
+ *     the original holder crashed and the OS later handed its PID to an
+ *     unrelated process, we conservatively read that as "still held" and
+ *     refuse. We accept that false-busy over the far worse false-free, and
+ *     record `startedAt`/`command` so an operator can diagnose a wedged lock.
+ *
+ * ## Release
+ *
+ *   - Normal exit: the `with*` wrappers release in a `finally`.
+ *   - Signals (SIGINT/SIGTERM): a one-time handler releases every held lock,
+ *     then re-raises the default disposition so exit status is unchanged.
+ *   - Hard crash (SIGKILL / power loss): nothing runs, but the stale-PID
+ *     takeover above reclaims the lock on the next attempt.
+ *   - `process.on("exit")`: a final best-effort synchronous unlink.
+ *
+ * ## Escape hatch
+ *
+ *   `HQ_DISABLE_OP_LOCK=1` makes acquisition a no-op (returns a handle whose
+ *   release does nothing). For emergencies and for callers that manage
+ *   exclusion themselves; documented, off by default.
+ */
+import * as crypto from "crypto";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+/** Process exit code used when an operation is refused because the lock is held. */
+export const OPERATION_LOCKED_EXIT = 17;
+/** Thrown by `acquireOperationLock` when a LIVE holder owns the lock. */
+export class OperationLockedError extends Error {
+    holder;
+    attempted;
+    constructor(holder, attempted) {
+        super(`Refusing to start "${attempted}": another HQ operation is already ` +
+            `running for this HQ root — "${holder.command}" (pid ${holder.pid}, ` +
+            `started ${holder.startedAt}). Wait for it to finish, or stop that ` +
+            `process, then retry.`);
+        this.holder = holder;
+        this.attempted = attempted;
+        this.name = "OperationLockedError";
+    }
+}
+function stateDir() {
+    return process.env.HQ_STATE_DIR || path.join(os.homedir(), ".hq");
+}
+/** Absolute lock path for a given HQ root. Exported for tests. */
+export function lockPathFor(hqRoot) {
+    const canon = path.resolve(hqRoot);
+    const key = crypto.createHash("sha1").update(canon).digest("hex").slice(0, 16);
+    return path.join(stateDir(), "locks", `operation-${key}.lock`);
+}
+/**
+ * Is `pid` a live process? `kill(pid, 0)` sends no signal; it only probes.
+ * ESRCH → no such process (dead/stale). EPERM → exists but not ours → ALIVE
+ * (conservative). Anything else → assume alive rather than risk a double-run.
+ */
+function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ESRCH")
+            return false;
+        return true; // EPERM (exists) or unknown → treat as alive
+    }
+}
+function readLockInfo(p) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(p, "utf8"));
+        if (parsed && typeof parsed.pid === "number" && typeof parsed.command === "string") {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+// ── Process-wide release plumbing ──────────────────────────────────────────
+// Track every lock this process currently holds so the signal/exit hooks can
+// release all of them. The hooks are installed exactly once.
+const heldLocks = new Set();
+let hooksInstalled = false;
+function unlinkIfOwned(p) {
+    // Only remove a lock whose recorded pid is THIS process — never clobber a
+    // lock another process took over after a (hypothetical) reclaim race.
+    const info = readLockInfo(p);
+    if (info && info.pid === process.pid) {
+        try {
+            fs.unlinkSync(p);
+        }
+        catch {
+            /* already gone — fine */
+        }
+    }
+}
+function installHooksOnce() {
+    if (hooksInstalled)
+        return;
+    hooksInstalled = true;
+    process.on("exit", () => {
+        for (const h of heldLocks)
+            unlinkIfOwned(h.path);
+    });
+    for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+        process.on(sig, () => {
+            for (const h of heldLocks)
+                unlinkIfOwned(h.path);
+            // Re-raise with the default disposition so the exit status is the normal
+            // signal status (and a second Ctrl-C still works). Removing our listener
+            // first avoids recursing back into this handler.
+            process.removeAllListeners(sig);
+            process.kill(process.pid, sig);
+        });
+    }
+}
+function makeHandle(p, info) {
+    const handle = {
+        path: p,
+        info,
+        release() {
+            heldLocks.delete(handle);
+            unlinkIfOwned(p);
+        },
+    };
+    heldLocks.add(handle);
+    installHooksOnce();
+    return handle;
+}
+const NOOP_HANDLE_BASE = { release() { } };
+/**
+ * Acquire the per-root operation lock for `command`. Returns a {@link LockHandle}
+ * on success; throws {@link OperationLockedError} when a live holder owns it.
+ * Reclaims a stale lock (dead holder) transparently.
+ */
+export function acquireOperationLock(hqRoot, command) {
+    if (process.env.HQ_DISABLE_OP_LOCK === "1") {
+        const info = {
+            pid: process.pid,
+            command,
+            startedAt: new Date().toISOString(),
+            hqRoot: path.resolve(hqRoot),
+        };
+        return { ...NOOP_HANDLE_BASE, path: "", info };
+    }
+    const p = lockPathFor(hqRoot);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    const info = {
+        pid: process.pid,
+        command,
+        startedAt: new Date().toISOString(),
+        hqRoot: path.resolve(hqRoot),
+    };
+    const payload = JSON.stringify(info, null, 2);
+    // Bounded retry: each iteration is one atomic create attempt. EEXIST against
+    // a stale holder reclaims and retries; EEXIST against a live holder refuses.
+    const MAX_ATTEMPTS = 5;
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+        let fd;
+        try {
+            fd = fs.openSync(p, "wx"); // O_CREAT | O_EXCL — atomic
+        }
+        catch (err) {
+            if (err?.code !== "EEXIST")
+                throw err;
+            const holder = readLockInfo(p);
+            if (holder && holder.pid !== process.pid && pidAlive(holder.pid)) {
+                throw new OperationLockedError(holder, command);
+            }
+            // Stale (dead holder), unreadable/torn, or our own leftover → reclaim.
+            try {
+                fs.unlinkSync(p);
+            }
+            catch {
+                /* someone else reclaimed it first; the next openSync re-evaluates */
+            }
+            continue;
+        }
+        try {
+            fs.writeSync(fd, payload);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        return makeHandle(p, info);
+    }
+    // Pathological churn (another process reclaiming in lockstep). Surface it
+    // rather than spin forever.
+    throw new Error(`Could not acquire HQ operation lock at ${p} after ${MAX_ATTEMPTS} attempts`);
+}
+/** Run `fn` while holding the per-root lock for `command` (async). */
+export async function withOperationLock(hqRoot, command, fn) {
+    const handle = acquireOperationLock(hqRoot, command);
+    try {
+        return await fn();
+    }
+    finally {
+        handle.release();
+    }
+}
+/** Run `fn` while holding the per-root lock for `command` (synchronous). */
+export function withOperationLockSync(hqRoot, command, fn) {
+    const handle = acquireOperationLock(hqRoot, command);
+    try {
+        return fn();
+    }
+    finally {
+        handle.release();
+    }
+}
+//# sourceMappingURL=operation-lock.js.map

package/dist/operation-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-lock.js","sourceRoot":"","sources":["../src/operation-lock.ts"],"names":[],"mappings":"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"}

package/dist/operation-lock.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Unit tests for the per-HQ-root operation mutex.
+ */
+export {};
+//# sourceMappingURL=operation-lock.test.d.ts.map

package/dist/operation-lock.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-lock.test.d.ts","sourceRoot":"","sources":["../src/operation-lock.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/operation-lock.test.js

@@ -0,0 +1,140 @@
+/**
+ * Unit tests for the per-HQ-root operation mutex.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { spawnSync } from "child_process";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { acquireOperationLock, withOperationLockSync, lockPathFor, OperationLockedError, OPERATION_LOCKED_EXIT, } from "./operation-lock.js";
+/** A PID that is guaranteed dead: spawn a node that exits immediately, reuse its pid. */
+function deadPid() {
+    const r = spawnSync(process.execPath, ["-e", ""], { stdio: "ignore" });
+    if (!r.pid)
+        throw new Error("could not spawn to obtain a dead pid");
+    return r.pid;
+}
+function writeLock(p, info) {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    const full = {
+        pid: 1,
+        command: "sync",
+        startedAt: new Date(0).toISOString(),
+        hqRoot: "/x",
+        ...info,
+    };
+    fs.writeFileSync(p, JSON.stringify(full));
+}
+describe("operation-lock", () => {
+    let stateDir;
+    let rootA;
+    let rootB;
+    beforeEach(() => {
+        stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-oplock-state-"));
+        process.env.HQ_STATE_DIR = stateDir;
+        delete process.env.HQ_DISABLE_OP_LOCK;
+        rootA = fs.mkdtempSync(path.join(os.tmpdir(), "hq-rootA-"));
+        rootB = fs.mkdtempSync(path.join(os.tmpdir(), "hq-rootB-"));
+    });
+    afterEach(() => {
+        fs.rmSync(stateDir, { recursive: true, force: true });
+        fs.rmSync(rootA, { recursive: true, force: true });
+        fs.rmSync(rootB, { recursive: true, force: true });
+        delete process.env.HQ_STATE_DIR;
+        delete process.env.HQ_DISABLE_OP_LOCK;
+    });
+    it("the lock path is under the state dir, keyed per canonical root", () => {
+        const a = lockPathFor(rootA);
+        const b = lockPathFor(rootB);
+        expect(a.startsWith(path.join(stateDir, "locks"))).toBe(true);
+        expect(a).not.toBe(b); // different roots → different lock files
+        // canonical: a trailing-slash variant maps to the same lock
+        expect(lockPathFor(rootA + path.sep)).toBe(a);
+    });
+    it("acquires, writes holder info, and releases (file gone after release)", () => {
+        const h = acquireOperationLock(rootA, "sync");
+        expect(fs.existsSync(h.path)).toBe(true);
+        const info = JSON.parse(fs.readFileSync(h.path, "utf8"));
+        expect(info.pid).toBe(process.pid);
+        expect(info.command).toBe("sync");
+        h.release();
+        expect(fs.existsSync(h.path)).toBe(false);
+    });
+    it("refuses fast with the holder's command + pid when a LIVE process holds it", () => {
+        // Simulate a DIFFERENT live process holding the lock. PID 1 (init/systemd)
+        // is always alive and is never our own pid, so kill(1,0) reports alive and
+        // the same-process reclaim path does not apply.
+        writeLock(lockPathFor(rootA), { pid: 1, command: "rescue" });
+        expect(() => acquireOperationLock(rootA, "sync")).toThrowError(OperationLockedError);
+        try {
+            acquireOperationLock(rootA, "sync");
+        }
+        catch (e) {
+            const err = e;
+            expect(err.holder.command).toBe("rescue");
+            expect(err.holder.pid).toBe(1);
+            expect(err.message).toContain("rescue");
+            expect(err.message).toContain("pid 1");
+        }
+    });
+    it("reclaims a stale lock whose holder PID is dead (takeover)", () => {
+        const stale = deadPid();
+        writeLock(lockPathFor(rootA), { pid: stale, command: "sync" });
+        // The dead holder must not block us.
+        const h = acquireOperationLock(rootA, "rescue");
+        const info = JSON.parse(fs.readFileSync(h.path, "utf8"));
+        expect(info.pid).toBe(process.pid); // we took it over
+        expect(info.command).toBe("rescue");
+        h.release();
+    });
+    it("reclaims a torn/unreadable lock file", () => {
+        const p = lockPathFor(rootA);
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, "{ this is not valid json");
+        const h = acquireOperationLock(rootA, "reindex");
+        expect(fs.existsSync(h.path)).toBe(true);
+        h.release();
+    });
+    it("different HQ roots are independent — both may hold concurrently", () => {
+        const a = acquireOperationLock(rootA, "sync");
+        const b = acquireOperationLock(rootB, "rescue"); // must NOT refuse
+        expect(fs.existsSync(a.path)).toBe(true);
+        expect(fs.existsSync(b.path)).toBe(true);
+        expect(a.path).not.toBe(b.path);
+        a.release();
+        b.release();
+    });
+    it("the same root is mutually exclusive across different commands", () => {
+        // A live sync in ANOTHER process holds the root (pid 1 stands in for it).
+        const p = lockPathFor(rootA);
+        writeLock(p, { pid: 1, command: "sync" });
+        // Neither rescue nor reindex may acquire while that sync holds it.
+        expect(() => acquireOperationLock(rootA, "rescue")).toThrowError(OperationLockedError);
+        expect(() => acquireOperationLock(rootA, "reindex")).toThrowError(OperationLockedError);
+        // Once that sync finishes (its lock is gone), the next command acquires.
+        fs.unlinkSync(p);
+        const h2 = acquireOperationLock(rootA, "reindex");
+        expect(fs.existsSync(h2.path)).toBe(true);
+        h2.release();
+    });
+    it("withOperationLockSync releases even when the body throws", () => {
+        const p = lockPathFor(rootA);
+        expect(() => withOperationLockSync(rootA, "reindex", () => {
+            expect(fs.existsSync(p)).toBe(true); // held during the body
+            throw new Error("boom");
+        })).toThrow("boom");
+        expect(fs.existsSync(p)).toBe(false); // released on the way out
+    });
+    it("HQ_DISABLE_OP_LOCK=1 makes acquisition a no-op", () => {
+        process.env.HQ_DISABLE_OP_LOCK = "1";
+        // Even with a live holder on record, the escape hatch acquires without error.
+        writeLock(lockPathFor(rootA), { pid: process.pid, command: "sync" });
+        const h = acquireOperationLock(rootA, "rescue");
+        expect(h.path).toBe(""); // no real lock file written
+        h.release(); // no-op, no throw
+    });
+    it("OPERATION_LOCKED_EXIT is a stable non-zero code", () => {
+        expect(OPERATION_LOCKED_EXIT).toBe(17);
+    });
+});
+//# sourceMappingURL=operation-lock.test.js.map

package/dist/operation-lock.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-lock.test.js","sourceRoot":"","sources":["../src/operation-lock.test.ts"],"names":[],"mappings":"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"}

package/dist/sync/event-sync.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Event-driven sync wiring — Phase 3 of event-driven-sync-menubar
+ * (US-017 publish / US-018 receive / US-019 rollout gate).
+ *
+ * Phases 1–2 built every piece but left them unconnected: the watcher runs
+ * targeted *push passes* (S3 upload) but never publishes a PushEvent, and the
+ * runner's receiver seam defaults to {@link NoopPushReceiver}. This module is
+ * the connective tissue that turns both on for enrolled accounts:
+ *
+ *  - {@link resolveEventSync} — the rollout gate. EXACT-email allowlist
+ *    (mirrors `resolvePresignTransport`'s shape in sync-runner.ts, but full
+ *    address, not domain suffix) + `HQ_SYNC_EVENT_SYNC` env override in both
+ *    directions. ONE gate governs publish AND receive so a device is never
+ *    publish-only or receive-only in a half-rolled state.
+ *  - {@link subscribeSyncReceive} — `POST /v1/sync/subscribe` (US-015/US-016):
+ *    mints the per-device queue and returns `{queueUrl, region, credentials}`,
+ *    where `credentials` are short-lived STS creds scoped to receive/delete on
+ *    exactly that queue.
+ *  - {@link sqsClientFromAwsSdk} — the doc-promised thin adapter from the AWS
+ *    SDK `SQSClient` to the receiver's narrow {@link SqsClientLike} seam.
+ *  - {@link createRefreshingSqsClient} — wraps the adapter with credential
+ *    lifecycle: proactive re-vend before expiry (skew window) + one reactive
+ *    retry on an expiry-class error. The queue URL is stable across re-vends
+ *    (same device → same queue, idempotent endpoint); only creds rotate.
+ *  - {@link startEventSync} — the wiring entry the runner calls from the
+ *    `--event-push` watch block when the gate is ON. Resolves tenant + device
+ *    identity, builds the {@link HttpPushTransport} + {@link PushEventEmitter}
+ *    (publish leg) and the {@link SqsPushReceiver} (receive leg, self-echo
+ *    filtered), and returns handles. Any startup failure degrades to
+ *    poll-only — it NEVER takes the daemon down.
+ *
+ * The 10-minute `--poll-remote-ms` pass remains the correctness backstop for
+ * every path here; event delivery is best-effort by design.
+ */
+import { SQSClient } from "@aws-sdk/client-sqs";
+import { HttpPushTransport, type AuthTokenSource } from "./push-transport.js";
+import { type PushReceiver, type SqsClientLike, type SyncEngineFn } from "./push-receiver.js";
+import type { TreeChangeBatch } from "../watcher.js";
+/**
+ * Accounts enrolled in event-driven sync (publish + receive).
+ *
+ * EXACT full-address matching, case-insensitive — NOT a domain suffix. The
+ * single-account Phase 3 rollout (2026-06-10) targets the operator's own
+ * devices; `xhassaan@getindigo.ai` and `hassaan@getindigo.ai.evil.com` must
+ * never match. Broadening later is an entry here (or a domain-set like
+ * `PRESIGN_ROLLOUT_DOMAINS` once GA'd).
+ */
+export declare const EVENT_SYNC_ROLLOUT_EMAILS: ReadonlySet<string>;
+/**
+ * Decide whether this session runs event-driven sync (publish + receive).
+ *
+ * Mirrors `resolvePresignTransport` precedence: `HQ_SYNC_EVENT_SYNC`
+ * overrides in both directions (`1`/`true`/`yes`/`on` → force on,
+ * `0`/`false`/`no`/`off` → force off) so unenrolled testers can exercise it
+ * and enrolled accounts can be rolled back without a release. An unset/blank
+ * override falls through to the exact-email check; an unrecognized override
+ * value is ignored (email check wins).
+ */
+export declare function resolveEventSync(email: string | undefined, override: string | undefined): boolean;
+export interface SubscribeSyncCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken: string;
+    /** ISO8601 expiry of the vended STS credentials. */
+    expiration: string;
+}
+export interface SubscribeSyncResponse {
+    /** The caller's own per-device queue URL (stable across calls). */
+    queueUrl: string;
+    /** Region the queue lives in. */
+    region: string;
+    /** Short-lived creds scoped to receive/delete on exactly this queue. */
+    credentials: SubscribeSyncCredentials;
+}
+/** Minimal fetch seam (matches push-transport.ts's FetchLike posture). */
+type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+/**
+ * `POST /v1/sync/subscribe` — provision (idempotently) this device's queue
+ * and vend fresh receive credentials. Auth mirrors HttpPushTransport: Bearer
+ * token resolved per-call via the supplied source.
+ */
+export declare function subscribeSyncReceive(opts: {
+    apiUrl: string;
+    authToken: AuthTokenSource;
+    deviceId: string;
+    timeoutMs?: number;
+    fetchImpl?: FetchLike;
+}): Promise<SubscribeSyncResponse>;
+/**
+ * Adapt the AWS SDK `SQSClient` to the receiver's narrow {@link SqsClientLike}
+ * seam (the doc-promised `sqsClientFromAwsSdk` from push-receiver.ts). The
+ * abort signal is forwarded so `dispose()` can cut a 20s long-poll short.
+ */
+export declare function sqsClientFromAwsSdk(client: Pick<SQSClient, "send">): SqsClientLike;
+export interface RefreshingSqsClientOptions {
+    /** The initial subscribe response (creds + region + queue URL). */
+    initial: SubscribeSyncResponse;
+    /** Re-vend: called when creds are near/past expiry. Idempotent server-side. */
+    subscribe: () => Promise<SubscribeSyncResponse>;
+    /**
+     * Build the underlying narrow client from a subscribe response. Default:
+     * AWS SDK `SQSClient` via {@link sqsClientFromAwsSdk}. Tests inject a fake.
+     */
+    buildSqs?: (resp: SubscribeSyncResponse) => SqsClientLike;
+    /** Clock seam (tests). Default `Date.now`. */
+    now?: () => number;
+}
+/**
+ * An {@link SqsClientLike} that owns the vended-credential lifecycle:
+ *
+ *  - PROACTIVE: before each call, if the recorded expiry is within the skew
+ *    window, re-subscribe (re-vend) and rebuild the inner client first.
+ *  - REACTIVE: if a call still fails with an expiry-class error (clock skew,
+ *    revocation), re-vend once and retry the call once. Anything else — or a
+ *    second failure — propagates to the receiver's own backoff/reconnect
+ *    loop, whose retention-backed redelivery makes the miss recoverable.
+ *
+ * Concurrent refreshes collapse onto one in-flight subscribe promise.
+ */
+export declare function createRefreshingSqsClient(opts: RefreshingSqsClientOptions): SqsClientLike;
+/** Structured line logger seam — the runner passes its stderr logger. */
+export type EventSyncLog = (message: string) => void;
+export interface StartEventSyncOptions {
+    hqRoot: string;
+    /** Vault API base URL (the runner's DEFAULT_VAULT_API_URL). */
+    apiUrl: string;
+    /** Cognito access-token source (getter for long-running daemons). */
+    authToken: AuthTokenSource;
+    /** This device's stable id (getOrCreateMachineId). */
+    deviceId: string;
+    /**
+     * Resolve the caller's tenant id (canonical person `prs_*` uid). The server
+     * rejects publishes whose `originTenantId` mismatches the JWT principal, so
+     * this MUST be the same identity the JWT resolves to.
+     */
+    resolveTenantId: () => Promise<string>;
+    /**
+     * The already-routed targeted-pull bridge (the runner's receiverSyncFn,
+     * funneled through its runGuarded mutex). Self-echo filtering happens HERE,
+     * before this is invoked.
+     */
+    syncFn: SyncEngineFn;
+    /** Diagnostic logger (one line per lifecycle event). Default: console.error. */
+    log?: EventSyncLog;
+    subscribe?: (deviceId: string) => Promise<SubscribeSyncResponse>;
+    buildSqs?: (resp: SubscribeSyncResponse) => SqsClientLike;
+    transport?: HttpPushTransport;
+    now?: () => number;
+}
+export interface EventSyncHandles {
+    /**
+     * Publish PushEvents for a settled change batch. Called by the runner
+     * AFTER the targeted push pass succeeds — an event must never announce
+     * bytes that are not in S3 yet. Fire-and-forget: failures are logged by
+     * the emitter's onError and the cadence poll covers the miss.
+     */
+    publishBatch: (batch: TreeChangeBatch) => void;
+    /** The live receiver (already started). */
+    receiver: PushReceiver;
+    /** This device's id — the runner uses it nowhere else, exposed for logs. */
+    ownDeviceId: string;
+    /** Tear down transport + receiver (runner shutdown path). */
+    dispose: () => Promise<void>;
+}
+/**
+ * Bring up the publish + receive legs. Returns `null` (poll-only degradation)
+ * on ANY startup failure — subscribe 5xx, tenant resolution failure, etc. —
+ * after logging the reason. The caller treats `null` as "today's behavior".
+ */
+export declare function startEventSync(opts: StartEventSyncOptions): Promise<EventSyncHandles | null>;
+export {};
+//# sourceMappingURL=event-sync.d.ts.map

package/dist/sync/event-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-sync.d.ts","sourceRoot":"","sources":["../../src/sync/event-sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EACL,SAAS,EAGV,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAIrD;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAExD,CAAC;AAEH;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,OAAO,CAMT;AAID,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,WAAW,EAAE,wBAAwB,CAAC;CACvC;AAED,0EAA0E;AAC1E,KAAK,SAAS,GAAG,CACf,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IACJ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KACE,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC,CAAC;AASvE;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,eAAe,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAqDjC;AAID;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,GAC9B,aAAa,CA4Bf;AAwBD,MAAM,WAAW,0BAA0B;IACzC,mEAAmE;IACnE,OAAO,EAAE,qBAAqB,CAAC;IAC/B,+EAA+E;IAC/E,SAAS,EAAE,MAAM,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAChD;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,qBAAqB,KAAK,aAAa,CAAC;IAC1D,8CAA8C;IAC9C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAgBD;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,0BAA0B,GAC/B,aAAa,CA0Cf;AAID,yEAAyE;AACzE,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAErD,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,SAAS,EAAE,eAAe,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,eAAe,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC;;;;OAIG;IACH,MAAM,EAAE,YAAY,CAAC;IACrB,gFAAgF;IAChF,GAAG,CAAC,EAAE,YAAY,CAAC;IAEnB,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACjE,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,qBAAqB,KAAK,aAAa,CAAC;IAC1D,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,YAAY,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;IAC/C,2CAA2C;IAC3C,QAAQ,EAAE,YAAY,CAAC;IACvB,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAsFlC"}