The refactor: target and gates
The rules are docs/STACK.md ("Rules for code in src/", "Absence", "Public API policy"). This file is the finish line in numbers, and the order the work lands in. Pre-1.0 and breaking by design: no compat shims.
Finish line (each one a gate that fails the build, not a goal)
| # | Property | Gate | Today → done |
|---|---|---|---|
| 1 | No platform absence outside src/absent.ts: no undefined, ?:, ?., ?? | scripts/absence-ratchet.mjs (in npm run typecheck) | met (a7982c0): 308/375/146/260 → 0/0/0/0 |
| 2 | Errors are values: throw only for assertNever, an internal invariant, a stream's own protocol, and a caller's callback's value passed back | scripts/throw-ratchet.mjs (in npm run typecheck) | met: 377 → 23 (every one of those four kinds; no throwing wrapper is left) |
| 3 | Every switch or tag chain over a closed union ends in assertNever | scripts/exhaustive.mjs (in npm run lint) | holds |
| 4 | The public API returns Result (0.2.0), ply-web updated in the same window | the bundle and type tests on dist/ | met in ply (rounds A–D); ply-web must switch before this lands on main |
| 5 | Every gate CI runs is green on every commit to main | .github/workflows/ci.yml, all 26 jobs | the rewrite left 23 red. Locally on ef29502 every gate passes but push-ng (local git 2.43; fails identically on the untouched pre-rewrite tag; CI runs 2.56) |
The one edge
Absence exists where a caller's data enters, and nowhere else:
- Options a caller may leave out are
Input<Config>(src/absent.ts) and are parsed once, at the entry, bywithDefaults(options, freshDefaults())into a totalConfig. Past that line no code asks whether a field is there.Input<T>is allowed for exactly two things: public entry option records, and the errorExtrabag. - Shared mutable records a caller owns and passes to every call (a transport's learned
quirks) are filled in place withfillIn, so the caller's record stays the one later calls see. - A caller's transport is a
TransportInput;asTransportfills its quirks, harvest store and scrubber at the edge (operation()). - Thrown values and foreign records (a JSONL line from another producer, a platform error) are read with
field/readKey/fromNullish, which returnOption.
Inside: absence a lookup produces is Option<T>; a total record's "none given" field is T | null; alternatives are tagged unions.
Order
- Green trunk (b350b96). The rewrite's seven red pushes: commitChanges limits regression, http lint, decoder and decision registries, absence ratchet, stale sweep lines; #164.
- Wave 1: total shared types (97802db, b2020be). Transport, OperationOpts, the thrown-value readers, otel: the types every cluster reads, so clusters convert without touching each other's files.
- Wave 2: clusters, in parallel (STACK.md "Converting a module"): packs, wire, write, merge, read, core. Each drove its files to zero absence, returns
Resultinternally, and kept a throwing wrapper for what another cluster or the public API still calls. Done: a7982c0. - Leftovers: LsRef total, OrMissing deleted, honest Result/wrapper names (ec02ad6, 3814e4a). Done.
- Cut-over (STACK.md step 3), bottom-up so a function's callers convert after it: round A codecs and validation; round B protocol, transport and
operation(); round C the entries (write, read, merge in parallel); round D deletethrown/orThrow, 0.2.0, docs. Tests keep their assertions throughtest/unwrap.js. Done. ply-web switchescatchfor an exhaustiveswitch (r.error.code)before this lands on main.
Visible changes so far (callers can observe these)
A
quirksrecord passed to a transport is filled with the defaults (treeFilter: 'tree:0',blobWants: 'many') instead of staying empty until a fallback is learned.A root
Span'sparentSpanIdisnull(the exported OTLP line still omits the key).Span
statusis a tagged union: onlycode: 2carriesmessage.memtree.replaceOncereturns aResult.A listed ref (
LsRef) always haspeeledandsymref-target,nullwhen the line carries none.parsePackobjects (andresolvePack's, anddescribePack's rows) carrybase, a tagged union ({ tag: 'none' },{ tag: 'ofs', offset },{ tag: 'ref', oid }), in place ofbaseOffset/baseOid;resolvePackno longer writes.oidonto the caller's parsed objects. A hand-builtresolvePackinput givesbasethe same way with plain values (left out: none) and is parsed at resolvePack's edge: a bad type, base or data isbad_request(a type outside the six used to bepack_corrupt).A pack object's declared size is checked where its header is read (
readObjHeader's cap):fetchObjectof an object pastmaxObjectSizeislimit_exceededwithwhat: 'pack object size'(was'object size'), asparsePackalready said, and the scan refuses it before reading an OFS/REF base.inflate()is a collector over the pull decoder, so it refuses what the pull refuses: CINFO > 7 (zlib: window size N is not a zlib window) and a back-reference past the declared window (inflate: distance too far back), bothpack_corrupt(the owner's ruling on #172).A wide fetch whose want cannot be a blob (a tree or commit through the blob:none or unfiltered fallback) drops the pack's blobs and their deltas as their headers arrive; they are counted in
git.fetch.wide.blobs, at their declared size ingit.fetch.wide.extra_bytes.mergeBasewithmaxDepth: null, andinflatewithexpectedSize: null, mean "not given" (the configured limit, no expected size) instead ofbad_request.Parse once (#156): a fetch want is an object id. A want git's upload-pack refuses ("expected to get oid": a ref name, an abbreviation, an empty want) is
bad_request(what: 'want') before any request; an upper-case id is sent lowercase (git reads either case as the same object); text after the id, which git ignores, is refused.lsRefsBodyrefuses a prefix with a NUL, CR or LF (what: 'ref prefix', aslsRefs) instead of writing it.encodeTreerefuses a mode other than the five git writes (what: 'mode') and an id that is not 40 lowercase hex (what: 'oid') instead of writing them;buildCommitObjectsrefuses a new blob id that is not one.mergeBaserefuses an id that is not 40 lowercase hex (what: 'oid') before any fetch;walkPathrefuses its tree id (fetchObject's refusal) even when there is no path to walk.validateSpec's plan carriesbaseas{ kind: 'ref', ref } | { kind: 'commit', oid }(nobaseOidflag);editFileparses the spec once, so a retry reuses the first attempt's commit time.Parse once (#156): a limits record is parsed once where it enters (
parseLimits):createTransport/GitHttp.create,operation()(every entry), a transport handed in (transportFrom),syncRef, and every public codec that takes limits (parseTree,parseCommit,parsePack/packParseOpts/parsePackInit,resolvePack,describePack,indexPack,verifyFetchAnswer,validatePath/parsePath,fileEntries,buildTree,validateTreeSpec,validateSpec,treeFiles,commitView,filesFromDir,writeFiles,objectsForPack,reachableObjects,planPush). A key that is present must be a finite non-negative number: the samebad_request(limits.<key> must be a finite non-negative number,what: <key>,got) as before, but refused at the entry before any request, whichever operation would have read it (it used to be refused only at the read that used it, so a bad key an operation never reached was never refused). When several keys are bad, the first inDEFAULT_LIMITSorder is the refusal, and an entry parses its limits before its spec (a call with both wrong gets the limits refusal). A key that is missing, or passed as the platform missing value, takesDEFAULT_LIMITS's value (it used to be refused at its first read;validatePath(p)andparsePath(p)with no limits record used to refuse every path);nullis a value, and refused.Transport.limits(andGitHttp#limits) is aCheckedLimits, branded byparseLimitsalone;DEFAULT_LIMITSandWORKER_LIMITSare checked records.parseLimits,CheckedLimitsandLimitsInputare exported.v2Inittakes aCheckedLimits(parseLimitsa caller's record first; the default isDEFAULT_LIMITS). AcachingFetch(which returns noResult) parses itslimitswhere it verifies an answer, as before. A merge's blob reads keep their bound as the lower ofmaxObjectSizeandmaxMergeBlobBytes.Parse once (#156): a fetch
haveandshallowis an object id, as a want is: upload-pack dies on anything else (process_haves"expected SHA1 object",process_shallow"invalid shallow line"), so one isbad_request(what: 'have'/'shallow',invalid have: must be an object id (40 hex digits)) before any request; an upper-case id is sent lowercase; text after the id is refused.negotiateparses every have before its first round (a bad one in a later batch used to be sent rounds later, or refused only then), and an acknowledgment that is not an object id isprotocol(it used to be offered back to the server as a have).Parse once (#156):
mergeTreesparses itsbase/ours/theirstree ids at the edge (nullis the empty tree; anything else must be 40 lowercase hex:bad_request,what: 'oid', in that order) before any tree is read (a bad one used to be refused by the first fetch).encodeCommitparsestreeand eachparent(after the header checks it always made): not 40 hex digits isbad_requestwhat: 'tree'/'parent'(it used to write the line; git's fsck refuses it:badTreeSha1,badParentSha1), and an upper-case id is written lowercase, asgit commit-treewrites it.buildCommitObjectsparsesoldCommit.buildPack's input (PackInput, also push'sobjects) gives its base as a tagged union with the read side's tags:base: { tag: 'none' } | { tag: 'ofs', index } | { tag: 'ref', oid }(left out: none), in place ofbaseIndex/baseOid. An ofs base names an earlier object by its index (its offset is not known until the pack is written). The quirks of the flag fields are gone: an emptybaseOidmeant no base, andbaseIndexbesidebaseOidwas an OFS_DELTA whose entry named no base.planPushrefuses, before anything is built, an ofs base that names no earlier object, a ref base that is not an object id (what: 'base', both), and an object that still carriesbaseIndex/baseOidor a base outside the three tags (it used to ignore an unknown field, and send a delta as a whole object).buildPackand the streamed push writer share one entry encoder (pack.ts entryHead); their bytes are unchanged.0.2.0: every exported function that can fail returns
Result<T, PlyError>;GitHttpis built withGitHttp.create(url, opts)(aResult), and its methods return the free functions' Results.failfrom the package isErr(plyError(…));plyErrorbuilds the error value.thrown/orThroware gone.A value a caller-supplied transport raises that carries a ply code but is not an
Errorcomes back as the Err, unchanged (it used to be rethrown); it is never mistaken for ply's owncas_conflict(no retry) or an unborn HEAD.A value the caller's own callback throws inside an operation comes back as an Err, never as a throw: a signer or a
pushDirfilter isbad_requestnaming it inwhatwith the thrown value ascause; afetchImplfailure is the transport's coded Err; any other foreign throw isbad_request(what: 'callback'), orambiguousonce a push request was handed to the transport. Telemetry callbacks (exporter,onEnd) never change an outcome.The user agent and the otel scope version are
ply/0.2.0/0.2.0.
Not carried forward
Five PRs the rewrite closed and never re-landed: #167 and #168 (brands on validated refs and wire fields) and #169 (a total capabilities record) are subsumed by waves 1 and 2 in this style; #173 (pull-based stream primitives) is a separate design change and should be re-proposed against the converted wire cluster. #164 landed in step 1.