@indigoai-us/hq-cloud 5.25.0 → 5.27.0

package/dist/sync/push-transport.d.ts

@@ -0,0 +1,150 @@
+/**
+ * PushTransport — outbound shipping seam for the watcher daemon.
+ *
+ * The daemon wires file-watcher events into a transport that ships each
+ * PushEvent to the cloud. Defining the interface here lets the daemon ship
+ * with a swappable boundary — tests inject a fake, a later story swaps in a
+ * concrete WebSocket/HTTP implementation, and the daemon entry point never
+ * changes.
+ *
+ * Lifecycle
+ * ─────────
+ *  - `start()` is awaited BEFORE the watcher is started. It's the place
+ *    to open sockets, refresh tokens, etc.
+ *  - `publish(event)` is called for every coalesced PushEvent the watcher
+ *    emits. Implementations decide whether to buffer, batch, or send
+ *    inline; the daemon awaits the returned promise so back-pressure can
+ *    be honored.
+ *  - `dispose()` is awaited DURING shutdown, AFTER the watcher has been
+ *    torn down. Implementations should drain in-flight publishes (with
+ *    their own internal timeout) and close any sockets.
+ *  - `connected` is a passive boolean used by the health endpoint. It MAY
+ *    flap during reconnect attempts — that's fine; consumers treat it as
+ *    advisory, not a contract.
+ *
+ * The `NoopPushTransport` shipped here is the default when no transport
+ * is wired in: it counts publishes (so unit tests can assert delivery)
+ * and logs nothing — observers should rely on the watcher's `onEvent`
+ * counter on the daemon side, not the transport's internals.
+ *
+ * Ported from indigoai-us/hq-pro PR #112 (src/sync/push-transport.ts) into
+ * @indigoai-us/hq-cloud (Path B) per project event-driven-sync-menubar US-007.
+ */
+import { type PushEvent } from "./push-event.js";
+export interface PushTransport {
+    /** Open sockets, refresh tokens. Awaited before the watcher starts. */
+    start(): Promise<void>;
+    /** Ship one coalesced PushEvent. Awaited per event for back-pressure. */
+    publish(event: PushEvent): Promise<void>;
+    /** Drain + close. Awaited during daemon shutdown after watcher.dispose. */
+    dispose(): Promise<void>;
+    /** Advisory: is the transport currently believed to be connected? */
+    readonly connected: boolean;
+}
+/**
+ * Default `PushTransport` used until a real implementation lands.
+ *
+ * Behavior:
+ *  - `start()` flips `connected` to true.
+ *  - `publish()` increments a counter (visible via `publishedCount`).
+ *  - `dispose()` flips `connected` back to false.
+ *
+ * Deliberately silent: when the daemon runs with this default, the
+ * watcher's per-event log line (emitted by the daemon itself, not the
+ * transport) is the only observability. That keeps the noop from drowning
+ * the log when high-rate writes hit a dev machine.
+ */
+export declare class NoopPushTransport implements PushTransport {
+    private _connected;
+    private _count;
+    get connected(): boolean;
+    /** Test/observability hook: how many events have been published. */
+    get publishedCount(): number;
+    start(): Promise<void>;
+    publish(_event: PushEvent): Promise<void>;
+    dispose(): Promise<void>;
+}
+/**
+ * Minimal fetch surface so tests can inject a mocked `fetch` without pulling
+ * in DOM/undici types. Matches the subset of the global `fetch` we use.
+ */
+export type FetchLike = (input: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+/**
+ * Async getter for the current Cognito access token. Long-running daemons MUST
+ * pass a getter (not a captured string) so each publish resolves the freshest
+ * token — mirrors {@link VaultServiceConfig.authToken} semantics in types.ts.
+ * A static string is also accepted for short-lived tools and tests.
+ */
+export type AuthTokenSource = string | (() => string | Promise<string>);
+export interface HttpPushTransportOptions {
+    /**
+     * Vault API base URL (e.g. `https://vault-api.example.com`). The same
+     * `apiUrl` the runner already resolves for VaultClient. Trailing slashes
+     * are stripped. Required — config/env-driven, no hard-coded default.
+     */
+    apiUrl: string;
+    /**
+     * Endpoint path the PushEvent is POSTed to. Defaults to `/sync/push`
+     * (matches the deployed hq-pro endpoint from US-006). Override for testing
+     * or future endpoint moves.
+     */
+    pushPath?: string;
+    /** Cognito JWT — static string OR async getter. See {@link AuthTokenSource}. */
+    authToken: AuthTokenSource;
+    /**
+     * Optional extra headers (e.g. client identification) merged onto every
+     * request. Authorization + Content-Type are always set by the transport.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Per-request timeout in milliseconds. Default 10_000. On timeout the
+     * publish rejects — the daemon treats a rejected publish as a transient
+     * miss (the cadence poll still covers it) and MUST NOT crash.
+     */
+    timeoutMs?: number;
+    /** Injectable fetch (tests). Defaults to the global `fetch`. */
+    fetchImpl?: FetchLike;
+}
+/**
+ * Real client `PushTransport` that POSTs encoded PushEvents to the deployed
+ * `/sync/push` endpoint, authenticating with the menubar's existing Cognito
+ * bearer token — the same auth path VaultClient uses (Authorization: Bearer
+ * <accessToken>, token resolved per-request via the supplied getter so it
+ * self-heals across refreshes).
+ *
+ * Failure posture
+ * ───────────────
+ * `publish()` rejects on a network error, a non-2xx response, or a timeout.
+ * The DAEMON is responsible for not letting that rejection crash it — the
+ * watcher's emit path catches publish errors and logs them; the periodic
+ * cadence poll remains the safety net that eventually ships the change. This
+ * transport never swallows errors itself, so callers retain full visibility.
+ *
+ * `connected` flips true on `start()` and false on `dispose()`. It is purely
+ * advisory (HTTP is connectionless); the health endpoint may read it but it
+ * carries no delivery guarantee.
+ */
+export declare class HttpPushTransport implements PushTransport {
+    private readonly apiUrl;
+    private readonly pushPath;
+    private readonly getAuthToken;
+    private readonly extraHeaders;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    private _connected;
+    constructor(opts: HttpPushTransportOptions);
+    get connected(): boolean;
+    start(): Promise<void>;
+    publish(event: PushEvent): Promise<void>;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=push-transport.d.ts.map

package/dist/sync/push-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-transport.d.ts","sourceRoot":"","sources":["../../src/sync/push-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAElE,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,yEAAyE;IACzE,OAAO,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,2EAA2E;IAC3E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACrD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,MAAM,CAAK;IAEnB,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,oEAAoE;IACpE,IAAI,cAAc,IAAI,MAAM,CAE3B;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,OAAO,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B;AAID;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,CACtB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,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;AAEvE;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;AAExE,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,SAAS,EAAE,eAAe,CAAC;IAC3B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAwB;IACrD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyB;IACtD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,UAAU,CAAS;gBAEf,IAAI,EAAE,wBAAwB;IAmB1C,IAAI,SAAS,IAAI,OAAO,CAEvB;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,OAAO,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAiCxC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B"}

package/dist/sync/push-transport.js

@@ -0,0 +1,150 @@
+/**
+ * PushTransport — outbound shipping seam for the watcher daemon.
+ *
+ * The daemon wires file-watcher events into a transport that ships each
+ * PushEvent to the cloud. Defining the interface here lets the daemon ship
+ * with a swappable boundary — tests inject a fake, a later story swaps in a
+ * concrete WebSocket/HTTP implementation, and the daemon entry point never
+ * changes.
+ *
+ * Lifecycle
+ * ─────────
+ *  - `start()` is awaited BEFORE the watcher is started. It's the place
+ *    to open sockets, refresh tokens, etc.
+ *  - `publish(event)` is called for every coalesced PushEvent the watcher
+ *    emits. Implementations decide whether to buffer, batch, or send
+ *    inline; the daemon awaits the returned promise so back-pressure can
+ *    be honored.
+ *  - `dispose()` is awaited DURING shutdown, AFTER the watcher has been
+ *    torn down. Implementations should drain in-flight publishes (with
+ *    their own internal timeout) and close any sockets.
+ *  - `connected` is a passive boolean used by the health endpoint. It MAY
+ *    flap during reconnect attempts — that's fine; consumers treat it as
+ *    advisory, not a contract.
+ *
+ * The `NoopPushTransport` shipped here is the default when no transport
+ * is wired in: it counts publishes (so unit tests can assert delivery)
+ * and logs nothing — observers should rely on the watcher's `onEvent`
+ * counter on the daemon side, not the transport's internals.
+ *
+ * Ported from indigoai-us/hq-pro PR #112 (src/sync/push-transport.ts) into
+ * @indigoai-us/hq-cloud (Path B) per project event-driven-sync-menubar US-007.
+ */
+import { encodePushEvent } from "./push-event.js";
+/**
+ * Default `PushTransport` used until a real implementation lands.
+ *
+ * Behavior:
+ *  - `start()` flips `connected` to true.
+ *  - `publish()` increments a counter (visible via `publishedCount`).
+ *  - `dispose()` flips `connected` back to false.
+ *
+ * Deliberately silent: when the daemon runs with this default, the
+ * watcher's per-event log line (emitted by the daemon itself, not the
+ * transport) is the only observability. That keeps the noop from drowning
+ * the log when high-rate writes hit a dev machine.
+ */
+export class NoopPushTransport {
+    _connected = false;
+    _count = 0;
+    get connected() {
+        return this._connected;
+    }
+    /** Test/observability hook: how many events have been published. */
+    get publishedCount() {
+        return this._count;
+    }
+    async start() {
+        this._connected = true;
+    }
+    async publish(_event) {
+        this._count += 1;
+    }
+    async dispose() {
+        this._connected = false;
+    }
+}
+/**
+ * Real client `PushTransport` that POSTs encoded PushEvents to the deployed
+ * `/sync/push` endpoint, authenticating with the menubar's existing Cognito
+ * bearer token — the same auth path VaultClient uses (Authorization: Bearer
+ * <accessToken>, token resolved per-request via the supplied getter so it
+ * self-heals across refreshes).
+ *
+ * Failure posture
+ * ───────────────
+ * `publish()` rejects on a network error, a non-2xx response, or a timeout.
+ * The DAEMON is responsible for not letting that rejection crash it — the
+ * watcher's emit path catches publish errors and logs them; the periodic
+ * cadence poll remains the safety net that eventually ships the change. This
+ * transport never swallows errors itself, so callers retain full visibility.
+ *
+ * `connected` flips true on `start()` and false on `dispose()`. It is purely
+ * advisory (HTTP is connectionless); the health endpoint may read it but it
+ * carries no delivery guarantee.
+ */
+export class HttpPushTransport {
+    apiUrl;
+    pushPath;
+    getAuthToken;
+    extraHeaders;
+    timeoutMs;
+    fetchImpl;
+    _connected = false;
+    constructor(opts) {
+        if (!opts.apiUrl || opts.apiUrl.trim() === "") {
+            throw new Error("HttpPushTransport: apiUrl is required");
+        }
+        this.apiUrl = opts.apiUrl.replace(/\/+$/, "");
+        const path = opts.pushPath ?? "/sync/push";
+        this.pushPath = path.startsWith("/") ? path : `/${path}`;
+        const tok = opts.authToken;
+        // Normalize string|getter into a single async getter (mirrors VaultClient).
+        this.getAuthToken =
+            typeof tok === "function" ? async () => tok() : async () => tok;
+        this.extraHeaders = opts.headers ?? {};
+        this.timeoutMs = opts.timeoutMs ?? 10_000;
+        // Bind so a destructured global fetch keeps its receiver.
+        this.fetchImpl =
+            opts.fetchImpl ??
+                ((input, init) => globalThis.fetch(input, init));
+    }
+    get connected() {
+        return this._connected;
+    }
+    async start() {
+        this._connected = true;
+    }
+    async publish(event) {
+        // Validate-on-encode (US-007 contract) — a malformed event throws a typed
+        // PushEventDecodeError BEFORE we hit the network.
+        const body = encodePushEvent(event);
+        const token = await this.getAuthToken();
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const res = await this.fetchImpl(`${this.apiUrl}${this.pushPath}`, {
+                method: "POST",
+                headers: {
+                    ...this.extraHeaders,
+                    Authorization: `Bearer ${token}`,
+                    "Content-Type": "application/json",
+                    Accept: "application/json",
+                },
+                body,
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => "");
+                throw new Error(`HttpPushTransport: POST ${this.pushPath} failed (${res.status})${text ? `: ${text}` : ""}`);
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async dispose() {
+        this._connected = false;
+    }
+}
+//# sourceMappingURL=push-transport.js.map

package/dist/sync/push-transport.js.map

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

package/dist/watcher.d.ts

@@ -8,6 +8,92 @@
  */
 import type { EntityContext } from "./types.js";
 import type { UploadAuthor } from "./s3.js";
+import type { PushTransport } from "./sync/push-transport.js";
+import type { EventDrivenPushFlagProvider } from "./sync/feature-flags.js";
+/**
+ * Injectable clock seam (US-001).
+ *
+ * Production code uses the host timers; tests inject a {@link FakeClock} so the
+ * debounce window can be advanced deterministically without real wall-clock
+ * sleeps. US-002 (real chokidar watcher) and US-003 (runner wiring) build on
+ * this same seam — keep the surface minimal and stable.
+ */
+export interface Clock {
+    /** Schedule `fn` to run after `ms`. Returns an opaque handle. */
+    setTimeout(fn: () => void, ms: number): unknown;
+    /** Cancel a previously scheduled timeout. Safe to call with a stale handle. */
+    clearTimeout(handle: unknown): void;
+    /** Current epoch milliseconds. */
+    now(): number;
+}
+/** Real clock backed by host timers + Date.now. The production default. */
+export declare const systemClock: Clock;
+/**
+ * Deterministic clock for tests. Advance virtual time with {@link advance};
+ * any timers whose deadline has passed fire in scheduled order. No real timers
+ * are ever created, so a test using only this clock leaks nothing.
+ */
+export declare class FakeClock implements Clock {
+    private current;
+    private nextId;
+    private timers;
+    now(): number;
+    setTimeout(fn: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+    /**
+     * Advance virtual time by `ms`, firing every timer whose deadline falls in
+     * the interval (in deadline order). Timers scheduled by a firing callback are
+     * honored within the same advance if their new deadline is still within the
+     * advanced window.
+     */
+    advance(ms: number): void;
+    /** Number of timers still pending — a leak check for tests. */
+    pendingTimerCount(): number;
+}
+/** A push pass to run when a debounced change settles. May be async. */
+export type PushFn = () => void | Promise<void>;
+export interface WatchPushDriverOptions {
+    /** Quiet window (ms) before a settled change triggers a push. */
+    debounceMs?: number;
+    /** Clock seam — defaults to {@link systemClock}; tests inject {@link FakeClock}. */
+    clock?: Clock;
+    /** Push pass to invoke when the window settles. */
+    push: PushFn;
+}
+/**
+ * The reusable debounce + coalesce + concurrency-guard core of event-driven
+ * push (US-001 seam).
+ *
+ * It is intentionally decoupled from chokidar and from S3: callers feed it
+ * synthetic or real change notifications via {@link notifyChange}, and it
+ * invokes the injected `push` fn at most once per quiet window. A push that is
+ * still in flight is never overlapped — a change arriving mid-push is collapsed
+ * and re-triggers a single follow-up pass after the next quiet window.
+ *
+ * US-002 wires a real chokidar watcher's events into {@link notifyChange};
+ * US-003 supplies the targeted-push `push` fn. Tests drive it directly with a
+ * {@link FakeClock} and a spy `push` fn (no real S3, no 10-minute sleep).
+ */
+export declare class WatchPushDriver {
+    private readonly debounceMs;
+    private readonly clock;
+    private readonly push;
+    private timer;
+    private pushing;
+    private pendingWhilePushing;
+    private disposed;
+    constructor(opts: WatchPushDriverOptions);
+    /**
+     * Register a change. Resets the quiet window; the push fires `debounceMs`
+     * after the LAST change in a burst, coalescing the burst to one push.
+     */
+    notifyChange(): void;
+    private fire;
+    /** True while a push pass is executing. */
+    isPushing(): boolean;
+    /** Cancel any pending debounce timer; idempotent. Leaves no timers behind. */
+    dispose(): void;
+}
 export declare class SyncWatcher {
     private watcher;
     private hqRoot;
@@ -23,4 +109,189 @@ export declare class SyncWatcher {
     private queueChange;
     private flush;
 }
+/** Decision for a single path: emit a change for it, or ignore it. */
+export type WatchPathFilter = (absolutePath: string, isDir?: boolean) => boolean;
+/**
+ * Build the composite emit-decision predicate. Returns true when a change to
+ * `absolutePath` SHOULD wake the watcher (i.e. it survives every exclusion
+ * layer). Pure and chokidar-free so the matching logic is unit-testable
+ * directly.
+ *
+ * @param hqRoot       sync root (== personal-vault root in personalMode).
+ * @param personalMode when true, also applies the personal-vault default
+ *                     exclusions and the excluded-top-level buckets.
+ */
+export declare function createWatchPathFilter(hqRoot: string, personalMode?: boolean): WatchPathFilter;
+export interface TreeWatcherOptions {
+    /** Sync root to watch (== personal-vault root in personalMode). */
+    hqRoot: string;
+    /** Quiet window (ms) before a settled burst emits one `changed` call. */
+    debounceMs?: number;
+    /** Apply personal-vault default + top-level exclusions. */
+    personalMode?: boolean;
+    /** Clock seam — defaults to {@link systemClock}; tests inject {@link FakeClock}. */
+    clock?: Clock;
+    /**
+     * Pre-built path filter override (test seam). When omitted, one is built
+     * from {@link createWatchPathFilter}.
+     */
+    pathFilter?: WatchPathFilter;
+}
+/**
+ * Chokidar-backed file watcher that emits a single debounced `changed` signal
+ * after a {@link debounceMs} quiet window, coalescing bursts. It honors the
+ * full exclusion stack via {@link createWatchPathFilter}, so excluded paths
+ * (`.env`, `output/`, `.git/`, `companies/` in personalMode, …) never emit.
+ *
+ * Lifecycle: {@link start} (idempotent), {@link stop}, {@link dispose}. Stop
+ * closes the chokidar watcher (releasing fds) and cancels any pending debounce
+ * timer. dispose() is stop() + permanent shutdown.
+ */
+/**
+ * One settled change-burst, handed to {@link TreeWatcher} listeners. Carries
+ * the set of relative paths that changed during the quiet window so a listener
+ * (e.g. {@link PushEventEmitter}) can build one PushEvent per path. `paths` is
+ * absolute-path → relative-path; both are needed (relative for the wire shape,
+ * absolute for hashing/statting the file on disk).
+ */
+export interface TreeChangeBatch {
+    /** Map of absolutePath → relativePath for every path in the settled burst. */
+    paths: Map<string, string>;
+}
+/**
+ * Listener invoked once per settled debounce window.
+ *
+ * Backwards compatible with the US-003 `WatcherSurface` contract: the first
+ * argument is the OPTIONAL changed relative path the loop routes its targeted
+ * push to (the first path of the burst; undefined when the window settled with
+ * no captured path). US-008's {@link PushEventEmitter} consumes the SECOND
+ * argument — the full {@link TreeChangeBatch} of every path in the burst — to
+ * build one PushEvent per path. Listeners are free to ignore either argument.
+ */
+export type TreeChangeListener = (changedRelPath?: string, batch?: TreeChangeBatch) => void;
+export declare class TreeWatcher {
+    private readonly hqRoot;
+    private readonly debounceMs;
+    private readonly clock;
+    private readonly shouldEmit;
+    private watcher;
+    private timer;
+    private listeners;
+    /** Paths accumulated for the current (in-flight) debounce window. */
+    private pending;
+    private disposed;
+    constructor(opts: TreeWatcherOptions);
+    /**
+     * Register a debounced-`changed` listener. Returns an unsubscribe fn.
+     *
+     * Listeners receive a {@link TreeChangeBatch} of the paths that changed in
+     * the settled window. Existing US-003 callers that only need the "something
+     * changed" signal can ignore the argument — the contract is backwards
+     * compatible (a zero-arg callback still type-checks).
+     */
+    onChange(listener: TreeChangeListener): () => void;
+    /**
+     * Begin watching. Idempotent — a second call while already running is a
+     * no-op (no second chokidar instance, no leaked fds).
+     */
+    start(): void;
+    /**
+     * Test/seam entry point: feed a raw filesystem path as if chokidar reported
+     * it. Applies the emit filter then arms the debounce. Real chokidar events
+     * route through here too.
+     */
+    handleEvent(absolutePath: string): void;
+    private arm;
+    private emit;
+    /** True while the chokidar watcher is active. */
+    isWatching(): boolean;
+    /** Number of pending debounce timers — a leak check for tests. */
+    pendingTimerCount(): number;
+    /**
+     * Stop watching: close the chokidar watcher (releasing fds) and cancel any
+     * pending debounce timer. Idempotent. The instance can be restarted with
+     * {@link start} unless {@link dispose} was called.
+     */
+    stop(): void;
+    /** Permanent shutdown: stop() + drop listeners; further events are no-ops. */
+    dispose(): void;
+}
+export interface PushEventEmitterOptions {
+    /** Tenant identifier stamped onto every PushEvent + checked against the flag. */
+    originTenantId: string;
+    /** Device identifier stamped onto every PushEvent. */
+    originDeviceId: string;
+    /** Transport that ships each PushEvent (US-007 NoopPushTransport / HttpPushTransport). */
+    transport: PushTransport;
+    /**
+     * Feature-flag seam. When `isEnabled(originTenantId)` is false the emitter is
+     * dormant: {@link attach} subscribes nothing and {@link emitForBatch} is a
+     * no-op. Defaults are NOT supplied here — the caller injects an
+     * EventDrivenPushFlagProvider so dormancy is explicit.
+     */
+    flagProvider: EventDrivenPushFlagProvider;
+    /**
+     * Returns the next monotonic sequence number for this device. Default: an
+     * internal counter starting at 0. Inject to persist across daemon restarts.
+     */
+    getSequenceNumber?: () => number;
+    /** Clock for eventTimestamp. Default `() => new Date()`. */
+    now?: () => Date;
+    /**
+     * Where publish failures + hash/stat errors go. Default `console.error`.
+     * Receives the offending PushEvent (when known) so callers can correlate.
+     */
+    onError?: (err: Error, ctx: {
+        relativePath?: string;
+    }) => void;
+    /**
+     * Optional structured logger for the US-011 3-log diagnostic chain. When
+     * supplied, the emitter logs `event=watcher.emit` (the 1st correlated link)
+     * carrying the PushEvent's `sequenceNumber` — the same join key stamped by
+     * the server `push.receive` log and the client `fanout.receive` log. Default:
+     * no log (the daemon stays quiet unless wired with a logger).
+     */
+    logger?: EmitterLogger;
+}
+/**
+ * Minimal structured logger surface for {@link PushEventEmitter}. A pino
+ * `Logger` (from `./sync/logger.ts`) satisfies this; tests inject a fake.
+ */
+export interface EmitterLogger {
+    info(obj: Record<string, unknown>, msg?: string): void;
+}
+/**
+ * Bridges {@link TreeWatcher} change batches to a {@link PushTransport} as
+ * typed PushEvents. Construct once per daemon, then {@link attach} to a
+ * running TreeWatcher (returns an unsubscribe fn). Flag-gated + failure-safe.
+ */
+export declare class PushEventEmitter {
+    private readonly originTenantId;
+    private readonly originDeviceId;
+    private readonly transport;
+    private readonly flagProvider;
+    private readonly now;
+    private readonly onError;
+    private readonly logger;
+    private internalSeq;
+    private readonly nextSeq;
+    constructor(opts: PushEventEmitterOptions);
+    /** True iff event-driven push is enabled for this emitter's tenant. */
+    get enabled(): boolean;
+    /**
+     * Subscribe to a TreeWatcher's change batches. Dormant (no subscription)
+     * when the flag is OFF for this tenant. Returns an unsubscribe fn (a no-op
+     * when dormant).
+     */
+    attach(watcher: TreeWatcher): () => void;
+    /**
+     * Build + ship one PushEvent per changed path in the batch. No-op when the
+     * flag is OFF. Each path is independent: a hash/stat failure or a transport
+     * publish rejection for one path is caught + surfaced via `onError` and does
+     * NOT abort the others or propagate (the daemon must not crash; the cadence
+     * poll covers any miss).
+     */
+    emitForBatch(batch: TreeChangeBatch): Promise<void>;
+    private emitOne;
+}
 //# sourceMappingURL=watcher.d.ts.map

package/dist/watcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"watcher.d.ts","sourceRoot":"","sources":["../src/watcher.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIhD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAU5C,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,GAAG,CAAgB;IAC3B,OAAO,CAAC,MAAM,CAAC,CAAe;IAC9B,OAAO,CAAC,UAAU,CAAiD;IACnE,OAAO,CAAC,cAAc,CAAoC;IAC1D,OAAO,CAAC,aAAa,CAA8C;IACnE,OAAO,CAAC,UAAU,CAAS;gBAEf,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,EAAE,MAAM,CAAC,EAAE,YAAY;IAOrE,KAAK,IAAI,IAAI;IAuBb,IAAI,IAAI,IAAI;IAWZ,OAAO,CAAC,WAAW;YAqBL,KAAK;CAgDpB"}
+{"version":3,"file":"watcher.d.ts","sourceRoot":"","sources":["../src/watcher.ts"],"names":[],"mappings":"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"}