Files
MikrotikManager/docs/bandwidth-operator-effect-ledger.md
T
DenozordecandClaude Sonnet 5.5 3c78c55c0d fix(docs): сохранить в Git CRLF-байты квитанций, закреплённых SHA-256
28 файлов закреплены хешами по CRLF-байтам рабочего дерева, а в индексе были LF-блобы.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
2026-11-15 20:53:14 +07:00

98 lines
18 KiB
Markdown

# Operator registry: concrete integration seam and effect ledger
Status: **DESIGN ONLY / UNIMPLEMENTED / UNACCEPTED**. Supplement to [the metadata/effect contract](bandwidth-operator-metadata-effect-contract.md). Counts describe the reviewed source graph, not accepted stand behavior. No backend window is justified by this document. The [public-bootstrap helpers now unit-accepted separately](mcp-operator-public-metadata-progress-20261028.json) are prerequisites, not a replacement for registry/source/ownership verification.
Implemented subset of the next API: [core/node public registry lease](bandwidth-public-registry-metadata.md), with only fixed `inspect` and `close`, has passed 19 new tests and 7 real owned PG groups. It checks the original joint catalog/role/source validators before taking the lock, and current public pins plus exact PID/lock around later checks. The generic `queryMetadata`/registry snapshot, private observation proof and effect dispatcher described below are still absent. Do not replace the existing strong operator `check()` with this public evidence alone.
Next implemented subset: [managed peer/coordinator metadata](bandwidth-peer-metadata.md) passed 29 new tests and 4 owned PG/localhost groups. The genuine retained observation/prerequisite and current signed grant are mandatory. Fixed managed SQL compares the private original endpoint/password inside PG and returns only boolean; no new credential projection, Q or native occurs in metadata. Current `servers.password` is text, not ciphertext; no unkeyed password hash is published. External provider is absent and refuses, so OP-M3 is still open. These PUBLIC wrappers are snapshots, not the private effect-authority continuation required below.
29 October: OP-M3 sources are now [accepted as guarded managed/external components](mcp-guarded-peer-sources-acceptance-20261029.json). The external source is a current encrypted profile with full-header AAD, ciphertext source proof and directory pins; the managed source uses gated fixed SQL. Both require a genuine original-window guard. A reproduced owner-during-Q gap was closed with the actual connector's continuous lifetime revocation propagated through core/node/window. 57 focused tests, 9 real owned PG/HTTP groups and 24 legacy PG groups passed, plus native/storage/build regression. The earlier managed-only paragraph above is historical. **OP-M4 remains open:** no private fixed registry effects or positive measured-latency full registration have been accepted.
## Actual call sites
`bandwidth-operator-writer-composition.ts` constructs one coordinator inside the held writer window. Its observation source wraps every `read` with `windows.verify`. Its registry adapter borrows the same already-open node session. `bandwidth-operator-registry.ts` defines `check()` as a complete `coordinator.inspect(prerequisite, scope)` and invokes it around opening, binding, queries and proofs. The managed/external registry adapters also use that check for their authorization/evidence callbacks. The equivalent combined `inspectAndAuthorize` path being implemented separately removes duplicate evidence/authority reads while preserving the strong predicate.
`coordinator.inspect` itself reads current signed operator files, runs full Q, calls `reader.inspect`, compares original evidence, re-reads the grant, runs full Q and re-reads the grant again. `reader.inspect` calls the credential-bearing source `read` and compares its full snapshot with the observation's private original snapshot. Thus this is the exact strong entrypoint a future metadata implementation must replace internally; merely replacing one window callback leaves the credential projection and secret-key source phases intact.
`windows.check` checks current original authority and external Q. `windows.verify` invokes it without nested session SQL. Window `io` checks around each borrowed operation. Configured-source dispatch separately validates source/catalog and raw physical ownership. `verifyOwnership` uses `fence.query(HELD_SQL)` on the same driver, checking both PID and session-exclusive registry lock. No future metadata frame may remove that check or execute it by recursively calling the source facade.
## Minimal next API, proposed rather than present
1. **Public files only:** core `inspectPublicNodeBootstrap(envelope, scope)` and node `inspectPublicBootstrap(scope)` supply immutable public signed bootstrap/source metadata. They must not read event/issuer secret keys, checkout a pool connection, calculate HMACs, assert SQL identity, or claim native/credential verification. They do not mint the genuine prerequisite capability or a strong source session.
2. **Same-lease public session:** a new separately reviewed configured-source `openMetadataWithOwnershipFence(scope, authorityGuard, ownershipGuard)` would open exactly one physical lease and return only `queryMetadata` and `bindingMetadata`. The core equivalent must run the existing joint identity pure validators on fresh fixed SQL rows using public signed expectations, with the existing before/after file and SQL-sequence discipline. It must read no secret key. Fixed metadata SQL and arguments are captured at construction; the consumer cannot provide SQL, rows, phase flags or callbacks claiming Q. The ownership guard remains raw same-lease SQL, runs before final public files and original authority, and requires the exact captured PID and lock. Old `open`/strong APIs remain unchanged.
3. **Observation metadata validation:** the observation reader needs a private method such as `inspectMetadata(observation, scope, metadataSource)`, accepting only its genuine retained observation. A captured trusted metadata source must freshly compare the exact original peer, enabled state, endpoint epoch, source/key generation/directory and all credential-ciphertext/version commitments without returning credentials. The original full snapshot must remain private. Public bootstrap files alone cannot establish current application endpoint or credential equality. Existing source roles must already permit the projection; otherwise use the existing app source separately, not new control-role privileges.
4. **Coordinator metadata frame:** `coordinator.inspectMetadata(prerequisite, scope)` consumes only the existing private prerequisite and invokes the public-file/session/observation metadata paths. It preserves original signed grant/evidence equality, original wall/monotonic expiry and signal. It produces immutable metadata/evidence/authority, explicitly excluding current-key, credential, native and Q assertions. An internal frame is valid only for one synchronous projection/equality operation, not across another await. No JSON origin or mutable model payload can mint it.
5. **Bridge integration:** replace the bridge's nested strong `check()` only on a newly private metadata path. The combined `inspectAndAuthorize` adapter consumes one such frame for both existing pure comparisons. Registry-owned query intent must be classified by fixed internal operations: public SQL/metadata, secret/HMAC, mutation and COMMIT. Arbitrary SQL string guessing or a public `metadataOnly` flag is insufficient. The old strong adapter remains the fallback. Effect dispatch must re-enter genuine strong authority/Q and exact current source checks before credentials, secret keys, native dispatch, mutation and COMMIT. Final confirmation still follows actual COMMIT ACK; otherwise UNKNOWN.
This is the minimum coherent integration, not a suggestion to ship five isolated helpers. In particular a public file helper cannot make today's `fresh()` safe under a metadata-only guard: `fresh()` executes strong `SELECT 1` and retains a freshly read issuer key for the immediate synchronous HMAC.
## Actual phases and counts for register
Managed and external `register` have the same phase structure; external alias/event use distinct MAC domains and v2 identity. The existing/new distinction below means an existing subject alias versus creating a new alias, including reuse of an already-known canonical node.
| Phase | New managed | Existing managed | New external | Existing external |
| --- | --- | --- | --- | --- |
| Native observation | one license GET | one license GET | one license GET | one license GET |
| Claim HMAC phase | one | one | one | one |
| Locked registry snapshot | one | one | one | one |
| Second HMAC phase | batch node/alias/event, three MACs | batch verification of snapshot MACs | batch node/external-alias/external-event, three MACs | batch verification of snapshot MACs |
| Mutating SQL before COMMIT | one fixed enrollment DO | zero | one fixed enrollment DO | zero |
| COMMIT | one | one | one | one |
The snapshot verification batch size depends on the bounded snapshot proof records; it is not necessarily three. The **two HMAC phases cannot simply become one**: the first claim proof is a bound parameter for the locked snapshot; its result determines whether to verify an existing alias or choose candidate/node/incarnation/event data for the second batch. One key buffer may not be carried across that awaited SQL to avoid a fresh key check.
Registry facade query counts are nine for new alias and eight for existing alias: BEGIN; SET configuration; initial authority SELECT; registry transaction lock; locked snapshot; optional DO; authority SELECT; COMMIT; post-COMMIT authority SELECT. The DO already batches node/alias/event writes; proposing generic write batching alone does not remove further statements on this path. It must still return actual command `DO` and retain all checks inside the fixed batch.
Outside these registry calls, the configured-session path adds at least seven strong facade phases: opening `fresh`, window binding, bridge binding, session lock acquire, PID read, claim-HMAC `fresh`, second-HMAC `fresh`. Total: **at least 16 strong query phases for new alias, 15 for existing alias**, excluding raw identity/ownership queries and application source reads. This count is not the number of scans; nested guards multiply each phase.
On the currently reviewed ordinary core connection, one driver query does core `checked` before/after plus node dispatch before/after. Each node dispatch reads two node file sets; each set verifies core material and reads the issuer key. This gives six event-key reads and four issuer-key reads per query. A joint registry core connection can remove the separate `checked` pairs but still has four event-key and four issuer-key reads. Initial source opening has additional material reads. These are real secret reads even when the visible query is `SELECT 1` or public metadata. Neither public helper alone removes them; a separate secret-free session mode is necessary.
## Eight-scan feasibility with mandatory before/after checks
Even after eliminating all accidental nested guards and all secret reads from public metadata, independent before/after Q at each meaningful effect gives this optimistic lower bound:
| Q boundary | New alias | Existing alias |
| --- | ---: | ---: |
| External acquisition | 1 | 1 |
| Credential projection, before/after | 2 | 2 |
| Native GET, before/after | 2 | 2 |
| Two key/HMAC phases, before/after each | 4 | 4 |
| Enrollment DO, before/after | 2 | 0 |
| COMMIT, before/after actual ACK | 2 | 2 |
| Final owner confirmation | 1 | 1 |
| **Optimistic total** | **14** | **12** |
This ignores extra key reads, separate mutation internals, opening effects and source checks; it is a lower bound under the stated independent-boundary contract. At 464.748 ms/scan, these bounds alone cost about 6506 and 5577 ms. **The eight-scan target cannot hold while retaining all those independent before/after full-Q boundaries.** Existing-alias enrollment also fails the target despite no DO.
An after-A scan can serve as before-B only if a private dispatcher proves exact adjacency with no intervening asynchronous metadata/file/SQL operation or authority handoff. Equal public results do not prove adjacency. Here claim-HMAC and the second MAC phase are separated by a real locked snapshot; native observation, metadata resolution and COMMIT also have intervening awaits. Do not subtract scans on paper without a concrete private dispatcher/sequence proof. A newly fixed larger SQL/key operation would need to demonstrate all original current-key/source checks without holding a key across awaited SQL; no such operation is currently implemented or accepted.
Therefore the next decision is explicit: either revise which metadata/effect boundaries require full Q, with a reviewed proof and tests, or accept that the five-second/full-Q contract is not achievable by these public helpers plus equivalent inspect/authorize collapse. No TTL renewal, stale Q cache, secret-read reordering, caller SQL, role broadening, second production pool/process or automatic replay is an admissible shortcut.
### Concrete overlap candidate, not accepted
The 14/12 bound counts independent checks. A private fixed dispatcher might share a single fresh scan as the post-A and pre-B check only when there is **no await or effect between that scan and B**, all B preparation has already completed, and A's result remains private until its post-check. This is a contract/proof obligation, not an optimization available to existing independent callbacks.
For example, management credential projection and the fixed license GET could be one private effect sequence: Q before projection; actual gated projection; Q both after projection and immediately before native dispatch; GET; Q after GET. That is three scans instead of four. The middle check must really be at `ClientRequest` dispatch; awaited import, address resolution, client preparation or TLS preparation after it prevents treating it as the final native boundary. Preserve the existing transport's final dispatch verifier.
The concrete adjacency candidate is **nine** scans for new alias: (1) acquisition; (2) before credentials; (3) after credentials/before native; (4) after native/before claim-key effect; (5) after claim-key effect; then the locked snapshot awaits, breaking sharing; (6) before second-key effect; (7) after second-key effect/before DO; (8) after DO/before COMMIT; (9) after genuine COMMIT ACK/final confirmation. Existing-alias omits DO and can combine second-key-after/COMMIT-before, giving eight. At the observed mean, nine scans cost 4182.732 ms, leaving only about 817 ms of the original window. This may still fail on the real round variance or public/SQL overhead; it is not accepted latency evidence.
An eight-slot new-alias chain would have to move claim-key's post-check across the awaited snapshot to share it with the second-key pre-check. That violates the stated immediate post-effect requirement, so it is **not an allowed overlap** in this proposal. All public preparation for a genuinely shareable next effect must finish before the shared scan, without secret/effect during preparation. In particular final public files, current authority and physical PID checks must precede Q9, followed by synchronous retirement/publication; another final async check after Q9 creates a tenth boundary rather than permitting a stale shared scan.
This ledger has unresolved hard requirements: key read and HMAC are separate asynchronous boundaries today, so a scan before the key read is not automatically a fresh pre-HMAC scan. Opening the strong source also reads keys. Those extra reads/checks must not be hidden in the nine/eight slots. A future fixed key effect would need to prove its exact key-read/HMAC ordering and current source checks without changing old strong APIs or carrying keys through the locked snapshot. Synchronous fixed-size secret reads or a different purpose-specific key operation are **not approved here** and need separate review for ordering, cancellation and I/O behavior. The two claim-dependent MAC phases remain separate. PostgreSQL cannot compute the application-key HMAC without granting the database a new secret capability, which is outside scope.
The feasible next implementation path is therefore: finish public-only prerequisites; implement the same-lease secret-free metadata path and private observation metadata proof; then review one closed, fixed enrollment effect dispatcher against this nine/eight-slot candidate **before** implementing effect fusion. It must demonstrate actual adjacency at transport/key/DO/COMMIT boundaries or reject the target. The new-alias path still misses the eight-scan static target and requires an explicit new decision, not hidden delayed post-checks. Reducing Docker query flags does not establish any of these proofs.
Moving observation or MAC preparation before the window is not a lifetime solution. The coordinator fixes its five-second monotonic budget before its first grant read; retained observation expiry and the writer's original end clip all later scopes. Performing work earlier consumes that same original budget, does not renew it, and cannot project credentials outside the required held-Q/physical-owner conditions. The claim MAC additionally depends on the actual observation, and its second phase on the locked registry snapshot.
## Review/acceptance gates
For the public helpers, reject any return field or comment claiming SQL identity, key-current status, held physical ownership or native verification. Reject secret-file reads, `connector`/pool access, HMAC production, or using the returned public object to mint a strong session. Preserve captured scope, original expiration and signed source pin; rotation during public-file I/O must refuse inconsistent results.
For future integration require forwarding actual SQL/HTTP observers, zero credential projection in metadata frames, exact source/grant/endpoint rotation negatives, raw owner loss, fake/copied frame refusal, late Q cancellation and COMMIT lost-ACK/post-ACK UNKNOWN. Count actual scans and secret reads with the measured latency fixture before any separately authorized stand attempt. No filesystem-based substitute for Docker Q is part of this design.
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.