@gusto/baerly-storage 0.2.0 → 0.3.0

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 (122) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +29 -0
  3. package/README.md +93 -52
  4. package/dist/API.md +151 -109
  5. package/dist/CHANGELOG.md +144 -0
  6. package/dist/THIRD-PARTY-LICENSES.txt +312 -0
  7. package/dist/{app-config-C0Bbw_Z6.d.ts → app-config-BIzyAKzy.d.ts} +14 -2
  8. package/dist/app-config.d.ts +1 -1
  9. package/dist/auth.d.ts +1 -1
  10. package/dist/auth.js +288 -288
  11. package/dist/auth.js.map +1 -1
  12. package/dist/baerly.js +10 -10
  13. package/dist/baerly.js.map +1 -1
  14. package/dist/bytes-BXdamO3L.js.map +1 -1
  15. package/dist/{client-DYZfoZb9.d.ts → client-BJXF3XJA.d.ts} +10 -10
  16. package/dist/client-react.d.ts +3 -3
  17. package/dist/client-react.js.map +1 -1
  18. package/dist/client.d.ts +3 -3
  19. package/dist/client.js.map +1 -1
  20. package/dist/{cloudflare-CINJPKCW.js → cloudflare-Cn2ibODt.js} +178 -2
  21. package/dist/cloudflare-Cn2ibODt.js.map +1 -0
  22. package/dist/cloudflare.d.ts +4 -4
  23. package/dist/cloudflare.js +10 -11
  24. package/dist/cloudflare.js.map +1 -1
  25. package/dist/{subcommand-DZcHcsYp.js → config-CGyBopy3.js} +643 -439
  26. package/dist/config-CGyBopy3.js.map +1 -0
  27. package/dist/context-DRZ3tZ5l.js.map +1 -1
  28. package/dist/{cost-CQt1YRkA.js → cost-BZ_MDBmn.js} +6 -4
  29. package/dist/cost-BZ_MDBmn.js.map +1 -0
  30. package/dist/{current-json-C-EyJqs0.js → current-json-DsN7FNY1.js} +47 -13
  31. package/dist/current-json-DsN7FNY1.js.map +1 -0
  32. package/dist/{db-BM3y2JQw.d.ts → db-CCT6tDfY.d.ts} +26 -108
  33. package/dist/{deploy-CrAbfgCq.js → deploy-BKKyGlSJ.js} +11 -4
  34. package/dist/deploy-BKKyGlSJ.js.map +1 -0
  35. package/dist/dev-vite.d.ts +5 -5
  36. package/dist/dev-vite.js +5 -5
  37. package/dist/dev-vite.js.map +1 -1
  38. package/dist/dev.d.ts +1 -1
  39. package/dist/dev.js +1 -1
  40. package/dist/{doctor-Db-hzPmE.js → doctor-BVU4GNXN.js} +13 -132
  41. package/dist/doctor-BVU4GNXN.js.map +1 -0
  42. package/dist/{dump-BYA55NLP.js → dump-DPEAKub6.js} +5 -3
  43. package/dist/dump-DPEAKub6.js.map +1 -0
  44. package/dist/errors-DOdL95kK.js.map +1 -1
  45. package/dist/{export-Bhbz90-z.js → export-BcuCLFFe.js} +6 -4
  46. package/dist/{export-Bhbz90-z.js.map → export-BcuCLFFe.js.map} +1 -1
  47. package/dist/{fsck-CPPZWt9p.js → fsck-RXgLOaJG.js} +23 -11
  48. package/dist/fsck-RXgLOaJG.js.map +1 -0
  49. package/dist/{http-Cw8p6y5b.js → http-Bd4byR4n.js} +45 -61
  50. package/dist/http-Bd4byR4n.js.map +1 -0
  51. package/dist/http.d.ts +15 -15
  52. package/dist/http.js +1 -1
  53. package/dist/{index-cUY-36AN.d.ts → index-BDceQQi-.d.ts} +20 -4
  54. package/dist/{index-C3JAH1Yo.d.ts → index-Cmsxx-ZN.d.ts} +9 -9
  55. package/dist/{index-DSvwEUeF.d.ts → index-DW7GT6M2.d.ts} +50 -42
  56. package/dist/{index-DwDTWPSU.d.ts → index-DnBGSeuU.d.ts} +10 -7
  57. package/dist/index.d.ts +6 -6
  58. package/dist/index.js +4 -4
  59. package/dist/{indexes-DAu2AkTW.d.ts → indexes-Cx7uMXm0.d.ts} +2 -2
  60. package/dist/{inspect-Bdbzvi-_.js → inspect-DhI49PSi.js} +16 -8
  61. package/dist/inspect-DhI49PSi.js.map +1 -0
  62. package/dist/{snapshot-SS8USDUF.js → log-tail-DXeDkWEp.js} +154 -83
  63. package/dist/log-tail-DXeDkWEp.js.map +1 -0
  64. package/dist/{maintenance-BRrThz8V.d.ts → maintenance-BkhUr72A.d.ts} +91 -26
  65. package/dist/{maintenance-ClzBC1Vv.js → maintenance-CWBQpZ2y.js} +368 -161
  66. package/dist/maintenance-CWBQpZ2y.js.map +1 -0
  67. package/dist/{maintenance-BvOv6BMM.js → maintenance-C_KSkVjd.js} +204 -82
  68. package/dist/maintenance-C_KSkVjd.js.map +1 -0
  69. package/dist/maintenance.d.ts +3 -2
  70. package/dist/maintenance.js +3 -2
  71. package/dist/node.d.ts +13 -8
  72. package/dist/node.js +1 -1
  73. package/dist/normalize-XWY25_sG.js.map +1 -1
  74. package/dist/{observability-CpOiEN0k.js → observability-BYd-RzEx.js} +63 -55
  75. package/dist/observability-BYd-RzEx.js.map +1 -0
  76. package/dist/observability.d.ts +3 -3
  77. package/dist/observability.js +1 -1
  78. package/dist/{plan-DOTl21vq.js → plan-DIu_B6fy.js} +7 -4
  79. package/dist/plan-DIu_B6fy.js.map +1 -0
  80. package/dist/{query-BmiQy328.js → query-sQNO5vU_.js} +1071 -1099
  81. package/dist/query-sQNO5vU_.js.map +1 -0
  82. package/dist/{rebuild-index-DC_nR6wP.js → rebuild-index-DP4CqSSs.js} +5 -4
  83. package/dist/rebuild-index-DP4CqSSs.js.map +1 -0
  84. package/dist/{restore-C6IcmLeA.js → restore-DpQYef6r.js} +362 -328
  85. package/dist/restore-DpQYef6r.js.map +1 -0
  86. package/dist/shared-secret-BJdSwpgw.js.map +1 -1
  87. package/dist/{src-QQ7jDeL2.js → src-CWpkSbvJ.js} +40 -20
  88. package/dist/src-CWpkSbvJ.js.map +1 -0
  89. package/dist/{src-DU1sCMlr.js → src-D24wDpzR.js} +269 -258
  90. package/dist/src-D24wDpzR.js.map +1 -0
  91. package/dist/{src-zhEAmmF7.js → src-Db4-qVtM.js} +36 -96
  92. package/dist/src-Db4-qVtM.js.map +1 -0
  93. package/dist/subcommand-CP9NY2J4.js +159 -0
  94. package/dist/subcommand-CP9NY2J4.js.map +1 -0
  95. package/dist/{usage-CLjirdD-.js → usage-CTfDq9HR.js} +3 -3
  96. package/dist/{usage-CLjirdD-.js.map → usage-CTfDq9HR.js.map} +1 -1
  97. package/dist/{validate-DCq_0DIn.js → validate-DtljsCh1.js} +51 -51
  98. package/dist/{validate-DCq_0DIn.js.map → validate-DtljsCh1.js.map} +1 -1
  99. package/package.json +40 -29
  100. package/dist/cloudflare-CINJPKCW.js.map +0 -1
  101. package/dist/config-DVfDGyw1.js +0 -278
  102. package/dist/config-DVfDGyw1.js.map +0 -1
  103. package/dist/cost-CQt1YRkA.js.map +0 -1
  104. package/dist/current-json-C-EyJqs0.js.map +0 -1
  105. package/dist/deploy-CrAbfgCq.js.map +0 -1
  106. package/dist/doctor-Db-hzPmE.js.map +0 -1
  107. package/dist/dump-BYA55NLP.js.map +0 -1
  108. package/dist/fsck-CPPZWt9p.js.map +0 -1
  109. package/dist/http-Cw8p6y5b.js.map +0 -1
  110. package/dist/inspect-Bdbzvi-_.js.map +0 -1
  111. package/dist/maintenance-BvOv6BMM.js.map +0 -1
  112. package/dist/maintenance-ClzBC1Vv.js.map +0 -1
  113. package/dist/observability-CpOiEN0k.js.map +0 -1
  114. package/dist/plan-DOTl21vq.js.map +0 -1
  115. package/dist/query-BmiQy328.js.map +0 -1
  116. package/dist/rebuild-index-DC_nR6wP.js.map +0 -1
  117. package/dist/restore-C6IcmLeA.js.map +0 -1
  118. package/dist/snapshot-SS8USDUF.js.map +0 -1
  119. package/dist/src-DU1sCMlr.js.map +0 -1
  120. package/dist/src-QQ7jDeL2.js.map +0 -1
  121. package/dist/src-zhEAmmF7.js.map +0 -1
  122. package/dist/subcommand-DZcHcsYp.js.map +0 -1
@@ -1,5 +1,5 @@
1
- import { d as IndexDefinition } from "./app-config-C0Bbw_Z6.js";
2
- import { h as Storage, p as CurrentJson } from "./index-DSvwEUeF.js";
1
+ import { d as IndexDefinition } from "./app-config-BIzyAKzy.js";
2
+ import { h as Storage, p as CurrentJson } from "./index-DW7GT6M2.js";
3
3
  //#region packages/server/src/compactor.d.ts
4
4
  /**
5
5
  * Public configuration knobs for {@link compact}. All optional; the
@@ -54,6 +54,19 @@ interface InternalCompactOptions extends CompactOptions {
54
54
  * row count balloons.
55
55
  */
56
56
  readonly ceilingEntries?: number;
57
+ /**
58
+ * @internal A fresh tail LOWER BOUND the caller already observed (the
59
+ * write-tick runner threads the writer's in-memory `observedTail`,
60
+ * `seq + 1`). When present it raises the ceiling-probe FLOOR to
61
+ * `max(log_seq_start, tail_hint, knownTail)`, so on a stale-low stored
62
+ * `tail_hint` the forward probe walks only "commits since this writer's
63
+ * commit" instead of re-walking the whole gap from the stale hint
64
+ * (which could blow the CF subrequest budget — B4). The compactor still
65
+ * discovers the TRUE tail by probing UP from this floor (small gap).
66
+ * Absent on the scheduled path ⇒ probe from `max(log_seq_start,
67
+ * tail_hint)` as before.
68
+ */
69
+ readonly knownTail?: number;
57
70
  }
58
71
  interface CompactResult {
59
72
  /** `true` iff a new snapshot landed and `current.json` was advanced. */
@@ -274,7 +287,7 @@ interface RebuildIndexOptions {
274
287
  * @throws BaerlyError code="InvalidResponse" — `current.json` missing.
275
288
  * @throws BaerlyError code="Internal" — protocol-invariant
276
289
  * violation (snapshot hash mismatch, missing log entry inside
277
- * `[log_seq_start, next_seq)`).
290
+ * `[log_seq_start, tail_hint)`).
278
291
  */
279
292
  declare const rebuildIndex: (storage: Storage, currentJsonKey: string, def: IndexDefinition, opts?: RebuildIndexOptions) => Promise<RebuildIndexResult>;
280
293
  //#endregion
@@ -337,34 +350,74 @@ interface MaintenanceResult {
337
350
  * ```
338
351
  */
339
352
  declare const runScheduledMaintenance: (args: MaintenanceArgs, options?: MaintenanceOptions) => Promise<MaintenanceResult>;
353
+ /** The six host-agnostic write-tick budgets (`maxFoldBytes`=`C`, `maxFoldRows`=`E`). Canonical shape; mirrors the protocol constants (typed there to avoid a cycle). */
354
+ interface MaintenanceProfile {
355
+ readonly gcInterval: number;
356
+ readonly gcMaxMarks: number;
357
+ readonly gcMaxSweeps: number;
358
+ readonly maxFoldEntriesPerPass: number;
359
+ readonly maxFoldBytes: number;
360
+ readonly maxFoldRows: number;
361
+ }
362
+ /**
363
+ * Tuning profile for the 50-subrequest Cloudflare free-tier budget,
364
+ * derived from {@link MAINTENANCE_PROFILE_CF_FREE} (one source of truth).
365
+ *
366
+ * Budget arithmetic (worst case):
367
+ * compact: 1 GET current + 1 GET snapshot (if any) + N GETs log
368
+ * + 1 PUT snapshot + 1 PUT current = 3 + N (N = maxEntriesPerRun).
369
+ * runGc: 1 GET current + 1 GET pending + 3 LISTs (one page each)
370
+ * + M GETs log (live tail for content hashes) + S DELETEs + 1 PUT
371
+ * pending = 6 + M + S.
372
+ *
373
+ * With N=20, M=20, S=10 the totals are: compact ≈ 23, gc ≈ 36 — over
374
+ * the 50 cap combined. The Cloudflare scheduled handler therefore
375
+ * alternates phases per tick (even minute → compact, odd minute →
376
+ * GC) by calling `compact()` / `runGc()` directly instead of
377
+ * `runScheduledMaintenance`; the `maintenance.budget.test.ts`
378
+ * worst-case test proves each phase in isolation sits under 50 ops
379
+ * with these bounds.
380
+ */
340
381
  declare const CLOUDFLARE_FREE_TIER: MaintenanceOptions;
341
382
  /**
342
- * Floor-based GC-cadence boundary crossing. BATCH-SAFE: a
343
- * `commitBatch` that jumps `next_seq` by its whole batch size can step
344
- * CLEAN OVER a `next_seq % interval === 0` modulo test; this floor test
345
- * trips on any interval boundary inside `(prevSeq, nextSeq]`.
383
+ * Floor-based GC-cadence boundary crossing. Every commit advances the
384
+ * writer-observed tail by one logical slot; `tail_hint` remains a
385
+ * lower bound and may be refreshed later by maintenance. The floor test
386
+ * trips on any interval boundary inside `(prevSeq, nextSeq]`, so it
387
+ * stays correct whether the observed/probed tail advances by one or
388
+ * catches up by a larger step.
346
389
  */
347
390
  declare const crossesGcBoundary: (prevSeq: number, nextSeq: number, interval: number) => boolean;
391
+ /**
392
+ * Derived live-tail byte size — the ratio TRIGGER input that replaces the
393
+ * formerly-stored exact byte count. `(observedTail − log_seq_start) ×
394
+ * mean_entry_bytes`. `observedTail` is a param so write-tick callers can
395
+ * pass the writer-observed tail and scheduled callers can pass a
396
+ * probe-discovered true tail. Cold-start (no mean yet) falls back to
397
+ * {@link MAINTENANCE_COLD_START_ENTRY_BYTES}, never 0 (see that constant).
398
+ * TRIGGER-only — structurally barred from `foldViable` (the exact-bytes CPU-kill
399
+ * ceiling).
400
+ */
401
+ declare const estimateTailBytes: (current: CurrentJson, observedTail: number) => number;
348
402
  /**
349
403
  * The cheap DISPATCH gate the writer calls after a commit — zero
350
- * storage ops; it reads the post-CAS {@link CurrentJson} already in
404
+ * storage ops; it reads the post-commit {@link CurrentJson} already in
351
405
  * scope. Ratio-OR-boundary, WITHOUT the entry floor (the floor is part
352
406
  * of the fold-trigger Gate 1 checked inside {@link runBoundedMaintenance}).
353
- * Returning `false` lets the writer skip the dispatch entirely.
407
+ * Returning `false` lets the writer skip the dispatch entirely. Ratio
408
+ * numerator is the DERIVED {@link estimateTailBytes};
409
+ * `observedTail` threads from the caller (the writer's in-memory observed
410
+ * tail `seq+1` under single-write commit). Both the boundary check and the
411
+ * ratio key off `observedTail`, since the stored `tail_hint` is now only a
412
+ * non-authoritative lower bound (compactor-advanced).
354
413
  */
355
- declare const shouldFireMaintenance: (current: CurrentJson, prevSeq: number, gcInterval: number) => boolean;
414
+ declare const shouldFireMaintenance: (current: CurrentJson, prevSeq: number, gcInterval: number, observedTail: number) => boolean;
356
415
  /** Per-tier caps for {@link runBoundedMaintenance}, threaded by the adapter. */
357
416
  interface BoundedMaintenanceOptions {
358
- /** Tail slice folded per pass. Default {@link WRITE_TICK_FOLD_ENTRIES_PER_PASS}. */
359
- readonly maxFoldEntriesPerPass?: number;
417
+ /** Host budgets, threaded by the adapter. Absent ⇒ {@link MAINTENANCE_PROFILE_CF_FREE} (CF-free-safe default; keeps a bare `Db.create()` maintaining). */
418
+ readonly profile?: MaintenanceProfile;
360
419
  /** Gate-1 minimum live-tail length. Default {@link WRITE_TICK_MIN_ENTRIES_TO_COMPACT}. */
361
420
  readonly minEntriesToCompact?: number;
362
- /** GC marks per pass. Default {@link WRITE_TICK_GC_MAX_MARKS}. */
363
- readonly gcMaxMarks?: number;
364
- /** GC sweeps per pass. Default {@link WRITE_TICK_GC_MAX_SWEEPS}. */
365
- readonly gcMaxSweeps?: number;
366
- /** GC cadence (boundary-crossing). Default {@link WRITE_TICK_GC_INTERVAL}. */
367
- readonly gcInterval?: number;
368
421
  /**
369
422
  * How many phases this tick may run. `"single"` (CF-free-safe
370
423
  * default) runs at most one of fold / GC per tick; `"both"` lets a
@@ -393,6 +446,10 @@ interface BoundedMaintenanceOptions {
393
446
  * composition of {@link compact} and {@link runGc} for one collection,
394
447
  * sized to fit a CPU-killable Cloudflare free-tier isolate by default.
395
448
  *
449
+ * INVARIANT: a {@link MaintenanceProfile} changes only maintenance rate +
450
+ * defer threshold — never data/API/query/wire/correctness; reads stay pure.
451
+ * See `maintenance-profile-equivalence.test.ts`.
452
+ *
396
453
  * Never throws — the write-tick caller must never see a maintenance
397
454
  * failure. Expected signals (CAS contention, an over-ceiling deferral)
398
455
  * are swallowed quietly; unexpected throws bump
@@ -400,7 +457,8 @@ interface BoundedMaintenanceOptions {
400
457
  * swallowed.
401
458
  *
402
459
  * Control flow (fold-priority with a stateless GC-starvation guard):
403
- * 0. `disabled` → return with zero storage ops.
460
+ * 0. `disabled` → skip fold/GC, but still allow the rate-limited
461
+ * tail_hint refresh that bounds read/write forward-probes.
404
462
  * 1. Read `current.json` once.
405
463
  * 2. Hard-GC starvation boundary (`"single"` only) → GC slice, skip fold.
406
464
  * 3. Gate 1 (ratio AND entry floor) trips → fold if viable, else
@@ -410,9 +468,16 @@ interface BoundedMaintenanceOptions {
410
468
  */
411
469
  declare const runBoundedMaintenance: (args: {
412
470
  storage: Storage;
413
- currentJsonKey: string; /** The writer's PRE-CAS `current.next_seq` — the GC cadence baseline. */
414
- prevSeq: number; /** `C` override (from `BAERLY_MAINTENANCE_MAX_FOLD_BYTES`). */
415
- maxFoldBytes?: number; /** From `BAERLY_MAINTENANCE_DISABLE`. */
471
+ currentJsonKey: string; /** The pre-commit observed tail — the GC cadence baseline. */
472
+ prevSeq: number;
473
+ /**
474
+ * Writer's in-memory observed tail (`seq + 1`). Given on the
475
+ * write-tick path so the runner's Gate-1 ratio + GC cadence key off
476
+ * the true tail without an O(gap) re-probe (the stored `tail_hint` is
477
+ * only a lower bound). Absent on a scheduled tick ⇒ the runner probes.
478
+ */
479
+ observedTail?: number; /** `C` override (from `BAERLY_MAINTENANCE_MAX_FOLD_BYTES`). */
480
+ maxFoldBytes?: number; /** From `BAERLY_MAINTENANCE_DISABLE`: disable fold/GC phases, not tail_hint refresh. */
416
481
  disabled?: boolean;
417
482
  }, options?: BoundedMaintenanceOptions) => Promise<void>;
418
483
  /**
@@ -427,7 +492,7 @@ declare const dispatchInlineAwaited: (task: () => Promise<void>) => void | Promi
427
492
  * observability context (NOT `Db.create`). It rides the per-request ALS
428
493
  * context because `dispatch = ctx.waitUntil` is inherently per-request,
429
494
  * and routing it through `Db.create` would widen that surface past its
430
- * locked four fields. The writer reads it at the post-CAS dispatch
495
+ * locked four fields. The writer reads it at the post-commit dispatch
431
496
  * point via `getCurrentContext()?.maintenance`.
432
497
  *
433
498
  * Absent ⇒ inline dispatch + CF-free-safe caps (the defaults inside
@@ -437,7 +502,7 @@ declare const dispatchInlineAwaited: (task: () => Promise<void>) => void | Promi
437
502
  interface MaintenanceDispatch {
438
503
  /** How to run the maintenance task. Default {@link dispatchInlineAwaited}. CF sets `ctx.waitUntil`. */
439
504
  readonly dispatch?: (task: () => Promise<void>) => void | Promise<void>;
440
- /** From `BAERLY_MAINTENANCE_DISABLE`. */
505
+ /** From `BAERLY_MAINTENANCE_DISABLE`: disables fold/GC phases while preserving tail_hint refresh. */
441
506
  readonly disabled?: boolean;
442
507
  /** `C` override, from `BAERLY_MAINTENANCE_MAX_FOLD_BYTES`. */
443
508
  readonly maxFoldBytes?: number;
@@ -445,5 +510,5 @@ interface MaintenanceDispatch {
445
510
  readonly options?: BoundedMaintenanceOptions;
446
511
  }
447
512
  //#endregion
448
- export { RunGcResult as _, MaintenanceDispatch as a, CompactResult as b, crossesGcBoundary as c, runScheduledMaintenance as d, shouldFireMaintenance as f, RunGcOptions as g, rebuildIndex as h, MaintenanceArgs as i, dispatchInlineAwaited as l, RebuildIndexResult as m, CLOUDFLARE_FREE_TIER as n, MaintenanceOptions as o, RebuildIndexOptions as p, InternalMaintenanceOptions as r, MaintenanceResult as s, BoundedMaintenanceOptions as t, runBoundedMaintenance as u, runGc as v, compact as x, CompactOptions as y };
449
- //# sourceMappingURL=maintenance-BRrThz8V.d.ts.map
513
+ export { compact as C, CompactResult as S, rebuildIndex as _, MaintenanceDispatch as a, runGc as b, MaintenanceResult as c, estimateTailBytes as d, runBoundedMaintenance as f, RebuildIndexResult as g, RebuildIndexOptions as h, MaintenanceArgs as i, crossesGcBoundary as l, shouldFireMaintenance as m, CLOUDFLARE_FREE_TIER as n, MaintenanceOptions as o, runScheduledMaintenance as p, InternalMaintenanceOptions as r, MaintenanceProfile as s, BoundedMaintenanceOptions as t, dispatchInlineAwaited as u, RunGcOptions as v, CompactOptions as x, RunGcResult as y };
514
+ //# sourceMappingURL=maintenance-BkhUr72A.d.ts.map