@indigoai-us/hq-cloud 6.15.75 → 6.15.76

package/dist/watcher.js

@@ -30,8 +30,18 @@ const DEBOUNCE_MS = 2000;
  */
 export const DEFAULT_EVENT_DEBOUNCE_MS = 15_000;
 export const DEFAULT_EVENT_MAX_WAIT_MS = 120_000;
+/**
+ * A small, quiet save should not pay the full burst-coalescing window.  This
+ * is deliberately still long enough to absorb editor atomic-save chatter.
+ */
+export const DEFAULT_EVENT_SMALL_BATCH_DEBOUNCE_MS = 2_500;
+export const DEFAULT_EVENT_SMALL_BATCH_MAX_PATHS = 8;
+export const DEFAULT_EVENT_SMALL_BATCH_MAX_BYTES = 1024 * 1024;
 export const EVENT_DEBOUNCE_MS_ENV = "HQ_SYNC_EVENT_DEBOUNCE_MS";
 export const EVENT_MAX_WAIT_MS_ENV = "HQ_SYNC_EVENT_MAX_WAIT_MS";
+export const EVENT_SMALL_BATCH_DEBOUNCE_MS_ENV = "HQ_SYNC_EVENT_SMALL_BATCH_DEBOUNCE_MS";
+export const EVENT_SMALL_BATCH_MAX_PATHS_ENV = "HQ_SYNC_EVENT_SMALL_BATCH_MAX_PATHS";
+export const EVENT_SMALL_BATCH_MAX_BYTES_ENV = "HQ_SYNC_EVENT_SMALL_BATCH_MAX_BYTES";
 /**
  * Resolve the event-pass debounce configuration from the environment.
  * `HQ_SYNC_EVENT_DEBOUNCE_MS` / `HQ_SYNC_EVENT_MAX_WAIT_MS`; 0, negative,
@@ -51,7 +61,15 @@ export function resolveEventDebounceConfig(env = process.env) {
     };
     const debounceMs = read(EVENT_DEBOUNCE_MS_ENV, DEFAULT_EVENT_DEBOUNCE_MS);
     const maxWaitMs = Math.max(debounceMs, read(EVENT_MAX_WAIT_MS_ENV, DEFAULT_EVENT_MAX_WAIT_MS));
-    return { debounceMs, maxWaitMs };
+    return {
+        debounceMs,
+        maxWaitMs,
+        // Never let a tuning error turn the small-batch path into a longer delay
+        // than the ordinary debounce window.
+        smallBatchDebounceMs: Math.min(debounceMs, read(EVENT_SMALL_BATCH_DEBOUNCE_MS_ENV, DEFAULT_EVENT_SMALL_BATCH_DEBOUNCE_MS)),
+        smallBatchMaxPaths: read(EVENT_SMALL_BATCH_MAX_PATHS_ENV, DEFAULT_EVENT_SMALL_BATCH_MAX_PATHS),
+        smallBatchMaxBytes: read(EVENT_SMALL_BATCH_MAX_BYTES_ENV, DEFAULT_EVENT_SMALL_BATCH_MAX_BYTES),
+    };
 }
 /**
  * A Linux chokidar watcher derives its directory budget from the host's real
@@ -907,6 +925,9 @@ function estimatePendingEntryBytes(absolutePath, relativePath) {
 export class TreeWatcher {
     hqRoot;
     debounceMs;
+    smallBatchDebounceMs;
+    smallBatchMaxPaths;
+    smallBatchMaxBytes;
     maxWaitMs;
     clock;
     shouldEmit;
@@ -935,6 +956,8 @@ export class TreeWatcher {
     /** Paths accumulated for the current (in-flight) debounce window. */
     pending = new Map();
     pendingChanges = new Map();
+    /** Latest known payload bytes per path; null makes the whole batch bulk. */
+    pendingPayloadSizes = new Map();
     knownKinds = new Map();
     pendingBytes = 0;
     overflowed = false;
@@ -956,6 +979,12 @@ export class TreeWatcher {
     constructor(opts) {
         this.hqRoot = opts.hqRoot;
         this.debounceMs = opts.debounceMs ?? DEBOUNCE_MS;
+        this.smallBatchDebounceMs =
+            opts.smallBatchDebounceMs !== undefined && opts.smallBatchDebounceMs > 0
+                ? Math.min(this.debounceMs, Math.floor(opts.smallBatchDebounceMs))
+                : null;
+        this.smallBatchMaxPaths = Math.max(1, Math.floor(opts.smallBatchMaxPaths ?? 1));
+        this.smallBatchMaxBytes = Math.max(0, Math.floor(opts.smallBatchMaxBytes ?? 0));
         this.maxWaitMs =
             opts.maxWaitMs !== undefined && opts.maxWaitMs > 0
                 ? Math.max(opts.maxWaitMs, this.debounceMs)
@@ -1343,6 +1372,7 @@ export class TreeWatcher {
                 this.arm();
                 return;
             }
+            this.pendingPayloadSizes.set(abs, this.payloadSizeFor(abs, kind));
             const deleteSnapshotEpoch = (this.deleteSnapshotEpochs.get(abs) ?? 0) + 1;
             this.deleteSnapshotEpochs.set(abs, deleteSnapshotEpoch);
             let deleteSnapshots = [];
@@ -1371,6 +1401,7 @@ export class TreeWatcher {
             // A newer live revision supersedes any queued unlink capture for this
             // path before that job is allowed to acquire and mutate the journal.
             this.deleteSnapshotEpochs.set(abs, (this.deleteSnapshotEpochs.get(abs) ?? 0) + 1);
+            this.pendingPayloadSizes.set(abs, this.payloadSizeFor(abs, kind));
             this.pendingChanges.set(abs, { kind });
             // Only directories are needed to disambiguate a native recursive
             // rename-after-delete. Unknown paths already correctly default to an
@@ -1495,11 +1526,14 @@ export class TreeWatcher {
         if (this.windowDeadlineAt === null && Number.isFinite(this.maxWaitMs)) {
             this.windowDeadlineAt = now + this.maxWaitMs;
         }
+        const quietWindowMs = this.isSmallPendingBatch()
+            ? this.smallBatchDebounceMs
+            : this.debounceMs;
         // Quiet-period debounce, capped by the window's max-wait deadline so a
         // continuous event stream cannot postpone the emit forever.
         const delayMs = this.windowDeadlineAt === null
-            ? this.debounceMs
-            : Math.max(0, Math.min(this.debounceMs, this.windowDeadlineAt - now));
+            ? quietWindowMs
+            : Math.max(0, Math.min(quietWindowMs, this.windowDeadlineAt - now));
         this.timer = this.clock.setTimeout(() => {
             this.timer = null;
             this.emit();
@@ -1541,6 +1575,7 @@ export class TreeWatcher {
         this.pendingStartedAt = null;
         this.pending.clear();
         this.pendingChanges.clear();
+        this.pendingPayloadSizes.clear();
         this.pendingBytes = 0;
         this.overflowed = false;
         this.overflowLogged = false;
@@ -1549,6 +1584,39 @@ export class TreeWatcher {
         this.droppedRouteHints.clear();
         this.droppedRoutesUnknown = false;
     }
+    payloadSizeFor(absolutePath, kind) {
+        // Exact deletes transfer no content; directory operations can expand to an
+        // arbitrary subtree and therefore never take the latency shortcut.
+        if (kind === "unlink")
+            return 0;
+        if (kind === "unlinkDir" || kind === "addDir")
+            return null;
+        try {
+            const stat = fs.lstatSync(absolutePath);
+            return stat.isFile() ? stat.size : null;
+        }
+        catch {
+            // An upsert whose bytes cannot be read is not proven small.
+            return null;
+        }
+    }
+    isSmallPendingBatch() {
+        if (this.smallBatchDebounceMs === null ||
+            this.overflowed ||
+            this.pending.size === 0 ||
+            this.pending.size > this.smallBatchMaxPaths) {
+            return false;
+        }
+        let bytes = 0;
+        for (const size of this.pendingPayloadSizes.values()) {
+            if (size === null)
+                return false;
+            bytes += size;
+            if (bytes > this.smallBatchMaxBytes)
+                return false;
+        }
+        return true;
+    }
     /**
      * Recover mutations that happened while chokidar was building its initial
      * watch set. `ignoreInitial` intentionally suppresses those initial events,
@@ -1709,6 +1777,19 @@ async function computeContentHash(absolutePath) {
 }
 /** Maximum paths remembered by one emitter to suppress unchanged announcements. */
 export const DEFAULT_PUBLISHED_CONTENT_HASH_MAX_PATHS = 50_000;
+/** Minimum delay between successful upsert announcements for one path. */
+export const DEFAULT_PUBLISH_MIN_INTERVAL_MS = 60_000;
+export const PUBLISH_MIN_INTERVAL_MS_ENV = "HQ_SYNC_PUBLISH_MIN_INTERVAL_MS";
+/** Resolve the optional per-path announcement interval without accepting invalid values. */
+export function resolvePublishMinIntervalMs(env = process.env) {
+    const raw = env[PUBLISH_MIN_INTERVAL_MS_ENV];
+    if (raw === undefined || raw.trim() === "")
+        return DEFAULT_PUBLISH_MIN_INTERVAL_MS;
+    const value = Number(raw);
+    return Number.isFinite(value) && value >= 0
+        ? Math.floor(value)
+        : DEFAULT_PUBLISH_MIN_INTERVAL_MS;
+}
 const PUBLISHED_CONTENT_HASH_RECORD_SET = 0x5031;
 const PUBLISHED_CONTENT_HASH_RECORD_DELETE = 0x5032;
 /**
@@ -1797,6 +1878,7 @@ function reduceDurablePublishedContentHashState(state, record) {
 class BoundedPublishedContentHashes {
     maxPaths;
     hashes = new Map();
+    publishedAt = new Map();
     constructor(maxPaths) {
         this.maxPaths = Math.max(1, Math.floor(maxPaths ?? DEFAULT_PUBLISHED_CONTENT_HASH_MAX_PATHS));
     }
@@ -1808,18 +1890,27 @@ class BoundedPublishedContentHashes {
         this.hashes.set(relativePath, hash);
         return hash;
     }
-    set(relativePath, contentHash) {
+    set(relativePath, contentHash, publishedAt) {
         this.hashes.delete(relativePath);
         this.hashes.set(relativePath, contentHash);
+        if (publishedAt !== undefined)
+            this.publishedAt.set(relativePath, publishedAt);
+        else
+            this.publishedAt.delete(relativePath);
         while (this.hashes.size > this.maxPaths) {
             const oldest = this.hashes.keys().next().value;
             if (oldest === undefined)
                 return;
             this.hashes.delete(oldest);
+            this.publishedAt.delete(oldest);
         }
     }
+    getPublishedAt(relativePath) {
+        return this.publishedAt.get(relativePath);
+    }
     delete(relativePath) {
         this.hashes.delete(relativePath);
+        this.publishedAt.delete(relativePath);
     }
 }
 /** Successful attempts retained in the batch outcome record for context. */
@@ -1879,6 +1970,7 @@ export class PushEventEmitter {
     transport;
     flagProvider;
     now;
+    clock;
     onError;
     onPublishOutcome;
     logger;
@@ -1887,6 +1979,15 @@ export class PushEventEmitter {
     lastPublishedContentHashes;
     durablePublishedContentHashes;
     lastPublishedContentHashMaxPaths;
+    publishMinIntervalMs;
+    /**
+     * A captured event whose bytes were already uploaded by the scoped push that
+     * called emitForBatch. Never retain only a path here: a later local rewrite
+     * can otherwise make the trailing announcement describe bytes absent from S3.
+     */
+    deferredPublishes = new Map();
+    deferredPublishTimers = new Map();
+    disposed = false;
     internalSeq = 0;
     nextSeq;
     publishTail = Promise.resolve();
@@ -1896,6 +1997,7 @@ export class PushEventEmitter {
         this.transport = opts.transport;
         this.flagProvider = opts.flagProvider;
         this.now = opts.now ?? (() => new Date());
+        this.clock = opts.clock ?? systemClock;
         this.logger = opts.logger;
         this.telemetryClient = opts.telemetryClient;
         this.telemetryClaims = opts.telemetryClaims;
@@ -1905,6 +2007,11 @@ export class PushEventEmitter {
         this.lastPublishedContentHashMaxPaths = Math.max(1, Math.floor(opts.lastPublishedContentHashMaxPaths ??
             DEFAULT_PUBLISHED_CONTENT_HASH_MAX_PATHS));
         this.lastPublishedContentHashes = new BoundedPublishedContentHashes(this.lastPublishedContentHashMaxPaths);
+        const configuredPublishMinIntervalMs = opts.publishMinIntervalMs ?? resolvePublishMinIntervalMs();
+        this.publishMinIntervalMs =
+            Number.isFinite(configuredPublishMinIntervalMs) && configuredPublishMinIntervalMs >= 0
+                ? Math.floor(configuredPublishMinIntervalMs)
+                : DEFAULT_PUBLISH_MIN_INTERVAL_MS;
         this.durablePublishedContentHashes = opts.lastPublishedContentHashStateDir
             ? this.openDurablePublishedContentHashes(opts.lastPublishedContentHashStateDir, opts.initialPublishedContentHashes ?? {})
             : null;
@@ -1942,7 +2049,7 @@ export class PushEventEmitter {
      * poll covers any miss).
      */
     async emitForBatch(batch) {
-        if (!this.enabled)
+        if (this.disposed || !this.enabled)
             return;
         const entriesByRel = new Map();
         for (const [absolutePath, relativePath] of batch.paths.entries()) {
@@ -1960,6 +2067,9 @@ export class PushEventEmitter {
             const settled = await Promise.all(chunk.map(([absolutePath, relativePath]) => this.emitOne(absolutePath, relativePath)));
             attempts.push(...settled.filter((attempt) => attempt !== undefined));
         }
+        this.reportPublishOutcome(attempts);
+    }
+    reportPublishOutcome(attempts) {
         try {
             this.onPublishOutcome(summarizePublishBatchOutcome(attempts));
         }
@@ -1977,13 +2087,12 @@ export class PushEventEmitter {
                 return undefined;
             const contentHash = await computeContentHash(absolutePath);
             if (this.wasPublished(relativePath, contentHash)) {
+                // This later, successfully-pushed revision restores the current
+                // publication. Its stale deferred predecessor must not announce after
+                // the scoped push has already replaced its S3 bytes.
+                this.clearDeferredPublish(relativePath);
                 return undefined;
             }
-            // A different observed revision breaks the old publication guarantee even
-            // if this transport attempt fails. Clearing first makes a later revert
-            // re-announce instead of silently treating it as the old content.
-            this.lastPublishedContentHashes.delete(relativePath);
-            await this.deleteDurablePublishedContentHash(relativePath);
             event = {
                 kind: "upsert",
                 relativePath,
@@ -1994,6 +2103,17 @@ export class PushEventEmitter {
                 sequenceNumber: this.nextSeq(),
                 eventTimestamp: this.now().toISOString(),
             };
+            const lastPublishedAt = this.lastPublishedContentHashes.getPublishedAt(relativePath);
+            if (lastPublishedAt !== undefined &&
+                this.clock.now() - lastPublishedAt < this.publishMinIntervalMs) {
+                this.deferUpsert(event, lastPublishedAt);
+                return undefined;
+            }
+            // A different observed revision breaks the old publication guarantee even
+            // if this transport attempt fails. Clearing first makes a later revert
+            // re-announce instead of silently treating it as the old content.
+            this.lastPublishedContentHashes.delete(relativePath);
+            await this.deleteDurablePublishedContentHash(relativePath);
         }
         catch (err) {
             const code = err && typeof err === "object" && "code" in err
@@ -2011,6 +2131,7 @@ export class PushEventEmitter {
             // targeted pull and let the vault-confirmed tombstone path remove it.
             // Invalidate before the attempt for the same failure/recreation posture
             // as a changed upsert above.
+            this.clearDeferredPublish(relativePath);
             this.lastPublishedContentHashes.delete(relativePath);
             await this.deleteDurablePublishedContentHash(relativePath);
             event = {
@@ -2022,6 +2143,9 @@ export class PushEventEmitter {
                 eventTimestamp: this.now().toISOString(),
             };
         }
+        return this.publishEvent(event);
+    }
+    async publishEvent(event) {
         // US-011: 1st link of the 3-log diagnostic chain. Stamps the same
         // `sequenceNumber` the server `push.receive` log and the client
         // `fanout.receive` log carry, so an operator can walk one event
@@ -2040,14 +2164,14 @@ export class PushEventEmitter {
         try {
             await this.transport.publish(event);
             if (event.kind === "upsert" && event.contentHash !== undefined) {
-                this.lastPublishedContentHashes.set(relativePath, event.contentHash);
-                await this.setDurablePublishedContentHash(relativePath, event.contentHash);
+                this.lastPublishedContentHashes.set(event.relativePath, event.contentHash, this.clock.now());
+                await this.setDurablePublishedContentHash(event.relativePath, event.contentHash);
             }
             else {
                 // A later recreation with the same bytes is a real state transition,
                 // so a successfully published tombstone must never suppress it.
-                this.lastPublishedContentHashes.delete(relativePath);
-                await this.deleteDurablePublishedContentHash(relativePath);
+                this.lastPublishedContentHashes.delete(event.relativePath);
+                await this.deleteDurablePublishedContentHash(event.relativePath);
             }
             const outcome = getPublishSuccessOutcome(event);
             return {
@@ -2059,7 +2183,7 @@ export class PushEventEmitter {
             // Push failure (network / non-2xx / timeout). The cadence poll is the
             // safety net — log + continue, never throw.
             this.onError(err instanceof Error ? err : new Error(String(err)), {
-                relativePath,
+                relativePath: event.relativePath,
             });
             this.emitPublishFailureTelemetry(event.kind, "publish");
             return {
@@ -2117,6 +2241,53 @@ export class PushEventEmitter {
             });
         }
     }
+    /** Remember one latest-wins uploaded revision until its publish interval ends. */
+    deferUpsert(event, lastPublishedAt) {
+        const relativePath = event.relativePath;
+        this.deferredPublishes.delete(relativePath);
+        this.deferredPublishes.set(relativePath, event);
+        while (this.deferredPublishes.size > this.lastPublishedContentHashMaxPaths) {
+            const oldest = this.deferredPublishes.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.clearDeferredPublish(oldest);
+        }
+        if (this.deferredPublishTimers.has(relativePath))
+            return;
+        const delay = Math.max(0, lastPublishedAt + this.publishMinIntervalMs - this.clock.now());
+        const timer = this.clock.setTimeout(() => this.flushDeferredPublish(relativePath), delay);
+        this.deferredPublishTimers.set(relativePath, timer);
+    }
+    flushDeferredPublish(relativePath) {
+        const deferred = this.deferredPublishes.get(relativePath);
+        this.clearDeferredPublish(relativePath);
+        if (this.disposed || !deferred)
+            return;
+        const run = this.publishTail.then(async () => {
+            this.reportPublishOutcome([await this.publishEvent(deferred)]);
+        }, async () => {
+            this.reportPublishOutcome([await this.publishEvent(deferred)]);
+        });
+        this.publishTail = run.catch(() => undefined);
+    }
+    clearDeferredPublish(relativePath) {
+        this.deferredPublishes.delete(relativePath);
+        const timer = this.deferredPublishTimers.get(relativePath);
+        if (timer !== undefined)
+            this.clock.clearTimeout(timer);
+        this.deferredPublishTimers.delete(relativePath);
+    }
+    /** Cancel every trailing publish and make future batch delivery inert. */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        for (const timer of this.deferredPublishTimers.values()) {
+            this.clock.clearTimeout(timer);
+        }
+        this.deferredPublishTimers.clear();
+        this.deferredPublishes.clear();
+    }
     emitPublishFailureTelemetry(kind, stage) {
         void emitCloudTelemetry(this.telemetryClient, {
             eventName: "push_event_failed",