diff --git a/docs/architecture/README.md b/docs/architecture/README.md index f92535e..9b61aa6 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -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. \ No newline at end of file +`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. \ No newline at end of file diff --git a/docs/architecture/gc-and-namespaces.md b/docs/architecture/gc-and-namespaces.md index 9d3668f..5a589bb 100644 --- a/docs/architecture/gc-and-namespaces.md +++ b/docs/architecture/gc-and-namespaces.md @@ -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 diff --git a/docs/architecture/open-questions.md b/docs/architecture/open-questions.md index 3ab3e80..7f9b185 100644 --- a/docs/architecture/open-questions.md +++ b/docs/architecture/open-questions.md @@ -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). \ No newline at end of file +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). \ No newline at end of file diff --git a/docs/architecture/ops-surface.md b/docs/architecture/ops-surface.md index 4874394..2641829 100644 --- a/docs/architecture/ops-surface.md +++ b/docs/architecture/ops-surface.md @@ -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 diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index d44366a..77f9c1c 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -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 diff --git a/tasks/architecture/oq-09-ops-visibility-tracker.md b/tasks/architecture/oq-09-ops-visibility-tracker.md deleted file mode 100644 index 7cf0358..0000000 --- a/tasks/architecture/oq-09-ops-visibility-tracker.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -id: oq-09-ops-visibility-tracker -name: "[external-trigger] first embedded ops deployment (OQ-09 unblock)" -status: pending -depends_on: [] -scope: single -risk: trivial -impact: component -level: research -tags: [external-trigger, deferred-oq] ---- - -## Description - -Tracker task (not actionable work): watches for the arrival of the -first embedded deployment of the `ops` surface. Its arrival unblocks -[OQ-09](../../docs/architecture/open-questions.md) (default namespace -visibility in network ops), at which point OQ-09 transitions -`deferred(scope)` → `open` and the deciding work is scheduled. - -## Acceptance Criteria - -- [ ] N/A — this task completes only when the external condition - arrives (first embedded ops deployment exists); it carries no - work itself. - -## References - -- docs/architecture/open-questions.md (OQ-09 — the `Blocked on` field - references this task id) -- docs/architecture/ops-surface.md - -## Notes - -> Per SDD deferred-OQ convention: `risk: trivial`, `level: research`, -> no implementation content. - -## Summary - -> Awaiting the external condition. \ No newline at end of file