@gusto/baerly-storage 0.4.1 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/API.md +3 -2
- package/dist/CHANGELOG.md +125 -0
- package/dist/THIRD-PARTY-LICENSES.txt +1 -1
- package/dist/auth.d.ts +1 -1
- package/dist/aws4fetch.esm-CXE5ZbAa.js +460 -0
- package/dist/aws4fetch.esm-CXE5ZbAa.js.map +1 -0
- package/dist/baerly.js +10 -10
- package/dist/baerly.spec.json +1 -1
- package/dist/client-react.d.ts +2 -2
- package/dist/{client-Fe8CwB73.d.ts → client-ypCm3zjt.d.ts} +2 -2
- package/dist/client.d.ts +2 -2
- package/dist/{cloudflare-DzKBrUlg.js → cloudflare-wrVYf4bb.js} +457 -56
- package/dist/cloudflare-wrVYf4bb.js.map +1 -0
- package/dist/cloudflare.d.ts +13 -10
- package/dist/cloudflare.js +6 -6
- package/dist/cloudflare.js.map +1 -1
- package/dist/{config-1tv0-Yzm.js → config-B6nTy8e2.js} +435 -33
- package/dist/config-B6nTy8e2.js.map +1 -0
- package/dist/constants-CfeMWQWk.js.map +1 -1
- package/dist/{cost-DSMIVqzL.js → cost-_SE_SVgZ.js} +4 -4
- package/dist/{cost-DSMIVqzL.js.map → cost-_SE_SVgZ.js.map} +1 -1
- package/dist/{db-DsPkOVEH.d.ts → db-DjjthkTi.d.ts} +2 -2
- package/dist/{deploy-DonTr-CV.js → deploy-Di_Q01qx.js} +5 -5
- package/dist/deploy-Di_Q01qx.js.map +1 -0
- package/dist/dev-vite.d.ts +31 -27
- package/dist/dev-vite.js +60 -30
- package/dist/dev-vite.js.map +1 -1
- package/dist/dev.d.ts +1 -1
- package/dist/doctor-RWVRpvat.js +102 -0
- package/dist/doctor-RWVRpvat.js.map +1 -0
- package/dist/{dump-Bh5k26VQ.js → dump-m2vEYDNY.js} +4 -4
- package/dist/{dump-Bh5k26VQ.js.map → dump-m2vEYDNY.js.map} +1 -1
- package/dist/{export-DtF5tDIM.js → export-DenKwEQu.js} +4 -4
- package/dist/{export-DtF5tDIM.js.map → export-DenKwEQu.js.map} +1 -1
- package/dist/{fsck-D_djMO5D.js → fsck-2Vq-7-e2.js} +5 -5
- package/dist/{fsck-D_djMO5D.js.map → fsck-2Vq-7-e2.js.map} +1 -1
- package/dist/gcs-admin-Bx6xSNJj.d.ts +123 -0
- package/dist/gcs.d.ts +18 -0
- package/dist/gcs.js +2 -0
- package/dist/goog4-signer-Z7KnJ1su.js +321 -0
- package/dist/goog4-signer-Z7KnJ1su.js.map +1 -0
- package/dist/{http-DxM9MflO.js → http-7zT29K3P.js} +4 -4
- package/dist/{http-DxM9MflO.js.map → http-7zT29K3P.js.map} +1 -1
- package/dist/{aws4fetch.esm-p7eEzLCs.js → http-transport-BTgVCY5r.js} +24 -476
- package/dist/http-transport-BTgVCY5r.js.map +1 -0
- package/dist/http.d.ts +2 -2
- package/dist/http.js +2 -2
- package/dist/{index-BNRh23K9.d.ts → index-BHz92Acj.d.ts} +2 -2
- package/dist/{index-BYk9oCNf.d.ts → index-CEZKQsKt.d.ts} +3 -2
- package/dist/{index-B6oexfOB.d.ts → index-DP3ClvcA.d.ts} +12 -10
- package/dist/{index-0rZcMBwy.d.ts → index-uE-w2dgj.d.ts} +2 -2
- package/dist/index.d.ts +3 -3
- package/dist/index.js +3 -3
- package/dist/{inspect-6WZ-pC7-.js → inspect-BpYbH1DM.js} +5 -5
- package/dist/{inspect-6WZ-pC7-.js.map → inspect-BpYbH1DM.js.map} +1 -1
- package/dist/{log-tail-D98U1JBo.js → log-tail-QWU4wlu-.js} +3 -11
- package/dist/log-tail-QWU4wlu-.js.map +1 -0
- package/dist/{maintenance-B_e0T99L.d.ts → maintenance-BGHGt2Yg.d.ts} +2 -2
- package/dist/{maintenance-B4Dki6Ig.js → maintenance-DULFcpd1.js} +4 -17
- package/dist/maintenance-DULFcpd1.js.map +1 -0
- package/dist/{maintenance-C7coQp4c.js → maintenance-fEi-UZ2o.js} +5 -11
- package/dist/maintenance-fEi-UZ2o.js.map +1 -0
- package/dist/maintenance.d.ts +1 -1
- package/dist/maintenance.js +1 -1
- package/dist/node.d.ts +22 -61
- package/dist/node.js +4 -3
- package/dist/{observability-wzs3-BL_.js → observability-Ch-VQJyE.js} +85 -27
- package/dist/{observability-wzs3-BL_.js.map → observability-Ch-VQJyE.js.map} +1 -1
- package/dist/observability.d.ts +2 -2
- package/dist/observability.js +1 -1
- package/dist/{plan-a7PJHBCy.js → plan-C4qgiXSg.js} +2 -2
- package/dist/{plan-a7PJHBCy.js.map → plan-C4qgiXSg.js.map} +1 -1
- package/dist/{query-rAtXNQQB.js → query-C43r-6ib.js} +2 -2
- package/dist/{query-rAtXNQQB.js.map → query-C43r-6ib.js.map} +1 -1
- package/dist/{rebuild-index-BVzQSZlm.js → rebuild-index-BH1dc1p6.js} +4 -4
- package/dist/{rebuild-index-BVzQSZlm.js.map → rebuild-index-BH1dc1p6.js.map} +1 -1
- package/dist/{restore-R-4rbciV.js → restore-D0VYWzfP.js} +5 -5
- package/dist/{restore-R-4rbciV.js.map → restore-D0VYWzfP.js.map} +1 -1
- package/dist/{runtime-spec-_GTdeSMo.js → runtime-spec--LykAdl1.js} +2 -2
- package/dist/{runtime-spec-_GTdeSMo.js.map → runtime-spec--LykAdl1.js.map} +1 -1
- package/dist/{s3-http-B-z8th6O.d.ts → s3-http-DD5gDc7t.d.ts} +6 -4
- package/dist/s3.d.ts +1 -1
- package/dist/s3.js +1 -1
- package/dist/sha256-CqcKTjw9.js +22 -0
- package/dist/sha256-CqcKTjw9.js.map +1 -0
- package/dist/{src-D__mHQmQ.js → src-BMFfDUI2.js} +69 -29
- package/dist/src-BMFfDUI2.js.map +1 -0
- package/dist/{src-CYHFDrKz.js → src-DvbTEya2.js} +3 -3
- package/dist/{src-CYHFDrKz.js.map → src-DvbTEya2.js.map} +1 -1
- package/dist/{subcommand-DoDA-K7d.js → subcommand-BV68pqwJ.js} +2 -2
- package/dist/{subcommand-DoDA-K7d.js.map → subcommand-BV68pqwJ.js.map} +1 -1
- package/dist/{usage-DBV1eQHC.js → usage-BMZR8o6U.js} +3 -3
- package/dist/{usage-DBV1eQHC.js.map → usage-BMZR8o6U.js.map} +1 -1
- package/package.json +12 -6
- package/dist/aws4fetch.esm-p7eEzLCs.js.map +0 -1
- package/dist/cloudflare-DzKBrUlg.js.map +0 -1
- package/dist/config-1tv0-Yzm.js.map +0 -1
- package/dist/deploy-DonTr-CV.js.map +0 -1
- package/dist/doctor-DSIyCDg_.js +0 -346
- package/dist/doctor-DSIyCDg_.js.map +0 -1
- package/dist/log-tail-D98U1JBo.js.map +0 -1
- package/dist/maintenance-B4Dki6Ig.js.map +0 -1
- package/dist/maintenance-C7coQp4c.js.map +0 -1
- package/dist/src-D__mHQmQ.js.map +0 -1
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
import { n as loadCollectionIndexes, r as parseBucketUri } from "./config-
|
|
2
|
-
import { i as rebuildIndex } from "./maintenance-
|
|
1
|
+
import { n as loadCollectionIndexes, r as parseBucketUri } from "./config-B6nTy8e2.js";
|
|
2
|
+
import { i as rebuildIndex } from "./maintenance-fEi-UZ2o.js";
|
|
3
3
|
import { o as BaerlyError, r as emitSuccess } from "./baerly.js";
|
|
4
|
-
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-
|
|
4
|
+
import { a as TENANT_ARG, i as JSON_ARG, n as BUCKET_ARG, o as assertCollectionArg, r as COLLECTION_ARG, s as defineBaerlySubcommand, t as APP_ARG } from "./subcommand-BV68pqwJ.js";
|
|
5
5
|
//#region src/admin/rebuild-index.ts
|
|
6
6
|
/** citty arg shape. Kebab-case so --help and parsed-object keys line up. */
|
|
7
7
|
const REBUILD_INDEX_ARGS = {
|
|
@@ -78,4 +78,4 @@ bundle.run;
|
|
|
78
78
|
//#endregion
|
|
79
79
|
export { rebuildIndexCmd };
|
|
80
80
|
|
|
81
|
-
//# sourceMappingURL=rebuild-index-
|
|
81
|
+
//# sourceMappingURL=rebuild-index-BH1dc1p6.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"rebuild-index-
|
|
1
|
+
{"version":3,"file":"rebuild-index-BH1dc1p6.js","names":[],"sources":["../packages/cli/src/admin/rebuild-index.ts"],"sourcesContent":["/**\n * `baerly admin rebuild-index` — idempotent reconciliation for one\n * secondary index. Walks the live `(snapshot, log)` of the named\n * collection, computes the expected index-key set under the named\n * index's definition, then PUTs missing keys and DELETEs orphans.\n *\n * Cost shape: `1 GET (current.json) + 1 GET (snapshot, if any) + N\n * GETs (live tail) + 1 LIST (the index prefix) + K PUTs + L DELETEs`.\n *\n * Exit codes (standard CLI shape):\n * - `0` — success (envelope on stdout in --json mode).\n * - `1` — user error (InvalidConfig: bad bucket URI, missing\n * args, unparseable config).\n * - `2` — storage error (NetworkError, AccessDenied, anything\n * non-BaerlyError).\n * - `3` — protocol invariant (Conflict, Internal, InvalidResponse).\n *\n * Idempotent — re-running on a healthy index is `{ removed: 0,\n * added: 0 }`; re-running after a crashed mid-commit reconciles\n * toward the live current.json view.\n *\n * Args:\n * --bucket Bucket URI (s3://..., file:///<abs>, memory://...).\n * --app Application name segment (defaults to baerly.config.ts).\n * --tenant Tenant name segment (defaults to baerly.config.ts).\n * --collection Collection name.\n * --index Index name (e.g. \"by_status\").\n * --on Field the index projects on (string today; matches\n * the IndexDefinition shape declared in baerly.config.ts).\n * --config Path to a baerly.config.{js,mjs,json}. Loaded with\n * dynamic import; the matching collection.indexes[]\n * definition is used. Mutually-exclusive with --on\n * (config takes precedence). `.ts` configs are not\n * supported today — point at the compiled output.\n *\n * The reconciliation logic itself lives in `@baerly/server`'s\n * `rebuildIndex`; this command is a thin URI + arg-parsing wrapper.\n */\n\nimport { type ArgsDef } from \"citty\";\nimport { BaerlyError, type IndexDefinition } from \"@baerly/protocol\";\nimport { rebuildIndex } from \"@baerly/server/maintenance\";\nimport { loadCollectionIndexes } from \"../config.ts\";\nimport { parseBucketUri } from \"../bucket-uri.ts\";\nimport { emitSuccess } 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\n/** citty arg shape. Kebab-case so --help and parsed-object keys line up. */\nconst REBUILD_INDEX_ARGS = {\n bucket: BUCKET_ARG,\n app: APP_ARG,\n tenant: TENANT_ARG,\n collection: COLLECTION_ARG,\n index: {\n type: \"string\",\n required: true,\n description: \"Index name (e.g. by_status)\",\n valueHint: \"name\",\n },\n on: {\n type: \"string\",\n required: false,\n description: \"Field the index projects on. Required unless --config supplies it.\",\n valueHint: \"field\",\n },\n config: {\n type: \"string\",\n required: false,\n description: \"Path to baerly.config.{js,mjs,json} — used to resolve the index's `on` field.\",\n valueHint: \"path\",\n },\n json: JSON_ARG,\n verbose: {\n type: \"boolean\",\n description: \"Emit a one-line summary to stdout in addition to the JSON envelope.\",\n },\n} as const satisfies ArgsDef;\n\n/** Resolve the `on` field of a single named index from the config file. */\nconst onFieldFromConfig = async (\n configPath: string,\n collection: string,\n indexName: string,\n): Promise<string | readonly string[]> => {\n const indexes = await loadCollectionIndexes(configPath, collection, \"baerly admin rebuild-index\");\n const def = indexes.find((d) => d.name === indexName);\n if (def === undefined) {\n throw new BaerlyError(\n \"InvalidConfig\",\n `baerly admin rebuild-index: config has no index ${JSON.stringify(indexName)} on collection ${JSON.stringify(collection)}`,\n );\n }\n return def.on;\n};\n\nconst bundle = defineBaerlySubcommand({\n name: \"admin.rebuild-index\",\n meta: {\n description: \"Idempotent reconciliation of one secondary index.\",\n },\n args: REBUILD_INDEX_ARGS,\n handler: async (args, ctx) => {\n const bucket = await parseBucketUri(args.bucket);\n assertCollectionArg(args.collection, \"baerly admin rebuild-index\");\n const on =\n args.config !== undefined && args.config.length > 0\n ? await onFieldFromConfig(args.config, args.collection, args.index)\n : args.on;\n if (on === undefined || on.length === 0) {\n throw new BaerlyError(\n \"InvalidConfig\",\n \"baerly admin rebuild-index: --on=<field> (or --config=<path>) is required\",\n );\n }\n const def: IndexDefinition = { name: args.index, on };\n const { app, tenant } = await ctx.resolveAppTenant({ app: args.app, tenant: args.tenant });\n const currentJsonKey = `${bucket.keyPrefix}app/${app}/tenant/${tenant}/manifests/${args.collection}/current.json`;\n const result = await rebuildIndex(bucket.storage, currentJsonKey, def);\n emitSuccess({\n command: \"admin.rebuild-index\",\n status: \"ok\",\n added: result.added,\n removed: result.removed,\n kept: result.kept,\n });\n if (args.verbose === true) {\n process.stdout.write(\n `rebuild-index: added=${result.added} removed=${result.removed} kept=${result.kept}\\n`,\n );\n }\n return 0;\n },\n});\n\n/**\n * citty `defineCommand` block for `baerly admin rebuild-index`.\n * Mounted on the `admin` subcommand tree in `baerly.ts`.\n */\nexport const rebuildIndexCmd = 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 *\n * @param argv Args AFTER the `admin rebuild-index` subcommand.\n */\nexport const runRebuildIndex = bundle.run;\n"],"mappings":";;;;;;AAwDA,MAAM,qBAAqB;CACzB,QAAQ;CACR,KAAK;CACL,QAAQ;CACR,YAAY;CACZ,OAAO;EACL,MAAM;EACN,UAAU;EACV,aAAa;EACb,WAAW;CACb;CACA,IAAI;EACF,MAAM;EACN,UAAU;EACV,aAAa;EACb,WAAW;CACb;CACA,QAAQ;EACN,MAAM;EACN,UAAU;EACV,aAAa;EACb,WAAW;CACb;CACA,MAAM;CACN,SAAS;EACP,MAAM;EACN,aAAa;CACf;AACF;;AAGA,MAAM,oBAAoB,OACxB,YACA,YACA,cACwC;CAExC,MAAM,OAAM,MADU,sBAAsB,YAAY,YAAY,4BAA4B,EAAA,CAC5E,MAAM,MAAM,EAAE,SAAS,SAAS;CACpD,IAAI,QAAQ,KAAA,GACV,MAAM,IAAI,YACR,iBACA,mDAAmD,KAAK,UAAU,SAAS,EAAE,iBAAiB,KAAK,UAAU,UAAU,GACzH;CAEF,OAAO,IAAI;AACb;AAEA,MAAM,SAAS,uBAAuB;CACpC,MAAM;CACN,MAAM,EACJ,aAAa,oDACf;CACA,MAAM;CACN,SAAS,OAAO,MAAM,QAAQ;EAC5B,MAAM,SAAS,MAAM,eAAe,KAAK,MAAM;EAC/C,oBAAoB,KAAK,YAAY,4BAA4B;EACjE,MAAM,KACJ,KAAK,WAAW,KAAA,KAAa,KAAK,OAAO,SAAS,IAC9C,MAAM,kBAAkB,KAAK,QAAQ,KAAK,YAAY,KAAK,KAAK,IAChE,KAAK;EACX,IAAI,OAAO,KAAA,KAAa,GAAG,WAAW,GACpC,MAAM,IAAI,YACR,iBACA,2EACF;EAEF,MAAM,MAAuB;GAAE,MAAM,KAAK;GAAO;EAAG;EACpD,MAAM,EAAE,KAAK,WAAW,MAAM,IAAI,iBAAiB;GAAE,KAAK,KAAK;GAAK,QAAQ,KAAK;EAAO,CAAC;EACzF,MAAM,iBAAiB,GAAG,OAAO,UAAU,MAAM,IAAI,UAAU,OAAO,aAAa,KAAK,WAAW;EACnG,MAAM,SAAS,MAAM,aAAa,OAAO,SAAS,gBAAgB,GAAG;EACrE,YAAY;GACV,SAAS;GACT,QAAQ;GACR,OAAO,OAAO;GACd,SAAS,OAAO;GAChB,MAAM,OAAO;EACf,CAAC;EACD,IAAI,KAAK,YAAY,MACnB,QAAQ,OAAO,MACb,wBAAwB,OAAO,MAAM,WAAW,OAAO,QAAQ,QAAQ,OAAO,KAAK,GACrF;EAEF,OAAO;CACT;AACF,CAAC;;;;;AAMD,MAAa,kBAAkB,OAAO;AASP,OAAO"}
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
import { n as encodeJsonBytes, t as decodeJsonBytes } from "./bytes-BXdamO3L.js";
|
|
2
|
-
import {
|
|
3
|
-
import { a as walkLogRange, d as logObjectKey, h as readCurrentJson, i as readLogEntry, m as logSeqStartOf, p as createCurrentJson, t as findLogTail } from "./log-tail-
|
|
4
|
-
import { a as getCurrentContext, c as noopMetricsRecorder, l as versionFromContent, n as runBoundedMaintenance, o as allIndexKeysFor, r as shouldFireMaintenance, s as validateIndexDefinition, t as dispatchInlineAwaited } from "./maintenance-
|
|
2
|
+
import { c as uuid, g as MAINTENANCE_PROFILE_CF_FREE, m as LOG_FORWARD_PROBE_CAP, o as timestamp, r as parseBucketUri, s as countKey, y as MAX_KEY_BYTES } from "./config-B6nTy8e2.js";
|
|
3
|
+
import { a as walkLogRange, d as logObjectKey, h as readCurrentJson, i as readLogEntry, m as logSeqStartOf, p as createCurrentJson, t as findLogTail } from "./log-tail-QWU4wlu-.js";
|
|
4
|
+
import { a as getCurrentContext, c as noopMetricsRecorder, l as versionFromContent, n as runBoundedMaintenance, o as allIndexKeysFor, r as shouldFireMaintenance, s as validateIndexDefinition, t as dispatchInlineAwaited } from "./maintenance-fEi-UZ2o.js";
|
|
5
5
|
import { o as BaerlyError, r as emitSuccess } from "./baerly.js";
|
|
6
|
-
import { a as TENANT_ARG, c as assertPathSegment, i as JSON_ARG, o as assertCollectionArg, s as defineBaerlySubcommand, t as APP_ARG } from "./subcommand-
|
|
6
|
+
import { a as TENANT_ARG, c as assertPathSegment, i as JSON_ARG, o as assertCollectionArg, s as defineBaerlySubcommand, t as APP_ARG } from "./subcommand-BV68pqwJ.js";
|
|
7
7
|
import { createInterface } from "node:readline";
|
|
8
8
|
//#region ../server/src/doc-id.ts
|
|
9
9
|
/**
|
|
@@ -775,4 +775,4 @@ bundle.run;
|
|
|
775
775
|
//#endregion
|
|
776
776
|
export { restoreCmd };
|
|
777
777
|
|
|
778
|
-
//# sourceMappingURL=restore-
|
|
778
|
+
//# sourceMappingURL=restore-D0VYWzfP.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"restore-R-4rbciV.js","names":["#storage","#currentJsonKey","#maxRetries","#initialBackoffMs","#random","#indexes","#verifyLogIntegrityOnCommit","#singleAttemptCommit","#backoff","#emitWriteMetrics","#provisionCurrentJson","#walkLog","#observe429","#cleanupStaleIndexKeysBestEffort","#readPreImage"],"sources":["../packages/server/src/doc-id.ts","../packages/server/src/key-limit.ts","../packages/server/src/log-conflict-adoption.ts","../packages/server/src/writer.ts","../packages/cli/src/admin/restore.ts"],"sourcesContent":["import { assertPathSegment } from \"./path-segment.ts\";\n\n/**\n * Guard a caller-supplied `_id` before it becomes a written key segment\n * (index keys, log `doc_id`) or filesystem path (`LocalFsStorage`). The\n * `_id` analogue of `assertKeySegment` (`db.ts`). Routes through the\n * single shared {@link assertPathSegment} rule (empty / `\"/\"` /\n * `\".\"`|`\"..\"` / C0-C1 control chars / leading `\"_\"` (ADR-003) / overlong,\n * all as `BaerlyError{code:\"InvalidConfig\"}`).\n */\nexport const assertDocId = (id: string): void => {\n assertPathSegment(id, \"_id\");\n};\n","import { BaerlyError, MAX_KEY_BYTES } from \"@baerly/protocol\";\n\nconst utf8 = new TextEncoder();\n\n/**\n * Reject an assembled object key over the S3/R2 full-key ceiling\n * ({@link MAX_KEY_BYTES}) as `InvalidConfig`. Per-segment caps don't\n * bound the sum, and index values skip `assertPathSegment` entirely, so\n * this post-encoding check at the writer's PUT sites is their only\n * overflow guard. @see docs/spec/storage-compatibility.md\n */\nexport const assertKeyWithinLimit = (key: string): void => {\n const bytes = utf8.encode(key).length;\n if (bytes > MAX_KEY_BYTES) {\n throw new BaerlyError(\n \"InvalidConfig\",\n `object key exceeds ${MAX_KEY_BYTES} bytes (got ${bytes}): ${JSON.stringify(key.slice(0, 80))}…`,\n );\n }\n};\n","/**\n * Self-session log-conflict adoption — the one decision that\n * distinguishes a retry of our own prior commit attempt from a\n * peer racing us at the same `seq`.\n *\n * Background. `Writer.#singleAttemptCommit` creates each log entry\n * with `If-None-Match: \"*\"` — and that create IS the commit. A 412 on\n * `/log/<seq>.json` can mean either\n *\n * (a) a peer genuinely won that seq (a foreign entry is committed\n * there); or\n * (b) our OWN previous attempt landed the committing log create but\n * its ack was lost — we never observed the `200` — and we're now\n * re-driving the same logical commit.\n *\n * This function makes the (a)/(b) call. It is callable, separately\n * testable, and patent-disclosable in isolation from the rest of the\n * commit path.\n *\n * ## Soundness invariant\n *\n * Adoption is sound iff all three hold:\n *\n * 1. **Same session.** `existing.session === self.session`. The\n * session id is a per-commit, in-RAM-only secret minted at\n * `Writer.commit` from `crypto.randomUUID().slice(0,\n * SESSION_ID_LENGTH)`; an adversary with bucket-write access\n * can forge any other field but cannot forge a value they\n * did not observe being PUT.\n * 2. **Matching seq.** `existing.seq === self.expectedSeq`. The\n * seq match is also implied by the key shape (the writer\n * reads `/log/<expectedSeq>.json`), but is re-asserted here\n * so the invariant is visible at the decision site.\n * 3. **Matching write intent.** The occupant's writer-minted log\n * fields match the entry this writer just attempted to create.\n * Same session + same seq alone is not sufficient: a collision,\n * test seam, or out-of-model bucket writer must not be able to\n * make this writer adopt a different logical mutation.\n *\n * When any of (1)/(2)/(3) fails, the caller MUST refuse adoption\n * and treat the occupant as a conflicting committed entry.\n *\n * A fourth precondition — single-input commit — is now structural,\n * not a runtime check: `#singleAttemptCommit` takes one `CommitInput`,\n * so a multi-input commit is unrepresentable. It matters because the\n * single `log/<seq>` create is the all-or-nothing commit point, so\n * per-input adoption decisions could not compose.\n *\n * ## Threat model\n *\n * The adversary may (a) write arbitrary bytes to any key in the\n * bucket, (b) replay any PUT they previously observed on the wire,\n * (c) reorder or drop network packets between the writer and the\n * bucket. The adversary may NOT (d) read the writer's local RAM\n * and therefore cannot learn the per-commit `session` id before\n * observing the writer's own `/log/<seq>.json` PUT. Under these\n * constraints, conditions (1)+(2)+(3) close every attack path in\n * the adversarial-replay property test\n * (`tests/integration/log-conflict-adversarial.test.ts`).\n *\n * **Pinned by:** `tests/integration/log-conflict-forgery.test.ts`\n * exercises the session-id-unguessability claim under a\n * `ForgeryStorage` adversary that plants arbitrary entries at the\n * writer's expected log key. Property verified by default at\n * `numRuns: 1000`; `FC_NUM_RUNS=10000` for the hardening sweep.\n *\n * ## Prior art\n *\n * SlateDB's manifest-pivot writer protocol (rfcs/0001-manifest.md,\n * scenarios 1–4) is the closest published prior art on the broader\n * commit-protocol skeleton. SlateDB's scenario 3 — \"conflicting SST\n * has same `writer_epoch` as me\" — is explicitly labelled an\n * **illegal state that should panic**. The three-clause adoption\n * decision encoded here (same session ∧ matching seq ∧ matching intent)\n * recognises that case as the writer's own prior in-flight attempt\n * and adopts it as success rather than aborting, closing the recovery\n * gap SlateDB leaves to operator intervention.\n *\n * Apache Iceberg and Delta Lake commits surface analogous failures as\n * `CommitFailedException` / commit-conflict retries; neither inspects\n * the conflicting object to determine ownership.\n *\n * See `docs/spec/prior-art.md` for the consolidated IDS-shaped\n * differentiation.\n *\n * @see docs/spec/sync-protocol.md §\"Contention and retries\"\n */\n\nimport type { LogEntry } from \"@baerly/protocol\";\n\n/**\n * Inputs to {@link tryAdoptOwnSessionLogEntry}. All fields are\n * required; the writer constructs this struct at the call site.\n */\nexport interface AdoptionContext {\n /**\n * The entry the writer just attempted to PUT. Carries the\n * writer's session, expected seq, and the rest of the LogEntry\n * shape minted in `Writer.#singleAttemptCommit` step 3.\n */\n readonly self: LogEntry;\n /**\n * The entry currently stored at `/log/<self.seq>.json`, as read\n * back after a 412. The caller is responsible for the GET (the\n * function is pure, no I/O).\n */\n readonly existing: LogEntry;\n}\n\n/**\n * Discriminated outcome of {@link tryAdoptOwnSessionLogEntry}.\n * `adopt: true` carries the existing entry (which by the invariant\n * matches `self` on writer-minted intent fields); the caller\n * substitutes it for `self` so the returned `CommitResult` matches\n * what's actually stored. `adopt: false` carries a machine-readable\n * `reason` so callers and tests can discriminate which clause of the\n * invariant failed.\n */\nexport type AdoptionDecision =\n | { readonly adopt: true; readonly entry: LogEntry }\n | {\n readonly adopt: false;\n readonly reason: \"foreign-session\" | \"wrong-seq\" | \"intent-mismatch\";\n };\n\n/**\n * Decide whether the entry already at `/log/<seq>.json` is the\n * writer's own prior in-flight attempt and may be adopted. Pure\n * function; no I/O. The caller performs the GET (when the log PUT\n * surfaces 412) and passes the read-back body in `ctx.existing`.\n *\n * ## Correctness precondition\n *\n * A fresh `session` id is minted per `commit()` call, seq-stable\n * across that call's retries. Adoption compares the writer-minted\n * intent/body fields as well as session and seq: a dropped-ack retry\n * reuses the same attempted entry and adopts, while a same-session /\n * same-seq occupant carrying a different logical mutation is treated as\n * a conflict and skipped by the caller's forward-probe loop.\n *\n * @see {@link AdoptionDecision} for the return shape.\n * @see The soundness invariant in this module's header docstring.\n */\nexport const tryAdoptOwnSessionLogEntry = (ctx: AdoptionContext): AdoptionDecision => {\n // Clause (1) — same session.\n if (ctx.existing.session !== ctx.self.session) {\n return { adopt: false, reason: \"foreign-session\" };\n }\n // Clause (2) — matching seq. The seq is also implied by the\n // key the caller read from, but re-asserted here for\n // patent-disclosure clarity.\n if (ctx.existing.seq !== ctx.self.seq) {\n return { adopt: false, reason: \"wrong-seq\" };\n }\n // Clause (3) — matching write intent: full-entry equality, including\n // `commit_ts`. A legitimate lost-ack self-retry passes this ONLY under\n // two premises:\n // P1 (single mint): `commit_ts`/`lsn`/`session` are minted once per\n // `#singleAttemptCommit` (one `Date.now()`) and the inner\n // transient-retry loop re-PUTs the IDENTICAL `entry`, so a real\n // read-back is byte-identical to `self`, `commit_ts` included.\n // P2 (order-stable round-trip): stored bytes are\n // `encodeJsonBytes` (`JSON.stringify`) and read back via\n // `JSON.parse`; `JSON.stringify(JSON.parse(...))` preserves key\n // order, so the two stringifications match.\n // If either breaks (re-mint on retry, or a canonical/sorting encoder /\n // normalizing read-back), a legit self-retry would falsely mismatch\n // here and DUPLICATE-write. P2 is pinned by `bytes.test.ts`.\n if (JSON.stringify(ctx.existing) !== JSON.stringify(ctx.self)) {\n return { adopt: false, reason: \"intent-mismatch\" };\n }\n return { adopt: true, entry: ctx.existing };\n};\n","/**\n * `Writer` — stateless multi-instance write engine (single-write commit).\n *\n * Each {@link Writer.commit} reads `current.json` FRESH (for\n * `log_seq_start` / `tail_hint` as a probe FLOOR — a lower bound, NOT a\n * CAS precondition), PUTs the content body, then **creates `log/<seq>`\n * via `If-None-Match: \"*\"`. That create IS the commit / linearization\n * point.** The writer writes NOTHING to `current.json` on the commit\n * path; `tail_hint` advances outside ordinary commits via compaction\n * folds, write-tick refreshes, and explicit operator/import paths. The\n * commit model and its invariants are recorded in ADR-004\n * (`docs/adr/004-single-write-commit.md`). The\n * optional integrity walk is gated by\n * {@link WriterOptions.verifyLogIntegrityOnCommit} (default off).\n *\n * No per-write cache: every commit re-reads + re-probes, so N stateless\n * instances contend at one place — the `If-None-Match` create of\n * `log/<seq>`. The loser gets a 412 and re-probes forward to the next\n * empty slot. A 412 from the writer's OWN session at the same seq is its\n * own lost-ack / crashed-but-durable commit → adopted (not retried), so\n * the write lands at EXACTLY `seq`, never duplicated.\n *\n * **Crash safety.** Order is content + additive index `newKeys` →\n * `log/<seq>` create → stale index-key DELETEs. A crash before the\n * create leaves an unreferenced content body + orphan additive index\n * keys (no log entry references them), not an orphan log entry with\n * missing content — the compactor sweeps the content, and a stray\n * additive key only ever yields a false-POSITIVE candidate that\n * `matchesWire` (read path) drops. Emitting `newKeys` before the commit\n * means a committed row is ALWAYS index-findable; the stale-key DELETE\n * stays after the commit so a crash can never de-index a committed\n * doc. See `index-emit-order.test.ts` and ADR-004 Q4.\n *\n * **`LogEntry` shape.** Emitted entries follow the contract in\n * `packages/protocol/src/log.ts` (see {@link LogEntry}) and\n * `docs/spec/log-entry-shape.md`. The on-bucket key is\n * `log/<seq>.json` (the integer `seq` is the load-bearing\n * identifier; the `lsn` string is schema-only).\n *\n * @see docs/spec/sync-protocol.md for the protocol invariants this\n * loop preserves.\n * @see docs/spec/log-entry-shape.md for the per-field contract.\n */\n\nimport {\n CURRENT_JSON_SCHEMA_VERSION,\n type CurrentJson,\n type CurrentJsonRead,\n type DocumentData,\n type LogEntry,\n type MetricsRecorder,\n createCurrentJson,\n decodeJsonBytes,\n encodeJsonBytes,\n logObjectKey,\n logSeqStartOf,\n BaerlyError,\n noopMetricsRecorder,\n type Storage,\n LOG_FORWARD_PROBE_CAP,\n MAINTENANCE_PROFILE_CF_FREE,\n MAINTENANCE_TAIL_HINT_REFRESH_WRITES,\n S3_REQUEST_MAX_RETRIES,\n SESSION_ID_LENGTH,\n countKey,\n readCurrentJson,\n timestamp,\n uuid,\n versionFromContent,\n} from \"@baerly/protocol\";\nimport { assertDocId } from \"./doc-id.ts\";\nimport { allIndexKeysFor, type IndexDefinition, validateIndexDefinition } from \"./indexes.ts\";\nimport { assertKeyWithinLimit } from \"./key-limit.ts\";\nimport { readLogEntry, walkLogRange } from \"./log-walk.ts\";\nimport { findLogTail } from \"./log-tail.ts\";\nimport { tryAdoptOwnSessionLogEntry } from \"./log-conflict-adoption.ts\";\nimport {\n dispatchInlineAwaited,\n runBoundedMaintenance,\n shouldFireMaintenance,\n} from \"./maintenance.ts\";\nimport { getCurrentContext } from \"./observability/context.ts\";\n\nconst CAS_CONFLICT_RESOLUTION = \"Re-read and retry.\";\n\nconst ctxMetrics = (): MetricsRecorder => getCurrentContext()?.recorder ?? noopMetricsRecorder;\n\n/**\n * Tunables for {@link Writer}. All optional; defaults match the\n * legacy retry budget so the new loop is a drop-in replacement.\n */\nexport interface WriterOptions {\n /**\n * Max retryable `Conflict` attempts before throwing `Conflict`.\n * Foreign log-create 412s are resolved inside a single attempt by\n * occupant read-back plus bounded forward re-probe; this budget is\n * retained for future retryable conflicts and tests.\n */\n readonly maxRetries?: number;\n\n /** Initial backoff in ms; doubles per attempt, capped at 1500ms. Default 25. */\n readonly initialBackoffMs?: number;\n\n /**\n * Pure function returning a number in [0, 1). Used for jitter; tests\n * inject a deterministic generator. Defaults to `Math.random`.\n */\n readonly random?: () => number;\n\n /**\n * Optional. Indexes declared for the collection this writer\n * commits to. Each commit emits one zero-byte PUT per declared\n * index (when the indexed field is set on the doc) — the additive\n * `newKeys` go down BEFORE the committing `log/<seq>` create, so a\n * committed row is always index-findable. On U/D, the writer reads\n * the pre-image content body from the log (one back-walk per\n * indexed collection, NOT per index) to compute the stale-key set;\n * stale keys are DELETE'd AFTER the commit, computed from the\n * resolved committing seq's pre-image.\n *\n * Validated at construction via {@link validateIndexDefinition} —\n * an invalid def throws `BaerlyError{code:\"SchemaError\"}`\n * synchronously, before the first commit. Empty / undefined is\n * a no-op (writer behaves identically to the no-index path — no\n * extra GET, no extra PUTs).\n *\n * Note: `Writer` is per-collection (the `currentJsonKey`\n * is per-collection), so this array applies to one collection\n * only — adapters that serve multiple collections instantiate\n * one writer per collection.\n *\n * Emits one new metric when at least one index is declared:\n * - `db.write.index_ops_per_logical_write` (histogram,\n * labelled by `collection`) — `K (PUT) + L (DELETE)` per\n * successful commit.\n */\n readonly indexes?: ReadonlyArray<IndexDefinition>;\n\n /**\n * When `true`, every commit walks the live log range\n * `[log_seq_start, tail_hint)` before minting a new entry, surfacing\n * a missing or malformed entry as `BaerlyError{code:\"Internal\"}`\n * (or `\"InvalidResponse\"` for parse failures). The walk is purely\n * observational — the per-doc fold lives in the read path\n * (`./query.ts`) and any hole inside the visible range would also\n * fire on the next read.\n *\n * Production callers default this OFF: under contention the walk\n * issues `O(tail)` Class-B GETs per CAS attempt and the retry\n * budget multiplies that by {@link S3_REQUEST_MAX_RETRIES}. Tests\n * that intentionally puncture bucket state to exercise the\n * invariant trigger opt in by passing `true`.\n *\n * Default `false`.\n */\n readonly verifyLogIntegrityOnCommit?: boolean;\n}\n\n/**\n * Single-doc mutation request. One `commit()` ↔ one {@link LogEntry}.\n */\nexport interface CommitInput {\n /** The mutation op. Maps directly to {@link LogEntry.op}. */\n readonly op: \"I\" | \"U\" | \"D\";\n\n /** The collection (table) name. Becomes {@link LogEntry.collection}. */\n readonly collection: string;\n\n /** The document primary key. Becomes {@link LogEntry.doc_id}. */\n readonly docId: string;\n\n /**\n * For `I` / `U`: the post-image. Becomes {@link LogEntry.after}. Must\n * be `undefined` for `op: \"D\"`.\n */\n readonly body?: DocumentData;\n\n /** Optional ISO-8601 origin marker; becomes {@link LogEntry.origin}. */\n readonly origin?: string;\n}\n\n/** Return shape of {@link Writer.commit}. */\nexport interface CommitResult {\n /** The committed `LogEntry`. Caller can ack on `entry.lsn`. */\n readonly entry: LogEntry;\n\n /**\n * ETag of `current.json` as read at the start of the commit. The\n * commit path no longer writes `current.json` (the `log/<seq>`\n * create IS the commit), so this is the manifest's pre-commit ETag,\n * not a post-write one.\n */\n readonly currentEtag: string;\n\n /** How many commit attempts it took (1 = first try won). */\n readonly attempts: number;\n}\n\nconst DEFAULT_INITIAL_BACKOFF_MS = 25;\nconst MAX_BACKOFF_MS = 1500;\nconst APPLICATION_JSON = \"application/json\";\n\n/**\n * Empty body for index entries. Each index entry is a fact (\"doc\n * `<docId>` has `<field> = <value>`\"), not data — readers list the\n * prefix, extract the doc id, then GET the content body separately.\n * Pre-allocated module-level constant so every index PUT shares one\n * zero-length buffer.\n */\nconst EMPTY_BODY = new Uint8Array(0);\n\n/**\n * Successful outcome of one full {@link Writer.#singleAttemptCommit}\n * attempt. A retryable log-create 412 that resolved to a foreign-session\n * occupant beyond the forward-probe budget throws\n * `BaerlyError{code:\"Conflict\"}`; the caller catches via\n * {@link isPreconditionFailed} and decides whether to retry. Non-retryable\n * failures (protocol-invariant violations, network errors) propagate.\n */\ninterface SingleAttemptSuccess {\n readonly entries: readonly LogEntry[];\n readonly currentEtag: string;\n readonly classAOps: number;\n}\n\n/**\n * Stateless write engine for the multi-instance core.\n *\n * Construction is cheap and performs zero I/O — adapters build a\n * fresh `Writer` per request and discard it. All real work\n * happens in {@link commit}.\n *\n * @example\n * ```ts\n * import { Writer } from \"@gusto/baerly-storage\";\n * import { MemoryStorage } from \"@gusto/baerly-storage\";\n *\n * const writer = new Writer({\n * storage: new MemoryStorage(),\n * currentJsonKey: \"app/tickets/tenant/acme/manifests/tickets/current.json\",\n * });\n *\n * const result = await writer.commit({\n * op: \"I\",\n * collection: \"tickets\",\n * docId: \"doc-1\",\n * body: { _id: \"doc-1\", title: \"hello\" },\n * });\n * console.log(result.entry.seq, result.attempts);\n * ```\n */\nexport class Writer {\n readonly #storage: Storage;\n readonly #currentJsonKey: string;\n readonly #maxRetries: number;\n readonly #initialBackoffMs: number;\n readonly #random: () => number;\n readonly #indexes: ReadonlyArray<IndexDefinition>;\n readonly #verifyLogIntegrityOnCommit: boolean;\n\n constructor(opts: {\n storage: Storage;\n /**\n * Full bucket-relative key of the CAS pointer, e.g.\n * `app/tickets/tenant/acme/manifests/tickets/current.json`. The\n * collection-prefix half lives at\n * `currentJsonKey.slice(0, currentJsonKey.lastIndexOf(\"/\"))` — the\n * log and content keys are derived from it.\n */\n currentJsonKey: string;\n options?: WriterOptions;\n }) {\n this.#storage = opts.storage;\n this.#currentJsonKey = opts.currentJsonKey;\n this.#maxRetries = opts.options?.maxRetries ?? S3_REQUEST_MAX_RETRIES;\n this.#initialBackoffMs = opts.options?.initialBackoffMs ?? DEFAULT_INITIAL_BACKOFF_MS;\n this.#random = opts.options?.random ?? Math.random;\n const indexes = opts.options?.indexes ?? [];\n for (const def of indexes) {\n validateIndexDefinition(def);\n }\n this.#indexes = indexes;\n this.#verifyLogIntegrityOnCommit = opts.options?.verifyLogIntegrityOnCommit ?? false;\n }\n\n /**\n * Atomically commit one mutation. Reads `current.json` fresh (as a\n * probe FLOOR, not a CAS precondition), PUTs the content body and any\n * additive index `newKeys`, then creates `log/<seq>` via\n * `If-None-Match: \"*\"` — that create IS the commit (single-write\n * commit; no `current.json` CAS follows it). Stale index keys are\n * DELETE'd after the commit.\n *\n * The hot-path cost under no contention on an unindexed collection is\n * 1 GET + 2 PUTs (content + the committing `log/<seq>` create); each\n * declared index that projects a key on this write adds one PUT\n * (new key, before the commit) and, on U/D, up to one DELETE (stale\n * key, after the commit). An in-flight peer write costs one extra GET\n * + the backoff sleep per retry.\n *\n * Idempotency: PUT content uses `If-None-Match: \"*\"`, so a retry of\n * the same logical write produces the same content key and the\n * second PUT no-ops. The `log/<seq>` create also uses\n * `If-None-Match: \"*\"`, so two writers racing the same tail cause\n * exactly one create to win; the loser reads back the occupant,\n * adopts its own lost-ack write or re-probes forward to the next\n * empty slot.\n *\n * @throws BaerlyError code=\"Conflict\" when a retryable conflict\n * escapes the single-attempt helper and exhausts the retry budget\n * (presently unreachable on the log-create 412 path).\n * @throws BaerlyError code=\"Internal\" when a log entry expected in\n * `[0, tail_hint)` is missing — a protocol-invariant violation\n * (compactor bug or stale `current.json`).\n * @throws BaerlyError code=\"InvalidResponse\" when a log-entry body\n * isn't valid JSON.\n *\n * **Implicit provisioning.** When `current.json` does not exist at\n * `currentJsonKey` (fresh bucket, fresh collection), the writer\n * auto-creates it with a zero-state manifest before the commit\n * lands. The cost is one extra Class A PUT on the very first\n * commit per collection; steady-state cost is unchanged. A peer\n * racing the same first-write loses cleanly on the create CAS\n * and re-reads to pick up the winner's manifest.\n */\n async commit(input: CommitInput): Promise<CommitResult> {\n // Validate the doc id BEFORE any I/O so every commit caller — the\n // public write path AND a direct caller like `baerly admin restore`\n // — is covered (defense in depth, mirroring the db-layer guard).\n // Rejects empty / `\"/\"` / `\".\"`|`\"..\"` / control / leading `\"_\"` /\n // overlong `docId` as `BaerlyError{code:\"InvalidConfig\"}`, so a\n // traversal-shaped `_id` can never become a written key segment.\n assertDocId(input.docId);\n const session = uuid().slice(0, SESSION_ID_LENGTH);\n const logPrefix = this.#currentJsonKey.slice(0, this.#currentJsonKey.lastIndexOf(\"/\"));\n\n // NOTE: with the post-commit fence-verify removed, no `Conflict`\n // currently escapes `#singleAttemptCommit` — a log-create 412 is\n // always resolved internally (own-session adoption or a bounded\n // forward-probe to the next empty slot; only an exhausted probe cap\n // throws, as `Internal`, not `Conflict`). So the retry-catch arm and\n // the budget-exhausted `Conflict` throw below are presently\n // unreachable. They are retained deliberately: they cost nothing on\n // the happy path and re-arm automatically if a future change ever\n // re-introduces a retryable `Conflict` out of the helper.\n for (let attempt = 1; attempt <= this.#maxRetries; attempt++) {\n let success: SingleAttemptSuccess;\n try {\n success = await this.#singleAttemptCommit(input, session, logPrefix, \"Writer\");\n } catch (error) {\n // Only a retryable `Conflict` (see NOTE above — currently none)\n // backs off and retries. Anything else propagates.\n if (!isPreconditionFailed(error)) {\n throw error;\n }\n await this.#backoff(attempt);\n continue;\n }\n // `success.classAOps` is the per-attempt base; add `(attempt\n // - 1)` to bill prior failed attempts as one PUT each (the\n // simple-and-test-locked cost model — not a precise replay\n // of every PUT in every dropped attempt).\n this.#emitWriteMetrics(input.collection, success.classAOps + (attempt - 1));\n return {\n entry: success.entries[0]!,\n currentEtag: success.currentEtag,\n attempts: attempt,\n };\n }\n\n // Retry budget exhausted.\n throw new BaerlyError(\n \"Conflict\",\n `Writer: CAS conflict on ${this.#currentJsonKey} after ${this.#maxRetries} attempts`,\n undefined,\n undefined,\n undefined,\n CAS_CONFLICT_RESOLUTION,\n true,\n );\n }\n\n /**\n * One full commit attempt — the body of {@link commit}. Reads\n * `current.json`, PUTs content + additive index `newKeys` in parallel,\n * then forward-probes the tail and creates `log/<seq>` once via\n * `If-None-Match: \"*\"` — the numbered log create IS the commit\n * (single-write commit; no `current.json` CAS follows it). Stale index\n * keys are DELETE'd after the commit. Returns the success payload.\n *\n * Commits exactly one {@link CommitInput} — the numbered log create is\n * the single linearization point per call.\n *\n * A log-create 412 is disambiguated by session read-back: own session\n * / own seq ⇒ our crashed-or-lost-ack commit is already durable ⇒\n * adopt; foreign session ⇒ re-probe forward and retry at the next\n * empty slot. Thrown `BaerlyError`s (Internal, InvalidResponse,\n * NetworkError) propagate.\n *\n * Crash safety invariant: content + additive index `newKeys` PUTs are\n * awaited before the log create. A crash before the create leaves\n * orphan content + additive index keys (no log entry references them)\n * — the compactor sweeps the content, and a stray additive key only\n * yields a false-positive candidate that `matchesWire` drops. A crash\n * AFTER the create is a durable, committed write at `seq` whose index\n * `newKeys` are already present (so it's index-findable); the only\n * residual is a possibly-undeleted stale OLD-value key, dropped by\n * `matchesWire` and cleaned by a later write / `rebuild-index`. The\n * inverse — committed log entry with missing content, or a de-indexed\n * committed doc — is never produced.\n */\n async #singleAttemptCommit(\n input: CommitInput,\n session: string,\n logPrefix: string,\n errorPrefix: string,\n ): Promise<SingleAttemptSuccess> {\n // ── Step 1. Read current.json (fresh; carries the ETag). ────────\n // On a fresh bucket / fresh collection the manifest doesn't exist\n // yet. Auto-create it with a zero-state initial so `db.collection(x)\n // .insert(...)` works zero-shot. A peer racing the same create\n // loses cleanly on `If-None-Match: \"*\"`; we re-read to pick up\n // the winner's manifest. Cost: one extra Class A PUT on the very\n // first commit per collection, zero overhead thereafter.\n const read =\n (await readCurrentJson(this.#storage, this.#currentJsonKey)) ??\n (await this.#provisionCurrentJson());\n const current = read.json;\n const baseEtag = read.etag;\n\n // ── Step 2. Optional integrity walk (`verifyLogIntegrityOnCommit`,\n // default off). Surfaces missing / malformed entries inside\n // `[log_seq_start, tail_hint)` as `Internal` / `InvalidResponse`;\n // entries below `log_seq_start` are folded into the snapshot\n // by `compact()` and possibly swept by `runGc()`, so the walk is\n // bounded to the live tail. The read path catches the same\n // conditions on the next consult — production callers leave the\n // walk off to avoid `O(tail)` Class-B GETs per CAS attempt.\n if (this.#verifyLogIntegrityOnCommit) {\n await this.#walkLog(logPrefix, logSeqStartOf(current), current.tail_hint);\n }\n\n // ── Step 3. Find the true tail (Class B forward-probe), then mint. ─\n // `tail_hint` is a non-authoritative lower bound (the writer no\n // longer advances it — only the compactor stamps it durably). The\n // forward-probe discovers the first empty seq >= the floor: the slot\n // this commit will create. Floor at `max(log_seq_start, tail_hint)`\n // so a compactor that advanced `log_seq_start` past a stale\n // `tail_hint` doesn't make us re-walk folded-but-unswept entries.\n // Bind to a local (oxlint `no-await-expression-member`).\n const probeFloor = Math.max(logSeqStartOf(current), current.tail_hint);\n // `findLogTail`'s density precondition holds: the floor sits in the\n // dense prefix because tail_hint advancers probe or derive known tails\n // from committed entries, while ordinary writer commits never stamp\n // `tail_hint`, so nothing advances the floor past a hole.\n const preCommitTail = await findLogTail(this.#storage, logPrefix, probeFloor);\n let seq = preCommitTail;\n\n // All entries share `session` (one session per logical commit) and\n // a single commit instant: `lsn`'s timestamp and `commit_ts` are\n // derived from ONE clock read so they can't drift apart under skew\n // (a reader validates `commit_ts` against `LAG_WINDOW_MILLIS`, and\n // two independent reads could straddle that band). The LSN's\n // `countKey(seq)` suffix MUST track the probed seq — it's compared on\n // adoption, so a stale suffix would misfire the disambiguation.\n const commitNowMs = Date.now();\n const commitTs = new Date(commitNowMs).toISOString();\n const lsnTimestamp = timestamp(commitNowMs);\n const mintEntry = (atSeq: number): LogEntry => ({\n lsn: `${lsnTimestamp}_${session}_${countKey(atSeq)}`,\n commit_ts: commitTs,\n op: input.op,\n collection: input.collection,\n doc_id: input.docId,\n session,\n seq: atSeq,\n ...(input.op !== \"D\" && input.body !== undefined ? { after: input.body } : {}),\n ...(input.origin !== undefined ? { origin: input.origin } : {}),\n });\n let entry = mintEntry(seq);\n\n // ── Step 4. PUT content bodies + additive index `newKeys` (BEFORE\n // the commit). ──────────────────────────────────────────────────\n // Content PUT: `ifNoneMatch: \"*\"` makes a same-hash re-write a\n // no-op (412 swallowed). Crash-recovery and same-body replay\n // both rely on this idempotency property. Content is content-\n // addressed, so writing it before the commit is crash-safe: a\n // crash here leaves an unreferenced body the compactor sweeps,\n // never an orphan log entry with missing content.\n //\n // Additive index `newKeys` (the markers for the doc's NEW value)\n // ALSO go down here, before the committing create. `newKeys`\n // depend only on `body` + `docId` (NOT on `seq`), so they're\n // stable across the forward re-probe — emit them once. Emitting\n // BEFORE the commit guarantees a committed row is ALWAYS index-\n // findable (no false-negative). A crash after a `newKey` PUT but\n // before the commit leaves an orphan additive key for an\n // UNcommitted write — benign: the index read includes the\n // candidate docId, the fold finds no committed (or the prior)\n // value, and `matchesWire` (query.ts) drops the false-positive.\n // The stale-key DELETEs (de-indexing the OLD value) stay AFTER the\n // commit (Step 5b), so a crash can never de-index a committed doc.\n // See ADR-004 Q4 + `index-emit-order.test.ts`.\n let contentPutCount = 0;\n let newKeysClassA = 0;\n const parallelPuts: Array<Promise<unknown>> = [];\n if (input.op !== \"D\" && input.body !== undefined) {\n contentPutCount++;\n const bytes = encodeJsonBytes(input.body);\n const version = await versionFromContent(bytes);\n const contentKey = `${logPrefix}/content/${version}.json`;\n assertKeyWithinLimit(contentKey);\n parallelPuts.push(\n this.#storage\n .put(contentKey, bytes, { ifNoneMatch: \"*\", contentType: APPLICATION_JSON })\n .catch((error: unknown) => {\n this.#observe429(error, input.collection);\n if (isPreconditionFailed(error)) {\n return;\n }\n throw error;\n }),\n );\n }\n // Additive index keys for the NEW value — emitted before the\n // commit on I/U (a D has no new value). `op:\"D\"` and a missing\n // body project to no keys. Empty `#indexes` short-circuits.\n if (this.#indexes.length > 0 && input.op !== \"D\") {\n const newKeys = allIndexKeysFor(logPrefix, this.#indexes, input.body, input.docId);\n for (const k of newKeys) {\n assertKeyWithinLimit(k);\n newKeysClassA++;\n parallelPuts.push(\n this.#storage\n .put(k, EMPTY_BODY, { ifNoneMatch: \"*\", contentType: APPLICATION_JSON })\n .catch((error: unknown) => {\n this.#observe429(error, input.collection);\n if (isPreconditionFailed(error)) {\n return;\n }\n throw error;\n }),\n );\n }\n }\n await Promise.all(parallelPuts);\n\n // ── Step 5. Create the commit: PUT log/<seq> via If-None-Match. ─\n // The numbered log create IS the commit (single-write commit). No\n // `current.json` CAS follows it — the create is the linearization\n // point (exactly-one-winner, CI-gated across all backends).\n //\n // 200 ⇒ committed at `seq`. 412 ⇒ disambiguate by session read-back:\n // - own session / own seq ⇒ our crashed-or-lost-ack commit is\n // already durable at `seq` ⇒ adopt the resolved `seq` and fall\n // through to the SAME index emit (Step 5b). The adopted commit\n // is EXACTLY the attempt that may have died after creating\n // `log/<seq>` but before emitting its index, so re-running the\n // (idempotent) emit completes it.\n // - foreign session / wrong seq ⇒ re-probe forward and retry at the\n // new first-empty slot (bounded by LOG_FORWARD_PROBE_CAP).\n // A transient NetworkError (e.g. a dropped ack on a create that may\n // already have landed) retries the SAME `seq`: the retry either\n // re-creates (write never landed) or hits the durable write → 412 →\n // own-session adoption. Either way the write lands at EXACTLY `seq`,\n // never duplicated.\n let committedEntry: LogEntry = entry;\n let probes = 0;\n let transientRetries = 0;\n for (;;) {\n const logEntryKey = logObjectKey(logPrefix, seq);\n assertKeyWithinLimit(logEntryKey);\n let conflicted = false;\n try {\n await this.#storage.put(logEntryKey, encodeJsonBytes(entry), {\n ifNoneMatch: \"*\",\n contentType: APPLICATION_JSON,\n });\n } catch (error) {\n this.#observe429(error, entry.collection);\n if (isPreconditionFailed(error)) {\n ctxMetrics().counter(\"db.r2.put.412_total\", 1, {\n collection: entry.collection,\n step: \"log-put\",\n });\n conflicted = true;\n } else if (isTransientWrite(error) && transientRetries < this.#maxRetries) {\n // Possible lost-ack — retry the SAME seq (idempotent: adoption\n // closes the double-commit window). Bounded backoff (full jitter,\n // same as the outer loop) so a backend in transient distress\n // isn't hammered; a persistent NetworkError still surfaces.\n transientRetries++;\n await this.#backoff(transientRetries);\n continue;\n } else {\n throw error;\n }\n }\n if (!conflicted) {\n committedEntry = entry;\n break;\n }\n // 412 — read back the occupant and decide.\n const existing = await readLogEntry(this.#storage, logEntryKey);\n const decision = tryAdoptOwnSessionLogEntry({\n self: entry,\n existing,\n });\n if (decision.adopt) {\n // Own crashed/lost-ack commit already durable at `seq`. Adopt it\n // (byte-identical to the attempted `entry`, INCLUDING `commit_ts`\n // — adoption compares the full entry) — the logical write lands at\n // EXACTLY `seq`, never duplicated. Fall through to Step 5b: the\n // adopted attempt may have died after the create but before the\n // index emit, so the (idempotent) emit must still run.\n committedEntry = decision.entry;\n break;\n }\n // Foreign session (or wrong seq) — re-probe forward from seq+1 and\n // retry at the new first-empty slot, re-minting seq + LSN.\n if (++probes > LOG_FORWARD_PROBE_CAP) {\n throw new BaerlyError(\n \"Internal\",\n `${errorPrefix}: log-tail forward-probe exceeded ${LOG_FORWARD_PROBE_CAP} on ${this.#currentJsonKey}`,\n );\n }\n seq = await findLogTail(this.#storage, logPrefix, seq + 1);\n entry = mintEntry(seq);\n }\n const committedEntries: readonly LogEntry[] = [committedEntry];\n\n // ── Step 5b. DELETE stale secondary-index keys (AFTER the commit). ─\n // The additive `newKeys` already went down in Step 4 (before the\n // commit), so a committed row is always index-findable. This block\n // handles only the OTHER half: deleting the OLD value's now-obsolete\n // markers. Keeping the stale-key DELETE AFTER the commit is the\n // load-bearing polarity (ADR-004 Q4): a crash here leaves the OLD\n // value's marker lingering — benign, the index read includes the\n // candidate, the fold sees the doc's NEW committed value, and\n // `matchesWire` (query.ts) drops the false-positive; the lingering\n // key is cleaned by a later same-doc write or operator\n // `rebuild-index`. The inverse — de-indexing a committed doc with no\n // log entry to drive repair — can NEVER happen, since the DELETE is\n // strictly after the commit.\n //\n // BOTH the fresh-win and the own-session-adoption break above reach\n // here with the resolved committing `seq`. Adoption correctness: an\n // adopted lost-ack commit is EXACTLY the attempt that may have died\n // after the create but before this DELETE, so it MUST run it too (do\n // not skip it). Idempotent under re-run: `Storage.delete` is\n // contractually idempotent, and the Step-4 `newKeys` PUT is\n // `ifNoneMatch: \"*\"` (412 swallowed).\n //\n // Empty `#indexes` short-circuits the whole block (including the\n // pre-image GET), preserving zero behaviour change for collections\n // without declared indexes. An `op:\"I\"` has no pre-image and no\n // stale keys, so it never reads.\n //\n // The pre-image is read at the RESOLVED committing `seq` (Step 5\n // may have advanced `seq` past a foreign winner): `#readPreImage`\n // back-walks from `seq - 1`, so it skips the just-committed entry\n // and finds the prior same-doc image.\n //\n // Filter-aware projection (T4): `allIndexKeysFor` short-circuits on\n // `def.predicate` miss. The diff `oldKeys \\ newKeys` covers all four\n // U-quadrants (match→match deletes only the changed keys; match→miss\n // DELETEs all; miss→match deletes nothing; miss→miss no-ops), each\n // pinned by a named test in `writer.test.ts` (\"Writer — filtered\n // index\").\n const staleKeysClassA = await this.#cleanupStaleIndexKeysBestEffort({\n input,\n logPrefix,\n seq,\n });\n // The per-logical-write index-op histogram counts BOTH halves: the\n // `newKeys` PUTs (Step 4) and the `staleKeys` DELETEs (Step 5b).\n const indexClassA = newKeysClassA + staleKeysClassA;\n if (this.#indexes.length > 0 && indexClassA > 0) {\n ctxMetrics().histogram(\"db.write.index_ops_per_logical_write\", indexClassA, {\n collection: input.collection,\n });\n }\n\n // ── Step 6. (removed). No current.json write on the commit path. ─\n // The numbered log create above IS the commit. `tail_hint` is\n // refreshed durably only by the compactor; the writer never advances\n // it. The maintenance trigger below reads a DERIVED tail-byte\n // estimate (`estimateTailBytes`), so there is no stored byte counter.\n\n // ── Step 6b. Write-tick maintenance dispatch. ───────────────────\n // Single funnel site: write-tick maintenance dispatch. Reached by\n // `commit()` exactly once per logical commit, after the committing\n // log create has landed.\n //\n // Config rides the per-request observability context\n // (`getCurrentContext()?.maintenance`), set by the adapter — NOT the\n // Writer constructor / `Db.create`. Absent ⇒ inline dispatch +\n // CF-free-safe caps, so a bare `Db.create(...).collection(...)\n // .insert(...)` maintains inline by default once enough writes\n // accrue.\n //\n // `prevSeq` is the pre-commit tail (`preCommitTail`); the slot we won\n // is `seq` (== prevSeq unless a forward re-probe moved it past a\n // foreign winner), so the boundary check spans `(prevSeq,\n // observedTail]`. `observedTail = seq+1` is a fresh in-memory lower\n // bound on the true tail: winning `log/<seq>` means `[tail_hint, seq)`\n // were observed occupied, so `seq+1 ≤ true tail`. We pass `current`\n // (the Step-1 read) for the snapshot fields — there is no `next`.\n const prevSeq = preCommitTail;\n const observedTail = seq + 1;\n const maint = getCurrentContext()?.maintenance;\n // Same absent-context default as runBoundedMaintenance's\n // `options?.profile ?? MAINTENANCE_PROFILE_CF_FREE` — keep the two in\n // step (this gate reads only gcInterval; the runner resolves the whole\n // profile) so the pre-fire cadence can't diverge from the fold's.\n const gcInterval =\n maint?.options?.profile?.gcInterval ?? MAINTENANCE_PROFILE_CF_FREE.gcInterval;\n const maintenanceDue =\n maint?.disabled === true\n ? observedTail - current.tail_hint >= MAINTENANCE_TAIL_HINT_REFRESH_WRITES\n : shouldFireMaintenance(current, prevSeq, gcInterval, observedTail);\n if (maintenanceDue) {\n const dispatch = maint?.dispatch ?? dispatchInlineAwaited;\n // `await dispatch(...)`: `dispatchInlineAwaited` returns the\n // task's promise (awaited inline — deterministic for tests +\n // correct for serverful Node). A `ctx.waitUntil`-style dispatch\n // returns void (fire-and-forget off the ack); `await void` is a\n // no-op. The `.then(() => {}, () => {})` is belt-and-suspenders:\n // `runBoundedMaintenance` already swallows internally, but this\n // guarantees a dispatched task can NEVER reject the commit even\n // if a future change makes it throw.\n await dispatch(() =>\n runBoundedMaintenance(\n {\n storage: this.#storage,\n currentJsonKey: this.#currentJsonKey,\n prevSeq,\n // Thread the in-memory observed tail so the runner's Gate-1\n // ratio + GC cadence key off the true tail without an\n // O(gap) re-probe (the stored `tail_hint` is only a lower\n // bound under single-write commit).\n observedTail,\n // `disabled` disables fold/GC phases inside the runner but\n // still permits the bounded tail_hint refresh that prevents a\n // maintenance-off collection from drifting past the probe cap.\n ...(maint?.disabled === true && { disabled: true }),\n ...(maint?.maxFoldBytes !== undefined && { maxFoldBytes: maint.maxFoldBytes }),\n },\n maint?.options,\n ).then(\n () => {},\n () => {},\n ),\n );\n }\n\n // Base class-A op count for this attempt: content PUTs (skipping\n // `op:\"D\"`) + the single log create + index PUTs + index DELETEs.\n // No current.json CAS anymore. Forward-probe GETs are Class B and\n // excluded. The caller of `commit()` adds `(attempt - 1)` for retry\n // cost.\n const classAOps = contentPutCount + 1 + indexClassA;\n return {\n entries: committedEntries,\n // No current.json write on the commit path — return the manifest\n // etag read in Step 1 (still a valid etag of the current manifest).\n currentEtag: baseEtag,\n classAOps,\n };\n }\n\n /**\n * Auto-create the per-collection `current.json` at\n * `this.#currentJsonKey` with a zero-state initial manifest. Called\n * by `#singleAttemptCommit` when the read returned `null` (fresh\n * bucket / fresh collection).\n *\n * Concurrency: `createCurrentJson` uses `If-None-Match: \"*\"`. If a\n * peer raced us and won, the storage layer surfaces `Conflict`; we\n * recover by re-reading the now-present manifest. We do NOT retry\n * the create — a single recover-via-read covers every race that\n * could have produced our null read.\n *\n * The seed shape (`snapshot: null`, `tail_hint: 0`, `log_seq_start:\n * 0`, `writer_fence: { epoch: 0, owner: \"\", claimed_at: \"\" }`)\n * matches `ensureTable` and `baerly deploy`'s pre-warm path, so an\n * operator who pre-provisions and a writer who auto-creates land\n * on byte-identical bytes.\n *\n * @throws BaerlyError code=\"InvalidResponse\" — the post-recover\n * re-read also returned null. Defensive guard; in practice\n * unreachable because the Conflict implies the key now exists.\n */\n async #provisionCurrentJson(): Promise<CurrentJsonRead> {\n const initial: CurrentJson = {\n schema_version: CURRENT_JSON_SCHEMA_VERSION,\n snapshot: null,\n tail_hint: 0,\n log_seq_start: 0,\n writer_fence: { epoch: 0, owner: \"\", claimed_at: \"\" },\n snapshot_bytes: 0,\n snapshot_rows: 0,\n };\n try {\n return await createCurrentJson(this.#storage, this.#currentJsonKey, initial);\n } catch (error) {\n if (!(error instanceof BaerlyError) || error.code !== \"Conflict\") {\n throw error;\n }\n }\n const recovered = await readCurrentJson(this.#storage, this.#currentJsonKey);\n if (recovered === null) {\n throw new BaerlyError(\n \"InvalidResponse\",\n `Writer: current.json missing at ${this.#currentJsonKey} after auto-create raced and recover read returned null`,\n );\n }\n return recovered;\n }\n\n async #cleanupStaleIndexKeysBestEffort(args: {\n input: CommitInput;\n logPrefix: string;\n seq: number;\n }): Promise<number> {\n if (this.#indexes.length === 0) {\n return 0;\n }\n\n const { input } = args;\n let staleKeys: readonly string[] = [];\n try {\n if (input.op === \"U\") {\n const preImage = await this.#readPreImage(\n args.logPrefix,\n input.collection,\n input.docId,\n args.seq,\n );\n const oldKeys = allIndexKeysFor(args.logPrefix, this.#indexes, preImage, input.docId);\n const newSet = new Set(\n allIndexKeysFor(args.logPrefix, this.#indexes, input.body, input.docId),\n );\n staleKeys = oldKeys.filter((k) => !newSet.has(k));\n } else if (input.op === \"D\") {\n const preImage = await this.#readPreImage(\n args.logPrefix,\n input.collection,\n input.docId,\n args.seq,\n );\n staleKeys = allIndexKeysFor(args.logPrefix, this.#indexes, preImage, input.docId);\n }\n } catch {\n ctxMetrics().counter(\"db.write.index_cleanup_errors_total\", 1, {\n collection: input.collection,\n step: \"pre-image-read\",\n });\n return 0;\n }\n\n // (op:\"I\" has no pre-image → no stale keys.)\n const indexDeletes: Array<Promise<unknown>> = [];\n for (const k of staleKeys) {\n indexDeletes.push(\n this.#storage.delete(k).catch(() => {\n ctxMetrics().counter(\"db.write.index_cleanup_errors_total\", 1, {\n collection: input.collection,\n step: \"delete\",\n });\n }),\n );\n }\n await Promise.all(indexDeletes);\n return staleKeys.length;\n }\n\n /**\n * Read the pre-image content body for a doc by walking the live log\n * backwards from `currentNextSeq` looking for the most-recent I/U\n * entry on this `(collection, docId)`. Returns `undefined` when:\n *\n * - the doc's most-recent op was `D` (tombstone — no live body);\n * - no entry for this doc lives inside the visible log range\n * `[log_seq_start, currentNextSeq)` (a fresh-insert race or the\n * doc has been folded into the snapshot but is no longer\n * referenced).\n *\n * Used ONLY by the index-emission path's stale-key half (Step 5b, on\n * `U` / `D`) to compute which OLD-value keys to DELETE. Bounded by\n * `log_seq_start`: entries below have been folded into the snapshot\n * and may already be swept off the bucket — a snapshot fold is the\n * rebuild command's job (see `./rebuild-index.ts`), not the writer's.\n *\n * **Cost note:** linear walk, O(snapshot lag). For helpdesk-shape\n * collections (100s of docs, <10k log entries) this is fine — the\n * compactor folds the live tail every ~100 entries\n * (`packages/server/src/compactor.ts`). A follow-up ticket caches\n * per-doc index head in `current.json` for O(1) lookup.\n */\n async #readPreImage(\n logPrefix: string,\n collection: string,\n docId: string,\n currentNextSeq: number,\n ): Promise<DocumentData | undefined> {\n // Walk newest-to-oldest so we hit the most-recent op first.\n // `s = -1` is the natural empty-bucket sentinel.\n for (let s = currentNextSeq - 1; s >= 0; s--) {\n const logKey = logObjectKey(logPrefix, s);\n const got = await this.#storage.get(logKey);\n if (got === null) {\n // A hole below the visible range — either we walked past\n // `log_seq_start` (the entry was folded + swept) or a peer\n // is mid-CAS on a write we don't see yet. Bail; the\n // rebuild command (`rebuildIndex`) handles holes by\n // re-projecting from the snapshot.\n continue;\n }\n let entry: LogEntry;\n try {\n entry = decodeJsonBytes<LogEntry>(got.body);\n } catch {\n // Malformed entry shouldn't propagate up the index-emission\n // path — let the outer commit's `#walkLog` (step 2) flag it\n // as the protocol violation. Skip.\n continue;\n }\n if (entry.collection !== collection || entry.doc_id !== docId) {\n continue;\n }\n if (entry.op === \"D\") {\n return undefined;\n } // last op was delete\n if ((entry.op === \"I\" || entry.op === \"U\") && entry.after !== undefined) {\n return entry.after;\n }\n }\n return undefined;\n }\n\n /**\n * Walk `log/<logSeqStart>.json` … `log/<nextSeq - 1>.json` with\n * bounded parallelism via `walkLogRange`. Materialised entries are\n * discarded — the walk's only job is to surface a hole or a\n * malformed body inside the visible range as\n * `BaerlyError{code:\"Internal\"}` / `\"InvalidResponse\"`.\n *\n * Gated on `verifyLogIntegrityOnCommit`; default off in production\n * because the per-doc fold already lives in the read path. See the\n * option's docstring for the rationale and the opt-in convention.\n *\n * `logSeqStart` is the boundary set by the compactor on\n * `current.json.log_seq_start`. Entries below it have been folded\n * into the snapshot and may have been swept off the bucket, so the\n * walk MUST NOT GET-require them.\n */\n async #walkLog(logPrefix: string, logSeqStart: number, nextSeq: number): Promise<void> {\n await walkLogRange(this.#storage, logPrefix, logSeqStart, nextSeq);\n }\n\n /**\n * Bump the `db.r2.put.429_total` counter when `err` looks like an\n * R2 prefix-partition rate-limit. Best-effort: detected via\n * `BaerlyError{code:\"NetworkError\"}` with a `429` token in the\n * message. Called from every PUT call site's catch arm; mutually\n * exclusive in practice with `isPreconditionFailed` (412 ≠ 429).\n */\n #observe429(err: unknown, collection: string): void {\n if (is429(err)) {\n ctxMetrics().counter(\"db.r2.put.429_total\", 1, { collection });\n }\n }\n\n /**\n * Emit the per-logical-write `class_a_ops_per_logical_write`\n * histogram for `commit`. `classAOps` is the per-attempt base plus\n * a charge for prior failed attempts (the retry-budget cost model),\n * computed by the caller.\n */\n #emitWriteMetrics(collection: string, classAOps: number): void {\n ctxMetrics().histogram(\"db.write.class_a_ops_per_logical_write\", classAOps, { collection });\n }\n\n /**\n * Exponential backoff with full jitter. `25 * 2^(attempt-1)` capped\n * at 1500ms; uniform jitter in `[0, base)` keeps colliding peers\n * from re-racing in lockstep. Worst-case total wait across the\n * default 8 attempts is roughly 2.5 s — well under a typical\n * Worker request budget.\n */\n async #backoff(attempt: number): Promise<void> {\n const base = Math.min(this.#initialBackoffMs * 2 ** (attempt - 1), MAX_BACKOFF_MS);\n const sleepMs = base * this.#random();\n if (sleepMs <= 0) {\n return;\n }\n await new Promise<void>((r) => setTimeout(r, sleepMs));\n }\n}\n\n// ---------------------------------------------------------------------\n// Internals\n// ---------------------------------------------------------------------\n\n/**\n * `true` when the underlying storage surfaced a `PreconditionFailed`\n * 412 (or its non-S3 equivalents). Every in-tree {@link Storage} impl\n * surfaces a lost CAS as `BaerlyError{code:\"Conflict\"}`.\n */\nconst isPreconditionFailed = (err: unknown): boolean =>\n err instanceof BaerlyError && err.code === \"Conflict\";\n\n/**\n * `true` when a log-create PUT failed transiently (a `NetworkError`) —\n * the write may or may not have landed (a dropped ack). Safe to retry\n * the SAME seq: own-session adoption closes the double-commit window if\n * it did land. NOT a 412 (that's handled by adoption directly).\n */\nconst isTransientWrite = (err: unknown): boolean =>\n err instanceof BaerlyError && err.code === \"NetworkError\";\n\n/**\n * `true` when the underlying storage surfaced an R2 prefix-partition\n * rate-limit. {@link S3HttpStorage} stamps the upstream HTTP status\n * onto `BaerlyError.cause` as `{ status }`; we discriminate on that\n * structured field rather than regex-matching the message.\n */\nconst is429 = (err: unknown): boolean => {\n if (!(err instanceof BaerlyError) || err.code !== \"NetworkError\") {\n return false;\n }\n const cause = err.cause as { status?: number } | undefined;\n return cause?.status === 429;\n};\n","/**\n * `baerly admin restore` — bulk-import NDJSON into a fresh collection.\n *\n * Reads NDJSON from stdin, reconstructs each row, and calls\n * `Writer.commit({op:\"I\"})` per row into the target bucket.\n * Programmatic callers (today: tests + the export round-trip\n * integration test) can divert the input by passing\n * `{ streams: { stdin } }` to {@link runRestore}. Idempotent on a fresh\n * bucket: re-running on a half-completed restore **refuses** unless\n * `--force` is set (which reseeds a fresh `current.json` above the old\n * tail first).\n *\n * Args:\n * --bucket Required. Target bucket URI.\n * --app Required (or via baerly.config.ts).\n * --tenant Required (or via baerly.config.ts).\n * --collection Required. Target collection name.\n * --force Truncate the target if it exists (reseed above the old tail).\n * --json JSON envelope.\n *\n * stdin: NDJSON, one `{_id, ...}` row per line. Empty lines tolerated.\n * EOF terminates.\n *\n * Cost shape: under single-write commit each `Writer.commit` is 2 Class\n * A PUTs (content + the committing `log/<seq>` create — no per-row\n * `current.json` write). So: 1 PUT current.json (initial seed) + N × 2\n * + 1 PUT current.json (final `tail_hint` stamp) = 2N + 2 Class A ops\n * for N rows.\n *\n * Partial-restore semantics: a mid-stream Network / Internal / parse\n * error leaves the target in a partial state (some rows committed,\n * `current.json` advanced to wherever the last successful commit\n * landed). Re-run with `--force` to truncate, or hand-clean. The\n * malformed-line case (missing `_id`, bad JSON) fails fast on that\n * line; rows committed BEFORE it survive.\n *\n * Exit codes:\n * 0 — every row committed.\n * 1 — InvalidConfig (bad bucket URI, missing args).\n * 2 — Network / storage error mid-stream, or a malformed NDJSON\n * line (raised as a plain `Error`, not `BaerlyError`).\n * 3 — Conflict from a pre-existing target without --force, or from a\n * concurrent writer when --force was used.\n */\n\nimport { createInterface } from \"node:readline\";\nimport { type ArgsDef } from \"citty\";\nimport {\n BaerlyError,\n CURRENT_JSON_SCHEMA_VERSION,\n createCurrentJson,\n type CurrentJson,\n type DocumentData,\n encodeJsonBytes,\n readCurrentJson,\n type Storage,\n} from \"@baerly/protocol\";\nimport { Writer } from \"@baerly/server/_internal/testing\";\nimport { parseBucketUri } from \"../bucket-uri.ts\";\nimport { emitSuccess } from \"../output.ts\";\nimport {\n APP_ARG,\n assertCollectionArg,\n defineBaerlySubcommand,\n JSON_ARG,\n TENANT_ARG,\n} from \"../subcommand.ts\";\n\nconst RESTORE_OWNER = \"baerly-restore\";\n\nconst RESTORE_ARGS = {\n bucket: {\n type: \"string\",\n required: true,\n description: \"Target bucket URI (s3://<bucket>[/<prefix>], file:///<abs>, memory://<bucket>)\",\n valueHint: \"bucket-uri\",\n },\n app: APP_ARG,\n tenant: TENANT_ARG,\n collection: {\n type: \"string\",\n required: true,\n description: \"Target collection name.\",\n valueHint: \"name\",\n },\n force: {\n type: \"boolean\",\n description: \"Truncate the target if it exists (bump fence + reseed current.json).\",\n },\n json: JSON_ARG,\n} as const satisfies ArgsDef;\n\nconst tailFromListedLogKeys = async (\n storage: Storage,\n collectionPrefix: string,\n): Promise<number> => {\n const logPrefix = `${collectionPrefix}/log/`;\n let maxSeq = -1;\n for await (const entry of storage.list(logPrefix)) {\n const tail = entry.key.slice(logPrefix.length);\n const match = /^(\\d+)\\.json$/.exec(tail);\n if (match === null) {\n continue;\n }\n const seq = Number.parseInt(match[1]!, 10);\n if (Number.isFinite(seq) && seq > maxSeq) {\n maxSeq = seq;\n }\n }\n return maxSeq + 1;\n};\n\nconst bundle = defineBaerlySubcommand({\n name: \"admin.restore\",\n meta: {\n description: \"Bulk-import canonical NDJSON into a fresh collection.\",\n },\n args: RESTORE_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 admin restore\");\n const currentJsonKey = `${bucket.keyPrefix}app/${app}/tenant/${tenant}/manifests/${args.collection}/current.json`;\n\n let baseSeq = 0;\n const head = await readCurrentJson(bucket.storage, currentJsonKey);\n if (head !== null && args.force !== true) {\n throw new BaerlyError(\n \"Conflict\",\n `baerly admin restore: ${currentJsonKey} exists; pass --force to truncate`,\n undefined,\n undefined,\n undefined,\n \"Pass --force to truncate the existing collection, or choose an empty target.\",\n false,\n );\n }\n if (head !== null) {\n // --force: reseed `current.json` above the old tail under\n // If-Match. The If-Match guards against a concurrent COMPACTOR\n // (the only steady-state writer of `current.json` under\n // single-write commit) landing between our read and our PUT —\n // that surfaces Conflict (exit 3). It does NOT fence concurrent\n // WRITERS: under single-write commit writers never touch\n // `current.json`, so the dormant `writer_fence` epoch is no\n // longer consulted. `restore` therefore assumes operational\n // exclusivity — do not run it against a collection taking live\n // writes. (We still bump the fence epoch to keep the field\n // monotone, but nothing reads it.)\n //\n // CRITICAL: stale log entries from the old generation still\n // live on disk under `log/<seq>.json` paths. The writer's\n // `If-None-Match: \"*\"` log PUT will 412 if we restart `tail_hint`\n // at 0 and collide with `log/0.json`. We instead advance\n // `tail_hint` and `log_seq_start` past the old data so new\n // commits land at fresh sequence numbers and the old log files\n // become unreferenced orphans (the compactor / GC sweep them on\n // the next maintenance pass). Do this from LISTed log keys, not\n // by folding the old log bodies: `--force` must be able to recover\n // from malformed old entries, and a hole must not make us\n // under-shoot a later old entry.\n const collectionPrefix = currentJsonKey.slice(0, currentJsonKey.lastIndexOf(\"/\"));\n const truncatedNext = await tailFromListedLogKeys(bucket.storage, collectionPrefix);\n baseSeq = truncatedNext;\n const reseeded: CurrentJson = {\n schema_version: CURRENT_JSON_SCHEMA_VERSION,\n snapshot: null,\n tail_hint: truncatedNext,\n log_seq_start: truncatedNext,\n writer_fence: {\n epoch: head.json.writer_fence.epoch + 1,\n owner: RESTORE_OWNER,\n claimed_at: \"\",\n },\n snapshot_bytes: 0,\n snapshot_rows: 0,\n };\n try {\n await bucket.storage.put(currentJsonKey, encodeJsonBytes(reseeded), {\n ifMatch: head.etag,\n contentType: \"application/json\",\n });\n } catch (error) {\n if (error instanceof BaerlyError) {\n throw error;\n }\n throw new BaerlyError(\n \"NetworkError\",\n `baerly admin restore: failed to reseed current.json: ${(error as Error).message}`,\n );\n }\n } else {\n // Fresh target: seed `current.json` with `tail_hint=0`.\n const seed: CurrentJson = {\n schema_version: CURRENT_JSON_SCHEMA_VERSION,\n snapshot: null,\n tail_hint: 0,\n log_seq_start: 0,\n writer_fence: { epoch: 0, owner: RESTORE_OWNER, claimed_at: \"\" },\n snapshot_bytes: 0,\n snapshot_rows: 0,\n };\n await createCurrentJson(bucket.storage, currentJsonKey, seed);\n }\n\n const writer = new Writer({ storage: bucket.storage, currentJsonKey });\n\n const input = ctx.streams?.stdin ?? process.stdin;\n const rl = createInterface({ input, crlfDelay: Infinity });\n let count = 0;\n let lineNo = 0;\n for await (const line of rl) {\n lineNo++;\n if (line.length === 0) {\n continue;\n }\n let parsed: unknown;\n try {\n parsed = JSON.parse(line);\n } catch (error) {\n // Malformed NDJSON mid-stream → exit 2 (the ticket's\n // partial-restore contract: the line that failed wasn't\n // committed, but anything BEFORE it survives). Bare `Error`\n // (not `BaerlyError`) routes through the helper's \"unknown\"\n // arm → exit 2.\n throw new Error(\n `baerly admin restore: line ${lineNo} is not valid JSON: ${(error as Error).message}`,\n { cause: error },\n );\n }\n if (parsed === null || typeof parsed !== \"object\" || Array.isArray(parsed)) {\n throw new Error(`baerly admin restore: line ${lineNo} is not a JSON object`);\n }\n const row = parsed as Record<string, unknown>;\n const id = row[\"_id\"];\n if (typeof id !== \"string\" || id.length === 0) {\n throw new Error(`baerly admin restore: line ${lineNo} missing non-empty string _id`);\n }\n // Pass the full object as the body — `_id` is part of the\n // body in the doc shape, and the writer keys on `docId`\n // separately.\n const body = row as unknown as DocumentData;\n await writer.commit({\n op: \"I\",\n collection: args.collection,\n docId: id,\n body,\n });\n count++;\n }\n // Stamp the final `tail_hint` durably. Under single-write commit the\n // writer never advances the hint (it's compactor-advanced) — but a\n // bulk restore knows exactly how many rows it wrote, so it stamps the\n // true tail (`baseSeq + count`) under If-Match so the restored bucket\n // reads efficiently without a forward-probe. A concurrent compactor\n // between our last commit and this stamp surfaces Conflict (exit 3).\n // CLAMP: `tail_hint` is a monotone lower bound, so never stamp it\n // BELOW what is already durable — take the max of our computed tail,\n // the value already stored, and `log_seq_start`. (Defends against a\n // compactor that advanced the hint between the reseed and here.)\n if (count > 0) {\n const afterLoad = await readCurrentJson(bucket.storage, currentJsonKey);\n if (afterLoad !== null) {\n const clampedTail = Math.max(\n baseSeq + count,\n afterLoad.json.tail_hint,\n afterLoad.json.log_seq_start,\n );\n const stamped: CurrentJson = { ...afterLoad.json, tail_hint: clampedTail };\n await bucket.storage.put(currentJsonKey, encodeJsonBytes(stamped), {\n ifMatch: afterLoad.etag,\n contentType: \"application/json\",\n });\n }\n }\n emitSuccess({\n command: \"admin.restore\",\n status: \"ok\",\n collection: args.collection,\n restored: count,\n });\n return 0;\n },\n});\n\n/** citty `defineCommand` block for `baerly admin restore`. */\nexport const restoreCmd = 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 runRestore = bundle.run;\n"],"mappings":"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"}
|
|
1
|
+
{"version":3,"file":"restore-D0VYWzfP.js","names":["#storage","#currentJsonKey","#maxRetries","#initialBackoffMs","#random","#indexes","#verifyLogIntegrityOnCommit","#singleAttemptCommit","#backoff","#emitWriteMetrics","#provisionCurrentJson","#walkLog","#observe429","#cleanupStaleIndexKeysBestEffort","#readPreImage"],"sources":["../packages/server/src/doc-id.ts","../packages/server/src/key-limit.ts","../packages/server/src/log-conflict-adoption.ts","../packages/server/src/writer.ts","../packages/cli/src/admin/restore.ts"],"sourcesContent":["import { assertPathSegment } from \"./path-segment.ts\";\n\n/**\n * Guard a caller-supplied `_id` before it becomes a written key segment\n * (index keys, log `doc_id`) or filesystem path (`LocalFsStorage`). The\n * `_id` analogue of `assertKeySegment` (`db.ts`). Routes through the\n * single shared {@link assertPathSegment} rule (empty / `\"/\"` /\n * `\".\"`|`\"..\"` / C0-C1 control chars / leading `\"_\"` (ADR-003) / overlong,\n * all as `BaerlyError{code:\"InvalidConfig\"}`).\n */\nexport const assertDocId = (id: string): void => {\n assertPathSegment(id, \"_id\");\n};\n","import { BaerlyError, MAX_KEY_BYTES } from \"@baerly/protocol\";\n\nconst utf8 = new TextEncoder();\n\n/**\n * Reject an assembled object key over the S3/R2 full-key ceiling\n * ({@link MAX_KEY_BYTES}) as `InvalidConfig`. Per-segment caps don't\n * bound the sum, and index values skip `assertPathSegment` entirely, so\n * this post-encoding check at the writer's PUT sites is their only\n * overflow guard. @see docs/spec/storage-compatibility.md\n */\nexport const assertKeyWithinLimit = (key: string): void => {\n const bytes = utf8.encode(key).length;\n if (bytes > MAX_KEY_BYTES) {\n throw new BaerlyError(\n \"InvalidConfig\",\n `object key exceeds ${MAX_KEY_BYTES} bytes (got ${bytes}): ${JSON.stringify(key.slice(0, 80))}…`,\n );\n }\n};\n","/**\n * Self-session log-conflict adoption — the one decision that\n * distinguishes a retry of our own prior commit attempt from a\n * peer racing us at the same `seq`.\n *\n * Background. `Writer.#singleAttemptCommit` creates each log entry\n * with `If-None-Match: \"*\"` — and that create IS the commit. A 412 on\n * `/log/<seq>.json` can mean either\n *\n * (a) a peer genuinely won that seq (a foreign entry is committed\n * there); or\n * (b) our OWN previous attempt landed the committing log create but\n * its ack was lost — we never observed the `200` — and we're now\n * re-driving the same logical commit.\n *\n * This function makes the (a)/(b) call. It is callable, separately\n * testable, and patent-disclosable in isolation from the rest of the\n * commit path.\n *\n * ## Soundness invariant\n *\n * Adoption is sound iff all three hold:\n *\n * 1. **Same session.** `existing.session === self.session`. The\n * session id is a per-commit, in-RAM-only secret minted at\n * `Writer.commit` from `crypto.randomUUID().slice(0,\n * SESSION_ID_LENGTH)`; an adversary with bucket-write access\n * can forge any other field but cannot forge a value they\n * did not observe being PUT.\n * 2. **Matching seq.** `existing.seq === self.expectedSeq`. The\n * seq match is also implied by the key shape (the writer\n * reads `/log/<expectedSeq>.json`), but is re-asserted here\n * so the invariant is visible at the decision site.\n * 3. **Matching write intent.** The occupant's writer-minted log\n * fields match the entry this writer just attempted to create.\n * Same session + same seq alone is not sufficient: a collision,\n * test seam, or out-of-model bucket writer must not be able to\n * make this writer adopt a different logical mutation.\n *\n * When any of (1)/(2)/(3) fails, the caller MUST refuse adoption\n * and treat the occupant as a conflicting committed entry.\n *\n * A fourth precondition — single-input commit — is now structural,\n * not a runtime check: `#singleAttemptCommit` takes one `CommitInput`,\n * so a multi-input commit is unrepresentable. It matters because the\n * single `log/<seq>` create is the all-or-nothing commit point, so\n * per-input adoption decisions could not compose.\n *\n * ## Threat model\n *\n * The adversary may (a) write arbitrary bytes to any key in the\n * bucket, (b) replay any PUT they previously observed on the wire,\n * (c) reorder or drop network packets between the writer and the\n * bucket. The adversary may NOT (d) read the writer's local RAM\n * and therefore cannot learn the per-commit `session` id before\n * observing the writer's own `/log/<seq>.json` PUT. Under these\n * constraints, conditions (1)+(2)+(3) close every attack path in\n * the adversarial-replay property test\n * (`tests/integration/log-conflict-adversarial.test.ts`).\n *\n * **Pinned by:** `tests/integration/log-conflict-forgery.test.ts`\n * exercises the session-id-unguessability claim under a\n * `ForgeryStorage` adversary that plants arbitrary entries at the\n * writer's expected log key. Property verified by default at\n * `numRuns: 1000`; `FC_NUM_RUNS=10000` for the hardening sweep.\n *\n * ## Prior art\n *\n * SlateDB's manifest-pivot writer protocol (rfcs/0001-manifest.md,\n * scenarios 1–4) is the closest published prior art on the broader\n * commit-protocol skeleton. SlateDB's scenario 3 — \"conflicting SST\n * has same `writer_epoch` as me\" — is explicitly labelled an\n * **illegal state that should panic**. The three-clause adoption\n * decision encoded here (same session ∧ matching seq ∧ matching intent)\n * recognises that case as the writer's own prior in-flight attempt\n * and adopts it as success rather than aborting, closing the recovery\n * gap SlateDB leaves to operator intervention.\n *\n * Apache Iceberg and Delta Lake commits surface analogous failures as\n * `CommitFailedException` / commit-conflict retries; neither inspects\n * the conflicting object to determine ownership.\n *\n * See `docs/spec/prior-art.md` for the consolidated IDS-shaped\n * differentiation.\n *\n * @see docs/spec/sync-protocol.md §\"Contention and retries\"\n */\n\nimport type { LogEntry } from \"@baerly/protocol\";\n\n/**\n * Inputs to {@link tryAdoptOwnSessionLogEntry}. All fields are\n * required; the writer constructs this struct at the call site.\n */\nexport interface AdoptionContext {\n /**\n * The entry the writer just attempted to PUT. Carries the\n * writer's session, expected seq, and the rest of the LogEntry\n * shape minted in `Writer.#singleAttemptCommit` step 3.\n */\n readonly self: LogEntry;\n /**\n * The entry currently stored at `/log/<self.seq>.json`, as read\n * back after a 412. The caller is responsible for the GET (the\n * function is pure, no I/O).\n */\n readonly existing: LogEntry;\n}\n\n/**\n * Discriminated outcome of {@link tryAdoptOwnSessionLogEntry}.\n * `adopt: true` carries the existing entry (which by the invariant\n * matches `self` on writer-minted intent fields); the caller\n * substitutes it for `self` so the returned `CommitResult` matches\n * what's actually stored. `adopt: false` carries a machine-readable\n * `reason` so callers and tests can discriminate which clause of the\n * invariant failed.\n */\nexport type AdoptionDecision =\n | { readonly adopt: true; readonly entry: LogEntry }\n | {\n readonly adopt: false;\n readonly reason: \"foreign-session\" | \"wrong-seq\" | \"intent-mismatch\";\n };\n\n/**\n * Decide whether the entry already at `/log/<seq>.json` is the\n * writer's own prior in-flight attempt and may be adopted. Pure\n * function; no I/O. The caller performs the GET (when the log PUT\n * surfaces 412) and passes the read-back body in `ctx.existing`.\n *\n * ## Correctness precondition\n *\n * A fresh `session` id is minted per `commit()` call, seq-stable\n * across that call's retries. Adoption compares the writer-minted\n * intent/body fields as well as session and seq: a dropped-ack retry\n * reuses the same attempted entry and adopts, while a same-session /\n * same-seq occupant carrying a different logical mutation is treated as\n * a conflict and skipped by the caller's forward-probe loop.\n *\n * @see {@link AdoptionDecision} for the return shape.\n * @see The soundness invariant in this module's header docstring.\n */\nexport const tryAdoptOwnSessionLogEntry = (ctx: AdoptionContext): AdoptionDecision => {\n // Clause (1) — same session.\n if (ctx.existing.session !== ctx.self.session) {\n return { adopt: false, reason: \"foreign-session\" };\n }\n // Clause (2) — matching seq. The seq is also implied by the\n // key the caller read from, but re-asserted here for\n // patent-disclosure clarity.\n if (ctx.existing.seq !== ctx.self.seq) {\n return { adopt: false, reason: \"wrong-seq\" };\n }\n // Clause (3) — matching write intent: full-entry equality, including\n // `commit_ts`. A legitimate lost-ack self-retry passes this ONLY under\n // two premises:\n // P1 (single mint): `commit_ts`/`lsn`/`session` are minted once per\n // `#singleAttemptCommit` (one `Date.now()`) and the inner\n // transient-retry loop re-PUTs the IDENTICAL `entry`, so a real\n // read-back is byte-identical to `self`, `commit_ts` included.\n // P2 (order-stable round-trip): stored bytes are\n // `encodeJsonBytes` (`JSON.stringify`) and read back via\n // `JSON.parse`; `JSON.stringify(JSON.parse(...))` preserves key\n // order, so the two stringifications match.\n // If either breaks (re-mint on retry, or a canonical/sorting encoder /\n // normalizing read-back), a legit self-retry would falsely mismatch\n // here and DUPLICATE-write. P2 is pinned by `bytes.test.ts`.\n if (JSON.stringify(ctx.existing) !== JSON.stringify(ctx.self)) {\n return { adopt: false, reason: \"intent-mismatch\" };\n }\n return { adopt: true, entry: ctx.existing };\n};\n","/**\n * `Writer` — stateless multi-instance write engine (single-write commit).\n *\n * Each {@link Writer.commit} reads `current.json` FRESH (for\n * `log_seq_start` / `tail_hint` as a probe FLOOR — a lower bound, NOT a\n * CAS precondition), PUTs the content body, then **creates `log/<seq>`\n * via `If-None-Match: \"*\"`. That create IS the commit / linearization\n * point.** The writer writes NOTHING to `current.json` on the commit\n * path; `tail_hint` advances outside ordinary commits via compaction\n * folds, write-tick refreshes, and explicit operator/import paths. The\n * commit model and its invariants are recorded in ADR-004\n * (`docs/adr/004-single-write-commit.md`). The\n * optional integrity walk is gated by\n * {@link WriterOptions.verifyLogIntegrityOnCommit} (default off).\n *\n * No per-write cache: every commit re-reads + re-probes, so N stateless\n * instances contend at one place — the `If-None-Match` create of\n * `log/<seq>`. The loser gets a 412 and re-probes forward to the next\n * empty slot. A 412 from the writer's OWN session at the same seq is its\n * own lost-ack / crashed-but-durable commit → adopted (not retried), so\n * the write lands at EXACTLY `seq`, never duplicated.\n *\n * **Crash safety.** Order is content + additive index `newKeys` →\n * `log/<seq>` create → stale index-key DELETEs. A crash before the\n * create leaves an unreferenced content body + orphan additive index\n * keys (no log entry references them), not an orphan log entry with\n * missing content — the compactor sweeps the content, and a stray\n * additive key only ever yields a false-POSITIVE candidate that\n * `matchesWire` (read path) drops. Emitting `newKeys` before the commit\n * means a committed row is ALWAYS index-findable; the stale-key DELETE\n * stays after the commit so a crash can never de-index a committed\n * doc. See `index-emit-order.test.ts` and ADR-004 Q4.\n *\n * **`LogEntry` shape.** Emitted entries follow the contract in\n * `packages/protocol/src/log.ts` (see {@link LogEntry}) and\n * `docs/spec/log-entry-shape.md`. The on-bucket key is\n * `log/<seq>.json` (the integer `seq` is the load-bearing\n * identifier; the `lsn` string is schema-only).\n *\n * @see docs/spec/sync-protocol.md for the protocol invariants this\n * loop preserves.\n * @see docs/spec/log-entry-shape.md for the per-field contract.\n */\n\nimport {\n CURRENT_JSON_SCHEMA_VERSION,\n type CurrentJson,\n type CurrentJsonRead,\n type DocumentData,\n type LogEntry,\n type MetricsRecorder,\n createCurrentJson,\n decodeJsonBytes,\n encodeJsonBytes,\n logObjectKey,\n logSeqStartOf,\n BaerlyError,\n noopMetricsRecorder,\n type Storage,\n LOG_FORWARD_PROBE_CAP,\n MAINTENANCE_PROFILE_CF_FREE,\n MAINTENANCE_TAIL_HINT_REFRESH_WRITES,\n S3_REQUEST_MAX_RETRIES,\n SESSION_ID_LENGTH,\n countKey,\n readCurrentJson,\n timestamp,\n uuid,\n versionFromContent,\n} from \"@baerly/protocol\";\nimport { assertDocId } from \"./doc-id.ts\";\nimport { allIndexKeysFor, type IndexDefinition, validateIndexDefinition } from \"./indexes.ts\";\nimport { assertKeyWithinLimit } from \"./key-limit.ts\";\nimport { readLogEntry, walkLogRange } from \"./log-walk.ts\";\nimport { findLogTail } from \"./log-tail.ts\";\nimport { tryAdoptOwnSessionLogEntry } from \"./log-conflict-adoption.ts\";\nimport {\n dispatchInlineAwaited,\n runBoundedMaintenance,\n shouldFireMaintenance,\n} from \"./maintenance.ts\";\nimport { getCurrentContext } from \"./observability/context.ts\";\n\nconst CAS_CONFLICT_RESOLUTION = \"Re-read and retry.\";\n\nconst ctxMetrics = (): MetricsRecorder => getCurrentContext()?.recorder ?? noopMetricsRecorder;\n\n/**\n * Tunables for {@link Writer}. All optional; defaults match the\n * legacy retry budget so the new loop is a drop-in replacement.\n */\nexport interface WriterOptions {\n /**\n * Max retryable `Conflict` attempts before throwing `Conflict`.\n * Foreign log-create 412s are resolved inside a single attempt by\n * occupant read-back plus bounded forward re-probe; this budget is\n * retained for future retryable conflicts and tests.\n */\n readonly maxRetries?: number;\n\n /** Initial backoff in ms; doubles per attempt, capped at 1500ms. Default 25. */\n readonly initialBackoffMs?: number;\n\n /**\n * Pure function returning a number in [0, 1). Used for jitter; tests\n * inject a deterministic generator. Defaults to `Math.random`.\n */\n readonly random?: () => number;\n\n /**\n * Optional. Indexes declared for the collection this writer\n * commits to. Each commit emits one zero-byte PUT per declared\n * index (when the indexed field is set on the doc) — the additive\n * `newKeys` go down BEFORE the committing `log/<seq>` create, so a\n * committed row is always index-findable. On U/D, the writer reads\n * the pre-image content body from the log (one back-walk per\n * indexed collection, NOT per index) to compute the stale-key set;\n * stale keys are DELETE'd AFTER the commit, computed from the\n * resolved committing seq's pre-image.\n *\n * Validated at construction via {@link validateIndexDefinition} —\n * an invalid def throws `BaerlyError{code:\"SchemaError\"}`\n * synchronously, before the first commit. Empty / undefined is\n * a no-op (writer behaves identically to the no-index path — no\n * extra GET, no extra PUTs).\n *\n * Note: `Writer` is per-collection (the `currentJsonKey`\n * is per-collection), so this array applies to one collection\n * only — adapters that serve multiple collections instantiate\n * one writer per collection.\n *\n * Emits one new metric when at least one index is declared:\n * - `db.write.index_ops_per_logical_write` (histogram,\n * labelled by `collection`) — `K (PUT) + L (DELETE)` per\n * successful commit.\n */\n readonly indexes?: ReadonlyArray<IndexDefinition>;\n\n /**\n * When `true`, every commit walks the live log range\n * `[log_seq_start, tail_hint)` before minting a new entry, surfacing\n * a missing or malformed entry as `BaerlyError{code:\"Internal\"}`\n * (or `\"InvalidResponse\"` for parse failures). The walk is purely\n * observational — the per-doc fold lives in the read path\n * (`./query.ts`) and any hole inside the visible range would also\n * fire on the next read.\n *\n * Production callers default this OFF: under contention the walk\n * issues `O(tail)` Class-B GETs per CAS attempt and the retry\n * budget multiplies that by {@link S3_REQUEST_MAX_RETRIES}. Tests\n * that intentionally puncture bucket state to exercise the\n * invariant trigger opt in by passing `true`.\n *\n * Default `false`.\n */\n readonly verifyLogIntegrityOnCommit?: boolean;\n}\n\n/**\n * Single-doc mutation request. One `commit()` ↔ one {@link LogEntry}.\n */\nexport interface CommitInput {\n /** The mutation op. Maps directly to {@link LogEntry.op}. */\n readonly op: \"I\" | \"U\" | \"D\";\n\n /** The collection (table) name. Becomes {@link LogEntry.collection}. */\n readonly collection: string;\n\n /** The document primary key. Becomes {@link LogEntry.doc_id}. */\n readonly docId: string;\n\n /**\n * For `I` / `U`: the post-image. Becomes {@link LogEntry.after}. Must\n * be `undefined` for `op: \"D\"`.\n */\n readonly body?: DocumentData;\n\n /** Optional ISO-8601 origin marker; becomes {@link LogEntry.origin}. */\n readonly origin?: string;\n}\n\n/** Return shape of {@link Writer.commit}. */\nexport interface CommitResult {\n /** The committed `LogEntry`. Caller can ack on `entry.lsn`. */\n readonly entry: LogEntry;\n\n /**\n * ETag of `current.json` as read at the start of the commit. The\n * commit path no longer writes `current.json` (the `log/<seq>`\n * create IS the commit), so this is the manifest's pre-commit ETag,\n * not a post-write one.\n */\n readonly currentEtag: string;\n\n /** How many commit attempts it took (1 = first try won). */\n readonly attempts: number;\n}\n\nconst DEFAULT_INITIAL_BACKOFF_MS = 25;\nconst MAX_BACKOFF_MS = 1500;\nconst APPLICATION_JSON = \"application/json\";\n\n/**\n * Empty body for index entries. Each index entry is a fact (\"doc\n * `<docId>` has `<field> = <value>`\"), not data — readers list the\n * prefix, extract the doc id, then GET the content body separately.\n * Pre-allocated module-level constant so every index PUT shares one\n * zero-length buffer.\n */\nconst EMPTY_BODY = new Uint8Array(0);\n\n/**\n * Successful outcome of one full {@link Writer.#singleAttemptCommit}\n * attempt. A retryable log-create 412 that resolved to a foreign-session\n * occupant beyond the forward-probe budget throws\n * `BaerlyError{code:\"Conflict\"}`; the caller catches via\n * {@link isPreconditionFailed} and decides whether to retry. Non-retryable\n * failures (protocol-invariant violations, network errors) propagate.\n */\ninterface SingleAttemptSuccess {\n readonly entries: readonly LogEntry[];\n readonly currentEtag: string;\n readonly classAOps: number;\n}\n\n/**\n * Stateless write engine for the multi-instance core.\n *\n * Construction is cheap and performs zero I/O — adapters build a\n * fresh `Writer` per request and discard it. All real work\n * happens in {@link commit}.\n *\n * @example\n * ```ts\n * import { Writer } from \"@gusto/baerly-storage\";\n * import { MemoryStorage } from \"@gusto/baerly-storage\";\n *\n * const writer = new Writer({\n * storage: new MemoryStorage(),\n * currentJsonKey: \"app/tickets/tenant/acme/manifests/tickets/current.json\",\n * });\n *\n * const result = await writer.commit({\n * op: \"I\",\n * collection: \"tickets\",\n * docId: \"doc-1\",\n * body: { _id: \"doc-1\", title: \"hello\" },\n * });\n * console.log(result.entry.seq, result.attempts);\n * ```\n */\nexport class Writer {\n readonly #storage: Storage;\n readonly #currentJsonKey: string;\n readonly #maxRetries: number;\n readonly #initialBackoffMs: number;\n readonly #random: () => number;\n readonly #indexes: ReadonlyArray<IndexDefinition>;\n readonly #verifyLogIntegrityOnCommit: boolean;\n\n constructor(opts: {\n storage: Storage;\n /**\n * Full bucket-relative key of the CAS pointer, e.g.\n * `app/tickets/tenant/acme/manifests/tickets/current.json`. The\n * collection-prefix half lives at\n * `currentJsonKey.slice(0, currentJsonKey.lastIndexOf(\"/\"))` — the\n * log and content keys are derived from it.\n */\n currentJsonKey: string;\n options?: WriterOptions;\n }) {\n this.#storage = opts.storage;\n this.#currentJsonKey = opts.currentJsonKey;\n this.#maxRetries = opts.options?.maxRetries ?? S3_REQUEST_MAX_RETRIES;\n this.#initialBackoffMs = opts.options?.initialBackoffMs ?? DEFAULT_INITIAL_BACKOFF_MS;\n this.#random = opts.options?.random ?? Math.random;\n const indexes = opts.options?.indexes ?? [];\n for (const def of indexes) {\n validateIndexDefinition(def);\n }\n this.#indexes = indexes;\n this.#verifyLogIntegrityOnCommit = opts.options?.verifyLogIntegrityOnCommit ?? false;\n }\n\n /**\n * Atomically commit one mutation. Reads `current.json` fresh (as a\n * probe FLOOR, not a CAS precondition), PUTs the content body and any\n * additive index `newKeys`, then creates `log/<seq>` via\n * `If-None-Match: \"*\"` — that create IS the commit (single-write\n * commit; no `current.json` CAS follows it). Stale index keys are\n * DELETE'd after the commit.\n *\n * The hot-path cost under no contention on an unindexed collection is\n * 1 GET + 2 PUTs (content + the committing `log/<seq>` create); each\n * declared index that projects a key on this write adds one PUT\n * (new key, before the commit) and, on U/D, up to one DELETE (stale\n * key, after the commit). An in-flight peer write costs one extra GET\n * + the backoff sleep per retry.\n *\n * Idempotency: PUT content uses `If-None-Match: \"*\"`, so a retry of\n * the same logical write produces the same content key and the\n * second PUT no-ops. The `log/<seq>` create also uses\n * `If-None-Match: \"*\"`, so two writers racing the same tail cause\n * exactly one create to win; the loser reads back the occupant,\n * adopts its own lost-ack write or re-probes forward to the next\n * empty slot.\n *\n * @throws BaerlyError code=\"Conflict\" when a retryable conflict\n * escapes the single-attempt helper and exhausts the retry budget\n * (presently unreachable on the log-create 412 path).\n * @throws BaerlyError code=\"Internal\" when a log entry expected in\n * `[0, tail_hint)` is missing — a protocol-invariant violation\n * (compactor bug or stale `current.json`).\n * @throws BaerlyError code=\"InvalidResponse\" when a log-entry body\n * isn't valid JSON.\n *\n * **Implicit provisioning.** When `current.json` does not exist at\n * `currentJsonKey` (fresh bucket, fresh collection), the writer\n * auto-creates it with a zero-state manifest before the commit\n * lands. The cost is one extra Class A PUT on the very first\n * commit per collection; steady-state cost is unchanged. A peer\n * racing the same first-write loses cleanly on the create CAS\n * and re-reads to pick up the winner's manifest.\n */\n async commit(input: CommitInput): Promise<CommitResult> {\n // Validate the doc id BEFORE any I/O so every commit caller — the\n // public write path AND a direct caller like `baerly admin restore`\n // — is covered (defense in depth, mirroring the db-layer guard).\n // Rejects empty / `\"/\"` / `\".\"`|`\"..\"` / control / leading `\"_\"` /\n // overlong `docId` as `BaerlyError{code:\"InvalidConfig\"}`, so a\n // traversal-shaped `_id` can never become a written key segment.\n assertDocId(input.docId);\n const session = uuid().slice(0, SESSION_ID_LENGTH);\n const logPrefix = this.#currentJsonKey.slice(0, this.#currentJsonKey.lastIndexOf(\"/\"));\n\n // NOTE: with the post-commit fence-verify removed, no `Conflict`\n // currently escapes `#singleAttemptCommit` — a log-create 412 is\n // always resolved internally (own-session adoption or a bounded\n // forward-probe to the next empty slot; only an exhausted probe cap\n // throws, as `Internal`, not `Conflict`). So the retry-catch arm and\n // the budget-exhausted `Conflict` throw below are presently\n // unreachable. They are retained deliberately: they cost nothing on\n // the happy path and re-arm automatically if a future change ever\n // re-introduces a retryable `Conflict` out of the helper.\n for (let attempt = 1; attempt <= this.#maxRetries; attempt++) {\n let success: SingleAttemptSuccess;\n try {\n success = await this.#singleAttemptCommit(input, session, logPrefix, \"Writer\");\n } catch (error) {\n // Only a retryable `Conflict` (see NOTE above — currently none)\n // backs off and retries. Anything else propagates.\n if (!isPreconditionFailed(error)) {\n throw error;\n }\n await this.#backoff(attempt);\n continue;\n }\n // `success.classAOps` is the per-attempt base; add `(attempt\n // - 1)` to bill prior failed attempts as one PUT each (the\n // simple-and-test-locked cost model — not a precise replay\n // of every PUT in every dropped attempt).\n this.#emitWriteMetrics(input.collection, success.classAOps + (attempt - 1));\n return {\n entry: success.entries[0]!,\n currentEtag: success.currentEtag,\n attempts: attempt,\n };\n }\n\n // Retry budget exhausted.\n throw new BaerlyError(\n \"Conflict\",\n `Writer: CAS conflict on ${this.#currentJsonKey} after ${this.#maxRetries} attempts`,\n undefined,\n undefined,\n undefined,\n CAS_CONFLICT_RESOLUTION,\n true,\n );\n }\n\n /**\n * One full commit attempt — the body of {@link commit}. Reads\n * `current.json`, PUTs content + additive index `newKeys` in parallel,\n * then forward-probes the tail and creates `log/<seq>` once via\n * `If-None-Match: \"*\"` — the numbered log create IS the commit\n * (single-write commit; no `current.json` CAS follows it). Stale index\n * keys are DELETE'd after the commit. Returns the success payload.\n *\n * Commits exactly one {@link CommitInput} — the numbered log create is\n * the single linearization point per call.\n *\n * A log-create 412 is disambiguated by session read-back: own session\n * / own seq ⇒ our crashed-or-lost-ack commit is already durable ⇒\n * adopt; foreign session ⇒ re-probe forward and retry at the next\n * empty slot. Thrown `BaerlyError`s (Internal, InvalidResponse,\n * NetworkError) propagate.\n *\n * Crash safety invariant: content + additive index `newKeys` PUTs are\n * awaited before the log create. A crash before the create leaves\n * orphan content + additive index keys (no log entry references them)\n * — the compactor sweeps the content, and a stray additive key only\n * yields a false-positive candidate that `matchesWire` drops. A crash\n * AFTER the create is a durable, committed write at `seq` whose index\n * `newKeys` are already present (so it's index-findable); the only\n * residual is a possibly-undeleted stale OLD-value key, dropped by\n * `matchesWire` and cleaned by a later write / `rebuild-index`. The\n * inverse — committed log entry with missing content, or a de-indexed\n * committed doc — is never produced.\n */\n async #singleAttemptCommit(\n input: CommitInput,\n session: string,\n logPrefix: string,\n errorPrefix: string,\n ): Promise<SingleAttemptSuccess> {\n // ── Step 1. Read current.json (fresh; carries the ETag). ────────\n // On a fresh bucket / fresh collection the manifest doesn't exist\n // yet. Auto-create it with a zero-state initial so `db.collection(x)\n // .insert(...)` works zero-shot. A peer racing the same create\n // loses cleanly on `If-None-Match: \"*\"`; we re-read to pick up\n // the winner's manifest. Cost: one extra Class A PUT on the very\n // first commit per collection, zero overhead thereafter.\n const read =\n (await readCurrentJson(this.#storage, this.#currentJsonKey)) ??\n (await this.#provisionCurrentJson());\n const current = read.json;\n const baseEtag = read.etag;\n\n // ── Step 2. Optional integrity walk (`verifyLogIntegrityOnCommit`,\n // default off). Surfaces missing / malformed entries inside\n // `[log_seq_start, tail_hint)` as `Internal` / `InvalidResponse`;\n // entries below `log_seq_start` are folded into the snapshot\n // by `compact()` and possibly swept by `runGc()`, so the walk is\n // bounded to the live tail. The read path catches the same\n // conditions on the next consult — production callers leave the\n // walk off to avoid `O(tail)` Class-B GETs per CAS attempt.\n if (this.#verifyLogIntegrityOnCommit) {\n await this.#walkLog(logPrefix, logSeqStartOf(current), current.tail_hint);\n }\n\n // ── Step 3. Find the true tail (Class B forward-probe), then mint. ─\n // `tail_hint` is a non-authoritative lower bound (the writer no\n // longer advances it — only the compactor stamps it durably). The\n // forward-probe discovers the first empty seq >= the floor: the slot\n // this commit will create. Floor at `max(log_seq_start, tail_hint)`\n // so a compactor that advanced `log_seq_start` past a stale\n // `tail_hint` doesn't make us re-walk folded-but-unswept entries.\n // Bind to a local (oxlint `no-await-expression-member`).\n const probeFloor = Math.max(logSeqStartOf(current), current.tail_hint);\n // `findLogTail`'s density precondition holds: the floor sits in the\n // dense prefix because tail_hint advancers probe or derive known tails\n // from committed entries, while ordinary writer commits never stamp\n // `tail_hint`, so nothing advances the floor past a hole.\n const preCommitTail = await findLogTail(this.#storage, logPrefix, probeFloor);\n let seq = preCommitTail;\n\n // All entries share `session` (one session per logical commit) and\n // a single commit instant: `lsn`'s timestamp and `commit_ts` are\n // derived from ONE clock read so they can't drift apart under skew\n // (a reader validates `commit_ts` against `LAG_WINDOW_MILLIS`, and\n // two independent reads could straddle that band). The LSN's\n // `countKey(seq)` suffix MUST track the probed seq — it's compared on\n // adoption, so a stale suffix would misfire the disambiguation.\n const commitNowMs = Date.now();\n const commitTs = new Date(commitNowMs).toISOString();\n const lsnTimestamp = timestamp(commitNowMs);\n const mintEntry = (atSeq: number): LogEntry => ({\n lsn: `${lsnTimestamp}_${session}_${countKey(atSeq)}`,\n commit_ts: commitTs,\n op: input.op,\n collection: input.collection,\n doc_id: input.docId,\n session,\n seq: atSeq,\n ...(input.op !== \"D\" && input.body !== undefined ? { after: input.body } : {}),\n ...(input.origin !== undefined ? { origin: input.origin } : {}),\n });\n let entry = mintEntry(seq);\n\n // ── Step 4. PUT content bodies + additive index `newKeys` (BEFORE\n // the commit). ──────────────────────────────────────────────────\n // Content PUT: `ifNoneMatch: \"*\"` makes a same-hash re-write a\n // no-op (412 swallowed). Crash-recovery and same-body replay\n // both rely on this idempotency property. Content is content-\n // addressed, so writing it before the commit is crash-safe: a\n // crash here leaves an unreferenced body the compactor sweeps,\n // never an orphan log entry with missing content.\n //\n // Additive index `newKeys` (the markers for the doc's NEW value)\n // ALSO go down here, before the committing create. `newKeys`\n // depend only on `body` + `docId` (NOT on `seq`), so they're\n // stable across the forward re-probe — emit them once. Emitting\n // BEFORE the commit guarantees a committed row is ALWAYS index-\n // findable (no false-negative). A crash after a `newKey` PUT but\n // before the commit leaves an orphan additive key for an\n // UNcommitted write — benign: the index read includes the\n // candidate docId, the fold finds no committed (or the prior)\n // value, and `matchesWire` (query.ts) drops the false-positive.\n // The stale-key DELETEs (de-indexing the OLD value) stay AFTER the\n // commit (Step 5b), so a crash can never de-index a committed doc.\n // See ADR-004 Q4 + `index-emit-order.test.ts`.\n let contentPutCount = 0;\n let newKeysClassA = 0;\n const parallelPuts: Array<Promise<unknown>> = [];\n if (input.op !== \"D\" && input.body !== undefined) {\n contentPutCount++;\n const bytes = encodeJsonBytes(input.body);\n const version = await versionFromContent(bytes);\n const contentKey = `${logPrefix}/content/${version}.json`;\n assertKeyWithinLimit(contentKey);\n parallelPuts.push(\n this.#storage\n .put(contentKey, bytes, { ifNoneMatch: \"*\", contentType: APPLICATION_JSON })\n .catch((error: unknown) => {\n this.#observe429(error, input.collection);\n if (isPreconditionFailed(error)) {\n return;\n }\n throw error;\n }),\n );\n }\n // Additive index keys for the NEW value — emitted before the\n // commit on I/U (a D has no new value). `op:\"D\"` and a missing\n // body project to no keys. Empty `#indexes` short-circuits.\n if (this.#indexes.length > 0 && input.op !== \"D\") {\n const newKeys = allIndexKeysFor(logPrefix, this.#indexes, input.body, input.docId);\n for (const k of newKeys) {\n assertKeyWithinLimit(k);\n newKeysClassA++;\n parallelPuts.push(\n this.#storage\n .put(k, EMPTY_BODY, { ifNoneMatch: \"*\", contentType: APPLICATION_JSON })\n .catch((error: unknown) => {\n this.#observe429(error, input.collection);\n if (isPreconditionFailed(error)) {\n return;\n }\n throw error;\n }),\n );\n }\n }\n await Promise.all(parallelPuts);\n\n // ── Step 5. Create the commit: PUT log/<seq> via If-None-Match. ─\n // The numbered log create IS the commit (single-write commit). No\n // `current.json` CAS follows it — the create is the linearization\n // point (exactly-one-winner, CI-gated across all backends).\n //\n // 200 ⇒ committed at `seq`. 412 ⇒ disambiguate by session read-back:\n // - own session / own seq ⇒ our crashed-or-lost-ack commit is\n // already durable at `seq` ⇒ adopt the resolved `seq` and fall\n // through to the SAME index emit (Step 5b). The adopted commit\n // is EXACTLY the attempt that may have died after creating\n // `log/<seq>` but before emitting its index, so re-running the\n // (idempotent) emit completes it.\n // - foreign session / wrong seq ⇒ re-probe forward and retry at the\n // new first-empty slot (bounded by LOG_FORWARD_PROBE_CAP).\n // A transient NetworkError (e.g. a dropped ack on a create that may\n // already have landed) retries the SAME `seq`: the retry either\n // re-creates (write never landed) or hits the durable write → 412 →\n // own-session adoption. Either way the write lands at EXACTLY `seq`,\n // never duplicated.\n let committedEntry: LogEntry = entry;\n let probes = 0;\n let transientRetries = 0;\n for (;;) {\n const logEntryKey = logObjectKey(logPrefix, seq);\n assertKeyWithinLimit(logEntryKey);\n let conflicted = false;\n try {\n await this.#storage.put(logEntryKey, encodeJsonBytes(entry), {\n ifNoneMatch: \"*\",\n contentType: APPLICATION_JSON,\n });\n } catch (error) {\n this.#observe429(error, entry.collection);\n if (isPreconditionFailed(error)) {\n ctxMetrics().counter(\"db.r2.put.412_total\", 1, {\n collection: entry.collection,\n step: \"log-put\",\n });\n conflicted = true;\n } else if (isTransientWrite(error) && transientRetries < this.#maxRetries) {\n // Possible lost-ack — retry the SAME seq (idempotent: adoption\n // closes the double-commit window). Bounded backoff (full jitter,\n // same as the outer loop) so a backend in transient distress\n // isn't hammered; a persistent NetworkError still surfaces.\n transientRetries++;\n await this.#backoff(transientRetries);\n continue;\n } else {\n throw error;\n }\n }\n if (!conflicted) {\n committedEntry = entry;\n break;\n }\n // 412 — read back the occupant and decide.\n const existing = await readLogEntry(this.#storage, logEntryKey);\n const decision = tryAdoptOwnSessionLogEntry({\n self: entry,\n existing,\n });\n if (decision.adopt) {\n // Own crashed/lost-ack commit already durable at `seq`. Adopt it\n // (byte-identical to the attempted `entry`, INCLUDING `commit_ts`\n // — adoption compares the full entry) — the logical write lands at\n // EXACTLY `seq`, never duplicated. Fall through to Step 5b: the\n // adopted attempt may have died after the create but before the\n // index emit, so the (idempotent) emit must still run.\n committedEntry = decision.entry;\n break;\n }\n // Foreign session (or wrong seq) — re-probe forward from seq+1 and\n // retry at the new first-empty slot, re-minting seq + LSN.\n if (++probes > LOG_FORWARD_PROBE_CAP) {\n throw new BaerlyError(\n \"Internal\",\n `${errorPrefix}: log-tail forward-probe exceeded ${LOG_FORWARD_PROBE_CAP} on ${this.#currentJsonKey}`,\n );\n }\n seq = await findLogTail(this.#storage, logPrefix, seq + 1);\n entry = mintEntry(seq);\n }\n const committedEntries: readonly LogEntry[] = [committedEntry];\n\n // ── Step 5b. DELETE stale secondary-index keys (AFTER the commit). ─\n // The additive `newKeys` already went down in Step 4 (before the\n // commit), so a committed row is always index-findable. This block\n // handles only the OTHER half: deleting the OLD value's now-obsolete\n // markers. Keeping the stale-key DELETE AFTER the commit is the\n // load-bearing polarity (ADR-004 Q4): a crash here leaves the OLD\n // value's marker lingering — benign, the index read includes the\n // candidate, the fold sees the doc's NEW committed value, and\n // `matchesWire` (query.ts) drops the false-positive; the lingering\n // key is cleaned by a later same-doc write or operator\n // `rebuild-index`. The inverse — de-indexing a committed doc with no\n // log entry to drive repair — can NEVER happen, since the DELETE is\n // strictly after the commit.\n //\n // BOTH the fresh-win and the own-session-adoption break above reach\n // here with the resolved committing `seq`. Adoption correctness: an\n // adopted lost-ack commit is EXACTLY the attempt that may have died\n // after the create but before this DELETE, so it MUST run it too (do\n // not skip it). Idempotent under re-run: `Storage.delete` is\n // contractually idempotent, and the Step-4 `newKeys` PUT is\n // `ifNoneMatch: \"*\"` (412 swallowed).\n //\n // Empty `#indexes` short-circuits the whole block (including the\n // pre-image GET), preserving zero behaviour change for collections\n // without declared indexes. An `op:\"I\"` has no pre-image and no\n // stale keys, so it never reads.\n //\n // The pre-image is read at the RESOLVED committing `seq` (Step 5\n // may have advanced `seq` past a foreign winner): `#readPreImage`\n // back-walks from `seq - 1`, so it skips the just-committed entry\n // and finds the prior same-doc image.\n //\n // Filter-aware projection (T4): `allIndexKeysFor` short-circuits on\n // `def.predicate` miss. The diff `oldKeys \\ newKeys` covers all four\n // U-quadrants (match→match deletes only the changed keys; match→miss\n // DELETEs all; miss→match deletes nothing; miss→miss no-ops), each\n // pinned by a named test in `writer.test.ts` (\"Writer — filtered\n // index\").\n const staleKeysClassA = await this.#cleanupStaleIndexKeysBestEffort({\n input,\n logPrefix,\n seq,\n });\n // The per-logical-write index-op histogram counts BOTH halves: the\n // `newKeys` PUTs (Step 4) and the `staleKeys` DELETEs (Step 5b).\n const indexClassA = newKeysClassA + staleKeysClassA;\n if (this.#indexes.length > 0 && indexClassA > 0) {\n ctxMetrics().histogram(\"db.write.index_ops_per_logical_write\", indexClassA, {\n collection: input.collection,\n });\n }\n\n // ── Step 6. (removed). No current.json write on the commit path. ─\n // The numbered log create above IS the commit. `tail_hint` is\n // refreshed durably only by the compactor; the writer never advances\n // it. The maintenance trigger below reads a DERIVED tail-byte\n // estimate (`estimateTailBytes`), so there is no stored byte counter.\n\n // ── Step 6b. Write-tick maintenance dispatch. ───────────────────\n // Single funnel site: write-tick maintenance dispatch. Reached by\n // `commit()` exactly once per logical commit, after the committing\n // log create has landed.\n //\n // Config rides the per-request observability context\n // (`getCurrentContext()?.maintenance`), set by the adapter — NOT the\n // Writer constructor / `Db.create`. Absent ⇒ inline dispatch +\n // CF-free-safe caps, so a bare `Db.create(...).collection(...)\n // .insert(...)` maintains inline by default once enough writes\n // accrue.\n //\n // `prevSeq` is the pre-commit tail (`preCommitTail`); the slot we won\n // is `seq` (== prevSeq unless a forward re-probe moved it past a\n // foreign winner), so the boundary check spans `(prevSeq,\n // observedTail]`. `observedTail = seq+1` is a fresh in-memory lower\n // bound on the true tail: winning `log/<seq>` means `[tail_hint, seq)`\n // were observed occupied, so `seq+1 ≤ true tail`. We pass `current`\n // (the Step-1 read) for the snapshot fields — there is no `next`.\n const prevSeq = preCommitTail;\n const observedTail = seq + 1;\n const maint = getCurrentContext()?.maintenance;\n // Same absent-context default as runBoundedMaintenance's\n // `options?.profile ?? MAINTENANCE_PROFILE_CF_FREE` — keep the two in\n // step (this gate reads only gcInterval; the runner resolves the whole\n // profile) so the pre-fire cadence can't diverge from the fold's.\n const gcInterval =\n maint?.options?.profile?.gcInterval ?? MAINTENANCE_PROFILE_CF_FREE.gcInterval;\n const maintenanceDue =\n maint?.disabled === true\n ? observedTail - current.tail_hint >= MAINTENANCE_TAIL_HINT_REFRESH_WRITES\n : shouldFireMaintenance(current, prevSeq, gcInterval, observedTail);\n if (maintenanceDue) {\n const dispatch = maint?.dispatch ?? dispatchInlineAwaited;\n // `await dispatch(...)`: `dispatchInlineAwaited` returns the\n // task's promise (awaited inline — deterministic for tests +\n // correct for serverful Node). A `ctx.waitUntil`-style dispatch\n // returns void (fire-and-forget off the ack); `await void` is a\n // no-op. The `.then(() => {}, () => {})` is belt-and-suspenders:\n // `runBoundedMaintenance` already swallows internally, but this\n // guarantees a dispatched task can NEVER reject the commit even\n // if a future change makes it throw.\n await dispatch(() =>\n runBoundedMaintenance(\n {\n storage: this.#storage,\n currentJsonKey: this.#currentJsonKey,\n prevSeq,\n // Thread the in-memory observed tail so the runner's Gate-1\n // ratio + GC cadence key off the true tail without an\n // O(gap) re-probe (the stored `tail_hint` is only a lower\n // bound under single-write commit).\n observedTail,\n // `disabled` disables fold/GC phases inside the runner but\n // still permits the bounded tail_hint refresh that prevents a\n // maintenance-off collection from drifting past the probe cap.\n ...(maint?.disabled === true && { disabled: true }),\n ...(maint?.maxFoldBytes !== undefined && { maxFoldBytes: maint.maxFoldBytes }),\n },\n maint?.options,\n ).then(\n () => {},\n () => {},\n ),\n );\n }\n\n // Base class-A op count for this attempt: content PUTs (skipping\n // `op:\"D\"`) + the single log create + index PUTs + index DELETEs.\n // No current.json CAS anymore. Forward-probe GETs are Class B and\n // excluded. The caller of `commit()` adds `(attempt - 1)` for retry\n // cost.\n const classAOps = contentPutCount + 1 + indexClassA;\n return {\n entries: committedEntries,\n // No current.json write on the commit path — return the manifest\n // etag read in Step 1 (still a valid etag of the current manifest).\n currentEtag: baseEtag,\n classAOps,\n };\n }\n\n /**\n * Auto-create the per-collection `current.json` at\n * `this.#currentJsonKey` with a zero-state initial manifest. Called\n * by `#singleAttemptCommit` when the read returned `null` (fresh\n * bucket / fresh collection).\n *\n * Concurrency: `createCurrentJson` uses `If-None-Match: \"*\"`. If a\n * peer raced us and won, the storage layer surfaces `Conflict`; we\n * recover by re-reading the now-present manifest. We do NOT retry\n * the create — a single recover-via-read covers every race that\n * could have produced our null read.\n *\n * The seed shape (`snapshot: null`, `tail_hint: 0`, `log_seq_start:\n * 0`, `writer_fence: { epoch: 0, owner: \"\", claimed_at: \"\" }`)\n * matches `ensureTable` and `baerly deploy`'s pre-warm path, so an\n * operator who pre-provisions and a writer who auto-creates land\n * on byte-identical bytes.\n *\n * @throws BaerlyError code=\"InvalidResponse\" — the post-recover\n * re-read also returned null. Defensive guard; in practice\n * unreachable because the Conflict implies the key now exists.\n */\n async #provisionCurrentJson(): Promise<CurrentJsonRead> {\n const initial: CurrentJson = {\n schema_version: CURRENT_JSON_SCHEMA_VERSION,\n snapshot: null,\n tail_hint: 0,\n log_seq_start: 0,\n writer_fence: { epoch: 0, owner: \"\", claimed_at: \"\" },\n snapshot_bytes: 0,\n snapshot_rows: 0,\n };\n try {\n return await createCurrentJson(this.#storage, this.#currentJsonKey, initial);\n } catch (error) {\n if (!(error instanceof BaerlyError) || error.code !== \"Conflict\") {\n throw error;\n }\n }\n const recovered = await readCurrentJson(this.#storage, this.#currentJsonKey);\n if (recovered === null) {\n throw new BaerlyError(\n \"InvalidResponse\",\n `Writer: current.json missing at ${this.#currentJsonKey} after auto-create raced and recover read returned null`,\n );\n }\n return recovered;\n }\n\n async #cleanupStaleIndexKeysBestEffort(args: {\n input: CommitInput;\n logPrefix: string;\n seq: number;\n }): Promise<number> {\n if (this.#indexes.length === 0) {\n return 0;\n }\n\n const { input } = args;\n let staleKeys: readonly string[] = [];\n try {\n if (input.op === \"U\") {\n const preImage = await this.#readPreImage(\n args.logPrefix,\n input.collection,\n input.docId,\n args.seq,\n );\n const oldKeys = allIndexKeysFor(args.logPrefix, this.#indexes, preImage, input.docId);\n const newSet = new Set(\n allIndexKeysFor(args.logPrefix, this.#indexes, input.body, input.docId),\n );\n staleKeys = oldKeys.filter((k) => !newSet.has(k));\n } else if (input.op === \"D\") {\n const preImage = await this.#readPreImage(\n args.logPrefix,\n input.collection,\n input.docId,\n args.seq,\n );\n staleKeys = allIndexKeysFor(args.logPrefix, this.#indexes, preImage, input.docId);\n }\n } catch {\n ctxMetrics().counter(\"db.write.index_cleanup_errors_total\", 1, {\n collection: input.collection,\n step: \"pre-image-read\",\n });\n return 0;\n }\n\n // (op:\"I\" has no pre-image → no stale keys.)\n const indexDeletes: Array<Promise<unknown>> = [];\n for (const k of staleKeys) {\n indexDeletes.push(\n this.#storage.delete(k).catch(() => {\n ctxMetrics().counter(\"db.write.index_cleanup_errors_total\", 1, {\n collection: input.collection,\n step: \"delete\",\n });\n }),\n );\n }\n await Promise.all(indexDeletes);\n return staleKeys.length;\n }\n\n /**\n * Read the pre-image content body for a doc by walking the live log\n * backwards from `currentNextSeq` looking for the most-recent I/U\n * entry on this `(collection, docId)`. Returns `undefined` when:\n *\n * - the doc's most-recent op was `D` (tombstone — no live body);\n * - no entry for this doc lives inside the visible log range\n * `[log_seq_start, currentNextSeq)` (a fresh-insert race or the\n * doc has been folded into the snapshot but is no longer\n * referenced).\n *\n * Used ONLY by the index-emission path's stale-key half (Step 5b, on\n * `U` / `D`) to compute which OLD-value keys to DELETE. Bounded by\n * `log_seq_start`: entries below have been folded into the snapshot\n * and may already be swept off the bucket — a snapshot fold is the\n * rebuild command's job (see `./rebuild-index.ts`), not the writer's.\n *\n * **Cost note:** linear walk, O(snapshot lag). For helpdesk-shape\n * collections (100s of docs, <10k log entries) this is fine — the\n * compactor folds the live tail every ~100 entries\n * (`packages/server/src/compactor.ts`). A follow-up ticket caches\n * per-doc index head in `current.json` for O(1) lookup.\n */\n async #readPreImage(\n logPrefix: string,\n collection: string,\n docId: string,\n currentNextSeq: number,\n ): Promise<DocumentData | undefined> {\n // Walk newest-to-oldest so we hit the most-recent op first.\n // `s = -1` is the natural empty-bucket sentinel.\n for (let s = currentNextSeq - 1; s >= 0; s--) {\n const logKey = logObjectKey(logPrefix, s);\n const got = await this.#storage.get(logKey);\n if (got === null) {\n // A hole below the visible range — either we walked past\n // `log_seq_start` (the entry was folded + swept) or a peer\n // is mid-CAS on a write we don't see yet. Bail; the\n // rebuild command (`rebuildIndex`) handles holes by\n // re-projecting from the snapshot.\n continue;\n }\n let entry: LogEntry;\n try {\n entry = decodeJsonBytes<LogEntry>(got.body);\n } catch {\n // Malformed entry shouldn't propagate up the index-emission\n // path — let the outer commit's `#walkLog` (step 2) flag it\n // as the protocol violation. Skip.\n continue;\n }\n if (entry.collection !== collection || entry.doc_id !== docId) {\n continue;\n }\n if (entry.op === \"D\") {\n return undefined;\n } // last op was delete\n if ((entry.op === \"I\" || entry.op === \"U\") && entry.after !== undefined) {\n return entry.after;\n }\n }\n return undefined;\n }\n\n /**\n * Walk `log/<logSeqStart>.json` … `log/<nextSeq - 1>.json` with\n * bounded parallelism via `walkLogRange`. Materialised entries are\n * discarded — the walk's only job is to surface a hole or a\n * malformed body inside the visible range as\n * `BaerlyError{code:\"Internal\"}` / `\"InvalidResponse\"`.\n *\n * Gated on `verifyLogIntegrityOnCommit`; default off in production\n * because the per-doc fold already lives in the read path. See the\n * option's docstring for the rationale and the opt-in convention.\n *\n * `logSeqStart` is the boundary set by the compactor on\n * `current.json.log_seq_start`. Entries below it have been folded\n * into the snapshot and may have been swept off the bucket, so the\n * walk MUST NOT GET-require them.\n */\n async #walkLog(logPrefix: string, logSeqStart: number, nextSeq: number): Promise<void> {\n await walkLogRange(this.#storage, logPrefix, logSeqStart, nextSeq);\n }\n\n /**\n * Bump the `db.r2.put.429_total` counter when `err` looks like an\n * R2 prefix-partition rate-limit. Best-effort: detected via\n * `BaerlyError{code:\"NetworkError\"}` with a `429` token in the\n * message. Called from every PUT call site's catch arm; mutually\n * exclusive in practice with `isPreconditionFailed` (412 ≠ 429).\n */\n #observe429(err: unknown, collection: string): void {\n if (is429(err)) {\n ctxMetrics().counter(\"db.r2.put.429_total\", 1, { collection });\n }\n }\n\n /**\n * Emit the per-logical-write `class_a_ops_per_logical_write`\n * histogram for `commit`. `classAOps` is the per-attempt base plus\n * a charge for prior failed attempts (the retry-budget cost model),\n * computed by the caller.\n */\n #emitWriteMetrics(collection: string, classAOps: number): void {\n ctxMetrics().histogram(\"db.write.class_a_ops_per_logical_write\", classAOps, { collection });\n }\n\n /**\n * Exponential backoff with full jitter. `25 * 2^(attempt-1)` capped\n * at 1500ms; uniform jitter in `[0, base)` keeps colliding peers\n * from re-racing in lockstep. Worst-case total wait across the\n * default 8 attempts is roughly 2.5 s — well under a typical\n * Worker request budget.\n */\n async #backoff(attempt: number): Promise<void> {\n const base = Math.min(this.#initialBackoffMs * 2 ** (attempt - 1), MAX_BACKOFF_MS);\n const sleepMs = base * this.#random();\n if (sleepMs <= 0) {\n return;\n }\n await new Promise<void>((r) => setTimeout(r, sleepMs));\n }\n}\n\n// ---------------------------------------------------------------------\n// Internals\n// ---------------------------------------------------------------------\n\n/**\n * `true` when the underlying storage surfaced a `PreconditionFailed`\n * 412 (or its non-S3 equivalents). Every in-tree {@link Storage} impl\n * surfaces a lost CAS as `BaerlyError{code:\"Conflict\"}`.\n */\nconst isPreconditionFailed = (err: unknown): boolean =>\n err instanceof BaerlyError && err.code === \"Conflict\";\n\n/**\n * `true` when a log-create PUT failed transiently (a `NetworkError`) —\n * the write may or may not have landed (a dropped ack). Safe to retry\n * the SAME seq: own-session adoption closes the double-commit window if\n * it did land. NOT a 412 (that's handled by adoption directly).\n */\nconst isTransientWrite = (err: unknown): boolean =>\n err instanceof BaerlyError && err.code === \"NetworkError\";\n\n/**\n * `true` when the underlying storage surfaced an R2 prefix-partition\n * rate-limit. {@link S3HttpStorage} stamps the upstream HTTP status\n * onto `BaerlyError.cause` as `{ status }`; we discriminate on that\n * structured field rather than regex-matching the message.\n */\nconst is429 = (err: unknown): boolean => {\n if (!(err instanceof BaerlyError) || err.code !== \"NetworkError\") {\n return false;\n }\n const cause = err.cause as { status?: number } | undefined;\n return cause?.status === 429;\n};\n","/**\n * `baerly admin restore` — bulk-import NDJSON into a fresh collection.\n *\n * Reads NDJSON from stdin, reconstructs each row, and calls\n * `Writer.commit({op:\"I\"})` per row into the target bucket.\n * Programmatic callers (today: tests + the export round-trip\n * integration test) can divert the input by passing\n * `{ streams: { stdin } }` to {@link runRestore}. Idempotent on a fresh\n * bucket: re-running on a half-completed restore **refuses** unless\n * `--force` is set (which reseeds a fresh `current.json` above the old\n * tail first).\n *\n * Args:\n * --bucket Required. Target bucket URI.\n * --app Required (or via baerly.config.ts).\n * --tenant Required (or via baerly.config.ts).\n * --collection Required. Target collection name.\n * --force Truncate the target if it exists (reseed above the old tail).\n * --json JSON envelope.\n *\n * stdin: NDJSON, one `{_id, ...}` row per line. Empty lines tolerated.\n * EOF terminates.\n *\n * Cost shape: under single-write commit each `Writer.commit` is 2 Class\n * A PUTs (content + the committing `log/<seq>` create — no per-row\n * `current.json` write). So: 1 PUT current.json (initial seed) + N × 2\n * + 1 PUT current.json (final `tail_hint` stamp) = 2N + 2 Class A ops\n * for N rows.\n *\n * Partial-restore semantics: a mid-stream Network / Internal / parse\n * error leaves the target in a partial state (some rows committed,\n * `current.json` advanced to wherever the last successful commit\n * landed). Re-run with `--force` to truncate, or hand-clean. The\n * malformed-line case (missing `_id`, bad JSON) fails fast on that\n * line; rows committed BEFORE it survive.\n *\n * Exit codes:\n * 0 — every row committed.\n * 1 — InvalidConfig (bad bucket URI, missing args).\n * 2 — Network / storage error mid-stream, or a malformed NDJSON\n * line (raised as a plain `Error`, not `BaerlyError`).\n * 3 — Conflict from a pre-existing target without --force, or from a\n * concurrent writer when --force was used.\n */\n\nimport { createInterface } from \"node:readline\";\nimport { type ArgsDef } from \"citty\";\nimport {\n BaerlyError,\n CURRENT_JSON_SCHEMA_VERSION,\n createCurrentJson,\n type CurrentJson,\n type DocumentData,\n encodeJsonBytes,\n readCurrentJson,\n type Storage,\n} from \"@baerly/protocol\";\nimport { Writer } from \"@baerly/server/_internal/testing\";\nimport { parseBucketUri } from \"../bucket-uri.ts\";\nimport { emitSuccess } from \"../output.ts\";\nimport {\n APP_ARG,\n assertCollectionArg,\n defineBaerlySubcommand,\n JSON_ARG,\n TENANT_ARG,\n} from \"../subcommand.ts\";\n\nconst RESTORE_OWNER = \"baerly-restore\";\n\nconst RESTORE_ARGS = {\n bucket: {\n type: \"string\",\n required: true,\n description: \"Target bucket URI (s3://<bucket>[/<prefix>], file:///<abs>, memory://<bucket>)\",\n valueHint: \"bucket-uri\",\n },\n app: APP_ARG,\n tenant: TENANT_ARG,\n collection: {\n type: \"string\",\n required: true,\n description: \"Target collection name.\",\n valueHint: \"name\",\n },\n force: {\n type: \"boolean\",\n description: \"Truncate the target if it exists (bump fence + reseed current.json).\",\n },\n json: JSON_ARG,\n} as const satisfies ArgsDef;\n\nconst tailFromListedLogKeys = async (\n storage: Storage,\n collectionPrefix: string,\n): Promise<number> => {\n const logPrefix = `${collectionPrefix}/log/`;\n let maxSeq = -1;\n for await (const entry of storage.list(logPrefix)) {\n const tail = entry.key.slice(logPrefix.length);\n const match = /^(\\d+)\\.json$/.exec(tail);\n if (match === null) {\n continue;\n }\n const seq = Number.parseInt(match[1]!, 10);\n if (Number.isFinite(seq) && seq > maxSeq) {\n maxSeq = seq;\n }\n }\n return maxSeq + 1;\n};\n\nconst bundle = defineBaerlySubcommand({\n name: \"admin.restore\",\n meta: {\n description: \"Bulk-import canonical NDJSON into a fresh collection.\",\n },\n args: RESTORE_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 admin restore\");\n const currentJsonKey = `${bucket.keyPrefix}app/${app}/tenant/${tenant}/manifests/${args.collection}/current.json`;\n\n let baseSeq = 0;\n const head = await readCurrentJson(bucket.storage, currentJsonKey);\n if (head !== null && args.force !== true) {\n throw new BaerlyError(\n \"Conflict\",\n `baerly admin restore: ${currentJsonKey} exists; pass --force to truncate`,\n undefined,\n undefined,\n undefined,\n \"Pass --force to truncate the existing collection, or choose an empty target.\",\n false,\n );\n }\n if (head !== null) {\n // --force: reseed `current.json` above the old tail under\n // If-Match. The If-Match guards against a concurrent COMPACTOR\n // (the only steady-state writer of `current.json` under\n // single-write commit) landing between our read and our PUT —\n // that surfaces Conflict (exit 3). It does NOT fence concurrent\n // WRITERS: under single-write commit writers never touch\n // `current.json`, so the dormant `writer_fence` epoch is no\n // longer consulted. `restore` therefore assumes operational\n // exclusivity — do not run it against a collection taking live\n // writes. (We still bump the fence epoch to keep the field\n // monotone, but nothing reads it.)\n //\n // CRITICAL: stale log entries from the old generation still\n // live on disk under `log/<seq>.json` paths. The writer's\n // `If-None-Match: \"*\"` log PUT will 412 if we restart `tail_hint`\n // at 0 and collide with `log/0.json`. We instead advance\n // `tail_hint` and `log_seq_start` past the old data so new\n // commits land at fresh sequence numbers and the old log files\n // become unreferenced orphans (the compactor / GC sweep them on\n // the next maintenance pass). Do this from LISTed log keys, not\n // by folding the old log bodies: `--force` must be able to recover\n // from malformed old entries, and a hole must not make us\n // under-shoot a later old entry.\n const collectionPrefix = currentJsonKey.slice(0, currentJsonKey.lastIndexOf(\"/\"));\n const truncatedNext = await tailFromListedLogKeys(bucket.storage, collectionPrefix);\n baseSeq = truncatedNext;\n const reseeded: CurrentJson = {\n schema_version: CURRENT_JSON_SCHEMA_VERSION,\n snapshot: null,\n tail_hint: truncatedNext,\n log_seq_start: truncatedNext,\n writer_fence: {\n epoch: head.json.writer_fence.epoch + 1,\n owner: RESTORE_OWNER,\n claimed_at: \"\",\n },\n snapshot_bytes: 0,\n snapshot_rows: 0,\n };\n try {\n await bucket.storage.put(currentJsonKey, encodeJsonBytes(reseeded), {\n ifMatch: head.etag,\n contentType: \"application/json\",\n });\n } catch (error) {\n if (error instanceof BaerlyError) {\n throw error;\n }\n throw new BaerlyError(\n \"NetworkError\",\n `baerly admin restore: failed to reseed current.json: ${(error as Error).message}`,\n );\n }\n } else {\n // Fresh target: seed `current.json` with `tail_hint=0`.\n const seed: CurrentJson = {\n schema_version: CURRENT_JSON_SCHEMA_VERSION,\n snapshot: null,\n tail_hint: 0,\n log_seq_start: 0,\n writer_fence: { epoch: 0, owner: RESTORE_OWNER, claimed_at: \"\" },\n snapshot_bytes: 0,\n snapshot_rows: 0,\n };\n await createCurrentJson(bucket.storage, currentJsonKey, seed);\n }\n\n const writer = new Writer({ storage: bucket.storage, currentJsonKey });\n\n const input = ctx.streams?.stdin ?? process.stdin;\n const rl = createInterface({ input, crlfDelay: Infinity });\n let count = 0;\n let lineNo = 0;\n for await (const line of rl) {\n lineNo++;\n if (line.length === 0) {\n continue;\n }\n let parsed: unknown;\n try {\n parsed = JSON.parse(line);\n } catch (error) {\n // Malformed NDJSON mid-stream → exit 2 (the ticket's\n // partial-restore contract: the line that failed wasn't\n // committed, but anything BEFORE it survives). Bare `Error`\n // (not `BaerlyError`) routes through the helper's \"unknown\"\n // arm → exit 2.\n throw new Error(\n `baerly admin restore: line ${lineNo} is not valid JSON: ${(error as Error).message}`,\n { cause: error },\n );\n }\n if (parsed === null || typeof parsed !== \"object\" || Array.isArray(parsed)) {\n throw new Error(`baerly admin restore: line ${lineNo} is not a JSON object`);\n }\n const row = parsed as Record<string, unknown>;\n const id = row[\"_id\"];\n if (typeof id !== \"string\" || id.length === 0) {\n throw new Error(`baerly admin restore: line ${lineNo} missing non-empty string _id`);\n }\n // Pass the full object as the body — `_id` is part of the\n // body in the doc shape, and the writer keys on `docId`\n // separately.\n const body = row as unknown as DocumentData;\n await writer.commit({\n op: \"I\",\n collection: args.collection,\n docId: id,\n body,\n });\n count++;\n }\n // Stamp the final `tail_hint` durably. Under single-write commit the\n // writer never advances the hint (it's compactor-advanced) — but a\n // bulk restore knows exactly how many rows it wrote, so it stamps the\n // true tail (`baseSeq + count`) under If-Match so the restored bucket\n // reads efficiently without a forward-probe. A concurrent compactor\n // between our last commit and this stamp surfaces Conflict (exit 3).\n // CLAMP: `tail_hint` is a monotone lower bound, so never stamp it\n // BELOW what is already durable — take the max of our computed tail,\n // the value already stored, and `log_seq_start`. (Defends against a\n // compactor that advanced the hint between the reseed and here.)\n if (count > 0) {\n const afterLoad = await readCurrentJson(bucket.storage, currentJsonKey);\n if (afterLoad !== null) {\n const clampedTail = Math.max(\n baseSeq + count,\n afterLoad.json.tail_hint,\n afterLoad.json.log_seq_start,\n );\n const stamped: CurrentJson = { ...afterLoad.json, tail_hint: clampedTail };\n await bucket.storage.put(currentJsonKey, encodeJsonBytes(stamped), {\n ifMatch: afterLoad.etag,\n contentType: \"application/json\",\n });\n }\n }\n emitSuccess({\n command: \"admin.restore\",\n status: \"ok\",\n collection: args.collection,\n restored: count,\n });\n return 0;\n },\n});\n\n/** citty `defineCommand` block for `baerly admin restore`. */\nexport const restoreCmd = 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 runRestore = bundle.run;\n"],"mappings":"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"}
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
const specIr = {
|
|
4
4
|
$schema: "https://baerly.dev/spec/ir-schema.json",
|
|
5
5
|
specVersion: "1",
|
|
6
|
-
|
|
6
|
+
serverVersion: "0.6.0",
|
|
7
7
|
errorCodes: [
|
|
8
8
|
{
|
|
9
9
|
"code": "InvalidConfig",
|
|
@@ -388,4 +388,4 @@ async function handleSpecRequest(request, resolve) {
|
|
|
388
388
|
//#endregion
|
|
389
389
|
export { handleSpecRequest as t };
|
|
390
390
|
|
|
391
|
-
//# sourceMappingURL=runtime-spec
|
|
391
|
+
//# sourceMappingURL=runtime-spec--LykAdl1.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"runtime-spec
|
|
1
|
+
{"version":3,"file":"runtime-spec--LykAdl1.js","names":["rawSpecIr"],"sources":["../packages/server/spec/baerly.spec.json","../packages/server/src/spec/runtime-spec.ts"],"sourcesContent":["","import type { BaerlyConfig, Verifier } from \"@baerly/protocol\";\nimport type { SpecIR } from \"./ir.ts\";\nimport rawSpecIr from \"../../spec/baerly.spec.json\" with { type: \"json\" };\n\n// Import the JSON as data (not ir.ts which drags the HTTP router into\n// the kernel closure). Cast to SpecIR so callers get typed access to\n// errorCodes, specVersion, etc. without following the ir.ts import chain.\nconst specIr = rawSpecIr as unknown as SpecIR;\n\n/** A declared collection summary, emitted only to authed callers. */\nexport interface SpecCollection {\n readonly name: string;\n readonly indexes: ReadonlyArray<string>;\n readonly schemaVendor?: string;\n}\n\n/** The /v1/spec response: the static IR plus an optional authed collections section. */\nexport type SpecResponse = SpecIR & { collections?: ReadonlyArray<SpecCollection> };\n\n/**\n * Build the /v1/spec response body. With no `config` (anonymous caller)\n * the static contract IR is returned verbatim. With a `config` (the\n * request already carried a valid identity), the declared collection\n * names + index names + schema vendor are appended — these are gated\n * behind the verifier so unauthenticated callers can't enumerate tenant\n * collection names.\n */\nexport function buildSpecResponse(config?: BaerlyConfig): SpecResponse {\n if (config === undefined) {\n return specIr as SpecResponse;\n }\n const collections: SpecCollection[] = Object.entries(config.collections).map(\n ([name, def]): SpecCollection => {\n const indexes = (def.indexes ?? []).map((ix) => ix.name);\n if (def.schema !== undefined) {\n return { name, indexes, schemaVendor: def.schema[\"~standard\"].vendor };\n }\n return { name, indexes };\n },\n );\n return { ...(specIr as SpecResponse), collections };\n}\n\n// Shared `GET /v1/spec` handler for both adapters (keeps the response shape\n// from drifting). `resolve` yields the adapter's verifier + tenant config.\n// Run tolerantly: any `resolve` or verifier failure degrades to the anonymous\n// static contract — it is public infra that must stay up when auth/config is\n// unhealthy. Collections are appended only for a non-null identity, so an\n// unauthenticated probe never enumerates them.\nexport async function handleSpecRequest(\n request: Request,\n resolve: () => Promise<{ verifier: Verifier; config: BaerlyConfig | undefined }>,\n): Promise<Response> {\n let config: BaerlyConfig | undefined;\n try {\n const { verifier, config: resolved } = await resolve();\n const identity = await verifier(request);\n if (identity !== null) {\n config = resolved;\n }\n } catch (error) {\n // A verifier *reject* is `null` (handled above); reaching here means\n // resolve() or the verifier *threw* — the auth backend or tenant config\n // is unhealthy. Stay tolerant (the static contract is public infra and\n // must stay up), but emit one operational signal so the outage isn't\n // invisible on this anonymous, pre-observability route. `console.warn`\n // (not a canonical line) matches the adapters' other ops warnings and\n // keeps this light module out of the observability closure. Log only the\n // error *message*, never the error object: an auth-backend failure can\n // carry credential material (tokens, keys, connection strings) in its\n // fields/stack, and this line lands in plaintext logs.\n const reason = error instanceof Error ? error.message : String(error);\n console.warn(`[baerly] /v1/spec degraded to the anonymous contract: ${reason}`);\n }\n return new Response(JSON.stringify(buildSpecResponse(config)), {\n status: 200,\n headers: { \"content-type\": \"application/json\" },\n });\n}\n"],"mappings":";;ACOA,MAAM,SAASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAAA;;;;;;;;;AAoBf,SAAgB,kBAAkB,QAAqC;CACrE,IAAI,WAAW,KAAA,GACb,OAAO;CAET,MAAM,cAAgC,OAAO,QAAQ,OAAO,WAAW,CAAC,CAAC,KACtE,CAAC,MAAM,SAAyB;EAC/B,MAAM,WAAW,IAAI,WAAW,CAAC,EAAA,CAAG,KAAK,OAAO,GAAG,IAAI;EACvD,IAAI,IAAI,WAAW,KAAA,GACjB,OAAO;GAAE;GAAM;GAAS,cAAc,IAAI,OAAO,YAAY,CAAC;EAAO;EAEvE,OAAO;GAAE;GAAM;EAAQ;CACzB,CACF;CACA,OAAO;EAAE,GAAI;EAAyB;CAAY;AACpD;AAQA,eAAsB,kBACpB,SACA,SACmB;CACnB,IAAI;CACJ,IAAI;EACF,MAAM,EAAE,UAAU,QAAQ,aAAa,MAAM,QAAQ;EAErD,IAAI,MADmB,SAAS,OAAO,MACtB,MACf,SAAS;CAEb,SAAS,OAAO;EAWd,MAAM,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;EACpE,QAAQ,KAAK,yDAAyD,QAAQ;CAChF;CACA,OAAO,IAAI,SAAS,KAAK,UAAU,kBAAkB,MAAM,CAAC,GAAG;EAC7D,QAAQ;EACR,SAAS,EAAE,gBAAgB,mBAAmB;CAChD,CAAC;AACH"}
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { _ as StoragePutOptions, g as StorageListEntry, h as StorageGetResult, m as StorageGetOptions, p as Storage, v as StoragePutResult } from "./index-
|
|
1
|
+
import { _ as StoragePutOptions, g as StorageListEntry, h as StorageGetResult, m as StorageGetOptions, p as Storage, v as StoragePutResult } from "./index-CEZKQsKt.js";
|
|
2
2
|
|
|
3
3
|
//#region packages/adapter-node/src/s3-http.d.ts
|
|
4
4
|
/**
|
|
@@ -34,8 +34,10 @@ interface S3HttpStorageOptions {
|
|
|
34
34
|
}
|
|
35
35
|
/**
|
|
36
36
|
* `Storage` impl that speaks the S3 REST API directly. Works against
|
|
37
|
-
* any S3-compatible endpoint — AWS S3, R2 (S3-compat),
|
|
38
|
-
*
|
|
37
|
+
* any S3-compatible endpoint — AWS S3, R2 (S3-compat), Minio. Does not
|
|
38
|
+
* depend on any AWS SDK. GCS is NOT supported over this S3-interop path
|
|
39
|
+
* (its conditional-write semantics can't linearize the commit log); use
|
|
40
|
+
* the native `GcsHttpStorage` adapter instead.
|
|
39
41
|
*
|
|
40
42
|
* Authentication is plugged in via the `sign` callback; this class
|
|
41
43
|
* itself does no SigV4. For Cloudflare Workers, the R2 binding fast
|
|
@@ -57,4 +59,4 @@ declare class S3HttpStorage implements Storage {
|
|
|
57
59
|
}
|
|
58
60
|
//#endregion
|
|
59
61
|
export { S3HttpStorageOptions as n, S3HttpStorage as t };
|
|
60
|
-
//# sourceMappingURL=s3-http-
|
|
62
|
+
//# sourceMappingURL=s3-http-DD5gDc7t.d.ts.map
|
package/dist/s3.d.ts
CHANGED
package/dist/s3.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { t as BaerlyError } from "./errors-Dfa3p78c.js";
|
|
2
|
-
import { n as S3HttpStorage, t as AwsClient } from "./aws4fetch.esm-
|
|
2
|
+
import { n as S3HttpStorage, t as AwsClient } from "./aws4fetch.esm-CXE5ZbAa.js";
|
|
3
3
|
//#region packages/adapter-node/src/s3-signer.ts
|
|
4
4
|
/**
|
|
5
5
|
* Static-credential SigV4 signer for {@link S3HttpStorage}, safe inside
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
//#region packages/protocol/src/sha256.ts
|
|
2
|
+
/**
|
|
3
|
+
* SHA-256 of `bytes` as a 64-char lowercase hex string.
|
|
4
|
+
*
|
|
5
|
+
* Zero-import leaf module on purpose: co-locating this with heavier
|
|
6
|
+
* runtime (snapshot-hash.ts / hashing.ts) would drag that module into
|
|
7
|
+
* every consumer's bundle closure. Callers that want a truncated form
|
|
8
|
+
* (e.g. {@link versionFromContent}'s content keys) slice the return.
|
|
9
|
+
*/
|
|
10
|
+
const sha256Hex = async (bytes) => {
|
|
11
|
+
const view = new Uint8Array(bytes.byteLength);
|
|
12
|
+
view.set(bytes);
|
|
13
|
+
const digest = await crypto.subtle.digest("SHA-256", view);
|
|
14
|
+
const out = new Uint8Array(digest);
|
|
15
|
+
let hex = "";
|
|
16
|
+
for (let i = 0; i < out.length; i++) hex += out[i].toString(16).padStart(2, "0");
|
|
17
|
+
return hex;
|
|
18
|
+
};
|
|
19
|
+
//#endregion
|
|
20
|
+
export { sha256Hex as t };
|
|
21
|
+
|
|
22
|
+
//# sourceMappingURL=sha256-CqcKTjw9.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"sha256-CqcKTjw9.js","names":[],"sources":["../packages/protocol/src/sha256.ts"],"sourcesContent":["/**\n * SHA-256 of `bytes` as a 64-char lowercase hex string.\n *\n * Zero-import leaf module on purpose: co-locating this with heavier\n * runtime (snapshot-hash.ts / hashing.ts) would drag that module into\n * every consumer's bundle closure. Callers that want a truncated form\n * (e.g. {@link versionFromContent}'s content keys) slice the return.\n */\nexport const sha256Hex = async (bytes: Uint8Array): Promise<string> => {\n // Copy via fresh ArrayBuffer: tsgo narrows `Uint8Array` to\n // `Uint8Array<ArrayBufferLike>`, which `crypto.subtle.digest` rejects\n // (wants `ArrayBufferView<ArrayBuffer>`). See microsoft/TypeScript#61375.\n const view = new Uint8Array(bytes.byteLength);\n view.set(bytes);\n const digest = await crypto.subtle.digest(\"SHA-256\", view);\n // Hand-rolled hex, not `Uint8Array.prototype.toHex()`: that TC39 method is\n // declared by the `ESNext.TypedArrays` lib (so it type-checks) but is gated\n // behind V8's `--js-base-64` flag in our Node floor (24.x) and isn't\n // universal across workerd/Node unflagged — it would throw at runtime.\n const out = new Uint8Array(digest);\n let hex = \"\";\n for (let i = 0; i < out.length; i++) {\n hex += out[i]!.toString(16).padStart(2, \"0\");\n }\n return hex;\n};\n"],"mappings":";;;;;;;;;AAQA,MAAa,YAAY,OAAO,UAAuC;CAIrE,MAAM,OAAO,IAAI,WAAW,MAAM,UAAU;CAC5C,KAAK,IAAI,KAAK;CACd,MAAM,SAAS,MAAM,OAAO,OAAO,OAAO,WAAW,IAAI;CAKzD,MAAM,MAAM,IAAI,WAAW,MAAM;CACjC,IAAI,MAAM;CACV,KAAK,IAAI,IAAI,GAAG,IAAI,IAAI,QAAQ,KAC9B,OAAO,IAAI,EAAE,CAAE,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG;CAE7C,OAAO;AACT"}
|