155 — The Matrix and EstatePublisher Are One Governed REST Projection

Governance chapter: 155. The Matrix FountainStore is the observed state authority; EstatePublisher is the executable projection of native operations over that state. REST makes those boundaries addressable without replacing the MIDI2 IDL, Swift kits, host adapters, or Store receipts.

One Matrix FountainStore projects a read-only status API and an executable EstatePublisher API, while native Swift and MIDI2 remain the authority beneath both surfaces

The generalizing act

The Matrix and EstatePublisher are two views of one governed system, not two systems that happen to exchange JSON.

The Matrix is the FountainStore collection estate.refactoring.scenario-status. It records the observed lifecycle state of the refactoring scenarios: proven, implemented, admitted, or unavailable, together with the evidence and reason that support each state. Its read projection answers: “What is true about the work now?”

EstatePublisher is the independent native Swift CLI/Core product. Its operation registry, Swift kits, host adapters, MIDI2 instruments, and Store receipts define what can be executed. Its REST projection answers: “Which typed operation may be requested, with which inputs, and where will its terminal proof be recorded?”

The two projections may be exposed through OpenAPI, but OpenAPI is a description and address space. It is not a replacement protocol, a second Store, a hand-authored command authority, or a permission to turn every Store write into an endpoint.

The reusable matrix pattern

The rule is not specific to EstatePublisher. Any governed scenario matrix can be projected through the same finite pattern:

Scenario Matrix Store
        ↓
truthful observed-state projection
        ↓
native capability registry
        ↓
executable operation projection
        ↓
typed receipt and evidence

For every matrix, the matrix remains the authority for observed scenario state. A read API may expose the collection and its evidence references. A native operation registry determines what is executable. Only admitted, wired scenarios receive executable operation routes. implemented, admitted, proven, and unavailable remain distinct states.

This pattern applies to Copilot capability matrices, deployment scenarios, instrument admission, Reframe workflows, and future governed scenario stores. Each domain may define its own schemas and operation names, but it reuses the same governance skeleton:

any matrix → truthful state API
admitted native capabilities → executable API
unavailable rows → visible blockers, never fake operations

The generalization is deliberately not “turn every matrix row into an endpoint.” It is a two-gate projection: every row may become truthful state, while only a native capability with an owning kit, executor, authority, lifecycle, and receipt path may become executable. The matrix store, native registry, and terminal evidence therefore remain linked without becoming interchangeable.

One definition, two projections, one observed state

                 normative native definition
       IDL + Swift kit + operation registry + Store contract
                              │
               ┌──────────────┴──────────────┐
               │                             │
       Matrix REST projection       EstatePublisher REST projection
       observed scenario state      executable typed operations
               │                             │
               └──────────────┬──────────────┘
                              │
               FountainStore receipts and evidence

The Matrix projection is read-only except for the one native, governed status-recording command. It must not expose arbitrary collection mutation. EstatePublisher may expose an operation only when the native inventory identifies its operation, scenario, inputs, authority, adapter, lifecycle, and terminal predicates. An unavailable Matrix row is a truthful state, not an executable endpoint.

This is the REST form of the existing “one definition, two projections” rule in Chapter 49. It generalizes the rule from documentation and transport to an executable boundary: the same native definition can be inspected, addressed, and driven through more than one transport while retaining one authority.

REST does not flatten MIDI2 or Swift

REST can model MIDI2 capabilities, Swift-runtime operations, asynchronous progress, cancellation, resume, and terminal receipts. Modeling them does not make them REST operations internally.

The HTTP request is an ingress projection. The native executor still selects the declared Swift operation, resolves its owning FCIS-KIT contract, drives the admitted MIDI2 instrument or host adapter where required, and persists the correlated Store receipt. The HTTP response may return an accepted correlation and a read URL; it must not claim completion from process creation, HTTP 200, or a quiet log.

The lossless identity chain is:

human/API request
  → declared scenario
  → native operation
  → FCIS-KIT / MIDI2 instrument / host adapter
  → correlation and idempotency key
  → FountainStore receipt
  → typed terminal result

Every link remains inspectable. A REST route that cannot name the next link is documentation, not an executable capability.

The Matrix API

The Matrix API exposes the authoritative status collection as a projection:

  • GET /matrix returns the collection identity, source Store, observed revision, counts, and scenario summaries.
  • GET /matrix/scenarios/{scenarioId} returns one status record and its evidence references.
  • GET /matrix/scenarios/{scenarioId}/history returns the append-only status history when the native Store projection supports it.
  • POST /matrix/scenarios/{scenarioId}/status is permitted only as a typed delegation to EstatePublisher --record-scenario-status; it is not an arbitrary JSON merge or direct database write.

The strict native inspection remains the authority for status reports. An OpenAPI client may read the same projection, but a generated document or cached inventory cannot advance a scenario. The status command validates the transition, actor, evidence, and Store lease before recording it.

The EstatePublisher API

The EstatePublisher API is generated from the strict native inventory and the operation contracts. It exposes:

  • GET /operations for the current native operation inventory;
  • GET /operations/{operationId} for one typed operation, its scenario, scope, inputs, effects, and proof predicates;
  • POST /operations/{operationId}/runs for an admitted operation with its typed request and idempotency key; and
  • GET /runs/{runId} for the persisted lifecycle and terminal evidence.

The generated surface includes route publication, local preview, inspection, and other operations only when the native CLI reports them as wired. It does not turn the unresolved ambiguous-destination-request scenario into a prose parser. That row remains visible as unavailable until a governed typed human-request adapter exists.

The API is asynchronous by default. A successful submission means that the native coordinator accepted a typed request and assigned a correlation. Completion means that the terminal MIDI2 envelope, bounded adapter result, and matching FountainStore receipt agree. Remote publication additionally requires typed remote read-back and digest equality.

Security and authority

The REST projection inherits, rather than weakens, the native admission boundaries:

  1. The caller is authenticated and authorized for the named operation and exact target.
  2. Credentials remain in SecretStore-backed host adapters; they never appear in OpenAPI examples or request bodies.
  3. The operation is resolved from the current native inventory, not from route-name matching or a generated manifest alone.
  4. The request is correlated, idempotent, budgeted, and subject to the operation’s cancellation and resume rules.
  5. Effects occur only through the owning Swift kit and named adapter.
  6. The Store receipt and typed terminal result are read back before completion is reported.

HTTP authentication, MIDI2 admission, Store authorization, host admission, and publication authorization remain distinct claims. A valid HTTP token cannot manufacture a MIDI2 peer, a Store lease, a remote credential, or a publication receipt.

Generation and drift

The REST documents are generated artifacts. The Matrix document is generated from strict native status inspection. The EstatePublisher document is generated from strict native operation inspection. Generation fails closed when either input is missing, stale, malformed, or inconsistent with the native authority.

CI SHALL regenerate both documents and compare them with the checked-in projections. A drift failure means that the API description is stale; it does not mean that the runtime has changed safely. Runtime acceptance still belongs to the native CLI, its focused tests, and the owning Store/MIDI2/adapter evidence.

The generated document must preserve these distinctions:

  • declared is not implemented;
  • implemented is not admitted;
  • admitted is not executed; and
  • executed is not proven until the terminal receipt and read-back agree.

Definition of done

This chapter is operationally implemented when:

  1. the Matrix status is read through the native strict inspection path;
  2. the EstatePublisher inventory is read through the native strict inspection path;
  3. both OpenAPI projections regenerate deterministically from those inputs;
  4. --check fails on drift;
  5. every executable operation maps back to one native scenario, operation, owning kit/adapter, correlation, and receipt;
  6. unavailable and merely declared capabilities remain non-executable;
  7. asynchronous completion is proven by terminal evidence rather than HTTP success; and
  8. route publication, preview, Store state, MIDI2 lifecycle, and host effects retain their existing acceptance gates.

Governing sentence

OpenAPI may make the Matrix and EstatePublisher addressable, but only the native definition, the admitted executor, and the FountainStore receipt can make a capability real.