docs(architecture): dissolve OQ-09's self-referential deferral

- OQ-09 resolved closed-by-default (deny-unlisted), decided on risk
  asymmetry in hand, not on a first deployment the crate itself must
  create; named reopen condition instead of a parked wait
- delete oq-09-ops-visibility-tracker.md (watch-task for an event the
  crate itself gates — never collapses)
- fix doc-lifecycle circularity: externally-owned OQs no longer block
  a spec's `reviewed` promotion
- gc-and-namespaces: "until a consumer names a requirement" reframed
  as re-entry via a new ADR, not a parked question
- README: state the corollary explicitly — facts this crate must
  create (its own first deployment/consumer) are never deciding inputs

Verified: full-text sweep for stale OQ-09 deferral/tracker references
comes up clean across docs/ and tasks/.
This commit is contained in:
glm-5.3-flash committed 2026-10-02 06:14:09 +00:00
1 parent 4b5009d85a
commit b18521a0e6
6 files changed
+75 -103

No files matched your search

+23 -18
View File
@@ -1,6 +1,6 @@
---
status: draft
last_updated: 2026-10-01
last_updated: 2026-10-02
---
# alkblobs — Architecture
@@ -54,25 +54,30 @@ there — not inherited as hedges:
## Open Questions
Tracked in [open-questions.md](open-questions.md). The Phase 0 register
(OQ-BL-01..06) is promoted there with its resolutions; three questions
(OQ-BL-01..06) is promoted there with its resolutions; two questions
remain parked — OQ-07/OQ-08 externally-owned (alkgit seam mapping,
alkfs intake; carried for visibility, gating nothing here) and OQ-09
(ops namespace-visibility default, `deferred(scope)` until the first
embedded ops deployment). **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. Two parking kinds remain legitimate: `deferred(scope)` on a
deciding fact that exists independently of this crate, and
externally-owned questions (how a consumer maps onto this crate) that
gate no decision here — full definitions in the header of
[open-questions.md](open-questions.md).
alkfs intake; carried for visibility, gating nothing here). OQ-09
(namespace-visibility default) resolved closed-by-default. **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. Two parking kinds remain legitimate:
`deferred(scope)` on a deciding fact that exists independently of this
crate, and externally-owned questions (how a consumer maps onto this
crate) that gate no decision here — full definitions in the header of
[open-questions.md](open-questions.md). A corollary worth restating,
because it recurs: a fact this crate must create (its own first
deployment, its own first consumer) is never a deciding input —
decisions stand on evidence in hand, and future needs reopen via named
requirements, not via waiting.
## Lifecycle
Spec docs: `draft` → `reviewed` → `stable` → `deprecated`. A doc moves
`reviewed` when every open question it references resolves and an
architecture review pass clears it; `stable` when implementation
verifies against it; `deprecated` when superseded (kept for reference).
ADRs use a separate status set (Accepted | Proposed | Deprecated |
Superseded), defined per ADR file. This tree is in `draft` pending the
first architecture review cycle.
`reviewed` when every *crate-owned* open question it references
resolves and an architecture review pass clears it — externally-owned
OQs (OQ-07/OQ-08) gate nothing here by definition and do not block the
lifecycle; their outcomes arrive through their owners' processes.
`stable` when implementation verifies against it; `deprecated` when
superseded (kept for reference). ADRs use a separate status set
(Accepted | Proposed | Deprecated | Superseded), defined per ADR file.
This tree is in `draft` pending the first architecture review cycle.
+6 -3
View File
@@ -1,6 +1,6 @@
---
status: draft
last_updated: 2026-10-01
last_updated: 2026-10-02
---
# Pooling, namespaces, and GC
@@ -121,8 +121,11 @@ existence flips atomically per key).
None owned by this document. The p2p replicator's cross-node GC
coordination is a property of the replicator policy layer (above the
crate), governed by the same seam — it does not open a question here
until a consumer names a requirement (OQ-07/OQ-08 intake).
crate), governed by the same seam — it raises a question here only
when a consumer *names a requirement* (OQ-07/OQ-08 intake), which is
re-entry via a new decision at a new ADR, not a parked question: no
decision here waits on a consumer, and a future requirement does not
create one retroactively.
## References
+33 -32
View File
@@ -1,6 +1,6 @@
---
status: draft
last_updated: 2026-10-01
last_updated: 2026-10-02
---
# Open Questions
@@ -32,8 +32,8 @@ rule: every residual either resolved into an ADR (the evidence was
already in hand) or re-owned as below.
**Index of active OQs:** OQ-07, OQ-08 (externally-owned, carried for
visibility), OQ-09 (deferred(scope)). Promoted Phase 0 questions
OQ-BL-01..06 are recorded here with their resolutions for
visibility). OQ-09 is resolved (recorded below). Promoted Phase 0
questions OQ-BL-01..06 are recorded here with their resolutions for
traceability.
---
@@ -77,33 +77,31 @@ traceability.
liveness seams (ADR-003/004/005) without baking an alkfs shape in.
- **Cross-references**: OQ-07, ADR-004
---
## Theme: ops surface
### OQ-09: Default visibility of namespaces in network ops
- **Origin**: [ops-surface.md](ops-surface.md)
- **Status**: deferred(scope)
- **Priority**: low (a policy default, one line to set; needs a real
deployment's posture to set it against)
- **Owner**: this crate — decided with the first embedded `ops`
deployment
- **Question**: are namespaces closed-by-default (an embedder must
grant read/write per namespace) or open-by-default (public read,
write gated)? The `AccessControl` machinery supports either posture;
the default shapes embedder onboarding and accidental-exposure risk.
- **Impacts**: one line in the ops module's ACL defaults at
implementation; ships after the decision, so it gates no
architecture output.
- **Resolution**: not yet decidable — the wrong default is a real risk
(an open-by-default store accidentally exposing content), and the
first *embedded deployment* of the ops surface is the deciding fact
(a deployment that can only exist once the ops module ships —
permitted under the rule above only because the decision gates
nothing before shipping; the module ships closed-by-default as the
documented interim posture).
- **Blocked on**: first embedded ops deployment (tracked in
`tasks/architecture/oq-09-ops-visibility-tracker.md`, the external-
trigger task per the SDD deferred-OQ convention).
- **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](ops-surface.md)
---
@@ -120,7 +118,8 @@ traceability.
Full rationale: [ADR-001](decisions/001-substrate-posture-and-ops-placement.md)
(family-pattern conformance record; placement; no-store-layer-wire
invariant).
- **Cross-references**: ADR-001; OQ-09 (the one residual policy line)
- **Cross-references**: ADR-001; OQ-09 (its one former residual policy
line, now resolved closed-by-default)
### OQ-BL-02: Multi-backend dispatch
@@ -185,12 +184,14 @@ traceability.
| OQ | Status | Deciding fact / owner |
|---|---|---|
| OQ-09 | deferred(scope) | first embedded ops deployment; tracker task `tasks/architecture/oq-09-ops-visibility-tracker.md` |
| OQ-07 | externally-owned | alkgit's architecture process (answerable on paper anytime; gates nothing here) |
| OQ-08 | externally-owned | alkfs Phase 0 intake |
Per the SDD deferred-OQ convention, OQ-09 carries a tracker task under
`tasks/architecture/` (`[external-trigger, deferred-oq]`); 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).
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-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).
+9 -6
View File
@@ -1,6 +1,6 @@
---
status: draft
last_updated: 2026-10-01
last_updated: 2026-10-02
---
# Ops surface (alkcall-backed network operations)
@@ -127,8 +127,9 @@ at op entry — this module never re-implements an authorization check
`resource_id_path` selecting the payload's `namespace` field;
actions map onto read/put/manage:
- `blobs/fetch`, `blobs/stat`, `blobs/have` — the **read** action;
unlisted namespaces (no ACL entries) deny by default (closed
posture until OQ-09 decides a different default)
unlisted namespaces (no ACL entries) deny by default
(OQ-09's resolution; a grant per namespace is the deferred cost,
deliberately paid over accidental exposure)
- `blobs/put` — the **write** action
- `blobs/delete` — not namespace-gated at all; internal authority
context only (alkcall ADR-017: internal switches context, never
@@ -152,9 +153,11 @@ true).
## Open Questions
- **OQ-09**: default visibility of namespaces in network ops
(open-by-default vs closed-by-default) — deferred(scope), decided at
the first embedded ops deployment; ships closed-by-default meanwhile.
None owned by this document. OQ-09 (default namespace visibility)
resolved closed-by-default — recorded in
[open-questions.md](open-questions.md) with its reopen condition (a
named requirement for open-read-by-default, never mere existence of a
deployment).
## References
+4 -4
View File
@@ -1,6 +1,6 @@
---
status: draft
last_updated: 2026-10-01
last_updated: 2026-10-02
---
# Overview
@@ -114,9 +114,9 @@ crate level:
- **OQ-07**: how alkgit's object-storage seam consumes alkblobs
(externally-owned: alkgit's architecture process)
- **OQ-08**: alkfs requirement intake (externally-owned: alkfs Phase 0)
- **OQ-09**: default namespace visibility in network ops
(deferred(scope) — decided at the first embedded `ops` deployment;
ships closed-by-default meanwhile)
- **OQ-09**: default namespace visibility in network ops —
resolved closed-by-default (deny-unlisted; reopen only on a named
open-read requirement)
## References