# ply Zero-dependency git smart-HTTP client that edits one file in a remote repo in **O(1) memory** and pushes the change **as a delta**. Runs anywhere with `fetch`, `CompressionStream`, `crypto.getRandomValues` and `Uint8Array` (Node ≥ 20, Workers, browsers behind a CORS proxy). Every byte and every roundtrip is recorded as an OTLP span. The test suite is a property/fuzz harness that uses real `git` as the oracle and the spans as the coverage map that steers generation. The hosted HTTP API and the public repository viewer live in [ply-web](https://github.com/ivarvong/ply-web) (the Cloudflare Worker `ply`). This repository is the git client. ## Install ply is not on npm (the npm name `ply` belongs to another package). Install it from GitHub; npm builds `dist/` on install: ```sh npm install github:ivarvong/ply # the default branch, as of now npm install github:ivarvong/ply# # recommended: pin a commit for reproducible builds ``` It installs as `ply`, so imports read `from 'ply'` and `from 'ply/'` (`ply/edit`, `ply/read`, `ply/tree`, `ply/checkout-node`, …). Types ship with it (`dist/*.d.ts`); JavaScript and TypeScript use the same calls. ply is ESM-only: there is no CommonJS build and no `require` export condition. The Node floor is 20 (`engines.node` is `>=20`; all 19 entry points import on 20.17.0). From a CommonJS file, `await import('ply')` works on every supported Node. `require('ply')` depends on the Node version: it works where Node loads an ES module with `require()` by default, which is Node 20.19.0 and later on the 20 line (Node's changelog for 20.19.0: "require(esm) is now enabled by default"; measured on 20.19.0 and 20.20.2) and Node 22.12 and later (measured on 22.15.0, 24.2.0, 24.16.0, 24.18.0 and 25.2.1). Before that it throws `ERR_REQUIRE_ESM`: on Node 20.18 and earlier (measured on 20.17.0, 20.18.0 and 20.18.3) and on Node 22 before 22.12 (Node's documented boundary, not measured here). CI job `pack` packs the tarball, installs it with `--ignore-scripts` into an empty project, and checks every import and this `require()` behaviour under Node 20, 22 and 24 (`npm run check:pack`, `test/pack-install.test.js`). The git install above needs the package manager to run ply's `prepare` script: `dist/` is not in git, and `prepare` builds it (npm first installs ply's dev tools in a temporary clone). Not every package manager runs it, and none of them fails when it does not run. Measured in an empty project at commit 77048fb: | package manager | default | `--ignore-scripts` | |---|---|---| | npm 11.16.0 | builds `dist/`; imports work | exits 0, no `dist/` | | pnpm 8.15.9 | builds `dist/`; imports work; installs the whole repository (7.8 MB), where npm installs `files` only (1.7 MB) | exits 0 with the warning `has to be built but the build scripts were ignored`, no `dist/` | | yarn 1.22.22 | exits 0 without running `prepare`, no `dist/` | exits 0, no `dist/` | | bun 1.2.18 | exits 0 with `Blocked 1 postinstall`, no `dist/`; `bun pm trust ply` then fails (`tsc: command not found`) | exits 0, no `dist/` | With no `dist/`, every import fails with `ERR_MODULE_NOT_FOUND`. So the git install works with npm and with pnpm 8, scripts on; it does not work with yarn 1 or bun 1.2, or with scripts off. pnpm, yarn and bun were given `github:ivarvong/ply#`, npm a local clone of the same commit (`git+file://`); pnpm 9 and later and yarn 2 and later were not measured. The packed tarball contains `dist/` and installs with scripts off (measured with npm; CI job `pack`). CI uploads it as the workflow artifact `ply-tarball`, which needs a GitHub login and expires; there is no install URL for it yet. ## Beta ply is pre-1.0 (0.2.0). The API can change between commits without a deprecation period, and there are no tagged releases yet: pin a commit sha, read the commit log before moving the pin, and let your type checker or tests catch a changed signature. Span names and attributes are a stated contract (see [Telemetry contract](#telemetry-contract)). ## Requirements - **Runtime**: Node ≥ 20, Cloudflare Workers, or any runtime with `fetch`, `CompressionStream`/`DecompressionStream`, `crypto.getRandomValues` and `Uint8Array` (a browser works behind a CORS proxy). `ply/tree-node`, `ply/checkout-node` and `ply/repo-node` are Node only (`node:fs`). - **TypeScript** (optional): the shipped declarations compile with `skipLibCheck: false` under `lib: ["ES2022"]` with `@types/node` 20, 22 or 24, under the `DOM` lib, and under `@cloudflare/workers-types`. `npm run check:dist` and `test/dist-types.test.js` compile each of those five consumers (pinned: `@types/node` 20.19.43, 22.20.5 and 24.19.2, `@cloudflare/workers-types` 5.20260916.1, TypeScript 7.0.2, `nodenext` resolution) and fail when a type package is missing; none is skipped. They need the web globals one of those provides (`ReadableStream`, `Response`, `AbortSignal`, `URL`); `lib: ["ES2022"]` with no types package is not enough. - **A git smart-HTTP server**: GitHub, GitLab, Gitea/Forgejo, Cloudflare Artifacts, or self-hosted `git http-backend` (`http.receivepack true` to push; nothing else). A stock git server works: without `uploadpack.allowFilter` its advertisement has no `filter`, and ply learns that from the server (`quirks.treeFilter = 'none'`, learned once per remote: see the Artifacts notes below) and fetches unfiltered: the same results, with more bytes per read. The quick start below runs on both. ply speaks protocol v2 for reads and receive-pack for pushes; SHA-1 repositories only. A server that answers only v0/v1 is refused as `unsupported` (`what: 'protocol version'`) on the first ls-refs. - **Auth**, per call in `opts.auth`: `{ token }` (HTTP Basic with user `x-access-token`, which GitHub tokens use), `{ token, user }` (a host that wants a username: GitLab `oauth2` for an OAuth token, your Gitea/Forgejo user), `{ bearer }`, or `{ header }` (an `Authorization` value sent as is). Or userinfo in the URL (`https://@host/…`), sent as git sends it. No `auth` and no userinfo: anonymous. Credentials never reach a span or an error message; redirects are not followed. Details in "Credentials" under [More detail](#more-detail). What ply does **not** do: create or delete repositories (that is the host's API, or `git init --bare` on your server: ply needs one to exist, empty or not); SSH transport (removed; HTTPS only); Git LFS content (an LFS pointer is refused by edits, see [Guards](#guards-and-policy)); pull requests, issues or any other host API object; a working tree or index (there is no clone: every call reads what it needs over the wire). ## Quick start: a repo end to end Every call takes `(url, spec, opts)` (`opts` is optional: `auth`, `limits`, `signal`, and `tracer`, a `new Tracer({ exporter })` to export spans; without one they are dropped), and returns a `Result`: `{ ok: true, value }` or `{ ok: false, error }`, never a throw. The blocks below run in order against one repository that starts empty (they are executed as written, against `git http-backend` with and without `uploadpack.allowFilter`, by `test/e2e-customer.test.js`, and type-checked as TypeScript by `test/types/readme.typetest.ts`). A ref that is written is a full name (`refs/heads/main`; a tag's `name` may be short); a ref that is only read (`readCommit`'s `ref`, `createBranch`'s `from`, `createTag`'s `target`) may also be a short name (`main`, `v1.3.0`) or a commit id. ```js // quick-start: setup const url = 'https://git.example.com/acme/site.git'; // an existing repository, empty or not const opts = { auth: { token: process.env['GIT_TOKEN'] } }; // add tracer: new Tracer({ exporter }) to export spans const author = { name: 'Release Bot', email: 'bot@example.com' }; // time defaults to now, tz to +0000 const outDir = './site-checkout'; // checkoutDir writes here; it must be absent or empty ``` **First commit into an empty repository.** `pushTree` commits exactly `files` as the tree. A branch that does not exist yet is created as a root commit. ```js // quick-start: first-commit import { pushTree } from 'ply'; const first = await pushTree(url, { ref: 'refs/heads/main', files: { 'README.md': '# site\n', 'src/config.ts': 'export const VERSION = "1.2.3";\n', 'bin/build': { data: '#!/bin/sh\necho build\n', mode: '100755' }, }, author, message: 'Initial commit', }, opts); if (!first.ok) throw first.error; console.log(first.value.newCommit); // the commit id main now points at ``` **Read** a commit, a directory, and a file (streamed, hash-checked as it is read). ```js // quick-start: read import { readCommit, listTree, readFile } from 'ply'; const head = await readCommit(url, { ref: 'main' }, opts); if (!head.ok) throw head.error; if ('empty' in head.value) throw new Error('main has no commits yet'); console.log(head.value.oid, head.value.tree, head.value.parents, head.value.message); const listing = await listTree(url, { ref: 'main', path: 'src' }, opts); if (!listing.ok) throw listing.error; for (const e of listing.value.entries) console.log(e.mode, e.type, e.oid, e.name); // as git ls-tree prints them const file = await readFile(url, { ref: 'main', path: 'src/config.ts' }, opts); if (!file.ok) throw file.error; const config = await new Response(file.value.stream).text(); // read the stream to the end (or cancel it) console.log(file.value.size, config); ``` **Edit one file**: find exactly one occurrence and replace it. The blob streams through; the push is a delta. ```js // quick-start: edit import { editFile } from 'ply'; const bump = await editFile(url, { ref: 'refs/heads/main', path: 'src/config.ts', find: 'VERSION = "1.2.3"', replace: 'VERSION = "1.2.4"', author, message: 'Bump version to 1.2.4', }, opts); if (!bump.ok) throw bump.error; // match_count when find is not there exactly once console.log(bump.value.newCommit, bump.value.noop); // noop: find === replace, nothing pushed ``` **Several changes in one commit**, applied in order. ```js // quick-start: commit-changes import { commitChanges } from 'ply'; const change = await commitChanges(url, { ref: 'refs/heads/main', changes: [ { kind: 'create', path: 'docs/intro.md', content: '# Intro\n' }, // refuses a path that exists { kind: 'write', path: 'README.md', content: '# site\n\nHello.\n' }, // creates or overwrites { kind: 'edit', path: 'src/config.ts', find: '1.2.4', replace: '1.3.0' }, // exactly one match { kind: 'delete', path: 'bin/build' }, // a file or a whole directory { kind: 'rename', from: 'docs/intro.md', to: 'docs/index.md' }, ], author, message: 'Docs; version 1.3.0', }, opts); if (!change.ok) throw change.error; console.log(change.value.outcome, change.value.oid); // 'commit', or 'noop' when the tree did not change ``` **Branches**: create one at a commit (a ref name or a 40-hex commit id), commit to it, merge it back. `mergeBranch` fast-forwards when it can and otherwise writes a merge commit (git's merge-ort result for clean merges; `merge_conflict` with the paths otherwise). ```js // quick-start: branch-merge import { createBranch, mergeBranch } from 'ply'; const feature = await createBranch(url, { ref: 'refs/heads/feature', from: 'main' }, opts); if (!feature.ok) throw feature.error; // cas_conflict when the branch already exists const work = await commitChanges(url, { ref: 'refs/heads/feature', changes: [{ kind: 'create', path: 'src/feature.ts', content: 'export const feature = true;\n' }], author, message: 'Add feature flag', }, opts); if (!work.ok) throw work.error; const hotfix = await editFile(url, { // main moves on meanwhile ref: 'refs/heads/main', path: 'README.md', find: 'Hello.', replace: 'Hello, world.', author, message: 'Fix greeting', }, opts); if (!hotfix.ok) throw hotfix.error; const merged = await mergeBranch(url, { ref: 'refs/heads/main', from: 'refs/heads/feature', author }, opts); if (!merged.ok) throw merged.error; console.log(merged.value.outcome, merged.value.oid); // 'merge': a commit with parents [main, feature] ``` **Tags**: lightweight (the ref names the commit) or annotated (a tag object with a tagger and message). ```js // quick-start: tag import { createTag } from 'ply'; const release = await createTag(url, { name: 'v1.3.0', target: 'refs/heads/main' }, opts); if (!release.ok) throw release.error; const notes = await createTag(url, { name: 'v1.3.0-notes', target: release.value.commit, message: 'Release 1.3.0', tagger: author }, opts); if (!notes.ok) throw notes.error; console.log(notes.value.oid, notes.value.commit); // the tag object, and the commit it names ``` **Rebase, cherry-pick, revert.** Each replays commits with the same three-way merge and pushes with the old tip as the compare-and-swap. ```js // quick-start: rebase-pick-revert import { rebaseBranch, cherryPick, revertCommit } from 'ply'; const topic = await createBranch(url, { ref: 'refs/heads/topic', from: 'refs/heads/main' }, opts); if (!topic.ok) throw topic.error; const onTopic = await commitChanges(url, { ref: 'refs/heads/topic', changes: [{ kind: 'create', path: 'src/topic.ts', content: 'export const topic = 1;\n' }], author, message: 'Add topic' }, opts); if (!onTopic.ok) throw onTopic.error; const onMain = await commitChanges(url, { ref: 'refs/heads/main', changes: [{ kind: 'create', path: 'CHANGELOG.md', content: '1.3.0\n' }], author, message: 'Changelog' }, opts); if (!onMain.ok) throw onMain.error; const rebased = await rebaseBranch(url, { ref: 'refs/heads/topic', onto: 'refs/heads/main', committer: author }, opts); if (!rebased.ok) throw rebased.error; // topic's commits replayed onto main's tip const picked = await cherryPick(url, { ref: 'refs/heads/main', commit: rebased.value.oid, committer: author }, opts); if (!picked.ok) throw picked.error; // outcome 'ok', or 'empty' when main already has the change (nothing written) const reverted = await revertCommit(url, { ref: 'refs/heads/main', commit: picked.value.oid, committer: author }, opts); if (!reverted.ok) throw reverted.error; // a 'Revert "Add topic"' commit on main ``` **History**, first parent, newest first (`git log --first-parent`). ```js // quick-start: history import { readLog } from 'ply'; const log = await readLog(url, { ref: 'refs/heads/main', limit: 10 }, opts); if (!log.ok) throw log.error; for (const c of log.value.commits) console.log(c.oid.slice(0, 7), c.parents.length, c.message.split('\n')[0]); ``` **Check out a whole tree**: as streams (Workers-safe), or into a directory (Node, laid out as `git clone` would, without `.git`). ```js // quick-start: checkout import { checkoutTree } from 'ply'; import { checkoutDir } from 'ply/checkout-node'; const tree = await checkoutTree(url, { ref: 'v1.3.0' }, opts); if (!tree.ok) throw tree.error; for await (const f of tree.value.files) { if (f.stream) console.log(f.path, f.mode, (await new Response(f.stream).arrayBuffer()).byteLength); // read each stream } const written = await checkoutDir(url, { dir: outDir, ref: 'main' }, opts); if (!written.ok) throw written.error; console.log(written.value.written.files); // files written under outDir ``` **Delete a branch.** Without `expected` the tip ls-refs reports is the compare-and-swap; with `expected: ''` the delete happens only from that tip. The branch the remote's HEAD names is refused by the server (`push_rejected`). ```js // quick-start: refs import { listRefs, deleteBranch, deleteTag } from 'ply'; const refs = await listRefs(url, {}, opts); // branches and tags; { prefixes: ['refs/heads/'] } for branches only if (!refs.ok) throw refs.error; console.log(refs.value.head, refs.value.refs.map(r => r.name)); // 'refs/heads/main', [ 'refs/heads/feature', … ] const gone = await deleteBranch(url, { ref: 'refs/heads/feature', expected: work.value.oid }, opts); if (!gone.ok) throw gone.error; // cas_conflict when feature moved off that commit; not_found when it is gone const untagged = await deleteTag(url, { name: 'v1.3.0-notes' }, opts); if (!untagged.ok) throw untagged.error; ``` **Errors.** `error.code` is a closed union, so a `switch` with `assertNever` in `default` is checked exhaustive by TypeScript (a new code in ply fails your build, not your users). What to do with each: ```js // quick-start: errors import { assertNever } from 'ply'; const stale = await editFile(url, { ref: 'refs/heads/main', path: 'src/config.ts', find: 'VERSION = "9.9.9"', replace: 'VERSION = "10.0.0"', author, message: 'Bump', }, opts); if (!stale.ok) { const e = stale.error; switch (e.code) { case 'cas_conflict': // the ref moved between read and push (editFile already redid it once): read again, redo console.warn('moved', e.expected, e.actual); break; case 'match_count': // find matched e.matches times, not once: the file is not what you expected console.warn('matches', e.matches); break; case 'not_found': // e.miss.kind: 'ref' | 'path' | 'repository' | 'head_unborn' | 'commit' | … console.warn('missing', e.miss.kind); break; case 'auth': // 401/403: the credential is missing, wrong, or lacks write access console.warn('auth'); break; case 'limit_exceeded': // a limits.* bound (e.what, e.got, e.max): raise it with withLimits, or do less per call console.warn('limit', e.what, e.got, e.max); break; case 'ambiguous': // the push was sent and may have landed: read the ref back before doing anything else console.warn('unknown outcome'); break; case 'network': case 'timeout': case 'rate_limited': case 'upstream_5xx': case 'protocol': case 'pack_corrupt': console.warn('transient: retry with backoff', e.code); break; // isRetryable(e) is true for exactly these case 'merge_conflict': case 'not_fast_forward': case 'not_linear': case 'unrelated_histories': console.warn('history needs a human', e.code); break; case 'push_rejected': case 'push_partial': case 'remote_error': // a hook, branch protection, or the server said no console.warn('refused', e.message); break; case 'bad_request': case 'unsupported': case 'lfs_pointer': case 'http': case 'not_git': case 'aborted': case 'internal': console.warn('fix the call or the setup', e.code, e.message); break; default: assertNever(e); } } ``` `retryPolicy(error)` gives the same advice as data (`yes`, `fresh`, `read`, `no`), and `CODE_DOCS[code]` a one-line description. Every option an entry takes is in its section below. ## More detail `inflate(buf, pos = 0, opts)` reads the zlib member at `buf[pos..]` and reports the bytes it `consumed`. `pos` is a position in `buf`: a non-negative safe integer no greater than `buf.length` (at the very end there are no bytes, so the member is cut: `pack_corrupt`). Any other value (negative, fractional, `NaN`, past the end, a string) is `bad_request` before a byte is read; it used to be passed to `subarray`, which reads a negative offset from the end of the buffer, and `NaN` threw. `Sha1` is an incremental hasher: `update(bytes)` any number of times, and `digest()` (20 bytes) or `hex()` (an `Oid`) is a snapshot of the bytes fed so far. It leaves the hasher as it was, so it can be called repeatedly (same input, same value) and `update()` may continue afterwards, which is what a running pack checksum needs. A second `digest()` used to return the hash of the message plus its padding. `streamingSha1().hex()` may also be awaited more than once (the same value); on Workers it ends the native `DigestStream`, so there an `update` after `hex()` rejects. `resolvePack(parsed, external, limits)` resolves every delta of a parsed pack (`parsePack`'s value, or `{ objects }` built by hand) and returns `{ objects, stats }`. `objects` is a `Map` from id to object, and its iteration order promises one thing: every base that is in the pack comes before the objects built on it (an id the pack holds twice has the place of the copy that resolved first). The order of siblings is not part of the contract, and it changed when the resolver began to work by dependency: for a thin pack `[REF@2 on X, REF@3 on X, OFS@4 on 2]` with X given, the objects come out at offsets 2, 4, 3 where they came out 2, 3, 4. `external(oid)` supplies thin bases: `{ type, data }` for a base that is not in the pack, or `null`. **It is called once per distinct missing base id, in pack order of the first REF_DELTA that waits on that id, however many deltas rest on it** (it used to be called once per waiting delta, so a caller that counts invocations sees fewer), and only after everything the pack can resolve by itself has resolved. Every REF_DELTA waiting on an id that `external` gives is patched directly on that base (chain 1, counted in `stats.externalBases`), also when the pack then produces that id itself: for `[REF@2 on X, OFS@3 on 2 producing X, REF@4 on X]` with X given, both REF deltas are patched on the given X (`externalBases` 2, `maxChain` 2) where the second used to be patched on the pack's copy at offset 3 (`externalBases` 1, `maxChain` 3), so such a pack can resolve where it used to be `limit_exceeded`. The other way round, a REF_DELTA whose base the pack itself builds is patched on the pack's copy whenever that copy resolves before the id is asked for: `external` is then not asked for that id, even if it holds it, and the delta's chain is the pack's own, so such a pack can be `limit_exceeded` where it used to resolve. For `[REF@2 on X producing A, REF@3 on B producing C, OFS@4 on 2 producing B]` with X and B given, `external` is asked for X only (it used to be asked for X, then B), and C is patched on the pack's B at offset 4: C's `chain` is 3, `stats.maxChain` 3 and `stats.externalBases` 1 (C used to be patched on the given B: `chain` 1, `maxChain` 2, `externalBases` 2), and with `maxDeltaChain` 2 the pack is `limit_exceeded` "delta chain depth 3 exceeds limit 2" where it used to resolve. A REF_DELTA on an id the pack holds twice is patched on whichever copy is registered when the delta is resolved, which can be the deeper one: for `[REF@2 on c0 producing c5, whole c1 at 3, OFS@4 on 3 producing c0, whole c5 at 5, REF@6 on c5 producing c2]` with no `external`, the object at offset 6 has `chain` 3 where it had 1, and with `maxDeltaChain` 2 the pack is `limit_exceeded` where it used to resolve. A pack of either shape that both versions refuse may carry the other code: `limit_exceeded` where it was `pack_corrupt` "ref delta base … not found", and the reverse. A base it returns must hash to the id that named it (`pack_corrupt` otherwise); a base it does not have is `pack_corrupt` "ref delta base … not found". The chain limit is checked before the lookup, and that check counts OFS links down to the nearest REF_DELTA: a delta more than `maxDeltaChain` OFS deltas above a REF_DELTA whose base has not resolved from the pack is `limit_exceeded` (`what: 'delta chain depth'`) and `external` is not called; a delta exactly `maxDeltaChain` OFS deltas above it is `limit_exceeded` if the base is given and "not found" if it is not. A chain of REF deltas is counted one link at a time, as each base resolves, and none of it is refused before the lookup: with its bottom base withheld, a REF chain of any length is "not found" after `external` was asked once for each link's base id, and with that base given the first link past `maxDeltaChain` is `limit_exceeded`. `describePack(bytes, limits)` takes no lookup: a base outside the pack is listed under `missingBases`, the objects that wait on it have `oid: null`, and the same check applies: an OFS chain more than `maxDeltaChain` deltas above a REF_DELTA whose base is missing is `limit_exceeded`, and a chain of REF deltas above a missing base is not (each link's base id is listed under `missingBases`). `stats` is `{ maxChain, externalBases, baseLookups, steps }`: the longest delta chain resolved, the deltas patched directly on a base `external` gave, the REF_DELTA base lookups by id, and `steps`, the number of entry visits the resolver made. An entry is visited at most three times in any pack order, so `steps` is at most three times the object count; it is a work counter for tests and telemetry, and its exact value may change between versions. Input with two entries at one offset (hand-built only; `parsePack` cannot produce it) gives one object at that offset: the first of those entries to resolve, which need not be the first in the list, because whole objects resolve before deltas, and deltas on bases in the pack before deltas on bases `external` gives. A cycle of OFS bases (hand-built only) is `limit_exceeded` `delta chain depth`. **Wrong-shape arguments.** These entry points answer null, undefined (for a required argument), a number or an array where an object, array or `Uint8Array` is documented with `bad_request` whose `what` names the argument, never a throw: `pushRepo` (`spec`, `options`), `pushDir` (`spec`, `options`), `filesFromDir` (`dir`, `options`), `pushPack`, `copyTree`, `loadTransferPack`, `planTransfer`, `planPackBatches`, `resolvePackRange`, `scanPackIndex`, `packSubset`; `decodeSavedIndex` answers them with its `bad_argument` refusal (`what` `bytes` or `want`), and the root's `matchOption` with `bad_request` (`what` `option` or `handlers`), while `isSome` and `isNone` answer `false`. Every other export may still throw a `TypeError` on such an argument; each call shape that does is listed in the `STILL_THROWS` allow-list in `test/input-validation.test.js`, which fails when a listed shape stops throwing or an unlisted one starts. `parsePack` accepts optional `maxObjects` and `maxInflatedTotal`. Omitting them uses `DEFAULT_LIMITS` (`maxPackObjects` 100_000, `maxInflatedTotal` 256 MiB). A limits object that drops either key fails closed (`bad_request`) instead of leaving the cap off. `validateIdent({ name, email, time, tz })` is the only way to build an author, committer, or tagger: `time` is a non-negative safe integer, `tz` is a civil offset (`-1200`..`+1400`), and the result is branded so a spread cannot reach `ident()`. [ply-web](https://github.com/ivarvong/ply-web) also uses these entry-point exports: `validateIdent`, `validateRef`, `validatePath`, `concat`, `limitError`, `isFilterRejection`, `fromAny`, `packParseOpts`. ```js import { editFile, Tracer, consoleExporter } from 'ply'; const tracer = new Tracer({ exporter: consoleExporter() }); // logs each export as one JSON line; or your own (request) => …, which gets the object: { resourceSpans: [{ resource, scopeSpans: [{ scope, spans: [span] }] }] } const cache = new Map(); // trees by oid, reused across edits const r = await editFile('https://github.com/o/r.git', { ref: 'refs/heads/main', path: 'src/config.ts', find: 'VERSION = "1.2.3"', replace: 'VERSION = "1.2.4"', author: { name: 'bot', email: 'bot@x' }, message: 'bump', }, { auth: { token: process.env.GIT_TOKEN }, tracer, cache }); if (!r.ok) { switch (r.error.code) { /* exhaustive over Code: every case, no default, then assertNever(r.error) */ } } // r.value.newCommit, r.value.pushBytes (≈ 300 + |replace| + 80·depth), r.value.noop ``` Every public function returns a `Result` (0.2.0): `{ ok: true, value }` or `{ ok: false, error }`, never a throw. `error` is a `PlyError`: an `Error` with a `code` from a closed union, so `switch (r.error.code)` with no `default` is checked exhaustive by the compiler. The one exception is `decodeSavedIndex`, whose `error` is the typed `SavedIndexRefusal` (a plain object; `switch (r.error.tag)` over its eight tags, see Saved pack index below), because a refused saved index means "scan again", not a failure. A stream (`readFile`'s `stream`, `checkoutTree`'s `files`) reports a failure the way a stream does: it errors, with that same `PlyError`. Your own code failing is an `Err` too. When a function you passed throws or rejects, the `Err` carries the thrown value, untouched, as `error.cause` (ply writes nothing on it), and `error.what` says whose it was. These are named: | you passed | `error.what` | `error.code` | | --- | --- | --- | | `signer` (its `sign` fails, or returns a non-string) | `'signer'` | `bad_request` | | `filter` (`pushDir` / `filesFromDir`) | `'filter'` | `bad_request` | | `transport`: `frames()` throws, or its stream rejects | `'transport.frames'` | `bad_request` on a read request; `ambiguous` on the push request | | `transport`: `advertise()` throws or rejects | `'transport.advertise'` | `bad_request` | | `fetchImpl` throws or rejects | `'fetchImpl'` | `network` (a fetch that fails is a network failure); `aborted` / `timeout` instead when the request's signal fired, and those are not named `fetchImpl` | | `cachingFetch`'s `shouldCache`, `waitUntil`, or the cache's `match` / `delete` / `put` throws when called | `'shouldCache'`, `'waitUntil'`, `'cache.match'`, `'cache.delete'`, `'cache.put'` | `bad_request` | Every other function you pass ends in the backstop: a throw from it that reaches the end of an operation (`editFile`, `commitChanges`, `pushTree`, merge, rebase, pick, and an `operation()` body together with every callback reached from it) is `what: 'callback'` with the thrown value as `error.cause`. For an `operation()` body this is a **breaking change since #277**: before it, the body's throw reached you unchanged; see "`operation()`: your body's outcomes" below. Three things are not failures of the operation: a cache whose `match` or `delete` promise rejects is a miss, a `put` that rejects is counted in `stats` (`putFailed`, `putError`; a `put` that throws when called is the fetch's `'cache.put'` failure, since it is called inside the fetch; under `verifyBeforeStore` the `put` is called only after `verifyFetchAnswer` accepted the answer, after the fetch answered, so one that throws there is counted in `putFailed` too, `putError` holding the `'cache.put'` Err's message, which names the thrown value, and the fetch is unaffected), and an `advertise()` ply calls only to confirm a refused push or an empty answer confirms nothing when it fails. A thrown value that already carries one of ply's codes (a transport or fetch that wraps ply's own) is that error, as it is. The outcome class follows the push: before the push request was handed to the transport nothing can have moved, so the failure is definite (the code in the table; the backstop is `bad_request`, retry `no`); once it was, the ref may have moved, so it is `ambiguous` (read the ref back): a named failure on a later read is then the `cause` of that `ambiguous`, and the backstop puts the replaced code, if the thrown value had one, in `error.original`. `pushDir` and `filesFromDir` also return node:fs's own failures (a missing directory, an unreadable file) as `bad_request` with `what: 'dir'` and the node error (its `code` such as `ENOENT` or `EACCES`, its `path`) as `error.cause`. This holds whatever the thrown value is: one that cannot be described (a null-prototype object, an object whose `message` getter or `toString` throws, a revoked Proxy) still ends as that `Err`, whose message says `a value with no string form` and whose `cause` is the value. Telemetry callbacks are different: they never change the outcome at all (see `onTelemetryError`). ### `operation()`: your body's outcomes **Breaking change since #277.** In `operation(op, url, opts, body)`, a throw from `body` (or from any callback reached from it) never reaches you as a throw or a rejection. This covers `body` only: a caller tracer whose `start()` throws, or an `opts.link` whose `span` is null or undefined (or whose `traceId`/`spanId` getter throws), still rejects before `body` runs. What you get back depends only on what was thrown and on whether a push request had been handed to the transport (the first `t.frames()` call for a service other than `git-upload-pack`) when it was thrown: | `body` … | before the push request was handed over | after | | --- | --- | --- | | throws a value that is not a `PlyError` | `bad_request`, `what: 'callback'`, `cause` the thrown value | `ambiguous`, `what: 'callback'`, `cause` the thrown value, its `code` in `original` if it has one (any value but null or undefined; a node `ECONNRESET` error, say) | | throws a `PlyError` | that `PlyError`, as itself | `ambiguous`, `what: 'callback'`, `cause` the thrown error, its code in `original` (a thrown `ambiguous` is itself) | | returns a `Result` | that `Result`, as it is | that `Result`, as it is | So a callback's own throw is treated as a failure, never as an answer: a definite `cas_conflict` you learned and then threw after the push is reported `ambiguous`. Return expected outcomes as values, a discriminated union inside the `Ok` (the pattern ply-web adopted in ivarvong/ply-web#153): ```ts type Bump = { tag: 'bumped'; commit: string } | { tag: 'conflict'; reason: 'ref_exists' | 'stale_expected' }; const r = await operation('bump', url, opts, async ({ t, root, outcome }) => { // … read refs over t … if (exists) return outcome('conflict', { tag: 'conflict', reason: 'ref_exists' }); // … push over t … return outcome('ok', { tag: 'bumped', commit }); }); if (!r.ok) return status(r.error); // ply's failure, or your crash (what: 'callback') if (r.value.tag === 'conflict') return conflict409(r.value.reason); ``` `test/operation-callback-contract.test.js` pins each row. ### Upgrading from 0de5ad4-era releases Before #277 a value thrown from an `operation()` body reached the caller unchanged, so some consumers threw their own errors through it for control flow (ply-web's `ref_exists` and `stale_expected` 409s). Those now arrive as `bad_request` (`what: 'callback'`, your value in `error.cause`), or as `ambiguous` when thrown after the push request was handed over; nothing fails to compile and nothing throws, the answer just changes. Return them as values instead (above). Reading `error.cause` of a `what: 'callback'` Err works as a stopgap before the hand-over, but after it the code is `ambiguous` and the ref may have moved. Credentials: `auth: { token, user? }` (Basic `:`, user defaulting to `x-access-token`, sent as UTF-8 bytes as git sends a credential helper's), `{ bearer }`, or `{ header }` (an Authorization value forwarded verbatim; it and a bearer token must be printable ASCII). An `auth` that would send nothing is `bad_request`: `{}`, an empty token with no user, and `{ user }` alone (git's credential API asks for the password there; `{ user, token: '' }` sends Basic `:`, the `https://@host` form). Without `auth`, userinfo in the URL is sent as git sends it, byte for byte (percent-decoded): `https://user:pass@host/…` is Basic `user:pass`, a token as the user (`https://@host/…`, the GitHub and GitLab form) is Basic `:`, `https://:pass@host/…` is `:pass`; a NUL, CR or LF in it, or a URL that does not parse, is `bad_request` before any request. `createTransport` (and every operation given a URL) requests only `http:` and `https:` URLs, and the rule is applied to the URL that will be requested, in this order: the URL must parse, its userinfo must be clean (`what: 'url userinfo'`), then your `allowUrl` runs on the base, then the scheme is checked, and only then are `auth` and `limits` validated. A base that is not http(s) given together with an invalid `auth` or an invalid limit therefore reports `what: 'url'`, where the same options on an http(s) base report `what: 'auth'` or the limit's name (`what: 'requestTimeoutMs'`); both are `bad_request`, and before the scheme rule such a base reported the `auth` or the limit. So a base in a scheme of your own that `allowUrl` maps to `https:` is accepted, an `allowUrl` that refuses returns your own error, an `allowUrl` that answers with a URL that is not http(s) is `bad_request` (`what: 'allowUrl'`), and without an `allowUrl` a base that is not http(s) (`file:`, `data:`, `ssh:`, `git:`, …) is `bad_request` (`what: 'url'`, a fixed message that never repeats the URL) with no request made; before, such a base was accepted and failed later as a `network` error from `fetch`. None reaches a span, a URL attribute or an error message, even when a server echoes it (the Basic user too, when it is token-shaped or the whole credential). By default redirects are never followed: a 3xx is an `http` error naming the target, so no credential can follow it to another origin. `followRedirects: 'initial'` is git's `http.followRedirects=initial`: only the first GET info/refs is followed (up to `maxRedirects`, each `Location` through your `allowUrl`), the base is rewritten, and a cross-origin rebase drops the credential. How that exchange settled (the followed `Location`s, or none) is remembered per remote and service, like the quirks record, so a later transport for the same remote sends its first POST straight to the settled base with no GET; the remembered `Location`s go through that transport's own `allowUrl` and `maxRedirects` again, and a 3xx on that base drops the memo, settles over the network and re-sends a byte body once (a streamed body gets the error). `forgetQuirks(url)` forgets it too. Outcomes are typed on `r.error.code`: `cas_conflict` (retry), `match_count` (find ≠ exactly once), `not_found`, `auth`, `rate_limited`, `pack_corrupt`, `remote_error`, `upstream_5xx`. A `find === replace` edit returns `{ noop: true }` and pushes nothing. ## Wire sequence | # | Request | Response | Why | |---|---|---|---| | 1 | v2 `ls-refs` with `ref-prefix` | one line | head oid | | 2 | v2 `fetch want filter tree:0 deepen 1 done` | 1-object pack | commit only (~300 B) | | 3…N+2 | v2 `fetch want filter tree:0` per level | 1-object pack each | only the trees on the path; cached by oid (immutable) | | N+3 | v2 `fetch want ` | 1-object pack, **streamed** | inflate → scan → SHA-1, never materialized | | N+4 | v0 `receive-pack` thin pack | `unpack ok` / `ng` | commit full + N tree `REF_DELTA`s + blob `REF_DELTA`; `old new ref` line is the CAS | With a warm tree cache (root tree oid unchanged) steps 3…N+2 vanish: 3 roundtrips + push. ## Fewer round trips on repeat edits Two ideas from [gitgrep](https://github.com/ivarvong/gitgrep): - `cachingFetch(fetch, caches.default, { waitUntil })` as `fetchImpl`: the commit/tree fetches are wants-only, filtered, and every object is hash-verified on arrival, so the responses are immutable and cached per colo under `sha256(url, credential, body)`. The answer streams to the caller and, through a verifier, into `cache.put`; without `verifyBeforeStore` nothing on the cache path holds a whole answer (with it, a MISS holds up to three times `limits.maxPackBytes`, below). The verifier keeps one pkt-line frame of state and errors the body handed to `put` at the first violation or at the end: pkt-line framing complete to the final flush, no `ERR` packet, no sideband channel-3 message and, when there is a packfile section, a `PACK` v2/v3 header and a trailing SHA-1 equal to a running SHA-1 of the pack bytes (no inflate, no delta resolution; pack and progress are each held to `limits.maxPackBytes`, and limits that do not parse store nothing). That running SHA-1 is what a MISS costs in the cache layer: in Node it is ply's pure-JS SHA-1, measured at about 3.5 ms of CPU per MiB of pack (Node 24.18, laptop, 1 MiB and 10 MiB answers; about 0.4 ms per MiB without it), and where the platform has `crypto.DigestStream` (Workers) it is the native digest, not measured here. An acknowledgments-only fetch answer (a round that ends on its `NAK`/`ACK` lines, to a request without `done`) is refused and not stored, as `verifyFetchAnswer` refuses it ("answer: no packfile section"). The answer to another command a caller's own `shouldCache` admits (ls-refs) is checked for framing and `ERR` only, and is cacheable. A failed or cut answer still reaches the caller and is not stored, so one bad exchange is not replayed: `PackCache.put` takes no abort signal, so the errored body is the abort (a Cache API put fails with its body), and the key is deleted after a refusal as well, counted in `stats.verifyFailed` with the reason in `stats.verifyError` (`git.pack.cache.verify.failed` / `.verify.error` on the span). A delete that fails there, by rejecting or by throwing, is ignored and does not reject the promise handed to `waitUntil`. The store never paces the caller: the cache branch queues at most `CACHE_LAG_BYTES` (1 MiB) for a store that reads slower than the caller, and past that the put is given up and the answer is not stored (`stats.putFailed`, the key deleted). A caller that cancels the response body cancels the origin and the put; nothing is drained. The store is untrusted, and a HIT is streamed exactly as stored, with no pass in the cache layer (`f.counters.parsed` counts the chunks the cache layer parsed; a HIT adds none): the check is the caller's own parse of the replayed answer. ply's client verifies the pack and hashes every object, and a HIT whose answer it refuses (`pack_corrupt`, `protocol` or `remote_error`: a flipped pack byte, a cut or empty entry, a wrong pack trailer, a stored `ERR`) is deleted and asked for once more from the origin (`x-ply-cache: bust`, answered `x-ply-pack-cache: BUST`, `stats.bust`); the retry's outcome is the call's outcome, and a limit, a timeout, an abort or a transport failure on a HIT is not retried. The blob stream is never cached, unless `verifyBeforeStore: true`: that widens the rule to every wants-only fetch and stores an answer only after `verifyFetchAnswer` accepted the whole of it (every want present, every object hashed; `openBlob` has no retry past a bad entry, so the entry must be right when it is written). Under the flag the store reads the cache branch whole, capped at three times `limits.maxPackBytes` (the pack and the progress v2Step accepts, plus framing), before the put, on top of the streaming verifier; an answer it refuses, and the answer to a request that is no fetch (ls-refs under a caller's `shouldCache`), is not stored and is counted in `stats.verifyFailed` (nothing was put, so no key is deleted); `stats.verifyOk` counts only the answers handed to `put`, not every answer the streaming verifier passed. When the `put` is called differs: without the flag it is called inside the fetch on every MISS, before the fetch answers (a `put` that throws when called is that fetch's `'cache.put'` Err, and the answer is cancelled first); with it, only once `verifyFetchAnswer` accepted the answer, after the fetch answered, so a `put` that throws or rejects then is `stats.putFailed` (`putError` the `'cache.put'` Err's message for a throw, the rejection's own message for a reject) and never a rejection of the fetch already returned. Off Workers, `memoryCache({ maxBytes, maxEntries })` is a store with the same shape: it keeps at most `maxBytes` of bodies and header text (default `LIMIT_MEMORY_CACHE_BYTES`, 64 MiB) in at most `maxEntries` entries (default `LIMIT_MEMORY_CACHE_ENTRIES`, 1024), evicts the least recently used first, and does not store an entry larger than the whole byte budget. A fractional budget is floored (`maxBytes: 100.5` is 100 bytes); a value that is not a finite, non-negative number (`NaN`, a negative, an infinity) falls back to the default, since the constructor returns no error. - `head`: the oid you believe the ref points at (your last `newCommit`). Skips ls-refs; receive-pack's compare-and-swap is the freshness check, and a stale hint is redone once from a real ls-refs (`result.hint` is `'used' | 'stale' | null`). Against github.com: 4 rtt / 549 ms cold → 3 rtt / 73 ms with both. `head` runs ls-refs concurrently with a speculative fetch of the hinted commit, so a stale hint is corrected before anything is pushed — same wall time as skipping ls-refs, one extra request, no wasted push. A `cas_conflict` (replica lag between ls-refs and receive-pack) is redone once, the retry's span linked to the first. Also: `client.discover()` is a capability canary (agent, object-format, `fetch=` features); push records the server's band-2 text in `git.push.remote.messages`; the blob hash uses native `crypto.DigestStream` where the platform has it. ## Reading without a clone `readFile(url, { ref, path }, opts)` → `{ ref, commit, blob, mode, size, stream }`: ls-refs → commit (`tree:0`, deepen 1) → one tree per level → the blob as a `ReadableStream`, hash-checked as it passes (the stream errors rather than ends if the bytes are not the blob's). The latest chunk stays until the object hash and the pack trailer verify, and a failure errors the stream without releasing it, so a consumer that received every byte saw a verified blob. `size` is known before the first byte. A `path` that ends in `/` names a directory and is `bad_request` (`what: 'path'`) before any request, as `git cat-file -t HEAD:file/` refuses it for a blob; earlier versions dropped the slash and read `file` (a breaking change, #300-8). `listTree` still reads `dir/` as `dir`, as git does for a tree. `openBlob(transport, oid, { maxBytes, follows })` opens that stream on a caller's transport for an oid it already resolved: `{ kind: 'stream', size, stream }`, or `{ kind: 'too_big', size }` when the object header's size is above `maxBytes`. The fetch is cancelled then (`git.read.blob.header_only`) and no body byte is delivered. `readBlob` is the same, buffered, and a pack that fails verification is an error rather than `bytes`. The stream is O(1) in memory but not unbounded on the wire: a blob whose pack exceeds `limits.maxPackBytes` (128 MiB; GitHub caps files at 100 MiB) is `limit_exceeded`, and one whose zlib stream runs past what its declared size allows (`zlibBound`, zlib's own `deflateBound`) is `pack_corrupt`, so a server cannot feed a reader forever. `listTree(url, { ref, path })` → `{ tree, entries: [{ name, mode, oid, type }] }` as `git ls-tree` prints them. `ref` is `HEAD` (default), a full ref, a short name (git's order: tags before branches), or a commit oid; tags are peeled. `resolveCommit(transport, ref, { abbrev: 'advertised' })` also takes a 4–39 character lowercase hex prefix when it matches one advertised tip (HEAD, branches, tags, and peeled targets) in that one ls-refs; a ref name wins, as in git. The default `abbrev: 'off'` keeps a short hex string as a ref name. `resolveAbbrev` is that step on an ls-refs answer (`unique_among_advertised`, `none`, or `ambiguous`). It is weaker than `git rev-parse`: an interior object is not a candidate. `import { readFile, listTree } from 'ply/read'` (36 KB min, no push or merge code). A `not_found` carries `miss` (`miss.kind`): a missing ref, an absent or unborn HEAD, a missing path, a file where a directory was required, a directory, a submodule, a commit (`miss.kind === 'commit'`, then `miss.miss` is `absent` or `not_commit`), or a repository 404. `readCommit` of an unborn HEAD, or of that branch by name, returns `{ empty: true, ref }` instead of `not_found`. `walkPath(transport, treeOid, comps, { cache })` walks a tree the caller already has. `walkCommit(transport, commitOid, comps, { cache, levels })` → `{ commit, data, tree, entry }` walks from a commit: on a server known to take `combine:blob:none+tree:K` (GitLab, Codeberg) the commit and its first `min(levels, 2)` tree levels come in one fetch, elsewhere it is the commit and one tree per level, as `readFile` reads them; `levels` defaults to `comps.length + 1`, and a tree that fetch brought but the walk did not read is answered by `fetchObject` with no request. `fetchCommit(transport, oid)` is that commit fetch for a 40-hex id: `{ oid, data, commit }`, or `not_found` with that commit miss. A corrupt pack stays `pack_corrupt`. `readCommit`, `readLog`, and `pickCommit` use that classification. The walk's first two tree levels ride with the commit (#218) where the server takes `filter combine:blob:none+tree:K` (git with `uploadpack.allowFilter`: gitlab.com, codeberg.org, a self-hosted git): one fetch brings the commit and every tree at depth < K, K = the levels the path needs, at most 2 (the root and its children). `readFile` at depth n is then 3 + max(0, n − 2) round trips instead of 3 + n, `listTree` 2 + max(0, n − 1) instead of 3 + n. Deeper levels are still one `tree:0` fetch each: K = 3 is the whole repository's second level (gitlab-org/gitlab: 526 KB and 566 trees, against 36 KB and 48 trees at K = 2), slower than the round trips it saves. The pack is checked as a `blob:none` pack is (hashes computed, every commit and tree against your limits, an extra over a limit dropped, a malformed object fails it) and its trees harvested for the walk. Whether a server takes it is learned from its answer and kept with the `quirks` record (not in it: the record's shape is unchanged); it is asked only once `tree:0` is known to work there, and the first time runs beside the `tree:0` commit fetch, so a refusal costs a request, not a round trip. GitHub refuses it (`filter 'combine' not supported`, `tree filter allows max depth 0`), so GitHub reads are unchanged; Artifacts sends every tree with a `blob:none` commit fetch already (3 round trips at any depth) and is never asked. A failed attempt is not used: the `tree:0` walk answers. Spans: `git.fetch.path_trees` (the filter sent) on that fetch. ### One object by id: `fetchObject` `fetchObject(transport, { oid, expectType, filter, deepen })` → `{ type, data, oid, size }` (`objectAt` is the same for an id already parsed). One object costs one object of pack, whatever the history behind it. By default (`deepen` left out or `null`) a want that may be a commit (`expectType` left out, `TYPE.COMMIT` or `TYPE.TAG`) is sent with `deepen 1`: git answers a commit want without a depth with every commit reachable from it (`filter tree:0` drops trees and blobs, not ancestors), so the pack grew with the repository's history and a large one was refused at `limits.maxInflatedTotal` (curl/curl: 64 MiB of commits for one commit). With `expectType` `TYPE.TREE` or `TYPE.BLOB` no `deepen` is sent: no history is reachable from a tree or a blob. To ask for history, say so: `deepen: n` is the commit and n − 1 generations of its ancestors, `deepen: 0` sends no `deepen` line (the whole history, held to the pack limits); a caller's `deepen` is always sent as given. The server's `shallow-info` section is read as protocol v2 defines it and nothing returned or kept says the repository is shallow (the result has no such field; the span carries the server's lines as `git.fetch.shallow`). An annotated tag want is answered by git with the tag and the one commit it peels to (two objects, where it was the tag and the whole history); `fetchObject` still refuses a two-object answer to a want that is not `expectType: TYPE.COMMIT` (`pack_corrupt`, `pack: expected 1 object, got 2`). A server whose advertisement lists no `shallow` on its `fetch=` line is not sent the default depth: after `discover()` none is sent; otherwise a first request it refuses (an empty response, an `ERR` line (`remote_error`) or HTTP 400) sends ply to the advertisement once per `quirks` record, and the want is asked again without `deepen`, once (the answer is then the history, and the limits refuse it honestly when it is too large). That request is the one sent before the default depth and its answer is read the same way: a server that also lists no `filter` is asked unfiltered, and one that refuses `tree:0` is asked with `blob:none`. If `shallow` is listed the first error stands; so an `ERR` line or a 400 for any other reason (a want the server does not have) costs one advertisement read, once per record. A 401, 403, 404, 429 or 5xx is never asked again, nor is a request whose `deepen` the caller gave. What the advertisement said about `shallow` is kept beside the `quirks` object, not in it: a consumer that rebuilds `quirks` from JSON relearns once per rebuilt object, which costs requests only on a server without `shallow`. The pack cache keys on the request body, so a `deepen 1` request never shares an entry with one that sent none: every request that now carries the default depth (untyped wants and `expectType: TYPE.TAG` included, not only commits) has a new key. ### Recent history: `readLog` `readLog(url, { ref, limit = 20 }, opts)` → `{ ref, oid, commits: [{ oid, tree, parents, author, committer, message, signed }], truncated }` (the commit view is `readCommit`'s). The order is **first parent, newest first**: exactly `git rev-list --first-parent -n `, the line a branch's history follows (one merge commit per landed branch). `parents` lists every parent. `truncated` is true when history continues past the last commit returned; fewer than `limit` commits with `truncated` true means the server's own repository is shallow there. One fetch: `want deepen filter tree:0`, commits only. A server that refuses `tree:0` (Artifacts) gets `blob:none`, learned once into `quirks`; that pack also carries every tree of the window, checked and harvested, so a following `listTree`/`readFile` on the same `transport` costs no round trip. Every object passes `assertFetched`, and the window is held to the deepen contract: a commit the server sent that is not an ancestor of `ref`, or a withheld parent without a `shallow` line, is `pack_corrupt`, never a short or foreign log. `limit` is 1 to `limits.maxMergeDepth` (1024); `path` filtering is not supported (`bad_request`): under `tree:0` the window has no trees. `import { readLog } from 'ply/log'` (43 KB min). Measured on a local mirror of curl (10 commits, served by `git http-backend`): `tree:0` 6,073 B, 10 objects; `blob:none` 128,965 B, 87 objects (10 commits, 77 trees), against 121,646 B for `blob:none` deepen 1. Tested in `test/log.test.js`: server (`tree:0`, `blob:none`-only) × shape (linear, merges, root within the limit, first-parent length equal to the limit, longer) × limit (1, n, larger than the history) × server behaviour (honest, shallow lines dropped, a foreign commit added) = 90 cells, each against git. ## Pushing a whole tree (deploy from a directory, no git binary) `pushTree(url, { ref, base?, files, author, message }, opts)` commits exactly `files` as the new tree, on the current head of `ref` (or `base`), and pushes it with the same rules as `editFile`: `head` hint, one fresh retry on `cas_conflict`, `strictHead`, `verify` (an acknowledged push that does not read back is `ambiguous`), `signer`, `cache`. An absent `ref` is created as a root commit (zero old oid: the CAS means "must not exist"). Identical files are `{ noop: true }`, nothing pushed. ```js import { pushTree } from 'ply/tree'; // Workers-safe import { pushDir } from 'ply/tree-node'; // Node: walks a directory (node:fs) await pushTree(url, { ref: 'refs/heads/main', author, message: 'deploy', files: { 'index.html': '

hi

', // string or Uint8Array → 100644 'bin/build': { data: script, mode: '100755' }, 'latest': { mode: '120000', data: 'v2/index.html' }, // symlink: the target is the blob 'vendor/lib': { mode: '160000', oid: submoduleCommit }, // gitlink: no data; the server need not have the commit } }, { auth, tracer, head: lastCommit }); await pushDir(url, { dir: './dist', ref: 'refs/heads/main', author, message: 'deploy' }, { auth, tracer }); ``` `files` is an object, a `Map`, or an iterable of `{ path, mode?, data?, oid? }`. Paths are validated like `editFile`'s (no `.git`, `..`, empty components); a path given twice, or as both a file and a directory, is `bad_request` before any request (git's fsck calls that tree `duplicateEntries`; `encodeTree` now refuses it too). `README` and `readme` are two names to git and are accepted: they collide only on a case-insensitive checkout. `encodeTree` (and so every tree `pushTree`, `commitChanges` and `mergeTrees` write) never writes a tree `git fsck --strict` refuses. Each entry is checked before a byte is written, and the first one that fails is `bad_request` with `what` naming the field: a name that is not a string or has no byte form (`tree entry name`); a mode that is not exactly `100644`, `100755`, `120000`, `40000` or `160000` (`mode`: zero-padded and non-canonical modes such as `040000` and `100664` are refused, not rewritten); an oid that is not 40 lowercase hex (`oid`); and, as `tree entry`, an empty name, a NUL or a `/` in a name, `.`, `..`, any spelling of `.git` that git checks (case-folded, NTFS short and stream forms, HFS ignorable code points, after a backslash), a name over 4096 bytes, the all-zero oid, `.gitmodules` as a symlink, tree or gitlink, `.gitattributes` as a tree or gitlink, and a duplicate name. A non-string name used to be encoded as its string form (`"5"`, `"undefined"`, `"[object Object]"`); it is now refused. `pushTree` refuses these with no request sent; `commitChanges` refuses them after its reads and before any push. The error does not grow with the name: the message quotes at most the first 200 UTF-16 units of a name or mode, followed by `… (N UTF-16 units)` when it was cut, and the `entry` field holds the same first 200 units, so match on `what` and the reason, not on the full name. The cut never splits a surrogate pair: when the 200th unit is the first half of one, 199 units are quoted, so a well-formed name gives a well-formed message and `entry`. A value that is not a string is named by its type (`object`, `bigint`) instead of being stringified. Each blob is bounded by `maxObjectSize`, the file count by `maxPackObjects`, each directory by `maxTreeEntries`. `treeSort(entries)` returns the entries (the same objects, any iterable of `{ mode, name }`) in git's tree order: by name bytes, a directory (`40000`) sorting as its name followed by `/`. It computes each entry's key once, before sorting, so it reads each `name` and `mode` once; the order is unchanged. Every name is therefore encoded: a name with no byte form (a lone surrogate) is `bad_request` for the first such entry in the order given, and a list of one such entry is now refused too (it used to be returned as it was, because a sort of one entry compares nothing). A name that is not a string (`null`, `undefined`, a Symbol, an object whose `toString` throws), or an entry that is not an object (`null`, `undefined`), is `bad_request` `tree entry name must be a string` at any list length, one entry included: the name is never converted to a string, so `treeSort` does not throw on it (a directory with such a name used to throw, or to sort as `null/`; a list of one such entry used to be returned as it was). Repeat pushes are thin: ply reads the parent's trees only where the new tree differs (one `tree:0` fetch per changed directory, cached by oid; on Artifacts the first `blob:none` fetch carries them all), sends only blobs no such tree names, and sends each changed tree as a `REF_DELTA` against the tree it replaces. Measured on a 208-entry tree (207 blobs, 26 trees) (`test/push-tree.test.js`): push 1 is 234 objects / ≈116.9 KB; push 2 (one file changed, one added, one deleted) is 7 objects / 1,176 B, exactly `git rev-list --objects new ^old`; push 3 (a one-byte change, `head` hint + `cache`) is 4 objects / 841 B with two upload-pack requests (ls-refs and the hinted commit, concurrent). Only the parent's trees are consulted, so a blob that exists on the server only in older history is sent again (correct, not minimal). Any push whose pack exceeds `limits.maxPackBytes` is refused before the upload starts: `limit_exceeded`, `what: 'push pack bytes'`, `got` = the measured pack size (set `maxPackBytes` a little under a host's cap: Artifacts allows 64 MiB, 67,108,864 bytes, of request body, which is the pack plus the command prefix, and the prefix grows with ref name length). `pushDir` / `filesFromDir(dir, { filter, limits })` read a directory as git's index would: the owner's execute bit makes `100755`, a symlink is `120000` with its target (never followed), empty directories vanish, `.git` is skipped, anything else (FIFO, socket) is `bad_request`. `filter(path, { directory, symlink })` → `false` leaves a path out; `.gitignore` is not read, and there is no `ply push` CLI. Gitlinks come only from `files` (`{ mode: '160000', oid }`): a nested checkout is walked as a plain directory. A tree oid from `filesFromDir` equals `git add -A && git write-tree` on the same directory (tested). File names: on macOS a name is recorded as `git add` records it under the configuration `git init` writes there (`core.precomposeunicode = true`), so a file created as `e` + U+0301 is `é` in the tree and in the `path` a `filter` sees, while the file is still opened by its name on disk. That is git's precompose, not Unicode NFC: a decomposed pair is joined, marks are never reordered, a character standing alone is never rewritten (KELVIN SIGN U+212A, U+0958 and U+F900 stay as they are), a name holding a code point beyond the BMP (an emoji) is recorded as read, and the Balinese pairs are not joined (tested against `git add -A` of git 2.50 on macOS only, over every code point NFC rewrites and the decomposed form of every precomposed character); on every other platform a name is recorded as the file system returns it. Neither rejects: a directory that does not exist, or a file that cannot be read, is `bad_request` with `what: 'dir'` and node's error as `cause` (before 0.2.0's Result contract was enforced here, they rejected as node:fs rejects). **Each object once.** `push` (`client.push`, and every command that pushes through it: `editFile`, `commitChanges`, `pushTree`, merge, rebase) sends a whole object that `objects` holds more than once a single time: the first copy, in its place, and an `ofs` base that named a repeat names the kept copy. A pack with one object twice is refused by a strict receiver (`git index-pack --strict`: "The same object … appears twice in the pack"). So `PushResult.entries`, the span's `git.push.pack.objects` (and its `git.push.pack.*` sizes) and the `git.push.object` events count the objects sent, which can be fewer than `objects.length`. Delta entries are sent as given; `planPush` returns the list as given; `pushPack` sends your pack untouched. ## Push a pack you already have (`pushPack`) A mirror relay, a bundle import or a pack cut from another pack does not need its objects in memory. `pushPack` sends a complete pack from a `ReadableStream`, with `push`'s command checks, capability checks and report handling: ```js const r = await pushPack(transport, { commands: [{ ref: 'refs/heads/main', oldOid: ZERO_OID, newOid: head }], pack: stream, // header, entries, trailer; read once length: packBytes, // optional: the pack alone, without the commands atomic: true, // optional, checked against the advertisement (as are pushOptions) }); ``` Memory is about two of the stream's chunks, whatever the pack's size (256 MiB measured, `test/push-pack.test.js`). `length`, when given, is checked against `maxPackBytes` before anything is sent and against the bytes as they go. Without it, the count is enforced while sending: the chunk that would cross `maxPackBytes` is never sent. The request is chunked either way (no `Content-Length`). A refusal before the request (a bad command, an over-cap `length`, a capability the server does not advertise) leaves the stream unread and unlocked, and the caller still owns it. So does a request that failed before the transport pulled the first chunk of its body (a signal that had already fired, a connect or DNS failure, a `fetchImpl` that rejects without reading the body, an HTTP answer that arrives with the body still unpulled): the server received no command list, so no ref can have moved, and the result is that failure itself, not `ambiguous`: `aborted`, `timeout`, `network`, or the answer's own code (`auth` for 401/403, `not_found` for 404, `rate_limited` for 429, `upstream_5xx`, `http` for a redirect, `not_git` for a 200 with the wrong content-type); the stream stays unread and unlocked unless the transport cancelled the body itself. From the first pull of the body the stream is spent: it is never retried, a request that did not finish it cancels it (asked once, with the failure as the reason when there is one, and never waited for: a stream whose `read()` or `cancel()` never settles does not hold `pushPack` past the server's report, your abort or a timeout), and every failure is `ambiguous`, with the first cause in `original` (`bad_request` for a wrong `length`, `limit_exceeded` for the cap, `internal` for a failed source). The last chunk is released only after the source has ended and its length has passed, so a refused pack never reaches the server whole. Ply does not parse or hash the pack: a corrupt one is refused by the server's report. ## Custom exchanges on a transport (`frames`) Every command in ply is one exchange on a transport: `t.frames(service, body, span, hints)` POSTs `body` to `service` and yields the response as pkt-line frames; `t.advertise(service, span)` is the info/refs GET. A request ply has no call for (a receive-pack with its own capabilities, a v2 command of your own) goes through the same method instead of a raw `fetch()`, and so gets what ply's calls get: - **auth** as configured on the transport, and **scrubbing**: no form of the credential reaches a span, a URL attribute or an error message, even one the server echoes back; - **remote text made printable, at the sites listed here**: text the server wrote is cut to at most 1024 UTF-16 units and then has every control, format and lone-surrogate character written as `\uXXXX` (tab and newline stay in running text; the rule is SAFETY.md I43) before it reaches an error message at these sites: an `ERR` line (capabilities, ls-refs, fetch), band 3 (fetch; push, in the `ambiguous` message), the HTTP error body (200 units) and content-type, a non-v2 first line, a refused acknowledgment line and a malformed ls-refs or receive-pack advertisement line (60 units), the section names of a fetch answer that has no packfile section (60 units each, at most 8 names), and the too-large push reason. The span attribute `git.push.band2.tail` is escaped the same way. These still carry the server's text as received, so escape them before printing: the span attributes `git.push.remote.messages`, `git.push.ng.reason`, `git.fetch.sections` and the fetch progress text (`git.sideband.progress.tail`), `hookOutput`, the `lines` and `rejected` detail fields, the ng reason quoted in a `push_rejected`, `cas_conflict` or `push_partial` message, and the object-format name in an `unsupported` message. A credential the server echoes in an `ERR` line (capabilities, ls-refs, fetch) or in band 3 (fetch, push) is redacted before the text is cut, so a cut that falls inside it leaves no part of it in the message; `v2Step`, `sidebandStep` and `parseCapabilitiesV2` take the scrubber as an optional last argument (none by default) for a caller that drives them itself. A message that quoted such a character raw before now shows the escape; - **spans**: `frames` fills the span you pass with `git.service`, `git.request.bytes` (a `StreamBody`'s `length`), `http.request.method`, `url.full` (redacted), `http.response.status_code`, `git.response.bytes`, `git.response.first_byte_ms` and the rest of the HTTP attributes (the telemetry contract below); - the transport's **redirect policy**, **limits**, **timeouts** (first byte, idle) and `signal`; - **typed errors**: a non-2xx, a foreign content type, a timeout, a network failure and a broken pkt-line are each a `PlyError` (`auth`, `not_found`, `http`, `not_git`, `timeout`, `network`, `protocol`, ...), thrown from the iteration (results never throw, streams error). What it leaves to you: the request's bytes (pkt framing, capabilities, a pack), what the reply means, and ending your span. `body` is bytes or a `StreamBody` `{ stream, length }`, read at the request's pace as it goes out (chunked). `length` is the figure the span reports, not a check: `frames` sends what the stream yields, so a stream that yields a different count, or bytes that are not a whole pack, is yours to catch (measured in the test: 7 extra bytes after a pack's trailer land, 7 short is git's `unpack failed`). A stream that errors midway ends the request: on Node, `fetch` rejects and `frames` throws `network` with your error on its `cause` chain; on workerd an errored request body can end as if it were complete. So a pack you are still producing should hold its last chunk back until it has checked the whole, and keep its own failure to report, as `pushPack` does (`streamSource` in `src/packwrite.ts`). Get a transport from `createTransport(url, opts)`, `GitHttp.create(url, opts)` (`.t`), or `transportFrom(record)` for a transport of your own. A receive-pack with a streamed pack, the report read with the exported step functions (this block is executed by `test/custom-exchange.test.js` against `git http-backend`, with the error paths beside it): ```js // custom-exchange: receive-pack import { createTransport, Tracer, KIND, ZERO_OID, TYPE, buildPack, hashObject, encodeTree, encodeCommit } from 'ply'; import { frames } from 'ply/transport'; import { pushBody, streamInit, streamStep, streamFinish, classifyReport } from 'ply/push'; // what to send: a root commit holding one file const file = new TextEncoder().encode('hello\n'); const tree = encodeTree([{ mode: '100644', name: 'hello.txt', oid: hashObject('blob', file) }]); if (!tree.ok) throw tree.error; const made = encodeCommit({ tree: hashObject('tree', tree.value), author: 'Me 1700000000 +0000', message: 'hello\n' }); if (!made.ok) throw made.error; const commit = hashObject('commit', made.value); const objects = [{ type: TYPE.BLOB, data: file }, { type: TYPE.TREE, data: tree.value }, { type: TYPE.COMMIT, data: made.value }]; const spans = []; const t = createTransport(url, { ...opts, tracer: new Tracer({ onEnd: s => spans.push(s) }) }); if (!t.ok) throw t.error; // the request: the commands as pkt-lines and a flush, then the pack, as one stream of known length const commands = [{ ref: 'refs/heads/main', oldOid: ZERO_OID, newOid: commit }]; const prefix = pushBody({ commands, caps: ['report-status', 'side-band-64k', 'agent=me/1'] }); if (!prefix.ok) throw prefix.error; const { pack } = await buildPack(objects); const stream = new ReadableStream({ start(c) { c.enqueue(prefix.value); c.enqueue(pack); c.close(); } }); const body = { stream, length: prefix.value.length + pack.length }; const span = t.value.tracer.start('custom receive-pack', { kind: KIND.CLIENT, scrub: t.value.scrub }); let reply = streamInit(true); // side-band-64k: the report in band 1, progress in band 2 try { for await (const f of frames(t.value, 'git-receive-pack', body, span)) { const stepped = streamStep(reply, f); if (!stepped.ok) throw stepped.error; reply = stepped.value; } } catch (e) { span.error(e); throw e; } finally { span.end(); } const done = streamFinish(reply); if (done.tag !== 'report') throw new Error(`no report: ${done.why}`); const report = classifyReport(done.lines, commands); // { tag: 'statuses', refs: [{ ref, ok: true, reason: '' }] } if (report.tag !== 'statuses' || !report.refs.every(r => r.ok)) throw new Error(`refused: ${JSON.stringify(report)}`); ``` **`encodeCommit` is held to the reader.** `encodeCommit({ tree, parents?, author, committer?, encoding?, extra?, message? })` returns a `Result` and never throws. As `encodeTag` does, it parses what it built with `parseCommit` and returns `bad_request` (`what: 'commit'`, or the field that would not read back) for a commit git or ply would not read back as the one given: an `author` or `committer` that is not an ident line `git fsck` accepts (`Name <+hhmm>`; build one with `ident(validateIdent(…))`), an `extra` line that starts `tree `, `parent `, `author `, `committer ` or `encoding ` (pass the encoding as `encoding`), and an empty `extra` line (it would end the header and turn the lines after it into message text). Before this, those inputs returned `ok` with bytes `git hash-object` refuses or `parseCommit` reads as `pack_corrupt`. Every commit it returns is stored by `git hash-object -t commit` byte for byte. **Stability.** `Transport` (`kind`, `url`, `tracer`, `parent`, `limits`, `signal`, `quirks`, `objects`, `scrub`, `frames`, `advertise`) is the public contract every command is written against, and the `ply/transport` exports `frames`, `advertise` and `transportFrom` are public API: a change to their shape is a breaking change, named in the release notes (ply is pre-1.0, so a minor version may carry one). `Frame` and `StreamBody` are part of it. The step functions used above (`pushBody`, `streamInit`/`streamStep`/`streamFinish`, `classifyReport`, `pktStep`, `v2Step`, `sidebandStep`) are public too, but they are protocol codecs: they follow git's wire format, and their states are opaque records you pass back, not fields to read. The HTTP implementation behind `frames` (`createTransport`'s internals, its retry and redirect memo) is not: depend on what it does, as described here, not on how. Before writing an exchange, check for the call that already does it: a pack you have is `pushPack`, objects are `push`, a fetch is `packStream`/`fetchPack`, refs are `lsRefs`, capabilities are `discover`/`receiveCaps`. Those add what a raw exchange does not: command and capability checks, a push's outcome rule (a report read exactly as git writes it, everything else `ambiguous`), and the cancel-and-release rules for a streamed pack. ## Push a whole local repository (history, no git binary) `pushRepo(dir, url, { refspecs?, all?, tags?, force?, dryRun?, thin? }, opts)` is `git push ` from a machine with Node and no git: it reads `dir`'s `.git` itself (a work tree, a linked worktree or a bare repository: loose objects inflated and hash-checked, every packfile parsed and resolved, `packed-refs` and loose refs, `HEAD`), asks the remote for its refs (one ls-refs), and sends one receive-pack request for every command. Example: [`examples/push-repo.mjs`](examples/push-repo.mjs). ```js import { pushRepo } from 'ply/repo-node'; // Node: reads .git (node:fs) const r = await pushRepo('./repo', url, { refspecs: ['main', 'v1.0', '+wip:refs/heads/backup', ':stale'] }, { auth }); if (r.ok && r.value.upToDate) console.log('Everything up-to-date'); // nothing was sent await pushRepo('./repo', url, { all: true, tags: true }, { auth }); // every branch and tag ``` Refspecs are git's: `src`, `src:dst`, `+src:dst` (forced), `:dst` (delete). `src` resolves as git resolves a name (`x`, `refs/x`, `refs/tags/x`, `refs/heads/x`, `refs/remotes/x`, `refs/remotes/x/HEAD`; a name given in full or from `refs/`, a branch and a tag outrank a `refs/remotes/` match, as in git's `count_refspec_match`, so a branch `foo` beside a remote named `foo` is the branch, and two matches of the same rank, a branch and a tag, are `bad_request`; a ref directly under `refs/`, such as `refs/stash`, is not counted, as git's `one_local_ref` leaves it out, so a branch `stash` in a repository that has run `git stash` is the branch, and such a ref is the source only when it is named in full or nothing else matches; tested against `git push --dry-run`), `HEAD` is the current branch, a 40-hex id needs a full `dst`, and a missing `dst` is the same ref. Under `refs/`, an entry that is not a ref to git is not one to `pushRepo`: a file or directory whose name starts with `.` or ends in `.lock`, and a file whose full name `git check-ref-format` refuses (Finder's `.DS_Store`, `bad~name`), are left out whatever they hold, as `git push` leaves them out (tested against `git push --dry-run`); a well-named ref file that holds neither an id nor `ref: ` is still `bad_request`, `what: 'ref'`. A loose ref that is a symbolic link is read as git reads it: a link whose target text is a ref name (`refs/heads/main`) is a symbolic ref to that name, any other link is the file it points at, and a link that points nowhere is not a ref (tested against `git push --dry-run`). One known difference from git: while a symbolic link to a directory exists anywhere under `refs/`, every `pushRepo` from that repository fails with `bad_request`, `what: 'ref'`, and the link as `path`, even a push of an unrelated ref, where git walks into the link and pushes (a link can loop, so ply refuses the repository by naming the link rather than leave the refs behind it out). A short `dst` is the branch or tag the remote has by that name, else the kind of `src`. With no refspecs (and neither `all` nor `tags`) the current branch goes to the same name. The pack is what the remote lacks: everything reachable from the new tips minus everything reachable from the remote's refs that the local repository has (exactly `git rev-list --objects --not `; gitlinks are not followed). A non-fast-forward update of a branch, an update of a ref whose tip the local repository lacks (git's "fetch first") and any change to an existing tag are refused before anything is sent — `not_fast_forward`, naming every refused ref, the same code a server's own non-fast-forward refusal carries — unless the refspec has `+` or `force` is set; none of the other refs are sent then either. Refs already at their target are `current`; when every ref is, the result is `upToDate` and no receive-pack request is made. `dryRun` makes the same decisions and counts the objects, and sends nothing. The result: `{ upToDate, dryRun, updates: [{ ref, oldOid, newOid, kind: 'create' | 'update' | 'force' | 'delete' }], current, objects, deltas, thinDeltas, rawBytes, packBytes }`; spans `git.push_repo` → `git.push_repo.read`, `git.push_repo.plan`, `git.receive-pack`. The pack is delta-compressed (`planDeltas`, `encodeDelta` in `ply`, a block-hash copy/insert generator in the shape of git's `diff-delta.c`): each tree and blob is tried against the previous version of the same path in the pack, then of the same file name (a rename), as an `OFS_DELTA`, kept only when it is under half the object, with chains of at most 50. Commits and tags are stored whole. `thin: true` also deltas the first version of each path against the remote's copy (`REF_DELTA`): `git push` sends thin packs and receive-pack completes them (`index-pack --fix-thin`), but ply cannot prove a host it has not seen does, so it is opt-in. Measured on this repository's own history (`test/push-repo.test.js`, against a stock `git http-backend`; `git push`'s pack is `git pack-objects --revs --thin --delta-base-offset`): `HEAD~50` to an empty remote, 957 objects, 1,394,379 B against git's 1,546,809 B (every object whole, as before: 4,513,180 B); then `HEAD` on top, 1,576 objects, 845,188 B thin against git's 856,093 B (1,512,574 B without `thin`, against git's 1,443,193 B non-thin; whole: 8,517,408 B). Memory: every packfile is resolved in memory (no `.idx` is read), so it suits repositories up to a few hundred MB. It fails closed with `limit_exceeded`: the objects held by `maxInflatedTotal` (256 MiB by default), their count by `maxPackObjects`, each by `maxObjectSize`, the pack sent and each local packfile by `maxPackBytes` (128 MiB by default; a local `.pack` is held whole while it is parsed, so one past the bound is refused from its size, before a byte of it is read: `what: 'local pack bytes'`; one exactly at the bound is read), the refs by `maxRefs`. For a larger repository raise all three of `maxInflatedTotal`, `maxPackObjects` and, when a single `.pack` is over 128 MiB, `maxPackBytes`: the process then holds that much, so this is for a repository that fits in memory. One that does not goes through the range-reader pipeline instead (`scanPackIndex`, `resolvePackRange`, `planPackBatches`, `packSubset` over a `RangeSource`, below), which holds no pack whole. With `maxPackBytes` raised past 2 GiB a pack of 2 GiB or more is read in pieces of at most 1 GiB (node aborts the process on a single read of 2^31 bytes or more), and a file the runtime cannot allocate one buffer for is `limit_exceeded` (`what: 'local pack buffer bytes'`, `got` the file's size), never a crash. Every other file `pushRepo` reads whole is bounded the same way, from its size, before a byte of it is read (one exactly at the bound is read; `limit_exceeded` with `got` the file's size): a loose object file by the longest zlib stream an object of `maxObjectSize` can have (`zlibBound(maxObjectSize + 32)`; `what: 'local loose object bytes'`), `packed-refs` and `config` by `maxLsRefsBytes` (128 MiB by default, the bound a ref listing has on the wire; `what: 'local packed-refs bytes'`, `'local config bytes'`), and the one-line files, a loose ref file, `HEAD`, `commondir` and a `.git` file, by 65 520 bytes (the pkt-line maximum, not configurable; `what: 'local ref file bytes'`, `'local HEAD bytes'`, `'local commondir bytes'`, `'local .git file bytes'`). A text file within a raised bound that the runtime cannot hold as one string (node: 512 MiB) is `limit_exceeded` too (`what` ending `buffer bytes`), so none of these files makes `pushRepo` reject. One of them that cannot be opened or read is treated as absent, as before. A packfile the file system will not give (`EACCES`, `EIO`, …) is `unsupported` with `kind: 'filesystem'`, `what: 'local pack'`, the `path`, and the node:fs error as `cause`, never a rejection. Refused with `bad_request` and `what`: SHA-256 repositories (`objectFormat`), reftable (`refStorage`), partial clones (`partialClone`), `objects/info/alternates` (`alternates`), shallow repositories (`shallow`), a ref file that is not an id or a symbolic ref (`ref`); a missing object is `bad_request` (`what: 'object'`), a loose object that does not hash to its name `pack_corrupt`. ## Mirror one ref between remotes `syncRef(srcUrl, dstUrl, { ref, dstRef?, force? }, opts)` keeps `dstRef` (default `ref`) on the destination equal to `ref` on the source: `git fetch ` then `git push --force-with-lease=: `, with no clone (`src/sync.ts`). One ls-refs on each side; equal tips are `in_sync` and nothing else is sent. Otherwise one fetch from the source with the destination's tip as the `have`, and one receive-pack command whose old id is that tip (zero: a create). The pack pushed is the source's pack as received, delta for delta and never thin, so it holds only what the source computed the destination lacks: nothing reachable from the destination's tip when the source has that commit (a source that does not NAKs the have and sends the whole history, which is still correct). Each remote has its own `auth`, `fetchImpl`, `quirks` and `transport` under `opts.src` and `opts.dst` (a top-level `auth` names neither and is `bad_request`); `tracer`, `parent`, `signal`, `limits` (`maxPackBytes` bounds the pack both ways) and `verify` are shared. Example (run as written by `test/sync-ref.test.js`): ```js // sync-ref example import { syncRef } from 'ply'; const r = await syncRef(srcUrl, dstUrl, { ref: 'refs/heads/main' }, { src: { auth: { token: process.env['SRC_TOKEN'] } }, // read with one credential dst: { auth: { token: process.env['DST_TOKEN'] } }, // write with another }); if (!r.ok) throw r.error; // not_fast_forward: the source was rewritten (force: true follows it); cas_conflict: the mirror moved if (r.value.outcome === 'in_sync') console.log('in sync at', r.value.oid); else console.log(r.value.outcome, r.value.from, '->', r.value.to, `${r.value.objects} objects, ${r.value.pushBytes} B`); ``` The result is `{ outcome: 'in_sync', ref, dstRef, oid }` or `{ outcome: 'created' | 'updated', ref, dstRef, from, to, forced, objects, pushBytes }`. An update that is not a fast-forward (a rewritten or diverged source, a destination ahead of it) and any change to an existing tag are `not_fast_forward` before anything is pushed, unless `force: true`, which pushes the source's tip with the same compare-and-swap. A push that loses the race to another writer is `cas_conflict` with `expected` the tip ply read and `actual` the destination's tip read back (null: deleted), as `createBranch` and `deleteBranch` report one. Spans: `git.sync_ref` → two `git.upload-pack ls-refs` (one per remote), `git.upload-pack fetch`, `git.receive-pack`. ## One commit from a change list `commitChanges(url, { ref?, base?, changes, author, committer?, message, time? }, opts)` writes one commit. `changes` is applied in order: `create` (refuses a path that already exists; `write` overwrites, which is what `git add` does), `edit` (exactly one non-overlapping match, or `match_count`), `delete` (a file or a directory; empty directories are pruned), `rename`. Modes are `100644`, `100755` and `120000`. A `mode` you give always wins. With no `mode`, a `write` over an existing regular file keeps that file's mode (a `100755` script stays executable, as rewriting a file's content does in git), and a `create`, or a `write` to a new path or over a symlink, is `100644`; to clear the executable bit pass `mode: '100644'`. So a mode-less `write` of identical bytes over a `100755` file changes nothing (`noop` on an existing ref). A single `edit` of an existing blob goes through `editFile`, so a large file stays a stream; every other list is an in-memory tree of the paths it touches. `ref` defaults to the remote HEAD, born or unborn (an empty `git init --bare -b main` commits `refs/heads/main`; a symref to a branch with no commit does the same). A detached HEAD is `bad_request`. A server that will not name an unborn HEAD is `not_found`. Pass `ref` for either. `base` defaults to that ref's tip. Another ref creates `ref` from it (an annotated tag is the commit it names, here and as an `editFile` base) and is `cas_conflict` (`expected` the zero id, `actual` the tip) when `ref` already exists. A 40-hex `base` is that commit — lowercase, as everywhere else in ply — and `bad_request` when the target exists at a different tip. The compare-and-swap is the one the call read first: a `ref` that was absent then is pushed with the zero old id on every path (a single streamed `edit` too, from a ref or a 40-hex `base`), so a ref another writer creates meanwhile, even at the base commit, is `cas_conflict`, never a commit on top of it reported as `created`. The zero id is `bad_request` before any request. An absent ref with no `base` is a root commit. A result tree equal to the parent does not write an empty commit: an existing ref returns `{ outcome: 'noop' }`; a new ref is `bad_request` (`nothing to commit`) and stays absent. `head` is the tip the ref must have, or the zero id when it must be absent; a mismatch is `cas_conflict` and is not retried. A lost push reads the ref back, so `actual` is the oid that won. With no `head` a commit on a ref that existed is last-writer-wins, the same way for a single streamed `edit` and for an in-memory change list: when its push loses to another writer (the ref moved, or was deleted) the call reads the ref again and redoes the commit once against what is there (`git.commit.attempt` is 1 on the span). A ref deleted meanwhile under a 40-hex `base` is created again from that commit (`created: true`, `oldOid: null`); a ref that moved is committed on its new tip, or is `bad_request` under a 40-hex `base` it no longer matches. With `head`, the same race is `cas_conflict` (`actual` null for a deleted ref) and the ref stays as the other writer left it. `author.time` and `committer` are separate stamps. `import { commitChanges } from 'ply'`. `editFile` accepts the same 40-hex `base` (the commit to edit) and an optional `committer`. A `base` ref that is an annotated tag, or a tag of a tag, is the commit git peels it to (where `git branch ` starts the branch). A commit id that is not the tip of an existing ref is `bad_request`. ## Checking out a whole tree (no git binary, no clone) `checkoutTree(url, { ref, path? }, opts)` → `{ ref, commit, tree, path, entries, files }`: ls-refs → one `blob:none` fetch of the commit (deepen 1: the commit and every tree under it — on Artifacts, the only filter it serves anyway) → the blobs, up to `batch` (default 1,000) wants per request. `entries` is every non-tree entry under `path` as `[{ path, mode, oid }]` in `git ls-tree -r` order, paths relative to `path`; `files` is an async iterator of `{ path, mode, oid, size, stream }`. Modes are git's canonical `100644`, `100755`, `120000` (a symlink: the stream is its target) and `160000` (a gitlink: `size` 0, `stream` null, the submodule's commit is not in this repository). ```js import { checkoutTree } from 'ply/checkout'; // Workers-safe import { checkoutDir } from 'ply/checkout-node'; // Node: writes a directory (node:fs) const r = await checkoutTree(url, { ref: 'main', path: 'site' }, { auth, tracer }); if (r.ok) for await (const f of r.value.files) if (f.stream) await env.BUCKET.put(f.path, f.stream, { httpMetadata: { contentLength: f.size } }); const done = await checkoutDir(url, { dir: './out', ref: 'v1.2.0' }, { auth, tracer }); // == git clone, minus .git ``` Every object is checked against its oid: a blob batch is delta-resolved and keyed by computed hash before any file is yielded (an object nobody asked for is `pack_corrupt`); a blob fetched alone streams through `readFile`'s verifier (the stream errors rather than ends on wrong bytes). A batch that hits `maxPackBytes`, `maxInflatedTotal` or `maxObjectSize` is split in half and refetched, down to single blobs, which stream in O(1) memory (a single blob whose pack is over `maxPackBytes` is `limit_exceeded`: every fetch, streamed or not, delivers at most that much pack); a host that refuses a many-wants fetch (an HTTP error, `ERR`) gets one blob per request from then on (`quirks.blobWants = 'single'`). A wrong blob is never a reason to fall back. Entries walked are bounded by `maxPackObjects` (a tree reused at many paths cannot multiply past it), depth by `maxPathDepth`, and a tree naming one entry twice (a symlink `a` beside a directory `a`) is `pack_corrupt`. Measured against `git http-backend` (`test/checkout-tree.test.js`, 22 entries: nested and unicode paths, exec bits, four symlinks, a gitlink, a 3 MiB blob, one blob at two paths): 3 requests (ls-refs, trees, blobs), the same behind an Artifacts-like `blob:none`-only proxy, against 72 for the per-file loop (`readCommit` → `listTree` per directory → `readFile` per blob, as the first `examples/checkout-tree.mjs` did, before `checkoutDir`). A commit oid as `ref` skips ls-refs. `checkoutDir` / `writeFiles(dir, files)` lay the files out as `git clone` does — `diff -r --no-dereference` identical to a clone of the same ref, permission bits included (100755 is created 0777 & ~umask, others 0666 & ~umask; symlinks never followed; a gitlink is an empty directory). `dir` must be absent or empty. Paths go through `validatePath` again (no `..`, absolute, empty or `.git` component); each directory is made one level at a time and must be a real directory (a symlink there — one this checkout made, or the same name on a case-insensitive filesystem — is `bad_request`, `what: 'checkout path'`); files are opened `O_EXCL`, so nothing is overwritten or written through a link. A file whose stream fails verification is removed before the error is rethrown; a checkout that throws leaves `dir` partial. No index, no `.git`, no working-tree updates: a one-shot materialisation. ## Hosts that refuse `filter tree:0` (Cloudflare Artifacts) Artifacts advertises `fetch=filter` but answers anything other than `blob:none` with `400 … only blob:none is supported`. ply learns that from the answer (not the host name), sets `quirks.treeFilter = 'blob:none'` on the transport and asks for `blob:none` from then on: a commit want then returns every tree of the commit, which ply delta-resolves, hash-checks and keeps (up to `limits.maxHarvestBytes`) so the deeper levels cost no round trip. The 400 is paid once per remote: a call that passes no `quirks` uses a record ply keeps per remote (origin + path, never the credential or query; the 256 most recently used remotes, per process or Workers isolate), and concurrent first requests wait for the one that finds out instead of each paying it. A `quirks` object you pass wins and is filled in place (pass a fresh `{}` to opt a call out of the shared record); `forgetQuirks(url)` drops one remote's record and `forgetQuirks()` all of them (a server reconfigured, a test faking several servers at one URL). A stale record costs bytes, never correctness. Cost: measured 8.9× the bytes of `tree:0` on a small repo; a merge-base walk ships every tree of every commit in its window. Spans say so (`git.fetch.filter.fallback`, `git.fetch.wide.extra_bytes`). A server whose upload-pack advertises no `filter` at all (a stock `git http-backend`: `uploadpack.allowFilter` is off by default) gets `quirks.treeFilter = 'none'`: a filtered fetch that comes back empty triggers one advertisement read, and with no `filter` on its `fetch=` line the request is retried unfiltered (`discover()` sets it too; an advertisement that lists `filter` again turns it back to `tree:0`). Unfiltered fetches carry objects a filter would have left out, so reads there cost more bytes; the results are the same. Artifacts rejects stale ref updates as `ng stale ref`, which is `cas_conflict`. Other observed Artifacts behaviour: an unknown want is an HTTP 500 (not `ERR`), HEAD follows the first-pushed branch and can be unborn, a receive-pack GET carrying `Git-Protocol: version=2` is answered with a v2-style list that names no push capabilities (so ply sends that header for upload-pack only, as git does), a push is capped at 64 MiB (67,108,864 bytes) of request body, pack plus command prefix, HTTPS only. Its [limits page](https://developers.cloudflare.com/artifacts/platform/limits/) also caps a push at 50,000 objects and 1 MiB of ref updates, and a file at 32 MiB. ## Branches and merging (git operations only) - `editFile(url, { ref: 'refs/heads/feature', base: 'refs/heads/main', … })` builds the commit on `base`'s head and *creates* `ref` (zero old-oid: the CAS means "must not exist yet"). - `mergeBranch(url, { ref, from, author })` lands `from` into `ref`: merge-base via commit-only packs, then `up_to_date` / `fast_forward` (empty pack — the server has every object) / a merge commit with parents `[ours, theirs]` from a three-way tree merge (git's trivial-merge rules per directory, only differing subtrees fetched). A file both sides changed is merged **line by line with a port of git's xdiff** (`linemerge.js`: histogram diff with its classic-Myers fallback, group compaction, zealous conflict refinement — what merge-ort runs), so a clean result is byte-for-byte git's; anything else is `merge_conflict` with the paths and a reason per path (`content`, `binary`, `too large to merge`, `undecided`, `possible rename …`). Git changed its compaction in 2.54; `rediff: 'myers'` (default) matches git ≥ 2.54, `'skip'` older git, `'undecided'` conflicts wherever the two differ. `.gitattributes` merge drivers apply when you say which tree supplies them — `attributes: 'ours'` (what `git merge` in a worktree reads), `'theirs'`, `'base'`, a ref or commit (`attr.tree`), or `null` (default: none, as git ≥ 2.46 does in a bare repository): `-merge`/`binary` conflict, `merge=union` keeps both sides. The merge base is git's (`merge-base --all`); a criss-cross history with two bases is refused rather than merged against one. The remaining supersets are renames (no rename detection: the guards conflict instead) and criss-cross. The rename guard is by path, not by similarity: a path neither side holds any more (deleted on both sides anywhere in the tree, including inside a directory both sides changed to the same tree, or a file one side replaced by a directory of its name) beside any added path is `merge_conflict`, whether or not git would pair them as a rename. So a merge, rebase or cherry-pick whose delete the target already has is refused when either side also added a file (git: clean, or an empty pick). `conflicts` lists each path once, with the reason the tree walk gave it if it had one. A merge with no directory both sides changed identically reads no tree for this. One with such directories can cost extra tree reads even when it is clean: the guard must rule out a path lost on both sides inside them beside a path one side alone added or removed, so it reads either those directories (base's copy and the shared one) or the directories only one side changed (base's copy and that side's), whichever are fewer, and the other set only if the first cannot rule it out; sibling directories 8 at a time, no tree twice (40 identically changed directories beside 40 one side edited: 83 tree reads, not 3). `fastForwardOnly`, `noFastForward`, `signer`, `verify`, `limits.maxMergeBlobBytes` (8 MiB). The line merge's work is bounded too: it counts its diff steps and stops at `limits.maxMergeWork` steps per merged file (2^32 in `DEFAULT_LIMITS`, 2^26 in `WORKER_LIMITS`), answering `too large to merge` — a file whose histogram diff goes quadratic (every adjacent pair of lines swapped: ~0.75 n² steps, so past ~75,700 lines at the default and ~9,450 in a Worker) is refused at the budget instead of merged in minutes; `mergeLines`/`diffScript` take `maxWork` (the same budget, absolute, for that call) and a `meter` (`{ steps }`) to change and read it. The count is kept inside the call, from zero: the `meter` is only written (its `steps` is set to that call's total on every return, refused or not, and to 0 when the call returns before any diff: binary content, an input over `maxBytes`, `driver: 'binary'`) and never read, so one meter reused across files, or one that is not an object (an array is one and gets a `steps` property; a function is ignored), changes no result, and a meter whose write throws (a setter, a Proxy's `set` trap, a revoked Proxy) is dropped with the result unchanged; a `maxWork` that is not a non-negative finite number (`NaN`, `Infinity`, a negative, a string) reads as the default, and a `limits.maxMergeWork` that is not one is `bad_request` like any other limit. Neither function throws on any `meter` or `maxWork` value (an unknown `driver` still throws). The count covers the classic-Myers fallback's whole work as well (the class counts, the trim, the cleanup's neighbour scans of up to 100 lines each way, every diagonal, snake and heuristic pass of the search, each box's trim and marks), not only its diagonals, so a low-variety file (a few distinct lines, each more than 64 times) spends the budget as it spends CPU: its counts are higher than they were (two unrelated 10,000-line `a`/`b`/`c` files: 5,370,282 steps for the diff) and such a file reaches `too large to merge` sooner. - `createBranch(url, { ref, from })`, `deleteBranch(url, { ref, expected? })` and `createTag(url, { name, target, message?, tagger? })` manage refs by URL (`src/refops.ts`): one receive-pack command each, no objects except an annotated tag's tag object. `from`/`target` is a ref name (resolved as `readCommit` resolves one; an annotated tag is peeled) or a 40-hex commit id the server must have. A ref that already exists is `cas_conflict` (`expected` the zero id, `actual` its tip), as a create is in `editFile`; a delete whose `expected` is not the tip is `cas_conflict` before anything is sent, and one that loses a race to another writer after ls-refs is `cas_conflict` with `actual` the ref read back (null only when it was deleted); an absent ref is `not_found`; what the server refuses (deleting the branch HEAD names) is its `push_rejected`. `verify: true` reads a created ref back. On a transport you already hold: `fastForward(t, { ref, from, to })` and `deleteRef(t, { ref, oid })`. - `rebaseBranch(url, { ref, onto, committer })` replays the branch's linear chain onto `onto`'s head (per commit: three-way of parent-tree / new-tip / commit-tree; author and message kept, committer ours, signatures dropped as git does) and force-updates the branch with its old tip as the CAS; commits that become empty are dropped as git's `--empty=drop` does and listed in `dropped`. One difference from `git rebase` stands: git leaves out a commit whose patch id equals a commit already in `onto` before it replays anything (its default, `--no-reapply-cherry-picks`); ply computes no patch ids and replays every commit, which is `git rebase --reapply-cherry-picks`. The results are equal while the upstream copy is in place (the replay comes out empty and is dropped) and differ when upstream applied the patch and later reverted it: git leaves the commit out, ply applies it again (and a replay git would have skipped can conflict). `squash: true` makes one commit; its default message is the replayed messages joined by blank lines (what `git rebase -i` writes for pick, squash, …). `cherryPick` / `revertCommit` are the same primitive with one commit. Merge commits in the chain → `not_linear`. A root commit (no parent) is picked and reverted against the empty tree, as git does. `empty: 'keep'` writes the commit when the result tree is already the target's (`git cherry-pick --keep-redundant-commits`, which also keeps a commit that was empty to start); the result is `outcome: 'kept_empty'`. The default `empty: 'stop'` reports `outcome: 'empty'` and writes nothing. The kept commit is built by the same path as a non-empty one: a cherry-pick keeps the picked author line (name, email, time, zone) and message, a revert uses the reverting author and git's `Revert ""` message, and the committer stamp is the caller's. - One primitive underneath all of it — the three-way tree merge, with the line merge for files both sides changed — with different arguments: | op | base | ours | theirs | commit | |---|---|---|---|---| | merge | merge-base tree | main | branch | parents `[main, branch]` | | rebase (per commit) | commit's parent tree | new tip | commit | parent `[new tip]` | | squash | merge-base tree | main | branch tip | parent `[main]` | | cherry-pick | commit's parent tree (empty tree, if the commit is a root) | target | commit | parent `[target]` | | revert | commit tree | target | commit's parent tree (empty tree, if the commit is a root) | parent `[target]` | - A pull request is a GitHub API object around such a branch; that call is outside this library. ## SSH SSH transport removed 2026-10-31; history on branch archive/ssh. ## Guards and policy - **LFS pointers** are refused (`lfs_pointer`): the file's content is in the LFS store, and editing the pointer corrupts it. The check is on the blob's first bytes (`version https://git-lfs.github.com/spec/v1`), which are streaming past anyway, so it costs nothing; `allowLfsPointer: true` opts in to editing the pointer itself. - **Signed commits**: pass `signer` (from `ed25519Signer({ privateKey, publicKeyRaw })` or `generateSigner()`) and the commit carries an SSH signature (PROTOCOL.sshsig, Ed25519 via WebCrypto — Workers and node). Verified by `git verify-commit` and `ssh-keygen -Y verify` in `test/sign.test.js`; satisfies "require signed commits" branch protection with the public key registered as a signing key. `signCommit(commitBytes, signer)` and `withGpgsig(commitBytes, signature)` sign any encoded commit, including one with no body section (`encodeCommit` with no `message`): the signed object without its `gpgsig` header is the input byte for byte. (Before, such a commit came back with a blank line added after the headers, so `git verify-commit` rejected its signature.) - We identify as `ply/0.2.0`, not as git. ## Layers ``` operations edit · push tree · merge · rebase · cherry-pick · revert operation.js: root span, transport, outcome, verify rule commands lsRefs · packStream/fetchObject · fetchPack/negotiate · push · discover · receiveCaps free functions over a transport transport the contract (transport.js): t.frames(service, body, span, hints) · t.advertise(service, span) implementation: http.js (one POST per command) protocol pure step functions: pktStep · v2Step · spStep · scanStep · streamStep · reportStep · threeWay · decideHead codecs pktline · inflate · sha1 · objects · pack (delta/build) · validate errors errors.js: every code, its retry policy; errors-doc.js: what each means ``` Each layer is testable without the one below it, and `test/bundle.test.js` asserts the dependency direction. Transport hints are neutral (`{ bypassCache }`), not headers; transport-specific detail goes under `http.*`, the neutral facts under `git.transport`, `git.request.bytes`, `git.response.bytes`, `git.response.cache`. ## Telemetry conventions (enforced by `test/pure.test.js` and `test/span-contract.test.js`) - Span names: `git. ` for wire round trips (`git.upload-pack ls-refs`, `git.upload-pack fetch`, `git.receive-pack`); `git.` for operation roots (`git.edit`, `git.commit`, `git.push_tree`, `git.checkout`, `git.read_log`, `git.merge`, `git.rebase`, `git.cherry_pick`, `git.revert`, `git.branch_create`, `git.branch_delete`, `git.tag_create`); `git..` for their children. - Attribute keys: dotted lowercase under `git.` `http.` `url.` `server.` `mem.` `error.` `ply.` `exception.`. - Every trace root (operation roots and the spans that follow them, below) carries `.outcome` (`ok`, `noop`, `fast_forward`, `cancelled`, …, or the error code). - On the HTTP transport (`createTransport`), every wire span carries `git.transport` and `server.address`. `git.request.bytes` is on POST spans only (`git.upload-pack ls-refs`, `git.upload-pack fetch`, `git.receive-pack`): the request body's length, set before the POST is sent (so a failed POST carries it too; on `git.receive-pack` it is then set again to the bytes actually sent), and absent when the GET ply makes before a POST fails first. `git.response.bytes` is set only when a response body was read to its end: on the GET spans (`git.upload-pack discover`, `git.receive-pack advertise`) once the advertisement is read whole, and on a POST span once the POST's response is read whole. A GET span never carries `git.request.bytes`, and an exchange that fails before its body is read whole (a non-2xx, a wrong content-type, a body over the cap, a timeout, a cut stream) sets no `git.response.bytes` of its own. The GET ply makes on a POST's own span (before the first POST under `followRedirects: 'initial'`, and before the re-send after a stale redirect memo; after the POST, when ls-refs gets an empty answer and when a push is refused at its status line) sets `git.response.bytes` there to the advertisement's length once it is read whole. Before the POST: a POST that reads its response whole replaces it with its own, and a POST that fails keeps the GET's count; the method is set back to `POST` for the first POST under `followRedirects: 'initial'`, but a span re-sent after a stale redirect memo ends with `http.request.method` (`GET`, from the re-settling GET) beside the re-sent POST's status, `git.request.bytes` and `git.response.bytes` (the re-send does not set the method again). After the POST: the GET's count, `http.request.method` (`GET`) and status are what the span ends with. A transport you pass in sets what it sets. ### Telemetry contract Span names, kinds, parent/child structure, links and attribute keys (with their value types) are public API. [`test/span-contract.json`](test/span-contract.json) is the contract: `test/span-contract.test.js` runs every operation (editFile, commitChanges, pushTree, checkoutTree, readFile, listTree, readCommit, mergeBranch, rebaseBranch, cherryPick, revertCommit, createBranch, deleteBranch, createTag), and the wire spans against real git and fails, naming each span and key, when what is emitted differs from the file. Values are not part of the contract; repeated siblings (three fetches) are one node, so round-trip counts are not either. - **Removing or renaming** a span or key, changing a value's type, or moving a span is a **breaking change** for consumers' dashboards and alerts, and is called out as one in the PR and the release notes. - **Adding** one also fails the test until the snapshot is regenerated (`npm run test:spans:update`), so every addition is visible in review as a diff of `test/span-contract.json`. ### In-process consumers: `onEnd` An exporter gets each span as one OTLP/JSON `ExportTraceServiceRequest` object, `{ resourceSpans: [{ resource, scopeSpans: [{ scope, spans: [span] }] }] }` (an object, not a string: `JSON.stringify` it for a JSONL file or a collector's body; `consoleExporter` does). Telemetry never changes an operation's outcome: a throw or a rejected promise from `exporter` or `onEnd` is caught, counted in `tracer.telemetryErrors` and handed to the optional `onTelemetryError(error, { hook, span })` tracer option; the operation's Result is what it would have been with a healthy tracer. `hook` is `'exporter'`, `'onEnd'`, `'onFinish'` (ply's own end-of-operation attributes) or `'internal'`: ply's own span-building failed (for example an attribute value with no string form), which is never blamed on your exporter; that span is counted and not exported. `onTelemetryError` is optional in `TracerOptions` and in the `TracerConfig` type; its types are exported as `TelemetryErrorSink` and `TelemetryHook`. `opts.tracer` is duck-typed: ply requires `start()` and calls no other method of it (every span, wire spans included, is opened with `start()`; a `span()` of your own is never called by ply), so a `{ start }` object, a `{ start, span }` wrapper or a `Tracer` built by another pinned copy of ply works and gets the same isolation (its `telemetryErrors` counter and `onTelemetryError` are used when present). A consumer in the same process (a list kept for one request, spans mirrored onto a platform tracer) usually wants plain values instead, and would otherwise pay to build the OTLP form and then `flattenLine` it straight back. `new Tracer({ onEnd })` calls `onEnd(span)` with an `EndedSpan` as each span ends: exactly the `FlatSpan` that `flattenLine` reads back from the line the exporter would get (ids, name, kind, `durationMs`, status, attributes as plain values, credential-scrubbed; events; links), plus `startTimeUnixNano`, `endTimeUnixNano` and `otlp()`, which builds that OTLP span on first call (and returns the same object after). `onEnd` runs before the exporter. A tracer with `onEnd` and no exporter builds no OTLP at all unless `otlp()` is called; one with neither builds nothing. A subclass that overrides `export` still gets every span. `test/otel-ended.test.js` holds the EndedSpan equal to `flattenLine` of the exported line over random attribute records of every value kind. ```js const spans = []; const tracer = new Tracer({ onEnd: s => spans.push(s) }); // s.attrs['git.response.bytes'] is a number; no OTLP built ``` ### Span lifetimes Some work is driven by the caller after the call returns: `readFile`'s `stream`, `checkoutTree`'s `files` iterator (and each streamed blob in it). Their spans — `git.read.blob`, `git.checkout.blobs` — **follow** the span that started them instead of being its children: - Each is the root of a trace of its own, with an OTLP link `ply.link=follows_from` to the span it follows, and that span carries `ply.link=followed_by` back if it was still open when the follower started (`git.read` → `git.read.blob`; `git.checkout.blobs` → each streamed `git.read.blob`). Links per span are capped at `maxEvents`, the rest counted in `droppedLinksCount`. - A follower is not an invocation (no `ply.isolate.*`), inherits its leader's credential scrubbing, and carries its own `.outcome`. It ends when the work does: the stream read to the end (`ok`), failing (the error code), or cancelled by the consumer (`cancelled`). A stream neither read to the end nor cancelled never ends its span, and holds its connection, like an unread `fetch` body. - Every other span ends within its parent: no child outlives its parent (asserted over every trace in the contract test). Why not keep the root open until the stream ends: the root's duration would then be the consumer's read speed (a slow downstream client, a Worker's response piping out), not ply's work, and a stream the caller never drains would leave the root — the span dashboards key on — unexported. Why not a child that ends late: trace viewers draw and roll up durations by the root span, so a child past its parent's end renders outside it and the root's time undercounts the work under it (#35). This is OpenTracing's `FOLLOWS_FROM` reference (a parent that does not depend on its child's result), which OpenTelemetry represents as a span link; Jaeger, Tempo and Honeycomb show links as navigable references between traces. So the operation root measures what the caller awaited (until the result is ready; for `readFile`, until the stream is open and its size known), and the follower measures the transfer. ## Errors An argument of the wrong shape is a caller error answered as a value, never a throw: `null`, a number or an array where an object is documented (an options bag, a spec, a pack, a source) is `bad_request` with `what` naming the argument (`'options'`, `'spec'`, `'pack'`, …), for `pushRepo`, `pushDir`, `filesFromDir` and the stack entries `scanPackIndex`, `resolvePackRange`, `planPackBatches`, `packSubset`, `planTransfer`, `copyTree`, `loadTransferPack` and `pushPack` (#296). `decodeSavedIndex` keeps one error union: a wrong-shape `bytes` or `want` is its `bad_argument` refusal naming the argument, a `tag` like the other seven. `userAgent` must be an RFC 9110 field value (field-vchar 0x21-0x7E or obs-text 0x80-0xFF, with SP and HTAB only between them); a control character, DEL, a code point above U+00FF or a leading or trailing SP/HTAB is `bad_request` (`what: 'userAgent'`, earlier `'user agent'`) when the options are parsed, where it used to fail later as a retryable `network` error (#300-1). Every error a function returns has a `code` from `errors.js`, whose `RETRY` table says what to do: `yes` (retry as-is), `fresh` (re-resolve the parent: `cas_conflict`), `no`, or `read` (`ambiguous`: the push may have landed — read the ref back before anything else). A push says landed (resolves), not landed (`cas_conflict`, `not_fast_forward`, `push_rejected`: each git rejection reason's class is in SPACE.md "Push ng reasons") or partly landed (`push_partial`, a non-atomic multi-ref push: `err.landed` and `err.rejected` name the refs) only on a report exactly as git's receive-pack writes it; every other state after the request may have reached the server — a cut, trailing bytes, band 3, a near-miss line, option lines, a limit hit while reading — is `ambiguous` (SAFETY.md I36; the space and every cell's outcome: SPACE.md). A push that provably sent nothing is not one of those states, for `push`, `pushPack` and everything built on them: a signal that had already fired before the request was made is `aborted` (or `timeout`) with no request made, and a request that failed before the transport pulled the first chunk of a streamed body (a pack over 16 KiB, or `pushPack`'s) is that failure itself (`network`, `aborted`, `timeout`, or an HTTP answer's own code), because the server received no command list. A body small enough to be handed over as bytes cannot be seen leaving, so a failed request with one stays `ambiguous`. After an acknowledged push, any failure to confirm — a forged report, a transport error on the read-back — is `ambiguous`, enforced in one place (`operation.js/verifyRef`, `push.js/ambiguousAfterPush`). A fetch answer is judged as git's fetch-pack judges it, against the request that was sent. `done` (`fetchPack`, `packStream`, `fetchBody`, `negotiate`) is `true`, `false` or left out (the default, `true`); any other value (`null`, `0`, `''`) is `bad_request` before any request, where it used to send the request without `done` and judge the answer as if `done` had been sent. After a request that sent `done`, an `acknowledgments` section is `protocol` ("expected packfile, received acknowledgments") even when a pack follows it; such an answer used to be ok. A `negotiate()` round (a request without `done`) that the server answers with `ready` and no packfile fails at that round: `protocol`, "the server said ready and sent no packfile section", as git's fetch-pack dies there ("expected packfile to be sent after 'ready'"). It used to go on to the final `done` request and could end ok. The round is `fetchPack` with `done: false`, which refuses the same answer when called directly. A round that ends on its acknowledgments without `ready` is still a round: negotiation goes on. `verifyFetchAnswer(request, answer)` (and so `cachingFetch` with `verifyBeforeStore`, which stores an answer only once `verifyFetchAnswer` accepted it whole) judges a stored answer the same way, by the `done` of the request that produced it. After a request that sent `done`, an answer with an `acknowledgments` section does not verify (`protocol`), with or without a pack after it; one with a pack after it used to verify. After a request without `done`, git's own answer (`acknowledgments` with `ACK` and `ready`, then the pack) verifies, as it always has, and an answer with no pack never does: a round that ends on its acknowledgments is `protocol` ("answer: no packfile section"). ## Shape `parseOid` returns a 40-character lowercase hex object id as an `Oid` (`bad_request` otherwise). `parseCommitId` is that check and also rejects `ZERO_OID`. git's `rev-parse` also accepts abbreviations, ref names, and uppercase hex; ply does not. `MODE_BLOB`, `MODE_EXEC`, `MODE_LINK`, `MODE_TREE`, `MODE_COMMIT`, and `BLOB_MODES` are the modes git writes in a tree (`BLOB_MODES` is the file modes: blob, executable, symlink). Two entry points, one codebase. `ply/edit` is the pipeline and imports only the free functions it uses; `ply` is the full client (negotiation, delta resolution, multi-ref pushes, advertisements). Nothing is a class on the hot path — `createTransport()` returns a record and `lsRefs`, `packStream`, `fetchObject`, `fetchPack`, `negotiate`, `push`, `discover` are functions over it — so a bundler keeps only what you import. `GitHttp` wraps all of them for scripts and tests: `GitHttp.create(url, opts)` is a `Result` (a bad URL is its Err), and each method answers with the free function's `Result`. `test/bundle.test.js` asserts the edit bundle carries no resolver, negotiation, advertisement or class code and stays under budget (39 KB min / 15 KB gz; full: 58 KB / 21 KB). `edit.js` is pure decisions between thin effects: `validateSpec`, `decideHead`, `lookupEntry`, `buildCommitObjects`, `memFromScan` are functions of their arguments and unit-tested against git without a server (`test/pure.test.js`); ls-refs, fetch, the blob stream, push and verify are the only places the client is touched. ## Limits Every bound is a field of `limits` (`opts.limits`, any call). `DEFAULT_LIMITS` is sized for a git client's heap: one object up to 64 MiB (`maxObjectSize`), 128 MiB of pack per fetch or push (`maxPackBytes`), 128 MiB of files per `pushTree` or `commitChanges` (`maxPushBytes`), 256 MiB held from one buffered pack (`maxInflatedTotal`), 100 000 objects per pack (`maxPackObjects`), 200 000 entries per tree (`maxTreeEntries`), 2^32 diff steps per merged file (`maxMergeWork`: CPU, not memory, about 25 s of it at the ~6 ns a step measured, sized so that a file git itself merges cleanly in about 5 s is merged, a 130,000-line file with 13,000 scattered one-line edits included; a file both sides changed whose line merge needs more is a `merge_conflict` with reason `too large to merge`, as one over `maxMergeBlobBytes` is). `withLimits({ ... })` overrides some of them; a field that is missing, `NaN`, infinite or negative is `bad_request`, never an open cap. A bound hit is `limit_exceeded` with `what` (the budget), `got` and `max`. `maxReportLines` (10 000) bounds receive-pack's report, but never below what git sends for the commands pushed (one unpack line plus one status per command, five per command with report-status-v2), so a push of up to `maxRefs` commands is never cut off by its own report; a report past the cap is `ambiguous` (the push was sent). Two more limits bound what is kept of receive-pack's answer and never change a push's outcome: `maxReportReasonBytes` (4096) is how much of one refusal reason (`ng `, or an `unpack `) is kept, so a longer one is cut there, the ref keeps its status and the error's code is read from the kept part (never fewer bytes than git's own longest reason, so a reason git writes is never cut), and whether a host's unpack status is echoed on a ref is read from the whole status and reason before the cut, so a pair that differs past the limit stays `ambiguous`; `maxReportProgressBytes` (8 MiB) is how much band-2 output (progress, hook text) is decoded, anything past it is dropped, the report is still read and `hookOutput` is the last 4 KiB of what was decoded. Keepalives and the answer as a whole are held to `maxPackBytes` and the timers. `rebaseBranch` makes two walks to find its base, each under its own limit: the branch is walked from its tip to `maxRebaseCommits` (10 000) + 2 commits, or to `maxMergeDepth` where that is deeper (a base that `mergeBranch`'s search finds is found here), and `onto` to `maxMergeDepth` (1024) commits, as `mergeBranch`, `mergeBase` and `readLog` are. A chain known to be longer than `maxRebaseCommits` is `limit_exceeded` with `what: 'rebase chain'`, `max: maxRebaseCommits` and `got: max + 1` however long the chain is: the search stops one past the limit and does not count the rest. It is known when the base was found, or when the `onto` walk reached the root of `onto`'s history and more than `maxRebaseCommits` commits of the branch are outside it. When both walks end without a shared commit and the `onto` walk was cut at `maxMergeDepth`, the refusal is `what: 'merge-base search depth'` with `max: maxMergeDepth` and `got` twice that, the fields `mergeBranch` reports: a commit of the branch walk may still be an ancestor of `onto` beyond the cut, so a short branch whose `onto` has moved more than `maxMergeDepth` commits past the base and a long chain look the same, and no request is spent to tell them apart. Raising `maxMergeDepth` until both walks reach the base settles it either way (the rebase, or `'rebase chain'`); `maxMergeDepth: 0` refuses every rebase before any search. A walk that has reached the root, or its cap, is not fetched again. A refusal costs no more requests under `WORKER_LIMITS` than the merge-base search alone (ls-refs and two walks at each of the 8 depths to 1024: 17), and up to 9 more under `DEFAULT_LIMITS` (26 measured: past `maxMergeDepth` the branch walk goes on in windows of `maxMergeDepth` commits from the cut frontier, one window held at a time as parent lists, so it holds no more than the merge-base search did), both asserted in `test/rebase.test.js` on a repository whose `onto` history is deeper than `maxMergeDepth`. A rebase costs one request for ls-refs, two per doubling of the search (8, 16, …), the replay and the push. What the replay costs depends on what its commits touch: about one request per commit whose files `onto` did not change, more for each file that must be line-merged with `onto` (three shapes of a 256-commit chain are measured at 268, 781 and 2,581 requests: `WORKER_LIMITS`, below). No limit bounds the requests of a rebase: `maxRebaseCommits` bounds the commits, not the files each one merges. The byte budgets count what an object costs, not only its bytes: each object parsed from a pack (`parsePack`, and the room `resolvePack` has left; so every fetch, `checkoutTree`, and `pushRepo`'s local packs), each local object `pushRepo` holds, each file `filesFromDir` reads, and each file or change `pushTree`/`commitChanges` takes is charged its bytes plus `LIMIT_OBJECT_OVERHEAD` (3 KiB, above the 1.0 to 2.4 KiB of heap and RSS one tiny object was measured to cost; the method is in `src/limits.ts`). So a pack of 100 000 three-byte blobs (1.4 MB on the wire, which `git index-pack` accepts) is `limit_exceeded` (`what: 'pack inflated bytes'`) under the defaults, and 100 000 eight-byte files are `limit_exceeded` (`what: 'push bytes'`), where counting bytes alone let both run a 128 MiB heap out of memory. On the defaults that is about 87 000 tiny objects per pack and 43 000 tiny files per push; `got` includes the overhead. `stats.inflated` is still the declared sum git reports. Time is bounded per exchange by four timers (#255, #273), all fields of `limits`; 0 turns one off: - `firstByteTimeoutMs` (60 s): from the request to the response headers. For a streamed request body (`pushPack`, a `StreamBody`), it starts when the upload ends, which for ply is when the platform has taken the last piece. The platform and the kernel may still be sending what they buffered (about 2 MiB on Node over loopback, measured), so on a slow link this limit also has to cover that tail: a link that cannot drain it in time fails as `firstByteTimeoutMs`. Once the response headers have arrived this limit cannot fire, whatever the upload does after (a server may answer before it has read the whole request). - `idleTimeoutMs` (60 s): the longest wait on the network with no progress, either no upload piece taken by the platform or no response chunk arriving. A streamed upload is handed to the platform in pieces of at most 64 KiB, so one large chunk is many progress marks; a mark means the platform took a piece, not that it reached the server, and marks arrive in bursts as the platform's and the kernel's buffers drain (with Node's fetch over loopback at 2.5 MiB/s: gaps up to about 0.5 s). The split has a cost for a source whose chunks are larger than 64 KiB: such a chunk costs what the same bytes cost as 64 KiB chunks, measured on Node 24 over loopback as about 0.13 to 0.15 ms more client CPU and 0.09 to 0.12 ms more wall time per MiB uploaded than handing each chunk over whole; a source of 64 KiB chunks measures level with that. ply does not measure upload progress below fetch: `idleTimeoutMs` and `firstByteTimeoutMs` fire on what ply can see (the platform stops taking pieces; no response after the last piece is handed over). For a bound on the upload as a whole, whatever the platform has buffered, the request timeout (`requestTimeoutMs`, off by default) or the caller's `signal` is what bounds a stalled upload. A server that keeps sending (upload-pack sends keepalives while it counts objects) is never cut. Idle time measures the network, not the consumer: while the consumer holds a chunk and has not asked for the next one, no idle time is charged; `heldTimeoutMs` bounds that instead. - `heldTimeoutMs` (240 s, 4 x the idle default, `LIMIT_HELD_TIMEOUT_MS`): the longest the consumer may hold one chunk, from taking it to asking for the next, before the exchange is cut with code `timeout` and `limit: 'heldTimeoutMs'` and the upstream body is cancelled. A consumer that holds just under it is not cut, and network idle is not charged while it holds. Precision: the take reads no clock (the hold adds no clock read per chunk), so the hold starts at the first clock read after the take (the exchange's pending timer firing, or the take arming one when none is due by then); the cut is never before take + `heldTimeoutMs`, and late by at most one timer interval: `idleTimeoutMs` or `heldTimeoutMs`, whichever is smaller (`heldTimeoutMs` when idle is off), plus the platform's timer latency, which is fine against a 240 s default. 0 turns it off, leaving a consumer that stops reading bounded only by the caller's `signal` or `requestTimeoutMs`. - `requestTimeoutMs` (0, off): an opt-in cap on the whole exchange, body included. Before #255 this was the only timer, at 60 s, so a large streamed fetch died at 60 s however steadily bytes arrived. A caller who passes it keeps that behaviour. Each of the four is a whole number of milliseconds from 0 to 2147483647 (the range of the platform's timer, 24.8 days); a larger value is refused as `bad_request` before any request, and 0 turns that timer off. **With the defaults there is no total cap: an exchange that keeps making progress runs as long as it takes, unless the caller sets `requestTimeoutMs` or passes a `signal`.** Network stalls are still bounded by the two network timers above, and a consumer that stalls by `heldTimeoutMs`. A timeout is the typed `timeout` error with `what` naming the limit that fired. The exchange span records `git.timeout.limit` and `git.timeout.ms` as well as `git.limits.first_byte_timeout_ms`, `git.limits.idle_timeout_ms`, `git.limits.held_timeout_ms` and `git.limits.request_timeout_ms`. There is no total cap by default, matching stock git, which has none (`http.lowSpeedLimit` is off by default). For a wall-clock bound, pass `requestTimeoutMs` or your own `signal`. Body reads end on abort even when a fetch wrapper does not tie the body to the signal. In a Worker, timers fire while a body read is pending (tested under workerd). `WORKER_LIMITS` is the preset for a 128 MiB isolate (a Cloudflare Worker): `maxObjectSize` and `maxDeltaResult` 16 MiB (one object peaks near twice its size), `maxPackBytes`, `maxPushBytes` and `maxLsRefsBytes` 32 MiB, `maxInflatedTotal` 64 MiB (about 21 000 tiny objects), `maxResolveWork` 512 MiB, `maxHarvestBytes` 8 MiB, `maxMergeBlobBytes` 2 MiB, `maxMergeWork` 2^26 steps (the worst files found under `maxMergeBlobBytes` are refused in 1.0 to 1.7 s of CPU on a loaded 16-core laptop, up to 0.9 s of which is splitting the three sides into lines, which no step budget covers; a 70,000-line file with 3,500 scattered one-line edits needs about 362 million steps, so in a Worker it is a conflict with reason `too large to merge`; `withLimits({ ...WORKER_LIMITS, maxMergeWork: 2 ** 30 })` merges it), `maxTreeEntries` 32 768, `maxRebaseCommits` 256, `maxReportReasonBytes` 1024 (a push of 10 000 refused refs keeps 10 MiB of reasons, not 40); the rest are the defaults. 256 bounds the length of the chain, not the number of requests: what a chain costs depends on what its commits touch, and a Worker request may make 1,000 subrequests (standard plan). The cheapest shape is the one `test/rebase.test.js` measures: a 256-commit branch whose every commit changes one file that `onto` did not touch is measured at 268 requests (at most 800 is asserted), and a branch one commit longer is refused (`what: 'rebase chain'`, `got: 257`, `max: 256`) in at most 17 requests. The same 256 commits are measured at 781 requests when every commit changes one file that `onto` also changed (each replay line-merges it), and at 2,581 when every commit line-merges three files in three directories. The first two are under a Worker's ceiling (781 leaves the caller 219 for everything else its request does); the third is 2.6 times past it, and ply has no request budget that would refuse it by name. A Worker that rebases branches over changes to the same files lowers `maxRebaseCommits` or raises its subrequest limit. All three were counted where requests leave the transport, against git http-backend (a `tree:0` server) under `WORKER_LIMITS`, with `src/` as of 6edf6a0; the first two end in the tree `git rebase` writes (the third was not compared), only the first is held by a test, and nothing here was run on workerd. The limit sweep (`npm run sweep -- --full`, nightly) runs it at `--max-old-space-size=128`: every `worker.*` cell refuses or succeeds, none runs out of memory. `maxResolveWork` is `resolvePackRange`'s hard work ceiling, applied exactly as given. It must be at least the record's own `maxInflatedTotal`: below it, `parseLimits` (and every `limits` option) is `bad_request` with `what: 'maxResolveWork'`. A record that leaves `maxResolveWork` out (a partial record, `withLimits`) gets 8 × its `maxInflatedTotal`, capped at `Number.MAX_SAFE_INTEGER` but never below `maxInflatedTotal` itself (`{ maxInflatedTotal: 1e18 }` gets 1e18). A spread of a preset carries the preset's number, not a derived one: `{ ...DEFAULT_LIMITS, maxInflatedTotal: 16 MiB }` is still bounded at 2 GiB, and `{ ...WORKER_LIMITS, maxInflatedTotal: 1 GiB }` is `bad_request` (512 MiB is below 1 GiB). Set `maxResolveWork` beside the changed `maxInflatedTotal`, or take the preset's number out with `withDerivedWork`: `withDerivedWork({ ...DEFAULT_LIMITS, maxInflatedTotal: 16 MiB })` is bounded at 128 MiB. `null` is `bad_request` on every key, `maxResolveWork` included. ```js import { pushTree, WORKER_LIMITS, withLimits } from 'ply'; const r = await pushTree(url, spec, { limits: withLimits({ ...WORKER_LIMITS, maxPackBytes: 62 * 1024 * 1024 }) }); ``` ## Memory Peak per invocation is one pkt-line (≤ 64 KB) + one inflate chunk (16 KB) + `|find|−1` carry + the replacement bytes. Measured over 446 fuzzed edits including 1.4 MB blobs: `mem.alloc.max_single` max = 16384. The blob is never resident; the delta is three ops computed from the match offset, and the new blob's oid comes from a streaming SHA-1 over the transformed stream (the exactly-one-match contract makes `newLen` known up front). Every fetch reads its pack as the band-1 bytes arrive, through one deflate decoder (`inflatePull`, of which `inflate()` is a collector): the pack's bytes and its zlib members are dropped once inflated, so a fetch holds what it keeps plus the decoder's hold, the 32 KiB window, one 16 KiB chunk and one pkt-line (114,672 B, `src/streambound.ts`). Measured (`test/stream-memory.test.js`, `node --expose-gc`, live `arrayBuffers` sampled every 256 KiB allocated): `fetchObject` through the blob:none fallback, a pack of 2,000 4 KiB trees, all retained (R = 8,192,000 B), peaks at R + 241,366 B where it peaked at R + 12,201,108 B with the pack joined first (`fetchPack` of the same pack: R + 241,345 B, was R + 12,201,108 B); with 62 256 KiB blobs in the pack too (an unfiltered fallback; a tree want drops them as their headers arrive) R + 257,434 B where it was R + 28,621,712 B. The response's own share of those figures (frames in flight, read with every chunk dropped) is 451,094 B. `inflate()` of a 64 MiB member in hand holds the output and 82,236 B. The pulls are exported for a caller that streams on its own: `inflateInit`/`inflateFeed`/`inflatePull`/`inflateEnd` (bytes in, chunks of at most 16 KiB out), `parsePackInit`/`parsePackFeed`/`parsePackPull`/`parsePackEnd` (a pack's header, each object's header with its parsed base, its inflated chunks, its end, the trailer) and `sidebandStep` (one packfile-section frame demultiplexed). Each pull answers `need` when it wants more input; a refusal is a `Result` error, and every later pull returns it again. What a zlib member may be is git's call: the decoder accepts a member stock zlib accepts as git links it, and refuses what it refuses. A zlib header's CINFO above 7 is `pack_corrupt`; a smaller CINFO is not enforced (zlib's `inflate.c` checks a distance against the declared window only under `INFLATE_STRICT`, which stock builds do not define), so a match that reaches past the declared window and stays inside the output already produced is read, as `git cat-file` and `git index-pack` read it. Before this, `inflate()`, `parsePack` and the pulls answered `pack_corrupt` (`inflate: distance too far back`) for such a member. A match that reaches before the first byte of output is still `pack_corrupt`. A dynamic block whose code-length, literal/length or distance code set is over-subscribed or incomplete is `pack_corrupt` at the block's header, with zlib's message (`inflate: invalid code lengths set`, `inflate: invalid literal/lengths set`, `inflate: invalid distances set`) and by zlib's rule: an incomplete set is allowed only when it has no codes, or is one 1-bit code in the literal/length or distance set. Members with such a set that an earlier version refused later now carry the message above in place of `unexpected end of input`, `invalid huffman code` or `distance too far back` (the code was and is `pack_corrupt`); members it accepted are now refused, as zlib and git refuse them. In the pulls, a member cut short after such a header is a definite refusal at the header, where the pull used to answer `need`. The same decoders as streams, for a `for await` (#241): `scanPack(source, { limits, verify, budget })` yields the scan's pieces (`header`, then for each object `object`, its inflated bytes as `chunk`s and `object-end`, then `trailer`; never `need` or `end`), `pktFrames(source)` yields pkt-line frames (`data`, `flush`, `delim`, `end`) and `inflateChunks(source, { bound, wrap })` yields one zlib member's inflated chunks (at most 16 KiB each). `source` is a `ReadableStream` or an `AsyncIterable`; each returns a `ReadableStream` with `highWaterMark: 0`, so the source is read only when you ask for the next item, one chunk at a time. A refusal (a bad header, a cut pack, a frame past 65,520 bytes, bytes after a zlib member's end, a chunk that is not a `Uint8Array`, bad options) errors the stream with the `PlyError` the pull returns, so it is thrown from the loop, and the source is cancelled. An error from the source is thrown as it is (the same object). A `break`, a `return` or a `throw` in the loop body cancels the stream, which cancels the source (a `ReadableStream` is cancelled with the reason; an iterable's `return()` is called). Measured (`test/stream-memory.test.js`, Node 22 and 24, live `arrayBuffers` at peak): `scanPack` over three 96 MiB blobs 84,284 B and `inflateChunks` over a 96 MiB member 84,284 B (bound 114,672), `pktFrames` over 2,000 maximal frames 131,036 B (bound 131,040, two frames); `test/pullstream.test.js` checks parity with the pull API over every chunking, the reads each item costs, and each refusal and release. ```js import { scanPack } from 'ply'; // pack: a ReadableStream or AsyncIterable of a pack's bytes. An invalid pack errors the stream (a PlyError). const sizes = []; // each object's inflated size, in pack order let size = 0; for await (const piece of scanPack(pack)) { switch (piece.kind) { case 'header': break; // piece.version, piece.count case 'object': size = 0; break; // piece.type, piece.offset, piece.base case 'chunk': size += piece.bytes.length; break; // the object's inflated bytes, in order case 'object-end': sizes.push(size); break; // piece.compressed, piece.stats case 'trailer': break; // piece.trailer: the pack's checksum } } ``` A pack scan holds no object: its peak is the constant in `src/streambound.ts` (the 32 KiB window, one 16 KiB chunk, one pkt-line, plus the chunk you fed and any chunk you keep), so there is no limit to set for it. What a scan's limits bound depends on its budget. By default (`packScanOpts(limits)`) it refuses exactly as `parsePack` does, charging each declared size plus per-object overhead against `maxInflatedTotal` before inflating, and applying `maxObjectSize`: right for a caller that keeps objects. A caller that drops them passes `packScanOpts(limits, verify, WORK_BUDGET)`, and a multi-GB pack needs no caps raised. `maxInflatedTotal` then means work rather than memory: bytes actually inflated may reach it, or `ratio` (default 32, `workBudget(ratio)`) times the pack bytes consumed so far if that is larger. A decompression bomb stops within one chunk of that, so lower `maxInflatedTotal` to spend less CPU on one. `maxObjectSize` applies only with `workBudget(ratio, true)`; `maxPackObjects` still applies, and bounds what you keep per entry. Refusal near the ratio can vary with how the pack is chunked; memory cannot. A caller that does retain chunks under a work budget has to bound them itself. `scanPackIndex(source, { oids, content, limits, verify, budget, signal })` is that driver for the common case: it reads a `ReadableStream` or `AsyncIterable` of a pack and returns each entry's layout (offset, header bytes, compressed length, stored type, declared size, base) without resolving a delta or keeping an object. It is the streaming counterpart of `describePack`, under `WORK_BUDGET` by default. It holds the scan's constant plus `SCAN_INDEX_ENTRY_BYTES` (31) per entry in typed columns, and 20 more per entry for each oid column in use: whole-object oids (on by default, hashed as the bytes stream past; `oids: false` saves about a fifth of the time) and REF bases (once the pack has a REF_DELTA). A REF-only pack, which is what Cloudflare Artifacts sends, holds 71 bytes per entry. **`type: null` means unknown, never a guess.** A REF chain whose base is itself a delta stays `null`, because linking it needs that delta's oid, which means applying deltas. On this repository's REF-only pack that is 4,647 of 5,675 REF deltas. Since Cloudflare Artifacts packs are REF_DELTA only, their chains deeper than one stay `null` here. `resolvePackRange` (below) resolves those. Columns grow by doubling up to the header's count. Measured (`test/stream-memory.test.js`): 200,000 entries with oids, 51 bytes per entry; three 96 MiB blobs, 84 KB live against the 114,672 B scan bound. Each entry's resolved type is the type of the whole object its chain rests on: an OFS chain's root, or a REF_DELTA's base when that base is a whole object in the pack and `oids` is on. A base outside the pack, a base that is itself a REF delta, or `oids` off is `null`, never a guess. `content.select` picks whole objects (a commit, say) whose bytes `content.take` receives in pack order, each capped by `maxObjectSize`. Verified while scanning: zlib, each declared size, each OFS base an earlier entry's offset, and the trailer. A refusal is a `Result` that cancels the source; an error from the source or from `take` rejects. `resolvePackRange(index, source, { limits, budget, cacheBytes, bases, signal })` is the rest of `git index-pack` for a pack too large to hold: every entry's oid, resolved type, chain depth and base, from `scanPackIndex`'s index and a `RangeSource` over the same bytes (`{ size, read(offset, length, signal) → Promise> }`: a file, an R2 object, or `rangeFromBytes` in memory; `signal` is an `AbortSignal` that is optional in the type, `signal?: AbortSignal | undefined`: a `read` of two parameters is a `RangeSource`, a direct caller may omit it or pass `undefined`, and a wrapper forwards the optional signal it was given as it is (`inner.read(offset, length, opts.signal)` compiles), so a `read` that takes it has to work without one, while ply always passes one). It works depth first from each whole object, reading each delta back through the source and applying it; of the results something rests on, the last is pinned as the next base (a linear chain builds each object once, whatever its size) and the others go to an LRU of `cacheBytes` (16 MiB by default). A base in neither is rebuilt over its chain, and every base made on the way is kept in the LRU, so a forked family larger than the cache walks a chain once per cache-full of siblings rather than once per sibling (151 objects forked 50 deep with a cache of 16: 235 reads and 1.56 × the object bytes of work, where it was 745 reads). With `cacheBytes` smaller than one object a fork still costs its depth per sibling; the work budget bounds that. A valid pack whose forked family is rebuilt past the work bound that way (`cacheBytes: 0`, or a cache smaller than one of its objects) is refused by design, `limit_exceeded` (`resolve work bytes`), where a cache with room for its objects resolves it. It holds one base, one pinned result, one result, one delta's instructions and the cache: at most `max(maxObjectSize, maxDeltaResult) + 3 × maxDeltaResult + cacheBytes` (272 MiB on the defaults, 80 MiB on `WORKER_LIMITS`), whatever the pack's size, depth or shape. Every oid is computed from the bytes; a base read back a second time must hash to the oid it had (a spool that changed is `pack_corrupt`); a thin base from `bases(oid)` must hash to the oid that named it. Refused: a base in neither the pack nor `bases` (`pack_corrupt`, "not found"; a REF cycle ends there too), a chain past `maxDeltaChain`, work past the budget (`limit_exceeded`, `resolve work bytes`). Work (`stats.work`) is bytes inflated from the source plus bytes of delta results made plus one per delta visited as a child of its base, so it rises by one per delta over the bytes alone (one blob and m REF deltas on it is 11 m + 6, not 10 m + 6), and a shape that visits a delta more than a constant number of times is refused by the budget rather than resolved slowly (#299). The budget follows what the pack declares (4 × its members' sizes plus each delta result made so far, never less than `maxInflatedTotal`), because delta-compressed history is legitimately hundreds of times its pack, and it never passes the hard ceiling, `limits.maxResolveWork` exactly as parsed (never below `maxInflatedTotal`: `parseLimits` refuses a smaller one): 2 GiB on `DEFAULT_LIMITS`, 512 MiB on `WORKER_LIMITS`, and 8 × the record's `maxInflatedTotal` when a caller's limits leave `maxResolveWork` out (the rule for a spread of a preset is under Limits). The ceiling is what stops a delta bomb: a 4 KB pack of 40 deltas each declaring a maximum-size result is refused after 512 MiB of work (about 2 s of CPU) under `WORKER_LIMITS` and after 2 GiB (about 8 s) under the defaults (`test/pack-range-resolve-bound.test.js`). An honest pack whose objects sum past the ceiling is refused the same way; raise `maxResolveWork` for it and split the work across requests. A `maxResolveWork` that is not a finite non-negative number is `bad_request` like any other limits key, whatever the budget. The result keeps `RESOLVED_ENTRY_BYTES` (41) per entry: oid, type, base, depth, resolved size and an oid-ordered index for `find(oid)`. Measured (node 24, laptop): this repository's REF-only pack (3,621 entries, 3.1 MB, chains to depth 50) in 3.3 s, about 18 MB/s of resolved bytes; chains of 4 MiB blobs at about 75 MB/s of resolved bytes, peak 8.44 MB live whether the pack was 8 or 33 MB (`test/resolve-memory.test.js`). Split work across requests by those rates. **Abort.** The storage behind a `RangeSource` or a scanned stream is the caller's and may never answer, so `scanPackIndex`, `resolvePackRange`, `loadTransferPack` (`{ scan, resolve, signal }`) and `packIdentity(source, signal)` take an `AbortSignal`: when it aborts the call returns `aborted` at once, whether or not the read in flight ever settles; the range or stream in flight is asked to cancel (not waited for), the `signal` passed as `read`'s third argument aborts, and whatever the storage answers later is dropped (a range that opens late is cancelled). A range whose `cancel()` throws, or returns something that is not a promise, changes none of this: its failure to cancel is dropped. A `signal` that has already aborted when `packIdentity` or `resolvePackRange` is called returns `aborted` before anything else: no storage read is issued, for a pack of whole objects (which needs none) as for one with deltas. A `packSubset` stream does the same when its consumer cancels it. Without a `signal` these calls wait for the storage. `planPackBatches(index, resolved, { budget, select, crossBatchRef })` plans how to push those entries as several pushes when one push would be over a host's limit. It is pure: it reads the two indexes and returns plain data (`{ version, trailer, budget, batches: [{ kind, entries, packBytes, objects, refRewrites }], hash }`), which `packSubset` turns into packs and `pushPack` sends. Build each batch with the index the plan was made from: `packSubset(source, index, batch.entries, { outsideBase: plan.crossBatchRef ? 'ref' : 'refuse', resolved })`. The planner sizes and checks every entry with the builder's own rule, so a batch it plans is one `packSubset` builds from that same `resolved`; without `resolved` (or with another pack's) a `crossBatchRef` batch that cuts an OFS chain below a delta base is refused by the builder (`bad_request`, `what: 'pack subset base'`), because only `resolved` knows a delta's id. The `budget` is the caller's, every dimension: `maxRequestBytes` and `maxObjects` per push (with `reserveBytes` and `reserveObjects` held back for the command prefix and any generated objects, such as a temp commit and its tree), and `maxObjectBytes` (resolved size) and `maxCompressedObjectBytes` (the zlib member) per object. ply holds no host's numbers; measured on Cloudflare Artifacts (2026-11-09), as an example only: 67,108,864 request bytes, about 50,000 objects, 33,554,432 inflated bytes per object, about 33,553,575 compressed. Every object is checked before any batch is planned, so an object no push can carry is refused (`limit_exceeded`, with `what`, `got`, `max`) before anything is sent. Children first: a strict server (`receive.fsckObjects`) refuses a pushed tree whose blob it lacks, so every blob goes in a batch before the trees, and the trees, commits and tags go last in one batch. Plan v1 refuses (`limit_exceeded`, "tree batch") when they do not fit one push, rather than ordering trees by depth. Delta families (a whole object and every delta resting on it) stay in one batch, so each batch has its bases. A family no single push holds is refused unless `crossBatchRef`: then it is split in chain order, and a delta whose base is in an earlier batch is written as REF_DELTA to the base's oid. That is a thin pack resting on what the destination already has; git's receive-pack accepts it (`index-pack --fix-thin`), but whether a host does is the host's to say, so it is opt-in. An Artifacts pack is REF_DELTA already, so nothing is rewritten for it, but the same opt-in governs it. The id written for a cut base is `resolved.oid(base)`, asked for only when a base is outside its delta's batch and checked there. A `resolved` that cannot name a cut base fails the plan (`bad_request`) before anything is pushed, and the message says which of three things happened: `oid()` answered no id, or anything but 40 lowercase hex ("cut from its base", with the entry); `oid()` returned nothing at all, neither an answer nor an exception ("oid() returned nothing", no `cause`); or calling `oid` threw, which a missing `oid` or one that is not a function also does ("oid() threw", with what was thrown as the error's `cause`). `packSubset` refuses the same entry in the same three ways (`bad_request`, `what: 'pack subset base'`) before it reads a byte, so no header ever carries anything but an object id. Order against the planner's other refusals: an `oid()` that threw or returned nothing is reported ahead of a `limit_exceeded` the same plan would otherwise end with (a tree batch too big for one push, say); an answer that is not an id is reported after it. An exception out of `resolved.oid()` is neither swallowed nor let out: `planPackBatches`, `packSubset`, `planTransfer`, `transferStep` and `runTransfer` return `bad_request` with what it threw as the error's `cause` (the same object), and a transfer step that ends that way has pushed nothing. A `resolved.type()` that throws while a transfer reads an entry ends the same way (`bad_request`, `what: 'entry'`, the `cause`). Sizes are counted as they will be written: an OFS_DELTA's distance at the length the largest distance in a push needs, and a REF rewrite at 20 bytes. The plan is deterministic and `hash` (SHA-1 of its canonical JSON: plan version, the source pack's trailer, the budget, the options and the batches; `planHash` recomputes it) names it, so a resumed transfer can tell its plan from another. Measured (node 24, laptop, `test/pack-plan.test.js`: a synthetic 200,000-entry index, 156,000 of them deltas, the two kinds alternating, median of 5 plans each, three runs of the test): planned in 47 to 51 ms when the deltas are REF_DELTA and 112 to 127 ms when they are OFS_DELTA (an OFS header's distance is sized per entry); 21 MB (OFS) and 36 MB (REF, the first plan in the process) of heap for the first plan of each kind; a 1.3 MB plan as JSON. With `crossBatchRef` off (the default) planning costs what it did before cut bases were checked: within 3% of main 8e3939d by the median of 15 interleaved process rounds. With `crossBatchRef` on, checking a cut base's id has a cost, accepted and stated here (measured at 02374d4, node 24, laptop, the 200,000-entry synthetic index above, 7 plans a process, 15 rounds alternating 8e3939d and 02374d4 processes, each process planning REF and OFS packs in turn; per-round ratio, median and range, and the ratio of the processes' minimums): a REF pack whose families are cut nowhere (50 pushes, 0 rewrites) 1.06 times (0.96 to 1.19; minimums 1.09, slower in 15 of 15 rounds); an OFS pack whose families are cut nowhere 1.03 times (0.98 to 1.12; minimums 1.04, 15 of 15); an OFS pack in which nearly every push boundary cuts a chain (blobs only, 2 objects a push, so 116,000 pushes and 76,000 cut deltas, each cut delta's base id asked of `resolved` and checked twice: once when it is sized in the push it opens, once when it is placed) 1.16 times (0.68 to 2.84 on a machine whose load average rose to 50 during the run; minimums 1.24, slower in 14 of 15), the fastest plan 185 ms against 245 ms. A REF pack asks for no id; the REF figures are the cost of the shared sizing path once OFS packs have been planned in the same process (a process that plans only REF packs measured 0.965 times). Run files: `ofs-cross-batch-eng-bench-head.txt` and `ofs-cross-batch-eng-allcut-head.txt` in the review-train scratch directory; an earlier check at the same commit measured 1.08 times for the REF case (`ofs-cross-batch-chk-bench.txt`, `ofs-cross-batch-chk-bench2.txt`). **Resumable transfer** (`copyTree`, #238) puts those together: one commit's tree, read from a spooled depth-1 pack, copied to another remote as a new parentless commit, in as many pushes as a host's cap needs, each safe to retry and the whole resumable from the destination alone. The caller owns the spool and where the loop runs; ply owns every state transition. `planTransfer(index, resolved, { budget, ref, commit, tempPrefix, crossBatchRef, atomic })` is pure: `commit` is the source commit's bytes (`scanPackIndex`'s `content` callback hands them over), `budget` the host's per-push limits (ply adds its own reserve: 258 objects and about 68 bytes per object for the generated trees and commit). `ref` is refused unless git would push it, and the temp ref is a branded `TempRef` under `tempPrefix` (which ends in `/`). It returns plain JSON with a `hash`, so a Worker can keep it between requests; `checkTransferPlan(plan, { ref, tempPrefix })` refuses a plan read back that is edited, stale or malformed (any field a step reads: an id, a ref, a step, the pack plan's budget, selection or batches) and is total: a stored value of any shape is `bad_request`, never a throw; a hole in one of its arrays (`steps`, `pack.batches`, `pack.select`, a batch's `entries`: a structured-clone store can hand one back, JSON cannot) is a corrupt plan (`what: 'plan'`). `transferStep` and `runTransfer` answer a `commit` that is not a `Uint8Array` with `bad_request` (`what: 'commit'`) before anything is read from it or sent. A stored plan is untrusted, so **the caller names the destination ref on every call that takes a stored plan** (`checkTransferPlan`, `transferStatus`, `transferStep`, `runTransfer`; types `PlanExpect`, `PlanExpectConfig`, `StepCommit`): the plan's `ref` must equal it, and a call that names no ref is refused (both `bad_request`, `what: 'ref'`). This is a breaking change: `transferStatus(dst, plan)`, `runTransfer(dst, from, plan, commit)` and `transferStep(…, step, commit)` with bare bytes, as earlier versions took them, are now `bad_request`. The temp ref is not a free field either: it must be the name the plan's key gives under `tempPrefix` (`what: 'tempRef'`), so a plan made with a custom `tempPrefix` is resumed by naming that prefix again on every call. The plan is checked once per call, before anything is read or sent; the plan object the call then holds is trusted for that call. The check is one linear pass over the plan on every stored-plan call (`checkTransferPlan`, `transferStatus`, `transferStep`, `runTransfer`): it rehashes the pack plan and walks the selection and every batch's entries, so its time and its transient memory (the pack plan's canonical JSON, one set of the selection) grow with the plan's entry count, and `transferStep` and `runTransfer` add one pass over the pack index. Measured at 04ee345 (Node 24.18, a 16-core laptop, median of 16 calls): about 21 ms for 100,000 entries and about 240 ms for 1,000,000; a caller that drives one `transferStep` per request pays it on each request. The plan's two hashes are unkeyed: they are integrity against corruption and stale or partial writes, not authentication against whoever can write the plan store. They do not hold the batch grouping or order: a writer of the store who regroups or reorders the batches into another partition of the same selection and recomputes what is derived from them (both hashes, the temp ref, the steps' temp commit ids) passes the check, and that plan runs. So what a plan may push is also checked directly, whatever its hashes say: its batches must partition its selection (every selected entry in exactly one batch, nothing else in any; `bad_request`, `what: 'batches'`), and `transferStep` and `runTransfer`, which hold the pack, refuse before any request a plan whose selection is not exactly the pack's trees and blobs (`bad_request`, `what: 'pack'`). Each step is a tagged variant: `{ kind: 'batch', temp, prev }` or `{ kind: 'final', prev }`, `prev` a tagged Option (`{ tag: 'none' }` or `{ tag: 'some', value }`). Every batch but the last moves a temp ref (`refs/ply/transfer/`) to a temp commit whose parent is the previous one and whose tree lists that batch's objects by id, fanned out into up to 256 subtrees by the id's first two hex digits (a flat tree was refused above about 16k entries on Cloudflare Artifacts). Everything pushed so far is reachable at every moment, and every batch is children first, so a strict server's fsck and connectivity check pass on each push. The last batch (the trees) carries the new commit and, in one atomic push, creates `ref` (compare-and-swap on the zero id) and deletes the temp ref; `atomic: false` sends it as one plain push. Every generated id is in the plan, so `transferStatus(dst, plan, { ref, tempPrefix })` reads the two refs (ls-refs) and names the next step, or `done`; a temp ref the plan never writes, or `ref` at another commit, is `cas_conflict`. `transferStep(dst, { source, pack, resolved }, plan, step, { commit, ref, tempPrefix })` is one push; every update is a compare-and-swap, so a step that landed, sent again, is refused (`ng … stale ref`) and moves nothing. `runTransfer(dst, from, plan, commit, { ref, tempPrefix, maxSteps, retries, settle })` loops status → step → settle. Settling reads the refs back after every push, at most `settle.reads` times `settle.delayMs` apart (default 3 and 200 ms), until they show it: a host's ls-refs can lag a push it acknowledged, and a lagging read must not make the loop send the step again. An acknowledged push the refs do not show pauses the run (`{ tag: 'paused', step, reason: 'settling', lastPush: 'acknowledged', lastStep: 'not_shown' }`). One case trusts the server's report instead of a read-back: when the final push is acknowledged (every command in its receive-pack report `ok`, so `ref` was created and the temp ref deleted, in one push, atomic unless the plan was made with `atomic: false`) and a read of the refs then fails (the first settle read, or a later one after reads that did not show the push yet; a settle span whose tracer fails counts as a failed read), the run ends `done` (`tempLeft: false`) on that report alone, in either mode (the `'unread'` arm of `acknowledged` in src/transfer.ts); the same failed read after a batch push ends the run with the read's error, because the transfer is not done. A caller that needs the destination's own word reads it with `transferStatus`. A push that is not a clean ok (ambiguous, rejected, partial) is judged by the refs, the only commit point: the step landed (by this push or another runner's) is progress and the run goes on or ends `done`; it did not land and the push was refused is that refusal; it did not land and the push was `ambiguous` is sent again (at most `retries` times in a row, within `maxSteps`) and then the run ends `ambiguous`, never paused; the refs could not be read is `ambiguous` with the push's own error as `cause`, never the read's error. A step that fails before any push request is made (ply's own refusal, such as `limit_exceeded` against the transport's `maxPackBytes`; the final push's receive-pack advertisement not read, `aborted` or `network` included; a capability the server does not advertise, `unsupported`) is not a push: the run ends with that error as it is, with no settle reads, it is not counted in `pushes`, and it is never `ambiguous` or a `lastPush`. `maxSteps` pauses it (`reason: 'max_steps'`) for the next request to resume. A pause states two facts about the run's last push in two fields (types `LastPush` and `LastStep`, exported beside `TransferRun`), because they can differ. `lastPush` is what the server answered this run's own push: `'none'` (the run made no push), `'acknowledged'` (its report said ok), `'refused'` (the server refused it) or `'unanswered'` (no report reached the run). `lastStep` is what the refs then showed of the step that push carried, whoever landed it: `'none'` (no push), `'landed'` or `'not_shown'`. So `lastPush: 'refused', lastStep: 'landed'` is a run whose push was refused because another runner had landed that step first: the step is on the destination and this run's push is not what put it there. A `max_steps` pause always has `lastStep: 'landed'` (or `'none'`); a `settling` pause is `'acknowledged'` and `'not_shown'`. A run that ends `ambiguous` because a step `did not land after N tries` (or could not be read back) carries the last push's own error as `cause` and its code as `original`. Done is `{ tag: 'done', head, pushes, tempLeft }`: `tempLeft` says a temp ref is still on the destination, for `sweepTransfers`. Spans: `git.transfer.run` over `git.transfer.status`, `git.transfer.step` (step index, kind, batch entries and bytes, generated objects, outcome; the push's wire spans under it) and `git.transfer.settle` (reads, outcome), and `git.transfer.sweep`, each with `git.transfer.plan.hash`. `copyTree` is plan then run. Commit policy: the new commit keeps the source's author, committer, encoding, message and other headers and drops `gpgsig`, `gpgsig-sha256` and `mergetag`; temp commits are written by `ply transfer 0 +0000`, so the same plan always gives the same ids. `sweepTransfers(dst, { prefix, keep })` deletes temp refs an abandoned transfer left: only names of a temp ref's shape, `<40 hex key>`, so a branch, a tag or a near-miss name under the prefix is never deleted. `prefix` (default `refs/ply/transfer/`) must be `refs/ply/transfer/` or a namespace below it ending in `/`; anything else (`''`, `refs/`, `refs/heads/`, a prefix without its trailing `/`, a sibling such as `refs/ply/transfer-old/`) is `bad_request` (`what: 'prefix'`) before any request, so a plan made with a `tempPrefix` outside that namespace leaves temp refs the sweep will not delete. Each request that resumes needs the pack's index and resolved columns again (rescan and resolve the spool, or keep them yourself); there is no serialized form of those yet. **Saved pack index** (#260): `encodeSavedIndex(index, resolved)` turns `scanPackIndex`'s index and, when given, `resolvePackRange`'s columns into bytes the caller stores; `decodeSavedIndex(bytes, { trailer, bytes }, maxDeltaChain, maxPackObjects)` reads them back, and `loadTransferPack(dst, source, saved, { scan, resolve })` does both for a resumed transfer (`loaded` is `saved`, `resolved` or `scanned`, and it returns the bytes to keep). `resolved` and `saved` are an `Option` (`some(value)` or `none`, exported from the root with `isSome`, `isNone`, `matchOption` and the `OptionHandlers` type; `none` is one shared object, so never assign to it). `isSome` and `isNone` answer `false` for a value that is not an `Option`. The root's `matchOption(o, { some, none })` returns a `Result`: `Ok` with the branch's value, `bad_request` (`what` `option` or `handlers`) for an argument that is not an `Option` or a `{ some, none }` pair of functions, and `bad_request` (`what` `matchOption handler`, the thrown value as `cause`) when the branch throws. `decodeSavedIndex` is the one call whose error is not a `PlyError`: its refusal is a typed union a caller branches on (and `describeSavedIndexRefusal` names), because a refused saved index is an expected outcome that means "scan again", not a failure. Stored bytes are untrusted: a saved index is refused (`SavedIndexRefusal`, by `tag`: `not_saved_index`; `version` with `version`; `truncated` with `bytes` and `want`; `corrupt`; `other_pack` with `saved` and `want`, each a `PackIdentity`; `malformed` with `field` and `index`; `limit_exceeded` with `what`, `got` and `max`; `bad_argument` with `what`, `bytes` or `want`, when `decodeSavedIndex` is given a `bytes` that is not a `Uint8Array` or a `want` that is not an object) unless it is an intact index of exactly that pack whose columns a scan plus a resolve could have produced, and `loadTransferPack` then scans again and says why on its span. Where the index carries ids (the default), a REF delta's base recorded as an entry must be the entry whose id it names, in the scan's `baseIndex` column (`malformed` `baseIndex`) and in the resolved base column (`malformed` `resolved.base`). A base recorded as not in the pack (`baseIndex` -1; a thin resolved base, allowed only beside that -1) is not looked up among the ids, so decoding does not show that the pack lacks the object the delta names. Where it carries none (a scan with `oids: false`), a REF delta with a base recorded in the `baseIndex` column is refused (`malformed` `baseIndex`): a scan without ids records none, and there is no id to check one against. The chain limit is the caller's, never a constant: resolved columns are held to the `maxDeltaChain` the caller resolves under, so an index saved under a raised limit loads under the same raised limit and is refused as `malformed` `resolved.depth` under a lower one, as a resolve would refuse the pack. `loadTransferPack` takes it from `resolve.limits` (`resolve.limits` and `scan.limits` are each parsed once, before anything is read; limits in either that do not parse are `bad_request` even when the saved index would have been used). A direct caller of `decodeSavedIndex` passes it as the third argument, the same `limits.maxDeltaChain` it gave `resolvePackRange`; left out, it is the default 64, so stored indexes of packs chained deeper than 64 need it. `decodeSavedIndex` does not parse that argument (pass a number; `loadTransferPack` passes a parsed limit). The entry count is held to `maxPackObjects`, the cap `scanPackIndex` holds a pack's header count to (100 000 by default, the fourth argument of `decodeSavedIndex`; `loadTransferPack` takes it from `scan.limits`, the limits its scan runs under, so a pack scanned under a raised cap resumes under the same raised cap): an index whose header counts more entries is refused as `limit_exceeded` (`what: 'pack objects'`, `got` the header's count, `max` the limit) before its check is computed or any column is built. The count is read before the index's check, so it is untrusted like the rest: `loadTransferPack` rescans on that refusal as on any other and records it (`refused`, and the span's `git.transfer.load.refused`); a pack really over the cap is then refused by the scan's own header-count check. Decoded columns are views into the bytes passed, not copies (a Node `Buffer` and a `Uint8Array` alike; a number column is copied only where it is not aligned in its buffer or the platform is big-endian), so a decoded index holds one copy of the columns: keep the bytes unchanged while the index is in use. `packSubset(source, pack, selection, { extras, outsideBase, resolved })` builds a new pack from chosen entries of an indexed one (`scanPackIndex`), reading the source through a `RangeSource` (`{ size, read(offset, length, signal) }`, the `signal` optional as above: a file, a buffer, an object store's ranged get; `rangeFromBytes` wraps bytes) and copying each entry's compressed bytes unchanged. It returns `{ stream, length, count }` with `length` exact before the first byte, so it feeds `pushPack` directly. `selection` is the source's entry indices in the order to write them, which may differ from the source's: each OFS_DELTA's distance is recomputed for its new position, and a REF_DELTA passes through as it is (a Cloudflare Artifacts pack is all REF). An OFS base must be written earlier in the new pack; one left out or written later is refused, or with `outsideBase: 'ref'` written as a REF_DELTA to the base's id when that id is known. The scan index knows only a whole object's id (oids on). `resolved` (default `null`) is `resolvePackRange`'s result for the same pack, and it knows every entry's id, so with it a chain is cut anywhere, below a delta base too; one with another entry count is refused (`bad_request`, `what: 'pack subset resolved'`), and an id it gives is checked before it is written (40 lowercase hex, or the entry is refused as above). An `oid()` that returns nothing at all is refused in those words (`bad_request`, `what: 'pack subset base'`, "oid() returned nothing", no `cause`); one that throws, with what it threw as the `cause` ("oid() threw"). `resolved.oid(base)` is asked once for each entry rewritten as a REF_DELTA, and the answer that was checked is the one the header carries, so an index that answers differently on a later call changes nothing. Write order: without `resolved` it is exactly `selection`. With `resolved` the pack is written base first: a selected base is moved before the first selected entry that rests on it, through any chain, and entries with no such tie keep the caller's order, so the order written can differ from `selection` (the ids and the bytes of each entry do not). That matters for REF_DELTA: stock git refuses a thin pack in which a REF_DELTA comes before its base when that base is itself a delta the receiver already holds (`index-pack --strict --fix-thin`: "The same object … appears twice in the pack"). Without `resolved` a REF_DELTA's base inside the selection cannot be told from one outside it, so that order is the caller's to get right, and a selection listing such a delta before its base still builds a pack strict git refuses; `planPackBatches` batches are base first either way. A REF base outside the selection makes the pack thin: the receiver supplies the base or refuses. `extras` are small objects ply encodes (a commit, a generated tree), deflated up front and written last; their base may be none or a REF. An extra a pack cannot hold is refused (`bad_request`, `what: 'pack subset extras'`) before anything is read or deflated, never thrown: `extras` itself when it is not an array (`null`, a number, an array-like; left out or `undefined` is no extras), one that is not an object (`null`, `undefined`), `data` that is not a `Uint8Array`, a whole object whose `type` is not 1 to 4 (commit, tree, blob, tag), an OFS base, a REF base that is not a 40-hex id. Consecutive source entries are one range read; the SHA-1 trailer is computed while streaming; a range that serves the wrong number of bytes errors the stream (`pack_corrupt`) before the trailer. `selection` is copied at the call, so changing the array afterwards changes nothing that is written. **Cancel.** `packSubset` takes no `signal` (a `signal` key in its options is not read): it is cancelled through the stream it returns. Cancelling the stream settles at once, whether or not the source ever answers: the `signal` given to `read` aborts with the consumer's reason (an `AbortError` when it gave none), the range in flight is cancelled with that same reason and not waited for, and a range that opens afterwards is cancelled too. A range whose `getReader` is the platform's own (`ReadableStream.prototype.getReader`: a `ReadableStream`, or a subclass that does not define its own) is read through that reader (its `cancel()` settles a read in flight, so each chunk is read with no added promise); any other range, a `ReadableStream` subclass that defines its own `getReader` included, is read through the reader its own `getReader()` returns. A range that is refused (it served more bytes than were asked for) or left unread is cancelled with `null`. A source that inspects the reason used to see `undefined`. Held: 17 bytes per selected entry (the copied index, its kind, its base's position, its new offset), 5 per source entry, the 20-byte base id of each entry rewritten as a REF_DELTA (kept in a map until the stream ends; from the code, not measured), the extras, and the chunk in flight; with `resolved`, also the base-first order (a second array of entry numbers, 4 bytes per selected entry, kept until the stream ends) and 1 more byte per source entry while ordering (these two from the code, not measured). Measured without `resolved` (`test/pack-subset-child.mjs`, Node 24): half of a 537 MB source, 268 MB written, 6 KB live. ## Things the oracle taught us (would have been wrong otherwise) - The whole fetch product space (haves, shallow, deepen-since/not, blob:limit, combine, thin, negotiation) is in `SAFETY.md`; the short version: git has two object-selection modes (bitmap = exact set difference; traversal = edge-tree heuristics), `--thin` changes which objects are excluded, shallow boundaries are grafts rather than negative refs, and `have` processing is order-dependent. - `filter tree:N` **includes blobs** at depth < N. It is not a subset of `blob:none`; `combine:blob:none+tree:N` is. (`test/oracle.test.js`) - git's `patch_delta` rejects deltas shorter than `DELTA_SIZE_MIN` = 4 bytes, which is exactly what "delete the whole file" encodes to. Degenerate deltas are sent as full objects. (found by fuzz seed 3359247) - `receive-pack` unpacks the pack before checking `old`, so a lost CAS race leaves dangling objects server-side. The conflict is still atomic for the ref. (`test/concurrency.test.js`) - Identical replacement would have produced an empty commit. Now a `noop`. (fuzz) ## Test loop `npm test` runs the push matrix as a seeded 1-in-8 sample (~2 min; the seed rotates daily, `PUSH_MATRIX_SEED=` reproduces a day); `npm run test:push-full` runs all 1,400 cells (~20 min). Coverage: 100% of lines across every `src/` module (`npm run coverage`), with the matrix excluded because it adds time, not lines. ``` npm run lint # oxlint; no-magic-numbers on the wire decoders (0 and 1 are the only allowed literals) npm run test:props # ~5 s: pure step functions — chunking invariance, codec roundtrips, node:zlib/crypto oracles npm run test:mutate # Stryker across src/. Full run locally and on main; a PR mutates only the src lines it changes npm run fuzz:below-hash -- --n 20 --seed 1 # mutate decompressed objects, re-hash, fetch, compare with git fsck --strict npm run test:oracle # ~5 s: real git — tree oids vs write-tree, git pack-objects (ofs-delta, 5 window/depth/compression combos) parsed to cat-file truth, verify-pack chain depths, index-pack --fix-thin accepts our thin packs, filter semantics, 6-writer CAS convergence npm run fuzz -- --n 200 # ~30 s: steered generative cases against git http-backend npm run test:git # ~15 min: fsck/check-ref-format/mktree compliance, clone/fetch parity with git's client, 768-cell push matrix vs git push npm run test:protocol # ~4 min: exhaustive fetch matrix (14,256 cells) vs pack-objects + captured upload-pack invocation npm run fuzz:protocol -- --n 500 # random wants/haves/deepen/filter/thin/negotiate/shallow on generated DAGs npm run trace -- fuzz-out/trace.jsonl git.receive-pack "git.push.ok==false" ``` An equivalent mutant stays only as `// Stryker disable next-line : ` on that line. A blanket `Stryker disable all`, or dropping a parser file from the Stryker config, fails `npm run test:mutate`. See SAFETY.md. ### The fuzzer `test/fuzz/gen.js` draws from a product space of named classes: blob content (`empty tiny text random repetitive boundary big binaryish`), match position (`start end middle chunk16k chunk32k chunk64k random`), find/replace length classes (incl. >127 for insert-op chunking, 64K copy-op boundaries, empty), server `core.compression` 0…9/−1 (stored / fixed / dynamic Huffman blocks), path depth 1…10, sibling shape (`none few many sortedge`: names that sort differently as dir vs file, unicode, leading `-`), history depth (so `deepen 1` reports `shallow`), file mode, and intended outcome (`ok noop zero_matches two_matches missing_path not_a_file cas_conflict` — the CAS case injects a competing push between our `ls-refs` and our `receive-pack` via `fetchImpl`). Each case is checked against git: ref advanced to our commit, `cat-file` bytes equal the expected splice, `diff --name-only -z` touches exactly the path, parent/author/message, tree oid, mode preserved, `fsck --strict`, plus two efficiency properties — push bytes ≤ `220 + 80·depth + |replace| + ⌈|replace|/127⌉ + 5·⌈|replace|/16K⌉ + 16·⌈|blob|/64K⌉` and max single allocation ≤ 70 KB regardless of blob size — then a second edit that must hit the tree cache at every level. Failures write `fuzz-out/fail-.jsonl` and print `--case ` to replay. ### Steering After each case the spans are bucketized (`buckets()` in `run.mjs`): inflate block types seen, pkt-line carry across TCP reads, max-size pkts, sideband frames, multi-chunk scans, matches straddling a chunk, delta op counts, chain depths, tree sizes, outcomes, push ratio, allocation high-water. 55% of cases target the least-covered bucket via a bucket→knob map (`TARGETS`), 20% mutate one knob of a case that hit a rare bucket, 25% are uniform. The run prints the coverage table and any `TARGETS` never reached. ## Layout ``` src/sha1.js streaming SHA-1 (subtle.digest can't stream) src/inflate.js zlib/deflate inflate that returns bytes consumed (packs have no length prefix) src/pktline.js pkt-line encode; decoder as pure (state, chunk) → {state, frames} src/pack.js pack parse/resolve, delta apply/generate, thin pack build src/objects.js blob/tree/commit codecs, tree sort (dir-as-slash) src/client.js v2 ls-refs/fetch (streamed sideband), v0 receive-pack; request bodies & response state machine are pure src/edit.js the pipeline; single-object pack stream + find/replace scanner as pure step functions src/otel.js OTLP/JSON tracer, one ExportTraceServiceRequest per line src/bytes.js alloc accounting (Mem), concat, indexOf ``` Prod lib is ~1100 lines. Tests are the rest.