@gusto/baerly-storage 0.3.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (141) hide show
  1. package/README.md +157 -92
  2. package/dist/API.md +64 -32
  3. package/dist/CHANGELOG.md +301 -5
  4. package/dist/RECIPES.md +125 -0
  5. package/dist/THIRD-PARTY-LICENSES.txt +22 -96
  6. package/dist/{app-config-BIzyAKzy.d.ts → app-config-DyiFK3_k.d.ts} +43 -11
  7. package/dist/app-config.d.ts +1 -1
  8. package/dist/auth.d.ts +1 -1
  9. package/dist/auth.js +13 -13
  10. package/dist/auth.js.map +1 -1
  11. package/dist/aws4fetch.esm-p7eEzLCs.js +1702 -0
  12. package/dist/aws4fetch.esm-p7eEzLCs.js.map +1 -0
  13. package/dist/baerly.js +35 -15
  14. package/dist/baerly.js.map +1 -1
  15. package/dist/baerly.spec.json +342 -0
  16. package/dist/{client-BJXF3XJA.d.ts → client-Fe8CwB73.d.ts} +3 -3
  17. package/dist/client-react.d.ts +3 -3
  18. package/dist/client-react.js +4 -4
  19. package/dist/client-react.js.map +1 -1
  20. package/dist/client.d.ts +4 -4
  21. package/dist/client.js +3 -3
  22. package/dist/{cloudflare-Cn2ibODt.js → cloudflare-DzKBrUlg.js} +2 -2
  23. package/dist/{cloudflare-Cn2ibODt.js.map → cloudflare-DzKBrUlg.js.map} +1 -1
  24. package/dist/cloudflare.d.ts +49 -6
  25. package/dist/cloudflare.js +55 -21
  26. package/dist/cloudflare.js.map +1 -1
  27. package/dist/config-1tv0-Yzm.js +2693 -0
  28. package/dist/config-1tv0-Yzm.js.map +1 -0
  29. package/dist/constants-CfeMWQWk.js +222 -0
  30. package/dist/constants-CfeMWQWk.js.map +1 -0
  31. package/dist/{cost-BZ_MDBmn.js → cost-DSMIVqzL.js} +42 -43
  32. package/dist/cost-DSMIVqzL.js.map +1 -0
  33. package/dist/{current-json-DsN7FNY1.js → current-json-C6nhPOm1.js} +6 -204
  34. package/dist/current-json-C6nhPOm1.js.map +1 -0
  35. package/dist/{db-CCT6tDfY.d.ts → db-DsPkOVEH.d.ts} +3 -3
  36. package/dist/{deploy-BKKyGlSJ.js → deploy-DonTr-CV.js} +4 -4
  37. package/dist/{deploy-BKKyGlSJ.js.map → deploy-DonTr-CV.js.map} +1 -1
  38. package/dist/dev-vite.d.ts +9 -5
  39. package/dist/dev-vite.js +5 -4
  40. package/dist/dev-vite.js.map +1 -1
  41. package/dist/dev.d.ts +1 -1
  42. package/dist/dev.js +1 -1
  43. package/dist/{doctor-BVU4GNXN.js → doctor-DSIyCDg_.js} +5 -8
  44. package/dist/{doctor-BVU4GNXN.js.map → doctor-DSIyCDg_.js.map} +1 -1
  45. package/dist/{dump-DPEAKub6.js → dump-Bh5k26VQ.js} +9 -32
  46. package/dist/dump-Bh5k26VQ.js.map +1 -0
  47. package/dist/{errors-DOdL95kK.js → errors-Dfa3p78c.js} +25 -5
  48. package/dist/errors-Dfa3p78c.js.map +1 -0
  49. package/dist/{export-BcuCLFFe.js → export-DtF5tDIM.js} +9 -32
  50. package/dist/{export-BcuCLFFe.js.map → export-DtF5tDIM.js.map} +1 -1
  51. package/dist/{fsck-RXgLOaJG.js → fsck-D_djMO5D.js} +10 -33
  52. package/dist/fsck-D_djMO5D.js.map +1 -0
  53. package/dist/{http-Bd4byR4n.js → http-DxM9MflO.js} +123 -35
  54. package/dist/http-DxM9MflO.js.map +1 -0
  55. package/dist/http.d.ts +42 -26
  56. package/dist/http.js +3 -2
  57. package/dist/{index-DnBGSeuU.d.ts → index-0rZcMBwy.d.ts} +2 -2
  58. package/dist/{index-Cmsxx-ZN.d.ts → index-B6oexfOB.d.ts} +7 -7
  59. package/dist/{index-BDceQQi-.d.ts → index-BNRh23K9.d.ts} +4 -4
  60. package/dist/{index-DW7GT6M2.d.ts → index-BYk9oCNf.d.ts} +193 -163
  61. package/dist/index.d.ts +6 -6
  62. package/dist/index.js +4 -4
  63. package/dist/{indexes-Cx7uMXm0.d.ts → indexes-Dn9hbGQG.d.ts} +2 -2
  64. package/dist/{inspect-DhI49PSi.js → inspect-6WZ-pC7-.js} +10 -33
  65. package/dist/inspect-6WZ-pC7-.js.map +1 -0
  66. package/dist/key-Di6yyxFu.js +35 -0
  67. package/dist/key-Di6yyxFu.js.map +1 -0
  68. package/dist/{log-tail-DXeDkWEp.js → log-tail-D98U1JBo.js} +31 -7
  69. package/dist/log-tail-D98U1JBo.js.map +1 -0
  70. package/dist/{maintenance-CWBQpZ2y.js → maintenance-B4Dki6Ig.js} +77 -22
  71. package/dist/maintenance-B4Dki6Ig.js.map +1 -0
  72. package/dist/{maintenance-BkhUr72A.d.ts → maintenance-B_e0T99L.d.ts} +28 -5
  73. package/dist/{maintenance-C_KSkVjd.js → maintenance-C7coQp4c.js} +17 -16
  74. package/dist/maintenance-C7coQp4c.js.map +1 -0
  75. package/dist/maintenance.d.ts +3 -3
  76. package/dist/maintenance.js +3 -3
  77. package/dist/node.d.ts +168 -65
  78. package/dist/node.js +3 -2
  79. package/dist/{normalize-XWY25_sG.js → normalize-rjnZLwS4.js} +2 -2
  80. package/dist/normalize-rjnZLwS4.js.map +1 -0
  81. package/dist/{observability-BYd-RzEx.js → observability-wzs3-BL_.js} +233 -71
  82. package/dist/observability-wzs3-BL_.js.map +1 -0
  83. package/dist/observability.d.ts +2 -2
  84. package/dist/observability.js +1 -1
  85. package/dist/{plan-DIu_B6fy.js → plan-a7PJHBCy.js} +2 -2
  86. package/dist/{plan-DIu_B6fy.js.map → plan-a7PJHBCy.js.map} +1 -1
  87. package/dist/{query-sQNO5vU_.js → query-rAtXNQQB.js} +96 -207
  88. package/dist/query-rAtXNQQB.js.map +1 -0
  89. package/dist/{rebuild-index-DP4CqSSs.js → rebuild-index-BVzQSZlm.js} +9 -32
  90. package/dist/rebuild-index-BVzQSZlm.js.map +1 -0
  91. package/dist/{request-BEF_OvMh.js → request-u0M51mhJ.js} +3 -3
  92. package/dist/{request-BEF_OvMh.js.map → request-u0M51mhJ.js.map} +1 -1
  93. package/dist/{restore-DpQYef6r.js → restore-R-4rbciV.js} +73 -100
  94. package/dist/restore-R-4rbciV.js.map +1 -0
  95. package/dist/runtime-spec-_GTdeSMo.js +391 -0
  96. package/dist/runtime-spec-_GTdeSMo.js.map +1 -0
  97. package/dist/s3-http-B-z8th6O.d.ts +60 -0
  98. package/dist/s3.d.ts +47 -0
  99. package/dist/s3.js +45 -0
  100. package/dist/s3.js.map +1 -0
  101. package/dist/{shared-secret-BJdSwpgw.js → shared-secret-DgEicd3x.js} +13 -5
  102. package/dist/shared-secret-DgEicd3x.js.map +1 -0
  103. package/dist/{src-Db4-qVtM.js → src-CYHFDrKz.js} +51 -8
  104. package/dist/src-CYHFDrKz.js.map +1 -0
  105. package/dist/{src-CWpkSbvJ.js → src-DYZ4H1aF.js} +6 -5
  106. package/dist/src-DYZ4H1aF.js.map +1 -0
  107. package/dist/src-D__mHQmQ.js +2271 -0
  108. package/dist/src-D__mHQmQ.js.map +1 -0
  109. package/dist/{subcommand-CP9NY2J4.js → subcommand-DoDA-K7d.js} +44 -6
  110. package/dist/subcommand-DoDA-K7d.js.map +1 -0
  111. package/dist/time-DUqvFMHq.js +119 -0
  112. package/dist/time-DUqvFMHq.js.map +1 -0
  113. package/dist/{usage-CTfDq9HR.js → usage-DBV1eQHC.js} +7 -22
  114. package/dist/usage-DBV1eQHC.js.map +1 -0
  115. package/dist/wire-izfGZDvr.js.map +1 -1
  116. package/package.json +51 -27
  117. package/dist/config-CGyBopy3.js +0 -5326
  118. package/dist/config-CGyBopy3.js.map +0 -1
  119. package/dist/cost-BZ_MDBmn.js.map +0 -1
  120. package/dist/current-json-DsN7FNY1.js.map +0 -1
  121. package/dist/dump-DPEAKub6.js.map +0 -1
  122. package/dist/errors-DOdL95kK.js.map +0 -1
  123. package/dist/fsck-RXgLOaJG.js.map +0 -1
  124. package/dist/http-Bd4byR4n.js.map +0 -1
  125. package/dist/inspect-DhI49PSi.js.map +0 -1
  126. package/dist/log-tail-DXeDkWEp.js.map +0 -1
  127. package/dist/maintenance-CWBQpZ2y.js.map +0 -1
  128. package/dist/maintenance-C_KSkVjd.js.map +0 -1
  129. package/dist/normalize-XWY25_sG.js.map +0 -1
  130. package/dist/observability-BYd-RzEx.js.map +0 -1
  131. package/dist/query-sQNO5vU_.js.map +0 -1
  132. package/dist/rebuild-index-DP4CqSSs.js.map +0 -1
  133. package/dist/restore-DpQYef6r.js.map +0 -1
  134. package/dist/shared-secret-BJdSwpgw.js.map +0 -1
  135. package/dist/src-CWpkSbvJ.js.map +0 -1
  136. package/dist/src-D24wDpzR.js +0 -6247
  137. package/dist/src-D24wDpzR.js.map +0 -1
  138. package/dist/src-Db4-qVtM.js.map +0 -1
  139. package/dist/subcommand-CP9NY2J4.js.map +0 -1
  140. package/dist/usage-CTfDq9HR.js.map +0 -1
  141. /package/dist/{chunk-EAsCxrDo.js → rolldown-runtime-EAsCxrDo.js} +0 -0
@@ -1,4 +1,165 @@
1
- import { f as DocumentData, m as JSONValue, p as DocumentValue } from "./app-config-BIzyAKzy.js";
1
+ import { f as DocumentData, m as JSONValue, p as DocumentValue } from "./app-config-DyiFK3_k.js";
2
+ //#region packages/protocol/src/errors.d.ts
3
+ /**
4
+ * Discriminator for {@link BaerlyError}. Strings (not subclasses) so they
5
+ * survive cross-realm boundaries (e.g. a Web Worker) and so callers can
6
+ * pattern-match with grep-friendly equality.
7
+ */
8
+ type BaerlyErrorCode = /** Caller-provided config or input is invalid (bad bucket, unsupported credential type, malformed URL, bucket not version-enabled when versioning was requested). */"InvalidConfig" /** Generic S3/HTTP transport failure (5xx, unexpected status, retries exhausted). */ | "NetworkError" /** S3 returned 403. Either credentials are wrong or the bucket policy denies the operation. */ | "AccessDenied" /** Server returned data that didn't parse (malformed XML, non-JSON body where JSON expected). */ | "InvalidResponse" /** Internal invariant violation — should not be reachable. File a bug. */ | "Internal"
9
+ /**
10
+ * Document body failed schema validation. Emitted by the table-API
11
+ * write verbs (`Collection.insert`, `Query.update`, `Collection.replace`) when
12
+ * the body is not valid JSON or contains an array where
13
+ * `DocumentValue` is required; also emitted when a collection has a
14
+ * declared `SchemaValidator` (via `Db.create({ collections })`) and
15
+ * the bound schema rejects the doc. In the schema-rejection case the
16
+ * error carries an `issues` array describing each failure. HTTP layer
17
+ * maps this to 400.
18
+ */
19
+ | "SchemaError"
20
+ /**
21
+ * Write conflicted with current state: CAS retry budget exhausted,
22
+ * duplicate caller-supplied `_id`, or an already-existing guarded
23
+ * storage key. Check `BaerlyError.retriable` to decide whether the
24
+ * same logical operation should be retried.
25
+ */
26
+ | "Conflict"
27
+ /**
28
+ * `Verifier` returned no identity. HTTP server maps to 401.
29
+ * Code is reserved here so the union locks.
30
+ */
31
+ | "Unauthorized"
32
+ /**
33
+ * The addressed resource does not exist. HTTP server maps to 404.
34
+ * Emitted by the row-by-id read / update / delete handlers in
35
+ * `packages/server/src/http/router.ts` when the predicate
36
+ * `{ _id }` matches zero rows. Not a protocol invariant —
37
+ * callers may retry after creating the resource or treat as a
38
+ * miss depending on intent. The CLI maps this to the generic
39
+ * exit-2 "storage error" bucket, not the exit-3 "protocol
40
+ * invariant" bucket.
41
+ */
42
+ | "NotFound"
43
+ /**
44
+ * Request body exceeded the server's size cap. HTTP server maps
45
+ * to 413. Cap is `MAX_BODY_BYTES` (1 MiB today; exported from
46
+ * `packages/server/src/http/router.ts`). The Node adapter
47
+ * enforces during the `node:http` stream pump so the process
48
+ * never materializes a multi-MiB body; Workers also rely on
49
+ * platform-side caps (16 MB free / 100 MB paid).
50
+ */
51
+ | "PayloadTooLarge"
52
+ /**
53
+ * A predicate is structurally well-formed but contradicts itself —
54
+ * no document can match. Emitted by `validateWire` and
55
+ * `mergePredicateWires`. Triggers:
56
+ * - `{ clauses: [{op:"in", field:"priority", value:[]}] }` (empty `in` set)
57
+ * - an `eq` clause with a value outside the residual interval
58
+ * established by range clauses on the same field
59
+ * - merging `{op:"gt", value:10}` with `{op:"lt", value:5}` on the
60
+ * same field (empty interval)
61
+ * - merging two `in` clauses on the same field with empty intersection
62
+ *
63
+ * Conflicting equality across clauses (`eq:"open"` + `eq:"closed"` on
64
+ * the same field) surfaces as `InvalidConfig` rather than this code —
65
+ * the merger treats it as a caller-side configuration bug, not an
66
+ * algebraic contradiction.
67
+ *
68
+ * The HTTP layer treats this as a 400 (caller error). The distinct
69
+ * code lets downstream code short-circuit empty-by-construction
70
+ * without re-running the validator or parsing messages.
71
+ */
72
+ | "UnsatisfiablePredicate"
73
+ /**
74
+ * A `useQuery` callback awaited a recorder terminal
75
+ * (`.get`/`.first`/`.all`/`.count`). The recorder runs once per
76
+ * render to capture the chain shape; it cannot survive an `await`
77
+ * because the proxy doesn't proxy across microtask boundaries. The
78
+ * recorder's terminal returns a thenable whose `.then` throws this
79
+ * error synchronously, converting what would otherwise be a silent
80
+ * spinner-hang into a render-time error the hook surfaces as
81
+ * `status: "error"`. Companion `baerly/no-await-in-use-query` lint
82
+ * flags the pattern at edit time. For compound reads, use
83
+ * `Promise.all` (parallel) or compose two `useQuery` calls with
84
+ * `useQuery.skip` (dependent).
85
+ */
86
+ | "UseQueryAwaitedRecorder"
87
+ /**
88
+ * A write method (`.insert`/`.update`/`.replace`/`.delete`) was
89
+ * called on the recorder inside a `useQuery` callback. Writes
90
+ * inside reads are a programming error; the recorder rejects them
91
+ * synchronously from the discovery pass, before any I/O fires. Use
92
+ * `useMutation()` instead.
93
+ */
94
+ | "UnexpectedWriteInQuery"
95
+ /**
96
+ * A `useMutation()` callback rejected with a non-`BaerlyError`
97
+ * throwable. The hook wraps the original throw under this code so
98
+ * the `error` slot is always a `BaerlyError`; the original value
99
+ * is preserved on `.cause`.
100
+ */
101
+ | "MutationFailed";
102
+ /**
103
+ * The single error class thrown by baerly-storage. Discriminate by `code`, not
104
+ * `instanceof`: the code string survives `JSON.stringify` round-trips
105
+ * across Worker / iframe / postMessage realm boundaries, where each
106
+ * realm has its own `BaerlyError` constructor identity. IDB-restored
107
+ * writes can replay across realms, so `instanceof` would spuriously
108
+ * fail on a structurally-identical error from another realm.
109
+ *
110
+ * @example
111
+ * ```ts
112
+ * try {
113
+ * await db.collection("tickets").insert({ title: "hi" });
114
+ * } catch (err) {
115
+ * if (err instanceof BaerlyError && err.code === "Conflict") {
116
+ * // Check err.retriable; CAS can retry, duplicate _id cannot.
117
+ * }
118
+ * throw err;
119
+ * }
120
+ * ```
121
+ */
122
+ declare class BaerlyError extends Error {
123
+ readonly code: BaerlyErrorCode;
124
+ readonly cause?: unknown;
125
+ /**
126
+ * Structured field-path issues, set only when `code === "SchemaError"`.
127
+ * Each entry's `path` is a dotted-key list (e.g. `["assignee", "team"]`
128
+ * or `["items", 3, "qty"]`) that targets the offending field on the
129
+ * input document. `message` is the validator-emitted human string.
130
+ *
131
+ * The HTTP layer's `mapError` renders these into the 400 body via
132
+ * the existing `HttpErrorEnvelope`; older callers that don't know
133
+ * about `issues` see a plain message-only error and stay correct.
134
+ */
135
+ readonly issues?: ReadonlyArray<{
136
+ readonly path: ReadonlyArray<string | number>;
137
+ readonly message: string;
138
+ }>;
139
+ /**
140
+ * Raw HTTP status, set only by the client-side wire decoder when
141
+ * inflating an `HttpErrorEnvelope` into this class. Server-side
142
+ * throws never set it (the HTTP layer's `mapError` derives the
143
+ * outbound status from `code`). Useful for diagnostics — e.g. to
144
+ * distinguish 404-as-"no such row" from 404-as-"route not found".
145
+ * Discriminate by `code` for behavior; reach for `status` only when
146
+ * you genuinely need the wire value.
147
+ */
148
+ readonly status?: number;
149
+ /** Canonical corrective action; crosses the wire via `HttpErrorEnvelope.error.resolution`. */
150
+ readonly resolution?: string;
151
+ private readonly retriableOverride;
152
+ /**
153
+ * Whether this error instance is retriable. Defaults from `code`, but
154
+ * context-sensitive throw sites can override it.
155
+ */
156
+ get retriable(): boolean;
157
+ constructor(code: BaerlyErrorCode, message: string, cause?: unknown, issues?: ReadonlyArray<{
158
+ readonly path: ReadonlyArray<string | number>;
159
+ readonly message: string;
160
+ }>, status?: number, resolution?: string, retriableOverride?: boolean);
161
+ }
162
+ //#endregion
2
163
  //#region packages/protocol/src/storage/types.d.ts
3
164
  /**
4
165
  * Object-storage abstraction. The protocol kernel writes through
@@ -267,8 +428,9 @@ interface CurrentJsonRead {
267
428
  * The methods on this interface ARE the supported operator surface.
268
429
  * Vocabulary additions (`or`, `not`, `regex`, `ne`, `exists`, ...)
269
430
  * are intentionally absent — calling them is a TS2339 compile
270
- * error, not a runtime rejection. See ADR-002 amendment dated
271
- * 2026-05-26 for the algebra-lock policy.
431
+ * error, not a runtime rejection. The algebra is conjunction-only in
432
+ * perpetuity — see the API surface lock in
433
+ * docs/contributing/conventions/change-discipline.md.
272
434
  *
273
435
  * @template T - the document shape the predicate is keyed against.
274
436
  */
@@ -504,7 +666,7 @@ type _StripIndex<T> = { [K in keyof T as string extends K ? never : K]: T[K] };
504
666
  * today's open-keyed default behavior.
505
667
  * @internal
506
668
  */
507
- type _AllPaths<T, D extends _PathDepth[number] = 4> = [D] extends [never] ? never : T extends object ? keyof _StripIndex<T> & string extends never ? string : { [K in keyof _StripIndex<T> & string]: _IsPathLeaf<T[K]> extends true ? K : K | `${K}.${_AllPaths<NonNullable<T[K]>, _PathDepth[D]>}` }[keyof _StripIndex<T> & string] : never;
669
+ type _AllPaths<T, D extends _PathDepth[number] = 4> = [D] extends [never] ? never : T extends object ? keyof _StripIndex<T> & string extends never ? string : { [K in keyof _StripIndex<T> & string]: _IsPathLeaf<NonNullable<T[K]>> extends true ? K : K | `${K}.${_AllPaths<NonNullable<T[K]>, _PathDepth[D]>}` }[keyof _StripIndex<T> & string] : never;
508
670
  /**
509
671
  * Legal dotted-path keys over `T`, with the root-level `_id` filtered
510
672
  * out so the top-level shape no longer accepts `{ _id: "x" }`. Nested
@@ -667,158 +829,16 @@ interface Query<T extends DocumentData = DocumentData> {
667
829
  }>;
668
830
  }
669
831
  //#endregion
670
- //#region packages/protocol/src/errors.d.ts
671
- /**
672
- * Discriminator for {@link BaerlyError}. Strings (not subclasses) so they
673
- * survive cross-realm boundaries (e.g. a Web Worker) and so callers can
674
- * pattern-match with grep-friendly equality.
675
- */
676
- type BaerlyErrorCode = /** Caller-provided config or input is invalid (bad bucket, unsupported credential type, malformed URL, bucket not version-enabled when versioning was requested). */"InvalidConfig" /** Generic S3/HTTP transport failure (5xx, unexpected status, retries exhausted). */ | "NetworkError" /** S3 returned 403. Either credentials are wrong or the bucket policy denies the operation. */ | "AccessDenied" /** Server returned data that didn't parse (malformed XML, non-JSON body where JSON expected). */ | "InvalidResponse" /** Internal invariant violation — should not be reachable. File a bug. */ | "Internal"
677
- /**
678
- * Document body failed schema validation. Emitted by the table-API
679
- * write verbs (`Collection.insert`, `Query.update`, `Collection.replace`) when
680
- * the body is not valid JSON or contains an array where
681
- * `DocumentValue` is required; also emitted when a collection has a
682
- * declared `SchemaValidator` (via `Db.create({ collections })`) and
683
- * the bound schema rejects the doc. In the schema-rejection case the
684
- * error carries an `issues` array describing each failure. HTTP layer
685
- * maps this to 400.
686
- */
687
- | "SchemaError"
688
- /**
689
- * CAS lost on `current.json`. Caller decides whether to retry.
690
- * Surfaces in the collection API and HTTP layer.
691
- */
692
- | "Conflict"
693
- /**
694
- * `Verifier` returned no identity. HTTP server maps to 401.
695
- * Code is reserved here so the union locks.
696
- */
697
- | "Unauthorized"
698
- /**
699
- * The addressed resource does not exist. HTTP server maps to 404.
700
- * Emitted by the row-by-id read / update / delete handlers in
701
- * `packages/server/src/http/router.ts` when the predicate
702
- * `{ _id }` matches zero rows. Not a protocol invariant —
703
- * callers may retry after creating the resource or treat as a
704
- * miss depending on intent. The CLI maps this to the generic
705
- * exit-2 "storage error" bucket, not the exit-3 "protocol
706
- * invariant" bucket.
707
- */
708
- | "NotFound"
709
- /**
710
- * Request body exceeded the server's size cap. HTTP server maps
711
- * to 413. Cap is `MAX_BODY_BYTES` (1 MiB today; exported from
712
- * `packages/server/src/http/router.ts`). The Node adapter
713
- * enforces during the `node:http` stream pump so the process
714
- * never materializes a multi-MiB body; Workers also rely on
715
- * platform-side caps (16 MB free / 100 MB paid).
716
- */
717
- | "PayloadTooLarge"
718
- /**
719
- * A predicate is structurally well-formed but contradicts itself —
720
- * no document can match. Emitted by `validateWire` and
721
- * `mergePredicateWires`. Triggers:
722
- * - `{ clauses: [{op:"in", field:"priority", value:[]}] }` (empty `in` set)
723
- * - an `eq` clause with a value outside the residual interval
724
- * established by range clauses on the same field
725
- * - merging `{op:"gt", value:10}` with `{op:"lt", value:5}` on the
726
- * same field (empty interval)
727
- * - merging two `in` clauses on the same field with empty intersection
728
- *
729
- * Conflicting equality across clauses (`eq:"open"` + `eq:"closed"` on
730
- * the same field) surfaces as `InvalidConfig` rather than this code —
731
- * the merger treats it as a caller-side configuration bug, not an
732
- * algebraic contradiction.
733
- *
734
- * The HTTP layer treats this as a 400 (caller error). The distinct
735
- * code lets downstream code short-circuit empty-by-construction
736
- * without re-running the validator or parsing messages.
737
- */
738
- | "UnsatisfiablePredicate"
739
- /**
740
- * A `useQuery` callback awaited a recorder terminal
741
- * (`.get`/`.first`/`.all`/`.count`). The recorder runs once per
742
- * render to capture the chain shape; it cannot survive an `await`
743
- * because the proxy doesn't proxy across microtask boundaries. The
744
- * recorder's terminal returns a thenable whose `.then` throws this
745
- * error synchronously, converting what would otherwise be a silent
746
- * spinner-hang into a render-time error the hook surfaces as
747
- * `status: "error"`. Companion `baerly/no-await-in-use-query` lint
748
- * flags the pattern at edit time. For compound reads, use
749
- * `Promise.all` (parallel) or compose two `useQuery` calls with
750
- * `useQuery.skip` (dependent).
751
- */
752
- | "UseQueryAwaitedRecorder"
753
- /**
754
- * A write method (`.insert`/`.update`/`.replace`/`.delete`) was
755
- * called on the recorder inside a `useQuery` callback. Writes
756
- * inside reads are a programming error; the recorder rejects them
757
- * synchronously from the discovery pass, before any I/O fires. Use
758
- * `useMutation()` instead.
759
- */
760
- | "UnexpectedWriteInQuery"
761
- /**
762
- * A `useMutation()` callback rejected with a non-`BaerlyError`
763
- * throwable. The hook wraps the original throw under this code so
764
- * the `error` slot is always a `BaerlyError`; the original value
765
- * is preserved on `.cause`.
766
- */
767
- | "MutationFailed";
768
- /**
769
- * The single error class thrown by Baerly. Discriminate by `code`, not
770
- * `instanceof`: the code string survives `JSON.stringify` round-trips
771
- * across Worker / iframe / postMessage realm boundaries, where each
772
- * realm has its own `BaerlyError` constructor identity. IDB-restored
773
- * writes can replay across realms, so `instanceof` would spuriously
774
- * fail on a structurally-identical error from another realm.
775
- *
776
- * @example
777
- * ```ts
778
- * try {
779
- * await db.collection("tickets").insert({ title: "hi" });
780
- * } catch (err) {
781
- * if (err instanceof BaerlyError && err.code === "Conflict") {
782
- * // ... CAS lost; retry
783
- * }
784
- * throw err;
785
- * }
786
- * ```
787
- */
788
- declare class BaerlyError extends Error {
789
- readonly code: BaerlyErrorCode;
790
- readonly cause?: unknown;
791
- /**
792
- * Structured field-path issues, set only when `code === "SchemaError"`.
793
- * Each entry's `path` is a dotted-key list (e.g. `["assignee", "team"]`
794
- * or `["items", 3, "qty"]`) that targets the offending field on the
795
- * input document. `message` is the validator-emitted human string.
796
- *
797
- * The HTTP layer's `mapError` renders these into the 400 body via
798
- * the existing `HttpErrorEnvelope`; older callers that don't know
799
- * about `issues` see a plain message-only error and stay correct.
800
- */
801
- readonly issues?: ReadonlyArray<{
802
- readonly path: ReadonlyArray<string | number>;
803
- readonly message: string;
804
- }>;
832
+ //#region packages/protocol/src/storage/memory.d.ts
833
+ /** Options for {@link MemoryStorage}. */
834
+ interface MemoryStorageOptions {
805
835
  /**
806
- * Raw HTTP status, set only by the client-side wire decoder when
807
- * inflating an `HttpErrorEnvelope` into this class. Server-side
808
- * throws never set it (the HTTP layer's `mapError` derives the
809
- * outbound status from `code`). Useful for diagnostics — e.g. to
810
- * distinguish 404-as-"no such row" from 404-as-"route not found".
811
- * Discriminate by `code` for behavior; reach for `status` only when
812
- * you genuinely need the wire value.
836
+ * Acknowledge the store is intentionally ephemeral — required to
837
+ * construct in a detected deployment ({@link isDeployedEnv}); ignored in
838
+ * dev/test. Env equivalent: `BAERLY_ALLOW_EPHEMERAL_STORAGE=true`.
813
839
  */
814
- readonly status?: number;
815
- constructor(code: BaerlyErrorCode, message: string, cause?: unknown, issues?: ReadonlyArray<{
816
- readonly path: ReadonlyArray<string | number>;
817
- readonly message: string;
818
- }>, status?: number);
840
+ ephemeral?: boolean;
819
841
  }
820
- //#endregion
821
- //#region packages/protocol/src/storage/memory.d.ts
822
842
  /**
823
843
  * In-memory `Storage`. The randomized property test runs against
824
844
  * this; it must be deterministic — no clocks beyond the caller's,
@@ -841,6 +861,7 @@ declare class BaerlyError extends Error {
841
861
  */
842
862
  declare class MemoryStorage implements Storage {
843
863
  #private;
864
+ constructor(opts?: MemoryStorageOptions);
844
865
  get(key: string, opts?: StorageGetOptions): Promise<StorageGetResult | null>;
845
866
  put(key: string, body: Uint8Array, opts?: StoragePutOptions): Promise<StoragePutResult>;
846
867
  delete(key: string, opts?: {
@@ -956,11 +977,13 @@ type Verifier = (req: Request) => Promise<VerifierResult | null>;
956
977
  /**
957
978
  * Debezium-style JSON CDC envelope using pgoutput's message-tag (`I`/`U`/`D`) vocabulary. One per mutation.
958
979
  *
959
- * **Pre-launch: the shape may still narrow.** Once the first production
960
- * consumer ships, this becomes a frozen migration contract behind
961
- * `baerly export --target=postgres` — the keys will be public, consumers
962
- * ack on `lsn`, and any rename / removal will be a major-version
963
- * migration.
980
+ * `LogEntry` is now a public, versionless/additive-only wire contract:
981
+ * 0.3.0 is the public early-access baseline. It is still pre-1.0 and
982
+ * soaking, so breaking changes remain possible, but only through an
983
+ * explicit compatibility decision, changelog/migration notes, and a
984
+ * versioned release. Assume external consumers may exist; do not
985
+ * silently rename, remove, or repurpose fields. Consumers must ignore
986
+ * unknown keys; new optional fields can be added in compatible releases.
964
987
  *
965
988
  * Field requirement matrix:
966
989
  * - Always: `lsn`, `commit_ts`, `op`, `collection`, `session`,
@@ -1016,7 +1039,7 @@ interface LogEntry {
1016
1039
  before?: DocumentData;
1017
1040
  /**
1018
1041
  * Pre-image of the primary key. U/D always carry this when
1019
- * `replica_identity` is not `PATCH_ONLY`. (For Baerly today,
1042
+ * `replica_identity` is not `PATCH_ONLY`. (For baerly-storage today,
1020
1043
  * `_id` is the only PK.)
1021
1044
  */
1022
1045
  key_old?: {
@@ -1025,12 +1048,19 @@ interface LogEntry {
1025
1048
  /** ORIGIN analogue — the writer session id. */
1026
1049
  origin?: string;
1027
1050
  /**
1028
- * Causal metadata (Baerly-only; no pgoutput analogue). The
1051
+ * Causal metadata (baerly-storage-only; no pgoutput analogue). The
1029
1052
  * session id that built the `lsn`. Surfaces here so consumers
1030
1053
  * can dedupe / order without parsing the cursor.
1031
1054
  */
1032
1055
  session: string;
1033
- /** Per-session sequence number embedded in the `lsn`. */
1056
+ /**
1057
+ * The `log/<seq>` slot this entry occupies — the integer in its
1058
+ * `log/<seq>.json` key, minted by `Writer.commit` as the forward-probed
1059
+ * collection-log tail (the winning `If-None-Match: "*"` create). One
1060
+ * entry per `session`, so this is a per-collection slot, not a
1061
+ * per-session counter. Also encoded (descending base-32) as the LSN's
1062
+ * third segment — see `lsnParts`.
1063
+ */
1034
1064
  seq: number;
1035
1065
  }
1036
1066
  //#endregion
@@ -1078,5 +1108,5 @@ interface MetricsRecorder {
1078
1108
  histogram(name: string, value: number, labels?: Readonly<Record<string, string>>): void;
1079
1109
  }
1080
1110
  //#endregion
1081
- export { StorageGetResult as _, MemoryStorage as a, StoragePutResult as b, Collection as c, Query as d, PredicateArg as f, StorageGetOptions as g, Storage as h, VerifierResult as i, OrderSpec as l, CurrentJsonRead as m, LogEntry as n, BaerlyError as o, CurrentJson as p, Verifier as r, BaerlyErrorCode as s, MetricsRecorder as t, Predicate as u, StorageListEntry as v, StoragePutOptions as y };
1082
- //# sourceMappingURL=index-DW7GT6M2.d.ts.map
1111
+ export { StoragePutOptions as _, MemoryStorage as a, BaerlyErrorCode as b, Predicate as c, CurrentJson as d, CurrentJsonRead as f, StorageListEntry as g, StorageGetResult as h, VerifierResult as i, Query as l, StorageGetOptions as m, LogEntry as n, Collection as o, Storage as p, Verifier as r, OrderSpec as s, MetricsRecorder as t, PredicateArg as u, StoragePutResult as v, BaerlyError as y };
1112
+ //# sourceMappingURL=index-BYk9oCNf.d.ts.map
package/dist/index.d.ts CHANGED
@@ -1,6 +1,6 @@
1
- import { a as CollectionNames, c as defineConfig, d as IndexDefinition, f as DocumentData, i as CollectionDefinition, l as SchemaIssue, n as BaerlyAppConfig, o as RowOf, r as BaerlyConfig, s as UnboundConfig, u as SchemaValidator } from "./app-config-BIzyAKzy.js";
2
- import { _ as StorageGetResult, a as MemoryStorage, b as StoragePutResult, c as Collection, d as Query, h as Storage, i as VerifierResult, o as BaerlyError, r as Verifier, s as BaerlyErrorCode, v as StorageListEntry } from "./index-DW7GT6M2.js";
3
- import { t as allIndexKeysFor } from "./indexes-Cx7uMXm0.js";
4
- import { a as loadSnapshotAsMap, c as collectionsToMaps, i as encodeSnapshotBody, n as walkLogRange, o as snapshotKey, r as SnapshotBody, s as resolveVerifier, t as probeTailFrom } from "./index-BDceQQi-.js";
5
- import { n as validateOrThrow, t as Db } from "./db-CCT6tDfY.js";
6
- export { type BaerlyAppConfig, type BaerlyConfig, BaerlyError, type BaerlyErrorCode, type Collection, type CollectionDefinition, type CollectionNames, Db, type DocumentData, type IndexDefinition, MemoryStorage, type Query, type RowOf, type SchemaIssue, type SchemaValidator, type SnapshotBody, type Storage, type StorageGetResult, type StorageListEntry, type StoragePutResult, type UnboundConfig, type Verifier, type VerifierResult, allIndexKeysFor, collectionsToMaps, defineConfig, encodeSnapshotBody, loadSnapshotAsMap, probeTailFrom, resolveVerifier, snapshotKey, validateOrThrow, walkLogRange };
1
+ import { a as CollectionNames, c as defineConfig, d as IndexDefinition, f as DocumentData, i as CollectionDefinition, l as SchemaIssue, n as BaerlyAppConfig, o as RowOf, r as BaerlyConfig, s as UnboundConfig, u as SchemaValidator } from "./app-config-DyiFK3_k.js";
2
+ import { a as MemoryStorage, b as BaerlyErrorCode, c as Predicate, g as StorageListEntry, h as StorageGetResult, i as VerifierResult, l as Query, o as Collection, p as Storage, r as Verifier, u as PredicateArg, v as StoragePutResult, y as BaerlyError } from "./index-BYk9oCNf.js";
3
+ import { t as allIndexKeysFor } from "./indexes-Dn9hbGQG.js";
4
+ import { a as loadSnapshotAsMap, c as collectionsToMaps, i as encodeSnapshotBody, n as walkLogRange, o as snapshotKey, r as SnapshotBody, s as resolveVerifier, t as probeTailFrom } from "./index-BNRh23K9.js";
5
+ import { n as validateOrThrow, t as Db } from "./db-DsPkOVEH.js";
6
+ export { type BaerlyAppConfig, type BaerlyConfig, BaerlyError, type BaerlyErrorCode, type Collection, type CollectionDefinition, type CollectionNames, Db, type DocumentData, type IndexDefinition, MemoryStorage, type Predicate, type PredicateArg, type Query, type RowOf, type SchemaIssue, type SchemaValidator, type SnapshotBody, type Storage, type StorageGetResult, type StorageListEntry, type StoragePutResult, type UnboundConfig, type Verifier, type VerifierResult, allIndexKeysFor, collectionsToMaps, defineConfig, encodeSnapshotBody, loadSnapshotAsMap, probeTailFrom, resolveVerifier, snapshotKey, validateOrThrow, walkLogRange };
package/dist/index.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import { defineConfig } from "./app-config.js";
2
- import { t as BaerlyError } from "./errors-DOdL95kK.js";
3
- import { S as probeTailFrom, _ as encodeSnapshotBody, m as allIndexKeysFor, p as walkLogRange, v as loadSnapshotAsMap, y as snapshotKey } from "./maintenance-CWBQpZ2y.js";
4
- import { o as validateOrThrow } from "./query-sQNO5vU_.js";
5
- import { i as MemoryStorage, n as resolveVerifier, r as collectionsToMaps, t as Db } from "./src-Db4-qVtM.js";
2
+ import { t as BaerlyError } from "./errors-Dfa3p78c.js";
3
+ import { b as loadSnapshotAsMap, g as allIndexKeysFor, h as walkLogRange, w as probeTailFrom, x as snapshotKey, y as encodeSnapshotBody } from "./maintenance-B4Dki6Ig.js";
4
+ import { i as MemoryStorage, n as resolveVerifier, r as collectionsToMaps, t as Db } from "./src-CYHFDrKz.js";
5
+ import { o as validateOrThrow } from "./query-rAtXNQQB.js";
6
6
  export { BaerlyError, Db, MemoryStorage, allIndexKeysFor, collectionsToMaps, defineConfig, encodeSnapshotBody, loadSnapshotAsMap, probeTailFrom, resolveVerifier, snapshotKey, validateOrThrow, walkLogRange };
@@ -1,4 +1,4 @@
1
- import { d as IndexDefinition, f as DocumentData } from "./app-config-BIzyAKzy.js";
1
+ import { d as IndexDefinition, f as DocumentData } from "./app-config-DyiFK3_k.js";
2
2
  //#region packages/server/src/indexes.d.ts
3
3
  /**
4
4
  * Compute the full index-key set a single doc produces under every
@@ -19,4 +19,4 @@ import { d as IndexDefinition, f as DocumentData } from "./app-config-BIzyAKzy.j
19
19
  declare const allIndexKeysFor: (logPrefix: string, defs: ReadonlyArray<IndexDefinition>, body: DocumentData | undefined, docId: string) => string[];
20
20
  //#endregion
21
21
  export { allIndexKeysFor as t };
22
- //# sourceMappingURL=indexes-Cx7uMXm0.d.ts.map
22
+ //# sourceMappingURL=indexes-Dn9hbGQG.d.ts.map
@@ -1,44 +1,21 @@
1
- import { n as loadCollectionIndexes, r as parseBucketUri } from "./config-CGyBopy3.js";
2
- import { h as readCurrentJson, n as probeTailFrom } from "./log-tail-DXeDkWEp.js";
1
+ import { n as loadCollectionIndexes, r as parseBucketUri } from "./config-1tv0-Yzm.js";
2
+ import { h as readCurrentJson, n as probeTailFrom } from "./log-tail-D98U1JBo.js";
3
3
  import { i as isJsonMode, o as BaerlyError, r as emitSuccess } from "./baerly.js";
4
- import { n as loadMaterialisedView } from "./plan-DIu_B6fy.js";
5
- import { n as defineBaerlySubcommand, t as assertCollectionArg } from "./subcommand-CP9NY2J4.js";
4
+ import { n as loadMaterialisedView } from "./plan-a7PJHBCy.js";
5
+ import { a as TENANT_ARG, i as JSON_ARG, n as BUCKET_ARG, o as assertCollectionArg, r as COLLECTION_ARG, s as defineBaerlySubcommand, t as APP_ARG } from "./subcommand-DoDA-K7d.js";
6
6
  //#region src/inspect.ts
7
7
  const INSPECT_ARGS = {
8
- bucket: {
9
- type: "string",
10
- required: true,
11
- description: "Bucket URI (s3://<bucket>[/<prefix>], file:///<abs>, memory://<bucket>)",
12
- valueHint: "bucket-uri"
13
- },
14
- app: {
15
- type: "string",
16
- required: false,
17
- description: "Application name segment (defaults to baerly.config.ts).",
18
- valueHint: "app"
19
- },
20
- tenant: {
21
- type: "string",
22
- required: false,
23
- description: "Tenant name segment (defaults to baerly.config.ts).",
24
- valueHint: "tenant"
25
- },
26
- collection: {
27
- type: "string",
28
- required: true,
29
- description: "Collection name.",
30
- valueHint: "name"
31
- },
8
+ bucket: BUCKET_ARG,
9
+ app: APP_ARG,
10
+ tenant: TENANT_ARG,
11
+ collection: COLLECTION_ARG,
32
12
  config: {
33
13
  type: "string",
34
14
  required: false,
35
15
  description: "Path to baerly.config.{js,mjs,json}; pulls declared indexes for key-count probes.",
36
16
  valueHint: "path"
37
17
  },
38
- json: {
39
- type: "boolean",
40
- description: "Emit a structured JSON envelope to stdout (success) or stderr (error)"
41
- }
18
+ json: JSON_ARG
42
19
  };
43
20
  const countListEntries = async (storage, prefix) => {
44
21
  let count = 0;
@@ -153,4 +130,4 @@ bundle.run;
153
130
  //#endregion
154
131
  export { inspect };
155
132
 
156
- //# sourceMappingURL=inspect-DhI49PSi.js.map
133
+ //# sourceMappingURL=inspect-6WZ-pC7-.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"inspect-6WZ-pC7-.js","names":[],"sources":["../packages/cli/src/inspect.ts"],"sourcesContent":["/**\n * `baerly inspect` — read-only summary for one collection.\n *\n * Args:\n * --bucket Required. Bucket URI.\n * --app Required (or via baerly.config.ts).\n * --tenant Required (or via baerly.config.ts).\n * --collection Required. Collection name.\n * --config Optional path to baerly.config.{js,mjs,json} for index info.\n * --json JSON envelope.\n *\n * Reports, per-collection:\n * - currentJsonKey path.\n * - schema_version, tail_hint, log_seq_start (default 0).\n * - live_log_tail (= tail_hint - log_seq_start).\n * - snapshot key (or null).\n * - snapshot_bytes / snapshot_rows (the fold-ceiling inputs C / E\n * are compared against; see graduation.md).\n * - writer_fence (epoch, owner, claimed_at).\n * - materialised row count (via export/loadMaterialisedView).\n * - per-declared-index key count (when --config supplied).\n * - well-formed status: \"ok\" or \"error\" with an `errors` array.\n *\n * For projected monthly Class A / $ trajectories, use\n * `baerly cost --bucket=<uri> --collection=<name>` — the projection\n * used to live as a footer here but moved to its own verb so inspect\n * stays a glance command (no GET-storm over the trailing log sample).\n *\n * Cost shape:\n * 1 GET current.json\n * + 1 GET snapshot (if any)\n * + N GETs log tail (= tail_hint - log_seq_start)\n * + K LISTs (one per declared index, when --config supplied)\n * + 1 LIST snapshot/ prefix (orphan detection)\n *\n * Never mutates anything.\n *\n * Exit codes:\n * 0 — inspection ran (status may be \"ok\" or \"error\"; both exit 0).\n * 1 — InvalidConfig (bad bucket URI, missing args, unknown flag).\n * 2 — Storage / Network error.\n * 3 — Protocol invariant (Conflict / Internal / InvalidResponse).\n */\n\nimport { type ArgsDef } from \"citty\";\nimport { BaerlyError, readCurrentJson, type CurrentJson, type Storage } from \"@baerly/protocol\";\nimport { probeTailFrom } from \"@baerly/server\";\nimport { loadMaterialisedView } from \"./export/index.ts\";\nimport { loadCollectionIndexes } from \"./config.ts\";\nimport { parseBucketUri } from \"./bucket-uri.ts\";\nimport { emitSuccess, isJsonMode } from \"./output.ts\";\nimport {\n APP_ARG,\n assertCollectionArg,\n BUCKET_ARG,\n COLLECTION_ARG,\n defineBaerlySubcommand,\n JSON_ARG,\n TENANT_ARG,\n} from \"./subcommand.ts\";\n\nconst INSPECT_ARGS = {\n bucket: BUCKET_ARG,\n app: APP_ARG,\n tenant: TENANT_ARG,\n collection: COLLECTION_ARG,\n config: {\n type: \"string\",\n required: false,\n description:\n \"Path to baerly.config.{js,mjs,json}; pulls declared indexes for key-count probes.\",\n valueHint: \"path\",\n },\n json: JSON_ARG,\n} as const satisfies ArgsDef;\n\nconst countListEntries = async (\n storage: Storage,\n prefix: string,\n): Promise<{ count: number; keys: string[] }> => {\n let count = 0;\n const keys: string[] = [];\n for await (const entry of storage.list(prefix)) {\n count++;\n keys.push(entry.key);\n }\n return { count, keys };\n};\n\ninterface InspectResult {\n currentJsonKey: string;\n schema_version: number;\n /** The stored, compactor-advanced lower-bound hint (`current.json.tail_hint`). */\n tail_hint: number;\n /** The TRUE committed tail, discovered by forward-probe past `tail_hint`. */\n discovered_tail: number;\n log_seq_start: number;\n live_log_tail: number;\n snapshot: string | null;\n snapshot_bytes: number;\n snapshot_rows: number;\n writer_fence: CurrentJson[\"writer_fence\"];\n materialised_rows: number;\n indexes: { name: string; count: number }[];\n status: \"ok\" | \"error\";\n errors: string[];\n}\n\nconst renderText = (r: InspectResult, collection: string): string => {\n const lines: string[] = [];\n lines.push(`baerly inspect ${collection}`);\n lines.push(` current.json: ${r.currentJsonKey}`);\n lines.push(` schema_version: ${r.schema_version}`);\n lines.push(` tail_hint (stored): ${r.tail_hint}`);\n lines.push(` discovered_tail: ${r.discovered_tail}`);\n lines.push(` log_seq_start: ${r.log_seq_start}`);\n lines.push(` live_log_tail: ${r.live_log_tail}`);\n lines.push(` snapshot: ${r.snapshot ?? \"(none)\"}`);\n lines.push(` snapshot_bytes: ${r.snapshot_bytes}`);\n lines.push(` snapshot_rows: ${r.snapshot_rows}`);\n lines.push(\n ` writer_fence: epoch=${r.writer_fence.epoch} owner=${JSON.stringify(r.writer_fence.owner)} claimed_at=${JSON.stringify(r.writer_fence.claimed_at)}`,\n );\n lines.push(` materialised_rows: ${r.materialised_rows}`);\n if (r.indexes.length > 0) {\n const formatted = r.indexes.map((i) => `${i.name} (count=${i.count})`).join(\", \");\n lines.push(` indexes: ${formatted}`);\n } else {\n lines.push(` indexes: (none declared)`);\n }\n lines.push(` status: ${r.status}`);\n if (r.errors.length > 0) {\n for (const e of r.errors) {\n lines.push(` error: ${e}`);\n }\n }\n return lines.join(\"\\n\") + \"\\n\";\n};\n\nconst bundle = defineBaerlySubcommand({\n name: \"inspect\",\n meta: {\n description: \"Read-only summary of one collection's snapshot + log state.\",\n },\n args: INSPECT_ARGS,\n handler: async (args, ctx) => {\n const bucket = await parseBucketUri(args.bucket);\n const { app, tenant } = await ctx.resolveAppTenant({ app: args.app, tenant: args.tenant });\n assertCollectionArg(args.collection, \"baerly inspect\");\n const collectionPrefix = `${bucket.keyPrefix}app/${app}/tenant/${tenant}/manifests/${args.collection}`;\n const currentJsonKey = `${collectionPrefix}/current.json`;\n\n const read = await readCurrentJson(bucket.storage, currentJsonKey);\n if (read === null) {\n throw new BaerlyError(\n \"InvalidConfig\",\n `baerly inspect: current.json not found at ${currentJsonKey}`,\n );\n }\n const cur = read.json;\n const log_seq_start = cur.log_seq_start ?? 0;\n // Discover the TRUE tail by forward-probe — under single-write commit\n // the stored `tail_hint` is only a lower bound (compactor-advanced),\n // so an accurate operator summary must probe past it.\n const tailProbe = await probeTailFrom(\n bucket.storage,\n collectionPrefix,\n Math.max(log_seq_start, cur.tail_hint),\n );\n const discoveredTail = tailProbe.tail;\n\n const errors: string[] = [];\n let materialisedRows = 0;\n try {\n const view = await loadMaterialisedView({\n storage: bucket.storage,\n currentJsonKey,\n collection: args.collection,\n });\n materialisedRows = view?.size ?? 0;\n } catch (error) {\n if (error instanceof BaerlyError) {\n errors.push(`${error.code}: ${error.message}`);\n } else {\n errors.push((error as Error).message);\n }\n }\n\n // Orphan-snapshot detection: list every file under <collectionPrefix>/snapshot/\n // and flag anything that isn't the currently-pointed-at snapshot.\n try {\n const snapshotPrefix = `${collectionPrefix}/snapshot/`;\n const { keys } = await countListEntries(bucket.storage, snapshotPrefix);\n for (const k of keys) {\n if (cur.snapshot !== k) {\n errors.push(`orphan snapshot: ${k}`);\n }\n }\n } catch (error) {\n if (error instanceof BaerlyError) {\n errors.push(`${error.code}: ${error.message}`);\n }\n }\n\n const indexes: { name: string; count: number }[] = [];\n if (typeof args.config === \"string\" && args.config.length > 0) {\n const defs = await loadCollectionIndexes(args.config, args.collection, \"baerly inspect\");\n for (const def of defs) {\n const prefix = `${collectionPrefix}/index/${def.name}/`;\n const { count } = await countListEntries(bucket.storage, prefix);\n indexes.push({ name: def.name, count });\n }\n }\n\n const result: InspectResult = {\n currentJsonKey,\n schema_version: cur.schema_version,\n tail_hint: cur.tail_hint,\n discovered_tail: discoveredTail,\n log_seq_start,\n live_log_tail: discoveredTail - log_seq_start,\n snapshot: cur.snapshot,\n snapshot_bytes: cur.snapshot_bytes,\n snapshot_rows: cur.snapshot_rows,\n writer_fence: cur.writer_fence,\n materialised_rows: materialisedRows,\n indexes,\n status: errors.length === 0 ? \"ok\" : \"error\",\n errors,\n };\n\n if (isJsonMode()) {\n emitSuccess({ command: \"inspect\", ...result });\n } else {\n process.stdout.write(renderText(result, args.collection));\n }\n return 0;\n },\n});\n\n/** citty `defineCommand` block for `baerly inspect`. */\nexport const inspect = bundle.cmd;\n\n/**\n * Programmatic entry used by tests. Bypasses citty's `run` wrapper\n * (which would call `process.exit` and kill vitest) and returns the\n * integer exit code directly.\n */\nexport const runInspect = bundle.run;\n"],"mappings":"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"}
@@ -0,0 +1,35 @@
1
+ import { t as BaerlyError } from "./errors-Dfa3p78c.js";
2
+ //#region packages/protocol/src/storage/key.ts
3
+ /**
4
+ * Validate a raw {@link Storage} object key against the portable baerly key
5
+ * grammar before it is used to address an object. A key MUST be non-empty
6
+ * and `/`-delimited, with **no path segment equal to `.` or `..`**.
7
+ *
8
+ * The dot-segment rule is not a vendor quirk — it is a *client-side*
9
+ * universal: RFC 3986 §5.2.4 "remove dot segments" is mandatory for every
10
+ * conformant URL parser, so `<endpoint>/<bucket>/.` normalizes to
11
+ * `<endpoint>/<bucket>/` and `<endpoint>/<bucket>/..` escapes the bucket
12
+ * entirely — *before* the request is signed or sent, in TypeScript, Go,
13
+ * Rust, Python, or any language a `Storage` port is written in. Such a key
14
+ * cannot be addressed over the S3/R2 HTTP API regardless of backend; a bare
15
+ * `.` PUT surfaces as a confusing bucket-root 403 rather than a clear
16
+ * rejection. The kernel never emits such keys (caller-controlled segments
17
+ * are already screened by `assertPathSegment` one layer up), so this is the
18
+ * boundary guard that makes every adapter reject them *identically* and
19
+ * gives ports a single, testable contract.
20
+ *
21
+ * Thrown as `BaerlyError{code:"InvalidConfig"}` to match the sibling
22
+ * key/segment guards (`assertKeyWithinLimit`, `assertPathSegment`). The
23
+ * full-key 1024-byte ceiling is enforced separately on the write path
24
+ * (`assertKeyWithinLimit`), where multi-segment keys are assembled.
25
+ *
26
+ * @see docs/spec/storage-compatibility.md — "Key namespace"
27
+ */
28
+ function assertValidStorageKey(key) {
29
+ if (key.length === 0) throw new BaerlyError("InvalidConfig", "storage key must be a non-empty string");
30
+ for (const segment of key.split("/")) if (segment === "." || segment === "..") throw new BaerlyError("InvalidConfig", `storage key may not contain a "." or ".." path segment — RFC 3986 dot-segment removal makes it unaddressable over the S3/R2 HTTP API: ${JSON.stringify(key)}`);
31
+ }
32
+ //#endregion
33
+ export { assertValidStorageKey as t };
34
+
35
+ //# sourceMappingURL=key-Di6yyxFu.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"key-Di6yyxFu.js","names":[],"sources":["../packages/protocol/src/storage/key.ts"],"sourcesContent":["import { BaerlyError } from \"../errors.ts\";\n\n/**\n * Validate a raw {@link Storage} object key against the portable baerly key\n * grammar before it is used to address an object. A key MUST be non-empty\n * and `/`-delimited, with **no path segment equal to `.` or `..`**.\n *\n * The dot-segment rule is not a vendor quirk — it is a *client-side*\n * universal: RFC 3986 §5.2.4 \"remove dot segments\" is mandatory for every\n * conformant URL parser, so `<endpoint>/<bucket>/.` normalizes to\n * `<endpoint>/<bucket>/` and `<endpoint>/<bucket>/..` escapes the bucket\n * entirely — *before* the request is signed or sent, in TypeScript, Go,\n * Rust, Python, or any language a `Storage` port is written in. Such a key\n * cannot be addressed over the S3/R2 HTTP API regardless of backend; a bare\n * `.` PUT surfaces as a confusing bucket-root 403 rather than a clear\n * rejection. The kernel never emits such keys (caller-controlled segments\n * are already screened by `assertPathSegment` one layer up), so this is the\n * boundary guard that makes every adapter reject them *identically* and\n * gives ports a single, testable contract.\n *\n * Thrown as `BaerlyError{code:\"InvalidConfig\"}` to match the sibling\n * key/segment guards (`assertKeyWithinLimit`, `assertPathSegment`). The\n * full-key 1024-byte ceiling is enforced separately on the write path\n * (`assertKeyWithinLimit`), where multi-segment keys are assembled.\n *\n * @see docs/spec/storage-compatibility.md — \"Key namespace\"\n */\nexport function assertValidStorageKey(key: string): void {\n if (key.length === 0) {\n throw new BaerlyError(\"InvalidConfig\", \"storage key must be a non-empty string\");\n }\n for (const segment of key.split(\"/\")) {\n if (segment === \".\" || segment === \"..\") {\n throw new BaerlyError(\n \"InvalidConfig\",\n `storage key may not contain a \".\" or \"..\" path segment — RFC 3986 dot-segment ` +\n `removal makes it unaddressable over the S3/R2 HTTP API: ${JSON.stringify(key)}`,\n );\n }\n }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,SAAgB,sBAAsB,KAAmB;CACvD,IAAI,IAAI,WAAW,GACjB,MAAM,IAAI,YAAY,iBAAiB,wCAAwC;CAEjF,KAAK,MAAM,WAAW,IAAI,MAAM,GAAG,GACjC,IAAI,YAAY,OAAO,YAAY,MACjC,MAAM,IAAI,YACR,iBACA,yIAC6D,KAAK,UAAU,GAAG,GACjF;AAGN"}