alkblobs/docs/architecture/open-questions.md

status, last_updated, notes

status	last_updated	notes
draft	2026-10-17	OQ-15 resolved 2026-10-17 (ADR-018 — the git-object derivation family, review-002 C-1's decision half; its implementation half is decided-but-sequenced work, `c1-git-object-family-impl`). OQ-12/13/14 resolved (ADR-015/016/017, 2026-10-15). OQ-16 resolved (ADR-019, 2026-10-17). OQ-07/08 remain externally-owned

Open Questions

Centralized tracker. Theme sections hold OQs; cross-theme status lives in the Deferred/Blocked index below.

Deferral policy (the Schrödinger's-code rule). A decision this crate needs before shipping may not be deferred on a dependency that is itself waiting for this crate to exist. alkgit is paused mid-Phase-1 to build this core; alkfs is pending that shared base. "Deciding input: what alkgit wires first" never collapses into an input, so it is not one. Two kinds of parked question remain legitimate:

• deferred(scope) — the deciding fact exists independently of this crate (e.g., alkfs Phase 0 outcomes); the crate proceeds on its own ADRs meanwhile.
• externally-owned questions — questions about how a consumer maps onto this crate, which are not decisions this crate needs before shipping and are not this document's to decide; they are carried here for visibility, owned by the consumer's own process, and collapse when that consumer acts (including on an API of this crate that will exist by then — that is acceptable only because the question gates no decision here; it would be Schrödinger's code if it gated one).

Invalid for either kind: a blocker that is a decision this crate must make before shipping. (A third category — decided-but-sequenced work — is not a parked kind at all; see below.) Phase 0's residual list was swept under this rule: every residual either resolved into an ADR (the evidence was already in hand) or re-owned as below.

The line between the two kinds (added 2026-10-03, after the pg-lo round): deferring on a consumer's design decision is valid — the deciding fact is obtainable independently of this crate (OQ-07, OQ-08). Deferring on a consumer's deployment of this crate is invalid — that fact is created by this crate (OQ-10's original framing, OQ-09's original framing). And a third thing is neither: decided-but-sequenced work. Once a question resolves to a decision (the pg-lo engine is the named large-tier candidate under REQ-2/ADR-008), what remains is the evidence pipeline the decision's own admission gate requires (POC #7) — a task with an owner, not a parked question, and not a hedge. A decision is not "unmade" because its verification is pending; deferral policy applies to decisions, not to work.

Index of active OQs: none — no OQ is active or parked. The last two of this register resolved 2026-10-17: OQ-15 (ADR-018 — the git-object derivation family; review-002 C-1's decision half), and OQ-16 (ADR-019 — the token registry's admission posture). Earlier: OQ-12, OQ-13, and OQ-14 resolved 2026-10-15 (ADR-015, ADR-016, ADR-017); OQ-07, OQ-08 remain externally-owned (carried for visibility, gating nothing). OQ-09, OQ-10, OQ-11, and the review-001 register (OQ-12/13/14) are resolved (recorded below). The parked index has no active rows — OQ-07/OQ-08 are externally-owned, not parked rows. Promoted Phase 0 questions OQ-BL-01..06 are recorded here with their resolutions for traceability.

---

Theme: consumer integration

OQ-07: How alkgit's object-storage seam consumes alkblobs

• Origin: overview.md, gc-and-namespaces.md
• Status: externally-owned (alkgit) — carried here for visibility; not a decision this crate must make before shipping
• Priority: high (it is why this crate exists) — but not a blocker: alkblobs builds by its own ADRs; this question maps the consumer on.
• Owner: alkgit (external)
• Question: how do alkgit's reviewed GitRefs/GitPackGen/GitPackIngest traits (its backend.md, ADR-018) sit over alkblobs — gix-odb-over-pool, alkblobs-behind-those-traits, or a mixed composition (e.g. refs in the pool, pack generation still gix)? Which tier serves the loose tier; does packfile serving (ADR-005) get wanted at all?
• Resolution: owned by alkgit's architecture process; it is answerable on paper against this document tree (backend.md + these ADRs) whenever alkgit's process acts, and gates nothing here. This crate's obligations toward it are already fixed: git-oid addressing (ADR-002), liveness seam (ADR-005), serving surface (ADR-006/store-api).
• Cross-references: OQ-08, ADR-002, ADR-005, ADR-006

OQ-08: alkfs requirement intake

• Origin: overview.md, backends-and-dispatch.md
• Status: externally-owned (alkfs) — carried here for visibility; alkfs Phase 0 has not run
• Priority: medium (alkfs Phase 0 pending; nothing here blocks on it)
• Owner: alkfs (external)
• Question: what does alkfs's Phase 0 name as requirements on the shared base — durability tiers, sync/replication seams the store does not expose, manifest-layer shapes beyond ADR-004's boundary (e.g. the appfile write-session shape as a consumer concern)?
• Resolution: owned by alkfs's Phase 0 (independently obtainable — it needs no alkblobs artifact). The store's posture toward an unknown consumer is deliberately permissive: open trait + addresses + liveness seams (ADR-003/004/005) without baking an alkfs shape in.
• Cross-references: OQ-07, ADR-004

OQ-10: Postgres as the second shipped kv engine

• Origin: docs/research/poc-postgres-kv-findings.md, poc-redb-kv-findings.md, backends-and-dispatch.md
• Status: resolved — by ADR-007 (2026-10-02)
• Resolution: the kv tier ships two engines — sqlite (default) and postgres (feature postgres, default-off) — behind one Backend trait; engine selection is a per-node constructor parameter (ADR-007). The evidence base was already complete (POC #3 A4's sqlite solo curves; POC #5 B1-B6's pg concurrency scale-out and posture deltas; POC #6 C1-C6 ruling out redb at a durability-tier mismatch) — all deciding facts were in hand, and the only thing the prior framing left outstanding was this crate's own build sequence, which is implementation sequencing, not an open architecture question.
• Why this is not Schrödinger's code (recorded because the question was once framed as an externally-owned standing offer): the proposed trigger — "a replicator-shaped deployment materializes" — is a fact only this crate could create (a deployment running alkblobs capable of pg cannot pre-exist the pg engine), so gating on it was circular hedging, the exact corollary the README names and the precedent OQ-09 resolved on. The topology-not-throughput decision rule and the measured curves stand on evidence in hand; the deployment is where the costs named by the ADR (POC-derived posture defaults) get verified — a deferred cost in the ADR-006 pattern, not a gating input.
• Reopen condition (not a parked question): a third engine is the ADR-003/007 substitution door — a new ADR with its own measured evidence and sweep-safety proof. "Some future deployment might want it" does not open it.
• Cross-references: OQ-07, ADR-003, ADR-004, ADR-007, POC #3, POC #5, POC #6

---

Theme: ops surface

OQ-09: Default visibility of namespaces in network ops

• Origin: ops-surface.md
• Status: resolved
• Resolution: closed-by-default (deny-unlisted namespaces: no ACL entry ⇒ no read, no write). The deciding fact for this is not a future deployment (one that can only exist once the ops module ships is not a deciding input — Schrödinger's-code rule); it is the risk asymmetry on evidence in hand: an open-by-default store accidentally exposes content and the exposure is discovered only after the fact, while a closed-by-default store's failure mode — a legit access attempt denied until a grant exists — is loud, cheap, and recoverable at grant time. A conservative default is chosen by reasoning from the failure modes, not measured against a deployment. This is a made decision with a deferred cost (an embedder wanting public read pays one explicit grant), not an unmade decision.
• Reopen condition (not a parked question): a concrete use case names why a namespace needs open read as a default — that is a new requirement naming a new decision (the same shape ADR-006 gives the chunk-tree question: deferred cost, re-entry at a new ADR if ever named). "Some future embedder might exist" does not open it.
• Cross-references: ADR-001, ops-surface.md

---

Theme: review-001 register (post-wave-7 general review) — resolved

Opened 2026-10-14 from review 001 (the post-wave-7 whole-surface pass): the review's decision-shaped findings route through OQs and ADRs — the fix-shaped findings do not (the review doc is their record). All three were decisions this crate needed before shipping; none was parked, and none deferred on a consumer (Schrödinger's rule: what the local tier's durability contract is, what a reaping sweep may touch, and what a grant or token confers are this crate's facts, not a deployment's). All three resolved 2026-10-15 on evidence already in the tree, each as an ADR; their gates satisfy waves 9/10's decomposition conditions in docs/plans/implementation.md.

OQ-12: The local tier's durability posture — fsync discipline, or a recorded no-fsync contract?

• Origin: review-001 F-3 (docs/reviews/001-storage-surface-general-review.md)
• Status: resolved — by ADR-015 (2026-10-15)
• Resolution: (a) fsync-durable publish — file fsync before the publish's directory-entry mutation (no-replace; hard-link publish primitive), directory fsync after it, scoped to the publish paths (ADR-015). Decided on evidence in hand: (b) would record corruption that is both possible and silent (the tier does not re-verify on read per ADR-006, so the git-precedent's zlib detector does not transfer); the fsync cost amortizes over the threshold-routed content class (POC #7's durable-local measurements); no constructor knob (the ADR records the rejection). The OQ's unconditional items are part of the ADR: error-on-truncation on the unix pread path, the no-replace publish (the never-overwritten invariant goes from documented to held), and write-error-discards-stage. Gated consumer satisfied: wave 9's F-3 task now has its decision terms.
• Cross-references: ADR-003, ADR-006, ADR-015, REQ-1, review-001 F-3/D-2

OQ-13: pg-lo reaping vs co-tenancy — who owns the large objects in a shared database?

• Origin: review-001 F-4
• Status: resolved — by ADR-016 (2026-10-15)
• Resolution: (b) strengthened — one large-object consumer per pg database, enforced as a constructor declaration gating the reaping method (orphan_reap_permitted, default false; reap_orphans refuses without it — the ADR-012 §3 deployment-verified-invariant pattern). The guard direction (a) was evaluated and rejected: the reap target class (LOs without companion rows) is indistinguishable from foreign consumers' LOs in the database-level catalog, so a robust guard kills the sweep and a weak one misses the actual loss case; no requirement wants the co-tenancy (fleets share one pool = one schema; ADR-012 §4), and same-pool multi-app consumers were never the hazard. The riding fixes are in the ADR unconditionally: the lo_entries(loid) index, the vanished-loid tolerance, and the candidate-snapshot race fix. Schema isolation of rows is unaffected (the hostile-schema test stays; only reaping is declaration-gated).
• Reopen condition (per ADR-016): a consumer names a real co-tenancy requirement — that is a new ADR, with a real guard design (and the catalog-ambiguity story for non-alkblobs consumers resolved explicitly), not a reopening.
• Cross-references: ADR-009, ADR-012 §3/§4, ADR-016, REQ-2, review-001 F-4

OQ-14: The ops authority model — what does a grant or a token actually confer?

• Origin: review-001 S-1 + S-3 (one model question; decided together)
• Status: resolved — by ADR-017 (2026-10-15)
• Resolution: (a) the model is named — CAS global pool; namespace/ACL is capability-to-ask, not data partitioning (ADR-017). (b) was unavailable: per-namespace pool separation would regress against REQ-4's structural cross-workspace dedup requirement and the OQ-BL-05/ADR-005 posture ADR-003 already generalized (physical separation = a topology concern, two stores). The ADR fixes the misleading texts ("absent from its namespace's pool" → pool framing), carries the model statement on the ops module doc, rules renewal authority as namespace parity with confirm (the mint records the namespace; the renewal validates against it), and resolves the write-only renewal duty as an explicit named role requirement: a remote fleet putter must hold read+write on its namespace (both have-based duties — confirm probe and renewal — ride read; the ACL matrix's write ⊄ read is untouched). The module doc and error texts carry the landed model (wave 10's S-1/S-3 task now has its decision terms). OQ-09's closed-by-default enforcement is unchanged.
• Cross-references: OQ-09, OQ-BL-05, ADR-003, ADR-005, ADR-010 §4, ADR-012 §2, ADR-017, review-001 S-1/S-3, ops-surface.md

---

Theme: review-002 register (the first consumer's review) — resolved

Opened 2026-10-17 from review 002 (the first consumer's evidence — alkgit's three recomposition POCs, pre-publish). The review's C-1 and C-2 were decision-shaped and routed through OQs and ADRs (the review-001 pattern); C-3/C-4 are fix-shaped ride-alongs (the review doc is their record). Both OQs resolved 2026-10-17 — OQ-15 by ADR-018 (C-1's decision half; its implementation half is decided-but-sequenced work, the c1-git-object-family-impl task) and OQ-16 by ADR-019 (c2-token-custody-posture, its own decision-and-landing unit) — per the plan's sequencing for the publish window (the wave is small; the consumer is waiting).

OQ-15: The git-object derivation family — does the hash registry extend to non-blob git forms, and on what contract terms?

• Origin: review 002 C-1; alkgit's substrate-recomposition DQ-1a (POC-O-validated)
• Status: resolved — by ADR-018 (2026-10-17; wave 13's c1-adr-git-object-family task, the ADR task that precedes and gates c1-git-object-family-impl — the implementation half is decided-but-sequenced work, not an open question)
• Priority: was high — the publish hold's primary reason (a one-way door: key bytes persist in kv rows, local files, pg-lo companions; pre-publish was the cheap window)
• Owner: this crate's architecture process (the ADR conversation; the prototype branch poc-o-git-objects was the working reference to re-derive from, not to merge)
• Question: the shape on the table was the single git-object derivation family — registry bytes 0x03/0x04, the preimage-identity derivation (git's loose-object form "<type> <len>\0" + content stored as the value; the digest is the plain hash over it, byte-identical to git's oid, every kind included). The ADR owns the contract terms: the ops kind question (Digest::from_git_oid_hex's 40/64-hex ingress is ambiguous across families once non-blob forms share the digest space), the stat = stored-preimage-length semantic, ADR-002's annotated exception (preimage-identity hashing vs the domain-separation invariant), the namespace posture (git oids are global; ADR-017's caveat stated for the family), and the public put shape.
• Resolution: the family registers as specified (ADR-018): registry bytes 0x03 (git-object-sha-1) / 0x04 (git-object-sha-256), both assigned pre-publish; the derivation preimage-identity over git's loose-object form as the stored value. The five contract terms: the ops kind question answered family explicit everywhere, no length-based family guessing — from_git_oid_hex's contract is pinned the blob family only, the ops surface stays blob-family in 0.1 (schema gate and ingress agree by construction; a family-explicit wire form is a named-consumer + new-ADR door), and family-explicit oid-bytes construction rides Key::from_bytes over the physical encoding; the stat semantic pinned as the stored-preimage length for family entries (deliberate, per-family, documented); ADR-002's domain-separation invariant admitted the family as an explicitly annotated exception (ADR-002 gains the annotation; the surviving invariants named verbatim); the namespace posture stated — git oids are global, ADR-017's CAS-global-pool caveat applies unchanged (the consumer accepted it on the same terms as its LFS acceptance); the public put shape pinned as put_git_object(algorithm, len, stream) — known-length only, family members only, error mapping inherited from the known-length path. Fleet threading is part of the family's contract (the prototype skipped it; the implementation lands the derivation-parameterized sites + fleet forms). Rejected alternatives named in the ADR: the oid-to-key map (DQ-1b), a kind-x-hash matrix, length-based family guessing, an unknown-length family arm, deferring the sha-256 sibling byte.
• Cross-references: ADR-002, ADR-017, hashing-and-keys.md, store-api.md, ops-surface.md, review-002 C-1, the prototype branch

OQ-16: The token registry's admission posture — what does the mint contract answer to the non-fleet no-confirm custody loop?

• Origin: review 002 C-2 (review-001 S-5's deferred admission cap; the deciding input it was waiting for arrived — POC-L's recorded attack shape)
• Status: resolved — by ADR-019 (2026-10-17; wave 13's c2-token-custody-posture task, its own decision-and-landing unit)
• Priority: was high — a publish-decision in substance ("not silence" was the bar); resolved with the shape documented and the cap landed
• Owner: this crate's architecture process (the mint contract is this crate's fact)
• Question: on a non-fleet store an unconfirmed custodial token holds its pin indefinitely, registered per mint, with no cap on mints — a hostile LFS-style upload loop is unbounded pin-holding plus unbounded registry growth. The decision space: (a) the admission cap at the mint boundary (which must answer the already-verified put honestly — the put handler mints after the commit), (b) the fleet-form TTL posture made available to non-fleet deployments, (c) the documented embedder-responsibility posture with the attack shape on paper.
• Resolution: (a) and (c) as a split; (b) rejected (ADR-019). The admission cap lands at the mint boundary — a registry-entry-count bound (both custody forms) wired from OpsConfig::token_registry_max_entries (default 65_536; usize::MAX uncapped), refusal not eviction (Error::RegistryFull, the error family's sixth member by ADR-012 §6.5's own rule), with the put handler answering the already-committed put through the new declared MINT_REFUSED wire error (the committed digest in the details; the CAS-idempotent re-put is the recovery) — the S-5 judgment ("not trivially expressible") flips on the new input: the concrete attack shape converts the cap from an open eviction-policy question into a bounded-refusal one (whose entry dies: none). The non-fleet custody posture is documented with the attack shape (module doc, ops-surface.md, TokenRegistry's doc): the door's mint policy is the embedder's; the fleet TTL is the safe posture for a door that cannot prove confirm; the cap bounds the registry's own resources, not the pool's bytes-between-sweeps story. (b) — the fleet TTL posture made available non-fleet — is rejected on record: the TTL is the fleet core's pin-row machinery (not a knob), expiry would break the confirm verb (registering liveness for possibly-swept content), and the honest alternative already exists (the fleet form, or door-level admission policy); re-opening is a new ADR.
• Cross-references: ADR-017, ADR-012 §2/§6.5, review-001 S-5, review-002 C-2, src/ops/tokens.rs, src/ops/put.rs

---

Theme: promoted Phase 0 register (resolutions recorded)

OQ-BL-01: Crate scope — store-only, or store + ops surface?

• Origin: docs/research/phase-0.md
• Status: resolved
• Resolution: store-only core; ops surface exists as a feature-gated alkcall-backed module (placement decided, not hedged — Schrödinger's-code rule applied: no waiting on paused consumers). Full rationale: ADR-001 (family-pattern conformance record; placement; no-store-layer-wire invariant).
• Cross-references: ADR-001; OQ-09 (its one former residual policy line, now resolved closed-by-default)

OQ-BL-02: Multi-backend dispatch

• Origin: docs/research/phase-0.md
• Status: resolved
• Resolution: lean Backend contract + two shipped backends + pure-function size routing (pre-threshold buffering for unknown-length puts); migration eliminated by construction; per-namespace backend config rejected. Full rationale: ADR-003.
• Cross-references: ADR-003, ADR-004

OQ-BL-03: Hash abstraction

• Origin: docs/research/phase-0.md
• Status: resolved
• Resolution: canonical git-blob-sha-256; git-blob-sha-1 tolerated; BLAKE3 excluded from the crate. Key bytes: algorithm-in-key, fixed-length enum-tagged, tag byte dropped. The declared wire-format ADR. Full rationale: ADR-002.
• Cross-references: ADR-002, ADR-006

OQ-BL-04: Verification and chunking

• Origin: docs/research/phase-0.md
• Status: resolved
• Resolution: whole-blob verification; range reads carry out-of-band slice digests; chunk-tree/CDC encodings excluded by scoping (not deferred — the transfer-encoding consumer cannot be waited on; re-entry is a new decision at a new layer if ever named). Full rationale: ADR-006.
• Cross-references: ADR-006, ADR-001

OQ-BL-05: Pooling and GC

• Origin: docs/research/phase-0.md
• Status: resolved
• Resolution: one pooled CAS; flat bytes + logical namespaces; store persists no root table; mark-and-sweep with three liveness sources (registered sources / RAII + batch pins / protect callback with abort); delete windows close the sweep-vs-put race; explicit sweep, embedder-owned cadence; packfile serving rides large-blob range reads if ever wanted. Full rationale: ADR-005.
• Cross-references: ADR-005, ADR-003

OQ-BL-06: POC register

• Origin: docs/research/phase-0.md
• Status: resolved (complete: #1, #3 passed; #2 absorbed; #4 covered in miniature, concurrency half specified as architecture in ADR-005; post-convergence additions #5 postgres and #6 redb passed and fed ADR-007; #7 pg-lo passed 2026-10-03 — poc-pglo-findings.md, spec poc-pglo-spec.md, requested by REQ-2/ADR-008)
• Resolution: register complete and extended post-convergence; Phase 0 ended; evidence trail in docs/research/. The register's canonical numbering lives in phase-0.md OQ-BL-06.
• Cross-references: all ADRs above

---

Parked index (deciding fact / owner — externally-owned rows are not blockers)

No active parked rows remain. OQ-15 resolved 2026-10-17 (ADR-018); it was never parked — it was in-wave sequenced work (wave 13's ADR task, above), the header's third category taken to task level, and its implementation half remains exactly that category (decided-but-sequenced: the c1-git-object-family-impl task, against a decided contract). OQ-07/OQ-08 are externally-owned (above), not parked; OQ-09/OQ-10/OQ-11/ OQ-12/OQ-13/OQ-14 are resolved with their records kept here for auditability (the review-001 register's resolutions are ADR-015/016/017, 2026-10-15), and OQ-16's resolution is ADR-019 (2026-10-17).

OQ	Status	Deciding fact / owner
OQ-07	externally-owned	alkgit's architecture process (answerable on paper anytime; gates nothing here)
OQ-08	externally-owned	alkfs Phase 0 intake

OQ-11 was deferred(scope) on "a named deployment requirement for a pg-only kv node arriving from outside this crate" (overview.md's feature-graph note; the audit trail of the parked wording is kept: the kv feature's rusqlite pull decoupled from default-on feature graphing). The 2026-10-11 audit round resolved it as a live circular hedge: the deciding fact already existed in this tree — REQ-2 (operator authority, 2026-10-03, pre-POC) names the deployment requirement, and ADR-009 shipped its consolidation posture ("a fleet node can consolidate on postgres-only"), which is the pg-pure node whose feature graph was parked — the same invalid shape OQ-09/OQ-10 were rejected for, with the deciding fact created by the tree's own progress and nobody re-auditing the row. Resolved by ADR-013 §4: engine features pull driver clusters independently (the ADR-010 §1 discipline extended to sqlite — feature sqlite, default-on, carrying rusqlite; kv/large tier features retired; local ungated), and a pg-pure build is a supported configuration this crate does not default to. No deferral remains.

OQ-09 was deferred(scope) on the first embedded ops deployment — a deciding fact that could only exist once the ops module ships, i.e. a wait that never collapses. It resolved to closed-by-default (see its entry above); its tracker task is deleted.

OQ-10 was briefly recorded as an externally-owned "standing offer" on a deployment trigger — the same invalid shape, caught at review: the trigger was a fact only this crate could create. It resolved to ADR-007 (two kv engines; see its entry above).

The pg-lo large-engine question (raised in the ADR-008 review round, 2026-10-03) never became a parked question: REQ-2 made the multi-instance-with-large-blobs topology a standing requirement (requirements.md — a planning fact predating all POCs), so there was nothing to defer on. It resolved to ADR-008 naming pg-lo as the candidate large-tier engine + POC #7 (docs/research/poc-pglo-spec.md) as its admission evidence — sequenced work, per the deferral-policy header's third category. That work completed the same day: POC #7 passed (docs/research/poc-pglo-findings.md, gate verdict passed with named deltas) and ADR-009 shipped the engine. An earlier draft of that OQ parked on "alkgit's architecture process names the topology" — rendered moot by the REQ-2 fact before it was even written; recorded here because the audit trail of why not parked is part of this document's job, and because it is the worked example of the header's third category (decided → sequenced → completed).

OQ-07/OQ-08 are owned by other repos' processes and are not alkblobs tracker tasks (their outcome arrives through their owners, not through any artifact this repo creates).