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:
1 parent
4b5009d85a
commit
b18521a0e6
6 files changed
+75
-103
No files matched your search
+23
-18
@@ -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.
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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).
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in new issue
Block a user