88 lines
14 KiB
Markdown
88 lines
14 KiB
Markdown
# Operator enrollment: metadata/effect contract proposal
|
||
|
||
Status: **UNIMPLEMENTED / UNACCEPTED**. This is a proposed contract revision, not an equivalent optimization of the current contract. It does not close S3-06 or authorize a stand stop, remote upload, production activation, or replay. The existing strong source/coordinator APIs remain unchanged. An independent equivalent `inspect`/`authorize` collapse is useful, but does not implement this proposal.
|
||
|
||
Implementation note: separate public-file prerequisites are implemented in the core/node source and [unit-accepted with 17 tests](mcp-operator-public-metadata-progress-20261028.json). They authenticate signed public data only; they do not implement the same-lease metadata session, observation metadata proof or effect dispatcher below. The [concrete effect ledger](bandwidth-operator-effect-ledger.md) supersedes the optimistic eight-scan arithmetic as a feasibility claim: independent boundaries need at least 14/12 scans, while a separately proven fixed continuation could potentially share adjacent boundaries to reach 9/8. Neither candidate has been accepted. The original five-second deadline remains fixed.
|
||
|
||
Next implemented prerequisite: a [fixed public registry metadata lease](bandwidth-public-registry-metadata.md) has passed 19 new unit tests and [7 actual owned PostgreSQL groups](mcp-public-registry-metadata-acceptance-20261028.json). It exposes only `inspect`/`close`, reuses the existing pool, validates current role/catalog/source and holds the exact PID/session lock without secret reads. It does not expose registry snapshot queries or effect dispatch, and is not wired into the operator window. The observation metadata and complete private effect composition below remain unimplemented.
|
||
|
||
Further implemented subset: [managed observation/coordinator metadata](bandwidth-peer-metadata.md), 29 new tests and [4 actual PG/localhost groups](mcp-operator-peer-metadata-managed-acceptance-20261028.json). The checker uses the existing application pool and compares the original private credential as a bound predicate, returning only boolean. The application currently stores server passwords as text; a nonexistent ciphertext field must not be assumed. The new PUBLIC wrappers cannot authorize an effect. External current-source metadata and the complete effect continuation remain open; OP-M3 is not closed by managed-only acceptance.
|
||
|
||
29 October update: [guarded managed and encrypted external sources](bandwidth-operator-peer-sources.md) now complete OP-M3 as a component (57 focused tests, 9 owned SQL/HTTP groups, 24 legacy SQL groups). The genuine guard binds current original authority and live physical-owner revocation; metadata still has no key/Q/native/write permission. The new external source proves the current randomized ciphertext profile and directory without decrypting it. Prior paragraphs describe earlier partial snapshots. The complete fixed effect dispatcher and measured-latency/real-window acceptance remain unimplemented/unaccepted; the five-second limit and remaining stand grant are unchanged.
|
||
|
||
## Evidence and feasibility bound
|
||
|
||
The read-only fixture `tmp/mcp-docker-latency-readonly-20261028.json` records 36 Docker GETs, zero service changes and four pinned containers still running. Three measured rounds took 563.080, 403.823 and 416.961 ms. Mean endpoint costs were `/info` 25.323 ms, full `/containers/json?all=1&size=0` inventory 197.916 ms and individual inspect 1.827 ms. The estimated complete five-container, 14-GET scan is **464.748 ms**. This estimate includes the unrelated owned PostgreSQL container in the complete inventory; it is not evidence from a stopped operator window.
|
||
|
||
The local genuine-SQL/mock-Docker profile took 4703 ms while making 4312 Docker GETs (308 complete 14-GET scans), 83 credential-source reads and one native license GET. The external fixture made Docker artificially cheap. At the stand estimate, 308 scans alone cost about 143.1 seconds. Passing that local profile cannot establish the unchanged five-second window on the stand.
|
||
|
||
The static design target is **at most eight complete scans per enrollment**, including acquisition and final confirmation: 8 × 464.748 = 3717.984 ms, leaving about 1282 ms for SQL, files, HTTP and processing. This is a target, not a latency guarantee: the observed slow round and variance require an actual bounded latency fixture. No TTL increase is proposed. Nine or more mandatory scans fail the static review target before any backend window is spent.
|
||
|
||
## Why the current graph multiplies work
|
||
|
||
The registry guard separately inspects the observation and authorizes the original operator. Both adapters call `coordinator.inspect`. That method calls `reader.inspect`, which calls the full credential-bearing `source.read`; composition performs another `windows.verify` immediately before it. The bridge checks around every query and keyed proof, the writer window checks around borrowed I/O, and configured source dispatch fences check original authority again. Each full window check runs the complete Docker scan. These are nested semantic checks, not independent HTTP effects.
|
||
|
||
A single raw PostgreSQL ownership/catalog query cannot prove external quiescence. The same backend PID and exclusive registry lock can remain present while a Docker backend restarts, a sibling executor appears, or an external controller becomes active. No SQL boolean, previous Docker result, signed operator JSON or empty occupancy result may replace current Q.
|
||
|
||
## Proposed separation
|
||
|
||
### Public metadata frame
|
||
|
||
Introduce a separate, server-owned metadata operation. Its concrete API should be an opaque frame, for example `inspectEnrollmentMetadata(prerequisite, scope)`, consumed by a combined registry `inspectAndAuthorize` adapter. Only the genuine existing prerequisite private capability can enter it. A copied/serialized prerequisite, public evidence JSON or caller-supplied validator cannot mint a frame.
|
||
|
||
Each invocation must freshly validate the original signed grant, original wall/monotonic lifetime and signal; exact peer/source directory/generation; public signed bootstrap/source identity; current endpoint enabled state, endpoint epoch and exact credential-ciphertext/version digest; and current registry identity/physical ownership where applicable. A frame returns only immutable evidence and authority metadata, bound to its original capability and current synchronous consumption. It grants no right to retrieve credentials, open a native client, read a secret key, calculate an HMAC or mutate SQL. It must not expose an endpoint/password projection.
|
||
|
||
**A public frame cannot claim `keyCurrent`, `credentialsVerified`, `nativeVerified` or current external Q.** In particular, public signed key hashes do not prove that a current secret file has been read. The frame is not reusable after another await, SQL dispatch or frame exit; it is not a cached source result or a renewable authority token.
|
||
|
||
The new metadata source mode must be genuinely secret-free. Calling today's `material()`/`fresh()` paths under a weaker Q guard is forbidden: those paths read secret event/node keys even for some metadata SQL. A distinct fixed metadata implementation must read only public material and execute fixed metadata projections. Existing strong `open`, `binding`, `keyedProof`, observation and dispatch APIs retain their current behavior and secret-read ordering. Any new effect API requires separate review and tests.
|
||
|
||
Metadata SQL may combine already authorized facts in one fixed statement on the existing physical lease. It must retain all old pure validators and exact owner/PID/catalog/source checks. Application facts may join that statement only when the existing role already has the necessary SELECT permissions. Otherwise use the existing application source separately. No new role privilege, nested control checkout, dynamic SQL, caller SQL, caller rows or callback asserting authority is allowed.
|
||
|
||
### Effect frame
|
||
|
||
Only a private server-owned effect dispatcher chooses effect kinds; the caller cannot pass a `metadataOnly`, `afterDispatch` or `qVerified` boolean. It binds the exact original capability, expected metadata, physical owner, input and original lifetime. Each effect frame obtains a **new complete Q scan**, validates actual current authority/source/endpoint/ownership, performs its fixed effect, and preserves the existing checks around asynchronous boundaries. A failed/late Q must occur before the effect's dispatch.
|
||
|
||
Full Q is mandatory before:
|
||
|
||
- Every actual management-credential projection.
|
||
- Every native license HTTP dispatch.
|
||
- Every secret-key read and HMAC-producing operation. Adjacent pure synchronous MAC calculations may share one freshly checked key only within a reviewed fixed batch; no key/result retained across an await or subsequent frame.
|
||
- Every SQL mutation, including any newly introduced state-changing statement.
|
||
- COMMIT, followed by a fresh complete Q after its actual ACK.
|
||
- Final owner confirmation before publishing the receipt and retiring the physical lease.
|
||
|
||
Acquisition also performs its full existing inventory scan. If post-ACK confirmation and final confirmation are combined, that requires one private terminal frame with no intervening await/effect; it cannot be inferred from two equal public objects. This proposal budgets them separately until that proof exists.
|
||
|
||
Q/current-source races must remain bounded by the same before/after discipline as today. This contract does not claim that several sequential Docker GETs are an atomic daemon snapshot or prevent a privileged outside actor from racing the scan. The signed complete-inventory/no-outside-controller assertion remains a prerequisite with its existing scope limitations.
|
||
|
||
## Static budget and required batching
|
||
|
||
Let C be credential projection frames, N native dispatch frames, K independently guarded secret-read/HMAC batches and W state-changing SQL statements before COMMIT. With acquisition, COMMIT, post-ACK and final confirmation counted separately:
|
||
|
||
`complete scans >= 4 + C + N + K + W`.
|
||
|
||
The optimistic eight-scan shape therefore needs C=N=K=W=1. **The current implementation has not established this shape.** Initial source opening, later node/event-key reads, before/after key checks, independent MAC calls or multiple SQL writes can make K or W larger. Each required scan must be counted; no phase may hide additional key reads, “verification” scans or mutations outside the budget. Required post-effect Q adds to the formula unless legitimately identical to another reviewed boundary.
|
||
|
||
The metadata split alone is insufficient. A candidate must additionally show a fixed registry write batch (one atomic statement for the enrollment node/alias/event writes, preserving exact command/row acknowledgments and all MAC domains) and a fixed key/MAC batch, with no secret reads moved across the existing public-read or asynchronous verifier boundaries. If those constraints cannot produce at most eight scans, this revision does not fit the window. The alternative is a genuinely continuously enforced external stop/restart prohibition with a cheap current proof, separately designed and accepted; a previously observed Docker scan is not that capability.
|
||
|
||
Before using the stand, produce a machine-counted effect ledger for both managed and external enrollment, existing/new canonical node paths, failure cleanup and post-COMMIT paths. The ledger must count actual scans, credential projections, secret reads, HMAC batches, native dispatches, SQL mutations and COMMITs. A fixed latency fixture must add the measured endpoint timings to each actual Docker GET and enforce the original five-second monotonic deadline. Mock-Docker zero-latency timing is inadequate. No new production pool/process or privilege is permitted; the whole-installation <=2 GB constraint remains.
|
||
|
||
## Required counterexamples and outcome rules
|
||
|
||
| Change/race | Required refusal or outcome |
|
||
| --- | --- |
|
||
| Q scan finishes after deadline or cancellation | No subsequent credential/key/native/SQL effect; late results do not publish authority or renew the original lifetime. |
|
||
| Backend starts, restart policy changes, or an executor/controller appears after metadata | Next effect's fresh full Q refuses before its dispatch; unchanged PG locks do not rescue it. |
|
||
| Secret key rotates after public metadata | Fresh full material validation before key use refuses the old pin; metadata never claims a current key. Same-byte source-directory cloning does not change the pinned source. |
|
||
| Grant revoked/changed during metadata or effect preparation | Final current original-authority check refuses before the effect; copied grant fields cannot renew original expiry. |
|
||
| Endpoint/credential ciphertext/epoch changes between metadata and projection | Exact original metadata predicate in the credential command projects zero payload; no GET and no fallback endpoint. |
|
||
| Physical PID/registry ownership is lost after metadata | Raw same-lease ownership fence refuses before effect dispatch and destroys the lease; no healthy pool return. |
|
||
| Mutation ACK is lost or malformed | No fabricated success, no second mutation/native attempt, no automatic replay; reconcile the original uncertain operation. |
|
||
| COMMIT is sent but ACK is lost | UNKNOWN, even if a later read appears committed; no automatic replay with a new alias/node. |
|
||
| COMMIT ACK is genuine, then Q/grant/source/final ownership fails | UNKNOWN, preserving durable state for reconciliation; do not roll back the acknowledged fact or publish readiness. |
|
||
| Frame/capability copied, retained across await or used with another peer/window | Refuse without credentials or effect dispatch. |
|
||
|
||
Acceptance needs actual owned SQL and localhost HTTP effects with forwarding observers, plus the latency fixture, before any separately authorized stand attempt. Neither the metadata proposal nor the independent equivalent guard collapse is evidence of deployed external enforcement or completion of the operator stage.
|
||
|
||
29 October key-effect prerequisite: the [fixed local key/MAC primitive](bandwidth-node-key-effect.md) has passed local unit tests and regression checks. It reads exactly 32 bytes and computes the fixed proof batch without await, pins actor/owner signals and wall/monotonic expiry, and wipes scratch keys before close. It is not connected to a dispatcher, does not prove current public source/Q/authority, and does not change the old strong API guard ordering or scan count. Synchronous OS latency is not bounded by cancellation. This resolves only the implementation of a candidate primitive; the closed effect adjacency, same-owner pipeline, latency and stand acceptance above remain open.
|