@indigoai-us/hq-cloud 6.16.31 → 6.16.33

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/dist/bin/sync-runner-watch-loop.d.ts.map +1 -1
  2. package/dist/bin/sync-runner-watch-loop.js +92 -2
  3. package/dist/bin/sync-runner-watch-loop.js.map +1 -1
  4. package/dist/bin/sync-runner.d.ts +7 -0
  5. package/dist/bin/sync-runner.d.ts.map +1 -1
  6. package/dist/bin/sync-runner.js.map +1 -1
  7. package/dist/bin/sync-runner.test.js +148 -2
  8. package/dist/bin/sync-runner.test.js.map +1 -1
  9. package/dist/ignore.d.ts +40 -14
  10. package/dist/ignore.d.ts.map +1 -1
  11. package/dist/ignore.js +119 -60
  12. package/dist/ignore.js.map +1 -1
  13. package/dist/ignore.test.js +205 -29
  14. package/dist/ignore.test.js.map +1 -1
  15. package/dist/journal-baseline.test.d.ts +2 -0
  16. package/dist/journal-baseline.test.d.ts.map +1 -0
  17. package/dist/journal-baseline.test.js +215 -0
  18. package/dist/journal-baseline.test.js.map +1 -0
  19. package/dist/journal-store.test.js +48 -1
  20. package/dist/journal-store.test.js.map +1 -1
  21. package/dist/journal.d.ts +17 -2
  22. package/dist/journal.d.ts.map +1 -1
  23. package/dist/journal.js +124 -11
  24. package/dist/journal.js.map +1 -1
  25. package/dist/sync/area-ledger-migration.d.ts +31 -1
  26. package/dist/sync/area-ledger-migration.d.ts.map +1 -1
  27. package/dist/sync/area-ledger-migration.js +47 -10
  28. package/dist/sync/area-ledger-migration.js.map +1 -1
  29. package/dist/sync/area-ledger-migration.test.js +27 -0
  30. package/dist/sync/area-ledger-migration.test.js.map +1 -1
  31. package/dist/sync/area-ledger.d.ts.map +1 -1
  32. package/dist/sync/area-ledger.js +14 -2
  33. package/dist/sync/area-ledger.js.map +1 -1
  34. package/dist/sync/area-ledger.test.js +37 -0
  35. package/dist/sync/area-ledger.test.js.map +1 -1
  36. package/dist/watcher.d.ts +39 -0
  37. package/dist/watcher.d.ts.map +1 -1
  38. package/dist/watcher.js +106 -12
  39. package/dist/watcher.js.map +1 -1
  40. package/dist/watcher.test.js +410 -0
  41. package/dist/watcher.test.js.map +1 -1
  42. package/package.json +1 -1
@@ -168,6 +168,43 @@ describe("TreeWatcher pending backlog caps", () => {
168
168
  fs.rmSync(dir, { recursive: true, force: true });
169
169
  }
170
170
  });
171
+ it("keeps a warm-up epoch only for a queued deletion capture, and only while it runs", async () => {
172
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watcher-warmup-epochs-"));
173
+ try {
174
+ for (let i = 0; i < 6; i++)
175
+ fs.writeFileSync(path.join(dir, `unchanged-${i}.md`), "old");
176
+ const settle = Date.now() + 50;
177
+ while (Date.now() < settle) { /* let old ctime settle below the cutoff */ }
178
+ const cutoff = Date.now();
179
+ while (Date.now() < cutoff + 50) { /* filesystems may round ctime down */ }
180
+ for (let i = 0; i < 4; i++)
181
+ fs.writeFileSync(path.join(dir, `fresh-${i}.md`), "new");
182
+ let resolveCapture;
183
+ const watcher = new TreeWatcher({
184
+ hqRoot: dir,
185
+ pathFilter: () => true,
186
+ queueLocalDeleteSnapshots: async () => {
187
+ await new Promise((resolve) => { resolveCapture = resolve; });
188
+ return [];
189
+ },
190
+ });
191
+ const result = watcher.collectWarmupCatchup(cutoff, ["gone-during-warmup.md"]);
192
+ expect([...result.batch.paths.values()].sort()).toEqual([
193
+ "fresh-0.md", "fresh-1.md", "fresh-2.md", "fresh-3.md", "gone-during-warmup.md",
194
+ ]);
195
+ // Four live changes were recorded, but only the deletion has a capture
196
+ // in flight, so only the deletion holds an epoch.
197
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(1);
198
+ await new Promise((resolve) => setImmediate(resolve)); // the queued job starts
199
+ resolveCapture();
200
+ await new Promise((resolve) => setImmediate(resolve));
201
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(0);
202
+ watcher.dispose();
203
+ }
204
+ finally {
205
+ fs.rmSync(dir, { recursive: true, force: true });
206
+ }
207
+ });
171
208
  it("does not report a journal row as deleted when its file exists behind a symlinked directory", () => {
172
209
  // The warm-up walk never descends through a symlinked directory (a Dirent
173
210
  // symlink is not a directory), so rows journaled under such a path were
@@ -2907,6 +2944,379 @@ describe("TreeWatcher deferred delete snapshots", () => {
2907
2944
  watcher.dispose();
2908
2945
  fs.rmSync(hqRoot, { recursive: true, force: true });
2909
2946
  });
2947
+ // `deleteSnapshotEpochs` exists to let a newer revision of a path
2948
+ // invalidate a delete-snapshot capture that is still queued or running. A
2949
+ // long-lived runner touches hundreds of thousands of distinct paths, so a
2950
+ // key may live in that map only while such a capture is in flight; any
2951
+ // other write into it is a leak keyed by path.
2952
+ const settle = () => new Promise((resolve) => setImmediate(resolve));
2953
+ it("retires a superseded capture's epoch when that capture completes", async () => {
2954
+ const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-epoch-retire-"));
2955
+ const clock = new FakeClock();
2956
+ let resolveCapture;
2957
+ let observedCurrent = true;
2958
+ const watcher = new TreeWatcher({
2959
+ hqRoot,
2960
+ clock,
2961
+ debounceMs: 25,
2962
+ pathFilter: () => true,
2963
+ queueLocalDeleteSnapshots: async (_relative, _kind, isCurrent) => {
2964
+ await new Promise((resolve) => { resolveCapture = resolve; });
2965
+ observedCurrent = isCurrent();
2966
+ return [];
2967
+ },
2968
+ });
2969
+ try {
2970
+ const target = path.join(hqRoot, "recreated.md");
2971
+ watcher.handleEvent(target, "unlink");
2972
+ await Promise.resolve();
2973
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(1);
2974
+ // The newer revision invalidates the running capture but must keep the
2975
+ // marker until that capture has actually observed it.
2976
+ watcher.handleEvent(target, "add");
2977
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(1);
2978
+ resolveCapture();
2979
+ await settle();
2980
+ expect(observedCurrent).toBe(false);
2981
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(0);
2982
+ }
2983
+ finally {
2984
+ watcher.dispose();
2985
+ fs.rmSync(hqRoot, { recursive: true, force: true });
2986
+ }
2987
+ });
2988
+ it("never creates an epoch for a live event or for a synchronous capture", () => {
2989
+ const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-epoch-live-"));
2990
+ const clock = new FakeClock();
2991
+ const capture = vi.fn(() => []);
2992
+ const watcher = new TreeWatcher({
2993
+ hqRoot,
2994
+ clock,
2995
+ debounceMs: 25,
2996
+ pathFilter: () => true,
2997
+ captureLocalDeleteSnapshots: capture,
2998
+ });
2999
+ try {
3000
+ watcher.handleEvent(path.join(hqRoot, "added.md"), "add");
3001
+ watcher.handleEvent(path.join(hqRoot, "edited.md"), "change");
3002
+ watcher.handleEvent(path.join(hqRoot, "made"), "addDir");
3003
+ watcher.handleEvent(path.join(hqRoot, "gone.md"), "unlink");
3004
+ watcher.handleEvent(path.join(hqRoot, "gone-dir"), "unlinkDir");
3005
+ clock.advance(25);
3006
+ expect(capture).toHaveBeenCalledTimes(2);
3007
+ // A synchronous capture has already run by the time the event returns:
3008
+ // there is nothing left to invalidate, so there is nothing to remember.
3009
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(0);
3010
+ }
3011
+ finally {
3012
+ watcher.dispose();
3013
+ fs.rmSync(hqRoot, { recursive: true, force: true });
3014
+ }
3015
+ });
3016
+ it("shares one epoch across overlapping captures of a path and retires it with the last", async () => {
3017
+ const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-epoch-overlap-"));
3018
+ const clock = new FakeClock();
3019
+ const resolvers = [];
3020
+ const observed = [];
3021
+ const watcher = new TreeWatcher({
3022
+ hqRoot,
3023
+ clock,
3024
+ debounceMs: 25,
3025
+ pathFilter: () => true,
3026
+ queueLocalDeleteSnapshots: async (_relative, _kind, isCurrent) => {
3027
+ await new Promise((resolve) => { resolvers.push(resolve); });
3028
+ observed.push(isCurrent());
3029
+ return [];
3030
+ },
3031
+ });
3032
+ try {
3033
+ const target = path.join(hqRoot, "twice.md");
3034
+ watcher.handleEvent(target, "unlink");
3035
+ await Promise.resolve();
3036
+ watcher.handleEvent(target, "unlink"); // second delete in the window queues behind the first
3037
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(1);
3038
+ resolvers.shift()();
3039
+ await settle();
3040
+ // The first capture was superseded by the second; the second is still
3041
+ // queued, so the path keeps its marker.
3042
+ expect(observed).toEqual([false]);
3043
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(1);
3044
+ resolvers.shift()();
3045
+ await settle();
3046
+ expect(observed).toEqual([false, true]);
3047
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(0);
3048
+ }
3049
+ finally {
3050
+ watcher.dispose();
3051
+ fs.rmSync(hqRoot, { recursive: true, force: true });
3052
+ }
3053
+ });
3054
+ it("leaves no epoch for a path whose capture the full queue rejected", async () => {
3055
+ const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-epoch-full-"));
3056
+ const clock = new FakeClock();
3057
+ const resolvers = [];
3058
+ const observed = [];
3059
+ const watcher = new TreeWatcher({
3060
+ hqRoot,
3061
+ clock,
3062
+ debounceMs: 25,
3063
+ pathFilter: () => true,
3064
+ maxPendingPaths: 2,
3065
+ queueLocalDeleteSnapshots: async (relative, _kind, isCurrent) => {
3066
+ await new Promise((resolve) => { resolvers.push(resolve); });
3067
+ observed.push(`${relative}:${isCurrent()}`);
3068
+ return [];
3069
+ },
3070
+ });
3071
+ const consoleError = vi.spyOn(console, "error").mockImplementation(() => undefined);
3072
+ try {
3073
+ const a = path.join(hqRoot, "a.md");
3074
+ const b = path.join(hqRoot, "b.md");
3075
+ watcher.handleEvent(a, "unlink");
3076
+ await Promise.resolve();
3077
+ resolvers.shift()();
3078
+ await settle(); // a's capture is done; a is still pending in the window
3079
+ expect(observed).toEqual(["a.md:true"]);
3080
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(0);
3081
+ watcher.handleEvent(b, "unlink");
3082
+ watcher.handleEvent(b, "unlink"); // two captures queued for b: the queue is full
3083
+ // A third delete of `a` finds the queue full. Nothing is in flight for
3084
+ // `a`, so nothing may be recorded for it either.
3085
+ watcher.handleEvent(a, "unlink");
3086
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(1);
3087
+ // A full queue must still supersede a capture that IS in flight for the
3088
+ // path, exactly as it did before, and that path's marker still retires.
3089
+ watcher.handleEvent(b, "unlink");
3090
+ await settle(); // the first queued capture for b starts
3091
+ resolvers.shift()();
3092
+ await settle(); // ...and the second, queued behind it
3093
+ resolvers.shift()();
3094
+ await settle();
3095
+ expect(observed).toEqual(["a.md:true", "b.md:false", "b.md:false"]);
3096
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(0);
3097
+ }
3098
+ finally {
3099
+ consoleError.mockRestore();
3100
+ watcher.dispose();
3101
+ fs.rmSync(hqRoot, { recursive: true, force: true });
3102
+ }
3103
+ });
3104
+ });
3105
+ describe("TreeWatcher untracked delete drop", () => {
3106
+ // Atomic writers (`.name.<pid>.<random>.tmp` renamed into place, editor
3107
+ // swap files) create and remove a path within one debounce window. Such a
3108
+ // path has no journal row, so its unlink has nothing to delete remotely and
3109
+ // no revision to bind: queueing it only cost a delete-snapshot capture, a
3110
+ // pending-map slot, and a targeted push that found nothing on disk. On the
3111
+ // controller these were 370 of 380 agency watcher events per minute.
3112
+ function makeRoot() {
3113
+ return fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-untracked-"));
3114
+ }
3115
+ it("drops a file unlink that has no journal row before it reaches a batch", () => {
3116
+ const hqRoot = makeRoot();
3117
+ const clock = new FakeClock();
3118
+ const capture = vi.fn(() => []);
3119
+ const watcher = new TreeWatcher({
3120
+ hqRoot,
3121
+ clock,
3122
+ debounceMs: 25,
3123
+ pathFilter: () => true,
3124
+ captureLocalDeleteSnapshots: capture,
3125
+ isUntrackedDelete: (relativePath) => relativePath.endsWith(".tmp"),
3126
+ });
3127
+ const batches = [];
3128
+ watcher.onChange((_first, batch) => batches.push([...(batch?.paths.values() ?? [])]));
3129
+ try {
3130
+ watcher.handleEvent(path.join(hqRoot, "notes", ".draft.md.123.abc.tmp"), "unlink");
3131
+ watcher.handleEvent(path.join(hqRoot, "notes", "kept.md"), "unlink");
3132
+ clock.advance(25);
3133
+ expect(batches).toEqual([["notes/kept.md"]]);
3134
+ // The dropped path never paid for a delete-snapshot capture.
3135
+ expect(capture).toHaveBeenCalledTimes(1);
3136
+ expect(capture).toHaveBeenCalledWith("notes/kept.md", "unlink");
3137
+ expect(watcher.untrackedDeletesDropped()).toBe(1);
3138
+ // Neither path leaves an epoch behind: the kept unlink was captured
3139
+ // synchronously (nothing in flight to invalidate) and the dropped one
3140
+ // never had a capture at all.
3141
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(0);
3142
+ }
3143
+ finally {
3144
+ watcher.dispose();
3145
+ fs.rmSync(hqRoot, { recursive: true, force: true });
3146
+ }
3147
+ });
3148
+ it("leaves no delete-snapshot epoch behind for an atomic write cancelled inside its own window", () => {
3149
+ // Every agency writer saves through `.<name>.<pid>.<random>.tmp` and
3150
+ // renames it into place, so the watcher sees an `add` and then an
3151
+ // `unlink` of a name it will never see again. 370 of those a minute on
3152
+ // the controller: if each one left a key in a per-path map, the map
3153
+ // would grow by half a million randomised paths a day.
3154
+ const hqRoot = makeRoot();
3155
+ const clock = new FakeClock();
3156
+ const queue = vi.fn(async () => []);
3157
+ const watcher = new TreeWatcher({
3158
+ hqRoot,
3159
+ clock,
3160
+ debounceMs: 25,
3161
+ pathFilter: () => true,
3162
+ queueLocalDeleteSnapshots: queue,
3163
+ isUntrackedDelete: (relativePath) => relativePath.endsWith(".tmp"),
3164
+ });
3165
+ const changed = vi.fn();
3166
+ watcher.onChange(changed);
3167
+ try {
3168
+ for (let i = 0; i < 250; i++) {
3169
+ const temp = path.join(hqRoot, "workspace", "agency", `.ledger.json.${i}.${(i * 7919).toString(36)}.tmp`);
3170
+ watcher.handleEvent(temp, "add");
3171
+ watcher.handleEvent(temp, "unlink");
3172
+ }
3173
+ clock.advance(1_000);
3174
+ expect(queue).not.toHaveBeenCalled();
3175
+ expect(changed).not.toHaveBeenCalled();
3176
+ expect(watcher.untrackedDeletesDropped()).toBe(250);
3177
+ expect(watcher.pendingTimerCount()).toBe(0);
3178
+ expect(watcher.censusSizes()).toMatchObject({ deleteSnapshotEpochs: 0, knownKinds: 0 });
3179
+ }
3180
+ finally {
3181
+ watcher.dispose();
3182
+ fs.rmSync(hqRoot, { recursive: true, force: true });
3183
+ }
3184
+ });
3185
+ it("resolves a vanished rename to an unlink, purges the path's earlier queued add, and leaves no timer armed", () => {
3186
+ const hqRoot = makeRoot();
3187
+ const clock = new FakeClock();
3188
+ const seam = vi.fn((relativePath) => relativePath.endsWith(".tmp"));
3189
+ const watcher = new TreeWatcher({
3190
+ hqRoot,
3191
+ clock,
3192
+ debounceMs: 25,
3193
+ pathFilter: () => true,
3194
+ isUntrackedDelete: seam,
3195
+ });
3196
+ const changed = vi.fn();
3197
+ watcher.onChange(changed);
3198
+ try {
3199
+ const temp = path.join(hqRoot, "state.json.tmp");
3200
+ fs.writeFileSync(temp, "{}");
3201
+ watcher.handleEvent(temp, "rename"); // exists → add
3202
+ expect(watcher.pendingTimerCount()).toBe(1);
3203
+ fs.rmSync(temp);
3204
+ watcher.handleEvent(temp, "rename"); // ENOENT → unlink → untracked → dropped
3205
+ // The create and the delete cancelled out inside one window. Nothing is
3206
+ // left to emit, so the window closes without waking the push at all.
3207
+ expect(seam).toHaveBeenCalledWith("state.json.tmp");
3208
+ expect(watcher.pendingTimerCount()).toBe(0);
3209
+ clock.advance(1_000);
3210
+ expect(changed).not.toHaveBeenCalled();
3211
+ expect(watcher.untrackedDeletesDropped()).toBe(1);
3212
+ }
3213
+ finally {
3214
+ watcher.dispose();
3215
+ fs.rmSync(hqRoot, { recursive: true, force: true });
3216
+ }
3217
+ });
3218
+ it("keeps journaled unlinks and never consults the seam for live files or directory deletes", () => {
3219
+ const hqRoot = makeRoot();
3220
+ const clock = new FakeClock();
3221
+ const seam = vi.fn(() => false);
3222
+ const capture = vi.fn(() => []);
3223
+ const watcher = new TreeWatcher({
3224
+ hqRoot,
3225
+ clock,
3226
+ debounceMs: 25,
3227
+ pathFilter: () => true,
3228
+ captureLocalDeleteSnapshots: capture,
3229
+ isUntrackedDelete: seam,
3230
+ });
3231
+ const batches = [];
3232
+ watcher.onChange((_first, batch) => batches.push(batch?.paths ?? new Map()));
3233
+ try {
3234
+ const live = path.join(hqRoot, "live.md");
3235
+ fs.writeFileSync(live, "x");
3236
+ watcher.handleEvent(live, "add");
3237
+ // A directory with no row of its own may still cover journaled
3238
+ // descendants; only the capture's prefix scan can tell, so directory
3239
+ // deletes always go through.
3240
+ watcher.handleEvent(path.join(hqRoot, "gone-dir"), "unlinkDir");
3241
+ watcher.handleEvent(path.join(hqRoot, "journaled.md"), "unlink");
3242
+ clock.advance(25);
3243
+ expect(seam).toHaveBeenCalledTimes(1);
3244
+ expect(seam).toHaveBeenCalledWith("journaled.md");
3245
+ expect([...(batches[0]?.values() ?? [])].sort()).toEqual(["gone-dir", "journaled.md", "live.md"]);
3246
+ expect(capture).toHaveBeenCalledWith("gone-dir", "unlinkDir");
3247
+ expect(capture).toHaveBeenCalledWith("journaled.md", "unlink");
3248
+ expect(watcher.untrackedDeletesDropped()).toBe(0);
3249
+ }
3250
+ finally {
3251
+ watcher.dispose();
3252
+ fs.rmSync(hqRoot, { recursive: true, force: true });
3253
+ }
3254
+ });
3255
+ it("keeps the unlink when the seam throws", () => {
3256
+ const hqRoot = makeRoot();
3257
+ const clock = new FakeClock();
3258
+ const watcher = new TreeWatcher({
3259
+ hqRoot,
3260
+ clock,
3261
+ debounceMs: 25,
3262
+ pathFilter: () => true,
3263
+ isUntrackedDelete: () => {
3264
+ throw new Error("journal unavailable");
3265
+ },
3266
+ });
3267
+ const batches = [];
3268
+ watcher.onChange((_first, batch) => batches.push([...(batch?.paths.values() ?? [])]));
3269
+ const consoleError = vi.spyOn(console, "error").mockImplementation(() => undefined);
3270
+ try {
3271
+ expect(() => watcher.handleEvent(path.join(hqRoot, "maybe.md"), "unlink")).not.toThrow();
3272
+ clock.advance(25);
3273
+ // Dropping is an optimisation; keeping the event is the safe default.
3274
+ expect(batches).toEqual([["maybe.md"]]);
3275
+ expect(watcher.untrackedDeletesDropped()).toBe(0);
3276
+ }
3277
+ finally {
3278
+ consoleError.mockRestore();
3279
+ watcher.dispose();
3280
+ fs.rmSync(hqRoot, { recursive: true, force: true });
3281
+ }
3282
+ });
3283
+ it("a dropped unlink supersedes an in-flight queued capture for the same path", async () => {
3284
+ const hqRoot = makeRoot();
3285
+ const clock = new FakeClock();
3286
+ let untracked = false;
3287
+ let resolveCapture;
3288
+ let observedCurrent;
3289
+ const watcher = new TreeWatcher({
3290
+ hqRoot,
3291
+ clock,
3292
+ debounceMs: 25,
3293
+ pathFilter: () => true,
3294
+ isUntrackedDelete: () => untracked,
3295
+ queueLocalDeleteSnapshots: async (_relative, _kind, isCurrent) => {
3296
+ await new Promise((resolve) => { resolveCapture = resolve; });
3297
+ observedCurrent = isCurrent();
3298
+ return [];
3299
+ },
3300
+ });
3301
+ try {
3302
+ const target = path.join(hqRoot, "flip.md");
3303
+ watcher.handleEvent(target, "unlink"); // journal view cold: kept, capture queued
3304
+ await Promise.resolve();
3305
+ untracked = true;
3306
+ watcher.handleEvent(target, "unlink"); // journal view warm: no row → dropped
3307
+ resolveCapture();
3308
+ await Promise.resolve();
3309
+ // The queued capture must not bind a revision for a path the watcher
3310
+ // has since discarded.
3311
+ expect(observedCurrent).toBe(false);
3312
+ expect(watcher.pendingTimerCount()).toBe(0);
3313
+ expect(watcher.untrackedDeletesDropped()).toBe(1);
3314
+ }
3315
+ finally {
3316
+ watcher.dispose();
3317
+ fs.rmSync(hqRoot, { recursive: true, force: true });
3318
+ }
3319
+ });
2910
3320
  });
2911
3321
  // ---------------------------------------------------------------------------
2912
3322
  // Event-pass debounce configuration (HQ_SYNC_EVENT_DEBOUNCE_MS / _MAX_WAIT_MS)