alchemy 2.0.0-beta.77 → 2.0.0-beta.78

package/lib/Git/Store/IncomingBody.js

@@ -0,0 +1,61 @@
+/**
+ * Receiving a git wire request body (DESIGN.md §3.6, §22.6, §22.10).
+ *
+ * A push body must NEVER be materialized: `request.arrayBuffer` on a
+ * 100 MiB pack inside a 128 MB isolate is an OOM (the failure that rejected
+ * the full alchemy-history push with a 500). The body is fed chunk by
+ * chunk into a {@link StreamingFeeder} the parser reads from as bytes
+ * arrive; the parser ends the body's life in memory by dispatching it in
+ * uniform parts to the hasher isolates, which write the parts to blob
+ * storage (the spill) while verifying them.
+ *
+ * The command section of a receive-pack request lives in the first bytes,
+ * so the first {@link HEAD_BYTES} are enough to parse the ref commands
+ * before the pack has arrived.
+ */
+import * as Effect from "effect/Effect";
+import { StoreError } from "../Protocol/Store.js";
+/** Head prefix that is enough for command-section parsing. */
+export const HEAD_BYTES = 1024 * 1024;
+/**
+ * Uniform multipart part size — also the hasher part size, since each
+ * hasher isolate writes the part it verifies (DESIGN §22.10). 8 MiB is
+ * above R2's 5 MiB minimum and its 10,000-part limit still allows ~78 GiB.
+ */
+export const SPILL_PART_BYTES = 8 * 1024 * 1024;
+/**
+ * Feeds a request body into the streaming source and ends it when the
+ * body ends. The reader respects feeder backpressure while application
+ * authorization or validation is running, and cancellation cancels the
+ * underlying body reader. Resolves with the total; a read failure
+ * fails the feeder so every waiting reader wakes with the error.
+ */
+export const feedBody = (body, feeder) => Effect.tryPromise({
+    try: async (signal) => {
+        let total = 0;
+        if (body !== null) {
+            const reader = body.getReader();
+            const cancel = () => {
+                void reader.cancel().catch(() => { });
+            };
+            signal.addEventListener("abort", cancel, { once: true });
+            try {
+                while (!signal.aborted) {
+                    const { value, done } = await reader.read();
+                    if (done)
+                        break;
+                    total += value.length;
+                    await Effect.runPromise(feeder.push(value), { signal });
+                }
+            }
+            finally {
+                signal.removeEventListener("abort", cancel);
+                reader.releaseLock();
+            }
+        }
+        feeder.end();
+        return { total };
+    },
+    catch: (error) => new StoreError({ reason: `incoming body read: ${String(error)}` }),
+}).pipe(Effect.tapError((error) => Effect.sync(() => feeder.fail(error))));
+//# sourceMappingURL=IncomingBody.js.map

package/lib/Git/Store/IncomingBody.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IncomingBody.js","sourceRoot":"","sources":["../../../src/Git/Store/IncomingBody.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGlD,8DAA8D;AAC9D,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,GAAG,IAAI,CAAC;AAEtC;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CACtB,IAAuC,EACvC,MAAuB,EACgC,EAAE,CACzD,MAAM,CAAC,UAAU,CAAC;IAChB,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;QACpB,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;YAChC,MAAM,MAAM,GAAG,GAAG,EAAE;gBAClB,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YACvC,CAAC,CAAC;YACF,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACzD,IAAI,CAAC;gBACH,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;oBACvB,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;oBAC5C,IAAI,IAAI;wBAAE,MAAM;oBAChB,KAAK,IAAI,KAAK,CAAC,MAAM,CAAC;oBACtB,MAAM,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;gBAC1D,CAAC;YACH,CAAC;oBAAS,CAAC;gBACT,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;gBAC5C,MAAM,CAAC,WAAW,EAAE,CAAC;YACvB,CAAC;QACH,CAAC;QACD,MAAM,CAAC,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,KAAK,EAAE,CAAC;IACnB,CAAC;IACD,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CACf,IAAI,UAAU,CAAC,EAAE,MAAM,EAAE,uBAAuB,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;CACrE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/lib/Git/Store/Keys.d.ts

@@ -0,0 +1,105 @@
+/**
+ * R2 key scheme (DESIGN.md §3.2).
+ *
+ * All R2 keys are **immutable and content-addressed** — this sidesteps the
+ * 1-write/s/key limit, makes conditional-put re-runs (idempotent alarm jobs)
+ * safe, and makes cross-repo fork references safe: a fork's `objects.r2_key`
+ * may point into the parent repo's prefix, since the bytes at a key never
+ * change once written.
+ *
+ * ```
+ * {repoId}/objects/{oid}            oversize loose objects, zlib(content)
+ * {repoId}/packs/pack-{sha1}.pack   v1.1 compaction output
+ * {repoId}/incoming/{pushId}.pack   v1.x streaming-push tee (reserved)
+ * {repoId}/lfs/{sha256}             LFS objects (reserved)
+ * ```
+ *
+ * `list()` is never used on a hot path — the `objects` table is the sole
+ * inventory. The prefix helpers exist for the delete-purge and GC alarm jobs
+ * only.
+ */
+/**
+ * R2 key for an oversize loose object: `{repoId}/objects/{oid}`.
+ *
+ * The stored bytes are `zlib(content)` without the loose header — byte-equal
+ * to what an `objects.location = 'row'` row would hold in `zdata`.
+ */
+export declare const objectKey: (repoId: string, oid: string) => string;
+/**
+ * R2 key for a compacted pack (v1.1): `{repoId}/packs/pack-{sha1}.pack`.
+ * The `sha1` is the pack's trailer checksum, making the key content-addressed.
+ */
+export declare const packKey: (repoId: string, sha: string) => string;
+/**
+ * R2 key of a clone bundle for a ref snapshot (DESIGN.md §12.2):
+ * `{repoId}/bundles/bundle-{refsHash}.pack`. Immutable and
+ * content-addressed by the refs it covers, so it is safe to cache at the
+ * edge and safe to write concurrently.
+ */
+export declare const bundleKey: (repoId: string, refsHash: string) => string;
+/**
+ * The bundle's **pre-framed** twin (DESIGN §22.4): the same pack already
+ * cut into band-1 sideband frames of exactly 65515 data bytes. Real git
+ * always negotiates `side-band-64k`, and bytes that cross into JS to be
+ * framed measured a hard ~15 MiB/s ceiling regardless of how the framing
+ * was written; this twin lets the sideband case be a platform-to-platform
+ * pipe like the raw case. Written alongside the bundle, immutable, same
+ * lifecycle (purged with the prefix).
+ */
+export declare const bundleSidebandKey: (repoId: string, refsHash: string) => string;
+/**
+ * R2 key for a streamed incoming push pack (v1.x upgrade seam, DESIGN.md
+ * §3.6): `{repoId}/incoming/{pushId}.pack`. Reserved — unused in v1's
+ * buffered ingest.
+ */
+export declare const incomingKey: (repoId: string, pushId: string) => string;
+/**
+ * Pack-id prefix of a **promoted wire pack** (DESIGN §22.5): a push whose
+ * body spilled to blob storage already holds every non-delta blob in the
+ * compaction layout (`typeSize header + zdata`), so ingest points those
+ * rows straight into the incoming object instead of copying 40 MiB of
+ * blobs through SQLite and compacting them out again later. The pack id
+ * is `wire-<receiveId>`; the object stays at its `incomingKey`.
+ */
+export declare const WIRE_PACK_PREFIX = "wire-";
+export declare const wirePackId: (receiveId: string) => string;
+export declare const isWirePackId: (packId: string) => boolean;
+/** R2 key of any pack by id — compacted (`packKey`) or promoted wire pack. */
+export declare const packKeyOf: (repoId: string, packId: string) => string;
+/**
+ * R2 key reserved for a future LFS object (DESIGN.md §10):
+ * `{repoId}/lfs/{sha256}`.
+ */
+export declare const lfsKey: (repoId: string, sha256: string) => string;
+/**
+ * The whole-repo R2 prefix (`{repoId}/`) — the unit the delete-purge alarm
+ * job lists and deletes (retained while the Registry reports
+ * `fork_count > 0`, since forks reference keys under it).
+ */
+export declare const repoPrefix: (repoId: string) => string;
+/**
+ * Prefix of all oversize loose objects for a repo: `{repoId}/objects/`.
+ */
+export declare const objectsPrefix: (repoId: string) => string;
+/**
+ * Prefix of all compacted packs for a repo (v1.1): `{repoId}/packs/`.
+ */
+export declare const packsPrefix: (repoId: string) => string;
+/**
+ * Prefix of all in-flight streamed push packs for a repo (reserved):
+ * `{repoId}/incoming/`.
+ */
+export declare const incomingPrefix: (repoId: string) => string;
+/**
+ * Prefix of all LFS objects for a repo (reserved): `{repoId}/lfs/`.
+ */
+export declare const lfsPrefix: (repoId: string) => string;
+/**
+ * R2 key of a repo's head snapshot (DESIGN.md §21): a small JSON object
+ * describing the current refs, visibility, and clone bundle, written by
+ * the Repo DO after every mutation commit. Lets the Worker serve
+ * anonymous public reads (advertisement + bundle clones) without waking
+ * the DO. Lives under the repo prefix so purge drains it.
+ */
+export declare const headKey: (repoId: string) => string;
+//# sourceMappingURL=Keys.d.ts.map

package/lib/Git/Store/Keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Keys.d.ts","sourceRoot":"","sources":["../../../src/Git/Store/Keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,SAAS,WAAY,MAAM,OAAO,MAAM,KAAG,MAC5B,CAAC;AAE7B;;;GAGG;AACH,eAAO,MAAM,OAAO,WAAY,MAAM,OAAO,MAAM,KAAG,MAClB,CAAC;AAErC;;;;;GAKG;AACH,eAAO,MAAM,SAAS,WAAY,MAAM,YAAY,MAAM,KAAG,MAChB,CAAC;AAE9C;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,WAAY,MAAM,YAAY,MAAM,KAAG,MACpB,CAAC;AAElD;;;;GAIG;AACH,eAAO,MAAM,WAAW,WAAY,MAAM,UAAU,MAAM,KAAG,MACxB,CAAC;AAEtC;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,UAAU,CAAC;AACxC,eAAO,MAAM,UAAU,cAAe,MAAM,KAAG,MACZ,CAAC;AACpC,eAAO,MAAM,YAAY,WAAY,MAAM,KAAG,OACT,CAAC;AAEtC,8EAA8E;AAC9E,eAAO,MAAM,SAAS,WAAY,MAAM,UAAU,MAAM,KAAG,MAG9B,CAAC;AAE9B;;;GAGG;AACH,eAAO,MAAM,MAAM,WAAY,MAAM,UAAU,MAAM,KAAG,MAC7B,CAAC;AAE5B;;;;GAIG;AACH,eAAO,MAAM,UAAU,WAAY,MAAM,KAAG,MAAsB,CAAC;AAEnE;;GAEG;AACH,eAAO,MAAM,aAAa,WAAY,MAAM,KAAG,MAA8B,CAAC;AAE9E;;GAEG;AACH,eAAO,MAAM,WAAW,WAAY,MAAM,KAAG,MAA4B,CAAC;AAE1E;;;GAGG;AACH,eAAO,MAAM,cAAc,WAAY,MAAM,KAAG,MAA+B,CAAC;AAEhF;;GAEG;AACH,eAAO,MAAM,SAAS,WAAY,MAAM,KAAG,MAA0B,CAAC;AAEtE;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,WAAY,MAAM,KAAG,MAA0B,CAAC"}

package/lib/Git/Store/Keys.js

@@ -0,0 +1,107 @@
+/**
+ * R2 key scheme (DESIGN.md §3.2).
+ *
+ * All R2 keys are **immutable and content-addressed** — this sidesteps the
+ * 1-write/s/key limit, makes conditional-put re-runs (idempotent alarm jobs)
+ * safe, and makes cross-repo fork references safe: a fork's `objects.r2_key`
+ * may point into the parent repo's prefix, since the bytes at a key never
+ * change once written.
+ *
+ * ```
+ * {repoId}/objects/{oid}            oversize loose objects, zlib(content)
+ * {repoId}/packs/pack-{sha1}.pack   v1.1 compaction output
+ * {repoId}/incoming/{pushId}.pack   v1.x streaming-push tee (reserved)
+ * {repoId}/lfs/{sha256}             LFS objects (reserved)
+ * ```
+ *
+ * `list()` is never used on a hot path — the `objects` table is the sole
+ * inventory. The prefix helpers exist for the delete-purge and GC alarm jobs
+ * only.
+ */
+/**
+ * R2 key for an oversize loose object: `{repoId}/objects/{oid}`.
+ *
+ * The stored bytes are `zlib(content)` without the loose header — byte-equal
+ * to what an `objects.location = 'row'` row would hold in `zdata`.
+ */
+export const objectKey = (repoId, oid) => `${repoId}/objects/${oid}`;
+/**
+ * R2 key for a compacted pack (v1.1): `{repoId}/packs/pack-{sha1}.pack`.
+ * The `sha1` is the pack's trailer checksum, making the key content-addressed.
+ */
+export const packKey = (repoId, sha) => `${repoId}/packs/pack-${sha}.pack`;
+/**
+ * R2 key of a clone bundle for a ref snapshot (DESIGN.md §12.2):
+ * `{repoId}/bundles/bundle-{refsHash}.pack`. Immutable and
+ * content-addressed by the refs it covers, so it is safe to cache at the
+ * edge and safe to write concurrently.
+ */
+export const bundleKey = (repoId, refsHash) => `${repoId}/bundles/bundle-${refsHash}.pack`;
+/**
+ * The bundle's **pre-framed** twin (DESIGN §22.4): the same pack already
+ * cut into band-1 sideband frames of exactly 65515 data bytes. Real git
+ * always negotiates `side-band-64k`, and bytes that cross into JS to be
+ * framed measured a hard ~15 MiB/s ceiling regardless of how the framing
+ * was written; this twin lets the sideband case be a platform-to-platform
+ * pipe like the raw case. Written alongside the bundle, immutable, same
+ * lifecycle (purged with the prefix).
+ */
+export const bundleSidebandKey = (repoId, refsHash) => `${repoId}/bundles/bundle-${refsHash}.sideband`;
+/**
+ * R2 key for a streamed incoming push pack (v1.x upgrade seam, DESIGN.md
+ * §3.6): `{repoId}/incoming/{pushId}.pack`. Reserved — unused in v1's
+ * buffered ingest.
+ */
+export const incomingKey = (repoId, pushId) => `${repoId}/incoming/${pushId}.pack`;
+/**
+ * Pack-id prefix of a **promoted wire pack** (DESIGN §22.5): a push whose
+ * body spilled to blob storage already holds every non-delta blob in the
+ * compaction layout (`typeSize header + zdata`), so ingest points those
+ * rows straight into the incoming object instead of copying 40 MiB of
+ * blobs through SQLite and compacting them out again later. The pack id
+ * is `wire-<receiveId>`; the object stays at its `incomingKey`.
+ */
+export const WIRE_PACK_PREFIX = "wire-";
+export const wirePackId = (receiveId) => `${WIRE_PACK_PREFIX}${receiveId}`;
+export const isWirePackId = (packId) => packId.startsWith(WIRE_PACK_PREFIX);
+/** R2 key of any pack by id — compacted (`packKey`) or promoted wire pack. */
+export const packKeyOf = (repoId, packId) => isWirePackId(packId)
+    ? incomingKey(repoId, packId.slice(WIRE_PACK_PREFIX.length))
+    : packKey(repoId, packId);
+/**
+ * R2 key reserved for a future LFS object (DESIGN.md §10):
+ * `{repoId}/lfs/{sha256}`.
+ */
+export const lfsKey = (repoId, sha256) => `${repoId}/lfs/${sha256}`;
+/**
+ * The whole-repo R2 prefix (`{repoId}/`) — the unit the delete-purge alarm
+ * job lists and deletes (retained while the Registry reports
+ * `fork_count > 0`, since forks reference keys under it).
+ */
+export const repoPrefix = (repoId) => `${repoId}/`;
+/**
+ * Prefix of all oversize loose objects for a repo: `{repoId}/objects/`.
+ */
+export const objectsPrefix = (repoId) => `${repoId}/objects/`;
+/**
+ * Prefix of all compacted packs for a repo (v1.1): `{repoId}/packs/`.
+ */
+export const packsPrefix = (repoId) => `${repoId}/packs/`;
+/**
+ * Prefix of all in-flight streamed push packs for a repo (reserved):
+ * `{repoId}/incoming/`.
+ */
+export const incomingPrefix = (repoId) => `${repoId}/incoming/`;
+/**
+ * Prefix of all LFS objects for a repo (reserved): `{repoId}/lfs/`.
+ */
+export const lfsPrefix = (repoId) => `${repoId}/lfs/`;
+/**
+ * R2 key of a repo's head snapshot (DESIGN.md §21): a small JSON object
+ * describing the current refs, visibility, and clone bundle, written by
+ * the Repo DO after every mutation commit. Lets the Worker serve
+ * anonymous public reads (advertisement + bundle clones) without waking
+ * the DO. Lives under the repo prefix so purge drains it.
+ */
+export const headKey = (repoId) => `${repoId}/head`;
+//# sourceMappingURL=Keys.js.map

package/lib/Git/Store/Keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Keys.js","sourceRoot":"","sources":["../../../src/Git/Store/Keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,MAAc,EAAE,GAAW,EAAU,EAAE,CAC/D,GAAG,MAAM,YAAY,GAAG,EAAE,CAAC;AAE7B;;;GAGG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,MAAc,EAAE,GAAW,EAAU,EAAE,CAC7D,GAAG,MAAM,eAAe,GAAG,OAAO,CAAC;AAErC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,MAAc,EAAE,QAAgB,EAAU,EAAE,CACpE,GAAG,MAAM,mBAAmB,QAAQ,OAAO,CAAC;AAE9C;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,MAAc,EAAE,QAAgB,EAAU,EAAE,CAC5E,GAAG,MAAM,mBAAmB,QAAQ,WAAW,CAAC;AAElD;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,MAAc,EAAE,MAAc,EAAU,EAAE,CACpE,GAAG,MAAM,aAAa,MAAM,OAAO,CAAC;AAEtC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC;AACxC,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,SAAiB,EAAU,EAAE,CACtD,GAAG,gBAAgB,GAAG,SAAS,EAAE,CAAC;AACpC,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,MAAc,EAAW,EAAE,CACtD,MAAM,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC;AAEtC,8EAA8E;AAC9E,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,MAAc,EAAE,MAAc,EAAU,EAAE,CAClE,YAAY,CAAC,MAAM,CAAC;IAClB,CAAC,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAC5D,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE9B;;;GAGG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,MAAc,EAAE,MAAc,EAAU,EAAE,CAC/D,GAAG,MAAM,QAAQ,MAAM,EAAE,CAAC;AAE5B;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,MAAc,EAAU,EAAE,CAAC,GAAG,MAAM,GAAG,CAAC;AAEnE;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,MAAc,EAAU,EAAE,CAAC,GAAG,MAAM,WAAW,CAAC;AAE9E;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,MAAc,EAAU,EAAE,CAAC,GAAG,MAAM,SAAS,CAAC;AAE1E;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,MAAc,EAAU,EAAE,CAAC,GAAG,MAAM,YAAY,CAAC;AAEhF;;GAEG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,MAAc,EAAU,EAAE,CAAC,GAAG,MAAM,OAAO,CAAC;AAEtE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,MAAc,EAAU,EAAE,CAAC,GAAG,MAAM,OAAO,CAAC"}

package/lib/Git/Store/ObjectStore.d.ts

@@ -0,0 +1,210 @@
+/**
+ * The concrete object store: DO SQLite rows + R2 overflow (DESIGN.md §3.3).
+ *
+ * Implements the git layer's `ObjectSource` contract over the `objects`
+ * table, dispatching byte reads on the `location` column:
+ *
+ * - `'row'`  — the `zdata` BLOB (zlib(content), no loose header),
+ * - `'r2'`   — a streamed R2 `get` of `r2_key` (which may point into a fork
+ *   parent's prefix — immutable, shared),
+ * - `'pack'` — v1.1 compaction; reads die with {@link NotImplementedError}
+ *   until the compaction alarm lands (schema-ready, DESIGN.md §10).
+ *
+ * Plus the push-side surface the protocol layer needs: staged inserts with
+ * the row/R2 placement policy, batched metadata reads, and the
+ * staged-∪-live membership oracle behind the receive-pack connectivity
+ * check (DESIGN.md §3.6 step 5).
+ *
+ * All reads on the `ObjectSource` surface see **live objects only**
+ * (`staged_push IS NULL`); staged rows become visible to fetches only after
+ * the final `transactionSync` flips them live.
+ */
+import type { BlobStoreShape } from "../BlobStore.ts";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import type { ObjectType, Oid } from "../Protocol/ObjectCodec.ts";
+import type { ManifestEntry } from "../Protocol/Store.ts";
+import { StoreError, type ObjectMeta, type ObjectSource } from "../Protocol/Store.ts";
+import type { SqlClient } from "./Sql.ts";
+/**
+ * Compressed-size threshold above which an object's bytes are offloaded to
+ * R2 (`location = 'r2'`) instead of a row BLOB — 1 MiB, a safety margin
+ * under the 2 MB SQLite row cap (DESIGN.md §3.3).
+ */
+export declare const R2_OFFLOAD_THRESHOLD = 1048576;
+/**
+ * Per-object uncompressed size cap for v1 — 64 MiB. Delta application needs
+ * base + result in memory; this keeps worst-case ingest memory bounded.
+ * Enforced by `PackParser` (rejected with `unpack object too large`);
+ * exported here as the storage layer's authoritative constant.
+ */
+export declare const MAX_OBJECT_SIZE = 67108864;
+/**
+ * Window size for coalesced reads out of compacted packs (DESIGN §15
+ * bottleneck 2). Touching one object in a window fetches the whole window,
+ * so a fetch that walks thousands of objects costs a handful of R2 GETs
+ * instead of thousands.
+ */
+export declare const WINDOW_BYTES: number;
+/**
+ * Objects per batch on the emission/closure paths — one SQL statement and
+ * one emitted chunk per batch instead of per object (DESIGN §22).
+ */
+export declare const EMIT_BATCH = 256;
+/**
+ * Rows per multi-row `INSERT` while staging a push: 6 bindings per row, and
+ * Durable Object SQLite allows at most 100 bound parameters per statement
+ * (`MAX_IN_PARAMS`) — 16 rows is 96. Still a 16x cut in statement
+ * executions over one row per statement (see `insertStagedBatch`).
+ */
+export declare const STAGE_INSERT_ROWS = 16;
+/**
+ * Isolate-wide budget for retained pack windows — 32 MiB (8 windows).
+ *
+ * The cache is a module-level LRU shared by every repo instance in the
+ * isolate, not a per-instance map: Durable Object instances of one class
+ * share an isolate and its 128 MiB, so per-instance caches multiply with
+ * the number of active repos. Measured (DESIGN §22.4): a 36 MiB push into a
+ * second repo was rejected with "isolate exceeded its memory limit" while
+ * the first repo's caches were resident. Keys carry the repo id
+ * (`packKey`), so sharing is safe.
+ */
+export declare const WINDOW_CACHE_BYTES: number;
+/**
+ * Windows fetched ahead of the one being emitted (DESIGN §22.4). Blob
+ * storage GETs cost ~150–250 ms each regardless of size, and a 40 MiB
+ * pack is ten of them; fetched one at a time they were half of the
+ * dynamic transfer time. 3 ahead + 1 current stays within the cache.
+ */
+export declare const PACK_LOOKAHEAD = 3;
+declare const NotImplementedError_base: Schema.Class<NotImplementedError, Schema.TaggedStruct<"NotImplementedError", {
+    readonly feature: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised (as a defect, via `Effect.die`) when a v1 code path reaches a
+ * feature the design explicitly defers — currently only reads of
+ * `location = 'pack'` objects, which exist starting with v1.1 compaction.
+ */
+export declare class NotImplementedError extends NotImplementedError_base {
+}
+/**
+ * A pack entry resolved by `PackParser`, ready to stage: the object id, its
+ * numeric type, uncompressed size, and the zlib-compressed bytes to store
+ * (the pack's compressed span verbatim for non-delta entries; a fresh
+ * `deflate(content)` for delta-resolved ones).
+ */
+/**
+ * The live-object predicate (DESIGN §22.14). A push's rows are live the
+ * moment its `pushes` row is committed; the per-row `staged_push` column
+ * is nulled afterwards, off the response path (`flipPush`), and by GC as a
+ * safety net. Reads never wait for that rewrite.
+ */
+export declare const LIVE_OBJECTS = "(staged_push IS NULL OR staged_push IN (SELECT push_id FROM pushes WHERE state = 'committed'))";
+export interface StagedObject {
+    readonly oid: Oid;
+    /**
+     * Set when the bytes already live in a pack in blob storage (a promoted
+     * wire pack, DESIGN §22.5): the row is staged as `location='pack'` with
+     * these coordinates and `zdata` is NOT stored.
+     */
+    readonly pack?: {
+        readonly packId: string;
+        readonly offset: number;
+    } | undefined;
+    /**
+     * Compressed span when `zdata` is not carried (a promoted row whose
+     * bytes live in the pack): the insert must record the real size.
+     */
+    readonly zsize?: number | undefined;
+    readonly type: ObjectType;
+    /** Uncompressed content size in bytes. */
+    readonly size: number;
+    /** `zlib(content)` without the loose header. */
+    readonly zdata: Uint8Array;
+}
+/** Outcome of {@link ObjectStore.insertStaged}. */
+export type InsertOutcome = "inserted" | "exists";
+/**
+ * The full storage surface of a repo's objects: the read-only
+ * `ObjectSource` the protocol layer consumes, plus batched metadata reads,
+ * staged inserts, and the connectivity-check membership oracle.
+ */
+export interface ObjectStore extends ObjectSource {
+    /**
+     * Inflated content for many objects, one statement per ~256 oids — the
+     * closure walk reads whole tree levels this way instead of one SQL
+     * round trip per tree (DESIGN §22). Missing oids are simply absent.
+     */
+    readonly readContentBatch: (oids: ReadonlyArray<Oid>) => Effect.Effect<ReadonlyMap<Oid, Uint8Array>, StoreError>;
+    readonly packEntries: (entries: ReadonlyArray<ManifestEntry>) => Stream.Stream<Uint8Array, StoreError>;
+    /**
+     * Batched metadata for many oids (live objects only). Chunked `IN`
+     * queries, ≤ 100 params each. Missing oids are simply absent from the map.
+     */
+    readonly getMetaBatch: (oids: ReadonlyArray<Oid>) => Effect.Effect<ReadonlyMap<Oid, ObjectMeta>, StoreError>;
+    /**
+     * Stages one resolved object for `pushId` (DESIGN.md §3.6 step 4).
+     *
+     * Placement policy: compressed size > 1 MiB ⇒ the bytes are written to R2
+     * **first** (`{repoId}/objects/{oid}`, content-addressed so re-runs are
+     * idempotent), then the metadata row; otherwise the row carries the BLOB.
+     *
+     * Existing oids are skipped (idempotent re-push). A row left staged by a
+     * **different** (crashed) push is adopted — re-stamped with this `pushId`
+     * so the connectivity check and the final live-flip see it.
+     */
+    readonly insertStaged: (pushId: string, object: StagedObject) => Effect.Effect<InsertOutcome, StoreError>;
+    /**
+     * Batched sibling of {@link ObjectStore.insertStaged} — the ingest hot
+     * path (DESIGN.md §16.6).
+     *
+     * Staging objects one at a time costs two statements each (an existence
+     * probe and an insert), so a 13.7k-object push ran ~27k statements and
+     * ~13.7k transactions inside a single-threaded Durable Object. This
+     * inserts a whole batch in **one** `transactionSync` with
+     * `INSERT OR IGNORE` (no probe), then adopts any rows left staged by a
+     * crashed push with one chunked `UPDATE`.
+     *
+     * Oversize objects (> 1 MiB compressed) still go through the per-object
+     * path, since each needs its own R2 write first.
+     */
+    readonly insertStagedBatch: (pushId: string, objects: ReadonlyArray<StagedObject>) => Effect.Effect<void, StoreError>;
+    /** A live object's type and content for thin-delta resolution, or `undefined`. */
+    /** Read only live objects or objects staged by this push, with a caller-selected size cap. */
+    readonly readPrepared: (pushId: string, oid: Oid, maxBytes: number) => Effect.Effect<{
+        readonly type: ObjectType;
+        readonly content: Uint8Array;
+    } | undefined, StoreError>;
+    readonly readBase: (oid: Oid) => Effect.Effect<{
+        readonly type: ObjectType;
+        readonly content: Uint8Array;
+    } | undefined, StoreError>;
+    /**
+     * The connectivity-check membership oracle: returns the subset of `oids`
+     * that exist in **neither** the live store **nor** this push's staged
+     * rows. An empty result means every referenced object is present and the
+     * push is safe to commit.
+     */
+    readonly missingObjects: (oids: ReadonlyArray<Oid>, pushId: string) => Effect.Effect<ReadonlyArray<Oid>, StoreError>;
+}
+/**
+ * Dependencies of {@link makeObjectStore}. Plain values (not Layers) so
+ * `RepoObject.ts` wires the store inside its inner per-instance effect.
+ */
+export interface ObjectStoreOptions {
+    /** The repo DO's SQL client (see `makeSqlClient`). */
+    readonly sql: SqlClient;
+    /** The swappable bulk-byte store (R2 by default — see `BlobStore.ts`). */
+    readonly blobs: BlobStoreShape;
+    /** The repo's ULID — the R2 key prefix (DESIGN.md §3.2). */
+    readonly repoId: string;
+}
+/**
+ * Creates the {@link ObjectStore} for one repo. Plain factory — no Layers —
+ * so `RepoObject.ts` can wire it in its inner effect with the ambient
+ * `state`/bucket handles.
+ */
+export declare const makeObjectStore: (options: ObjectStoreOptions) => ObjectStore;
+export {};
+//# sourceMappingURL=ObjectStore.d.ts.map

package/lib/Git/Store/ObjectStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ObjectStore.d.ts","sourceRoot":"","sources":["../../../src/Git/Store/ObjectStore.ts"],"names":[],"mappings":"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"}