Skip to content

docs: propose provider-neutral fulfillment protocol - #64

Draft
scotwells wants to merge 6 commits into
mainfrom
design/provider-fulfillment-protocol
Draft

scotwells wants to merge 6 commits into
mainfrom
design/provider-fulfillment-protocol

Conversation

@scotwells

@scotwells scotwells commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Provider-neutral fulfillment: proposed documentation only. Select authenticated durable Reserve/Commit/Cancel, exact provider supply, all-channel exclusion, signed queryable receipts, global M1 decision, operation authority, unknown-effect recovery and separate R3 finalization. External supply requires independently qualified owner contracts.

Make PhysicalMaintenance participate in global exclusion while preserving this external wire protocol’s real Allocation/M1/R2 binding. Fleet field custody uses the selected-cell path; no fabricated supplier reservation, quota or R3. Supplier-controlled dependent devices/connections still require their owners’ authority and fences. No new external maintenance API or executor.

Remaining P2 response and preserved boundaries

Responds to the exact fresh complete-set review. The earlier commissioning/adopted-settlement findings remain resolved in the proposed contracts; this revision does not replace them with maintenance.

  • physical-maintenance-v1 adds one explicit subject to the existing shared custody/slot/journal/release protocol, not a second allocator or executor.
  • Passive Device work has exact asset/resource/custody identity, current action/input authority, protected finite work inputs and one-use technician permits; no MachineCapacity, Machine, quota hold, Installation or bootstrap is invented.
  • Active dependent devices and connections retain their own custody and writers. Their separately authorized, effective prerequisite fences precede field admission; target clearance cannot reset, disconnect, wipe or reconnect them.
  • Unknown work, delivery, cessation, identity, accounting or physical clearance retains custody and conservative old/new interests. Restoration reconciles independent owner/field history and excludes old crews before any recovery authority.
  • L5, R2, physical reservation disposition and fresh inventory eligibility remain separate. Observational adoption causes no effects. Catalog withdrawal blocks acquisition but does not revoke retained runtime capabilities; current action/input rights and separate suspension remain mandatory.

No runtime implementation, core #41/#51/#58/#59 change, managed-service scope, compatibility machinery, new PR, merge, watch or self-signoff. This existing branch remains based on origin/main at 8ebec19513a0cbc8f219d3acae46f89ab471510b; companion branch diffs are not imported.

Exact final complete-set manifest

PR Exact final head
#41 f04e63ddd9d10cbf306daf3a0232961debd85e7f
#51 fa07c2236801a33a58efc914b555586c8e146cc6
#58 a922ff1eb3275e26af6ae750a7515ddde245a754
#59 d7ff793b03711203dbfc9fac87d43922cc649b6f
#60 80c72446a574202c9dac5f6d3c26ce4a0af875ba
#61 8101f645cc8167f71a07147e6ea1a9cdf69a57cf
#62 496ec4530aa3bacdb4858d0b22192be1a92b0c48
#63 ce4a30a36ee476073281b40b8353ac5eb2c99e0c
#64 4495e20f4c3ee7697dfd97a5a95823ca5fa7b448
#65 94824bf7ef614fcdecf3ce813c289e259367e90c
#66 ffe6ed28e261578bbc3d0226585b5e80f5d5985c

This PR's final head is 4495e20f4c3ee7697dfd97a5a95823ca5fa7b448. Core heads are unchanged. #60–#65 pin immutable contract-bearing snapshots; #66 pins their final source heads. Post-contract commits refresh only pins/review provenance, avoiding circular final-head dependencies. Older embedded pins in snapshots are drafting history, not authority to substitute an older contract for this aligned set.

PR Immutable contract-bearing snapshot
#60 4bf770db8bd2b065748c3b9384d4c72f9b8ec0e1
#61 25fef48790b13da95900de64ffd2d1b36e0510eb
#62 4f9934980b3f441c1d777157fa0ba1dcfce372d7
#63 2b384517fd08c04cf078923ebda2cddcfa1dc424
#64 58a6596d30b3819d0b3799192730626439ef9885
#65 310a55d97394bb296c579bd3ad01177455c15cc4
#66 26601c7121542d7c89ddac84c1f8592f08cb8372

Documentation validation

  • Combined all eleven revisions with temporary git merge-tree/commit objects only: conflict-free; no branch or PR merge and no shell worktree. Combined tree c5c26cf30c2ee1f974404576220c106ad32961f2, local validation commit 036e40a0573be61b506fff7e8604bac4377117a0.
  • Repository link checker plus fence-aware validation: 48 Markdown files, 647 local targets, 355 local anchors, no missing targets/anchors or undefined explicit references. All 21 unique pinned Fleet source paths exist.
  • 15 SVGs parse/render; both DOT sources render; all three PlantUML sources pass check-only; four JSON examples parse. Three changed SVGs visually inspected for clipping/layout.
  • D01–D40, I1–I39 and N1–N23 have unique contiguous definitions. All preexisting D01–D35, I1–I35 and N1–N21 rows remain byte-for-byte unchanged. New scenarios are specifications, not qualification runs.
  • Per-PR changes remain inside each intended enhancement directory; original unrelated branch changes preserved. Original supplied head is an ancestor of each published head. Per-PR and combined whitespace checks pass.
  • External HTTP sources were not comprehensively revalidated. docs: propose standalone Metal network handoff #61's previously unavailable cloud attachment reference remains an explicit owner prerequisite, not an assumed integration.

Remaining prerequisites and review status

Fresh independent complete-set integration review is required for this exact changed manifest; no previous approval or author check signs off these revisions. Implementation still needs the shared ledger hooks and synchronous storage/restore interlocks, independent R/KMS/PKI and physical fences, registered owner gates, protected inputs/evidence, qualified online field permits and site/crew exclusion, active-custody/network owner agreements, accounting applicability proofs, measured profile limits and real qualification/drills. QP does not qualify compute or supplier execution. R-history-loss reactivation remains unsupported until separately implemented and qualified.

No runtime, hardware, provider, Q0/Q1/QP/QD/QE qualification, owner approval or independent signoff is claimed. Ready for the requested fresh independent review, not merge or deployment approval.

@scotwells

Copy link
Copy Markdown
Contributor Author

ARCHITECTURAL SIGN-OFF

Reviewed exact head 50e678ee20645ad0a4e340005b18432fe4633bec. Fetched the actual PR head and refreshed both the remote PR metadata and refs/pull/64/head immediately before this verdict; both still identify that SHA.

Scope: proposed standalone Fleet/Metal architecture only. This is not implementation, real-hardware, vendor, security-platform, operational or production acceptance; it is not a formal GitHub approval. Nodes, clusters, node services and backwards compatibility with illustrative APIs are excluded.

I read the repository guidance, README, architecture context, the full fulfillment proposal, and relevant pinned source contracts. Cross-checked #60 at 2563b2a2f177a72d20c1d62265c89ff15688ba25, #61 at ed6edec5b056fd53343e11d58d979af495f1bd7c, #62 at 7fa823050a443c1f5b85c56e85ed04ebaa5bd2cb, and #63 at 8fe054101ac3bea822e5d16e40cb375a884e7e56; also #41 at f04e63ddd9d10cbf306daf3a0232961debd85e7f, #51 at fa07c2236801a33a58efc914b555586c8e146cc6, #58 at a922ff1eb3275e26af6ae750a7515ddde245a754, and #59/PXE/lifecycle at d7ff793b03711203dbfc9fac87d43922cc649b6f. Cross-checking a dependency does not approve its implementation or independently sign off that entire proposal.

Adversarial findings

No blocking architectural findings at this revision. In docs/enhancements/provider-fulfillment/README.md, the following concrete failure traces have explicit safe dispositions:

  • Effect-free preparation (lines 201–243, 269–277): lose a Reserve reply, retry it, then deliver Commit twice. The same key retains the same asset; Reserve and Commit authorize bookkeeping only, not procurement, power, boot, credentials or networking. R2 must be retained before separately admitting consumer effects. Unknown holds count against finite caps, and a different selection requires terminal provider/quota acknowledgment of the preceding attempt.
  • Commit/abort/deadline race (lines 247–330): M1 passes its admission-time check, its response is lost, and the provider reaches expiry before seeing Commit. The local lock becomes ExpiredUnresolved rather than free. M0 and M1 contend in the same ledger transaction domain; a committed M1 survives late delivery, while M0 permanently excludes M1. The explicit distinction between deadline admission and WAL completion avoids promising an impossible exact wall-clock reclamation boundary.
  • Cancellation and replay (lines 285–309, 377–419, 526–533): deliver Cancel before Reserve or operation Submit, then replay the original request after restart. Durable absent-key tombstones/high-water marks reject resurrection. Digest conflicts cannot change inputs. A lost physical reset response after the send marker remains Unknown; transport idempotency is not asserted to make hardware replay safe. Recovery retains the operation/plan/driver and requires old-effect settlement.
  • Canonical identity and exclusivity (lines 162–195, 254–268): advertise one chassis through two offerings/provider projects. All-channel local locking plus inventory-qualified canonical enrollment and global occupancy prevent independent allocation islands. Serial-number equality or provider signatures alone do not prove physical identity. This agrees with docs: propose inventory lifecycle and trust #63's canonical adjudication and conservative adopted custody; it does not require an external provider to expose Fleet CRDs or permit cross-provider custody transfer.
  • Permission changes and evidence (lines 334–375, 453–504): close a safety/permission gate during admission or renewal, or return signed Ready with stale/missing network/stop evidence. The shared docs: propose allocation admission and quota custody #60/docs: concrete operation execution, fencing, and recovery #62 ordering rejects stale authority; the verifier requires exact identities, revisions, freshness and owner-specific predicates. Provider authenticity is not physical truth. DelegatedContract cannot become QualifiedImage by assertion.
  • Release and disappearance (lines 506–565): clean hardware but lose quota acknowledgment, or commit Released and lose R3 acknowledgment. The first retains occupancy/charge; the second retains the provider lock until exact finalization, so delayed R3 is a capacity delay rather than overlapping ownership. Old cleanup/finalization cannot target a new incarnation. Bankruptcy, forced project deletion, lost journals or missing fences retain independent recovery custody/quarantine rather than manufacture release, readiness or a replacement allocation.

Explicit prerequisites, not hidden guarantees

Lines 738–759 correctly make activation conditional on owner acceptance and qualification of the #60 ledger/decision extension, all-channel provider exclusion, canonical identity and independent witnesses, #62 effect fencing and retained inputs, #61 physical network/disconnect evidence, release/accounting predicates, protected time/keys/restore authority, and emergency access. Those are substantive implementation/production blockers, but the architecture specifies the required semantics and fails closed without them. I do not classify their explicit absence as a missing protocol or assume Milo, commodity BMCs, a provider signature, or a controller lease supplies them today.

Validation was documentary/adversarial, not a hardware execution or implementation test. The PR changes one proposal document; git diff --check passed. No files were edited, and no formal approval, merge or watch was performed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant