@gusto/baerly-storage 0.6.0 → 0.7.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.
- package/README.md +47 -124
- package/dist/API.md +161 -512
- package/dist/CHANGELOG.md +1137 -378
- package/dist/RECIPES.md +398 -80
- package/dist/THIRD-PARTY-LICENSES.txt +5 -26
- package/dist/{app-config-DyiFK3_k.d.ts → app-config-C6qW7m8S.d.ts} +119 -111
- package/dist/app-config.d.ts +31 -1
- package/dist/app-config.js +1 -2
- package/dist/app-config.js.map +1 -1
- package/dist/auth.d.ts +33 -28
- package/dist/auth.js +549 -985
- package/dist/auth.js.map +1 -1
- package/dist/baerly.js +130 -138
- package/dist/baerly.js.map +1 -1
- package/dist/baerly.spec.json +97 -22
- package/dist/capacity-warning-header-BlVopyiI.js +16 -0
- package/dist/capacity-warning-header-BlVopyiI.js.map +1 -0
- package/dist/{client-ypCm3zjt.d.ts → client-CHQTXpef.d.ts} +121 -36
- package/dist/client-react.d.ts +67 -20
- package/dist/client-react.js +240 -54
- package/dist/client-react.js.map +1 -1
- package/dist/client.d.ts +5 -4
- package/dist/client.js +51 -16
- package/dist/client.js.map +1 -1
- package/dist/{cloudflare-wrVYf4bb.js → cloudflare-CKHYXccw.js} +61 -82
- package/dist/cloudflare-CKHYXccw.js.map +1 -0
- package/dist/cloudflare.d.ts +106 -71
- package/dist/cloudflare.js +334 -271
- package/dist/cloudflare.js.map +1 -1
- package/dist/code-resolution-CL_7L0wS.js +22 -0
- package/dist/code-resolution-CL_7L0wS.js.map +1 -0
- package/dist/collection-api-DbyhLAY8.d.ts +1001 -0
- package/dist/config-DEzInG6M.js +4035 -0
- package/dist/config-DEzInG6M.js.map +1 -0
- package/dist/constants-D3GSH3tc.js +469 -0
- package/dist/constants-D3GSH3tc.js.map +1 -0
- package/dist/{context-DRZ3tZ5l.js → context-rlpSnHFA.js} +17 -17
- package/dist/context-rlpSnHFA.js.map +1 -0
- package/dist/cost-B52llVDx.js +330 -0
- package/dist/cost-B52llVDx.js.map +1 -0
- package/dist/{current-json-C6nhPOm1.js → current-json-CC6lE4Aj.js} +115 -32
- package/dist/current-json-CC6lE4Aj.js.map +1 -0
- package/dist/db-plFUNTSF.d.ts +130 -0
- package/dist/db-read-seams-BSs0m1z1.js +3261 -0
- package/dist/db-read-seams-BSs0m1z1.js.map +1 -0
- package/dist/{deploy-Di_Q01qx.js → deploy-Obj4nE-Z.js} +10 -14
- package/dist/deploy-Obj4nE-Z.js.map +1 -0
- package/dist/{dev-banner-CWHIk8tH.d.ts → dev-banner-B5AUHmu1.d.ts} +1 -4
- package/dist/dev-landing-BI5UdmOb.d.ts +32 -0
- package/dist/dev-landing-CD-si4dW.js +50 -0
- package/dist/dev-landing-CD-si4dW.js.map +1 -0
- package/dist/dev-vite.d.ts +9 -14
- package/dist/dev-vite.js +11 -10
- package/dist/dev-vite.js.map +1 -1
- package/dist/dev.d.ts +3 -2
- package/dist/dev.js +2 -1
- package/dist/doctor-BA0i-YAN.js +270 -0
- package/dist/doctor-BA0i-YAN.js.map +1 -0
- package/dist/dump-D1vX8ozg.js +133 -0
- package/dist/dump-D1vX8ozg.js.map +1 -0
- package/dist/errors-7Rk1HGCE.js +160 -0
- package/dist/errors-7Rk1HGCE.js.map +1 -0
- package/dist/{validate-DtljsCh1.js → export-BVL2EvYE.js} +409 -19
- package/dist/export-BVL2EvYE.js.map +1 -0
- package/dist/fsck-BWkPgov4.js +145 -0
- package/dist/fsck-BWkPgov4.js.map +1 -0
- package/dist/{gcs-admin-Bx6xSNJj.d.ts → gcs-admin-Dso1HWQj.d.ts} +18 -14
- package/dist/gcs.d.ts +19 -7
- package/dist/gcs.js +1 -2
- package/dist/{goog4-signer-Z7KnJ1su.js → goog4-signer-CeLIABoE.js} +102 -92
- package/dist/goog4-signer-CeLIABoE.js.map +1 -0
- package/dist/{http-7zT29K3P.js → http-Z5rZyYMX.js} +898 -271
- package/dist/http-Z5rZyYMX.js.map +1 -0
- package/dist/http-transport-DNUM8kU-.js +1299 -0
- package/dist/http-transport-DNUM8kU-.js.map +1 -0
- package/dist/http.d.ts +366 -294
- package/dist/http.js +2 -2
- package/dist/index-JJrIu1pO.d.ts +135 -0
- package/dist/index-LEgHN0qJ.d.ts +50 -0
- package/dist/{index-DP3ClvcA.d.ts → index-RiEYj8t0.d.ts} +291 -78
- package/dist/index.d.ts +27 -6
- package/dist/index.js +3 -5
- package/dist/inspect-BTsVYZKd.js +196 -0
- package/dist/inspect-BTsVYZKd.js.map +1 -0
- package/dist/{key-Di6yyxFu.js → key-C4FPZ9Io.js} +3 -4
- package/dist/{key-Di6yyxFu.js.map → key-C4FPZ9Io.js.map} +1 -1
- package/dist/ledger-Dj_bGgo0.js +192 -0
- package/dist/ledger-Dj_bGgo0.js.map +1 -0
- package/dist/legacy-names-DgZBtgOh.js +47 -0
- package/dist/legacy-names-DgZBtgOh.js.map +1 -0
- package/dist/log-C9W15Dfo.d.ts +94 -0
- package/dist/log-tail-DWJbneBF.js +142 -0
- package/dist/log-tail-DWJbneBF.js.map +1 -0
- package/dist/log-walk-C-vA-WGJ.js +111 -0
- package/dist/log-walk-C-vA-WGJ.js.map +1 -0
- package/dist/maintenance-Dd-Yakqj.js +1709 -0
- package/dist/maintenance-Dd-Yakqj.js.map +1 -0
- package/dist/maintenance-DevB6z4e.js +2237 -0
- package/dist/maintenance-DevB6z4e.js.map +1 -0
- package/dist/maintenance.d.ts +100 -3
- package/dist/maintenance.js +1 -3
- package/dist/node.d.ts +119 -92
- package/dist/node.js +3 -3
- package/dist/{observability-Ch-VQJyE.js → observability-C-ISCCLE.js} +1247 -326
- package/dist/observability-C-ISCCLE.js.map +1 -0
- package/dist/observability.d.ts +27 -3
- package/dist/observability.js +3 -3
- package/dist/path-segment-DBXG26PW.js +363 -0
- package/dist/path-segment-DBXG26PW.js.map +1 -0
- package/dist/{plan-C4qgiXSg.js → plan-BvQbaNMe.js} +19 -11
- package/dist/plan-BvQbaNMe.js.map +1 -0
- package/dist/request-CRWiTrza.js +272 -0
- package/dist/request-CRWiTrza.js.map +1 -0
- package/dist/restore-U6Im8V1V.js +1467 -0
- package/dist/restore-U6Im8V1V.js.map +1 -0
- package/dist/retry-OBtLB2GC.js +126 -0
- package/dist/retry-OBtLB2GC.js.map +1 -0
- package/dist/rolldown-runtime-D3KUYPsf.js +12 -0
- package/dist/{runtime-spec--LykAdl1.js → runtime-spec-B5mg3pHF.js} +189 -28
- package/dist/runtime-spec-B5mg3pHF.js.map +1 -0
- package/dist/{s3-http-DD5gDc7t.d.ts → s3-http-DBC_wiCL.d.ts} +14 -8
- package/dist/s3.d.ts +20 -7
- package/dist/s3.js +4 -5
- package/dist/s3.js.map +1 -1
- package/dist/{sha256-CqcKTjw9.js → sha256-4FfGQNPw.js} +9 -9
- package/dist/sha256-4FfGQNPw.js.map +1 -0
- package/dist/{shared-secret-DgEicd3x.js → shared-secret-Vkur-8r0.js} +27 -15
- package/dist/shared-secret-Vkur-8r0.js.map +1 -0
- package/dist/{aws4fetch.esm-CXE5ZbAa.js → sigv4-sign-5IUflUD_.js} +143 -96
- package/dist/sigv4-sign-5IUflUD_.js.map +1 -0
- package/dist/snapshot-CknzkDM0.js +148 -0
- package/dist/snapshot-CknzkDM0.js.map +1 -0
- package/dist/{src-BMFfDUI2.js → src-Actga-bO.js} +949 -363
- package/dist/src-Actga-bO.js.map +1 -0
- package/dist/src-D0MQfvOp.js +812 -0
- package/dist/src-D0MQfvOp.js.map +1 -0
- package/dist/src-Dr9uo3dc.js +501 -0
- package/dist/src-Dr9uo3dc.js.map +1 -0
- package/dist/{subcommand-BV68pqwJ.js → subcommand-BLoF66dG.js} +89 -16
- package/dist/subcommand-BLoF66dG.js.map +1 -0
- package/dist/{time-DUqvFMHq.js → time-DRxTP9iv.js} +15 -34
- package/dist/time-DRxTP9iv.js.map +1 -0
- package/dist/types-suVbsEWS.d.ts +116 -0
- package/dist/{usage-BMZR8o6U.js → usage-CPzVhrQr.js} +40 -45
- package/dist/usage-CPzVhrQr.js.map +1 -0
- package/dist/uuid-BuT_c404.js +333 -0
- package/dist/uuid-BuT_c404.js.map +1 -0
- package/dist/verifier-Bmlmndzo.d.ts +95 -0
- package/dist/{wire-izfGZDvr.js → wire-DndvKU-K.js} +2 -3
- package/dist/wire-DndvKU-K.js.map +1 -0
- package/package.json +90 -69
- package/dist/aws4fetch.esm-CXE5ZbAa.js.map +0 -1
- package/dist/bytes-BXdamO3L.js +0 -11
- package/dist/bytes-BXdamO3L.js.map +0 -1
- package/dist/cloudflare-wrVYf4bb.js.map +0 -1
- package/dist/config-B6nTy8e2.js +0 -3095
- package/dist/config-B6nTy8e2.js.map +0 -1
- package/dist/constants-CfeMWQWk.js +0 -222
- package/dist/constants-CfeMWQWk.js.map +0 -1
- package/dist/context-DRZ3tZ5l.js.map +0 -1
- package/dist/cost-_SE_SVgZ.js +0 -203
- package/dist/cost-_SE_SVgZ.js.map +0 -1
- package/dist/current-json-C6nhPOm1.js.map +0 -1
- package/dist/db-DjjthkTi.d.ts +0 -254
- package/dist/deploy-Di_Q01qx.js.map +0 -1
- package/dist/doctor-RWVRpvat.js +0 -102
- package/dist/doctor-RWVRpvat.js.map +0 -1
- package/dist/dump-m2vEYDNY.js +0 -94
- package/dist/dump-m2vEYDNY.js.map +0 -1
- package/dist/errors-Dfa3p78c.js +0 -78
- package/dist/errors-Dfa3p78c.js.map +0 -1
- package/dist/export-DenKwEQu.js +0 -401
- package/dist/export-DenKwEQu.js.map +0 -1
- package/dist/fsck-2Vq-7-e2.js +0 -279
- package/dist/fsck-2Vq-7-e2.js.map +0 -1
- package/dist/goog4-signer-Z7KnJ1su.js.map +0 -1
- package/dist/http-7zT29K3P.js.map +0 -1
- package/dist/http-transport-BTgVCY5r.js +0 -1250
- package/dist/http-transport-BTgVCY5r.js.map +0 -1
- package/dist/index-BHz92Acj.d.ts +0 -162
- package/dist/index-CEZKQsKt.d.ts +0 -1113
- package/dist/index-uE-w2dgj.d.ts +0 -115
- package/dist/indexes-Dn9hbGQG.d.ts +0 -22
- package/dist/inspect-BpYbH1DM.js +0 -133
- package/dist/inspect-BpYbH1DM.js.map +0 -1
- package/dist/log-tail-QWU4wlu-.js +0 -514
- package/dist/log-tail-QWU4wlu-.js.map +0 -1
- package/dist/maintenance-BGHGt2Yg.d.ts +0 -537
- package/dist/maintenance-DULFcpd1.js +0 -2144
- package/dist/maintenance-DULFcpd1.js.map +0 -1
- package/dist/maintenance-fEi-UZ2o.js +0 -1412
- package/dist/maintenance-fEi-UZ2o.js.map +0 -1
- package/dist/normalize-rjnZLwS4.js +0 -133
- package/dist/normalize-rjnZLwS4.js.map +0 -1
- package/dist/observability-Ch-VQJyE.js.map +0 -1
- package/dist/plan-C4qgiXSg.js.map +0 -1
- package/dist/query-C43r-6ib.js +0 -1773
- package/dist/query-C43r-6ib.js.map +0 -1
- package/dist/rebuild-index-BH1dc1p6.js +0 -81
- package/dist/rebuild-index-BH1dc1p6.js.map +0 -1
- package/dist/request-u0M51mhJ.js +0 -72
- package/dist/request-u0M51mhJ.js.map +0 -1
- package/dist/restore-D0VYWzfP.js +0 -778
- package/dist/restore-D0VYWzfP.js.map +0 -1
- package/dist/rolldown-runtime-EAsCxrDo.js +0 -14
- package/dist/runtime-spec--LykAdl1.js.map +0 -1
- package/dist/sha256-CqcKTjw9.js.map +0 -1
- package/dist/shared-secret-DgEicd3x.js.map +0 -1
- package/dist/src-BMFfDUI2.js.map +0 -1
- package/dist/src-DYZ4H1aF.js +0 -392
- package/dist/src-DYZ4H1aF.js.map +0 -1
- package/dist/src-DvbTEya2.js +0 -536
- package/dist/src-DvbTEya2.js.map +0 -1
- package/dist/subcommand-BV68pqwJ.js.map +0 -1
- package/dist/time-DUqvFMHq.js.map +0 -1
- package/dist/usage-BMZR8o6U.js.map +0 -1
- package/dist/validate-DtljsCh1.js.map +0 -1
- package/dist/wire-izfGZDvr.js.map +0 -1
|
@@ -0,0 +1,469 @@
|
|
|
1
|
+
// packages/protocol/src/constants.ts
|
|
2
|
+
/**
|
|
3
|
+
* Max encoded size of one committed document (UTF-8 bytes of
|
|
4
|
+
* `encodeJsonBytes(post-image)`, the bytes `LogEntry.after` is stored
|
|
5
|
+
* as): 1 MiB.
|
|
6
|
+
*
|
|
7
|
+
* The writer refuses an insert, update or replace whose post-image is
|
|
8
|
+
* larger, as `InvalidConfig` before any storage call. That bounds every
|
|
9
|
+
* write path the same way: in-process calls, which no HTTP body cap
|
|
10
|
+
* covers, and HTTP merge-patches, each of which fits `MAX_BODY_BYTES`
|
|
11
|
+
* but can grow a stored row past it. Only the post-image is checked, so
|
|
12
|
+
* a row stored larger by an earlier release stays readable, deletable,
|
|
13
|
+
* and shrinkable.
|
|
14
|
+
*
|
|
15
|
+
* 1 MiB matches `MAX_BODY_BYTES` (a document at the cap still fits one
|
|
16
|
+
* request body, with the envelope's few bytes of headroom lost).
|
|
17
|
+
* Firestore's document limit is the same 1 MiB. Any snapshot format must
|
|
18
|
+
* hold one row at this size: a later format sizes its storage unit to
|
|
19
|
+
* fit the row rather than shrinking this cap.
|
|
20
|
+
*/
|
|
21
|
+
const MAX_DOCUMENT_BYTES = 1048576;
|
|
22
|
+
/**
|
|
23
|
+
* Max total object-key length S3 and R2 accept (UTF-8 bytes). A key
|
|
24
|
+
* over this fails the PUT with an opaque provider 400; baerly surfaces
|
|
25
|
+
* it early as InvalidConfig. See docs/spec/storage-compatibility.md.
|
|
26
|
+
*/
|
|
27
|
+
const MAX_KEY_BYTES = 1024;
|
|
28
|
+
/**
|
|
29
|
+
* Full-jitter backoff base, in milliseconds, after a throttle (`429`,
|
|
30
|
+
* S3 `503 SlowDown`; any error whose cause carries `throttled: true`).
|
|
31
|
+
* Longer than {@link STORAGE_RETRY_TRANSIENT_BASE_MILLIS} because a
|
|
32
|
+
* throttle says the store is overloaded, and an early resend adds load.
|
|
33
|
+
*
|
|
34
|
+
* 1 s is the AWS SDKs' throttle base
|
|
35
|
+
* (https://aws.amazon.com/blogs/developer/announcing-updated-retry-behavior-for-aws-sdks-and-tools/).
|
|
36
|
+
*
|
|
37
|
+
* @see packages/protocol/src/storage/retry.ts (`storageRetryDelayMillis`)
|
|
38
|
+
*/
|
|
39
|
+
const STORAGE_RETRY_THROTTLE_BASE_MILLIS = 1e3;
|
|
40
|
+
/**
|
|
41
|
+
* Upper bound, in milliseconds, on one backoff between storage
|
|
42
|
+
* attempts, jittered or server-hinted (`Retry-After` is clamped to
|
|
43
|
+
* it). 20 s is the AWS SDKs' backoff cap
|
|
44
|
+
* (https://aws.amazon.com/blogs/developer/announcing-updated-retry-behavior-for-aws-sdks-and-tools/).
|
|
45
|
+
*
|
|
46
|
+
* @see packages/protocol/src/storage/retry.ts (`storageRetryDelayMillis`)
|
|
47
|
+
*/
|
|
48
|
+
const STORAGE_RETRY_MAX_DELAY_MILLIS = 2e4;
|
|
49
|
+
/**
|
|
50
|
+
* Request-ledger limit on both pools on Workers Paid (the `cf-paid`
|
|
51
|
+
* maintenance profile): Paid's default 10,000 subrequests per invocation
|
|
52
|
+
* less a 10% margin. An operator who lowers `limits.subrequests` in the
|
|
53
|
+
* Wrangler config is invisible to the Worker, so `cf-paid` assumes the
|
|
54
|
+
* default.
|
|
55
|
+
*/
|
|
56
|
+
const CF_PAID_REQUEST_LIMIT = 9e3;
|
|
57
|
+
/**
|
|
58
|
+
* Runaway guard on the tolerant forward-probe walk (`probeTailFrom`):
|
|
59
|
+
* max `log/<seq>` GETs past `tail_hint` before it THROWS `Internal`
|
|
60
|
+
* (rather than silently truncating reads). A runaway alarm only — the
|
|
61
|
+
* maintenance tick keeps `tail_hint` near the tail, so a >cap gap means
|
|
62
|
+
* maintenance is off or the collection is far past graduation.
|
|
63
|
+
*
|
|
64
|
+
* @see packages/server/src/log-tail.ts (`probeTailFrom`)
|
|
65
|
+
*/
|
|
66
|
+
const LOG_FORWARD_PROBE_CAP = 1e5;
|
|
67
|
+
/**
|
|
68
|
+
* Sequence distance retained below `log_seq_start` before `log/<seq>.json`
|
|
69
|
+
* objects become retirable: a rate limit on how fast retirement approaches the
|
|
70
|
+
* live floor.
|
|
71
|
+
*
|
|
72
|
+
* Folded entries stay readable below the floor for this long, which is what a
|
|
73
|
+
* windowed commit (`Writer#readFoldedWindow`, for an insert guard or an
|
|
74
|
+
* admission re-check whose read predates a fold) needs to finish rather than
|
|
75
|
+
* refuse with `WriteConflict`; it reads at most the entries a fold absorbed
|
|
76
|
+
* between two reads in one request, far fewer than 1024. The value is a
|
|
77
|
+
* literal: it carries no derivation, and shrinking it is a measured change of
|
|
78
|
+
* its own.
|
|
79
|
+
*
|
|
80
|
+
* **This window is NOT a paused-writer fence, and no safety property may be
|
|
81
|
+
* derived from it.** It is a cost margin and a rate limit on how fast
|
|
82
|
+
* retirement approaches the live floor — nothing more. The withdrawn argument
|
|
83
|
+
* was that a certified-deleted slot needs `log_seq_start` to advance by more
|
|
84
|
+
* than this window "during one in-flight commit". The arithmetic is correct and
|
|
85
|
+
* the quantifier is vacuous: one in-flight commit bounds no wall-clock and no
|
|
86
|
+
* commit count, so this is a rate x duration assumption expressed in sequences,
|
|
87
|
+
* the same class as `GC_GRACE_PERIOD_MILLIS` in seconds. Lowering the value on
|
|
88
|
+
* cost grounds costs windowed-commit headroom and retirement smoothness; it
|
|
89
|
+
* does not weaken a safety proof, because there was never one here.
|
|
90
|
+
*
|
|
91
|
+
* Withdrawing the claim does not leave the schedule open, because the commit
|
|
92
|
+
* path closes it directly. After the committing `log/<seq>` create resolves,
|
|
93
|
+
* `Writer#assertCommitAboveDeleteFloor` re-reads `current.json` and fails a
|
|
94
|
+
* create that won at a `seq` below `min(log_delete_floor, log_seq_start)` with
|
|
95
|
+
* `BaerlyError{code:"AmbiguousCommit"}`, rather than acknowledging a mutation
|
|
96
|
+
* no reader can see. That check keys on the certified delete floor, not on this
|
|
97
|
+
* window, which is exactly why the window may keep being a cost margin without
|
|
98
|
+
* carrying a safety obligation. Do not re-derive a fence from this value.
|
|
99
|
+
*
|
|
100
|
+
* @see packages/server/src/writer.ts (`Writer#assertCommitAboveDeleteFloor`)
|
|
101
|
+
* @see packages/server/src/log-retention.ts
|
|
102
|
+
* @see docs/spec/sync-protocol.md invariant 12
|
|
103
|
+
* @see docs/adr/002-ephemeral-coordination.md § Closed paths
|
|
104
|
+
*/
|
|
105
|
+
const LOG_RETENTION_SEQ_WINDOW = 1024;
|
|
106
|
+
/**
|
|
107
|
+
* MIME type written for `current.json` PUTs. S3 round-trips this on
|
|
108
|
+
* subsequent GETs; useful for diagnostics when staring at a bucket
|
|
109
|
+
* via the AWS console.
|
|
110
|
+
*
|
|
111
|
+
* @see packages/protocol/src/coordination/current-json.ts
|
|
112
|
+
*/
|
|
113
|
+
const CURRENT_JSON_CONTENT_TYPE = "application/json";
|
|
114
|
+
/**
|
|
115
|
+
* MIME type written for `gc/pending.json` PUTs.
|
|
116
|
+
*
|
|
117
|
+
* @see packages/protocol/src/coordination/gc-pending.ts
|
|
118
|
+
*/
|
|
119
|
+
const GC_PENDING_CONTENT_TYPE = "application/json";
|
|
120
|
+
/**
|
|
121
|
+
* Default grace period between "marking" a key for GC and "sweeping"
|
|
122
|
+
* (deleting) it. 7 days, chosen to span the worst plausible writer-
|
|
123
|
+
* retry window (a paused-process writer that resumes hours later
|
|
124
|
+
* should still find its idempotency anchor on the bucket). The
|
|
125
|
+
* `runGc()` function accepts an override for tests.
|
|
126
|
+
*
|
|
127
|
+
* Why 7 days specifically:
|
|
128
|
+
* - **1 day is too aggressive for batch workloads.** Worker isolate
|
|
129
|
+
* scheduling pauses, cross-region replication lag, and
|
|
130
|
+
* {@link STORAGE_RETRY_THROTTLE_BASE_MILLIS} retry cascades can plausibly
|
|
131
|
+
* exceed an hour under pathological conditions.
|
|
132
|
+
* - **30 days is conservative beyond the worst plausible pause.**
|
|
133
|
+
* Doubles `gc/pending.json` size at steady state and slows
|
|
134
|
+
* visibility into "did GC actually run?" by 4×.
|
|
135
|
+
* - **7 days spans the realistic upper bound** — long-running batch
|
|
136
|
+
* jobs, multi-region propagation delays, queue backlogs, and
|
|
137
|
+
* downstream outages the writer is retrying through. The protocol
|
|
138
|
+
* is unaffected by the choice of value within the [hours, weeks]
|
|
139
|
+
* range; this constant is the operator-tunable knob.
|
|
140
|
+
*
|
|
141
|
+
* Production code MUST NOT call `runGc` with `graceMillis` below the
|
|
142
|
+
* default outside maintenance windows — going below the longest
|
|
143
|
+
* plausible writer-retry latency risks deleting an anchor a writer
|
|
144
|
+
* is about to find on retry. Test code that sets `graceMillis: 0` is
|
|
145
|
+
* exercising the sweep path deliberately, not modelling production.
|
|
146
|
+
*
|
|
147
|
+
* @see packages/server/src/gc.ts
|
|
148
|
+
*/
|
|
149
|
+
const GC_GRACE_PERIOD_MILLIS = 6048e5;
|
|
150
|
+
/**
|
|
151
|
+
* Fraction of the GC grace one `runGc` pass may spend between the
|
|
152
|
+
* `current.json` read its DELETEs rest on and each DELETE batch. Once
|
|
153
|
+
* the elapsed time exceeds `graceMillis * GC_PASS_GRACE_FRACTION`, the
|
|
154
|
+
* pass issues no further DELETEs and leaves the remaining due
|
|
155
|
+
* candidates in `gc/pending.json` for a later pass, which re-reads the
|
|
156
|
+
* manifest.
|
|
157
|
+
*
|
|
158
|
+
* Why 1/10:
|
|
159
|
+
* - **A live pass never trips it.** Against the 7-day default the
|
|
160
|
+
* budget is ~16.8 hours, and a pass on every first-class host lasts
|
|
161
|
+
* seconds. Only a paused or starved process crosses it.
|
|
162
|
+
* - **It bounds how stale a DELETE's liveness proof can be.** It
|
|
163
|
+
* matters for the legacy `stale-log` arm, whose DELETE can rest on
|
|
164
|
+
* the pass's first `current.json` read: a candidate is due no earlier
|
|
165
|
+
* than its mark plus the grace, so a DELETE issued within `f` of the
|
|
166
|
+
* grace after that read rests on one taken at least `(1 - f)` of the
|
|
167
|
+
* grace after the mark. An `orphan-snapshot` DELETE always rests on
|
|
168
|
+
* the sweep-time re-read, taken after the candidate came due, so a
|
|
169
|
+
* full grace after its mark.
|
|
170
|
+
*
|
|
171
|
+
* In-band, by design: one clock comparison per DELETE batch, no lease
|
|
172
|
+
* and no knob. Elapsed time is the larger of one node's wall-clock and
|
|
173
|
+
* monotonic readings, so neither cross-node skew nor a backward clock
|
|
174
|
+
* correction shortens it, and a suspend the monotonic clock skips still
|
|
175
|
+
* shows on the wall clock. The after-the-mark figures rest on `due_at`
|
|
176
|
+
* and so keep invariant 14's wall-clock limitation. A pass with
|
|
177
|
+
* `graceMillis: 0` (tests only) has no grace to keep a fraction of and
|
|
178
|
+
* is not bounded.
|
|
179
|
+
*
|
|
180
|
+
* @see docs/spec/sync-protocol.md (invariant 14)
|
|
181
|
+
* @see packages/server/src/gc.ts
|
|
182
|
+
*/
|
|
183
|
+
const GC_PASS_GRACE_FRACTION = 1 / 10;
|
|
184
|
+
/**
|
|
185
|
+
* Cap on candidates kept in `gc/pending.json` to bound the size of
|
|
186
|
+
* the file. The compactor marks at most this many candidates per
|
|
187
|
+
* pass; subsequent passes pick up the rest. Larger collections will
|
|
188
|
+
* lag GC by one pass per `GC_MAX_PENDING_CANDIDATES` orphans, which
|
|
189
|
+
* is acceptable.
|
|
190
|
+
*
|
|
191
|
+
* @see packages/server/src/gc.ts
|
|
192
|
+
*/
|
|
193
|
+
const GC_MAX_PENDING_CANDIDATES = 1e3;
|
|
194
|
+
/**
|
|
195
|
+
* Keys per LIST response page on every in-tree object-store adapter:
|
|
196
|
+
* S3 and GCS `max-keys` and R2 binding `limit` all cap at 1000. `runGc`
|
|
197
|
+
* widens its orphan-snapshot mark window past already-pending keys only
|
|
198
|
+
* up to this size, so the widening never adds a full LIST page (a
|
|
199
|
+
* provider may still truncate a page short and cost another request).
|
|
200
|
+
*
|
|
201
|
+
* @see packages/server/src/gc.ts
|
|
202
|
+
* @see docs/spec/storage-compatibility.md
|
|
203
|
+
*/
|
|
204
|
+
const GC_MARK_LIST_PAGE_KEYS = 1e3;
|
|
205
|
+
/**
|
|
206
|
+
* Floor for the ratio denominator — avoid div-by-tiny on a fresh collection. Also
|
|
207
|
+
* sets the first-fold threshold: until a snapshot exists, fold fires at tail ≈ this.
|
|
208
|
+
*
|
|
209
|
+
* @see packages/server/src/maintenance.ts
|
|
210
|
+
*/
|
|
211
|
+
const MAINTENANCE_MIN_LIVE_BYTES = 65536;
|
|
212
|
+
/**
|
|
213
|
+
* Cloudflare Paid scheduled-compactor tail-discovery budget (`P`) for
|
|
214
|
+
* `CLOUDFLARE_PAID_TIER`. Without one, the scheduled probe may walk up to
|
|
215
|
+
* {@link LOG_FORWARD_PROBE_CAP} (100,000) GETs past a stale `tail_hint`,
|
|
216
|
+
* which no Paid invocation can issue: the request ledger refuses the pass
|
|
217
|
+
* at {@link CF_PAID_REQUEST_LIMIT} and nothing folds. With a budget, a
|
|
218
|
+
* pass that exhausts it checkpoints the certified lower bound in
|
|
219
|
+
* `current.json` and the next pass resumes there.
|
|
220
|
+
*
|
|
221
|
+
* With the Paid profile's per-pass slice
|
|
222
|
+
* `N` = {@link NODE_MAINTENANCE_FOLD_ENTRIES_PER_PASS} (200), the worst
|
|
223
|
+
* pass is `4 + N + P` = 1,204 storage calls, 3,612 with every call retried
|
|
224
|
+
* {@link STORAGE_RETRY_MAX_ATTEMPTS} times, well inside 9,000. 1,000 is
|
|
225
|
+
* five slices of discovery per pass: large enough that a pass behind by
|
|
226
|
+
* a normal backlog still folds, small enough that a scheduled compact, GC
|
|
227
|
+
* and retirement pass together stay under the limit at full retries.
|
|
228
|
+
*
|
|
229
|
+
* @see packages/server/src/maintenance.ts (`CLOUDFLARE_PAID_TIER`)
|
|
230
|
+
* @see packages/server/src/maintenance-budget.test.ts
|
|
231
|
+
*/
|
|
232
|
+
const CF_PAID_COMPACT_TAIL_PROBE_GETS = 1e3;
|
|
233
|
+
/**
|
|
234
|
+
* SNAPSHOT-rebuild ceiling `C` (the unsliceable axis — Decision 3a), memory. A
|
|
235
|
+
* conservative configured budget for the CF-free ~10 ms CPU limit; the ~5.5 ms
|
|
236
|
+
* rebuild-time figure behind it is a sizing estimate, not an observed platform
|
|
237
|
+
* limit. Raise via BAERLY_MAINTENANCE_MAX_FOLD_BYTES on capable
|
|
238
|
+
* hosts. Auto-maintained snapshot ceiling S_max = C. NOT snapshot+tail (tail is sliced).
|
|
239
|
+
*
|
|
240
|
+
* @see docs/spec/scale-ceilings.md
|
|
241
|
+
* @see packages/server/src/maintenance.ts
|
|
242
|
+
*/
|
|
243
|
+
const MAINTENANCE_MAX_FOLD_BYTES_DEFAULT = 524288;
|
|
244
|
+
/**
|
|
245
|
+
* The largest snapshot a Cloudflare **free-tier** isolate can safely
|
|
246
|
+
* rebuild in ONE fold under the ~10 ms CPU budget. This is the WARN
|
|
247
|
+
* THRESHOLD, not a runtime cap: an operator who raises
|
|
248
|
+
* `BAERLY_MAINTENANCE_MAX_FOLD_BYTES` ABOVE this value on a free Worker
|
|
249
|
+
* is past the conservative budget, and a larger snapshot rebuild may
|
|
250
|
+
* exceed an invocation's CPU or memory resources. If an invocation is
|
|
251
|
+
* terminated mid-rebuild the CAS does not land, so that fold does not
|
|
252
|
+
* advance `log_seq_start`. This value is a configured budget; no
|
|
253
|
+
* particular snapshot size is established to cause termination.
|
|
254
|
+
*
|
|
255
|
+
* Sized at 2× {@link MAINTENANCE_MAX_FOLD_BYTES_DEFAULT}. The ~5.5 ms
|
|
256
|
+
* rebuild estimate for the default (512 KiB) and the linear
|
|
257
|
+
* extrapolation to ~1 MiB are sizing estimates, not observed platform
|
|
258
|
+
* limits; anything strictly larger is simply outside the budget
|
|
259
|
+
* this constant documents. On CF **paid**
|
|
260
|
+
* (raised CPU limits) or Node, a larger ceiling is fine — hence this is
|
|
261
|
+
* a one-time `console.warn` at handler init, NOT a hard rejection.
|
|
262
|
+
*
|
|
263
|
+
* @see packages/adapter-cloudflare/src/worker.ts
|
|
264
|
+
* @see packages/server/src/maintenance.ts
|
|
265
|
+
* @see docs/spec/scale-ceilings.md
|
|
266
|
+
*/
|
|
267
|
+
const CF_FREE_MAX_SAFE_FOLD_BYTES = 1048576;
|
|
268
|
+
/**
|
|
269
|
+
* SNAPSHOT-rebuild ceiling `E`, per-entry CPU axis: gates `snapshot_rows` (per-entry
|
|
270
|
+
* parse/merge/serialize is ~half of fold CPU and scales with ROW COUNT not bytes, VLDB 2021
|
|
271
|
+
* Sarkar — a tiny-doc snapshot can blow CPU under C).
|
|
272
|
+
*
|
|
273
|
+
* This is the **cf-free** value and the shared default. `pnpm bench:fold-ceiling`
|
|
274
|
+
* measures 2048 rows at ~1.5 ms against the ~10 ms free-tier budget (a ~6.6×
|
|
275
|
+
* margin), and the row axis does not reach 10 ms until ~16,384 rows. The value
|
|
276
|
+
* stays at 2048 as a conservative configured budget: a fold that overruns a free
|
|
277
|
+
* isolate's CPU may be terminated before the `current.json` CAS lands — see
|
|
278
|
+
* {@link CF_FREE_MAX_SAFE_FOLD_BYTES}. The
|
|
279
|
+
* larger hosts no longer inherit it; see {@link CF_PAID_MAINTENANCE_MAX_FOLD_ROWS}
|
|
280
|
+
* and {@link NODE_MAINTENANCE_MAX_FOLD_ROWS}.
|
|
281
|
+
*
|
|
282
|
+
* @see docs/spec/scale-ceilings.md
|
|
283
|
+
* @see packages/server/src/maintenance.ts
|
|
284
|
+
*/
|
|
285
|
+
const MAINTENANCE_MAX_FOLD_ROWS = 2048;
|
|
286
|
+
/**
|
|
287
|
+
* Snapshot-rebuild byte ceiling `C` for the **cf-paid** profile.
|
|
288
|
+
*
|
|
289
|
+
* A paid isolate's wall is ~128 MB of Worker memory, not CPU — at a 30 s CPU
|
|
290
|
+
* budget the rebuild is never CPU-bound, but a fold holds the old snapshot, the
|
|
291
|
+
* new snapshot, and the tail at once. `pnpm bench:fold-ceiling` measures peak
|
|
292
|
+
* heap at ~2.4× the snapshot on the byte axis, stable across 704 MB–4.3 GB
|
|
293
|
+
* heaps: 8 MiB peaks at ~19.5 MB, a 4× margin under 128 MB. The next grid cell
|
|
294
|
+
* up (16 MiB ⇒ 37.3 MB peak) exceeds that margin, which is what fixes this
|
|
295
|
+
* value.
|
|
296
|
+
*
|
|
297
|
+
* The margin is deliberately tight because overrun is NOT graceful here: an
|
|
298
|
+
* isolate OOM mid-fold would leave the `current.json` CAS unpublished, so that
|
|
299
|
+
* fold would not advance `log_seq_start`.
|
|
300
|
+
*
|
|
301
|
+
* @see docs/spec/scale-ceilings.md
|
|
302
|
+
* @see bench/measurement/fold-ceiling-probe.ts
|
|
303
|
+
*/
|
|
304
|
+
const CF_PAID_MAINTENANCE_MAX_FOLD_BYTES = 8388608;
|
|
305
|
+
/**
|
|
306
|
+
* Snapshot-rebuild row ceiling `E` for the **cf-paid** profile. Same 128 MB
|
|
307
|
+
* memory wall and same 4× margin as {@link CF_PAID_MAINTENANCE_MAX_FOLD_BYTES};
|
|
308
|
+
* the row axis costs ~600 B of peak heap per row (measured), so 32,768 rows
|
|
309
|
+
* peaks at ~19.7 MB. The next grid cell up (65,536 rows ⇒ 39.4 MB) exceeds the
|
|
310
|
+
* margin.
|
|
311
|
+
*
|
|
312
|
+
* @see docs/spec/scale-ceilings.md
|
|
313
|
+
*/
|
|
314
|
+
const CF_PAID_MAINTENANCE_MAX_FOLD_ROWS = 32768;
|
|
315
|
+
/**
|
|
316
|
+
* Snapshot-rebuild byte ceiling `C` for the **node** profile.
|
|
317
|
+
*
|
|
318
|
+
* Serverful Node has no per-request cap, and its fold is not abortable —
|
|
319
|
+
* `nodeMaintenanceDispatch` passes no `signal` — so an over-large fold
|
|
320
|
+
* COMPLETES. The failure mode is one slow write, not a stranded CAS. That
|
|
321
|
+
* asymmetry is why Node's ceiling is set generously where cf-free's and
|
|
322
|
+
* cf-paid's are set tightly: UNDER-setting `C` permanently defers the fold,
|
|
323
|
+
* which is the worse failure on every host. Inline fold latency is budgeted by
|
|
324
|
+
* {@link NODE_MAINTENANCE_FOLD_ENTRIES_PER_PASS} (the sliceable tail work), not
|
|
325
|
+
* by this ceiling (the unsliceable snapshot rebuild).
|
|
326
|
+
*
|
|
327
|
+
* 32 MiB is the top of the measured grid, NOT the wall: `pnpm bench:fold-ceiling`
|
|
328
|
+
* reports `grid-exhausted` for this profile at every margin and at every heap
|
|
329
|
+
* from 704 MB up. At a 704 MB heap — the smallest realistic container — a
|
|
330
|
+
* 32 MiB fold peaks at ~37 MB, a ~19× margin. The scaling rule past the grid is
|
|
331
|
+
* `C ≈ heap / 10` (peak ≈ 2.4× snapshot, 4× margin). Finding the real wall
|
|
332
|
+
* needs the byte axis extended past 32 MiB.
|
|
333
|
+
*
|
|
334
|
+
* A separate hard ceiling sits near 512 MB regardless of heap: `encodeJsonBytes`
|
|
335
|
+
* / `decodeJsonBytes` materialize the whole snapshot as a JS string, so a
|
|
336
|
+
* snapshot at V8's `MAX_STRING_LENGTH` throws mid-fold.
|
|
337
|
+
*
|
|
338
|
+
* @see docs/spec/scale-ceilings.md
|
|
339
|
+
* @see bench/measurement/fold-ceiling-probe.ts
|
|
340
|
+
*/
|
|
341
|
+
const NODE_MAINTENANCE_MAX_FOLD_BYTES = 33554432;
|
|
342
|
+
/**
|
|
343
|
+
* Snapshot-rebuild row ceiling `E` for the **node** profile. 65,536 rows is the
|
|
344
|
+
* largest row cell with a stable measured peak (~39.4 MB, reproduced within
|
|
345
|
+
* 0.05 MB across four runs); the 131,072-row cell's peak is not yet reliably
|
|
346
|
+
* measurable. Against even a 704 MB heap that is a ~17× margin, consistent with
|
|
347
|
+
* {@link NODE_MAINTENANCE_MAX_FOLD_BYTES} being a measured floor rather than a
|
|
348
|
+
* wall.
|
|
349
|
+
*
|
|
350
|
+
* @see docs/spec/scale-ceilings.md
|
|
351
|
+
*/
|
|
352
|
+
const NODE_MAINTENANCE_MAX_FOLD_ROWS = 65536;
|
|
353
|
+
/**
|
|
354
|
+
* Fraction of a fold ceiling at which an admitted write starts carrying a
|
|
355
|
+
* capacity warning (main-10 G7). The warning fires when the projected
|
|
356
|
+
* snapshot, at its peak over the pending tail and the writes just
|
|
357
|
+
* admitted, holds at least this share of `E` rows or of the `C - margin`
|
|
358
|
+
* bytes the growth refusal compares against. It is a policy choice, not a
|
|
359
|
+
* measurement: 90% leaves roughly 200 rows of runway on Workers Free's
|
|
360
|
+
* 2,048-row `E`, enough for an app to react before the first
|
|
361
|
+
* `CapacityExceeded`, and about 10% of `C` in bytes. The warning is a
|
|
362
|
+
* pure function of `current.json` and the tail, so it clears the moment
|
|
363
|
+
* that state drops back under the threshold.
|
|
364
|
+
*
|
|
365
|
+
* @see packages/server/src/capacity.ts
|
|
366
|
+
*/
|
|
367
|
+
const CAPACITY_WARN_FRACTION = .9;
|
|
368
|
+
/** CF-free profile; the absent-context default. */
|
|
369
|
+
const MAINTENANCE_PROFILE_CF_FREE = {
|
|
370
|
+
gcInterval: 4,
|
|
371
|
+
gcMaxMarks: 20,
|
|
372
|
+
gcMaxSweeps: 10,
|
|
373
|
+
maxFoldEntriesPerPass: 20,
|
|
374
|
+
maxFoldBytes: MAINTENANCE_MAX_FOLD_BYTES_DEFAULT,
|
|
375
|
+
maxFoldRows: MAINTENANCE_MAX_FOLD_ROWS
|
|
376
|
+
};
|
|
377
|
+
/** Node profile; 10× CF-free per-pass caps, and its own measured snapshot ceilings. */
|
|
378
|
+
const MAINTENANCE_PROFILE_NODE = {
|
|
379
|
+
gcInterval: 2,
|
|
380
|
+
gcMaxMarks: 200,
|
|
381
|
+
gcMaxSweeps: 100,
|
|
382
|
+
maxFoldEntriesPerPass: 200,
|
|
383
|
+
maxFoldBytes: NODE_MAINTENANCE_MAX_FOLD_BYTES,
|
|
384
|
+
maxFoldRows: NODE_MAINTENANCE_MAX_FOLD_ROWS
|
|
385
|
+
};
|
|
386
|
+
/**
|
|
387
|
+
* CF-paid profile — opt-in via `BAERLY_MAINTENANCE_PROFILE=cf-paid`. A paid
|
|
388
|
+
* isolate keeps the CF-free single-phase shape (one phase per request) but has a
|
|
389
|
+
* 9,000-call request ledger limit ({@link CF_PAID_REQUEST_LIMIT}), so it reuses the
|
|
390
|
+
* `NODE_MAINTENANCE_*` per-pass caps.
|
|
391
|
+
*
|
|
392
|
+
* A profile moves RATE and the DEFER THRESHOLD, never the stored data or the
|
|
393
|
+
* query semantics — that is the equivalence invariant, and it is what
|
|
394
|
+
* `tests/integration/maintenance-profile-equivalence.test.ts` proves: a read
|
|
395
|
+
* folds snapshot + live tail, so HOW MUCH a profile has folded is invisible to
|
|
396
|
+
* a reader. Snapshot ceilings therefore differ per host, sized to each host's
|
|
397
|
+
* real wall (see {@link CF_PAID_MAINTENANCE_MAX_FOLD_BYTES}). Operators can
|
|
398
|
+
* still raise `C` out-of-band with `BAERLY_MAINTENANCE_MAX_FOLD_BYTES`.
|
|
399
|
+
*
|
|
400
|
+
* @see packages/adapter-cloudflare/src/worker.ts
|
|
401
|
+
* @see docs/about/graduation.md
|
|
402
|
+
*/
|
|
403
|
+
const MAINTENANCE_PROFILE_CF_PAID = {
|
|
404
|
+
gcInterval: 2,
|
|
405
|
+
gcMaxMarks: 200,
|
|
406
|
+
gcMaxSweeps: 100,
|
|
407
|
+
maxFoldEntriesPerPass: 200,
|
|
408
|
+
maxFoldBytes: CF_PAID_MAINTENANCE_MAX_FOLD_BYTES,
|
|
409
|
+
maxFoldRows: CF_PAID_MAINTENANCE_MAX_FOLD_ROWS
|
|
410
|
+
};
|
|
411
|
+
/**
|
|
412
|
+
* Rate-limit the defer-warn off SHARED current.json.last_warned_seq (not per-isolate
|
|
413
|
+
* memory — CF recycles isolates). ~once per this many writes.
|
|
414
|
+
*
|
|
415
|
+
* @see packages/protocol/src/coordination/current-json.ts
|
|
416
|
+
* @see packages/server/src/maintenance.ts
|
|
417
|
+
*/
|
|
418
|
+
const MAINTENANCE_WARN_INTERVAL_WRITES = 1e3;
|
|
419
|
+
/**
|
|
420
|
+
* Stable seed for `CurrentJson.snapshot === null` when building the
|
|
421
|
+
* opaque `_meta.manifest_pointer` cursor emitted on read responses.
|
|
422
|
+
* The literal no longer appears by itself on the wire; it is folded
|
|
423
|
+
* into the server-side digest so the cursor never exposes physical
|
|
424
|
+
* snapshot keys.
|
|
425
|
+
*
|
|
426
|
+
* @see packages/server/src/contract.ts (HttpOkMeta)
|
|
427
|
+
*/
|
|
428
|
+
const MANIFEST_POINTER_EMPTY_SNAPSHOT = "none";
|
|
429
|
+
/**
|
|
430
|
+
* Keys that must never propagate through {@link applyMergePatch} or
|
|
431
|
+
* {@link coalesceMergePatches}: assigning to
|
|
432
|
+
* them on a plain object pollutes the prototype chain. The literal
|
|
433
|
+
* `{ __proto__: ... }` syntax is a prototype-setter (not an own key)
|
|
434
|
+
* and bypasses `Object.keys`, but `JSON.parse('{"__proto__":...}')`
|
|
435
|
+
* produces a real own property — which is exactly how a malicious
|
|
436
|
+
* HTTP PATCH body would arrive on the wire.
|
|
437
|
+
*
|
|
438
|
+
* Lifted to a constant so every iteration path that touches a
|
|
439
|
+
* caller-supplied object can re-use the same defence without
|
|
440
|
+
* duplicating the keyword list.
|
|
441
|
+
*
|
|
442
|
+
* @see packages/protocol/src/json.ts (applyMergePatch, coalesceMergePatches)
|
|
443
|
+
* @see docs/spec/json-merge-patch.md
|
|
444
|
+
*/
|
|
445
|
+
const FORBIDDEN_MERGE_KEYS = /* @__PURE__ */ new Set([
|
|
446
|
+
"__proto__",
|
|
447
|
+
"constructor",
|
|
448
|
+
"prototype"
|
|
449
|
+
]);
|
|
450
|
+
/**
|
|
451
|
+
* Locked error wording for the "no auth configured" failure mode. The
|
|
452
|
+
* adapter throws this when neither `config.auth` nor `verifier:`
|
|
453
|
+
* resolves a real `Verifier`. Pinned via a regression test so future
|
|
454
|
+
* refactors do not drift the operator-facing wording.
|
|
455
|
+
*
|
|
456
|
+
* Consumed by:
|
|
457
|
+
* - `packages/adapter-cloudflare/src/worker.ts` (first-fetch throw)
|
|
458
|
+
* - `packages/adapter-node/src/server.ts` (first-fetch throw)
|
|
459
|
+
* - `packages/cli/src/doctor/cloudflare.ts` (FAIL finding mirrors it)
|
|
460
|
+
*/
|
|
461
|
+
const NO_AUTH_CONFIGURED_MESSAGE = "baerly: no auth configured. Set `auth` in baerly.config.ts (\"none\", \"shared-secret\") or pass `verifier` on the adapter factory.";
|
|
462
|
+
/**
|
|
463
|
+
* Locked error wording for `auth: "shared-secret"` + missing env var.
|
|
464
|
+
* Same pinning rationale as {@link NO_AUTH_CONFIGURED_MESSAGE}.
|
|
465
|
+
*/
|
|
466
|
+
const SHARED_SECRET_MISSING_MESSAGE = "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.";
|
|
467
|
+
export { SHARED_SECRET_MISSING_MESSAGE as C, NO_AUTH_CONFIGURED_MESSAGE as S, STORAGE_RETRY_THROTTLE_BASE_MILLIS as T, MAINTENANCE_PROFILE_NODE as _, CURRENT_JSON_CONTENT_TYPE as a, MAX_DOCUMENT_BYTES as b, GC_MARK_LIST_PAGE_KEYS as c, GC_PENDING_CONTENT_TYPE as d, LOG_FORWARD_PROBE_CAP as f, MAINTENANCE_PROFILE_CF_PAID as g, MAINTENANCE_PROFILE_CF_FREE as h, CF_PAID_REQUEST_LIMIT as i, GC_MAX_PENDING_CANDIDATES as l, MAINTENANCE_MIN_LIVE_BYTES as m, CF_FREE_MAX_SAFE_FOLD_BYTES as n, FORBIDDEN_MERGE_KEYS as o, LOG_RETENTION_SEQ_WINDOW as p, CF_PAID_COMPACT_TAIL_PROBE_GETS as r, GC_GRACE_PERIOD_MILLIS as s, CAPACITY_WARN_FRACTION as t, GC_PASS_GRACE_FRACTION as u, MAINTENANCE_WARN_INTERVAL_WRITES as v, STORAGE_RETRY_MAX_DELAY_MILLIS as w, MAX_KEY_BYTES as x, MANIFEST_POINTER_EMPTY_SNAPSHOT as y };
|
|
468
|
+
|
|
469
|
+
//# sourceMappingURL=constants-D3GSH3tc.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"constants-D3GSH3tc.js","names":[],"sources":["../packages/protocol/src/constants.ts"],"sourcesContent":["/**\n * Leading and trailing path segments an `assertDocumentValues` error keeps\n * (`a.b.c.d.….w.x.y.z`). The document is caller-controlled and unbounded\n * in depth, so the message's path is capped; 4 + 4 segments name the\n * field's top-level location and its immediate container, which is what a\n * caller needs to find it.\n */\nexport const DOCUMENT_ERROR_PATH_EDGE_SEGMENTS = 4;\n\n/**\n * Characters of one object key an `assertDocumentValues` error path shows\n * before eliding the rest. Keys are caller-controlled and unbounded, so\n * this keeps one long key from making the message unbounded.\n */\nexport const DOCUMENT_ERROR_PATH_KEY_CHARS = 64;\n\n/**\n * Characters of a refused request `Content-Type` an `UnsupportedMediaType`\n * error echoes before eliding the rest. The header is caller-controlled\n * and its message is public, so this keeps one long header from making\n * the error body and the log line unbounded. 100 holds any registered\n * media type with a short parameter.\n */\nexport const UNSUPPORTED_MEDIA_TYPE_ECHO_CHARS = 100;\n\n/**\n * Max encoded size of one committed document (UTF-8 bytes of\n * `encodeJsonBytes(post-image)`, the bytes `LogEntry.after` is stored\n * as): 1 MiB.\n *\n * The writer refuses an insert, update or replace whose post-image is\n * larger, as `InvalidConfig` before any storage call. That bounds every\n * write path the same way: in-process calls, which no HTTP body cap\n * covers, and HTTP merge-patches, each of which fits `MAX_BODY_BYTES`\n * but can grow a stored row past it. Only the post-image is checked, so\n * a row stored larger by an earlier release stays readable, deletable,\n * and shrinkable.\n *\n * 1 MiB matches `MAX_BODY_BYTES` (a document at the cap still fits one\n * request body, with the envelope's few bytes of headroom lost).\n * Firestore's document limit is the same 1 MiB. Any snapshot format must\n * hold one row at this size: a later format sizes its storage unit to\n * fit the row rather than shrinking this cap.\n */\nexport const MAX_DOCUMENT_BYTES = 1_048_576;\n\n/**\n * Max nesting depth of one document or update patch: 100 levels, where\n * each object or array is a level and the document itself is the first.\n * A scalar adds none, so `{ a: [1] }` is 2 levels deep.\n *\n * `assertDocumentValues` refuses a deeper value as `SchemaError` before\n * any write: on `insert` and `replace`, on an update patch and on\n * each merged post-image, in the HTTP client before it sends, and on\n * `baerly admin restore`'s dump lines. Without a cap, a document\n * committed on a host with a deep call stack can overflow a recursive\n * path (`applyMergePatch`, `jsonValueEqual`, `JSON.stringify`) on a host with a\n * shallower one, wedging reads or folds of its collection; on Node 26 a\n * document of about 8,000 levels already overflows. Only writes are\n * checked, so a row stored deeper by an earlier release stays readable\n * and deletable.\n *\n * 100 is MongoDB's limit for BSON documents (\"Nested Depth for BSON\n * Documents\", MongoDB Limits and Thresholds). Any snapshot format must\n * hold a row at this depth.\n */\nexport const MAX_DOCUMENT_DEPTH = 100;\n\n/**\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 * Largest `limit` an `order(...).limit(k)` read serves from a bounded\n * top-k heap instead of a full sort (`orderRows` in\n * `packages/server/src/query-eval.ts`). Above it the read sorts every\n * row, as it does with no `limit`.\n *\n * Measured with `bench/query-order.ts` (Node 26, random-order keys):\n * n = 2048, k = 20 / 64: 446 -> 57 / 664 -> 150 µs; n = 65,536 about\n * -93%. With the cap lifted the same heap keeps winning on random input\n * (n = 2048: -51% at k = 256, +27% at k = 1000), so 64 is not the\n * crossover. It bounds the heap's worst case, where every row replaces\n * the root, at about `1 + 2·log2(64) = 13` comparisons per row, close\n * to a full sort's `log2(2048) = 11` on random input at the Free row\n * ceiling, and it covers the usual page sizes.\n */\nexport const QUERY_TOP_K_MAX = 64;\n\n/**\n * Adjacent row pairs the top-k pre-scan always compares before it stops\n * comparing once the keys have both risen and fallen (see\n * {@link QUERY_TOP_K_MAX}). The rise/fall counts only choose which end\n * of the input the heap reads from, so that nearly reversed input\n * rarely replaces the root; they never change the result.\n */\nexport const QUERY_TOP_K_SAMPLE = 64;\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 * 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 * Total attempts (first try included) every storage adapter makes for\n * one `Storage` call before surfacing the last failure: S3, GCS, and\n * the R2 binding, for `get` / `put` / `delete` and for each `list`\n * page. 429 and 5xx share this one counter, so a failing call costs at\n * most 3 requests on every host. Applied by `retryStorageCall`. An\n * `ifMatch` put (a compare-and-swap) is the exception: one attempt,\n * since a resend after a lost ack would meet its own write as a 412.\n *\n * 3 is the common prior-art cap: AWS SDK standard retry mode allows 3\n * attempts (https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html),\n * and the Google SRE book caps per-request retries at 3\n * (https://sre.google/sre-book/handling-overload/). Retrying happens at\n * this one layer only: stacked retry loops multiply (\"3 retries at 5\n * layers = 243x\", AWS Builders' Library, \"Timeouts, retries and backoff\n * with jitter\"). A store failing three times in a row is reported as a\n * retriable `NetworkError` rather than ridden out here.\n *\n * @see packages/protocol/src/storage/retry.ts (`retryStorageCall`)\n */\nexport const STORAGE_RETRY_MAX_ATTEMPTS: number = 3;\n\n/**\n * Full-jitter backoff base, in milliseconds, after a transient failure\n * (5xx, network error): retry `n` (0-based) waits\n * `random() * min(STORAGE_RETRY_MAX_DELAY_MILLIS, base * 2^n)`.\n *\n * 50 ms is the AWS SDKs' transient base\n * (https://aws.amazon.com/blogs/developer/announcing-updated-retry-behavior-for-aws-sdks-and-tools/).\n *\n * @see packages/protocol/src/storage/retry.ts (`storageRetryDelayMillis`)\n */\nexport const STORAGE_RETRY_TRANSIENT_BASE_MILLIS: number = 50;\n\n/**\n * Full-jitter backoff base, in milliseconds, after a throttle (`429`,\n * S3 `503 SlowDown`; any error whose cause carries `throttled: true`).\n * Longer than {@link STORAGE_RETRY_TRANSIENT_BASE_MILLIS} because a\n * throttle says the store is overloaded, and an early resend adds load.\n *\n * 1 s is the AWS SDKs' throttle base\n * (https://aws.amazon.com/blogs/developer/announcing-updated-retry-behavior-for-aws-sdks-and-tools/).\n *\n * @see packages/protocol/src/storage/retry.ts (`storageRetryDelayMillis`)\n */\nexport const STORAGE_RETRY_THROTTLE_BASE_MILLIS: number = 1000;\n\n/**\n * Upper bound, in milliseconds, on one backoff between storage\n * attempts, jittered or server-hinted (`Retry-After` is clamped to\n * it). 20 s is the AWS SDKs' backoff cap\n * (https://aws.amazon.com/blogs/developer/announcing-updated-retry-behavior-for-aws-sdks-and-tools/).\n *\n * @see packages/protocol/src/storage/retry.ts (`storageRetryDelayMillis`)\n */\nexport const STORAGE_RETRY_MAX_DELAY_MILLIS: number = 20_000;\n\n/**\n * Request-ledger limit on the `internal` pool on Workers Free (the\n * `cf-free` maintenance profile): every storage call one invocation may\n * issue, R2 binding calls and `fetch` calls alike. Cloudflare documents\n * 1,000 subrequests to internal services per Free invocation\n * (https://developers.cloudflare.com/workers/platform/limits/); 900 keeps\n * a 10% margin for calls the ledger cannot see but the platform counts:\n * app code in the same Worker, redirects, and any per-call multiplier on\n * the binding. A Free probe confirmed the 1,000 (the 1,001st binding call\n * throws \"Too many API requests by single Worker invocation\"); the R2\n * adapter's refusal on that error is the backstop if the ledger undercounts.\n *\n * @see packages/protocol/src/storage/ledger.ts (`RequestLedger`)\n */\nexport const CF_FREE_INTERNAL_REQUEST_LIMIT: number = 900;\n\n/**\n * Request-ledger limit on the `external` pool under the `cf-free`\n * profile: storage calls that leave through `fetch` (S3 over HTTP, GCS).\n * Only fetch storage charges this pool; R2 binding calls do not. Free\n * allows 50 external subrequests per invocation, and a `fetch` past the\n * 50th throws before it is sent (observed at exactly call 51). 45 keeps 5 for calls outside the ledger: the verifier's JWKS\n * fetch on a cold isolate and app code in the same Worker. The removed\n * response cache's allowance stays headroom; this limit is unchanged.\n * `CF_FREE_FETCH_FOLD_AT_TAIL_ENTRIES` and `CF_FREE_FETCH_GC_MAX_SWEEPS`\n * are sized so a whole request fits it.\n */\nexport const CF_FREE_EXTERNAL_REQUEST_LIMIT: number = 45;\n\n/**\n * Request-ledger limit on both pools on Workers Paid (the `cf-paid`\n * maintenance profile): Paid's default 10,000 subrequests per invocation\n * less a 10% margin. An operator who lowers `limits.subrequests` in the\n * Wrangler config is invisible to the Worker, so `cf-paid` assumes the\n * default.\n */\nexport const CF_PAID_REQUEST_LIMIT: number = 9000;\n\n/**\n * Legacy internal Cache API accounting cap. The production Worker never\n * calls the Cache API; point reads always reach storage. Retained with\n * `RequestLedger.chargeCacheCall` for budget-interference tests and\n * internal compatibility, without increasing any supported host limit.\n */\nexport const CF_CACHE_API_MAX_CALLS: number = 3;\n\n/**\n * Storage requests a commit keeps on the request ledger for resolving its\n * committing `log/<seq>` create: `2 * STORAGE_RETRY_MAX_ATTEMPTS` = 6.\n *\n * Once the create is sent, the writer may still need, each retried up to\n * `STORAGE_RETRY_MAX_ATTEMPTS` times by the adapter:\n *\n * - one occupant readback GET of the slot, when the create fails (a 412, a\n * send of unknown outcome, or a throttle that can hide a lost race), and\n * - the `current.json` GET of the delete-floor check, after a win or an\n * adopted lost-ack create.\n *\n * Without room for both, a create that landed but lost its reply cannot be\n * resolved and becomes `AmbiguousCommit`, and a won create skips the\n * delete-floor check. Everything else after the create (the write tick) is\n * best effort and is not reserved.\n *\n * Each slot's attempt runs under a request-ledger hold\n * (`RequestLedger.hold`) of\n * `STORAGE_RETRY_MAX_ATTEMPTS + COMMIT_RESOLUTION_RESERVE` = 9 requests: the\n * create at full retries, plus this reserve. The create is the commit's only\n * write, so the hold is the same for every collection, whatever indexes it\n * declares. Other work in the invocation (a `ctx.waitUntil` write tick)\n * cannot spend held requests. The writer refuses with `CapacityExceeded`,\n * before it writes anything, when the ledger's room cannot cover the hold.\n * After a lost create race it takes a new hold before the next create.\n *\n * The arithmetic assumes the default adapter retry policy; an adapter\n * configured with more retries can need more than it reserves.\n *\n * @see packages/server/src/writer.ts (`#withCommitHold`)\n */\nexport const COMMIT_RESOLUTION_RESERVE: number = 2 * STORAGE_RETRY_MAX_ATTEMPTS;\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 (measured at 150-360 entries at\n * steady state on the free-tier profile).\n *\n * 16 bounds CONCURRENCY, not the per-request total: a walk still issues\n * one GET per live-tail entry, 16 at a time, and every GET is charged to\n * the invocation's request ledger, which refuses a read whose tail does\n * not fit the host's limit. On Workers the platform also caps an\n * invocation at 6 simultaneous outgoing connections, R2 binding calls\n * included, so the walk runs at most 6 at a time there whatever this\n * value is. A reader relies on the compactor keeping the live tail short\n * enough that the walk fits; see `docs/spec/scale-ceilings.md`\n * §Per-tier bounds.\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 * Sequence distance retained below `log_seq_start` before `log/<seq>.json`\n * objects become retirable: a rate limit on how fast retirement approaches the\n * live floor.\n *\n * Folded entries stay readable below the floor for this long, which is what a\n * windowed commit (`Writer#readFoldedWindow`, for an insert guard or an\n * admission re-check whose read predates a fold) needs to finish rather than\n * refuse with `WriteConflict`; it reads at most the entries a fold absorbed\n * between two reads in one request, far fewer than 1024. The value is a\n * literal: it carries no derivation, and shrinking it is a measured change of\n * its own.\n *\n * **This window is NOT a paused-writer fence, and no safety property may be\n * derived from it.** It is a cost margin and a rate limit on how fast\n * retirement approaches the live floor — nothing more. The withdrawn argument\n * was that a certified-deleted slot needs `log_seq_start` to advance by more\n * than this window \"during one in-flight commit\". The arithmetic is correct and\n * the quantifier is vacuous: one in-flight commit bounds no wall-clock and no\n * commit count, so this is a rate x duration assumption expressed in sequences,\n * the same class as `GC_GRACE_PERIOD_MILLIS` in seconds. Lowering the value on\n * cost grounds costs windowed-commit headroom and retirement smoothness; it\n * does not weaken a safety proof, because there was never one here.\n *\n * Withdrawing the claim does not leave the schedule open, because the commit\n * path closes it directly. After the committing `log/<seq>` create resolves,\n * `Writer#assertCommitAboveDeleteFloor` re-reads `current.json` and fails a\n * create that won at a `seq` below `min(log_delete_floor, log_seq_start)` with\n * `BaerlyError{code:\"AmbiguousCommit\"}`, rather than acknowledging a mutation\n * no reader can see. That check keys on the certified delete floor, not on this\n * window, which is exactly why the window may keep being a cost margin without\n * carrying a safety obligation. Do not re-derive a fence from this value.\n *\n * @see packages/server/src/writer.ts (`Writer#assertCommitAboveDeleteFloor`)\n * @see packages/server/src/log-retention.ts\n * @see docs/spec/sync-protocol.md invariant 12\n * @see docs/adr/002-ephemeral-coordination.md § Closed paths\n */\nexport const LOG_RETENTION_SEQ_WINDOW: number = 1024;\n\n/**\n * Maximum log-object DELETEs a retention pass may attempt on one write tick.\n * Twenty keeps a GC tick plus retirement at 48 calls (144 with every call\n * retried), inside Workers Free's 900-call R2 binding limit, and drains faster\n * than the fold floor advances in steady state.\n *\n * `retireLogRange` is the pass that spends this budget. Every maintenance\n * trigger runs it via the shared `retireLogs` helper in `maintenance.ts`:\n * `runScheduledMaintenance` after its GC phase, and `runBoundedMaintenance`\n * both on the hard-GC early-return path and as its final step. The combined\n * per-tick storage-call arithmetic, against the worst cases `maintenance.ts`'s\n * `CLOUDFLARE_FREE_TIER` JSDoc documents (fault-free; times\n * {@link STORAGE_RETRY_MAX_ATTEMPTS} with every call retried):\n *\n * - One retirement pass, worst case, is 23 calls: 1 advisory-gate GET\n * + `casUpdateCurrentJson`'s own GET + 1 CAS PUT + up to 20 DELETEs.\n * - A maximally contended write-tick GC including the retirement gate read\n * is 26 storage operations, pinned exactly by `maintenance-budget.test.ts`.\n * When the gate finds work, the pass adds its CAS read + CAS write + up to\n * 20 DELETEs on top (48, or 144 retried).\n * - A compaction pass is ≤49, so compact + retirement would be 72. **Retirement\n * cannot share a tick with a fold**: in `\"single\"` phase mode a write-tick\n * fold returns before the runner's retirement step, and\n * `maintenance-budget.test.ts` pins that a fold tick issues zero retirement\n * storage ops.\n * - The write-tick host request also spends one `current.json` GET on the\n * commit path's certified-delete-floor check, outside the tick's pinned\n * figures above. Nothing here changes the value 20: retirement never\n * shares a tick with a fold, so the DELETE budget only ever stacks onto a\n * GC tick.\n *\n * A pass whose range is empty returns `{deleted: 0}` and spends 1 GET. Its\n * observability is the `db.log_retention.deleted_total` counter `retireLogs`\n * emits per pass, so a permanently-stalled retirement (a floor wedged at the\n * live floor) is visible as a counter that stays flat while the log object\n * count grows.\n *\n * @see packages/server/src/log-retention.ts\n * @see packages/server/src/maintenance.ts (`retireLogs`)\n */\nexport const LOG_RETENTION_MAX_DELETES_PER_TICK: number = 20;\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 STORAGE_RETRY_THROTTLE_BASE_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 * Fraction of the GC grace one `runGc` pass may spend between the\n * `current.json` read its DELETEs rest on and each DELETE batch. Once\n * the elapsed time exceeds `graceMillis * GC_PASS_GRACE_FRACTION`, the\n * pass issues no further DELETEs and leaves the remaining due\n * candidates in `gc/pending.json` for a later pass, which re-reads the\n * manifest.\n *\n * Why 1/10:\n * - **A live pass never trips it.** Against the 7-day default the\n * budget is ~16.8 hours, and a pass on every first-class host lasts\n * seconds. Only a paused or starved process crosses it.\n * - **It bounds how stale a DELETE's liveness proof can be.** It\n * matters for the legacy `stale-log` arm, whose DELETE can rest on\n * the pass's first `current.json` read: a candidate is due no earlier\n * than its mark plus the grace, so a DELETE issued within `f` of the\n * grace after that read rests on one taken at least `(1 - f)` of the\n * grace after the mark. An `orphan-snapshot` DELETE always rests on\n * the sweep-time re-read, taken after the candidate came due, so a\n * full grace after its mark.\n *\n * In-band, by design: one clock comparison per DELETE batch, no lease\n * and no knob. Elapsed time is the larger of one node's wall-clock and\n * monotonic readings, so neither cross-node skew nor a backward clock\n * correction shortens it, and a suspend the monotonic clock skips still\n * shows on the wall clock. The after-the-mark figures rest on `due_at`\n * and so keep invariant 14's wall-clock limitation. A pass with\n * `graceMillis: 0` (tests only) has no grace to keep a fraction of and\n * is not bounded.\n *\n * @see docs/spec/sync-protocol.md (invariant 14)\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_PASS_GRACE_FRACTION: number = 1 / 10;\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 * Keys per LIST response page on every in-tree object-store adapter:\n * S3 and GCS `max-keys` and R2 binding `limit` all cap at 1000. `runGc`\n * widens its orphan-snapshot mark window past already-pending keys only\n * up to this size, so the widening never adds a full LIST page (a\n * provider may still truncate a page short and cost another request).\n *\n * @see packages/server/src/gc.ts\n * @see docs/spec/storage-compatibility.md\n */\nexport const GC_MARK_LIST_PAGE_KEYS: number = 1000;\n\n/**\n * Bounded retry cap for the `gc/pending.json` CAS read-modify-write\n * loop in {@link casUpdateGcPending}. On `WriteConflict` (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 `WriteConflict`. 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/spec/scale-ceilings.md for the derivation.\n *\n * @see docs/spec/scale-ceilings.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 exceed the CF-free budget on every fold\n * (round-4 Tier-1). `gcMaxMarks` bounds each LIST classification window and the resulting\n * ledger growth; `gcMaxSweeps` bounds DELETEs. Cadence is BOUNDARY-CROSSING (§3.1), not\n * 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 keys classified per GC category per write-tick pass. Bounds the LIST window and\n * the candidate-ledger growth it can cause.\n *\n * @see packages/server/src/maintenance.ts\n */\nexport const WRITE_TICK_GC_MAX_MARKS: number = 20;\n\n/**\n * Maximum candidate DELETEs per write-tick pass.\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 * Cloudflare Free scheduled-compactor tail-discovery budget (`P`). A\n * prior-snapshot fold pass costs 1 GET current + P GETs tail probe +\n * 1 GET prior snapshot + N GETs log + 1 PUT snapshot + 1 PUT current\n * = 4 + N + P storage operations. With P=25 and the Free profile's\n * N=20 slice, the worst pass is 49 operations, 147 with every call\n * retried, inside the 900 a Free invocation may spend through the R2\n * binding ({@link CF_FREE_INTERNAL_REQUEST_LIMIT}). Through `fetch` (45)\n * the pass lowers its probe to what the ledger leaves after the fold\n * ({@link COMPACT_FOLD_WRITE_REQUESTS}), 21 GETs, and fits in 45; see\n * `CLOUDFLARE_FREE_TIER`. Kept at 25\n * because Free CPU, not the request count, binds first on the binding,\n * and the maintenance-backlog baselines were measured at it.\n *\n * @see packages/server/src/maintenance.ts\n * @see packages/server/src/maintenance-budget.test.ts\n */\nexport const CF_FREE_COMPACT_TAIL_PROBE_GETS: number = 25;\n\n/**\n * Cloudflare Paid scheduled-compactor tail-discovery budget (`P`) for\n * `CLOUDFLARE_PAID_TIER`. Without one, the scheduled probe may walk up to\n * {@link LOG_FORWARD_PROBE_CAP} (100,000) GETs past a stale `tail_hint`,\n * which no Paid invocation can issue: the request ledger refuses the pass\n * at {@link CF_PAID_REQUEST_LIMIT} and nothing folds. With a budget, a\n * pass that exhausts it checkpoints the certified lower bound in\n * `current.json` and the next pass resumes there.\n *\n * With the Paid profile's per-pass slice\n * `N` = {@link NODE_MAINTENANCE_FOLD_ENTRIES_PER_PASS} (200), the worst\n * pass is `4 + N + P` = 1,204 storage calls, 3,612 with every call retried\n * {@link STORAGE_RETRY_MAX_ATTEMPTS} times, well inside 9,000. 1,000 is\n * five slices of discovery per pass: large enough that a pass behind by\n * a normal backlog still folds, small enough that a scheduled compact, GC\n * and retirement pass together stay under the limit at full retries.\n *\n * @see packages/server/src/maintenance.ts (`CLOUDFLARE_PAID_TIER`)\n * @see packages/server/src/maintenance-budget.test.ts\n */\nexport const CF_PAID_COMPACT_TAIL_PROBE_GETS: number = 1000;\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 * Storage requests a write-tick fold issues besides its log GETs, on its\n * common path (every call answered first time, no concurrent writer): the\n * `current.json` GET, one tail-probe GET at the writer's observed tail, the\n * prior-snapshot GET, the snapshot PUT and the `current.json` CAS PUT. A\n * fold of `e` entries costs `5 + e` after the runner's own `current.json`\n * GET (the `6 + e` in {@link CF_FREE_FETCH_FOLD_AT_TAIL_ENTRIES}'s\n * derivation counts that GET too).\n *\n * `runBoundedMaintenance` skips the fold when the invocation's request\n * ledger has less than this plus the tail it would fold left. Retries and\n * a tail a concurrent writer lengthened can still overrun; the ledger\n * refuses that call before it is sent and the next tick folds again.\n *\n * @see packages/server/src/maintenance.ts (`runBoundedMaintenance`)\n */\nexport const MAINTENANCE_FOLD_BASE_REQUESTS: number = 5;\n\n/**\n * Storage writes a folding `compact()` pass issues after its log GETs: the\n * snapshot PUT and the `current.json` CAS PUT. A bounded scheduled compact\n * (`maxTailProbeGets` set) reserves these, the prior-snapshot GET and its\n * `maxEntriesPerRun` log GETs out of what the invocation's request ledger\n * has left after its `current.json` GET, and probes the tail with the rest\n * (at most `maxTailProbeGets`). On Workers Free over `fetch`\n * ({@link CF_FREE_EXTERNAL_REQUEST_LIMIT} = 45, N = 20) that leaves a\n * 21-GET probe, so a pass behind a stale `tail_hint` folds in 45 calls\n * instead of being refused at call 46 before it writes anything.\n *\n * @see packages/server/src/compactor.ts\n */\nexport const COMPACT_FOLD_WRITE_REQUESTS: number = 2;\n\n/**\n * Storage requests a write-tick GC slice issues besides its sweep DELETEs,\n * on its common path: the `current.json` GET, the `gc/pending.json` GET,\n * one snapshot LIST page, the fresh `current.json` GET before a due sweep,\n * and the pending CAS (GET + PUT). A slice sweeping `S` costs `6 + S`.\n * Contention adds at most 6 (the pending-bootstrap race, two more CAS\n * attempts), the `12 + S` worst case in `CLOUDFLARE_FREE_TIER`'s JSDoc.\n *\n * `runBoundedMaintenance` lowers the slice's sweep cap to what the\n * invocation's request ledger has left after this, and skips the slice\n * when not even this is left. A deferred sweep stays pending for the next\n * slice.\n *\n * @see packages/server/src/maintenance.ts (`runBoundedMaintenance`)\n */\nexport const MAINTENANCE_GC_BASE_REQUESTS: number = 6;\n\n/**\n * Most storage requests a log-retirement pass can be charged before its\n * floor CAS lands: the advisory `current.json` GET and the CAS's own GET,\n * each up to {@link STORAGE_RETRY_MAX_ATTEMPTS} attempts, plus the CAS PUT,\n * which an If-Match PUT sends once. 7 at 3 attempts.\n *\n * `retireLogRange` moves `log_delete_floor` past the range BEFORE it\n * DELETEs it, and the next pass starts at the floor, so a DELETE refused\n * after the CAS leaks that log object for good. `runBoundedMaintenance`\n * therefore caps the pass at `(remaining - this) / STORAGE_RETRY_MAX_ATTEMPTS`\n * DELETEs, so every DELETE can spend all its attempts, and skips the pass\n * when that leaves none. The range not retired stays retirable.\n *\n * @see packages/server/src/maintenance.ts (`runBoundedMaintenance`)\n * @see packages/server/src/log-retention.ts (`retireLogRange`)\n */\nexport const MAINTENANCE_RETIRE_PRE_FLOOR_REQUESTS: number = 2 * STORAGE_RETRY_MAX_ATTEMPTS + 1;\n\n/**\n * Storage requests the write tick's `tail_hint` refresh issues: one\n * non-retrying `casUpdateCurrentJson` (GET + PUT). `runBoundedMaintenance`\n * skips the refresh when the invocation's request ledger has less left; a\n * later tick refreshes instead.\n *\n * @see packages/server/src/maintenance.ts (`runBoundedMaintenance`)\n */\nexport const MAINTENANCE_TAIL_HINT_REFRESH_REQUESTS: number = 2;\n\n/**\n * Live-tail length at which the write tick folds under the `cf-free`\n * profile when the Worker reaches its bucket through `fetch` (S3 over\n * HTTP) rather than the R2 binding, whatever the tail-to-snapshot ratio.\n * The Cloudflare adapter detects that from the storage it was given and\n * threads this as `foldAtTailEntries`, with\n * {@link CF_FREE_FETCH_GC_MAX_SWEEPS}; Free with the R2 binding, `cf-paid`,\n * and Node keep the ratio trigger alone.\n *\n * Workers Free + S3 is not a supported host. A Worker cannot tell Free\n * from Paid, so `cf-free` caps storage over `fetch` at\n * {@link CF_FREE_EXTERNAL_REQUEST_LIMIT} calls: a request past Free's 50\n * gets a typed `CapacityExceeded` instead of the platform throwing at call\n * 51. This trigger keeps ordinary requests inside that cap, including a\n * Paid Worker on S3 that has not set `cf-paid`.\n *\n * **Why the ratio trigger fails there.** Every storage call there is\n * charged to the `external` pool, {@link CF_FREE_EXTERNAL_REQUEST_LIMIT}\n * (45) of Free's 50 external subrequests per invocation, leaving 5 for the\n * verifier and platform. The Cloudflare limits page counts\n * subrequests per invocation and does not exempt `ctx.waitUntil` work, so\n * the tick a write dispatches is assumed to share the write's cap. A write\n * and a read both replay the live tail, one GET per entry, so a request\n * costs at least its tail. The ratio trigger first folds near 512 entries\n * (`MAINTENANCE_MIN_LIVE_BYTES` / 128-byte entries) and no sooner than\n * {@link WRITE_TICK_MIN_ENTRIES_TO_COMPACT} (50): at that tail an insert\n * alone costs 57 calls, so the fold never fits and every read fails once\n * the tail passes ~41.\n *\n * **Derivation of 7.** From `request-counts.json` (100-doc snapshot, live\n * tail `t`): an insert, an update and a delete each cost `7 + t`, whatever\n * indexes the collection declares; the commit's only write is its log\n * create. A fold of `e` entries costs `6 + e`. A fold and GC never share a\n * tick (`phasesPerTick: \"single\"`), so a request costs its route plus one\n * of:\n *\n * - the fold, triggered at tail `T`, or `T + 1` when the hard-GC guard\n * pre-empts it: at most `14 + 2T`, 28 at `T = 7`;\n * - a GC slice sweeping `D` = {@link CF_FREE_FETCH_GC_MAX_SWEEPS} due\n * snapshots, plus log retirement, including a write whose tail reaches\n * `T + 1` while the hard-GC guard pre-empts the fold.\n *\n * The Worker adds no Cache API calls. The `free-fetch:*` cells measure\n * inserts, cold updates and a mixed rotation through a full cycle of\n * fold and GC phases with\n * every GC slice sweeping its cap; the worst is 30 at `T = 7`,\n * `D = 3`, set by the GC arm. `T = 8`, `D = 2` would only match snapshot\n * creation at the guaranteed GC cadence; `T = 7`, `D = 3` leaves sweep\n * throughput headroom. The 15 calls of room left are deliberately unspent:\n * a later fold trigger moves the snapshot-creation rate and the GC\n * throughput argument on {@link CF_FREE_FETCH_GC_MAX_SWEEPS}, so raising\n * `T` is a measured change of its own.\n * The longest live tail a read then sees is `T + 1` = 8: any read, with or\n * without declared indexes (`$in` included), costs 11. Every point read\n * pays this storage-backed cost, even when repeated.\n * Retried calls (up to `STORAGE_RETRY_MAX_ATTEMPTS` each) are outside this\n * budget.\n *\n * Changing this value, a fold or GC cost, or the GC cadence moves the\n * `free-fetch:*` cells; `tests/unit/request-counts.test.ts` asserts they\n * stay within 45.\n *\n * @see packages/adapter-cloudflare/src/worker.ts (`cfMaintenanceDispatch`)\n * @see tests/fixtures/request-count-free-fetch.ts\n * @see https://developers.cloudflare.com/workers/platform/limits/#subrequests\n */\nexport const CF_FREE_FETCH_FOLD_AT_TAIL_ENTRIES: number = 7;\n\n/**\n * Most replaced snapshots one write-tick GC slice deletes under the\n * `cf-free` profile when storage is reached through `fetch`; replaces\n * {@link WRITE_TICK_GC_MAX_SWEEPS} (10) there. Each DELETE is one of the\n * request's external subrequests, and a full 10-delete slice on top of the\n * write that dispatched it exceeds the 45-call budget at the tail lengths a\n * write tick folds from. At 3 every `free-fetch:*` cell fits with room to\n * spare at {@link CF_FREE_FETCH_FOLD_AT_TAIL_ENTRIES} (derivation there);\n * the sweep stays at 3 because it is sized by the throughput argument below,\n * which a larger sweep only widens.\n *\n * **Sweep throughput must outrun the fold rate.** Every landed fold\n * replaces one snapshot, so a collection produces at most one sweep\n * candidate per `T` commits (`T` = the fold trigger). On\n * `phasesPerTick: \"single\"` a fold may pre-empt a cadence GC tick but never\n * the hard-GC tick, which runs once per\n * `WRITE_TICK_GC_INTERVAL * GC_STARVATION_GUARD` = 16 commits, so the\n * guaranteed sweep rate alone must cover it:\n *\n * D / 16 > 1 / T, i.e. D > 16 / T = 2.3 at T = 7.\n *\n * `D = 3` clears that with about 31% margin before counting the cadence\n * GC ticks folds do not pre-empt. This sizes the sweep only; it assumes\n * marking keeps pace with the fold rate.\n *\n * @see packages/adapter-cloudflare/src/worker.ts (`cfMaintenanceDispatch`)\n */\nexport const CF_FREE_FETCH_GC_MAX_SWEEPS: number = 3;\n\n/**\n * The scheduled pass's own `minEntriesToCompact` floor (`runMaintenancePass`,\n * which `runScheduledMaintenance` runs), applied when no\n * `options.compact.minEntriesToCompact` is set. Deliberately NOT\n * `DEFAULT_MIN_TO_COMPACT` (compact()'s own 100) or\n * {@link WRITE_TICK_MIN_ENTRIES_TO_COMPACT} (50): both of those floors exist\n * for the IN-BAND write tick, where a write is not a scheduling decision and\n * folding on every one would thrash snapshot rewrites. A scheduler that\n * fires has already decided it is time to do work, so the only live tail\n * worth leaving unfolded is none — a count floor on the scheduled path\n * parks a low-write collection's tail permanently between the floor and\n * the reads' per-entry GET cost (measured: a 36-entry tail costing 36 S3\n * GETs, ~1.2s, on every read because a 100-floor cron tick skipped it for\n * months; a consumer independently converged on 1). Each fold rewrites\n * the whole snapshot, so write-amplification-sensitive callers can still\n * raise it via `options.compact.minEntriesToCompact`; see\n * docs/spec/sync-protocol.md § Maintenance runtime model.\n *\n * @see packages/server/src/maintenance.ts\n */\nexport const SCHEDULED_MIN_ENTRIES_TO_COMPACT: number = 1;\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 performs bounded fold work plus bounded GC LIST classification and DELETE sweeps\n * against a co-located S3/R2 — sub-second on the occasional boundary write at a 10×\n * 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\n * here would reintroduce as multi-second commit stalls. Raise the snapshot ceiling separately\n * via `BAERLY_MAINTENANCE_MAX_FOLD_BYTES`; these caps slice the per-pass work, not the\n * ceiling.\n *\n * @see packages/adapter-node/src/server.ts\n * @see packages/server/src/maintenance.ts\n * @see docs/spec/scale-ceilings.md\n */\nexport const NODE_MAINTENANCE_FOLD_ENTRIES_PER_PASS: number = 200;\n\n/** Node-tier per-category LIST classification/ledger-growth cap. 10× CF-free. @see {@link NODE_MAINTENANCE_FOLD_ENTRIES_PER_PASS} */\nexport const NODE_MAINTENANCE_GC_MAX_MARKS: number = 200;\n\n/** Node-tier candidate DELETE cap per pass. 10× CF-free. @see {@link NODE_MAINTENANCE_FOLD_ENTRIES_PER_PASS} */\nexport const NODE_MAINTENANCE_GC_MAX_SWEEPS: number = 100;\n\n/**\n * Keys per parallel DELETE batch in a `runGc` sweep. The pass checks\n * {@link GC_PASS_GRACE_FRACTION} before each batch, so this is how many\n * DELETEs can land after the bound is crossed.\n *\n * Equal to the largest in-band sweep cap\n * ({@link NODE_MAINTENANCE_GC_MAX_SWEEPS}), so every write-tick GC\n * slice issues its DELETEs as one batch and pays no added round trip.\n * Only a pass with a larger or no sweep cap splits its sweep. Batching\n * changes no request count.\n *\n * @see packages/server/src/gc.ts\n */\nexport const GC_SWEEP_DELETE_BATCH_KEYS: number = NODE_MAINTENANCE_GC_MAX_SWEEPS;\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. A\n * conservative configured budget for the CF-free ~10 ms CPU limit; the ~5.5 ms\n * rebuild-time figure behind it is a sizing estimate, not an observed platform\n * limit. 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/spec/scale-ceilings.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 * is past the conservative budget, and a larger snapshot rebuild may\n * exceed an invocation's CPU or memory resources. If an invocation is\n * terminated mid-rebuild the CAS does not land, so that fold does not\n * advance `log_seq_start`. This value is a configured budget; no\n * particular snapshot size is established to cause termination.\n *\n * Sized at 2× {@link MAINTENANCE_MAX_FOLD_BYTES_DEFAULT}. The ~5.5 ms\n * rebuild estimate for the default (512 KiB) and the linear\n * extrapolation to ~1 MiB are sizing estimates, not observed platform\n * limits; anything strictly larger is simply outside the budget\n * this constant documents. On CF **paid**\n * (raised CPU limits) or Node, a larger ceiling is fine — hence this is\n * a one-time `console.warn` at 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/spec/scale-ceilings.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).\n *\n * This is the **cf-free** value and the shared default. `pnpm bench:fold-ceiling`\n * measures 2048 rows at ~1.5 ms against the ~10 ms free-tier budget (a ~6.6×\n * margin), and the row axis does not reach 10 ms until ~16,384 rows. The value\n * stays at 2048 as a conservative configured budget: a fold that overruns a free\n * isolate's CPU may be terminated before the `current.json` CAS lands — see\n * {@link CF_FREE_MAX_SAFE_FOLD_BYTES}. The\n * larger hosts no longer inherit it; see {@link CF_PAID_MAINTENANCE_MAX_FOLD_ROWS}\n * and {@link NODE_MAINTENANCE_MAX_FOLD_ROWS}.\n *\n * @see docs/spec/scale-ceilings.md\n * @see packages/server/src/maintenance.ts\n */\nexport const MAINTENANCE_MAX_FOLD_ROWS: number = 2048;\n\n/**\n * Snapshot-rebuild byte ceiling `C` for the **cf-paid** profile.\n *\n * A paid isolate's wall is ~128 MB of Worker memory, not CPU — at a 30 s CPU\n * budget the rebuild is never CPU-bound, but a fold holds the old snapshot, the\n * new snapshot, and the tail at once. `pnpm bench:fold-ceiling` measures peak\n * heap at ~2.4× the snapshot on the byte axis, stable across 704 MB–4.3 GB\n * heaps: 8 MiB peaks at ~19.5 MB, a 4× margin under 128 MB. The next grid cell\n * up (16 MiB ⇒ 37.3 MB peak) exceeds that margin, which is what fixes this\n * value.\n *\n * The margin is deliberately tight because overrun is NOT graceful here: an\n * isolate OOM mid-fold would leave the `current.json` CAS unpublished, so that\n * fold would not advance `log_seq_start`.\n *\n * @see docs/spec/scale-ceilings.md\n * @see bench/measurement/fold-ceiling-probe.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 CF_PAID_MAINTENANCE_MAX_FOLD_BYTES: number = 8 * 1024 * 1024;\n\n/**\n * Snapshot-rebuild row ceiling `E` for the **cf-paid** profile. Same 128 MB\n * memory wall and same 4× margin as {@link CF_PAID_MAINTENANCE_MAX_FOLD_BYTES};\n * the row axis costs ~600 B of peak heap per row (measured), so 32,768 rows\n * peaks at ~19.7 MB. The next grid cell up (65,536 rows ⇒ 39.4 MB) exceeds the\n * margin.\n *\n * @see docs/spec/scale-ceilings.md\n */\nexport const CF_PAID_MAINTENANCE_MAX_FOLD_ROWS: number = 32_768;\n\n/**\n * Snapshot-rebuild byte ceiling `C` for the **node** profile.\n *\n * Serverful Node has no per-request cap, and its fold is not abortable —\n * `nodeMaintenanceDispatch` passes no `signal` — so an over-large fold\n * COMPLETES. The failure mode is one slow write, not a stranded CAS. That\n * asymmetry is why Node's ceiling is set generously where cf-free's and\n * cf-paid's are set tightly: UNDER-setting `C` permanently defers the fold,\n * which is the worse failure on every host. Inline fold latency is budgeted by\n * {@link NODE_MAINTENANCE_FOLD_ENTRIES_PER_PASS} (the sliceable tail work), not\n * by this ceiling (the unsliceable snapshot rebuild).\n *\n * 32 MiB is the top of the measured grid, NOT the wall: `pnpm bench:fold-ceiling`\n * reports `grid-exhausted` for this profile at every margin and at every heap\n * from 704 MB up. At a 704 MB heap — the smallest realistic container — a\n * 32 MiB fold peaks at ~37 MB, a ~19× margin. The scaling rule past the grid is\n * `C ≈ heap / 10` (peak ≈ 2.4× snapshot, 4× margin). Finding the real wall\n * needs the byte axis extended past 32 MiB.\n *\n * A separate hard ceiling sits near 512 MB regardless of heap: `encodeJsonBytes`\n * / `decodeJsonBytes` materialize the whole snapshot as a JS string, so a\n * snapshot at V8's `MAX_STRING_LENGTH` throws mid-fold.\n *\n * @see docs/spec/scale-ceilings.md\n * @see bench/measurement/fold-ceiling-probe.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 NODE_MAINTENANCE_MAX_FOLD_BYTES: number = 32 * 1024 * 1024;\n\n/**\n * Snapshot-rebuild row ceiling `E` for the **node** profile. 65,536 rows is the\n * largest row cell with a stable measured peak (~39.4 MB, reproduced within\n * 0.05 MB across four runs); the 131,072-row cell's peak is not yet reliably\n * measurable. Against even a 704 MB heap that is a ~17× margin, consistent with\n * {@link NODE_MAINTENANCE_MAX_FOLD_BYTES} being a measured floor rather than a\n * wall.\n *\n * @see docs/spec/scale-ceilings.md\n */\nexport const NODE_MAINTENANCE_MAX_FOLD_ROWS: number = 65_536;\n\n/**\n * Byte slack the growth refusal keeps under `C` (main-10 G4). A growth write\n * is refused when its projected snapshot bytes would exceed\n * `C - CAPACITY_BYTES_MARGIN`. The projection sizes the snapshot exactly as\n * the compactor encodes it (rows, separators, header) for a known fold end,\n * which is how fold passes are judged against `C` itself. A growth check\n * does not know when its write will fold, so the header's `max_seq` may\n * gain digits by then (at most 16 for a safe integer). 64 bytes covers that\n * with room to spare; `capacity.test.ts` checks the projection against real\n * folds byte for byte.\n *\n * @see docs/spec/scale-ceilings.md\n */\nexport const CAPACITY_BYTES_MARGIN: number = 64;\n\n/**\n * Fraction of a fold ceiling at which an admitted write starts carrying a\n * capacity warning (main-10 G7). The warning fires when the projected\n * snapshot, at its peak over the pending tail and the writes just\n * admitted, holds at least this share of `E` rows or of the `C - margin`\n * bytes the growth refusal compares against. It is a policy choice, not a\n * measurement: 90% leaves roughly 200 rows of runway on Workers Free's\n * 2,048-row `E`, enough for an app to react before the first\n * `CapacityExceeded`, and about 10% of `C` in bytes. The warning is a\n * pure function of `current.json` and the tail, so it clears the moment\n * that state drops back under the threshold.\n *\n * @see packages/server/src/capacity.ts\n */\nexport const CAPACITY_WARN_FRACTION: number = 0.9;\n\n/**\n * `retryAfter` (seconds) on a `MaintenancePending` refusal (main-10 G6).\n * The refused write dispatches one bounded fold before it refuses, and\n * that fold finishes within the same invocation: inline before the\n * response, or in the Cloudflare `ctx.waitUntil` continuation right after\n * it. A retry needs only to land after that, so the value is the smallest\n * non-zero `Retry-After` (RFC 9110 §10.2.3 delay-seconds is a whole\n * number). Each retry runs its own fold pass, so a longer backlog drains\n * across retries rather than within one delay. The HTTP client's caps on\n * those retries are `MAINTENANCE_PENDING_CLIENT_MAX_ATTEMPTS` and\n * `MAINTENANCE_PENDING_CLIENT_MAX_WAIT_MILLIS` in\n * `packages/client/src/request-retry.ts`.\n */\nexport const MAINTENANCE_PENDING_RETRY_AFTER_SECONDS: number = 1;\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 per-pass caps, and its own measured snapshot ceilings. */\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: NODE_MAINTENANCE_MAX_FOLD_BYTES,\n maxFoldRows: NODE_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 CF-free single-phase shape (one phase per request) but has a\n * 9,000-call request ledger limit ({@link CF_PAID_REQUEST_LIMIT}), so it reuses the\n * `NODE_MAINTENANCE_*` per-pass caps.\n *\n * A profile moves RATE and the DEFER THRESHOLD, never the stored data or the\n * query semantics — that is the equivalence invariant, and it is what\n * `tests/integration/maintenance-profile-equivalence.test.ts` proves: a read\n * folds snapshot + live tail, so HOW MUCH a profile has folded is invisible to\n * a reader. Snapshot ceilings therefore differ per host, sized to each host's\n * real wall (see {@link CF_PAID_MAINTENANCE_MAX_FOLD_BYTES}). Operators can\n * still raise `C` out-of-band with `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: CF_PAID_MAINTENANCE_MAX_FOLD_BYTES,\n maxFoldRows: CF_PAID_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 every\n * path where no fold published the hint (originally HR-2, the DEFER\n * path). When the fold defers (snapshot over the configured fold ceiling),\n * when `BAERLY_MAINTENANCE_DISABLE` suppresses both phases, or when a\n * tick runs only GC, the compactor never stamps `tail_hint` via its\n * Step-7 fold CAS — so the gap `(true_tail − tail_hint)` would grow\n * without bound and every read would re-walk the whole live tail via\n * `probeTailFrom`. The runner therefore advances `tail_hint` toward the\n * observed tail with a best-effort `current.json` CAS — but only once\n * per this many writes, so it is NOT a per-commit `current.json` write\n * (which is exactly what single-write commit removed).\n *\n * This interval is a floor on the rate, not a licence to publish more\n * than once per tick. A tick publishes `tail_hint` AT MOST ONCE, by\n * whichever party gets there first, because the interval is measured\n * against the tick's in-memory `current.json` — which no CAS writes back,\n * so a repeat call still reads as due and would rewrite identical bytes.\n * Exactly two parties can publish: the runner's own refresh, and a fold\n * that returned `written` (Step-7 stamped `max(stored, discoveredTail)`\n * with `discoveredTail >= observedTail`). GC is not one of them — a GC\n * tick takes the ordinary rate-limited refresh like any other, which is\n * what makes the bound below unconditional rather than cadence-dependent.\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 applyMergePatch} or\n * {@link coalesceMergePatches}: 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 (applyMergePatch, coalesceMergePatches)\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 * Pre-provisioned, first-attempt Class A commit floor, whatever indexes the\n * collection declares.\n *\n * The floor is the sole committing `log/<seq>` create\n * (`If-None-Match: \"*\"`). It is not a ceiling: provisioning,\n * contention/retries, and in-band maintenance can add Class A operations.\n *\n * @see tests/integration/http-cost-shape.test.ts\n * @see packages/server/src/writer.test.ts\n * @see tests/integration/write-amp.test.ts\n */\nexport const COMMIT_CLASS_A_FLOOR: number = 1;\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\n/**\n * Stands in for \"this manifest has no `generation`\". Both spellings of\n * that state — a `current.json` predating the field, and a bare-LSN\n * cursor minted before this build — decode to this value, so an\n * ordinary string comparison handles them without a fail-open branch.\n * See the truth table in `docs/spec/sync-protocol.md`.\n *\n * `\"-\"` is safe as the sentinel because a real generation is a minted\n * lowercase-hex nonce (`mintGeneration`), and hex contains no `-`. So\n * the sentinel can never collide with a value a manifest actually\n * carries, in either the `/v1/since` cursor codec or the GC candidate\n * fence.\n *\n * Sited HERE rather than next to the cursor codec that first needed\n * it: `constants.ts` is a zero-import leaf, and `runGc` imports this\n * sentinel. Re-exported from `cursor.ts` so existing importers are\n * unaffected. Importing it from `cursor.ts` instead would drag\n * `parseCursor` + `formatCursor` into the `index.js` and\n * `maintenance.js` closures — every consumer paying for a `/v1/since`\n * codec to get one `\"-\"`.\n */\nexport const NO_GENERATION = \"-\";\n\n/**\n * Longest inbound `x-request-id` the adapters carry onto the canonical\n * log line; a longer one is replaced with a generated id. 128 holds\n * every common id format with room to spare (UUID 36, W3C\n * `traceparent` 55, an X-Ray `Root=…;Parent=…;Sampled=…` header ~80)\n * while keeping a caller from inflating every log line it touches.\n */\nexport const MAX_REQUEST_ID_LENGTH = 128;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AA4CA,MAAa,qBAAqB;;;;;;AA6BlC,MAAa,gBAAgB;;;;;;;;;;;;AA4K7B,MAAa,qCAA6C;;;;;;;;;AAU1D,MAAa,iCAAyC;;;;;;;;AAsCtD,MAAa,wBAAgC;;;;;;;;;;AA0E7C,MAAa,wBAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwC7C,MAAa,2BAAmC;;;;;;;;AAgEhD,MAAa,4BAAoC;;;;;;AAiCjD,MAAa,0BAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgC/C,MAAa,yBAAiC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoC9C,MAAa,yBAAiC,IAAI;;;;;;;;;;AAWlD,MAAa,4BAAoC;;;;;;;;;;;AAYjD,MAAa,yBAAiC;;;;;;;AAqC9C,MAAa,6BAAqC;;;;;;;;;;;;;;;;;;;;;AAyGlD,MAAa,kCAA0C;;;;;;;;;;;AA8QvD,MAAa,qCAA6C;;;;;;;;;;;;;;;;;;;;;;;;AA0B1D,MAAa,8BAAsC;;;;;;;;;;;;;;;;;;AAmBnD,MAAa,4BAAoC;;;;;;;;;;;;;;;;;;;AAqBjD,MAAa,qCAA6C;;;;;;;;;;AAW1D,MAAa,oCAA4C;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BzD,MAAa,kCAA0C;;;;;;;;;;;AAYvD,MAAa,iCAAyC;;;;;;;;;;;;;;;AA+BtD,MAAa,yBAAiC;;AA4B9C,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;;;;;;;;;;;;;;;;;;AAmBA,MAAa,8BAAuD;CAClE,YAAA;CACA,YAAA;CACA,aAAA;CACA,uBAAA;CACA,cAAc;CACd,aAAa;AACf;;;;;;;;AASA,MAAa,mCAA2C;;;;;;;;;;AAgDxD,MAAa,kCAA0C;;;;;;;;;;;;;;;;;AAkBvD,MAAa,uCAA4C,IAAI,IAAI;CAC/D;CACA;CACA;AACF,CAAC;;;;;;;;;;;;AA4CD,MAAa,6BACX;;;;;AAMF,MAAa,gCACX"}
|