@gusto/baerly-storage 0.5.0 → 0.6.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 (102) hide show
  1. package/dist/API.md +3 -2
  2. package/dist/CHANGELOG.md +82 -0
  3. package/dist/THIRD-PARTY-LICENSES.txt +1 -1
  4. package/dist/auth.d.ts +1 -1
  5. package/dist/aws4fetch.esm-CXE5ZbAa.js +460 -0
  6. package/dist/aws4fetch.esm-CXE5ZbAa.js.map +1 -0
  7. package/dist/baerly.js +10 -10
  8. package/dist/baerly.spec.json +1 -1
  9. package/dist/client-react.d.ts +2 -2
  10. package/dist/{client-Fe8CwB73.d.ts → client-ypCm3zjt.d.ts} +2 -2
  11. package/dist/client.d.ts +2 -2
  12. package/dist/{cloudflare-DzKBrUlg.js → cloudflare-wrVYf4bb.js} +457 -56
  13. package/dist/cloudflare-wrVYf4bb.js.map +1 -0
  14. package/dist/cloudflare.d.ts +3 -3
  15. package/dist/cloudflare.js +5 -5
  16. package/dist/{config-1tv0-Yzm.js → config-B6nTy8e2.js} +435 -33
  17. package/dist/config-B6nTy8e2.js.map +1 -0
  18. package/dist/constants-CfeMWQWk.js.map +1 -1
  19. package/dist/{cost-DSMIVqzL.js → cost-_SE_SVgZ.js} +4 -4
  20. package/dist/{cost-DSMIVqzL.js.map → cost-_SE_SVgZ.js.map} +1 -1
  21. package/dist/{db-DsPkOVEH.d.ts → db-DjjthkTi.d.ts} +2 -2
  22. package/dist/{deploy-DonTr-CV.js → deploy-Di_Q01qx.js} +5 -5
  23. package/dist/deploy-Di_Q01qx.js.map +1 -0
  24. package/dist/dev-vite.d.ts +31 -27
  25. package/dist/dev-vite.js +60 -30
  26. package/dist/dev-vite.js.map +1 -1
  27. package/dist/dev.d.ts +1 -1
  28. package/dist/doctor-RWVRpvat.js +102 -0
  29. package/dist/doctor-RWVRpvat.js.map +1 -0
  30. package/dist/{dump-Bh5k26VQ.js → dump-m2vEYDNY.js} +4 -4
  31. package/dist/{dump-Bh5k26VQ.js.map → dump-m2vEYDNY.js.map} +1 -1
  32. package/dist/{export-DtF5tDIM.js → export-DenKwEQu.js} +4 -4
  33. package/dist/{export-DtF5tDIM.js.map → export-DenKwEQu.js.map} +1 -1
  34. package/dist/{fsck-D_djMO5D.js → fsck-2Vq-7-e2.js} +5 -5
  35. package/dist/{fsck-D_djMO5D.js.map → fsck-2Vq-7-e2.js.map} +1 -1
  36. package/dist/gcs-admin-Bx6xSNJj.d.ts +123 -0
  37. package/dist/gcs.d.ts +18 -0
  38. package/dist/gcs.js +2 -0
  39. package/dist/goog4-signer-Z7KnJ1su.js +321 -0
  40. package/dist/goog4-signer-Z7KnJ1su.js.map +1 -0
  41. package/dist/{http-DGd5tbNs.js → http-7zT29K3P.js} +4 -4
  42. package/dist/{http-DGd5tbNs.js.map → http-7zT29K3P.js.map} +1 -1
  43. package/dist/{aws4fetch.esm-p7eEzLCs.js → http-transport-BTgVCY5r.js} +24 -476
  44. package/dist/http-transport-BTgVCY5r.js.map +1 -0
  45. package/dist/http.d.ts +2 -2
  46. package/dist/http.js +2 -2
  47. package/dist/{index-BNRh23K9.d.ts → index-BHz92Acj.d.ts} +2 -2
  48. package/dist/{index-BYk9oCNf.d.ts → index-CEZKQsKt.d.ts} +3 -2
  49. package/dist/{index-CuA9Mi3K.d.ts → index-DP3ClvcA.d.ts} +7 -7
  50. package/dist/{index-0rZcMBwy.d.ts → index-uE-w2dgj.d.ts} +2 -2
  51. package/dist/index.d.ts +3 -3
  52. package/dist/index.js +3 -3
  53. package/dist/{inspect-6WZ-pC7-.js → inspect-BpYbH1DM.js} +5 -5
  54. package/dist/{inspect-6WZ-pC7-.js.map → inspect-BpYbH1DM.js.map} +1 -1
  55. package/dist/{log-tail-D98U1JBo.js → log-tail-QWU4wlu-.js} +3 -11
  56. package/dist/log-tail-QWU4wlu-.js.map +1 -0
  57. package/dist/{maintenance-B_e0T99L.d.ts → maintenance-BGHGt2Yg.d.ts} +2 -2
  58. package/dist/{maintenance-B4Dki6Ig.js → maintenance-DULFcpd1.js} +4 -17
  59. package/dist/maintenance-DULFcpd1.js.map +1 -0
  60. package/dist/{maintenance-C7coQp4c.js → maintenance-fEi-UZ2o.js} +5 -11
  61. package/dist/maintenance-fEi-UZ2o.js.map +1 -0
  62. package/dist/maintenance.d.ts +1 -1
  63. package/dist/maintenance.js +1 -1
  64. package/dist/node.d.ts +21 -60
  65. package/dist/node.js +4 -3
  66. package/dist/{observability-BmflLCdF.js → observability-Ch-VQJyE.js} +38 -16
  67. package/dist/{observability-BmflLCdF.js.map → observability-Ch-VQJyE.js.map} +1 -1
  68. package/dist/observability.d.ts +2 -2
  69. package/dist/observability.js +1 -1
  70. package/dist/{plan-a7PJHBCy.js → plan-C4qgiXSg.js} +2 -2
  71. package/dist/{plan-a7PJHBCy.js.map → plan-C4qgiXSg.js.map} +1 -1
  72. package/dist/{query-rAtXNQQB.js → query-C43r-6ib.js} +2 -2
  73. package/dist/{query-rAtXNQQB.js.map → query-C43r-6ib.js.map} +1 -1
  74. package/dist/{rebuild-index-BVzQSZlm.js → rebuild-index-BH1dc1p6.js} +4 -4
  75. package/dist/{rebuild-index-BVzQSZlm.js.map → rebuild-index-BH1dc1p6.js.map} +1 -1
  76. package/dist/{restore-R-4rbciV.js → restore-D0VYWzfP.js} +5 -5
  77. package/dist/{restore-R-4rbciV.js.map → restore-D0VYWzfP.js.map} +1 -1
  78. package/dist/{runtime-spec-Dsw2-n8S.js → runtime-spec--LykAdl1.js} +2 -2
  79. package/dist/{runtime-spec-Dsw2-n8S.js.map → runtime-spec--LykAdl1.js.map} +1 -1
  80. package/dist/{s3-http-B-z8th6O.d.ts → s3-http-DD5gDc7t.d.ts} +6 -4
  81. package/dist/s3.d.ts +1 -1
  82. package/dist/s3.js +1 -1
  83. package/dist/sha256-CqcKTjw9.js +22 -0
  84. package/dist/sha256-CqcKTjw9.js.map +1 -0
  85. package/dist/{src-BL_JoPTn.js → src-BMFfDUI2.js} +68 -28
  86. package/dist/{src-BL_JoPTn.js.map → src-BMFfDUI2.js.map} +1 -1
  87. package/dist/{src-CYHFDrKz.js → src-DvbTEya2.js} +3 -3
  88. package/dist/{src-CYHFDrKz.js.map → src-DvbTEya2.js.map} +1 -1
  89. package/dist/{subcommand-DoDA-K7d.js → subcommand-BV68pqwJ.js} +2 -2
  90. package/dist/{subcommand-DoDA-K7d.js.map → subcommand-BV68pqwJ.js.map} +1 -1
  91. package/dist/{usage-DBV1eQHC.js → usage-BMZR8o6U.js} +3 -3
  92. package/dist/{usage-DBV1eQHC.js.map → usage-BMZR8o6U.js.map} +1 -1
  93. package/package.json +10 -4
  94. package/dist/aws4fetch.esm-p7eEzLCs.js.map +0 -1
  95. package/dist/cloudflare-DzKBrUlg.js.map +0 -1
  96. package/dist/config-1tv0-Yzm.js.map +0 -1
  97. package/dist/deploy-DonTr-CV.js.map +0 -1
  98. package/dist/doctor-DSIyCDg_.js +0 -346
  99. package/dist/doctor-DSIyCDg_.js.map +0 -1
  100. package/dist/log-tail-D98U1JBo.js.map +0 -1
  101. package/dist/maintenance-B4Dki6Ig.js.map +0 -1
  102. package/dist/maintenance-C7coQp4c.js.map +0 -1
@@ -1 +1 @@
1
- {"version":3,"file":"constants-CfeMWQWk.js","names":[],"sources":["../packages/protocol/src/constants.ts"],"sourcesContent":["/**\n * Max total object-key length S3 and R2 accept (UTF-8 bytes). A key\n * over this fails the PUT with an opaque provider 400; baerly surfaces\n * it early as InvalidConfig. See docs/spec/storage-compatibility.md.\n */\nexport const MAX_KEY_BYTES = 1024;\n\n/**\n * Half-window (in milliseconds) within which a `LogEntry`'s embedded\n * `commit_ts` must agree with wall-clock time for downstream consumers\n * to accept the entry as causally ordered. Bound on tolerated\n * client/server clock skew across the protocol.\n *\n * 5 s is the protocol's tolerance for client/server clock skew.\n * Tightening this can cause spurious rejections on machines that\n * haven't synced NTP; loosening it widens the window during which\n * causal ordering can be disturbed by skew.\n *\n * @see docs/spec/sync-protocol.md\n * @see packages/protocol/src/storage/types.ts (`Storage` JSDoc)\n */\nexport const LAG_WINDOW_MILLIS: number = 5000;\n\n/**\n * Bit width of the descending base-32 seq segment in every LSN\n * (`<base32-time>_<session>_<seq>`, minted in `Writer.commit`).\n * The output character width is `Math.ceil(COUNT_BIT_WIDTH / 5) = 11`.\n *\n * **Domain:** 0 .. `Number.MAX_SAFE_INTEGER` (2^53 − 1). A collection\n * would need 2^53 writes before the seq counter could overflow — an\n * unreachable ceiling in practice.\n *\n * **Why 53 bits:** JavaScript numbers are IEEE-754 doubles; the safe\n * integer range is exactly [0, 2^53 − 1]. Encoding at this width keeps\n * the arithmetic in the encoder and decoder (`uint2strDesc` /\n * `str2uintDesc` in `packages/protocol/src/types.ts`) exact and\n * leaves no headroom for the negative-overflow path that manifested\n * at the old 10-bit width (domain 0..1023).\n *\n * **Ordering property:** fixed-width base-32 encoding preserves\n * descending lex order across the entire domain\n * (`countKey(a) > countKey(b)` iff `a < b`), which the reverse-walk\n * on `Storage.list` relies on.\n *\n * **Three production consumers** must all agree on this value:\n * 1. Encoder — `countKey` in `packages/protocol/src/types.ts`\n * 2. Decoder — `lsnParts` in `packages/protocol/src/log.ts`\n * 3. Validator regex — `LSN_RE` in `packages/server/src/http/since.ts`\n * (derives its `{N}` from `Math.ceil(COUNT_BIT_WIDTH / 5)`)\n *\n * The independent shape-assertion literal in\n * `tests/fixtures/collection-api-cascade.ts` is kept hand-written and\n * is NOT a consumer of this constant (importing the production\n * validator into the test that checks it would make the assertion\n * a tautology).\n *\n * Changing this constant is a protocol-breaking change — it reshapes\n * every emitted LSN cursor.\n *\n * @see packages/protocol/src/types.ts (`countKey`, `uint2strDesc`)\n * @see packages/protocol/src/log.ts (`lsnParts`, `str2uintDesc` call)\n * @see packages/server/src/http/since.ts (`LSN_RE`)\n * @see docs/spec/log-entry-shape.md\n */\nexport const COUNT_BIT_WIDTH: number = 53;\n\n/**\n * Bit width of the base-32 timestamp prefix encoded into every\n * {@link LogEntry.lsn} (`<base32-time>_<session>_<seq>`, minted in\n * `Writer.commit`). 42 bits gives ~139 years of millisecond\n * precision, which is enough for the protocol's lifetime.\n *\n * Changing this is a protocol-breaking change — it would re-shape\n * every emitted LSN.\n *\n * @see packages/protocol/src/time.ts (`timestamp`)\n * @see packages/server/src/writer.ts (`Writer.commit`)\n * @see docs/spec/sync-protocol.md\n */\nexport const TIMESTAMP_BIT_WIDTH: number = 42;\n\n/**\n * Length of the random-prefix `session` segment embedded in every\n * {@link LogEntry.lsn} (`<base32-time>_<session>_<seq>`). 6 hex chars\n * from `crypto.randomUUID()` give 16⁶ ≈ 1.7 × 10⁷ distinct sessions;\n * birthday-collision rate at N=100 is ~3 × 10⁻⁴, comfortably below\n * the 1 % bound asserted in `tests/regressions.test.ts`. Collisions\n * within a single commit's writer set are also disambiguated by the\n * trailing `<seq>` counter.\n *\n * @see packages/server/src/writer.ts (`Writer.commit` —\n * `session = uuid().slice(0, SESSION_ID_LENGTH)`)\n */\nexport const SESSION_ID_LENGTH: number = 6;\n\n/**\n * Maximum attempts `S3HttpStorage.list` will make per page when the\n * server replies 429 (rate-limited). After this many in a row, it\n * gives up with `NetworkError`. Separate from the inner transient-\n * failure budget so a single hot page can't burn the whole retry\n * allowance.\n */\nexport const LIST_OBJECT_MAX_RETRIES: number = 10;\n\n/**\n * Backoff (in milliseconds) inserted between LIST attempts when S3\n * returns 429 (rate-limited).\n */\nexport const RATE_LIMIT_BACKOFF_MILLIS: number = 1000;\n\n/**\n * Upper clamp on a server-provided `Retry-After` hint, in seconds.\n * RFC 7231 §7.1.3 allows arbitrary delta-seconds or HTTP-dates, but a\n * client that blindly honours a multi-hour hint hands a misbehaving\n * proxy a denial-of-service primitive. 60s covers any plausible S3-\n * compatible throttle while keeping the worst-case bounded.\n *\n * @see packages/protocol/src/storage/s3-http.ts (`parseRetryAfter`)\n */\nexport const RETRY_AFTER_MAX_SECONDS: number = 60;\n\n/**\n * Default retry budget for `S3HttpStorage.retry` (the wrapper around\n * each of the four `Storage` methods). Bounded so that permanent\n * failures (CORS misconfig, NXDOMAIN, persistent 5xx) surface to\n * callers as rejected promises instead of retrying forever and\n * leaving `Writer.commit()` permanently pending.\n *\n * 8 attempts at the existing 100ms→×1.5→10s schedule covers ~30s of\n * transient turbulence, which is enough to ride out a leader election\n * or a brief network blip without papering over a real outage.\n */\nexport const S3_REQUEST_MAX_RETRIES: number = 8;\n\n/**\n * Maximum concurrent log-entry GETs issued by a single `walkLogRange`\n * call. Bounds Class-B fan-out per read and per CAS attempt — without\n * a bound, a reader on a collection whose compactor has fallen behind\n * fans out one GET per live-tail entry (typically 50-100 on the free-\n * tier profile), and a contended writer multiplies that by the CAS\n * retry budget ({@link S3_REQUEST_MAX_RETRIES}).\n *\n * 16 keeps the worst-case under retry to `16 * 8 = 128` concurrent\n * GETs — comfortably under the Workers subrequest cap (50 concurrent\n * / 1000 total) and leaving headroom for the writer's content / index\n * / log / CAS PUTs sharing the same isolate.\n *\n * @see packages/server/src/log-walk.ts (`walkLogRange`)\n */\nexport const MAX_PARALLEL_LOG_READS: number = 16;\n\n/**\n * Runaway guard on the tolerant forward-probe walk (`probeTailFrom`):\n * max `log/<seq>` GETs past `tail_hint` before it THROWS `Internal`\n * (rather than silently truncating reads). A runaway alarm only — the\n * maintenance tick keeps `tail_hint` near the tail, so a >cap gap means\n * maintenance is off or the collection is far past graduation.\n *\n * @see packages/server/src/log-tail.ts (`probeTailFrom`)\n */\nexport const LOG_FORWARD_PROBE_CAP: number = 100_000;\n\n/**\n * Current major version of the `current.json` control-object schema.\n * Readers MUST reject unknown versions with\n * `BaerlyError{code:\"InvalidResponse\"}` rather than try to coerce.\n *\n * Bump only on a breaking change to `CurrentJson` field semantics.\n * Adding a new optional field is NOT breaking; renaming or removing\n * a field IS breaking.\n *\n * @see packages/protocol/src/coordination/current-json.ts\n */\nexport const CURRENT_JSON_SCHEMA_VERSION = 3 as const;\n\n/**\n * MIME type written for `current.json` PUTs. S3 round-trips this on\n * subsequent GETs; useful for diagnostics when staring at a bucket\n * via the AWS console.\n *\n * @see packages/protocol/src/coordination/current-json.ts\n */\nexport const CURRENT_JSON_CONTENT_TYPE: string = \"application/json\";\n\n/**\n * Current major version of the `gc/pending.json` control-object\n * schema. Readers MUST reject unknown versions with\n * `BaerlyError{code:\"InvalidResponse\"}` rather than try to coerce.\n *\n * Bump only on a breaking change to `GcPending` field semantics.\n * Adding a new optional field is NOT breaking; renaming or removing\n * a field IS breaking.\n *\n * @see packages/protocol/src/coordination/gc-pending.ts\n */\nexport const GC_PENDING_SCHEMA_VERSION = 1 as const;\n\n/**\n * Current major version of the snapshot control-object schema\n * ({@link SnapshotBody}). Readers MUST reject unknown versions with\n * `BaerlyError{code:\"InvalidResponse\"}` rather than try to coerce.\n *\n * Bump only on a breaking change to `SnapshotBody` field semantics.\n * Adding a new optional field is NOT breaking; renaming or removing\n * a field IS breaking.\n *\n * @see packages/server/src/snapshot.ts\n */\nexport const SNAPSHOT_SCHEMA_VERSION = 1 as const;\n\n/**\n * MIME type written for `gc/pending.json` PUTs.\n *\n * @see packages/protocol/src/coordination/gc-pending.ts\n */\nexport const GC_PENDING_CONTENT_TYPE: string = \"application/json\";\n\n/**\n * Default grace period between \"marking\" a key for GC and \"sweeping\"\n * (deleting) it. 7 days, chosen to span the worst plausible writer-\n * retry window (a paused-process writer that resumes hours later\n * should still find its idempotency anchor on the bucket). The\n * `runGc()` function accepts an override for tests.\n *\n * Why 7 days specifically:\n * - **1 day is too aggressive for batch workloads.** Worker isolate\n * scheduling pauses, cross-region replication lag, and\n * {@link RATE_LIMIT_BACKOFF_MILLIS} retry cascades can plausibly\n * exceed an hour under pathological conditions.\n * - **30 days is conservative beyond the worst plausible pause.**\n * Doubles `gc/pending.json` size at steady state and slows\n * visibility into \"did GC actually run?\" by 4×.\n * - **7 days spans the realistic upper bound** — long-running batch\n * jobs, multi-region propagation delays, queue backlogs, and\n * downstream outages the writer is retrying through. The protocol\n * is unaffected by the choice of value within the [hours, weeks]\n * range; this constant is the operator-tunable knob.\n *\n * Production code MUST NOT call `runGc` with `graceMillis` below the\n * default outside maintenance windows — going below the longest\n * plausible writer-retry latency risks deleting an anchor a writer\n * is about to find on retry. Test code that sets `graceMillis: 0` is\n * exercising the sweep path deliberately, not modelling production.\n *\n * @see packages/server/src/gc.ts\n */\n// Stryker disable next-line ArithmeticOperator: internal tuning value, not an off-process contract — asserting the literal would be a tautological change-detector. See docs/contributing/mutation-testing.md constants policy.\nexport const GC_GRACE_PERIOD_MILLIS: number = 7 * 24 * 60 * 60 * 1000;\n\n/**\n * Cap on candidates kept in `gc/pending.json` to bound the size of\n * the file. The compactor marks at most this many candidates per\n * pass; subsequent passes pick up the rest. Larger collections will\n * lag GC by one pass per `GC_MAX_PENDING_CANDIDATES` orphans, which\n * is acceptable.\n *\n * @see packages/server/src/gc.ts\n */\nexport const GC_MAX_PENDING_CANDIDATES: number = 1000;\n\n/**\n * Bounded retry cap for the `gc/pending.json` CAS read-modify-write\n * loop in {@link casUpdateGcPending}. On `Conflict` (a concurrent GC\n * pass landed between this pass's read and its write) the loop\n * re-reads `latest` and re-applies the pure merge mutator, retrying up\n * to this many total attempts before surfacing `Conflict`. Safe to\n * retry because the mutator is pure and the sweep DELETEs are\n * idempotent and already performed; a re-merge against fresh state\n * never loses a concurrently-marked candidate. Small fixed cap — under\n * one writer per collection at steady state, contention is rare; this\n * just bounds the worst case so a pathological storm can't spin.\n *\n * @see packages/protocol/src/coordination/gc-pending.ts\n */\nexport const GC_PENDING_CAS_MAX_ATTEMPTS: number = 3;\n\n/**\n * Fold-trigger ratio: fold fires at tail ≥ R×snapshot. Pure READ-AMP / fold-frequency\n * knob — with the ceiling on the snapshot axis (Decision 3a, tail sliced) the\n * auto-maintained snapshot ceiling is S_max = C, NOT C/(1+R). R=1.0 caps steady-state\n * read-amp at ~2× and keeps compaction write-amp (≈1+1/R) moderate. See\n * docs/about/graduation.md for the derivation.\n *\n * @see docs/about/graduation.md\n * @see packages/server/src/maintenance.ts\n */\nexport const MAINTENANCE_TARGET_RATIO: number = 1;\n\n/**\n * Floor for the ratio denominator — avoid div-by-tiny on a fresh collection. Also\n * sets the first-fold threshold: until a snapshot exists, fold fires at tail ≈ this.\n *\n * @see packages/server/src/maintenance.ts\n */\n// Stryker disable next-line ArithmeticOperator: internal tuning value, not an off-process contract — asserting the literal would be a tautological change-detector. See docs/contributing/mutation-testing.md constants policy.\nexport const MAINTENANCE_MIN_LIVE_BYTES: number = 64 * 1024;\n\n/**\n * Cold-start per-entry byte estimate for the ratio TRIGGER's derived live-tail\n * size (`estimateTailBytes`), used until the compactor stamps a real\n * `current.json.mean_entry_bytes` on the first fold. Folding too-few entries is\n * barred by Gate-1's entry-count floor (`minEntriesToCompact`), NOT by this\n * value — so over-estimating is equally safe; this is a first-fold-TIMING\n * choice. A small typical log-entry size keeps the first fold's cadence close\n * to a precisely measured path for typical entries; must be non-zero so a\n * bare `Db.create()` still bootstraps its first auto-fold (a 0 fallback leaves\n * the ratio dead pre-stamp). Large-body collections see a bounded first-fold\n * delay; after it stamps a real mean the estimate tracks the exact tail.\n *\n * @see packages/server/src/maintenance.ts (`estimateTailBytes`)\n */\n// Stryker disable next-line ArithmeticOperator: internal cold-start tuning value, not an off-process contract — asserting the literal would be a tautological change-detector. See docs/contributing/mutation-testing.md constants policy.\nexport const MAINTENANCE_COLD_START_ENTRY_BYTES: number = 128;\n\n/**\n * Per-tick GC budget — these are DEFAULTS (= the most-constrained tier, CF free, reusing\n * the TESTED `CLOUDFLARE_FREE_TIER` values in maintenance.ts / maintenance-budget.test.ts).\n * The adapter THREADS per-tier overrides into the context (§8.4); Node/CF-paid raise them.\n * NOT universal constants — a Node-sized value here would silently kill every CF-free fold\n * (round-4 Tier-1). gc pass ≈ 6 + maxMarks + maxSweeps subrequests (both GET/DELETE the\n * bucket — §3.1). Cadence is BOUNDARY-CROSSING (§3.1), not modulo.\n *\n * @see packages/server/src/maintenance.ts\n * @see packages/server/src/maintenance-budget.test.ts\n */\nexport const WRITE_TICK_GC_INTERVAL: number = 4; // tuned so maxSweeps/interval ≥ p (§7.1)\n\n/**\n * Fold-starvation guard (critique A): on `phasesPerTick:\"single\"`, every Nth GC-interval is a\n * HARD GC boundary the fold may NOT preempt, so a long fold-heavy drain can't starve GC to zero.\n * Stateless (seq-derived) — no per-isolate preemption counter (CF recycles isolates). At 4 a\n * sustained drain still yields ~1 GC tick per 4 GC-intervals.\n *\n * @see packages/server/src/maintenance.ts\n */\nexport const GC_STARVATION_GUARD: number = 4;\n\n/**\n * Maximum GC marks per write-tick pass (M in 6+M+S; GETs the live tail to hash).\n *\n * @see packages/server/src/maintenance.ts\n */\nexport const WRITE_TICK_GC_MAX_MARKS: number = 20;\n\n/**\n * Maximum GC sweeps per write-tick pass (S in 6+M+S; DELETE subrequests).\n *\n * @see packages/server/src/maintenance.ts\n */\nexport const WRITE_TICK_GC_MAX_SWEEPS: number = 10;\n\n/**\n * Per-pass tail SLICE default — compact()'s maxEntriesPerRun. Fold ≤ this+3 subrequests, so\n * a large tail drains incrementally over write-ticks (Decision 3). Adapter-overridable.\n *\n * @see packages/server/src/maintenance.ts\n */\nexport const WRITE_TICK_FOLD_ENTRIES_PER_PASS: number = 20;\n\n/**\n * compact()'s minEntriesToCompact, set EXPLICITLY by the runner so it agrees with Gate 1\n * rather than inheriting compact()'s silent default 100 (which would contradict the 64 KB\n * first-fold story — round-4 Tier-3). Adapter-overridable; CF-free value.\n *\n * @see packages/server/src/maintenance.ts\n */\nexport const WRITE_TICK_MIN_ENTRIES_TO_COMPACT: number = 50;\n\n/**\n * Node-tier write-tick maintenance caps — a MODERATE multiple of the CF-free `WRITE_TICK_*`\n * defaults, threaded into the per-request observability context by `baerlyNode` /\n * `createFetchHandler` (§8.4). Node v1 runs maintenance INLINE on the commit path (no\n * `waitUntil`), so the cap is NOT the CF subrequest wall — it's the worst-case single-write\n * added latency. A maintenance tick only fires on a ratio/boundary trip (rare), and when it\n * does it costs ~`maxFoldEntriesPerPass` + (6 + `gcMaxMarks` + `gcMaxSweeps`) storage\n * round-trips against a co-located S3/R2 — sub-second on the occasional boundary write at a\n * 10× multiple. These are deliberately BOUNDED (10× CF-free), NOT unbounded: the deleted\n * scheduled full-tail sweep folded the entire live tail in one shot, which a 100× multiple here\n * would reintroduce as multi-second commit stalls. Raise the snapshot ceiling separately via\n * `BAERLY_MAINTENANCE_MAX_FOLD_BYTES`; these caps slice the per-pass work, not the ceiling.\n *\n * @see packages/adapter-node/src/server.ts\n * @see packages/server/src/maintenance.ts\n * @see docs/about/graduation.md\n */\nexport const NODE_MAINTENANCE_FOLD_ENTRIES_PER_PASS: number = 200;\n\n/** Node-tier GC marks per pass (M in 6+M+S). 10× CF-free. @see {@link NODE_MAINTENANCE_FOLD_ENTRIES_PER_PASS} */\nexport const NODE_MAINTENANCE_GC_MAX_MARKS: number = 200;\n\n/** Node-tier GC sweeps per pass (S in 6+M+S). 10× CF-free. @see {@link NODE_MAINTENANCE_FOLD_ENTRIES_PER_PASS} */\nexport const NODE_MAINTENANCE_GC_MAX_SWEEPS: number = 100;\n\n/**\n * Node-tier GC cadence (boundary-crossing). Shorter than the CF-free `WRITE_TICK_GC_INTERVAL`\n * (4) so the per-write sweep budget keeps up: `gcMaxSweeps / gcInterval = 100 / 2 = 50`\n * comfortably clears the garbage-per-write rate `p` (the `maxSweeps/interval ≥ p` invariant,\n * §7.1) with a wide margin.\n *\n * @see {@link NODE_MAINTENANCE_FOLD_ENTRIES_PER_PASS}\n */\nexport const NODE_MAINTENANCE_GC_INTERVAL: number = 2;\n\n/**\n * SNAPSHOT-rebuild ceiling `C` (the unsliceable axis — Decision 3a), memory. Default sized\n * ~5.5 ms under CF-free ~10 ms. Raise via BAERLY_MAINTENANCE_MAX_FOLD_BYTES on capable\n * hosts. Auto-maintained snapshot ceiling S_max = C. NOT snapshot+tail (tail is sliced).\n *\n * @see docs/about/graduation.md\n * @see packages/server/src/maintenance.ts\n */\n// Stryker disable next-line ArithmeticOperator: internal tuning value, not an off-process contract — asserting the literal would be a tautological change-detector. See docs/contributing/mutation-testing.md constants policy.\nexport const MAINTENANCE_MAX_FOLD_BYTES_DEFAULT: number = 512 * 1024;\n\n/**\n * The largest snapshot a Cloudflare **free-tier** isolate can safely\n * rebuild in ONE fold under the ~10 ms CPU budget. This is the WARN\n * THRESHOLD, not a runtime cap: an operator who raises\n * `BAERLY_MAINTENANCE_MAX_FOLD_BYTES` ABOVE this value on a free Worker\n * risks a snapshot rebuild that exceeds the ~10 ms CPU limit and gets\n * CPU-killed MID-REBUILD — the CAS never lands, so the fold silently\n * never advances `log_seq_start` and the tail grows unbounded.\n *\n * Sized at 2× {@link MAINTENANCE_MAX_FOLD_BYTES_DEFAULT}. The default\n * (512 KiB) rebuilds in ~5.5 ms under the CF-free ~10 ms budget\n * (constants.ts default JSDoc); linear-extrapolating, ~1 MiB is the\n * point where one-shot rebuild fills the budget with little margin, so\n * anything strictly larger is no longer free-tier-safe. On CF **paid**\n * (raised CPU limits), Node, or once §11 chunked snapshots land, a\n * larger ceiling is fine — hence this is a one-time `console.warn` at\n * handler init, NOT a hard rejection.\n *\n * @see packages/adapter-cloudflare/src/worker.ts\n * @see packages/server/src/maintenance.ts\n * @see docs/about/graduation.md\n */\n// Stryker disable next-line ArithmeticOperator: internal tuning value, not an off-process contract — asserting the literal would be a tautological change-detector. See docs/contributing/mutation-testing.md constants policy.\nexport const CF_FREE_MAX_SAFE_FOLD_BYTES: number = 1024 * 1024;\n\n/**\n * SNAPSHOT-rebuild ceiling `E`, per-entry CPU axis: gates `snapshot_rows` (per-entry\n * parse/merge/serialize is ~half of fold CPU and scales with ROW COUNT not bytes, VLDB 2021\n * Sarkar — a tiny-doc snapshot can blow CPU under C). PROVISIONAL — bench\n * landed; paid recalibration deferred.\n *\n * @see docs/about/graduation.md\n * @see packages/server/src/maintenance.ts\n */\nexport const MAINTENANCE_MAX_FOLD_ROWS: number = 2048;\n\n// Declared here (not the nominal server `MaintenanceProfile`) to avoid a server→protocol cycle; keep field-identical to it.\ntype MaintenanceProfileShape = Readonly<{\n gcInterval: number;\n gcMaxMarks: number;\n gcMaxSweeps: number;\n maxFoldEntriesPerPass: number;\n maxFoldBytes: number;\n maxFoldRows: number;\n}>;\n\n/** CF-free profile; the absent-context default. */\nexport const MAINTENANCE_PROFILE_CF_FREE: MaintenanceProfileShape = {\n gcInterval: WRITE_TICK_GC_INTERVAL,\n gcMaxMarks: WRITE_TICK_GC_MAX_MARKS,\n gcMaxSweeps: WRITE_TICK_GC_MAX_SWEEPS,\n maxFoldEntriesPerPass: WRITE_TICK_FOLD_ENTRIES_PER_PASS,\n maxFoldBytes: MAINTENANCE_MAX_FOLD_BYTES_DEFAULT,\n maxFoldRows: MAINTENANCE_MAX_FOLD_ROWS,\n};\n\n/** Node profile; 10× CF-free caps. */\nexport const MAINTENANCE_PROFILE_NODE: MaintenanceProfileShape = {\n gcInterval: NODE_MAINTENANCE_GC_INTERVAL,\n gcMaxMarks: NODE_MAINTENANCE_GC_MAX_MARKS,\n gcMaxSweeps: NODE_MAINTENANCE_GC_MAX_SWEEPS,\n maxFoldEntriesPerPass: NODE_MAINTENANCE_FOLD_ENTRIES_PER_PASS,\n maxFoldBytes: MAINTENANCE_MAX_FOLD_BYTES_DEFAULT,\n maxFoldRows: MAINTENANCE_MAX_FOLD_ROWS,\n};\n\n/**\n * CF-paid profile — opt-in via `BAERLY_MAINTENANCE_PROFILE=cf-paid`. A paid\n * isolate keeps the CPU-killable single-phase shape but has the 10,000-\n * subrequest budget (vs free's 50), so it reuses the `NODE_MAINTENANCE_*`\n * per-pass caps. CRITICAL: snapshot ceilings `maxFoldBytes` (`C`) /\n * `maxFoldRows` (`E`) are UNCHANGED — a profile moves rate, never correctness\n * (the equivalence invariant); the memory wall is raised via\n * `BAERLY_MAINTENANCE_MAX_FOLD_BYTES`.\n *\n * @see packages/adapter-cloudflare/src/worker.ts\n * @see docs/about/graduation.md\n */\nexport const MAINTENANCE_PROFILE_CF_PAID: MaintenanceProfileShape = {\n gcInterval: NODE_MAINTENANCE_GC_INTERVAL,\n gcMaxMarks: NODE_MAINTENANCE_GC_MAX_MARKS,\n gcMaxSweeps: NODE_MAINTENANCE_GC_MAX_SWEEPS,\n maxFoldEntriesPerPass: NODE_MAINTENANCE_FOLD_ENTRIES_PER_PASS,\n maxFoldBytes: MAINTENANCE_MAX_FOLD_BYTES_DEFAULT,\n maxFoldRows: MAINTENANCE_MAX_FOLD_ROWS,\n};\n\n/**\n * Rate-limit the defer-warn off SHARED current.json.last_warned_seq (not per-isolate\n * memory — CF recycles isolates). ~once per this many writes.\n *\n * @see packages/protocol/src/coordination/current-json.ts\n * @see packages/server/src/maintenance.ts\n */\nexport const MAINTENANCE_WARN_INTERVAL_WRITES: number = 1000;\n\n/**\n * Rate-limit for the maintenance tick's `tail_hint` advance on the\n * DEFER path (HR-2). When the fold defers (snapshot over the CF-CPU-kill\n * ceiling) the compactor never stamps `tail_hint` via its Step-7 fold\n * CAS, so the gap `(true_tail − tail_hint)` would grow without bound and\n * every read would re-walk the whole live tail via `probeTailFrom`. The\n * runner therefore advances `tail_hint` toward the observed tail with a\n * best-effort `current.json` CAS — but only once per this many writes,\n * so it is NOT a per-commit `current.json` write (which is exactly what\n * single-write commit removed).\n *\n * Sized at 128: it bounds a deferring collection's worst-case\n * read-walk to ≤128 forward GETs (≈one extra read-page sweep — a\n * negligible per-read latency cost), keeps the gap two-to-three orders\n * of magnitude below {@link LOG_FORWARD_PROBE_CAP} (so the cap-throw is a\n * pure runaway guard, never reached in normal operation), and holds the\n * hint-advance CAS rate under ~1% of the commit rate (negligible\n * Class-A cost, amortized). Smaller would tighten the read-walk at a\n * higher CAS rate; larger would loosen it — 128 is the modest middle.\n *\n * @see packages/server/src/maintenance.ts\n */\nexport const MAINTENANCE_TAIL_HINT_REFRESH_WRITES: number = 128;\n\n/**\n * Stable seed for `CurrentJson.snapshot === null` when building the\n * opaque `_meta.manifest_pointer` cursor emitted on read responses.\n * The literal no longer appears by itself on the wire; it is folded\n * into the server-side digest so the cursor never exposes physical\n * snapshot keys.\n *\n * @see packages/server/src/contract.ts (HttpOkMeta)\n */\nexport const MANIFEST_POINTER_EMPTY_SNAPSHOT: string = \"none\";\n\n/**\n * Keys that must never propagate through {@link merge}: assigning to\n * them on a plain object pollutes the prototype chain. The literal\n * `{ __proto__: ... }` syntax is a prototype-setter (not an own key)\n * and bypasses `Object.keys`, but `JSON.parse('{\"__proto__\":...}')`\n * produces a real own property — which is exactly how a malicious\n * HTTP PATCH body would arrive on the wire.\n *\n * Lifted to a constant so every iteration path that touches a\n * caller-supplied object can re-use the same defence without\n * duplicating the keyword list.\n *\n * @see packages/protocol/src/json.ts (merge)\n * @see docs/spec/json-merge-patch.md\n */\nexport const FORBIDDEN_MERGE_KEYS: ReadonlySet<string> = new Set([\n \"__proto__\",\n \"constructor\",\n \"prototype\",\n]);\n\n/**\n * Architecturally-enforced ceiling: storage ops per logical write.\n *\n * Two Class A ops: PUT content + the committing `log/<seq>` create\n * (`If-None-Match: \"*\"`). There is no `current.json` CAS on the commit\n * path — the winning log create IS the commit. The cost-model page\n * derives the free-tier write budget from this multiplier; the\n * maintenance end-to-end test asserts it at CI time. Changing this constant is a\n * cost-model-breaking change.\n *\n * @see docs/about/cost-model.md §\"Cost ceiling\"\n * @see tests/integration/maintenance-e2e.test.ts\n */\nexport const STORAGE_OPS_PER_LOGICAL_WRITE: number = 2;\n\n/**\n * Canonical auth posture identifiers consumed by `BaerlyAppConfig.auth`,\n * the adapter resolution path (`packages/adapter-cloudflare/src/worker.ts`,\n * `packages/adapter-node/src/baerly-node.ts`), and `baerly doctor`.\n *\n * - `\"none\"` — no header check; pin every request to `config.tenant`.\n * For local dev, intranet, CLI tools — contexts where the network\n * seam itself is the trust boundary.\n * - `\"shared-secret\"` — bearer-token check; reads `SHARED_SECRET` from\n * the runtime env and pins every request to `config.tenant`.\n *\n * Custom verifiers (`cloudflareAccess`, `bearerJwt`, SigV4, …) bypass\n * this enum — pass a `Verifier` to the adapter factory's `verifier:`\n * option instead.\n */\nexport const AUTH_CONFIG_VALUES = [\"none\", \"shared-secret\"] as const;\n\n/**\n * Locked error wording for the \"no auth configured\" failure mode. The\n * adapter throws this when neither `config.auth` nor `verifier:`\n * resolves a real `Verifier`. Pinned via a regression test so future\n * refactors do not drift the operator-facing wording.\n *\n * Consumed by:\n * - `packages/adapter-cloudflare/src/worker.ts` (first-fetch throw)\n * - `packages/adapter-node/src/server.ts` (first-fetch throw)\n * - `packages/cli/src/doctor/cloudflare.ts` (FAIL finding mirrors it)\n */\nexport const NO_AUTH_CONFIGURED_MESSAGE: string =\n 'baerly: no auth configured. Set `auth` in baerly.config.ts (\"none\", \"shared-secret\") or pass `verifier` on the adapter factory.';\n\n/**\n * Locked error wording for `auth: \"shared-secret\"` + missing env var.\n * Same pinning rationale as {@link NO_AUTH_CONFIGURED_MESSAGE}.\n */\nexport const SHARED_SECRET_MISSING_MESSAGE: string =\n 'baerly: auth=\"shared-secret\" but SHARED_SECRET env is empty/unset. Cloudflare: `wrangler secret put SHARED_SECRET`, or add to .dev.vars for local dev. Node: set in process env.';\n"],"mappings":";;;;;;AAKA,MAAa,gBAAgB;;;;;AAuG7B,MAAa,4BAAoC;;;;;;;;;;AAoDjD,MAAa,wBAAgC;;;;;;;;AAsB7C,MAAa,4BAAoC;;;;;;AAiCjD,MAAa,0BAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgC/C,MAAa,yBAAiC,QAAc,KAAK;;;;;;;;;;AAWjE,MAAa,4BAAoC;;;;;;;AAqCjD,MAAa,6BAAqC,KAAK;;;;;;;;;AAqHvD,MAAa,qCAA6C,MAAM;;;;;;;;;;;;;;;;;;;;;;;AAyBhE,MAAa,8BAAsC,OAAO;;;;;;;;;;AAW1D,MAAa,4BAAoC;;AAajD,MAAa,8BAAuD;CAClE,YAAA;CACA,YAAA;CACA,aAAA;CACA,uBAAA;CACA,cAAc;CACd,aAAa;AACf;;AAGA,MAAa,2BAAoD;CAC/D,YAAA;CACA,YAAA;CACA,aAAA;CACA,uBAAA;CACA,cAAc;CACd,aAAa;AACf;;;;;;;;;;;;;AAcA,MAAa,8BAAuD;CAClE,YAAA;CACA,YAAA;CACA,aAAA;CACA,uBAAA;CACA,cAAc;CACd,aAAa;AACf;;;;;;;;AASA,MAAa,mCAA2C;;;;;;;;;;AAmCxD,MAAa,kCAA0C;;;;;;;;;;;;;;;;AAiBvD,MAAa,uCAA4C,IAAI,IAAI;CAC/D;CACA;CACA;AACF,CAAC;;;;;;;;;;;;AA6CD,MAAa,6BACX;;;;;AAMF,MAAa,gCACX"}
1
+ {"version":3,"file":"constants-CfeMWQWk.js","names":[],"sources":["../packages/protocol/src/constants.ts"],"sourcesContent":["/**\n * Max total object-key length S3 and R2 accept (UTF-8 bytes). A key\n * over this fails the PUT with an opaque provider 400; baerly surfaces\n * it early as InvalidConfig. See docs/spec/storage-compatibility.md.\n */\nexport const MAX_KEY_BYTES = 1024;\n\n/**\n * Half-window (in milliseconds) within which a `LogEntry`'s embedded\n * `commit_ts` must agree with wall-clock time for downstream consumers\n * to accept the entry as causally ordered. Bound on tolerated\n * client/server clock skew across the protocol.\n *\n * 5 s is the protocol's tolerance for client/server clock skew.\n * Tightening this can cause spurious rejections on machines that\n * haven't synced NTP; loosening it widens the window during which\n * causal ordering can be disturbed by skew.\n *\n * @see docs/spec/sync-protocol.md\n * @see packages/protocol/src/storage/types.ts (`Storage` JSDoc)\n */\nexport const LAG_WINDOW_MILLIS: number = 5000;\n\n/**\n * Bit width of the descending base-32 seq segment in every LSN\n * (`<base32-time>_<session>_<seq>`, minted in `Writer.commit`).\n * The output character width is `Math.ceil(COUNT_BIT_WIDTH / 5) = 11`.\n *\n * **Domain:** 0 .. `Number.MAX_SAFE_INTEGER` (2^53 − 1). A collection\n * would need 2^53 writes before the seq counter could overflow — an\n * unreachable ceiling in practice.\n *\n * **Why 53 bits:** JavaScript numbers are IEEE-754 doubles; the safe\n * integer range is exactly [0, 2^53 − 1]. Encoding at this width keeps\n * the arithmetic in the encoder and decoder (`uint2strDesc` /\n * `str2uintDesc` in `packages/protocol/src/types.ts`) exact and\n * leaves no headroom for the negative-overflow path that manifested\n * at the old 10-bit width (domain 0..1023).\n *\n * **Ordering property:** fixed-width base-32 encoding preserves\n * descending lex order across the entire domain\n * (`countKey(a) > countKey(b)` iff `a < b`), which the reverse-walk\n * on `Storage.list` relies on.\n *\n * **Three production consumers** must all agree on this value:\n * 1. Encoder — `countKey` in `packages/protocol/src/types.ts`\n * 2. Decoder — `lsnParts` in `packages/protocol/src/log.ts`\n * 3. Validator regex — `LSN_RE` in `packages/server/src/http/since.ts`\n * (derives its `{N}` from `Math.ceil(COUNT_BIT_WIDTH / 5)`)\n *\n * The independent shape-assertion literal in\n * `tests/fixtures/collection-api-cascade.ts` is kept hand-written and\n * is NOT a consumer of this constant (importing the production\n * validator into the test that checks it would make the assertion\n * a tautology).\n *\n * Changing this constant is a protocol-breaking change — it reshapes\n * every emitted LSN cursor.\n *\n * @see packages/protocol/src/types.ts (`countKey`, `uint2strDesc`)\n * @see packages/protocol/src/log.ts (`lsnParts`, `str2uintDesc` call)\n * @see packages/server/src/http/since.ts (`LSN_RE`)\n * @see docs/spec/log-entry-shape.md\n */\nexport const COUNT_BIT_WIDTH: number = 53;\n\n/**\n * Bit width of the base-32 timestamp prefix encoded into every\n * {@link LogEntry.lsn} (`<base32-time>_<session>_<seq>`, minted in\n * `Writer.commit`). 42 bits gives ~139 years of millisecond\n * precision, which is enough for the protocol's lifetime.\n *\n * Changing this is a protocol-breaking change — it would re-shape\n * every emitted LSN.\n *\n * @see packages/protocol/src/time.ts (`timestamp`)\n * @see packages/server/src/writer.ts (`Writer.commit`)\n * @see docs/spec/sync-protocol.md\n */\nexport const TIMESTAMP_BIT_WIDTH: number = 42;\n\n/**\n * Length of the random-prefix `session` segment embedded in every\n * {@link LogEntry.lsn} (`<base32-time>_<session>_<seq>`). 6 hex chars\n * from `crypto.randomUUID()` give 16⁶ ≈ 1.7 × 10⁷ distinct sessions;\n * birthday-collision rate at N=100 is ~3 × 10⁻⁴, comfortably below\n * the 1 % bound asserted in `tests/regressions.test.ts`. Collisions\n * within a single commit's writer set are also disambiguated by the\n * trailing `<seq>` counter.\n *\n * @see packages/server/src/writer.ts (`Writer.commit` —\n * `session = uuid().slice(0, SESSION_ID_LENGTH)`)\n */\nexport const SESSION_ID_LENGTH: number = 6;\n\n/**\n * Maximum attempts `S3HttpStorage.list` will make per page when the\n * server replies 429 (rate-limited). After this many in a row, it\n * gives up with `NetworkError`. Separate from the inner transient-\n * failure budget so a single hot page can't burn the whole retry\n * allowance.\n */\nexport const LIST_OBJECT_MAX_RETRIES: number = 10;\n\n/**\n * Backoff (in milliseconds) inserted between LIST attempts when S3\n * returns 429 (rate-limited).\n */\nexport const RATE_LIMIT_BACKOFF_MILLIS: number = 1000;\n\n/**\n * Upper clamp on a server-provided `Retry-After` hint, in seconds.\n * RFC 7231 §7.1.3 allows arbitrary delta-seconds or HTTP-dates, but a\n * client that blindly honours a multi-hour hint hands a misbehaving\n * proxy a denial-of-service primitive. 60s covers any plausible S3-\n * compatible throttle while keeping the worst-case bounded.\n *\n * @see packages/adapter-node/src/http-transport.ts (`parseRetryAfter`)\n */\nexport const RETRY_AFTER_MAX_SECONDS: number = 60;\n\n/**\n * Default retry budget for `S3HttpStorage.retry` (the wrapper around\n * each of the four `Storage` methods). Bounded so that permanent\n * failures (CORS misconfig, NXDOMAIN, persistent 5xx) surface to\n * callers as rejected promises instead of retrying forever and\n * leaving `Writer.commit()` permanently pending.\n *\n * 8 attempts at the existing 100ms→×1.5→10s schedule covers ~30s of\n * transient turbulence, which is enough to ride out a leader election\n * or a brief network blip without papering over a real outage.\n */\nexport const S3_REQUEST_MAX_RETRIES: number = 8;\n\n/**\n * Maximum concurrent log-entry GETs issued by a single `walkLogRange`\n * call. Bounds Class-B fan-out per read and per CAS attempt — without\n * a bound, a reader on a collection whose compactor has fallen behind\n * fans out one GET per live-tail entry (typically 50-100 on the free-\n * tier profile), and a contended writer multiplies that by the CAS\n * retry budget ({@link S3_REQUEST_MAX_RETRIES}).\n *\n * 16 keeps the worst-case under retry to `16 * 8 = 128` concurrent\n * GETs — comfortably under the Workers subrequest cap (50 concurrent\n * / 1000 total) and leaving headroom for the writer's content / index\n * / log / CAS PUTs sharing the same isolate.\n *\n * @see packages/server/src/log-walk.ts (`walkLogRange`)\n */\nexport const MAX_PARALLEL_LOG_READS: number = 16;\n\n/**\n * Runaway guard on the tolerant forward-probe walk (`probeTailFrom`):\n * max `log/<seq>` GETs past `tail_hint` before it THROWS `Internal`\n * (rather than silently truncating reads). A runaway alarm only — the\n * maintenance tick keeps `tail_hint` near the tail, so a >cap gap means\n * maintenance is off or the collection is far past graduation.\n *\n * @see packages/server/src/log-tail.ts (`probeTailFrom`)\n */\nexport const LOG_FORWARD_PROBE_CAP: number = 100_000;\n\n/**\n * Current major version of the `current.json` control-object schema.\n * Readers MUST reject unknown versions with\n * `BaerlyError{code:\"InvalidResponse\"}` rather than try to coerce.\n *\n * Bump only on a breaking change to `CurrentJson` field semantics.\n * Adding a new optional field is NOT breaking; renaming or removing\n * a field IS breaking.\n *\n * @see packages/protocol/src/coordination/current-json.ts\n */\nexport const CURRENT_JSON_SCHEMA_VERSION = 3 as const;\n\n/**\n * MIME type written for `current.json` PUTs. S3 round-trips this on\n * subsequent GETs; useful for diagnostics when staring at a bucket\n * via the AWS console.\n *\n * @see packages/protocol/src/coordination/current-json.ts\n */\nexport const CURRENT_JSON_CONTENT_TYPE: string = \"application/json\";\n\n/**\n * Current major version of the `gc/pending.json` control-object\n * schema. Readers MUST reject unknown versions with\n * `BaerlyError{code:\"InvalidResponse\"}` rather than try to coerce.\n *\n * Bump only on a breaking change to `GcPending` field semantics.\n * Adding a new optional field is NOT breaking; renaming or removing\n * a field IS breaking.\n *\n * @see packages/protocol/src/coordination/gc-pending.ts\n */\nexport const GC_PENDING_SCHEMA_VERSION = 1 as const;\n\n/**\n * Current major version of the snapshot control-object schema\n * ({@link SnapshotBody}). Readers MUST reject unknown versions with\n * `BaerlyError{code:\"InvalidResponse\"}` rather than try to coerce.\n *\n * Bump only on a breaking change to `SnapshotBody` field semantics.\n * Adding a new optional field is NOT breaking; renaming or removing\n * a field IS breaking.\n *\n * @see packages/server/src/snapshot.ts\n */\nexport const SNAPSHOT_SCHEMA_VERSION = 1 as const;\n\n/**\n * MIME type written for `gc/pending.json` PUTs.\n *\n * @see packages/protocol/src/coordination/gc-pending.ts\n */\nexport const GC_PENDING_CONTENT_TYPE: string = \"application/json\";\n\n/**\n * Default grace period between \"marking\" a key for GC and \"sweeping\"\n * (deleting) it. 7 days, chosen to span the worst plausible writer-\n * retry window (a paused-process writer that resumes hours later\n * should still find its idempotency anchor on the bucket). The\n * `runGc()` function accepts an override for tests.\n *\n * Why 7 days specifically:\n * - **1 day is too aggressive for batch workloads.** Worker isolate\n * scheduling pauses, cross-region replication lag, and\n * {@link RATE_LIMIT_BACKOFF_MILLIS} retry cascades can plausibly\n * exceed an hour under pathological conditions.\n * - **30 days is conservative beyond the worst plausible pause.**\n * Doubles `gc/pending.json` size at steady state and slows\n * visibility into \"did GC actually run?\" by 4×.\n * - **7 days spans the realistic upper bound** — long-running batch\n * jobs, multi-region propagation delays, queue backlogs, and\n * downstream outages the writer is retrying through. The protocol\n * is unaffected by the choice of value within the [hours, weeks]\n * range; this constant is the operator-tunable knob.\n *\n * Production code MUST NOT call `runGc` with `graceMillis` below the\n * default outside maintenance windows — going below the longest\n * plausible writer-retry latency risks deleting an anchor a writer\n * is about to find on retry. Test code that sets `graceMillis: 0` is\n * exercising the sweep path deliberately, not modelling production.\n *\n * @see packages/server/src/gc.ts\n */\n// Stryker disable next-line ArithmeticOperator: internal tuning value, not an off-process contract — asserting the literal would be a tautological change-detector. See docs/contributing/mutation-testing.md constants policy.\nexport const GC_GRACE_PERIOD_MILLIS: number = 7 * 24 * 60 * 60 * 1000;\n\n/**\n * Cap on candidates kept in `gc/pending.json` to bound the size of\n * the file. The compactor marks at most this many candidates per\n * pass; subsequent passes pick up the rest. Larger collections will\n * lag GC by one pass per `GC_MAX_PENDING_CANDIDATES` orphans, which\n * is acceptable.\n *\n * @see packages/server/src/gc.ts\n */\nexport const GC_MAX_PENDING_CANDIDATES: number = 1000;\n\n/**\n * Bounded retry cap for the `gc/pending.json` CAS read-modify-write\n * loop in {@link casUpdateGcPending}. On `Conflict` (a concurrent GC\n * pass landed between this pass's read and its write) the loop\n * re-reads `latest` and re-applies the pure merge mutator, retrying up\n * to this many total attempts before surfacing `Conflict`. Safe to\n * retry because the mutator is pure and the sweep DELETEs are\n * idempotent and already performed; a re-merge against fresh state\n * never loses a concurrently-marked candidate. Small fixed cap — under\n * one writer per collection at steady state, contention is rare; this\n * just bounds the worst case so a pathological storm can't spin.\n *\n * @see packages/protocol/src/coordination/gc-pending.ts\n */\nexport const GC_PENDING_CAS_MAX_ATTEMPTS: number = 3;\n\n/**\n * Fold-trigger ratio: fold fires at tail ≥ R×snapshot. Pure READ-AMP / fold-frequency\n * knob — with the ceiling on the snapshot axis (Decision 3a, tail sliced) the\n * auto-maintained snapshot ceiling is S_max = C, NOT C/(1+R). R=1.0 caps steady-state\n * read-amp at ~2× and keeps compaction write-amp (≈1+1/R) moderate. See\n * docs/about/graduation.md for the derivation.\n *\n * @see docs/about/graduation.md\n * @see packages/server/src/maintenance.ts\n */\nexport const MAINTENANCE_TARGET_RATIO: number = 1;\n\n/**\n * Floor for the ratio denominator — avoid div-by-tiny on a fresh collection. Also\n * sets the first-fold threshold: until a snapshot exists, fold fires at tail ≈ this.\n *\n * @see packages/server/src/maintenance.ts\n */\n// Stryker disable next-line ArithmeticOperator: internal tuning value, not an off-process contract — asserting the literal would be a tautological change-detector. See docs/contributing/mutation-testing.md constants policy.\nexport const MAINTENANCE_MIN_LIVE_BYTES: number = 64 * 1024;\n\n/**\n * Cold-start per-entry byte estimate for the ratio TRIGGER's derived live-tail\n * size (`estimateTailBytes`), used until the compactor stamps a real\n * `current.json.mean_entry_bytes` on the first fold. Folding too-few entries is\n * barred by Gate-1's entry-count floor (`minEntriesToCompact`), NOT by this\n * value — so over-estimating is equally safe; this is a first-fold-TIMING\n * choice. A small typical log-entry size keeps the first fold's cadence close\n * to a precisely measured path for typical entries; must be non-zero so a\n * bare `Db.create()` still bootstraps its first auto-fold (a 0 fallback leaves\n * the ratio dead pre-stamp). Large-body collections see a bounded first-fold\n * delay; after it stamps a real mean the estimate tracks the exact tail.\n *\n * @see packages/server/src/maintenance.ts (`estimateTailBytes`)\n */\n// Stryker disable next-line ArithmeticOperator: internal cold-start tuning value, not an off-process contract — asserting the literal would be a tautological change-detector. See docs/contributing/mutation-testing.md constants policy.\nexport const MAINTENANCE_COLD_START_ENTRY_BYTES: number = 128;\n\n/**\n * Per-tick GC budget — these are DEFAULTS (= the most-constrained tier, CF free, reusing\n * the TESTED `CLOUDFLARE_FREE_TIER` values in maintenance.ts / maintenance-budget.test.ts).\n * The adapter THREADS per-tier overrides into the context (§8.4); Node/CF-paid raise them.\n * NOT universal constants — a Node-sized value here would silently kill every CF-free fold\n * (round-4 Tier-1). gc pass ≈ 6 + maxMarks + maxSweeps subrequests (both GET/DELETE the\n * bucket — §3.1). Cadence is BOUNDARY-CROSSING (§3.1), not modulo.\n *\n * @see packages/server/src/maintenance.ts\n * @see packages/server/src/maintenance-budget.test.ts\n */\nexport const WRITE_TICK_GC_INTERVAL: number = 4; // tuned so maxSweeps/interval ≥ p (§7.1)\n\n/**\n * Fold-starvation guard (critique A): on `phasesPerTick:\"single\"`, every Nth GC-interval is a\n * HARD GC boundary the fold may NOT preempt, so a long fold-heavy drain can't starve GC to zero.\n * Stateless (seq-derived) — no per-isolate preemption counter (CF recycles isolates). At 4 a\n * sustained drain still yields ~1 GC tick per 4 GC-intervals.\n *\n * @see packages/server/src/maintenance.ts\n */\nexport const GC_STARVATION_GUARD: number = 4;\n\n/**\n * Maximum GC marks per write-tick pass (M in 6+M+S; GETs the live tail to hash).\n *\n * @see packages/server/src/maintenance.ts\n */\nexport const WRITE_TICK_GC_MAX_MARKS: number = 20;\n\n/**\n * Maximum GC sweeps per write-tick pass (S in 6+M+S; DELETE subrequests).\n *\n * @see packages/server/src/maintenance.ts\n */\nexport const WRITE_TICK_GC_MAX_SWEEPS: number = 10;\n\n/**\n * Per-pass tail SLICE default — compact()'s maxEntriesPerRun. Fold ≤ this+3 subrequests, so\n * a large tail drains incrementally over write-ticks (Decision 3). Adapter-overridable.\n *\n * @see packages/server/src/maintenance.ts\n */\nexport const WRITE_TICK_FOLD_ENTRIES_PER_PASS: number = 20;\n\n/**\n * compact()'s minEntriesToCompact, set EXPLICITLY by the runner so it agrees with Gate 1\n * rather than inheriting compact()'s silent default 100 (which would contradict the 64 KB\n * first-fold story — round-4 Tier-3). Adapter-overridable; CF-free value.\n *\n * @see packages/server/src/maintenance.ts\n */\nexport const WRITE_TICK_MIN_ENTRIES_TO_COMPACT: number = 50;\n\n/**\n * Node-tier write-tick maintenance caps — a MODERATE multiple of the CF-free `WRITE_TICK_*`\n * defaults, threaded into the per-request observability context by `baerlyNode` /\n * `createFetchHandler` (§8.4). Node v1 runs maintenance INLINE on the commit path (no\n * `waitUntil`), so the cap is NOT the CF subrequest wall — it's the worst-case single-write\n * added latency. A maintenance tick only fires on a ratio/boundary trip (rare), and when it\n * does it costs ~`maxFoldEntriesPerPass` + (6 + `gcMaxMarks` + `gcMaxSweeps`) storage\n * round-trips against a co-located S3/R2 — sub-second on the occasional boundary write at a\n * 10× multiple. These are deliberately BOUNDED (10× CF-free), NOT unbounded: the deleted\n * scheduled full-tail sweep folded the entire live tail in one shot, which a 100× multiple here\n * would reintroduce as multi-second commit stalls. Raise the snapshot ceiling separately via\n * `BAERLY_MAINTENANCE_MAX_FOLD_BYTES`; these caps slice the per-pass work, not the ceiling.\n *\n * @see packages/adapter-node/src/server.ts\n * @see packages/server/src/maintenance.ts\n * @see docs/about/graduation.md\n */\nexport const NODE_MAINTENANCE_FOLD_ENTRIES_PER_PASS: number = 200;\n\n/** Node-tier GC marks per pass (M in 6+M+S). 10× CF-free. @see {@link NODE_MAINTENANCE_FOLD_ENTRIES_PER_PASS} */\nexport const NODE_MAINTENANCE_GC_MAX_MARKS: number = 200;\n\n/** Node-tier GC sweeps per pass (S in 6+M+S). 10× CF-free. @see {@link NODE_MAINTENANCE_FOLD_ENTRIES_PER_PASS} */\nexport const NODE_MAINTENANCE_GC_MAX_SWEEPS: number = 100;\n\n/**\n * Node-tier GC cadence (boundary-crossing). Shorter than the CF-free `WRITE_TICK_GC_INTERVAL`\n * (4) so the per-write sweep budget keeps up: `gcMaxSweeps / gcInterval = 100 / 2 = 50`\n * comfortably clears the garbage-per-write rate `p` (the `maxSweeps/interval ≥ p` invariant,\n * §7.1) with a wide margin.\n *\n * @see {@link NODE_MAINTENANCE_FOLD_ENTRIES_PER_PASS}\n */\nexport const NODE_MAINTENANCE_GC_INTERVAL: number = 2;\n\n/**\n * SNAPSHOT-rebuild ceiling `C` (the unsliceable axis — Decision 3a), memory. Default sized\n * ~5.5 ms under CF-free ~10 ms. Raise via BAERLY_MAINTENANCE_MAX_FOLD_BYTES on capable\n * hosts. Auto-maintained snapshot ceiling S_max = C. NOT snapshot+tail (tail is sliced).\n *\n * @see docs/about/graduation.md\n * @see packages/server/src/maintenance.ts\n */\n// Stryker disable next-line ArithmeticOperator: internal tuning value, not an off-process contract — asserting the literal would be a tautological change-detector. See docs/contributing/mutation-testing.md constants policy.\nexport const MAINTENANCE_MAX_FOLD_BYTES_DEFAULT: number = 512 * 1024;\n\n/**\n * The largest snapshot a Cloudflare **free-tier** isolate can safely\n * rebuild in ONE fold under the ~10 ms CPU budget. This is the WARN\n * THRESHOLD, not a runtime cap: an operator who raises\n * `BAERLY_MAINTENANCE_MAX_FOLD_BYTES` ABOVE this value on a free Worker\n * risks a snapshot rebuild that exceeds the ~10 ms CPU limit and gets\n * CPU-killed MID-REBUILD — the CAS never lands, so the fold silently\n * never advances `log_seq_start` and the tail grows unbounded.\n *\n * Sized at 2× {@link MAINTENANCE_MAX_FOLD_BYTES_DEFAULT}. The default\n * (512 KiB) rebuilds in ~5.5 ms under the CF-free ~10 ms budget\n * (constants.ts default JSDoc); linear-extrapolating, ~1 MiB is the\n * point where one-shot rebuild fills the budget with little margin, so\n * anything strictly larger is no longer free-tier-safe. On CF **paid**\n * (raised CPU limits), Node, or once §11 chunked snapshots land, a\n * larger ceiling is fine — hence this is a one-time `console.warn` at\n * handler init, NOT a hard rejection.\n *\n * @see packages/adapter-cloudflare/src/worker.ts\n * @see packages/server/src/maintenance.ts\n * @see docs/about/graduation.md\n */\n// Stryker disable next-line ArithmeticOperator: internal tuning value, not an off-process contract — asserting the literal would be a tautological change-detector. See docs/contributing/mutation-testing.md constants policy.\nexport const CF_FREE_MAX_SAFE_FOLD_BYTES: number = 1024 * 1024;\n\n/**\n * SNAPSHOT-rebuild ceiling `E`, per-entry CPU axis: gates `snapshot_rows` (per-entry\n * parse/merge/serialize is ~half of fold CPU and scales with ROW COUNT not bytes, VLDB 2021\n * Sarkar — a tiny-doc snapshot can blow CPU under C). PROVISIONAL — bench\n * landed; paid recalibration deferred.\n *\n * @see docs/about/graduation.md\n * @see packages/server/src/maintenance.ts\n */\nexport const MAINTENANCE_MAX_FOLD_ROWS: number = 2048;\n\n// Declared here (not the nominal server `MaintenanceProfile`) to avoid a server→protocol cycle; keep field-identical to it.\ntype MaintenanceProfileShape = Readonly<{\n gcInterval: number;\n gcMaxMarks: number;\n gcMaxSweeps: number;\n maxFoldEntriesPerPass: number;\n maxFoldBytes: number;\n maxFoldRows: number;\n}>;\n\n/** CF-free profile; the absent-context default. */\nexport const MAINTENANCE_PROFILE_CF_FREE: MaintenanceProfileShape = {\n gcInterval: WRITE_TICK_GC_INTERVAL,\n gcMaxMarks: WRITE_TICK_GC_MAX_MARKS,\n gcMaxSweeps: WRITE_TICK_GC_MAX_SWEEPS,\n maxFoldEntriesPerPass: WRITE_TICK_FOLD_ENTRIES_PER_PASS,\n maxFoldBytes: MAINTENANCE_MAX_FOLD_BYTES_DEFAULT,\n maxFoldRows: MAINTENANCE_MAX_FOLD_ROWS,\n};\n\n/** Node profile; 10× CF-free caps. */\nexport const MAINTENANCE_PROFILE_NODE: MaintenanceProfileShape = {\n gcInterval: NODE_MAINTENANCE_GC_INTERVAL,\n gcMaxMarks: NODE_MAINTENANCE_GC_MAX_MARKS,\n gcMaxSweeps: NODE_MAINTENANCE_GC_MAX_SWEEPS,\n maxFoldEntriesPerPass: NODE_MAINTENANCE_FOLD_ENTRIES_PER_PASS,\n maxFoldBytes: MAINTENANCE_MAX_FOLD_BYTES_DEFAULT,\n maxFoldRows: MAINTENANCE_MAX_FOLD_ROWS,\n};\n\n/**\n * CF-paid profile — opt-in via `BAERLY_MAINTENANCE_PROFILE=cf-paid`. A paid\n * isolate keeps the CPU-killable single-phase shape but has the 10,000-\n * subrequest budget (vs free's 50), so it reuses the `NODE_MAINTENANCE_*`\n * per-pass caps. CRITICAL: snapshot ceilings `maxFoldBytes` (`C`) /\n * `maxFoldRows` (`E`) are UNCHANGED — a profile moves rate, never correctness\n * (the equivalence invariant); the memory wall is raised via\n * `BAERLY_MAINTENANCE_MAX_FOLD_BYTES`.\n *\n * @see packages/adapter-cloudflare/src/worker.ts\n * @see docs/about/graduation.md\n */\nexport const MAINTENANCE_PROFILE_CF_PAID: MaintenanceProfileShape = {\n gcInterval: NODE_MAINTENANCE_GC_INTERVAL,\n gcMaxMarks: NODE_MAINTENANCE_GC_MAX_MARKS,\n gcMaxSweeps: NODE_MAINTENANCE_GC_MAX_SWEEPS,\n maxFoldEntriesPerPass: NODE_MAINTENANCE_FOLD_ENTRIES_PER_PASS,\n maxFoldBytes: MAINTENANCE_MAX_FOLD_BYTES_DEFAULT,\n maxFoldRows: MAINTENANCE_MAX_FOLD_ROWS,\n};\n\n/**\n * Rate-limit the defer-warn off SHARED current.json.last_warned_seq (not per-isolate\n * memory — CF recycles isolates). ~once per this many writes.\n *\n * @see packages/protocol/src/coordination/current-json.ts\n * @see packages/server/src/maintenance.ts\n */\nexport const MAINTENANCE_WARN_INTERVAL_WRITES: number = 1000;\n\n/**\n * Rate-limit for the maintenance tick's `tail_hint` advance on the\n * DEFER path (HR-2). When the fold defers (snapshot over the CF-CPU-kill\n * ceiling) the compactor never stamps `tail_hint` via its Step-7 fold\n * CAS, so the gap `(true_tail − tail_hint)` would grow without bound and\n * every read would re-walk the whole live tail via `probeTailFrom`. The\n * runner therefore advances `tail_hint` toward the observed tail with a\n * best-effort `current.json` CAS — but only once per this many writes,\n * so it is NOT a per-commit `current.json` write (which is exactly what\n * single-write commit removed).\n *\n * Sized at 128: it bounds a deferring collection's worst-case\n * read-walk to ≤128 forward GETs (≈one extra read-page sweep — a\n * negligible per-read latency cost), keeps the gap two-to-three orders\n * of magnitude below {@link LOG_FORWARD_PROBE_CAP} (so the cap-throw is a\n * pure runaway guard, never reached in normal operation), and holds the\n * hint-advance CAS rate under ~1% of the commit rate (negligible\n * Class-A cost, amortized). Smaller would tighten the read-walk at a\n * higher CAS rate; larger would loosen it — 128 is the modest middle.\n *\n * @see packages/server/src/maintenance.ts\n */\nexport const MAINTENANCE_TAIL_HINT_REFRESH_WRITES: number = 128;\n\n/**\n * Stable seed for `CurrentJson.snapshot === null` when building the\n * opaque `_meta.manifest_pointer` cursor emitted on read responses.\n * The literal no longer appears by itself on the wire; it is folded\n * into the server-side digest so the cursor never exposes physical\n * snapshot keys.\n *\n * @see packages/server/src/contract.ts (HttpOkMeta)\n */\nexport const MANIFEST_POINTER_EMPTY_SNAPSHOT: string = \"none\";\n\n/**\n * Keys that must never propagate through {@link merge}: assigning to\n * them on a plain object pollutes the prototype chain. The literal\n * `{ __proto__: ... }` syntax is a prototype-setter (not an own key)\n * and bypasses `Object.keys`, but `JSON.parse('{\"__proto__\":...}')`\n * produces a real own property — which is exactly how a malicious\n * HTTP PATCH body would arrive on the wire.\n *\n * Lifted to a constant so every iteration path that touches a\n * caller-supplied object can re-use the same defence without\n * duplicating the keyword list.\n *\n * @see packages/protocol/src/json.ts (merge)\n * @see docs/spec/json-merge-patch.md\n */\nexport const FORBIDDEN_MERGE_KEYS: ReadonlySet<string> = new Set([\n \"__proto__\",\n \"constructor\",\n \"prototype\",\n]);\n\n/**\n * Architecturally-enforced ceiling: storage ops per logical write.\n *\n * Two Class A ops: PUT content + the committing `log/<seq>` create\n * (`If-None-Match: \"*\"`). There is no `current.json` CAS on the commit\n * path — the winning log create IS the commit. The cost-model page\n * derives the free-tier write budget from this multiplier; the\n * maintenance end-to-end test asserts it at CI time. Changing this constant is a\n * cost-model-breaking change.\n *\n * @see docs/about/cost-model.md §\"Cost ceiling\"\n * @see tests/integration/maintenance-e2e.test.ts\n */\nexport const STORAGE_OPS_PER_LOGICAL_WRITE: number = 2;\n\n/**\n * Canonical auth posture identifiers consumed by `BaerlyAppConfig.auth`,\n * the adapter resolution path (`packages/adapter-cloudflare/src/worker.ts`,\n * `packages/adapter-node/src/baerly-node.ts`), and `baerly doctor`.\n *\n * - `\"none\"` — no header check; pin every request to `config.tenant`.\n * For local dev, intranet, CLI tools — contexts where the network\n * seam itself is the trust boundary.\n * - `\"shared-secret\"` — bearer-token check; reads `SHARED_SECRET` from\n * the runtime env and pins every request to `config.tenant`.\n *\n * Custom verifiers (`cloudflareAccess`, `bearerJwt`, SigV4, …) bypass\n * this enum — pass a `Verifier` to the adapter factory's `verifier:`\n * option instead.\n */\nexport const AUTH_CONFIG_VALUES = [\"none\", \"shared-secret\"] as const;\n\n/**\n * Locked error wording for the \"no auth configured\" failure mode. The\n * adapter throws this when neither `config.auth` nor `verifier:`\n * resolves a real `Verifier`. Pinned via a regression test so future\n * refactors do not drift the operator-facing wording.\n *\n * Consumed by:\n * - `packages/adapter-cloudflare/src/worker.ts` (first-fetch throw)\n * - `packages/adapter-node/src/server.ts` (first-fetch throw)\n * - `packages/cli/src/doctor/cloudflare.ts` (FAIL finding mirrors it)\n */\nexport const NO_AUTH_CONFIGURED_MESSAGE: string =\n 'baerly: no auth configured. Set `auth` in baerly.config.ts (\"none\", \"shared-secret\") or pass `verifier` on the adapter factory.';\n\n/**\n * Locked error wording for `auth: \"shared-secret\"` + missing env var.\n * Same pinning rationale as {@link NO_AUTH_CONFIGURED_MESSAGE}.\n */\nexport const SHARED_SECRET_MISSING_MESSAGE: string =\n 'baerly: auth=\"shared-secret\" but SHARED_SECRET env is empty/unset. Cloudflare: `wrangler secret put SHARED_SECRET`, or add to .dev.vars for local dev. Node: set in process env.';\n"],"mappings":";;;;;;AAKA,MAAa,gBAAgB;;;;;AAuG7B,MAAa,4BAAoC;;;;;;;;;;AAoDjD,MAAa,wBAAgC;;;;;;;;AAsB7C,MAAa,4BAAoC;;;;;;AAiCjD,MAAa,0BAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgC/C,MAAa,yBAAiC,QAAc,KAAK;;;;;;;;;;AAWjE,MAAa,4BAAoC;;;;;;;AAqCjD,MAAa,6BAAqC,KAAK;;;;;;;;;AAqHvD,MAAa,qCAA6C,MAAM;;;;;;;;;;;;;;;;;;;;;;;AAyBhE,MAAa,8BAAsC,OAAO;;;;;;;;;;AAW1D,MAAa,4BAAoC;;AAajD,MAAa,8BAAuD;CAClE,YAAA;CACA,YAAA;CACA,aAAA;CACA,uBAAA;CACA,cAAc;CACd,aAAa;AACf;;AAGA,MAAa,2BAAoD;CAC/D,YAAA;CACA,YAAA;CACA,aAAA;CACA,uBAAA;CACA,cAAc;CACd,aAAa;AACf;;;;;;;;;;;;;AAcA,MAAa,8BAAuD;CAClE,YAAA;CACA,YAAA;CACA,aAAA;CACA,uBAAA;CACA,cAAc;CACd,aAAa;AACf;;;;;;;;AASA,MAAa,mCAA2C;;;;;;;;;;AAmCxD,MAAa,kCAA0C;;;;;;;;;;;;;;;;AAiBvD,MAAa,uCAA4C,IAAI,IAAI;CAC/D;CACA;CACA;AACF,CAAC;;;;;;;;;;;;AA6CD,MAAa,6BACX;;;;;AAMF,MAAa,gCACX"}
@@ -1,7 +1,7 @@
1
- import { r as parseBucketUri } from "./config-1tv0-Yzm.js";
1
+ import { r as parseBucketUri } from "./config-B6nTy8e2.js";
2
2
  import { i as isJsonMode, o as BaerlyError, r as emitSuccess } from "./baerly.js";
3
- import { a as TENANT_ARG, i as JSON_ARG, n as BUCKET_ARG, o as assertCollectionArg, r as COLLECTION_ARG, s as defineBaerlySubcommand, t as APP_ARG } from "./subcommand-DoDA-K7d.js";
4
- import { estimateWritesPerMin } from "./usage-DBV1eQHC.js";
3
+ import { a as TENANT_ARG, i as JSON_ARG, n as BUCKET_ARG, o as assertCollectionArg, r as COLLECTION_ARG, s as defineBaerlySubcommand, t as APP_ARG } from "./subcommand-BV68pqwJ.js";
4
+ import { estimateWritesPerMin } from "./usage-BMZR8o6U.js";
5
5
  //#region src/cost/provider.ts
6
6
  const detectProvider = (args) => {
7
7
  if (args.override !== void 0) return args.override;
@@ -200,4 +200,4 @@ bundle.run;
200
200
  //#endregion
201
201
  export { cost };
202
202
 
203
- //# sourceMappingURL=cost-DSMIVqzL.js.map
203
+ //# sourceMappingURL=cost-_SE_SVgZ.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"cost-DSMIVqzL.js","names":[],"sources":["../packages/cli/src/cost/provider.ts","../packages/cli/src/cost/project.ts","../packages/cli/src/cost.ts"],"sourcesContent":["/**\n * Provider sniffer: maps a bucket URI + optional S3 endpoint into a\n * pricing tag, and resolves that tag into a `ProviderPricing`\n * record. Pure — zero I/O.\n *\n * Detection rules (first match wins):\n * - `file://*` → \"dev\"\n * - `memory://*` → \"dev\"\n * - `s3://*` + endpoint matching `*.r2.cloudflarestorage.com` → \"r2\"\n * - `s3://*` + endpoint matching `*.amazonaws.com` → \"aws-s3\"\n * - `s3://*` + no endpoint → \"aws-s3\"\n * - everything else (Minio, Backblaze, on-prem, unknown s3 endpoint) → \"self-hosted\"\n *\n * `override` skips detection entirely — used by the\n * `baerly inspect --provider=...` CLI flag when auto-detection picks\n * wrong (e.g., a self-hosted S3 gateway in front of R2).\n */\n\nimport type { ProviderPricing } from \"./project.ts\";\n\nexport type ProviderTag = ProviderPricing[\"provider\"];\n\nexport interface DetectArgs {\n /** Raw bucket URI as passed on the CLI (s3://, file://, memory://). */\n readonly bucketUri: string;\n /** Effective S3 endpoint at parse time (typically `process.env[\"BAERLY_S3_ENDPOINT\"]`). */\n readonly s3Endpoint?: string;\n /** When set, skip detection and return this tag. */\n readonly override?: ProviderTag;\n}\n\nexport const detectProvider = (args: DetectArgs): ProviderTag => {\n if (args.override !== undefined) {\n return args.override;\n }\n if (args.bucketUri.startsWith(\"file://\")) {\n return \"dev\";\n }\n if (args.bucketUri.startsWith(\"memory://\")) {\n return \"dev\";\n }\n if (!args.bucketUri.startsWith(\"s3://\")) {\n return \"self-hosted\";\n }\n // s3:// branch — look at the endpoint.\n const endpoint = args.s3Endpoint ?? \"\";\n if (endpoint === \"\") {\n return \"aws-s3\";\n } // default AWS\n if (/\\.r2\\.cloudflarestorage\\.com(:\\d+)?\\/?$/i.test(endpoint)) {\n return \"r2\";\n }\n if (/\\.amazonaws\\.com(:\\d+)?\\/?$/i.test(endpoint)) {\n return \"aws-s3\";\n }\n return \"self-hosted\";\n};\n\n/**\n * R2 price table.\n * Source: <https://developers.cloudflare.com/r2/pricing/> (review date 2026-05-17).\n * Change-control: pair every edit with a `docs/about/pricing-log.md` entry.\n */\nconst R2_PRICING: ProviderPricing = {\n provider: \"r2\",\n freeClassAPerMonth: 1_000_000,\n usdPerMillionClassA: 4.5,\n freeStorageGb: 10,\n usdPerGbMonth: 0.015,\n effectiveWriteAmp: 3,\n};\n\n/**\n * AWS S3 (Standard) price table.\n * Source: <https://aws.amazon.com/s3/pricing/> (review date 2026-05-17).\n * The 12-month new-account free tier is intentionally excluded\n * (most operators are past it; reporting $0 to them would lie).\n */\nconst AWS_S3_PRICING: ProviderPricing = {\n provider: \"aws-s3\",\n freeClassAPerMonth: 0,\n usdPerMillionClassA: 5,\n freeStorageGb: 0,\n usdPerGbMonth: 0.023,\n effectiveWriteAmp: 4,\n};\n\nconst SELF_HOSTED_PRICING: ProviderPricing = {\n provider: \"self-hosted\",\n freeClassAPerMonth: 0,\n usdPerMillionClassA: Number.NaN,\n freeStorageGb: 0,\n usdPerGbMonth: Number.NaN,\n effectiveWriteAmp: 4,\n};\n\nconst DEV_PRICING: ProviderPricing = {\n provider: \"dev\",\n freeClassAPerMonth: 0,\n usdPerMillionClassA: Number.NaN,\n freeStorageGb: 0,\n usdPerGbMonth: Number.NaN,\n effectiveWriteAmp: 4,\n};\n\nexport const pricingFor = (provider: ProviderTag): ProviderPricing => {\n switch (provider) {\n case \"r2\": {\n return R2_PRICING;\n }\n case \"aws-s3\": {\n return AWS_S3_PRICING;\n }\n case \"self-hosted\": {\n return SELF_HOSTED_PRICING;\n }\n case \"dev\": {\n return DEV_PRICING;\n }\n }\n};\n","/**\n * Pure projection math for the `baerly inspect` cost-trajectory\n * footer. Zero I/O. Price tables live as top-level constants; every\n * change MUST be paired with a `docs/about/pricing-log.md` entry.\n *\n * Three rules:\n * 1. `classAPerMonth = writesPerMin × 60 × 24 × 30 × effectiveWriteAmp`\n * where `effectiveWriteAmp` (≈3 on Cloudflare, ≈4 on Node) is the\n * measured Class A ops/write INCLUDING in-band maintenance — see\n * `docs/spec/attachments/amortized-write-cost-baseline.json`. The\n * old \"× 2\" was the commit FLOOR only and undercounted maintenance.\n * 2. `projectedUsdPerMonth = 0` exactly when both `classAPerMonth\n * ≤ pricing.freeClassAPerMonth` AND `storedBytes ≤\n * pricing.freeStorageGb × 1GB`. Say `$0`, not `$0.00`. `null`\n * for self-hosted/dev (no $ model).\n * 3. Returns `null` when `writesPerMin` is non-finite (no-data case\n * from `estimateWritesPerMin`); inspect renders no footer.\n */\n\n/** R2 / AWS S3 / self-hosted / dev price table. */\nexport interface ProviderPricing {\n readonly provider: \"r2\" | \"aws-s3\" | \"self-hosted\" | \"dev\";\n /** Free-tier Class A ops per month; 0 if no free tier. */\n readonly freeClassAPerMonth: number;\n /** $/1M Class A above free tier. NaN for \"self-hosted\" / \"dev\". */\n readonly usdPerMillionClassA: number;\n /** Free-tier stored GB; 0 if no free tier. */\n readonly freeStorageGb: number;\n /** $/GB-month above free tier. NaN for \"self-hosted\" / \"dev\". */\n readonly usdPerGbMonth: number;\n /**\n * Effective Class A ops per logical write, INCLUDING in-band\n * maintenance (folds + GC) — NOT just the 2-op commit floor.\n * Empirically measured: ~3 on Cloudflare (cf-free profile), ~4 on\n * serverful Node (gcInterval=2 ⇒ ~2× the GC LISTs). Source:\n * docs/spec/attachments/amortized-write-cost-baseline.json (bench\n * `pnpm bench:amortized-write-cost`). Provider is the host proxy:\n * r2 ⇒ Cloudflare ⇒ 3; aws-s3 ⇒ Node ⇒ 4.\n */\n readonly effectiveWriteAmp: number;\n}\n\n/**\n * Graduation triggers — sustained for 7 days, any one of these\n * means the workload has outgrown baerly-storage's positioning.\n *\n * Source: `docs/about/cost-model.md:159-163`.\n */\nexport const GRADUATION_CLASS_A_PER_MONTH = 50_000_000;\n/**\n * Advisory crossing — eyes-open signal, NOT a hard stop.\n *\n * Keyed to a sustained WRITE RATE (100 writes/min, account-wide), not an\n * absolute Class A count, so it fires at the same workload on every\n * provider regardless of write-amp. On R2 (×3) that is ~13M Class A/mo\n * (~$54/mo object-storage ops); on S3 (×4) ~17.3M Class A/mo (~$86/mo).\n * The previous absolute 13M-Class-A threshold was R2-derived and, applied\n * to S3, fired at ~75 writes/min (~$65/mo) while the rendered note quoted\n * the 100-writes/min figure (~$86) — provider-inconsistent. Fires before\n * the 50M hard trigger to surface the ops-vs-cost tradeoff: object storage\n * buys zero ops / no on-call / no migration; a managed DB trades those\n * dollars for a schema, SQL, and an ops surface. Does NOT change the 50M\n * hard trigger.\n */\nexport const GRADUATION_ADVISORY_WRITES_PER_MIN = 100;\n// Storage graduation is a COST SIGNAL at the ~10 GB R2 free-tier line,\n// not a hard trigger — intentionally not represented as a graduation\n// constant. `storedBytes` feeds the dollar projection (storage overage)\n// but the projection surfaces no storage graduation %; the tooling\n// tracks only the 50M Class A/mo trigger. See cost-model.md. (The\n// historic `effective write-amp > 6` trigger is retired — see\n// pricing-log.md 2026-06-22 — and is not represented here either.)\n\n/** What the inspect footer renders from. */\nexport interface Trajectory {\n readonly writesPerMin: number;\n readonly classAPerMonth: number;\n /** Percent of provider's free-tier Class A budget. `null` when the provider has no free tier (aws-s3) or no $ model (self-hosted/dev). */\n readonly percentOfFreeTier: number | null;\n /** Percent of the 50M/mo graduation trigger. Always a finite number. */\n readonly percentOfGraduation: number;\n /** Percent of the 100-writes/min advisory threshold (provider-agnostic). Always a finite number. */\n readonly percentOfAdvisory: number;\n /** Projected USD/month. `0` when fully inside the free tier. `null` when the provider has no $ model (self-hosted/dev). */\n readonly projectedUsdPerMonth: number | null;\n readonly withinFreeTier: boolean;\n readonly provider: ProviderPricing[\"provider\"];\n}\n\n/**\n * Project a `writesPerMin` rate (typically from\n * `estimateWritesPerMin`) into a monthly cost trajectory.\n *\n * Returns `null` when `writesPerMin` is non-finite. The caller\n * (inspect) renders no footer in that case.\n */\nexport const project = (\n writesPerMin: number,\n storedBytes: number,\n pricing: ProviderPricing,\n): Trajectory | null => {\n if (!Number.isFinite(writesPerMin)) {\n return null;\n }\n\n const classAPerMonth = writesPerMin * 60 * 24 * 30 * pricing.effectiveWriteAmp;\n\n const percentOfGraduation = (classAPerMonth / GRADUATION_CLASS_A_PER_MONTH) * 100;\n // Advisory is a write-RATE crossing (provider-agnostic), not an absolute\n // Class A count — so it fires at the same 100 writes/min on R2 and S3\n // alike, rather than at a lower S3 rate where the rendered cost note\n // would be wrong. See GRADUATION_ADVISORY_WRITES_PER_MIN.\n const percentOfAdvisory = (writesPerMin / GRADUATION_ADVISORY_WRITES_PER_MIN) * 100;\n\n const percentOfFreeTier =\n pricing.freeClassAPerMonth > 0 ? (classAPerMonth / pricing.freeClassAPerMonth) * 100 : null;\n\n const storedGb = storedBytes / (1024 * 1024 * 1024);\n const withinFreeTier =\n pricing.freeClassAPerMonth > 0 &&\n classAPerMonth <= pricing.freeClassAPerMonth &&\n storedGb <= pricing.freeStorageGb;\n\n let projectedUsdPerMonth: number | null;\n if (Number.isNaN(pricing.usdPerMillionClassA)) {\n projectedUsdPerMonth = null;\n } else if (withinFreeTier) {\n projectedUsdPerMonth = 0;\n } else {\n const classAOverage = Math.max(0, classAPerMonth - pricing.freeClassAPerMonth);\n const storageOverage = Math.max(0, storedGb - pricing.freeStorageGb);\n projectedUsdPerMonth =\n (classAOverage / 1_000_000) * pricing.usdPerMillionClassA +\n storageOverage * pricing.usdPerGbMonth;\n }\n\n return {\n writesPerMin,\n classAPerMonth,\n percentOfFreeTier,\n percentOfGraduation,\n percentOfAdvisory,\n projectedUsdPerMonth,\n withinFreeTier,\n provider: pricing.provider,\n };\n};\n","/**\n * `baerly cost` — projected cost trajectory for one collection.\n *\n * Sniffs the writes/min rate over the trailing log sample for one\n * collection and projects it into a free-tier-aware monthly Class A\n * + storage cost projection vs. the M-size graduation trigger\n * (50M Class A/mo). Read-only; never mutates anything.\n *\n * Args:\n * --bucket Required. Bucket URI.\n * --app Required (or via baerly.config.ts).\n * --tenant Required (or via baerly.config.ts).\n * --collection Required. Collection name.\n * --provider Optional. r2 | aws-s3 | self-hosted | dev. Overrides\n * the auto-detected provider (bucket URI +\n * BAERLY_S3_ENDPOINT).\n * --json JSON envelope.\n *\n * Cost shape:\n * ceil(logKeys/1000) LIST pages over the log/ prefix (1 for typical\n * logs; more only for deep, uncompacted logs — R2/S3 list pages cap\n * at 1000 keys)\n * + up to 120 GETs for trailing log entries (`SAMPLE_SIZE`)\n *\n * Exit codes:\n * 0 — projection rendered.\n * 1 — InvalidConfig (bad bucket URI, missing args, unknown flag,\n * insufficient log entries to estimate, dev backend).\n * 2 — Storage / Network error.\n * 3 — Protocol invariant (Conflict / Internal / InvalidResponse).\n */\n\nimport { type ArgsDef } from \"citty\";\nimport { BaerlyError } from \"@baerly/protocol\";\nimport { parseBucketUri } from \"./bucket-uri.ts\";\nimport { emitSuccess, isJsonMode } from \"./output.ts\";\nimport { detectProvider, pricingFor, type ProviderTag } from \"./cost/provider.ts\";\nimport { project, type Trajectory } from \"./cost/project.ts\";\nimport { estimateWritesPerMin } from \"./admin/usage.ts\";\nimport {\n APP_ARG,\n assertCollectionArg,\n BUCKET_ARG,\n COLLECTION_ARG,\n defineBaerlySubcommand,\n JSON_ARG,\n TENANT_ARG,\n} from \"./subcommand.ts\";\n\nconst COST_ARGS = {\n bucket: BUCKET_ARG,\n app: APP_ARG,\n tenant: TENANT_ARG,\n collection: COLLECTION_ARG,\n provider: {\n type: \"string\",\n required: false,\n description:\n \"Override pricing provider (r2|aws-s3|self-hosted|dev). Auto-detected from bucket URI + BAERLY_S3_ENDPOINT.\",\n valueHint: \"r2|aws-s3|self-hosted|dev\",\n },\n json: JSON_ARG,\n} as const satisfies ArgsDef;\n\n/** Compact \"1.5M\" / \"22k\" / \"842\" rendering for Class A op counts. */\nconst formatOps = (n: number): string => {\n if (n >= 1_000_000) {\n return `${(n / 1_000_000).toFixed(1)}M`;\n }\n if (n >= 1_000) {\n return `${(n / 1_000).toFixed(0)}k`;\n }\n return n.toFixed(0);\n};\n\n/** Advisory line rendered when past 100 writes/min but under the 50M/mo graduation trigger. */\nconst renderAdvisoryLine = (t: Trajectory): string => {\n if (t.percentOfAdvisory < 100 || t.percentOfGraduation >= 100) {\n return \"\";\n }\n if (t.projectedUsdPerMonth === null) {\n return (\n ` advisory: ~100 writes/min crossed. Object storage buys zero ops, no on-call,\\n` +\n ` no migration; a managed DB trades those dollars for schema + SQL + ops.\\n` +\n ` Hard graduation trigger: 50M Class A/mo. Self-hosted — bill model not modelled.\\n`\n );\n }\n const costNote = t.provider === \"r2\" ? \"~$54/mo on R2\" : \"~$86/mo on S3\";\n return (\n ` advisory: ~100 writes/min crossed (${costNote}, object-storage ops). Object storage buys\\n` +\n ` zero ops, no on-call, and no migration for your bytes. A managed DB trades those\\n` +\n ` dollars for a schema, SQL, and an ops surface. Review if that tradeoff\\n` +\n ` makes sense for your workload. Hard graduation trigger: 50M Class A/mo.\\n`\n );\n};\n\n/** Two-line trajectory block. Three output states per design spec §4.2. */\nconst renderTrajectory = (t: Trajectory): string => {\n const wpm = t.writesPerMin.toFixed(t.writesPerMin < 10 ? 1 : 0);\n const classA = formatOps(t.classAPerMonth);\n // State 2: ops-only — provider known but no $ model. Today only\n // self-hosted reaches this (dev is filtered out upstream).\n if (t.projectedUsdPerMonth === null) {\n const advisory = renderAdvisoryLine(t);\n return [\n ` trajectory: ~${wpm} writes/min → ~${classA} Class A/mo`,\n ` ${t.percentOfGraduation.toFixed(2)}% of 50M/mo graduation trigger. Self-hosted — bill model not modelled.`,\n ...(advisory ? [advisory] : []),\n ].join(\"\\n\");\n }\n // Only \"r2\" can reach withinFreeTier===true (aws-s3 has freeClassAPerMonth: 0).\n // self-hosted/dev are filtered upstream.\n const usd = t.withinFreeTier\n ? `~$0 (R2 free tier)`\n : `~$${t.projectedUsdPerMonth!.toFixed(2)}/mo`;\n // Invariant: withinFreeTier===true implies pricing.freeClassAPerMonth>0,\n // which in turn implies percentOfFreeTier!==null (see project.ts).\n const tail = t.withinFreeTier\n ? `${t.percentOfFreeTier!.toFixed(0)}% of free-tier Class A budget. ${t.percentOfFreeTier! < 50 ? \"Well inside the promise.\" : \"Approaching free-tier ceiling.\"}`\n : `${t.percentOfGraduation.toFixed(2)}% of 50M/mo graduation trigger.`;\n const advisory = renderAdvisoryLine(t);\n return [\n ` trajectory: ~${wpm} writes/min → ~${classA} Class A/mo → ${usd}`,\n ` ${tail}`,\n ...(advisory ? [advisory] : []),\n ].join(\"\\n\");\n};\n\nconst PROVIDER_TAGS: ReadonlySet<string> = new Set([\"r2\", \"aws-s3\", \"self-hosted\", \"dev\"]);\n\nconst bundle = defineBaerlySubcommand({\n name: \"cost\",\n meta: {\n description: \"Project a collection's monthly Class A + storage cost trajectory.\",\n },\n args: COST_ARGS,\n handler: async (args, ctx) => {\n if (typeof args.provider === \"string\" && args.provider.length > 0) {\n if (!PROVIDER_TAGS.has(args.provider)) {\n throw new BaerlyError(\n \"InvalidConfig\",\n `baerly cost: --provider must be one of r2|aws-s3|self-hosted|dev (got ${JSON.stringify(args.provider)})`,\n );\n }\n }\n const bucket = await parseBucketUri(args.bucket);\n const { app, tenant } = await ctx.resolveAppTenant({ app: args.app, tenant: args.tenant });\n assertCollectionArg(args.collection, \"baerly cost\");\n\n const override =\n typeof args.provider === \"string\" && args.provider.length > 0\n ? (args.provider as ProviderTag)\n : undefined;\n const provider = detectProvider({\n bucketUri: args.bucket,\n s3Endpoint: process.env[\"BAERLY_S3_ENDPOINT\"],\n override,\n });\n if (provider === \"dev\") {\n throw new BaerlyError(\n \"InvalidConfig\",\n `baerly cost: dev backends (file://, memory://) have no $ model; pass --provider=r2|aws-s3|self-hosted to project against one.`,\n );\n }\n\n const verdict = await estimateWritesPerMin(bucket.storage, app, tenant, args.collection, {\n keyPrefix: bucket.keyPrefix,\n });\n const trajectory = project(verdict.writesPerMin, 0, pricingFor(provider));\n if (trajectory === null) {\n throw new BaerlyError(\n \"InvalidConfig\",\n `baerly cost: not enough log entries under ${args.collection} to estimate writes/min (need >= 2)`,\n );\n }\n\n if (isJsonMode()) {\n emitSuccess({ command: \"cost\", collection: args.collection, trajectory });\n } else {\n process.stdout.write(`baerly cost ${args.collection}\\n${renderTrajectory(trajectory)}\\n`);\n }\n return 0;\n },\n});\n\n/** citty `defineCommand` block for `baerly cost`. */\nexport const cost = bundle.cmd;\n\n/**\n * Programmatic entry used by tests. Bypasses citty's `run` wrapper\n * (which would call `process.exit` and kill vitest) and returns the\n * integer exit code directly.\n */\nexport const runCost = bundle.run;\n"],"mappings":"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"}
1
+ {"version":3,"file":"cost-_SE_SVgZ.js","names":[],"sources":["../packages/cli/src/cost/provider.ts","../packages/cli/src/cost/project.ts","../packages/cli/src/cost.ts"],"sourcesContent":["/**\n * Provider sniffer: maps a bucket URI + optional S3 endpoint into a\n * pricing tag, and resolves that tag into a `ProviderPricing`\n * record. Pure — zero I/O.\n *\n * Detection rules (first match wins):\n * - `file://*` → \"dev\"\n * - `memory://*` → \"dev\"\n * - `s3://*` + endpoint matching `*.r2.cloudflarestorage.com` → \"r2\"\n * - `s3://*` + endpoint matching `*.amazonaws.com` → \"aws-s3\"\n * - `s3://*` + no endpoint → \"aws-s3\"\n * - everything else (Minio, Backblaze, on-prem, unknown s3 endpoint) → \"self-hosted\"\n *\n * `override` skips detection entirely — used by the\n * `baerly inspect --provider=...` CLI flag when auto-detection picks\n * wrong (e.g., a self-hosted S3 gateway in front of R2).\n */\n\nimport type { ProviderPricing } from \"./project.ts\";\n\nexport type ProviderTag = ProviderPricing[\"provider\"];\n\nexport interface DetectArgs {\n /** Raw bucket URI as passed on the CLI (s3://, file://, memory://). */\n readonly bucketUri: string;\n /** Effective S3 endpoint at parse time (typically `process.env[\"BAERLY_S3_ENDPOINT\"]`). */\n readonly s3Endpoint?: string;\n /** When set, skip detection and return this tag. */\n readonly override?: ProviderTag;\n}\n\nexport const detectProvider = (args: DetectArgs): ProviderTag => {\n if (args.override !== undefined) {\n return args.override;\n }\n if (args.bucketUri.startsWith(\"file://\")) {\n return \"dev\";\n }\n if (args.bucketUri.startsWith(\"memory://\")) {\n return \"dev\";\n }\n if (!args.bucketUri.startsWith(\"s3://\")) {\n return \"self-hosted\";\n }\n // s3:// branch — look at the endpoint.\n const endpoint = args.s3Endpoint ?? \"\";\n if (endpoint === \"\") {\n return \"aws-s3\";\n } // default AWS\n if (/\\.r2\\.cloudflarestorage\\.com(:\\d+)?\\/?$/i.test(endpoint)) {\n return \"r2\";\n }\n if (/\\.amazonaws\\.com(:\\d+)?\\/?$/i.test(endpoint)) {\n return \"aws-s3\";\n }\n return \"self-hosted\";\n};\n\n/**\n * R2 price table.\n * Source: <https://developers.cloudflare.com/r2/pricing/> (review date 2026-05-17).\n * Change-control: pair every edit with a `docs/about/pricing-log.md` entry.\n */\nconst R2_PRICING: ProviderPricing = {\n provider: \"r2\",\n freeClassAPerMonth: 1_000_000,\n usdPerMillionClassA: 4.5,\n freeStorageGb: 10,\n usdPerGbMonth: 0.015,\n effectiveWriteAmp: 3,\n};\n\n/**\n * AWS S3 (Standard) price table.\n * Source: <https://aws.amazon.com/s3/pricing/> (review date 2026-05-17).\n * The 12-month new-account free tier is intentionally excluded\n * (most operators are past it; reporting $0 to them would lie).\n */\nconst AWS_S3_PRICING: ProviderPricing = {\n provider: \"aws-s3\",\n freeClassAPerMonth: 0,\n usdPerMillionClassA: 5,\n freeStorageGb: 0,\n usdPerGbMonth: 0.023,\n effectiveWriteAmp: 4,\n};\n\nconst SELF_HOSTED_PRICING: ProviderPricing = {\n provider: \"self-hosted\",\n freeClassAPerMonth: 0,\n usdPerMillionClassA: Number.NaN,\n freeStorageGb: 0,\n usdPerGbMonth: Number.NaN,\n effectiveWriteAmp: 4,\n};\n\nconst DEV_PRICING: ProviderPricing = {\n provider: \"dev\",\n freeClassAPerMonth: 0,\n usdPerMillionClassA: Number.NaN,\n freeStorageGb: 0,\n usdPerGbMonth: Number.NaN,\n effectiveWriteAmp: 4,\n};\n\nexport const pricingFor = (provider: ProviderTag): ProviderPricing => {\n switch (provider) {\n case \"r2\": {\n return R2_PRICING;\n }\n case \"aws-s3\": {\n return AWS_S3_PRICING;\n }\n case \"self-hosted\": {\n return SELF_HOSTED_PRICING;\n }\n case \"dev\": {\n return DEV_PRICING;\n }\n }\n};\n","/**\n * Pure projection math for the `baerly inspect` cost-trajectory\n * footer. Zero I/O. Price tables live as top-level constants; every\n * change MUST be paired with a `docs/about/pricing-log.md` entry.\n *\n * Three rules:\n * 1. `classAPerMonth = writesPerMin × 60 × 24 × 30 × effectiveWriteAmp`\n * where `effectiveWriteAmp` (≈3 on Cloudflare, ≈4 on Node) is the\n * measured Class A ops/write INCLUDING in-band maintenance — see\n * `docs/spec/attachments/amortized-write-cost-baseline.json`. The\n * old \"× 2\" was the commit FLOOR only and undercounted maintenance.\n * 2. `projectedUsdPerMonth = 0` exactly when both `classAPerMonth\n * ≤ pricing.freeClassAPerMonth` AND `storedBytes ≤\n * pricing.freeStorageGb × 1GB`. Say `$0`, not `$0.00`. `null`\n * for self-hosted/dev (no $ model).\n * 3. Returns `null` when `writesPerMin` is non-finite (no-data case\n * from `estimateWritesPerMin`); inspect renders no footer.\n */\n\n/** R2 / AWS S3 / self-hosted / dev price table. */\nexport interface ProviderPricing {\n readonly provider: \"r2\" | \"aws-s3\" | \"self-hosted\" | \"dev\";\n /** Free-tier Class A ops per month; 0 if no free tier. */\n readonly freeClassAPerMonth: number;\n /** $/1M Class A above free tier. NaN for \"self-hosted\" / \"dev\". */\n readonly usdPerMillionClassA: number;\n /** Free-tier stored GB; 0 if no free tier. */\n readonly freeStorageGb: number;\n /** $/GB-month above free tier. NaN for \"self-hosted\" / \"dev\". */\n readonly usdPerGbMonth: number;\n /**\n * Effective Class A ops per logical write, INCLUDING in-band\n * maintenance (folds + GC) — NOT just the 2-op commit floor.\n * Empirically measured: ~3 on Cloudflare (cf-free profile), ~4 on\n * serverful Node (gcInterval=2 ⇒ ~2× the GC LISTs). Source:\n * docs/spec/attachments/amortized-write-cost-baseline.json (bench\n * `pnpm bench:amortized-write-cost`). Provider is the host proxy:\n * r2 ⇒ Cloudflare ⇒ 3; aws-s3 ⇒ Node ⇒ 4.\n */\n readonly effectiveWriteAmp: number;\n}\n\n/**\n * Graduation triggers — sustained for 7 days, any one of these\n * means the workload has outgrown baerly-storage's positioning.\n *\n * Source: `docs/about/cost-model.md:159-163`.\n */\nexport const GRADUATION_CLASS_A_PER_MONTH = 50_000_000;\n/**\n * Advisory crossing — eyes-open signal, NOT a hard stop.\n *\n * Keyed to a sustained WRITE RATE (100 writes/min, account-wide), not an\n * absolute Class A count, so it fires at the same workload on every\n * provider regardless of write-amp. On R2 (×3) that is ~13M Class A/mo\n * (~$54/mo object-storage ops); on S3 (×4) ~17.3M Class A/mo (~$86/mo).\n * The previous absolute 13M-Class-A threshold was R2-derived and, applied\n * to S3, fired at ~75 writes/min (~$65/mo) while the rendered note quoted\n * the 100-writes/min figure (~$86) — provider-inconsistent. Fires before\n * the 50M hard trigger to surface the ops-vs-cost tradeoff: object storage\n * buys zero ops / no on-call / no migration; a managed DB trades those\n * dollars for a schema, SQL, and an ops surface. Does NOT change the 50M\n * hard trigger.\n */\nexport const GRADUATION_ADVISORY_WRITES_PER_MIN = 100;\n// Storage graduation is a COST SIGNAL at the ~10 GB R2 free-tier line,\n// not a hard trigger — intentionally not represented as a graduation\n// constant. `storedBytes` feeds the dollar projection (storage overage)\n// but the projection surfaces no storage graduation %; the tooling\n// tracks only the 50M Class A/mo trigger. See cost-model.md. (The\n// historic `effective write-amp > 6` trigger is retired — see\n// pricing-log.md 2026-06-22 — and is not represented here either.)\n\n/** What the inspect footer renders from. */\nexport interface Trajectory {\n readonly writesPerMin: number;\n readonly classAPerMonth: number;\n /** Percent of provider's free-tier Class A budget. `null` when the provider has no free tier (aws-s3) or no $ model (self-hosted/dev). */\n readonly percentOfFreeTier: number | null;\n /** Percent of the 50M/mo graduation trigger. Always a finite number. */\n readonly percentOfGraduation: number;\n /** Percent of the 100-writes/min advisory threshold (provider-agnostic). Always a finite number. */\n readonly percentOfAdvisory: number;\n /** Projected USD/month. `0` when fully inside the free tier. `null` when the provider has no $ model (self-hosted/dev). */\n readonly projectedUsdPerMonth: number | null;\n readonly withinFreeTier: boolean;\n readonly provider: ProviderPricing[\"provider\"];\n}\n\n/**\n * Project a `writesPerMin` rate (typically from\n * `estimateWritesPerMin`) into a monthly cost trajectory.\n *\n * Returns `null` when `writesPerMin` is non-finite. The caller\n * (inspect) renders no footer in that case.\n */\nexport const project = (\n writesPerMin: number,\n storedBytes: number,\n pricing: ProviderPricing,\n): Trajectory | null => {\n if (!Number.isFinite(writesPerMin)) {\n return null;\n }\n\n const classAPerMonth = writesPerMin * 60 * 24 * 30 * pricing.effectiveWriteAmp;\n\n const percentOfGraduation = (classAPerMonth / GRADUATION_CLASS_A_PER_MONTH) * 100;\n // Advisory is a write-RATE crossing (provider-agnostic), not an absolute\n // Class A count — so it fires at the same 100 writes/min on R2 and S3\n // alike, rather than at a lower S3 rate where the rendered cost note\n // would be wrong. See GRADUATION_ADVISORY_WRITES_PER_MIN.\n const percentOfAdvisory = (writesPerMin / GRADUATION_ADVISORY_WRITES_PER_MIN) * 100;\n\n const percentOfFreeTier =\n pricing.freeClassAPerMonth > 0 ? (classAPerMonth / pricing.freeClassAPerMonth) * 100 : null;\n\n const storedGb = storedBytes / (1024 * 1024 * 1024);\n const withinFreeTier =\n pricing.freeClassAPerMonth > 0 &&\n classAPerMonth <= pricing.freeClassAPerMonth &&\n storedGb <= pricing.freeStorageGb;\n\n let projectedUsdPerMonth: number | null;\n if (Number.isNaN(pricing.usdPerMillionClassA)) {\n projectedUsdPerMonth = null;\n } else if (withinFreeTier) {\n projectedUsdPerMonth = 0;\n } else {\n const classAOverage = Math.max(0, classAPerMonth - pricing.freeClassAPerMonth);\n const storageOverage = Math.max(0, storedGb - pricing.freeStorageGb);\n projectedUsdPerMonth =\n (classAOverage / 1_000_000) * pricing.usdPerMillionClassA +\n storageOverage * pricing.usdPerGbMonth;\n }\n\n return {\n writesPerMin,\n classAPerMonth,\n percentOfFreeTier,\n percentOfGraduation,\n percentOfAdvisory,\n projectedUsdPerMonth,\n withinFreeTier,\n provider: pricing.provider,\n };\n};\n","/**\n * `baerly cost` — projected cost trajectory for one collection.\n *\n * Sniffs the writes/min rate over the trailing log sample for one\n * collection and projects it into a free-tier-aware monthly Class A\n * + storage cost projection vs. the M-size graduation trigger\n * (50M Class A/mo). Read-only; never mutates anything.\n *\n * Args:\n * --bucket Required. Bucket URI.\n * --app Required (or via baerly.config.ts).\n * --tenant Required (or via baerly.config.ts).\n * --collection Required. Collection name.\n * --provider Optional. r2 | aws-s3 | self-hosted | dev. Overrides\n * the auto-detected provider (bucket URI +\n * BAERLY_S3_ENDPOINT).\n * --json JSON envelope.\n *\n * Cost shape:\n * ceil(logKeys/1000) LIST pages over the log/ prefix (1 for typical\n * logs; more only for deep, uncompacted logs — R2/S3 list pages cap\n * at 1000 keys)\n * + up to 120 GETs for trailing log entries (`SAMPLE_SIZE`)\n *\n * Exit codes:\n * 0 — projection rendered.\n * 1 — InvalidConfig (bad bucket URI, missing args, unknown flag,\n * insufficient log entries to estimate, dev backend).\n * 2 — Storage / Network error.\n * 3 — Protocol invariant (Conflict / Internal / InvalidResponse).\n */\n\nimport { type ArgsDef } from \"citty\";\nimport { BaerlyError } from \"@baerly/protocol\";\nimport { parseBucketUri } from \"./bucket-uri.ts\";\nimport { emitSuccess, isJsonMode } from \"./output.ts\";\nimport { detectProvider, pricingFor, type ProviderTag } from \"./cost/provider.ts\";\nimport { project, type Trajectory } from \"./cost/project.ts\";\nimport { estimateWritesPerMin } from \"./admin/usage.ts\";\nimport {\n APP_ARG,\n assertCollectionArg,\n BUCKET_ARG,\n COLLECTION_ARG,\n defineBaerlySubcommand,\n JSON_ARG,\n TENANT_ARG,\n} from \"./subcommand.ts\";\n\nconst COST_ARGS = {\n bucket: BUCKET_ARG,\n app: APP_ARG,\n tenant: TENANT_ARG,\n collection: COLLECTION_ARG,\n provider: {\n type: \"string\",\n required: false,\n description:\n \"Override pricing provider (r2|aws-s3|self-hosted|dev). Auto-detected from bucket URI + BAERLY_S3_ENDPOINT.\",\n valueHint: \"r2|aws-s3|self-hosted|dev\",\n },\n json: JSON_ARG,\n} as const satisfies ArgsDef;\n\n/** Compact \"1.5M\" / \"22k\" / \"842\" rendering for Class A op counts. */\nconst formatOps = (n: number): string => {\n if (n >= 1_000_000) {\n return `${(n / 1_000_000).toFixed(1)}M`;\n }\n if (n >= 1_000) {\n return `${(n / 1_000).toFixed(0)}k`;\n }\n return n.toFixed(0);\n};\n\n/** Advisory line rendered when past 100 writes/min but under the 50M/mo graduation trigger. */\nconst renderAdvisoryLine = (t: Trajectory): string => {\n if (t.percentOfAdvisory < 100 || t.percentOfGraduation >= 100) {\n return \"\";\n }\n if (t.projectedUsdPerMonth === null) {\n return (\n ` advisory: ~100 writes/min crossed. Object storage buys zero ops, no on-call,\\n` +\n ` no migration; a managed DB trades those dollars for schema + SQL + ops.\\n` +\n ` Hard graduation trigger: 50M Class A/mo. Self-hosted — bill model not modelled.\\n`\n );\n }\n const costNote = t.provider === \"r2\" ? \"~$54/mo on R2\" : \"~$86/mo on S3\";\n return (\n ` advisory: ~100 writes/min crossed (${costNote}, object-storage ops). Object storage buys\\n` +\n ` zero ops, no on-call, and no migration for your bytes. A managed DB trades those\\n` +\n ` dollars for a schema, SQL, and an ops surface. Review if that tradeoff\\n` +\n ` makes sense for your workload. Hard graduation trigger: 50M Class A/mo.\\n`\n );\n};\n\n/** Two-line trajectory block. Three output states per design spec §4.2. */\nconst renderTrajectory = (t: Trajectory): string => {\n const wpm = t.writesPerMin.toFixed(t.writesPerMin < 10 ? 1 : 0);\n const classA = formatOps(t.classAPerMonth);\n // State 2: ops-only — provider known but no $ model. Today only\n // self-hosted reaches this (dev is filtered out upstream).\n if (t.projectedUsdPerMonth === null) {\n const advisory = renderAdvisoryLine(t);\n return [\n ` trajectory: ~${wpm} writes/min → ~${classA} Class A/mo`,\n ` ${t.percentOfGraduation.toFixed(2)}% of 50M/mo graduation trigger. Self-hosted — bill model not modelled.`,\n ...(advisory ? [advisory] : []),\n ].join(\"\\n\");\n }\n // Only \"r2\" can reach withinFreeTier===true (aws-s3 has freeClassAPerMonth: 0).\n // self-hosted/dev are filtered upstream.\n const usd = t.withinFreeTier\n ? `~$0 (R2 free tier)`\n : `~$${t.projectedUsdPerMonth!.toFixed(2)}/mo`;\n // Invariant: withinFreeTier===true implies pricing.freeClassAPerMonth>0,\n // which in turn implies percentOfFreeTier!==null (see project.ts).\n const tail = t.withinFreeTier\n ? `${t.percentOfFreeTier!.toFixed(0)}% of free-tier Class A budget. ${t.percentOfFreeTier! < 50 ? \"Well inside the promise.\" : \"Approaching free-tier ceiling.\"}`\n : `${t.percentOfGraduation.toFixed(2)}% of 50M/mo graduation trigger.`;\n const advisory = renderAdvisoryLine(t);\n return [\n ` trajectory: ~${wpm} writes/min → ~${classA} Class A/mo → ${usd}`,\n ` ${tail}`,\n ...(advisory ? [advisory] : []),\n ].join(\"\\n\");\n};\n\nconst PROVIDER_TAGS: ReadonlySet<string> = new Set([\"r2\", \"aws-s3\", \"self-hosted\", \"dev\"]);\n\nconst bundle = defineBaerlySubcommand({\n name: \"cost\",\n meta: {\n description: \"Project a collection's monthly Class A + storage cost trajectory.\",\n },\n args: COST_ARGS,\n handler: async (args, ctx) => {\n if (typeof args.provider === \"string\" && args.provider.length > 0) {\n if (!PROVIDER_TAGS.has(args.provider)) {\n throw new BaerlyError(\n \"InvalidConfig\",\n `baerly cost: --provider must be one of r2|aws-s3|self-hosted|dev (got ${JSON.stringify(args.provider)})`,\n );\n }\n }\n const bucket = await parseBucketUri(args.bucket);\n const { app, tenant } = await ctx.resolveAppTenant({ app: args.app, tenant: args.tenant });\n assertCollectionArg(args.collection, \"baerly cost\");\n\n const override =\n typeof args.provider === \"string\" && args.provider.length > 0\n ? (args.provider as ProviderTag)\n : undefined;\n const provider = detectProvider({\n bucketUri: args.bucket,\n s3Endpoint: process.env[\"BAERLY_S3_ENDPOINT\"],\n override,\n });\n if (provider === \"dev\") {\n throw new BaerlyError(\n \"InvalidConfig\",\n `baerly cost: dev backends (file://, memory://) have no $ model; pass --provider=r2|aws-s3|self-hosted to project against one.`,\n );\n }\n\n const verdict = await estimateWritesPerMin(bucket.storage, app, tenant, args.collection, {\n keyPrefix: bucket.keyPrefix,\n });\n const trajectory = project(verdict.writesPerMin, 0, pricingFor(provider));\n if (trajectory === null) {\n throw new BaerlyError(\n \"InvalidConfig\",\n `baerly cost: not enough log entries under ${args.collection} to estimate writes/min (need >= 2)`,\n );\n }\n\n if (isJsonMode()) {\n emitSuccess({ command: \"cost\", collection: args.collection, trajectory });\n } else {\n process.stdout.write(`baerly cost ${args.collection}\\n${renderTrajectory(trajectory)}\\n`);\n }\n return 0;\n },\n});\n\n/** citty `defineCommand` block for `baerly cost`. */\nexport const cost = bundle.cmd;\n\n/**\n * Programmatic entry used by tests. Bypasses citty's `run` wrapper\n * (which would call `process.exit` and kill vitest) and returns the\n * integer exit code directly.\n */\nexport const runCost = bundle.run;\n"],"mappings":"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"}
@@ -1,5 +1,5 @@
1
1
  import { a as CollectionNames, d as IndexDefinition, f as DocumentData, o as RowOf, r as BaerlyConfig, s as UnboundConfig, u as SchemaValidator } from "./app-config-DyiFK3_k.js";
2
- import { f as CurrentJsonRead, n as LogEntry, o as Collection, p as Storage } from "./index-BYk9oCNf.js";
2
+ import { f as CurrentJsonRead, n as LogEntry, o as Collection, p as Storage } from "./index-CEZKQsKt.js";
3
3
  //#region packages/server/src/schema.d.ts
4
4
  /**
5
5
  * Run a validator and throw `BaerlyError{code:"SchemaError"}` on failure.
@@ -251,4 +251,4 @@ declare class Db<TConfig extends BaerlyConfig = UnboundConfig> {
251
251
  }
252
252
  //#endregion
253
253
  export { validateOrThrow as n, Db as t };
254
- //# sourceMappingURL=db-DsPkOVEH.d.ts.map
254
+ //# sourceMappingURL=db-DjjthkTi.d.ts.map
@@ -1,5 +1,5 @@
1
- import { t as loadAppConfig } from "./config-1tv0-Yzm.js";
2
- import { t as deployCloudflare } from "./cloudflare-DzKBrUlg.js";
1
+ import { t as loadAppConfig } from "./config-B6nTy8e2.js";
2
+ import { t as deployCloudflare } from "./cloudflare-wrVYf4bb.js";
3
3
  import { a as setJsonMode, n as emitError, o as BaerlyError, r as emitSuccess, s as defineCommand } from "./baerly.js";
4
4
  //#region src/deploy.ts
5
5
  /**
@@ -31,8 +31,8 @@ const DEPLOY_ARGS = {
31
31
  },
32
32
  probeBucket: {
33
33
  type: "string",
34
- description: "Run a live CAS preflight against this bucket URI before deploying (s3://, file:///, memory://); aborts non-zero if the backend fails the conditional-write / exactly-one-winner probe. Same check as `baerly doctor --bucket`.",
35
- valueHint: "s3://bucket/prefix"
34
+ description: "Run a live CAS preflight against this bucket URI before deploying (s3://, gcs://, file:///, memory://); aborts non-zero if the backend fails the conditional-write / exactly-one-winner probe. Same CAS check as `baerly doctor --bucket` (doctor additionally runs GCS cost advisories).",
35
+ valueHint: "s3://bucket/prefix | gcs://bucket"
36
36
  }
37
37
  };
38
38
  const KNOWN_KEYS = /* @__PURE__ */ new Set([
@@ -87,4 +87,4 @@ const deploy = defineCommand({
87
87
  //#endregion
88
88
  export { deploy };
89
89
 
90
- //# sourceMappingURL=deploy-DonTr-CV.js.map
90
+ //# sourceMappingURL=deploy-Di_Q01qx.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"deploy-Di_Q01qx.js","names":[],"sources":["../packages/cli/src/deploy.ts"],"sourcesContent":["/**\n * `baerly deploy` — citty dispatcher.\n *\n * Reads `baerly.config.ts:target` and routes to the matching\n * deploy backend. Today: `cloudflare` only — the `node` example\n * embodies its deployment shape directly (self-host via `node\n * server.js` after your PaaS or container build), so `baerly\n * deploy` rejects `target: \"node\"` with an actionable InvalidConfig.\n *\n * Exit-code contract (standard CLI shape):\n * - 0 success.\n * - 1 user error (InvalidConfig, missing config, unknown target).\n * - 2 storage / external error (NetworkError, Wrangler returned\n * non-zero, anything non-BaerlyError).\n * - 3 protocol invariant (Conflict, Internal, InvalidResponse —\n * should not happen here unless someone hand-edited mid-flight).\n */\n\nimport { defineCommand, type ArgsDef, type ParsedArgs } from \"citty\";\nimport { BaerlyError } from \"@baerly/protocol\";\nimport { loadAppConfig } from \"./config.ts\";\nimport { deployCloudflare } from \"./deploy/cloudflare.ts\";\nimport { emitError, emitSuccess, setJsonMode } from \"./output.ts\";\n\nconst DEPLOY_ARGS = {\n target: {\n type: \"string\",\n description:\n 'Override `baerly.config.ts:target`. Only \"cloudflare\" supported (\"node\" self-deploys via your PaaS or container build).',\n valueHint: \"cloudflare\",\n },\n json: {\n type: \"boolean\",\n description: \"Emit a structured JSON envelope to stdout (success) or stderr (error)\",\n },\n probeBucket: {\n type: \"string\",\n description:\n \"Run a live CAS preflight against this bucket URI before deploying (s3://, gcs://, file:///, memory://); aborts non-zero if the backend fails the conditional-write / exactly-one-winner probe. Same CAS check as `baerly doctor --bucket` (doctor additionally runs GCS cost advisories).\",\n valueHint: \"s3://bucket/prefix | gcs://bucket\",\n },\n} as const satisfies ArgsDef;\n\nconst KNOWN_KEYS: ReadonlySet<string> = new Set([\n \"target\",\n \"json\",\n \"probeBucket\",\n \"probe-bucket\",\n \"_\",\n]);\n\nconst errorToExitCode = (code: string): number => {\n if (code === \"InvalidConfig\") {\n return 1;\n }\n if (code === \"Conflict\" || code === \"Internal\" || code === \"InvalidResponse\") {\n return 3;\n }\n return 2;\n};\n\nconst handleDeploy = async (args: ParsedArgs<typeof DEPLOY_ARGS>): Promise<number> => {\n setJsonMode(args.json === true);\n try {\n for (const k of Object.keys(args)) {\n if (!KNOWN_KEYS.has(k)) {\n throw new BaerlyError(\"InvalidConfig\", `baerly deploy: unknown flag --${k}`);\n }\n }\n const config = await loadAppConfig();\n const target = args.target ?? config.target;\n if (target === \"cloudflare\") {\n const probeBucketUri =\n typeof args.probeBucket === \"string\" && args.probeBucket.length > 0\n ? args.probeBucket\n : undefined;\n const exit = await deployCloudflare(config, { probeBucketUri });\n if (exit === 0) {\n emitSuccess({ command: \"deploy\", status: \"ok\", target });\n }\n return exit;\n }\n throw new BaerlyError(\n \"InvalidConfig\",\n `baerly deploy: target ${JSON.stringify(target)} has no deploy backend. ` +\n `Self-host: \\`node server.js\\` after your PaaS or container build. ` +\n `Cloudflare Workers is the only managed deploy backend today.`,\n );\n } catch (error) {\n if (error instanceof BaerlyError) {\n emitError(\"deploy\", error.code, error.message);\n return errorToExitCode(error.code);\n }\n emitError(\"deploy\", \"Unknown\", (error as Error).message);\n return 2;\n }\n};\n\n/** citty `defineCommand` block for `baerly deploy`. */\nexport const deploy = defineCommand({\n meta: {\n name: \"deploy\",\n description: \"Deploy this baerly app. Dispatches by baerly.config.ts:target.\",\n },\n args: DEPLOY_ARGS,\n run: async ({ args }) => {\n const code = await handleDeploy(args);\n if (code !== 0) {\n process.exit(code);\n }\n },\n});\n\n/**\n * Programmatic entry used by tests. Bypasses citty's `run` wrapper\n * (which would call `process.exit` and kill vitest) and returns the\n * integer exit code directly.\n */\nexport const runDeploy = async (argv: readonly string[]): Promise<number> => {\n const { parseArgs } = await import(\"citty\");\n let parsed: ParsedArgs<typeof DEPLOY_ARGS>;\n try {\n parsed = parseArgs<typeof DEPLOY_ARGS>(argv as string[], DEPLOY_ARGS);\n } catch (error) {\n setJsonMode(argv.includes(\"--json\"));\n emitError(\"deploy\", \"InvalidConfig\", (error as Error).message);\n return 1;\n }\n return handleDeploy(parsed);\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAwBA,MAAM,cAAc;CAClB,QAAQ;EACN,MAAM;EACN,aACE;EACF,WAAW;CACb;CACA,MAAM;EACJ,MAAM;EACN,aAAa;CACf;CACA,aAAa;EACX,MAAM;EACN,aACE;EACF,WAAW;CACb;AACF;AAEA,MAAM,6BAAkC,IAAI,IAAI;CAC9C;CACA;CACA;CACA;CACA;AACF,CAAC;AAED,MAAM,mBAAmB,SAAyB;CAChD,IAAI,SAAS,iBACX,OAAO;CAET,IAAI,SAAS,cAAc,SAAS,cAAc,SAAS,mBACzD,OAAO;CAET,OAAO;AACT;AAEA,MAAM,eAAe,OAAO,SAA0D;CACpF,YAAY,KAAK,SAAS,IAAI;CAC9B,IAAI;EACF,KAAK,MAAM,KAAK,OAAO,KAAK,IAAI,GAC9B,IAAI,CAAC,WAAW,IAAI,CAAC,GACnB,MAAM,IAAI,YAAY,iBAAiB,iCAAiC,GAAG;EAG/E,MAAM,SAAS,MAAM,cAAc;EACnC,MAAM,SAAS,KAAK,UAAU,OAAO;EACrC,IAAI,WAAW,cAAc;GAK3B,MAAM,OAAO,MAAM,iBAAiB,QAAQ,EAAE,gBAH5C,OAAO,KAAK,gBAAgB,YAAY,KAAK,YAAY,SAAS,IAC9D,KAAK,cACL,KAAA,EACuD,CAAC;GAC9D,IAAI,SAAS,GACX,YAAY;IAAE,SAAS;IAAU,QAAQ;IAAM;GAAO,CAAC;GAEzD,OAAO;EACT;EACA,MAAM,IAAI,YACR,iBACA,yBAAyB,KAAK,UAAU,MAAM,EAAE,uJAGlD;CACF,SAAS,OAAO;EACd,IAAI,iBAAiB,aAAa;GAChC,UAAU,UAAU,MAAM,MAAM,MAAM,OAAO;GAC7C,OAAO,gBAAgB,MAAM,IAAI;EACnC;EACA,UAAU,UAAU,WAAY,MAAgB,OAAO;EACvD,OAAO;CACT;AACF;;AAGA,MAAa,SAAS,cAAc;CAClC,MAAM;EACJ,MAAM;EACN,aAAa;CACf;CACA,MAAM;CACN,KAAK,OAAO,EAAE,WAAW;EACvB,MAAM,OAAO,MAAM,aAAa,IAAI;EACpC,IAAI,SAAS,GACX,QAAQ,KAAK,IAAI;CAErB;AACF,CAAC"}
@@ -1,7 +1,7 @@
1
1
  import { n as BaerlyAppConfig } from "./app-config-DyiFK3_k.js";
2
- import { r as Verifier } from "./index-BYk9oCNf.js";
2
+ import { r as Verifier } from "./index-CEZKQsKt.js";
3
3
  import { t as DevBannerHint } from "./dev-banner-CWHIk8tH.js";
4
- import { t as Db } from "./db-DsPkOVEH.js";
4
+ import { t as Db } from "./db-DjjthkTi.js";
5
5
  import { Plugin } from "vite";
6
6
 
7
7
  //#region packages/dev/src/vite-plugin.d.ts
@@ -11,8 +11,29 @@ interface BaerlyDevOptions {
11
11
  * table set (`Object.keys(config.collections)`) are derived from it.
12
12
  * Per-collection schemas/indexes flow through to the in-process
13
13
  * listener the same way `baerlyNode` / `baerlyWorker` pipe them.
14
+ *
15
+ * **Optional.** If omitted, the config is loaded at dev-server startup
16
+ * from `configPath`, or — if that's also omitted — by convention from
17
+ * `<viteRoot>/src/baerly.config.ts`.
18
+ *
19
+ * Prefer omitting it (convention or `configPath`). Passing the object
20
+ * means the caller's `vite.config` must `import` the config module,
21
+ * which forces Nx's `@nx/vite` / `@nx/vitest` inference plugins to
22
+ * bundle that module — and its transitive imports — while creating the
23
+ * project graph. That pulls unresolved imports into the config bundle
24
+ * and forces the app into the root `nx.json` inference-exclusion lists.
25
+ * Letting `baerlyDev` load the config itself (below) keeps the caller's
26
+ * `vite.config` import-free, the same way `reactRouter()` loads
27
+ * `react-router.config.ts` by convention.
14
28
  */
15
- readonly config: BaerlyAppConfig;
29
+ readonly config?: BaerlyAppConfig;
30
+ /**
31
+ * Absolute path to the `baerly.config` module (its default export is
32
+ * the `BaerlyAppConfig`). Loaded lazily via Vite's `ssrLoadModule` at
33
+ * dev-server startup. Overrides the `<viteRoot>/src/baerly.config.ts`
34
+ * convention. Ignored when `config` is provided.
35
+ */
36
+ readonly configPath?: string;
16
37
  /**
17
38
  * Shared-secret token. **Optional.** Required only when
18
39
  * `config.auth === "shared-secret"` and `verifier` is unset — in
@@ -24,9 +45,13 @@ interface BaerlyDevOptions {
24
45
  * when `verifier` is supplied (the operator owns the auth seam).
25
46
  *
26
47
  * Throwing the symmetric `InvalidConfig` on a misconfig matches
27
- * production behaviour: forgetting `SHARED_SECRET` in dev fails
28
- * fast at `vite dev` startup with the same locked wording the
29
- * adapter would emit.
48
+ * production behaviour: forgetting `SHARED_SECRET` in dev throws
49
+ * with the same locked wording the adapter would emit. With an
50
+ * explicit `config` object this fails fast at `vite dev` startup
51
+ * (factory-time resolution); when the config is loaded lazily
52
+ * (`configPath` / convention) the throw is deferred to dev-server
53
+ * startup and surfaces as a per-request 503 rather than aborting
54
+ * the Vite process.
30
55
  */
31
56
  readonly secret?: string;
32
57
  /**
@@ -123,27 +148,6 @@ declare function baerlyDevAuth(opts: BaerlyDevAuthOptions): Plugin;
123
148
  * ```
124
149
  */
125
150
  declare function loadDevVars<K extends string>(path: string, ...keys: readonly K[]): Record<K, string | undefined>;
126
- /**
127
- * Resolution order for the in-process verifier (mirrors
128
- * `baerlyNode` / `baerlyWorker`):
129
- *
130
- * 1. `opts.verifier` set → use as-is.
131
- * 2. else `opts.config.auth === "shared-secret"` → require
132
- * `opts.secret`; build `sharedSecret({ secret, tenantPrefix:
133
- * config.tenant })`. Throws `BaerlyError("InvalidConfig", ...)`
134
- * at Vite startup when `opts.secret` is empty/unset — same
135
- * locked wording the production adapter would emit.
136
- * 3. else `opts.config.auth === "none"` → pin every request to
137
- * `config.tenant`; no header check.
138
- *
139
- * Bearer injection on `/v1/*` only fires in branch 2 (and only when
140
- * branch 1 didn't win) — the dev convenience that lets the SPA call
141
- * the listener without putting the secret in the browser bundle.
142
- * Branch 3 leaves the `Authorization` header alone.
143
- *
144
- * Verifier resolution happens eagerly at factory time so a misconfig
145
- * fails Vite startup, not the first `/v1/*` round-trip.
146
- */
147
151
  declare function baerlyDev(opts: BaerlyDevOptions): Plugin;
148
152
  //#endregion
149
153
  export { BaerlyDevAuthOptions, BaerlyDevOptions, baerlyDev, baerlyDevAuth, loadDevVars };
package/dist/dev-vite.js CHANGED
@@ -1,5 +1,6 @@
1
- import { n as resolveVerifier, t as Db } from "./src-CYHFDrKz.js";
2
- import { n as getRequestListener, t as baerlyNode } from "./src-BL_JoPTn.js";
1
+ import { t as BaerlyError } from "./errors-Dfa3p78c.js";
2
+ import { n as resolveVerifier, t as Db } from "./src-DvbTEya2.js";
3
+ import { n as getRequestListener, t as baerlyNode } from "./src-BMFfDUI2.js";
3
4
  import { i as printDevBanner, n as ensureTable, t as LocalFsStorage } from "./src-DYZ4H1aF.js";
4
5
  import { resolve } from "node:path";
5
6
  import { existsSync, readFileSync } from "node:fs";
@@ -128,12 +129,12 @@ function loadDevVars(path, ...keys) {
128
129
  * `baerlyNode` / `baerlyWorker`):
129
130
  *
130
131
  * 1. `opts.verifier` set → use as-is.
131
- * 2. else `opts.config.auth === "shared-secret"` → require
132
+ * 2. else `config.auth === "shared-secret"` → require
132
133
  * `opts.secret`; build `sharedSecret({ secret, tenantPrefix:
133
134
  * config.tenant })`. Throws `BaerlyError("InvalidConfig", ...)`
134
- * at Vite startup when `opts.secret` is empty/unset — same
135
- * locked wording the production adapter would emit.
136
- * 3. else `opts.config.auth === "none"` → pin every request to
135
+ * when `opts.secret` is empty/unset — same locked wording the
136
+ * production adapter would emit.
137
+ * 3. else `config.auth === "none"` → pin every request to
137
138
  * `config.tenant`; no header check.
138
139
  *
139
140
  * Bearer injection on `/v1/*` only fires in branch 2 (and only when
@@ -141,24 +142,45 @@ function loadDevVars(path, ...keys) {
141
142
  * the listener without putting the secret in the browser bundle.
142
143
  * Branch 3 leaves the `Authorization` header alone.
143
144
  *
144
- * Verifier resolution happens eagerly at factory time so a misconfig
145
- * fails Vite startup, not the first `/v1/*` round-trip.
145
+ * When an explicit `config` object is passed, verifier resolution happens
146
+ * eagerly at factory time so a misconfig fails Vite startup, not the first
147
+ * `/v1/*` round-trip. When the config is loaded lazily (`configPath` or the
148
+ * `<viteRoot>/src/baerly.config.ts` convention), that resolution is deferred
149
+ * to dev-server startup, once the config is available.
146
150
  */
151
+ function resolveAuth(opts, config) {
152
+ return {
153
+ verifier: resolveVerifier({
154
+ factoryVerifier: opts.verifier,
155
+ config,
156
+ readEnv: (k) => k === "SHARED_SECRET" ? opts.secret : process.env[k]
157
+ }),
158
+ bearerForInjection: opts.verifier === void 0 && config.auth === "shared-secret" ? opts.secret : void 0
159
+ };
160
+ }
147
161
  function baerlyDev(opts) {
148
- const verifier = resolveVerifier({
149
- factoryVerifier: opts.verifier,
150
- config: opts.config,
151
- readEnv: (k) => k === "SHARED_SECRET" ? opts.secret : process.env[k]
152
- });
153
- const bearerForInjection = opts.verifier === void 0 && opts.config.auth === "shared-secret" ? opts.secret : void 0;
162
+ const eagerAuth = opts.config !== void 0 ? resolveAuth(opts, opts.config) : void 0;
163
+ let markSettled;
154
164
  return {
155
165
  name: "baerly-dev",
156
166
  apply: "serve",
167
+ api: { whenSettled: new Promise((settle) => {
168
+ markSettled = settle;
169
+ }) },
157
170
  configureServer(server) {
158
- const app = opts.config.app;
159
- const tenant = opts.config.tenant;
160
- const tables = Object.keys(opts.config.collections);
161
171
  const ready = (async () => {
172
+ let config;
173
+ if (opts.config !== void 0) config = opts.config;
174
+ else {
175
+ const configPath = opts.configPath ?? resolve(server.config.root, "src/baerly.config.ts");
176
+ const mod = await server.ssrLoadModule(configPath);
177
+ if (typeof mod.default !== "object" || mod.default === null) throw new BaerlyError("InvalidConfig", `baerly-dev: ${configPath} must default-export a BaerlyAppConfig object`);
178
+ config = mod.default;
179
+ }
180
+ const { verifier, bearerForInjection } = eagerAuth ?? resolveAuth(opts, config);
181
+ const app = config.app;
182
+ const tenant = config.tenant;
183
+ const tables = Object.keys(config.collections);
162
184
  const storage = new LocalFsStorage({ root: opts.dataDir ?? resolve(server.config.root, ".baerly-data") });
163
185
  for (const table of tables) await ensureTable(storage, {
164
186
  app,
@@ -170,28 +192,34 @@ function baerlyDev(opts) {
170
192
  storage,
171
193
  app,
172
194
  tenant,
173
- config: opts.config
195
+ config
174
196
  });
175
197
  await opts.seed(db);
176
198
  }
177
199
  const requestHandler = baerlyNode({
178
- config: opts.config,
200
+ config,
179
201
  storage,
180
202
  verifier
181
203
  }).fetch;
182
- return getRequestListener(requestHandler);
204
+ return {
205
+ listener: getRequestListener(requestHandler),
206
+ bearerForInjection,
207
+ appName: config.app
208
+ };
183
209
  })();
184
210
  ready.catch((error) => {
185
211
  console.error("[baerly-dev] setup failed:", error);
186
212
  });
213
+ ready.then(markSettled, markSettled);
187
214
  server.middlewares.use((req, res, next) => {
188
215
  const url = req.url;
189
216
  if (url === void 0 || !isV1Path(url)) {
190
217
  next();
191
218
  return;
192
219
  }
193
- if (bearerForInjection !== void 0) injectAuthorizationHeader(req, `Bearer ${bearerForInjection}`);
194
- ready.then((listener) => {
220
+ if (eagerAuth?.bearerForInjection !== void 0) injectAuthorizationHeader(req, `Bearer ${eagerAuth.bearerForInjection}`);
221
+ ready.then(({ listener, bearerForInjection }) => {
222
+ if (eagerAuth === void 0 && bearerForInjection !== void 0) injectAuthorizationHeader(req, `Bearer ${bearerForInjection}`);
195
223
  listener(req, res);
196
224
  }, (error) => {
197
225
  res.statusCode = 503;
@@ -206,14 +234,16 @@ function baerlyDev(opts) {
206
234
  const address = server.httpServer?.address();
207
235
  const port = typeof address === "object" && address !== null ? address.port : void 0;
208
236
  const url = port !== void 0 ? `http://localhost:${port}/` : "http://localhost/";
209
- printDevBanner({
210
- name: opts.config.app,
211
- primaryUrl: {
212
- label: "App",
213
- url
214
- },
215
- ...opts.hints !== void 0 && { hints: opts.hints }
216
- });
237
+ ready.then(({ appName }) => {
238
+ printDevBanner({
239
+ name: appName,
240
+ primaryUrl: {
241
+ label: "App",
242
+ url
243
+ },
244
+ ...opts.hints !== void 0 && { hints: opts.hints }
245
+ });
246
+ }).catch(() => {});
217
247
  });
218
248
  }
219
249
  };