docs: propose ADR 0046 d2b 3.0 Provider control plane#334
Merged
Conversation
Freeze the shared Zone, resource, Host/Guest, Provider, reconciliation, process, session, and bootstrap contracts before parallel specification authoring. This keeps the pre-ADR45 v3 tree as the factual baseline while allowing exact, independently reviewed reuse from main.
Record the reviewed Host/Guest model, bootstrap authority, sensitive credential channel, minimal resource and Provider catalogs, Nix cleanup/artifact rules, and fixed performance/security bounds before integrating parallel specs.
Specify Zone-local control resources, direct Nix ResourceSpec authoring and artifact resolution, configuration cleanup, and the complete CLI contract on top of the ADR 0046 foundation.
Keep bootstrap resources runtime-owned, resolve Process templates through semantic owners without package references, and avoid treating current VM listings as Host resources.
Define fine-grained Volume layout, views, ACL repair, attachments, and quotas alongside external Device discovery, arbitration, claims, Provider packaging, and cleanup contracts.
Specify the bounded core emitter, optional OTEL Provider, authoritative audit and support surfaces, and the exhaustive pre-ADR45-to-v3 code and artifact disposition map.
Define Credential binding, lifecycle, Provider placement, redaction, audit, and end-to-end Noise KK token and signature delivery without exposing sensitive output to intermediary Zones.
Specify Provider-owned Volume state, schema migration, sealing, snapshots, relocation, lifecycle cleanup, and configuration publication without exposing paths or seizing controller/API resources.
Specify ZoneLink hierarchy, per-hop authorization, transport Provider binding, relay constraints, watch and call forwarding, and configuration-driven cleanup on the fixed core controller.
Specify Host, Guest, Process, EphemeralProcess, and User schemas, async launch and reconciliation, pidfd supervision, sandboxing, no-isolation posture, Nix authoring, and exact migration work.
Specify Network fabric, dynamic bridge and firewall reconciliation, net-VM system artifacts, runtime config delivery through fine-grained Volumes, guest agents, and child-first cleanup.
Align CLI, Nix, telemetry, and migration specs on core-managed ownership, fixed core-controller publication, event-only Deleted revisions, post-commit audit recovery, and count-based retention without forced finalizers.
Define the fixed Host/User bootstrap Provider and the ADR 0021-preserving virtiofs attachment Provider, including exact package layouts, lifecycle, security, and delivery work.
Test failure of the runtime-owned bootstrap resource rather than expecting a forbidden Nix declaration.
Specify Wayland session and policy resources, canonical Process and Volume composition, authenticated FD handoff, GPU dependency, decoration metadata, filtering, and fail-closed compositor mediation.
Specify same-user Host and Guest placement, injected D-Bus FD access, lease reconciliation, end-to-end Noise KK delivery, redaction, and complete package/test boundaries.
Specify gateway-Guest-only cloud control, co-located Credential delivery, canonical Process and Provider-state Volume composition, async effects, relay routing, and redacted lifecycle evidence.
Reconcile the ADR 0046 foundation specs and dossiers so the Provider control-plane contract is internally consistent and normative: - Canonical Provider ResourceSpec is exactly artifactId/config; manifest, package, component, resource, status, and generated properties are resolved from the signed manifest/catalog, never authored fields. - ProviderStateSet is the logical, query-time grouping of ordinary Volume resources owned by a Provider, never a ResourceType or stored row. Every Provider component, including stateless ones, gets its own private framework-created Volume (empty stateSchema when stateless), using the canonical Volume schema and User/<name> layout principals from a bounded, Nix-preprovisioned pool; components mount only their own view, with no cross-component sharing. Core ProviderDeployment creates these Volumes from signed state declarations before launching the corresponding component Process. Resource rows and the core operation ledger remain sole authority for refs/generation/backoff. - A closed, non-resource bootstrap state-realization exception documents the narrow, per-execution-target break in that ordering needed to bootstrap Volume creation itself: each Host/Guest/user-domain local- storage owner running its own volume-local controller instance has its own local bootstrap mechanism, provisioning only that instance's empty state Volume and, where present on that same target, system-core's/ system-minijail's, which volume-local then adopts/reconciles as ordinary Volumes on its own startup. The mechanism never crosses an execution-target boundary or leaks a parent-Host dirfd, so a Guest can bootstrap its own primitive controllers independently; no other Provider/component receives this exception, and it is not a third Process-bootstrap Provider. - No Provider process (including primitive Process/Volume/Network/Device Providers) imports/calls the broker or performs privileged mutation directly; Providers call injected async EffectPort traits and Core/ProviderSupervisor privately maps effects to broker/allocator/ systemd/user/guest/kernel operations. - Core ProviderDeployment creates static controller/service Processes and their per-component state Volumes; controllers never bootstrap their own Process; worker authority is narrowed to inherited LaunchTicket resources. - Process common fields are frozen to their exact names (providerRef, executionRef, domain, userRef, processClass, template, configRef, credentialRefs, mounts, sandbox, budget, networkUsage, deviceUsage, endpoints, telemetry); successfulTtl/failedTtl defaults preserved. - UserNamespaceSpec drops numeric hostUid/hostGid for a frozen semantic mappingClass (process-principal-root); Core resolves and writes uid_map/gid_map only in private LaunchTicket/effect-adapter state. - Provider-specific ResourceTypes use the frozen vendor-qualification grammar <provider-name>.d2b.io.<Type>; standard types stay unqualified. - Transport Providers are carriage-only; the core ZoneLink handler alone owns ZoneLink/Noise/session/reconnect/route/idempotency/intent state. - Volume keeps fine-grained layout/ACL/view/attachment/quota semantics but drops raw host paths from the public spec in favor of an opaque sourcePolicyId resolved only inside private Nix/bundle/effect authority; volume-local remains sole Volume-type owner and volume-virtiofs stays attachment-only. - Provider status is core-derived from component/dependency/process health, never self-declared by the Provider. - Finalizer/deletion ordering never force-clears an undrained finalizer; audit appends only after the committed Deleted revision, using dedup/exactly-once recovery. - Async reconciliation keeps p95 launch-attempt targets and forbids polling/debounce sleeps. Records the underlying decisions as D075-D086 in the decision register. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Keep metric dimensions bounded to closed semantic domains. Carry Zone and resource identity in the permitted OTEL resource and audit surfaces instead.
Define generation-fenced persistent tap deletion and bind USBIP firewall teardown to the existing closed action request.
Keep coarse Endpoint scope closed while moving subject, component, and operation restrictions into consumerPolicy. Bind controller admission and planned drift coverage to that contract so provider examples cannot introduce aliases.
Keep Credential identity confined to authorized bounded audit records, align service admission with canonical resource verbs and Role subresources, and narrow the Entra login Endpoint example.
Map Credential service admission one-for-one to allowed operation classes and require exact supplemental lifecycle subresources for administrative CRUD.
vicondoa
force-pushed
the
adr0046-provider-resource-control-plane
branch
from
July 24, 2026 23:56
c2cbdc7 to
6078a87
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Dependency: none
Base: v3/main @ 9cc7db2
Head: 6078a87
Tree: ed7ae3508a7315c73e8dc11c16ddec7977a5162e
candidate_id: pending canonical post-rebase snapshot
content_id: pending canonical post-rebase snapshot
Checks: