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

package/lib/Git/RepoObject.d.ts

@@ -0,0 +1,804 @@
+/**
+ * The per-repo Durable Object (DESIGN.md §2, §3.4, §3.6, §8).
+ *
+ * One DO per repo, addressed by `getByName(repoId)` (a ULID — never
+ * `owner/name`, so renames never move data). The DO owns refs, the object
+ * index and loose bytes, tokens, the commit graph, push staging, and the
+ * alarm jobs (import / fork / delete-purge / staging-GC). It runs the git
+ * v0 wire protocol in its `fetch` handler — advertisement, upload-pack,
+ * receive-pack — because every byte those need lives in this DO's SQLite.
+ *
+ * NOTE: the protocol *choreography* (advertisement builder, request
+ * parsers, pack writer/parser) is implemented in this file against the
+ * pure codec primitives in `src/Git/Protocol/` (`Pkt`, `Sideband`, `ObjectCodec`,
+ * `Delta`, `Zlib`, `Store`). DESIGN.md places these in
+ * `src/git/{Advertise,UploadPack,ReceivePack,PackParser,PackWriter}.ts`;
+ * they live here (exported) until the git-layer split lands — moving them
+ * is a mechanical extraction.
+ *
+ * ### Wire endpoints
+ * The Worker proxies these untouched to `stub.fetch`:
+ * **Example:** Routes served by this DO's fetch handler
+ * ```
+ * GET  /:owner/:repo[.git]/info/refs?service=git-(upload|receive)-pack
+ * POST /:owner/:repo[.git]/git-upload-pack
+ * POST /:owner/:repo[.git]/git-receive-pack
+ * ```
+ */
+import * as Cloudflare from "../Cloudflare/index.ts";
+import type { HttpEffect } from "../Http.ts";
+import { RuntimeContext } from "../RuntimeContext.ts";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Semaphore from "effect/Semaphore";
+import * as Stream from "effect/Stream";
+import { BranchMissing, MergeConflict, NoMergeBase, NothingToMerge, ObjectNotFound, PullExists, PullNotFound, PullStateConflict, ReadOnlyRepo, RefConflict, RefNotFound, RepoNotFound, ValidationError, WrongObjectType, type RepoStatus } from "./Api.ts";
+import type { RandomAccess } from "./Protocol/PackParser.ts";
+import { ObjectType, type ObjectTypeName, type Oid } from "./Protocol/ObjectCodec.ts";
+import { type PktLine } from "./Protocol/Pkt.ts";
+import { StoreError, type ManifestEntry, type ObjectSource } from "./Protocol/Store.ts";
+import { type DiffEntryData } from "./Protocol/TreeDiff.ts";
+import { type ImportSource } from "./Jobs/Import.ts";
+import { type SnapshotChunk } from "./Jobs/Fork.ts";
+import type { StreamingFeeder } from "./Store/StreamingSource.ts";
+import { Hasher, type HasherShape } from "./Hasher/Hasher.ts";
+import { BlobStore, type BlobStoreShape } from "./BlobStore.ts";
+import { RegistryStore } from "./RegistryObject.ts";
+import { type ObjectStore } from "./Store/ObjectStore.ts";
+/**
+ * Pushes up to this size are ingested straight from memory; larger ones are
+ * parked in R2 and parsed from there (DESIGN.md §3.6). A **buffering
+ * threshold, not a limit** — a push larger than this is no longer rejected.
+ *
+ * The spill threshold of the streaming receive (`receiveWireBody`): bodies
+ * up to this size are buffered and parsed from memory (the fast path, at
+ * 50 MiB the bound v1 validated for a 128 MB isolate); larger bodies are
+ * never materialized — they stream into an R2 multipart upload as they
+ * arrive and are parsed back through bounded windows.
+ *
+ * Measured on the 38 MiB alchemy-repo push: ~20 s in memory, ~37 s through
+ * R2. The R2 path costs about 2x, and is unbounded — the full 67 MiB
+ * alchemy history (44k objects) pushed in 92 s.
+ */
+export declare const MAX_PACK_BYTES: number;
+/** Objects staged per SQL transaction during ingest (DESIGN.md §16.6). */
+/** Bytes per hasher part — the spill part size, so a part is one R2 part (DESIGN §22.7). */
+export declare const HASH_PART_BYTES: number;
+/** Hasher calls in flight per push (DESIGN §22.8). */
+export declare const HASH_CONCURRENCY = 8;
+export declare const STAGE_BATCH_OBJECTS = 2048;
+/** Byte budget per staging batch, so a batch of large blobs stays bounded. */
+export declare const STAGE_BATCH_BYTES: number;
+export { MAX_DIFF_FILES, MAX_DIFF_TREE_READS } from "./Protocol/TreeDiff.ts";
+/** Max commits popped by the merge-base paint walk. */
+export declare const MAX_COMPARE_WALK = 10000;
+/** Max commits returned in a Comparison's `commits` array. */
+export declare const MAX_COMPARE_COMMITS = 250;
+/**
+ * Max commits popped by the PR live-field walk (`getPull`). Saturation
+ * makes the numeric detail fields `null` (reason `"unknown"`); merge still
+ * works because {@link MAX_PULL_MERGE_WALK} gives the merge path a deeper
+ * budget.
+ */
+export declare const MAX_PULL_WALK = 5000;
+/** Deeper walk budget for `mergePull` (needs only reachability + one base). */
+export declare const MAX_PULL_MERGE_WALK = 50000;
+/** Conflicting paths reported on a `MergeConflict` (the set may be larger). */
+export declare const MAX_CONFLICT_PATHS = 20;
+/** Agent string advertised on the wire. */
+export declare const GIT_AGENT = "git-service/1";
+/** How long a push waits for ingest memory before answering 503. */
+export declare const PUSH_WAIT_TIMEOUT = "30 seconds";
+/**
+ * Memory the Repo DO lends to concurrent push ingests, in MiB — one
+ * permit per MiB (DESIGN.md §2.1).
+ *
+ * The semaphore exists for MEMORY, not correctness: a DO is
+ * single-threaded, but its input gate is only closed across *storage*
+ * awaits, and receive-pack awaits the network and blob storage — so two
+ * pushes genuinely interleave. Correctness across that interleave is
+ * already handled by data scoping (`staged_push = pushId`, and every
+ * read filtering `staged_push IS NULL`) plus a synchronous
+ * `transactionSync` finalize. What is left is that two concurrent
+ * 50 MiB buffers would exhaust the 128 MB isolate.
+ *
+ * Bounding the resource rather than the count is what lets pushes to
+ * different branches proceed together: a normal push is kilobytes and
+ * takes one permit, so it no longer queues behind a large one.
+ */
+export declare const PUSH_MEMORY_BUDGET_MB = 64;
+/**
+ * The push-admission semaphore, ONE per isolate (DESIGN §21.2, §22.4). DO
+ * instances of a class share an isolate, so a per-instance gate would let
+ * N repos each admit a full budget's worth of concurrent pushes.
+ */
+export declare const isolatePushGate: Effect.Effect<Semaphore.Semaphore>;
+/**
+ * Permits a push must reserve: its buffered ceiling in MiB. A body
+ * larger than {@link MAX_PACK_BYTES} spills to blob storage instead of
+ * growing in memory, so that is the cap; an absent `content-length`
+ * (chunked upload) is charged the same worst case.
+ */
+export declare const pushPermitsFor: (contentLength: number | undefined) => number;
+/** How long crashed push staging survives before the GC alarm reaps it. */
+export declare const STAGING_TTL_MS: number;
+/** The realm sent on wire 401s. */
+export declare const WWW_AUTHENTICATE: 'Basic realm="git-service"';
+/**
+ * Worker↔DO headers for the clone-bundle splice (DESIGN.md §11): the DO
+ * answers an eligible clone with these *instead of* the pack, and the
+ * Worker streams the named R2 object to the client. Only
+ * {@link BUNDLE_HASH_HEADER} is kept on the client-visible response, as
+ * observable proof the fast path served the clone.
+ */
+export declare const BUNDLE_KEY_HEADER: "x-git-bundle-key";
+export declare const BUNDLE_HASH_HEADER: "x-git-bundle";
+export declare const BUNDLE_COUNT_HEADER: "x-git-bundle-count";
+export declare const BUNDLE_SIDEBAND_HEADER: "x-git-bundle-sideband";
+declare const PackIngestError_base: Schema.Class<PackIngestError, Schema.TaggedStruct<"PackIngestError", {
+    readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A push pack failed to ingest (malformed, oversize, checksum mismatch,
+ * missing thin base, delta error). Reported in-band as `unpack <reason>` +
+ * per-ref `ng` — never as an HTTP error.
+ */
+export declare class PackIngestError extends PackIngestError_base {
+}
+declare const WireProtocolError_base: Schema.Class<WireProtocolError, Schema.TaggedStruct<"WireProtocolError", {
+    readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A syntactically valid request that the v0 grammar does not allow
+ * (missing wants, malformed command lines, unsupported deepen flavors).
+ * Answered with an `ERR` pkt.
+ */
+export declare class WireProtocolError extends WireProtocolError_base {
+}
+/** Repo metadata as stored in the `config` table. */
+export interface RepoMetaData {
+    readonly repoId: string;
+    readonly owner: string;
+    readonly name: string;
+    readonly defaultBranch: string;
+    readonly description: string | null;
+    readonly readOnly: boolean;
+    /** Anyone can read/clone without a token (GitHub public-repo model). */
+    readonly public: boolean;
+    readonly forkOf: string | null;
+    readonly status: RepoStatus;
+    readonly createdAt: number;
+    /** Object storage breakdown (DESIGN.md §12.1). */
+    readonly objects: ObjectStatsData;
+    /** Server-side timing of the last push (DESIGN.md §19 phase 0). */
+    readonly lastPush: PushStatsData | null;
+}
+/** `beginPush` input: the parsed ref commands (DESIGN §22.10). */
+export interface BeginPushInput {
+    readonly commands: ReadonlyArray<RefCommand>;
+}
+/** `beginPush` outcome. `denied` is reported per ref (`ng <ref> <reason>`). */
+export type BeginPushResult = {
+    readonly _tag: "ok";
+    readonly pushId: string;
+} | {
+    readonly _tag: "denied";
+    readonly reason: string;
+};
+/** One ref's outcome in a push report. */
+export interface PushRefResult {
+    readonly ref: string;
+    readonly ok: boolean;
+    readonly reason?: string | undefined;
+}
+/** `commitPush` input: what the Worker-side ingest learned (DESIGN §22.10). */
+export interface CommitPushInput {
+    readonly pushId: string;
+    readonly commands: ReadonlyArray<RefCommand>;
+    readonly atomic: boolean;
+    readonly commits: ReadonlyArray<StagedCommitInfo>;
+    readonly referenced: ReadonlyArray<Oid>;
+    readonly referencedParents: ReadonlyArray<Oid>;
+    /** Rows staged as references into the wire pack (it must then outlive the push). */
+    readonly promoted: number;
+    readonly stats: {
+        readonly objects: number;
+        readonly bytes: number;
+        readonly ingestMs: number;
+        readonly stageMs: number;
+        readonly phases: Record<string, number> | undefined;
+    };
+}
+/** `commitPush` outcome: the `unpack` line and per-ref results. */
+export interface CommitPushResult {
+    readonly unpack: string;
+    readonly results: ReadonlyArray<PushRefResult>;
+}
+/** Server-side push timing — see the REST `PushStats` schema. */
+export interface PushStatsData {
+    readonly objects: number;
+    readonly bytes: number;
+    readonly ingestMs: number;
+    readonly stageMs: number;
+    readonly connectivityMs: number;
+    readonly finalizeMs: number;
+    readonly totalMs: number;
+    /** Ingest split by phase (ms) — see the REST `PushStats.phases` caveat. */
+    readonly phases?: Record<string, number> | undefined;
+}
+/** Where a repo's objects live — see the REST `ObjectStats` schema. */
+export interface ObjectStatsData {
+    /** Blobs still in SQLite rows, awaiting compaction into an R2 pack. */
+    readonly loose: number;
+    /** Commits, trees and tags: always SQLite rows (never packed). */
+    readonly resident: number;
+    /** Blobs in R2 packs. */
+    readonly packed: number;
+    readonly r2: number;
+    readonly bytes: number;
+}
+/** Patch accepted by {@link GitRepoShape.updateRepoMeta}. */
+export interface RepoMetaPatch {
+    readonly description?: string | null | undefined;
+    /** Must resolve to an existing branch. */
+    readonly defaultBranch?: string | undefined;
+    readonly readOnly?: boolean | undefined;
+    /** Anyone can read/clone without a token when `true`. */
+    readonly public?: boolean | undefined;
+}
+/** One ref (peeled target present for annotated tags). */
+export interface RefData {
+    readonly name: string;
+    readonly oid: string;
+    readonly peeled?: string | undefined;
+}
+/** Result of {@link GitRepoShape.listRefs}. */
+export interface RefsPage {
+    /** The default branch's full ref name, `null` on an unborn repo. */
+    readonly head: string | null;
+    readonly refs: ReadonlyArray<RefData>;
+}
+/** Input of {@link GitRepoShape.initRepo} (also fork/import bootstrap). */
+export interface InitRepoInput {
+    readonly repoId: string;
+    readonly owner: string;
+    readonly name: string;
+    readonly defaultBranch: string;
+    readonly description: string | null;
+    readonly readOnly: boolean;
+    /** Anyone can read/clone without a token when `true`. */
+    readonly public: boolean;
+    readonly forkOf: string | null;
+}
+/** Result of init/fork/import bootstrap: the meta + a bootstrap token. */
+export interface InitRepoResult {
+    readonly meta: RepoMetaData;
+}
+/** Input of {@link GitRepoShape.updateRef}. */
+export interface UpdateRefInput {
+    readonly name: string;
+    readonly newOid: string;
+    /**
+     * CAS token: `string` = must currently equal; `null` = must not exist;
+     * absent = unconditional.
+     */
+    readonly expectedOid?: string | null | undefined;
+}
+/** Input of {@link GitRepoShape.removeRef}. */
+export interface RemoveRefInput {
+    readonly name: string;
+    readonly expectedOid?: string | undefined;
+}
+/** Input of {@link GitRepoShape.readObject}. */
+export interface ReadObjectInput {
+    readonly oid: string;
+    /** When set, a different actual type fails with `WrongObjectType`. */
+    readonly expect?: ObjectTypeName | undefined;
+}
+/** A fully-read object (content inflated, ≤ 64 MiB by the ingest cap). */
+export interface ObjectData {
+    readonly oid: string;
+    readonly type: ObjectTypeName;
+    readonly size: number;
+    readonly content: Uint8Array;
+}
+/** One commit for the REST read surface. */
+export interface CommitData {
+    readonly oid: string;
+    readonly tree: string;
+    readonly parents: ReadonlyArray<string>;
+    readonly author: SignatureData;
+    readonly committer: SignatureData;
+    readonly message: string;
+}
+/** An author/committer signature. */
+export interface SignatureData {
+    readonly name: string;
+    readonly email: string;
+    readonly date: number;
+    readonly tz: string;
+}
+/** Input of {@link GitRepoShape.readCommitLog}. */
+export interface CommitLogInput {
+    /** Refname or 40-hex oid; default = HEAD (the default branch). */
+    readonly ref?: string | undefined;
+    readonly cursor?: string | undefined;
+    readonly limit?: number | undefined;
+}
+/** One page of {@link GitRepoShape.readCommitLog}. */
+export interface CommitLogPage {
+    readonly items: ReadonlyArray<CommitData>;
+    readonly nextCursor: string | null;
+    readonly hasMore: boolean;
+}
+export type { DiffEntryData } from "./Protocol/TreeDiff.ts";
+/** Result of {@link GitRepoShape.readCommitDiff}. */
+export interface CommitDiffData {
+    readonly oid: string;
+    readonly parent: string | null;
+    readonly files: ReadonlyArray<DiffEntryData>;
+    readonly truncated: boolean;
+}
+/** Input of {@link GitRepoShape.compareCommits}. */
+export interface CompareInput {
+    /** Refname or 40-hex oid. */
+    readonly base: string;
+    readonly head: string;
+}
+/** Result of {@link GitRepoShape.compareCommits}. */
+export interface CompareData {
+    readonly base: string;
+    readonly head: string;
+    readonly mergeBase: string;
+    readonly aheadBy: number;
+    readonly behindBy: number;
+    readonly commits: ReadonlyArray<CommitData>;
+    readonly commitsTruncated: boolean;
+    readonly files: ReadonlyArray<DiffEntryData>;
+    readonly filesTruncated: boolean;
+}
+/** Input of {@link GitRepoShape.readFileAtPath}. */
+export interface ReadFileInput {
+    /** Refname or 40-hex oid; default = HEAD. */
+    readonly ref?: string | undefined;
+    /** Slash-separated path inside the tree. */
+    readonly path: string;
+}
+/** A file read via tree walk. */
+export interface FileData {
+    readonly oid: string;
+    /** Octal mode string, e.g. `100644`. */
+    readonly mode: string;
+    readonly size: number;
+    readonly content: Uint8Array;
+}
+/** One pull-request row (see the REST `Pull` schema). */
+export interface PullData {
+    readonly number: number;
+    readonly title: string;
+    readonly body: string | null;
+    /** Full base ref name, e.g. `refs/heads/main`. */
+    readonly baseRef: string;
+    /** Full head ref name, e.g. `refs/heads/feature`. */
+    readonly headRef: string;
+    readonly state: "open" | "closed" | "merged";
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    readonly mergedAt: number | null;
+    /** FF: the head tip; the merge commit otherwise. Set iff state=merged. */
+    readonly mergeCommit: string | null;
+}
+/** Detail = row + live compare fields (`null` = uncomputable, see REST docs). */
+export interface PullDetailData extends PullData {
+    readonly baseOid: string | null;
+    readonly headOid: string | null;
+    readonly mergeBase: string | null;
+    readonly aheadBy: number | null;
+    readonly behindBy: number | null;
+    readonly mergeable: boolean | null;
+    readonly mergeableReason: "ff" | "merge-commit" | "conflict" | "up-to-date" | "unknown" | null;
+}
+/** Input of {@link GitRepoShape.createPull}. */
+export interface CreatePullInput {
+    readonly title: string;
+    readonly body?: string | undefined;
+    /** Short or full branch name; normalized to `refs/heads/…` here. */
+    readonly base: string;
+    readonly head: string;
+}
+/** Input of {@link GitRepoShape.listPulls}. */
+export interface ListPullsInput {
+    readonly state?: "open" | "closed" | "merged" | "all" | undefined;
+    /** Last-seen PR number as a string (keyset pagination, newest first). */
+    readonly cursor?: string | undefined;
+    /** Default 20, max 100. */
+    readonly limit?: number | undefined;
+}
+/** One page of {@link GitRepoShape.listPulls}. */
+export interface PullsPage {
+    readonly items: ReadonlyArray<PullData>;
+    readonly nextCursor: string | null;
+    readonly hasMore: boolean;
+}
+/** Input of {@link GitRepoShape.updatePull}. */
+export interface UpdatePullInput {
+    readonly number: number;
+    readonly title?: string | undefined;
+    /** `null` clears the body. */
+    readonly body?: string | null | undefined;
+    readonly state?: "open" | "closed" | undefined;
+}
+/** Input of {@link GitRepoShape.mergePull}. */
+export interface MergePullInput {
+    readonly number: number;
+    /** Merge-commit message; ignored on fast-forward. */
+    readonly message?: string | undefined;
+    /** Race guard: fail RefConflict when the head tip moved since inspection. */
+    readonly expectedHeadOid?: string | undefined;
+    /** Race guard for application inspection of the base branch. */
+    readonly expectedBaseOid?: string | undefined;
+}
+/** Result of {@link GitRepoShape.mergePull}. */
+export interface MergePullResult {
+    readonly method: "ff" | "merge-commit";
+    /** The oid the base ref now points at. */
+    readonly oid: string;
+    readonly pull: PullData;
+}
+/** Input of {@link GitRepoShape.startImport}. */
+export interface StartImportInput extends InitRepoInput {
+    readonly source: ImportSource;
+}
+/** Input of {@link GitRepoShape.startFork}. */
+export interface StartForkInput extends InitRepoInput {
+    readonly parentRepoId: string;
+}
+/** The common auth+repo error union of most RPC methods. */
+export type RepoAuthError = RepoNotFound | StoreError;
+/**
+ * The Repo DO's typed RPC surface. All methods are `RuntimeContext`-colored
+ * (callable only through a stub / inside the deployed Worker). Note: no
+ * method may be named `delete` (Cloudflare stub proxy reserves it).
+ */
+export interface GitRepoShape {
+    /** Seeds config (repo create). */
+    readonly initRepo: (input: InitRepoInput) => Effect.Effect<InitRepoResult, StoreError, RuntimeContext>;
+    /** Seeds config with `status: importing`, arms the import alarm job. */
+    readonly startImport: (input: StartImportInput) => Effect.Effect<InitRepoResult, StoreError, RuntimeContext>;
+    /** Seeds config with `status: forking`, arms the fork alarm job. */
+    readonly startFork: (input: StartForkInput) => Effect.Effect<InitRepoResult, StoreError, RuntimeContext>;
+    /** Flips `status: deleting` and arms the purge alarm job. */
+    /**
+     * Arms a compaction run now (admin): loose object bytes are moved into an
+     * immutable R2 pack by the alarm (DESIGN.md §12.1). Normally armed
+     * automatically by the post-push size check.
+     */
+    readonly startCompact: () => Effect.Effect<void, RepoAuthError, RuntimeContext>;
+    readonly startPurge: () => Effect.Effect<void, RepoAuthError, RuntimeContext>;
+    readonly getRepoMeta: () => Effect.Effect<RepoMetaData, RepoAuthError, RuntimeContext>;
+    /** Repo metadata for the Worker's own bookkeeping. */
+    readonly readMeta: () => Effect.Effect<RepoMetaData, RepoNotFound | StoreError, RuntimeContext>;
+    readonly updateRepoMeta: (patch: RepoMetaPatch) => Effect.Effect<RepoMetaData, RepoAuthError | RefNotFound, RuntimeContext>;
+    readonly listRefs: (prefix?: string | undefined) => Effect.Effect<RefsPage, RepoAuthError, RuntimeContext>;
+    readonly getRef: (name: string) => Effect.Effect<RefData, RepoAuthError | RefNotFound, RuntimeContext>;
+    readonly updateRef: (input: UpdateRefInput) => Effect.Effect<RefData, RepoAuthError | RefConflict | ObjectNotFound | ReadOnlyRepo, RuntimeContext>;
+    readonly removeRef: (input: RemoveRefInput) => Effect.Effect<void, RepoAuthError | RefNotFound | RefConflict | ReadOnlyRepo, RuntimeContext>;
+    readonly readObject: (input: ReadObjectInput) => Effect.Effect<ObjectData, RepoAuthError | ObjectNotFound | WrongObjectType, RuntimeContext>;
+    readonly readCommitLog: (input: CommitLogInput) => Effect.Effect<CommitLogPage, RepoAuthError | RefNotFound, RuntimeContext>;
+    /**
+     * The changed-file list of a commit vs its FIRST parent (empty tree for
+     * a root commit) — see the REST `diff` endpoint.
+     */
+    readonly readCommitDiff: (input: {
+        readonly oid: string;
+    }) => Effect.Effect<CommitDiffData, RepoAuthError | ObjectNotFound | WrongObjectType, RuntimeContext>;
+    /**
+     * Three-dot comparison of two revisions: merge base, ahead/behind
+     * counts, head-side commits, and the mergeBase..head file diff — see
+     * the REST `compare` endpoint.
+     */
+    readonly compareCommits: (input: CompareInput) => Effect.Effect<CompareData, RepoAuthError | RefNotFound | ObjectNotFound | WrongObjectType | NoMergeBase, RuntimeContext>;
+    readonly readFileAtPath: (input: ReadFileInput) => Effect.Effect<FileData, RepoAuthError | RefNotFound | ObjectNotFound, RuntimeContext>;
+    /** Opens a pull request (same-repo branches, `write` scope). */
+    readonly createPull: (input: CreatePullInput) => Effect.Effect<PullData, RepoAuthError | BranchMissing | PullExists | ValidationError, RuntimeContext>;
+    /** Lists PRs newest-first with keyset pagination (`read` scope). */
+    readonly listPulls: (input: ListPullsInput) => Effect.Effect<PullsPage, RepoAuthError, RuntimeContext>;
+    /** Reads one PR with live compare fields recomputed from current tips. */
+    readonly getPull: (number: number) => Effect.Effect<PullDetailData, RepoAuthError | PullNotFound, RuntimeContext>;
+    /** Patches title/body, or closes/reopens via `state` (`write` scope). */
+    readonly updatePull: (input: UpdatePullInput) => Effect.Effect<PullData, RepoAuthError | PullNotFound | PullStateConflict, RuntimeContext>;
+    /**
+     * Merges an open PR: fast-forward when possible, else a two-parent merge
+     * commit iff the three-way tree merge is trivial (no path changed on both
+     * sides vs the merge base). Conflicts are a typed 409 — the server never
+     * writes conflict markers.
+     */
+    readonly mergePull: (input: MergePullInput) => Effect.Effect<MergePullResult, RepoAuthError | PullNotFound | PullStateConflict | BranchMissing | NothingToMerge | MergeConflict | RefConflict | ReadOnlyRepo, RuntimeContext>;
+    /**
+     * Streams a row snapshot for a fork (DESIGN.md §2.3 Fork). Internal —
+     * called only by a sibling Repo DO's fork alarm job; never routed from
+     * the Worker.
+     */
+    readonly snapshotRows: () => Stream.Stream<SnapshotChunk, StoreError>;
+    /**
+     * Push, phase 1 (DESIGN §22.10): authorize the parsed commands and open
+     * a staging push. The Worker then streams the pack through the hasher
+     * fan-out and the spill, staging rows with `stagePush`.
+     */
+    readonly beginPush: (input: BeginPushInput) => Effect.Effect<BeginPushResult, RepoNotFound | StoreError, RuntimeContext>;
+    /** Push, phase 2: stage one batch of rows (see `PushWire.ts`). */
+    readonly stagePush: (pushId: string, batch: Uint8Array) => Effect.Effect<void, RepoNotFound | StoreError, RuntimeContext>;
+    /** Abort uncommitted staging; false means committed data must be retained. */
+    readonly abortPush: (pushId: string, packIds?: ReadonlyArray<string>) => Effect.Effect<boolean, RepoNotFound | StoreError, RuntimeContext>;
+    /** Validate connectivity without moving refs. Commit repeats this check. */
+    readonly validatePush: (input: CommitPushInput) => Effect.Effect<void, RepoNotFound | StoreError, RuntimeContext>;
+    /** Read from this push's staging area and the live store only. */
+    readonly readPreparedObject: (pushId: string, oid: Oid, maxBytes: number) => Effect.Effect<{
+        readonly type: ObjectType;
+        readonly content: Uint8Array;
+    } | undefined, RepoNotFound | StoreError, RuntimeContext>;
+    /** A live object for thin-delta base resolution, or `undefined`. */
+    readonly readPushBase: (oid: Oid) => Effect.Effect<{
+        readonly type: ObjectType;
+        readonly content: Uint8Array;
+    } | undefined, RepoNotFound | StoreError, RuntimeContext>;
+    /**
+     * Push, phase 3: connectivity over the staged rows, the commit-graph
+     * rows, the transactional ref CAS, and post-commit bookkeeping.
+     */
+    readonly commitPush: (input: CommitPushInput) => Effect.Effect<CommitPushResult, RepoNotFound | StoreError, RuntimeContext>;
+    /** The git wire protocol (info/refs, upload-pack). */
+    readonly fetch: HttpEffect<Cloudflare.DurableObjectState | RuntimeContext>;
+    /** Alarm job dispatcher (import / fork / purge / gc). */
+    readonly alarm: (info?: Cloudflare.AlarmInvocationInfo) => Effect.Effect<void, never, RuntimeContext>;
+}
+/** Upload-pack capability list (DESIGN.md §4). */
+export declare const uploadCapabilities: (defaultBranch: string) => string;
+/** Receive-pack capability list (DESIGN.md §4). */
+export declare const receiveCapabilities: () => string;
+/** The two smart-HTTP services. */
+export type GitService = "git-upload-pack" | "git-receive-pack";
+/**
+ * Builds the v0 `info/refs` advertisement (with `# service=` prelude):
+ * HEAD first with the capability line, refs sorted, annotated tags peeled
+ * (`^{}` lines), zero-id `capabilities^{}` on an empty repo.
+ */
+export declare const buildAdvertisement: (options: {
+    readonly service: GitService;
+    readonly defaultBranch: string;
+    /** Sorted by name; peeled targets included for annotated tags. */
+    readonly refs: ReadonlyArray<RefData>;
+}) => Uint8Array;
+/** A parsed v0 upload-pack request. */
+export interface UploadPackRequest {
+    readonly wants: ReadonlyArray<Oid>;
+    readonly haves: ReadonlyArray<Oid>;
+    readonly done: boolean;
+    readonly depth: number | undefined;
+    readonly clientShallow: ReadonlyArray<Oid>;
+    readonly capabilities: ReadonlySet<string>;
+}
+/**
+ * Parses a v0 upload-pack POST body (already gunzipped) into wants /
+ * shallow / deepen / haves / done. Rejects `deepen-since` / `deepen-not` /
+ * `filter` (not advertised) with {@link WireProtocolError}.
+ */
+export declare const parseUploadPackRequest: (pkts: ReadonlyArray<PktLine>) => Effect.Effect<UploadPackRequest, WireProtocolError>;
+/** One receive-pack command (`<old> <new> <refname>`). */
+export interface RefCommand {
+    readonly oldOid: Oid;
+    readonly newOid: Oid;
+    readonly ref: string;
+}
+/** A parsed v0 receive-pack request head. */
+export interface ReceivePackRequest {
+    readonly commands: ReadonlyArray<RefCommand>;
+    readonly capabilities: ReadonlySet<string>;
+    /** Byte offset of the pack within the body (== length when no pack). */
+    readonly packStart: number;
+    /** True for git's bare-flush `http.postBuffer` probe. */
+    readonly probe: boolean;
+}
+/**
+ * Parses a v0 receive-pack POST body (already gunzipped): command
+ * pkt-lines (first carries `\0caps`) up to the flush, leaving the raw pack
+ * bytes at `packStart`. Detects the empty-flush probe (DESIGN.md §2.3
+ * Push step 2).
+ */
+export declare const parseReceivePackRequest: (body: Uint8Array) => Effect.Effect<ReceivePackRequest, WireProtocolError>;
+/** The 12-byte pack header: `PACK`, version 2, entry count. */
+export declare const packHeader: (count: number) => Uint8Array;
+/**
+ * The §3.5 no-delta pack emitter: header + per-entry
+ * `varint(type,size) + stored zdata` (verbatim — zero compression CPU) +
+ * incremental SHA-1 trailer. Constant memory; the manifest is already
+ * materialized so the count is known upfront.
+ */
+export declare const packStream: (entries: ReadonlyArray<ManifestEntry>, objects: ObjectSource) => Stream.Stream<Uint8Array, StoreError>;
+/**
+ * The entry stream alone — no header, no trailer. Because entries are
+ * stored non-delta (`varint(type,size) + zdata`), entry streams from
+ * different sources concatenate into one valid pack under a rewritten
+ * header and a fresh trailer. That is what lets a clone be served as
+ * "bundle bytes + a small delta" (DESIGN.md §21.2), and it is the same
+ * property geometric pack merging relies on.
+ */
+export declare const packEntryStream: (entries: ReadonlyArray<ManifestEntry>, objects: ObjectSource) => Stream.Stream<Uint8Array, StoreError>;
+/** A commit staged by an ingest, with what the commit graph needs. */
+export interface StagedCommitInfo {
+    readonly oid: Oid;
+    readonly tree: Oid;
+    readonly parents: ReadonlyArray<Oid>;
+    readonly commitTime: number;
+}
+/** The result of a successful pack ingest. */
+export interface IngestResult {
+    /** Objects in the pack (including already-existing re-pushed ones). */
+    readonly objectCount: number;
+    /** SQL staging time, when measured by the streaming ingest path. */
+    readonly stageMs?: number | undefined;
+    /** Per-phase CPU split of ingest (ms) — see `PackParser` `phases`. */
+    readonly phases?: Record<string, number> | undefined;
+    /** Objects staged as references into a promoted wire pack (DESIGN §22.5). */
+    readonly promoted?: number | undefined;
+    /** The completed spilled object's key, when the body spilled (DESIGN §22.10). */
+    readonly parkedKey?: string | undefined;
+    /** The resolved pack's key — delta-resolved blobs, promoted (DESIGN §22.13). */
+    readonly resolvedKey?: string | undefined;
+    /** The pack's trailer checksum (hex). */
+    readonly packSha: string;
+    /** Staged commits (commit-graph rows are inserted at finalize). */
+    readonly commits: ReadonlyArray<StagedCommitInfo>;
+    /** Oids referenced by staged trees/tags + commit trees (hard edges). */
+    readonly referenced: ReadonlyArray<Oid>;
+    /** Oids referenced as commit parents (soft under shallow import). */
+    readonly referencedParents: ReadonlyArray<Oid>;
+}
+/**
+ * The store surface ingest needs (DESIGN §22.10): staging rows and thin
+ * delta bases. The Repo DO satisfies it directly; the Worker satisfies it
+ * over RPC so the pack never enters the Durable Object.
+ */
+export interface IngestStore {
+    readonly insertStagedBatch: ObjectStore["insertStagedBatch"];
+    /** Awaits staging that `insertStagedBatch` may have left in flight. */
+    readonly settle?: Effect.Effect<void, StoreError> | undefined;
+    /** A live base object for a thin delta, or `undefined` when absent. */
+    readonly readBase: (oid: Oid) => Effect.Effect<{
+        readonly type: ObjectType;
+        readonly content: Uint8Array;
+    } | undefined, StoreError>;
+}
+/** An {@link IngestStore} over a full {@link ObjectStore}. */
+export declare const ingestStoreOf: (store: ObjectStore) => IngestStore;
+/** Options of {@link ingestPack}. */
+export interface IngestOptions {
+    readonly store: IngestStore;
+    readonly pushId: string;
+    /**
+     * When the wire body was spilled to blob storage, stage non-delta blobs
+     * as references into it (DESIGN §22.5): `packId` is the wire pack's id,
+     * `base` the pack's byte offset within the spilled object (the request's
+     * pkt-line commands precede it).
+     */
+    readonly promote?: (() => {
+        readonly packId: string;
+        readonly base: number;
+    } | undefined) | undefined;
+    /**
+     * When set, entries are inflated and hashed by the hasher service one
+     * spilled part at a time (DESIGN §22.7) instead of by the in-process
+     * parser; the DO only pumps bytes and stages rows.
+     */
+    readonly hasher?: HasherShape | undefined;
+    /** Bytes per hasher part (tests shrink it). @default HASH_PART_BYTES */
+    readonly partBytes?: number | undefined;
+    /**
+     * The streaming spill (DESIGN §22.10): the pump reads the whole request
+     * BODY in uniform parts, each hasher writes its part to blob storage,
+     * and the completed object is the promotion target (`packId`) and the
+     * source's fallback reader. Bodies that end within `threshold` bytes
+     * stay in memory and nothing is written.
+     */
+    readonly spill?: {
+        readonly body: RandomAccess;
+        readonly feeder: StreamingFeeder;
+        readonly packStart: number;
+        readonly blobs: BlobStoreShape;
+        readonly key: string;
+        readonly packId: string;
+        readonly repoId: string;
+        readonly threshold: number;
+    } | undefined;
+    /**
+     * Shallow-import mode: commit parents may be absent (they become walk
+     * boundaries); trees/blobs/tags must still be fully connected.
+     */
+    readonly allowMissingParents?: boolean | undefined;
+}
+/**
+ * Single-pass buffered pack ingest (DESIGN.md §3.6): parse entries,
+ * store non-delta compressed spans **verbatim**, resolve ofs/ref deltas
+ * (thin bases from the live store), enforce the 64 MiB object cap, verify
+ * the trailer SHA-1, and stage everything under `pushId`.
+ *
+ * The v1.x streaming upgrade seam: this function's only view of the pack
+ * is `pack: Uint8Array` random access — swapping in an R2-backed
+ * `RandomAccess` touches this implementation, not the protocol drivers.
+ */
+/**
+ * Ingests a pack from a {@link RandomAccess} source — the path that has **no
+ * size cap** (DESIGN.md §3.6). Memory is bounded by the source's read
+ * window and the delta LRU rather than by the pack, so the source can be an
+ * R2 object of any size (see `Store/PackSource.ts`).
+ *
+ * Delegates the wire-format work to the pure `PackParser` (which the pack
+ * fixtures in `test/pack.test.ts` cover directly) and does the repo-side
+ * work in its sink: stage the object, and record commit-graph edges.
+ * Blobs are staged without inflating — only commits, trees and tags need
+ * their content parsed, and those are small.
+ */
+export declare const ingestPackFrom: (source: RandomAccess, options: IngestOptions) => Effect.Effect<IngestResult, PackIngestError | StoreError>;
+export declare const ingestPack: (pack: Uint8Array, options: Omit<IngestOptions, "store"> & {
+    readonly store: ObjectStore;
+}) => Effect.Effect<IngestResult, PackIngestError | StoreError>;
+/** A node of the merge-base paint walk's max-heap (gen desc, time desc). */
+export interface WalkHeapNode {
+    readonly oid: string;
+    readonly gen: number;
+    readonly time: number;
+}
+/** Pushes onto a binary max-heap keyed `(gen desc, commit_time desc)`. */
+export declare const heapPush: (heap: Array<WalkHeapNode>, node: WalkHeapNode) => void;
+/** Pops the max node. Callers must check `heap.length > 0` first. */
+export declare const heapPop: (heap: Array<WalkHeapNode>) => WalkHeapNode;
+/** Decompresses a request body when it is gzip (header or 1f8b sniff). */
+export declare const gunzipIfNeeded: (body: Uint8Array, contentEncoding: string | undefined) => Effect.Effect<Uint8Array, PackIngestError>;
+declare const GitRepo_base: Effect.Effect<Cloudflare.DurableObject<GitRepo>, never, GitRepo | Cloudflare.Worker> & {
+    new (_: never): GitRepoShape & {
+        "~alchemy/name": "GitRepo";
+    };
+    from(scriptName: import("../Input.ts").Input<string>): Effect.Effect<Cloudflare.DurableObject<GitRepo>, never, Cloudflare.Worker>;
+    from<Req = never>(worker: import("../Dependencies.ts").Dependencies<GitRepo> | Effect.Effect<import("../Dependencies.ts").Dependencies<GitRepo>, never, Req>): Effect.Effect<Cloudflare.DurableObject<GitRepo>, never, Req | Cloudflare.Worker>;
+    make<Req = never>(impl: Effect.Effect<Effect.Effect<GitRepoShape, never, Cloudflare.DurableObjectState | RuntimeContext | import("effect/Scope").Scope>, never, Req>): import("effect/Layer").Layer<GitRepo, never, Exclude<Req, Cloudflare.DurableObjectServices> | Cloudflare.Worker>;
+};
+/**
+ * The per-repo Durable Object class (modular form). The runtime
+ * implementation is {@link GitRepoLive}; the hosting Worker provides it via
+ * `Effect.provide(GitRepoLive)` and consumers `yield* GitRepo` for the
+ * namespace handle.
+ */
+export declare class GitRepo extends GitRepo_base {
+}
+/**
+ * A repository's RPC stub: {@link GitRepoShape} as the Worker calls it,
+ * with `fetch` taking the request.
+ */
+export type RepoStub = ReturnType<Cloudflare.Workers.DurableObject<GitRepoShape>["getByName"]>;
+/** What {@link RepoStore} provides: a repository's stub by id. */
+export interface RepoStoreShape {
+    /** The repository's stub, by its registry id (a ULID). */
+    readonly getByName: (repoId: string) => RepoStub;
+}
+declare const RepoStore_base: Context.ServiceClass<RepoStore, "alchemy/Git/RepoStore", RepoStoreShape>;
+/**
+ * `Git.RepoStore` — the repository block as a service: every route reaches
+ * a repository through it. `ReposDurableObject` provides it over the
+ * {@link GitRepo} Durable Object namespace. It is the seam for decorating
+ * repositories (hook `commitPush`, `updateRef`, `mergePull` to observe ref
+ * moves) or for implementing {@link GitRepoShape} over another store.
+ *
+ * @binding
+ */
+export declare class RepoStore extends RepoStore_base {
+}
+/**
+ * The Repo DO implementation Layer. Requires the {@link BlobStore}
+ * service (provide `Git.BlobStoreR2(yourBucket)` — or any other
+ * implementation — in the same layer graph) and the {@link Registry}
+ * namespace.
+ */
+export declare const GitRepoLive: import("effect/Layer").Layer<GitRepo, never, BlobStore | Hasher | RegistryStore | Cloudflare.Worker>;
+export default GitRepoLive;
+//# sourceMappingURL=RepoObject.d.ts.map