#Architecture

This is the architecture of the development preview, not a description of a released product. Only manifest v3, catalog v3, receipt v6, plan v4, host protocol v6, managed scope v2, and manager tools v5 are current cognitive-package inputs.

Host protocol v6 binds User and Workspace kind independently from the textual scope ID. It keeps package observation separate from exact operation observation, revision-based watch, and explicit-user pre-admission cancellation. Those projections use only durable Use-owned evidence and do not create a second lifecycle state machine.

The A1 qualification matrix composes User and Workspace managers over one shared Artifact Store and the same textual scope ID. The same signed OKF package completes apply, restart, exact snapshot, leased query, upgrade, uninstall, and terminal replay in both installations. An operation leaves the other installation cursor unchanged and its admitted generation lease callable: shared immutable bytes are an optimization, never lifecycle or invocation authority.

The Use-owned PluginManagerService is now the typed presentation boundary over that Host protocol. Its standard MCP adapter exposes exactly the frozen thirteen-tool v5 inventory and delegates every operation to the same service. Apply and cancellation reopen durable evidence and request existing confirmation from an injected trusted host provider; an agent tool call never becomes user confirmation. Standalone Registry-backed install, upgrade, and uninstall now use this service and include the exact Host plan/apply result in their JSON output while preserving existing fields. The standalone plugin CLI maps all thirteen manager operations to the same service, returns the exact typed result, keeps planning read-only, and requires the exact durable operation ID, plan digest, and explicit --yes for apply or cancellation. A normal CLI or agent call does not imply confirmation. The A3S Code TUI and Code-side manager MCP composition now reuse this same service, so the CLI, TUI, and manager endpoint share one operation identity and confirmation boundary.

The manager MCP adapter also projects internal UseError values into a secret-free public error contract (PR #197). Only validated use.* codes and bounded public messages cross the boundary; paths, URLs, suggestions, details, provider-owned identifiers, and package-authored diagnostics are omitted or collapsed to a generic code. PR #199 adds an embedding Gateway path that acquires and retains an exact CapabilitySnapshotLease through server clones and calls. PR #200 separates the catalog publication generation from each descriptor's package lifecycle generation, so one immutable publication can safely contain independently upgraded packages without admitting two incarnations of one surface. Live-host reference resolution, per-consumer authorization, CLI wiring, and the independent client/recovery matrix remain open. PR #202 adds host-owned bounded admission to Gateway calls and a standard Streamable HTTP /mcp endpoint. PR #203 hardens that edge with a constant-time bearer credentials, duplicate-header rejection, optional exact Origin checking (native clients may omit Origin), WWW-Authenticate and Retry-After responses, and real rmcp client discovery/invocation tests. The transport does not terminate TLS; hosts must use loopback or a trusted TLS reverse proxy. Authentication and admission are endpoint safeguards, not live reference authorization. CapabilityGatewayHttpConfig::for_principals now supports a bounded (64-entry) immutable token-to-principal registry; the full credential set is scanned without early exit, duplicate tokens are rejected, and only the selected typed principal is passed to provider hooks. The value is never serialized into MCP discovery or results.

The injected invocation provider is also the authorization seam. Its required authorize hook runs after the published input schema is validated and before any provider effect; a denial returns the bounded use.plugin.capability_gateway_forbidden result and never calls invoke. Hosts should bind a provider instance to their authenticated principal and keep principal, Grant, and scope policy private to that provider. There is no implicit allow implementation; even a contract-only provider must state its policy explicitly. The hook does not replace production receipt/Runtime/Grant composition.

The live resolver seam is explicit: CapabilityGatewayInvocationResolver maps one catalog descriptor to a private CapabilityGatewayInvocationLease, and CapabilityGatewayResolvedProvider verifies the exact opaque reference, authorizes once, and retains the handle through the call. The production host still has to compose receipt, Runtime, Grant, and multi-principal authorities; the seam itself does not grant access.

Embedding hosts can derive the Gateway catalog from one immutable CapabilityRegistrySnapshot with CapabilityRegistrySnapshot::capability_gateway_catalog. This bounded projection rechecks each host-supplied, schema-checked descriptor against the snapshot cursor, exact package/manifest digests, reviewed publication evidence, selected surfaces, and ready/enabled bindings before constructing the canonical catalog. A host may expose a consumer-specific subset, but the helper cannot invent a package or surface outside the reviewed publication. Signature verification and opaque-reference resolution remain host authorities. The companion CapabilityGatewayMcpServer::from_registry_snapshot acquires the matching RAII lease only after projection and returns no server when the publication changes or is draining.

For a live host that has verified signed descriptions, the preferred constructor is CapabilityGatewayMcpServer::from_verified_registry_snapshot_with_factory_and_options. It consumes one snapshot, binds the verified catalog and resolver to the same cursor, acquires the exact server lease, and retains consumer negotiation and bounded admission policy together. A publication race returns no server. The injected factory remains responsible for receipt, Runtime, Grant, principal, and scope authorization.

The embedding boundary now retains a typed consumer decision as well. CapabilityConsumerProfile distinguishes the default generic-mcp client from an explicit a3s client, and CapabilityConsumerNegotiation rejects an unsupported Flow, Knowledge, or UI request instead of silently dropping it. The canonical negotiation and digest survive Gateway clones and snapshot leases. These labels are metadata rather than grants: the current standard MCP adapter still publishes only schema-validated Tools, while profile-aware resources/prompts and production host composition remain open.

The target architecture separates package management, workload scheduling, and host rendering. Its most important constraint is: CLI, TUI, and agent management MCP must call one shared Plugin Manager instead of implementing separate lifecycles.

     local package          release bundle     named TUF registries
           └──────────────────────┬───────────────────────┘
                                  │
                    shared host Plugin Manager
       catalog · resolve · lock · policy · plan/apply · replay
                                  │ exact reviewed closure
                                  ▼
                         a3s-use package engine
    verify · install forward · bind · publish once · remove reverse
                    ┌─────────────┴─────────────┐
                    │                           │
               native plane               cognitive plane
          Runtime Task/Service             MCP · OKF · Flow · Skill · UI
                    │                           │
                    └─────────────┬─────────────┘
                                  ▼
                 A3S Code · OS · Knowledge · agents

#Ownership

#Single sources of truth

The current implementation reuses these existing mechanisms:

• a3s-use-core: canonical package/plugin, dependency resolver/lock, catalog, plan, permission, grant, release, and OKF bundle contracts;
• a3s-use-extension: ACL manifests, package-graph Registry resolution/download, TUF catalog, package store, receipts, leases, and workspace grants;
• src/plugin_lifecycle: canonical package and package-graph intent, dependency schedule, durable journal, coordinator, and typed Tool/MCP/OKF/Flow/Skill/UI hosts;
• src/plugin_runtime: Runtime selection, bindings, receipts, invocation, and observation;
• src/surface_reconciler plus src/capability_registry: dependency readiness and capability publication;
• src/plugin_manager: the shared typed application service and standard manager MCP adapter over the production Host Manager. Standalone Registry-backed compatibility mutations and the complete thirteen-operation plugin CLI, A3S Code TUI, and Code-side manager MCP composition use this service. The adapter projects only the bounded, secret-free manager error contract; host lifecycle leases and endpoint authorization remain separate.

Do not add another manager, grant store, Runtime selector, capability registry, or generic execution protocol.

UsePaths owns one process-wide Artifact Store. Verified archives, executable planning targets, presentation media, and expanded package trees are sharded by SHA-256 there and carry no Registry-source or installation authority. Registry datastores retain canonical source observations and resumable partials; installation snapshots retain selections and lifecycle authority. Source prune and scoped uninstall never delete global bytes. Immutable Runtime plan payloads are decoded under the installation maintenance and plan-store locks, and their referenced Blob artifacts remain part of reachability. Cross-source reachability, hard quota admission, and path-free read-only digest audit now cover both physical tiers. Exact-plan logical quarantine re-audits a complete mismatch, publishes a canonical no-clobber marker, preserves the original bytes, and blocks new ordinary access; the marker grants neither recovery nor deletion authority. Verified rehydration now runs separately through ArtifactStoreMaintenance: the same collection guard covers a fresh zero-durable-reference proof, independent candidate verification, exact path-free review, quota-aware staging, and prepared/completed crash recovery. Completed exact replay is read-only and no longer depends on the external candidate or retirement of references published after completion. Confirmed GC is implemented as another ArtifactStoreMaintenance operation. Its bounded policy explicitly names exact Blob or expanded-package digests; there is no automatic sweep. Planning and nonterminal apply keep the global collection guard across a fresh all-owner zero-reference proof and exact physical/lifecycle evidence. Apply requires the reviewed canonical plan digest, publishes a durable admission fence, atomically retires each container within its shard, and removes only a bounded no-link tombstone tree. Interrupted state blocks new references and resumes the same target set. Completion replay is read-only, while predecessor chaining distinguishes later objects that reuse a digest from the operation already completed.

#Package dependency boundary

A schema-v3 package declares only package IDs and SemVer ranges. The host owns the enabled named Registry set. The standalone host persists it as canonical ACL, compare-and-swaps authority changes against a reviewed revision, and isolates TUF metadata, observations, and partials by exact source identity. Resolution is bounded and deterministic, rejects cross-Registry ambiguity, and emits one canonical lock containing exact versions, content digests, host compatibility, Registry URLs/trust roots, and TUF role versions.

The operation plan binds that lock. Apply revalidates the entire closure before payload download, then prepares dependencies before dependents. Existing dependencies are retained only when their exact locked generation is already visible. All changed packages publish through one immutable snapshot cutover; uninstall runs in reverse and refuses to remove a package with installed dependents.

#Host-owned Runtime Broker

A package may declare workload requirements but cannot select a provider. The host supplies an explicit RuntimeClientRegistry and assignment. Planning performs two deterministic selections:

1. Before archive download, a signed planning target proves that a compatible provider exists.
2. After the grant proposal is fixed, the same provider/build/capability evidence binds final semantics.

If no provider satisfies the request at either stage, planning fails closed. It must not fall back to native execution or another provider. ADR-001 freezes this boundary.

#Why a saga

Package storage, workspace grants, Runtime, Gateway, projection, and capability publication do not share a database transaction. The complete apply is therefore a durable, idempotent parent saga:

intent
  → package checkpoint
  → grant checkpoint
  → Runtime checkpoint
  → Gateway checkpoint
  → projection checkpoint
  → capability publication checkpoint
  → old-generation drain checkpoint
  → terminal result

Each checkpoint uses an idempotency key bound to the plan, exact installation, package generation, action, sequence, kind, and surface. Graph siblings and equal textual IDs in different scope kinds cannot alias. Crash recovery continues from durable intent and the last completed checkpoint. Repeated apply returns the same terminal result without duplicating side effects.

The in-crate foundation now implements a package-lock graph above each package-owned surface graph:

package install:  revalidate lock → download/prepare packages forward → publish changed closure once
package uninstall: hide/drain/remove changed packages in reverse → preserve retained dependencies
surface enable:   prepare surfaces forward → publish once
surface disable:  hide → drain → stop surfaces in reverse

Runtime Tool/MCP, immutable Flow/Skill/UI evidence, and OKF Knowledge adapters are implemented. The standalone host provides a bundled SQLite/FTS5 backend with complete User/Workspace isolation, transactional generation cutover, exact projection-authorized search, and concept/source-digest citations. It also composes the real A3S Flow preflight host only from an explicit absolute compiler path. The P0 schema-v3 package/capability hosts commit a verified generation as installed-disabled, publish or hide exact-generation snapshots, drain generation leases, and remove only receipt-owned roots. The dependency foundation adds exact retained-node verification, crash-safe atomic graph publication, durable admission/lock records, and journal recovery after partial install or uninstall. Signed remote standalone CLI installs use this graph. A3S Code's Plugin Manager composes executable Tool Tasks, stdio MCP, the real A3S Flow preflight host, Skill, and UI through the public lifecycle factory; CLI and TUI consume one watcher and hot-plug exact generations. Managed A3S Code Knowledge Workspace/session carriers, Runtime Service/Gateway composition, durable Flow run routing, and prior Runtime generation retirement remain in progress, so this foundation does not claim a complete production saga.

Embedding hosts implement CognitivePackageLifecycleFactory to supply their exact Runtime, Gateway, A3S Flow, Skill/UI, and A3S Knowledge adapters. They reuse Use's resolver, graph journal, and capability cutover rather than creating another package manager. The standalone factory supports executable Tasks, stdio MCP, immutable Skill/UI projection, local SQLite/FTS5 OKF Knowledge, and A3S Flow only when configured with an absolute native TypeScript compiler path. It fails before publication for required Service, HTTP MCP, or unconfigured Flow owners. CognitivePackageManager::new stays provider-free; from_env is the explicit CLI composition.

ADR-002 freezes this lifecycle boundary.

ADR-003 freezes the next Control Store boundary: one per-installation mutable authority, no JSON/SQLite dual writes, and an outbox around provider effects that cannot join the local transaction.

The inactive schema-v11 kernel now derives that complete outbox inventory from the reviewed Plan and committed generation. It prepares dependency surfaces before dependants, cuts over once, drains accepted calls, and retires surfaces in reverse order through typed owners. Tool and MCP effects bind the exact reviewed Runtime selection; package state, Grants, lifecycle identity, and provider selection stay inside the aggregate rather than becoming duplicate effects. Applied outcomes persist canonical owner-specific Capability Index plus its immutable Agent-catalog binding, lease, Runtime Task/opaque-Service readiness, Flow artifact, Knowledge projection, or Skill/UI content evidence. The applied cutover observation atomically advances publication and the catalog identity before drain; a later required failure remains pending for same-key reconciliation instead of rolling back visible state. The inactive one-effect dispatcher now retains one installation-wide shared maintenance fence from claim through durable observation, commits a claim, releases the SQLite transaction and bounded executor before owner I/O, routes the exact identity through separate Capability Index, invocation-lease, Runtime, Flow, Knowledge, Skill, or UI ports, and records a later applied, deferred, rejected, or unknown observation. Deferred is reserved for owner-proven safe-no-effect outcomes; its bounded durable not-before time blocks early claims and then permits automatic same-key retry. Provider timeout leaves a fixed observation budget inside the claim lease and becomes unknown evidence. Timeout or caller cancellation detaches only the wait: the possibly accepted owner task retains the same shared maintenance guard until it actually completes. Process exit after a possible effect, expired claims, and ambiguity require explicit replay of the committed key. Production lifecycle still does not construct it. The first concrete post-commit adapter now covers immutable Skill and UI preparation. It re-derives the typed owner and committed idempotency key, acquires the exact package through the verified Artifact Store lease, reads one named surface without exposing its package root, re-verifies the full package, and returns a stable path-free receipt independent of retry claim metadata. Contention safely defers the same key; tampering, absence, or authority substitution is a proved-no-effect rejection; this read-only adapter cannot report unknown acceptance. Static stop/remove are path-independent projection receipts. The second concrete adapter now covers OKF Knowledge. It reads first-use OKF content only as a path-free verified Artifact payload, saves staged receipt evidence before promotion, saves promoted evidence before reporting applied, and replays retained promoted evidence without Artifact access. Pre-effect contention safely defers; authority or byte drift rejects; ambiguity after stage, promote, remove, or receipt persistence remains unknown for explicit same-key reconciliation. Stop performs no Knowledge mutation and remove uses the retained receipt. A real SQLite composition test carries one committed claim through the dispatcher and back into durable Control evidence. Artifact admission is separately idempotent and creates no lifecycle authority; its reference guard spans the distinct Control commit. A third concrete Capability Plane adapter now implements Capability Index and invocation leases together. It asks a host-owned pure projector for the Agent catalog, rejects descriptors outside enabled and prepared package incarnations, publishes that catalog, and writes one canonical content-addressed Index document containing its immutable identity. There is no second SQLite store or mutable current file; Control's applied cutover observation is the sole publication cursor and binds the catalog identity in the same transaction. Admission reopens that exact catalog before reading the cursor and taking shared locks for every exact package lifecycle incarnation. Drain requires the old incarnation to be unpublished and takes its exclusive lock, safely deferring while an accepted call is active. No-follow, no-replace publication and exact staging replay protect both immutable payloads. Index and lease files are derived operational state excluded from backup; coordinated legacy inventory now validates the catalog and descriptor-snapshot records as one strict CapabilityPayloads family. Production owner-registry cutover, clean-target activation, and retention coordination remain separate gates. The strict descriptor projector at this boundary consumes only host-verified CapabilityDescriptionProof values plus a package-scoped signer allowlist. It checks exact catalog provenance, dependency closure, prepared owner evidence, active Grants, and reviewed Tool/MCP shape before deriving opaque route identities. The projector is side-effect free and subset-based; key custody remains a separate activation gate. An installation-owned durable snapshot store now captures the exact normalized proof set and signer policy under the Control candidate identity. Its canonical bytes are content- addressed, published with bounded no-follow staging and no-clobber replay, and revalidated on every read; missing evidence defers while substitution, duplicate keys, or tampering fails closed. Coordinated backup validates and archives this canonical record, while the store remains an inactive external owner for production Control wiring. Runtime Tool release schemas now travel through the inactive Runtime/Control path as canonical digest attestation; key custody, owner-native clean-target restore/retention, and production Control/Runtime wiring remain open. A real composition test covers Knowledge, Skill, catalog/Index cutover, stale admission, and same-key drain retry. The inactive Runtime owner is now qualified for release-backed Tool Task/Service and Streamable HTTP MCP. It consumes a path-free verified release payload on first prepare, binds the complete plan semantics to committed provider evidence, persists monotonic Runtime/Gateway recovery state, and replays or retires exact final receipts without Artifact paths. Any ambiguity after an external or persistence effect remains unknown. Runtime now exposes a bounded canonical RuntimeSurfacePlan payload and CommittedRuntimeSurfaceResolver, so a host can reconstruct all inputs after restart and recheck exact provider evidence. Production composition must still bind the durable source and atomic dispatcher to committed Control authority and immutable artifacts. The installation-scoped, host-owned RuntimeSurfacePlanStore is now the qualified source: it uses canonical digest addressing, bounded batch publication, no-clobber writes, restart-safe reads, and fail-closed tamper checks. It owns payload bytes, not desired state, so exact new records must publish before the corresponding Control commit. The process-local Runtime selection used for qualification is not production authority. The inactive lifecycle admission seam accepts the canonical cognitive-package Plan, authorization evidence, and optional planned Grant transition. It derives both prior Control cursors from the immutable Plan and accepts no caller-selected generation. The combined qualification entry point retains one installation-wide fence while registering the exact reviewed operation, projecting graph, Grant, provider, capability, and effect fields, checking exact Runtime prepare coverage and reviewed Grant proposal digests, publishing immutable plan bytes, and committing the projected generation. Production still must route the live lifecycle through this seam. This is an internal cutover proof, not a public API or production lifecycle wiring. A private path-free registry also freezes the six external payload-owner IDs and exact ACL backup policies. Artifact Store exclusion is explicit; the five snapshotted owners must produce one complete, generation-bound canonical receipt set with schema, digest, and accounting bounds. A private session now freezes one canonical Control export digest under the exclusive maintenance fence without holding a database transaction across owner I/O. The Knowledge owner is the first qualified adapter: it creates and offline-verifies a bounded OKF SQLite/FTS5 archive and canonical binding/selection inventory, or records an absent database as zero files without mutating live state. Both live snapshot creation and offline verification require the exact bound Control export. Every retained Knowledge incarnation must join its original prepare intent and committed OKF bundle; applied observation/projection evidence must match, and removed or missing applied payload needs the matching remove effect. Deferred outcomes remain safe-no-effect scheduling evidence; claimed and unknown outcomes remain reconciliation evidence. None is desired state. The Runtime plan owner is the fifth snapshotted owner: it captures immutable installation-scoped plan envelopes, validates complete key/plan binding, restores them before Host projection activation, and contributes referenced Runtime blob digests to installation reachability. An offline-verified Knowledge snapshot can now stage its exact database under a clean target state root without changing live payload state. Activation requires that target's exclusive maintenance fence, re-audits the database and inventory, rejects unowned, existing, or ambiguous state, and publishes by one atomic rename with a path-free result; retry is idempotent while the same staged attempt and fence remain held. The planning-and-diagnostic observation owner is the second concrete snapshot adapter. It reuses the owning stores' validators and archives only terminal diagnostic histories and terminal resolution attempts. Active resolution/download attempts and locks are excluded from restore authority, while their canonical count and path/digest inventory remain manifest-bound. Bounded no-follow traversal, duplicate checks, a second live scan, no-clobber publication, and offline verification reject drift, substitution, foreign records, unknown layouts, and trailing bytes. Its path-free receipt is bound to the exact Control export. An offline-verified archive can now be staged beneath the target state root without touching live owner paths. First activation requires a clean record inventory and the exact exclusive maintenance fence, then atomically marks the archive as activating before no-clobber record publication. Digest-named deterministic partials make interrupted publication replayable; only an exact snapshot subset is accepted after activation starts, and the result remains path-free. The Host protocol projection is the third concrete snapshot and clean-target restore adapter. Its owner-native scanner archives immutable request-to-plan records, optional outcomes, and canonical cancellations. Operation aliases and latest-enablement diagnostics are derived indexes: they must agree with their source requests but never enter the archive. Bounded no-follow traversal, a second scan, no-clobber publication, and offline owner decoding reject drift and substitution. Before publication, Host Plans, completion/cancellation evidence, desired package state, selected surfaces, and package/capability generations must reconcile with the exact bound Control export; Host receipt and health fields remain observations. Its path-free manifest also preserves no-change requests without inventing an operation. An offline-verified snapshot can stage a private archive copy and build a complete target-local Host root from exact source bytes and newly derived canonical indexes, excluding legacy aliases and locks. Activation requires the exact exclusive maintenance fence and an absent live owner root, persists a snapshot-bound marker, revalidates both the exact tree and owner-native semantic scan, and publishes the whole root by one atomic no-clobber directory move. Deterministic archive, record, and marker partials plus exact post-publication replay close each local crash boundary. The Restore Coordinator is now the fourth concrete snapshot owner. Its native journal decoder archives only exact canonical completed operations for the bound installation. Active marker and operation files are excluded while their bounded digest inventory remains manifest-bound, including marker-only handoff. Orphaned nonterminal records, pruning or temporary residue, unknown layout, links, foreign history, and path rebinding fail closed. A second scan precedes no-clobber publication; a streaming offline verifier binds exact terminal bytes and the path-free receipt to the Control export. Empty or active-only history creates no archive. Its self-hosted restore adapter requires the exact exclusive fence and active marker, preserves that marker and any current operation, replaces only terminal history, and binds exact before/source/target inventories in durable activation evidence. Replay tolerates retained-operation status progress but rejects marker, candidate, retired-record, or publication-partial drift. A legacy whole-installation marker reserves one future terminal slot at the native 64-record limit; the typed complete-set marker has no retained operation and preserves all 64 source records.

The private complete-set snapshot coordinator now captures the canonical Control export and all five registered owner snapshots under one maintenance fence and timestamp. One path-free canonical manifest binds the fixed owner registry, receipts, schemas, digests, and byte accounting. The coordinator streams a fixed-order single-file archive outside every Use data and state root, reuses each owner-native offline verifier, and publishes only the fully audited file without replacement. Absent owners add no payload bytes, and the global Artifact Store remains excluded. These paths remain inactive qualification code. The verified aggregate can now retain one target's exact exclusive fence and stage the Control database plus all five owner candidates beneath one fixed .control-installation-restore directory. A path-free descriptor first binds the snapshot, installation, owner registry, Knowledge policy, and component set. Control is single-file checkpointed, export-round-tripped, and physically digest-bound; external candidates reuse owner-native validation under the same guard. No live authority path changes. Exact retry and interrupted Control construction recover, while contaminated targets, links, unknown entries, rebinding, and candidate drift fail closed. Complete activation now preflights every owner before recording durable top-level intent. The immutable attempt remains the restore identity; activation.json is the sole mutable ordered journal, and the typed global .maintenance.restore.json marker binds the same operation and blocks ordinary shared access. Control Store, Runtime plans, Host projection, Knowledge, observations, and Restore Coordinator execute in fixed order; each step follows journal, marker, owner effect, checkpoint. Every checkpoint binds its canonical path-free result by byte count and a domain-separated digest. The coordinator owner also verifies the exact marker bytes, length, and digest before history mutation. Reopen reacquires the exact fence, rebinds the same verified snapshot, attempt, registry, and policy, and reconstructs or verifies every candidate/live boundary. Journal and marker partials, all six post-effect/pre-checkpoint boundaries, the final checkpoint before retirement, and exit after deletion converge. Marker absence is accepted only beside the complete six-checkpoint journal; out-of-order roots, ambiguous markers, links, rebinding, and evidence drift fail closed. Completed replay performs no owner effect and can only resume bounded fixed-order retirement of the six link-free staging trees. A 21-boundary real-child-process matrix qualifies the top-level protocol, including every retirement boundary. The canonical attempt.json and complete activation.json then form the exact installation-bound terminal receipt. Legacy backup and artifact reachability exclude only that two-file receipt; incomplete, extended, linked, or tampered evidence fails closed. Production backup/restore wiring and coordinated authority cutover remain disabled until every consumer can switch together.

#Runtime visibility

The Surface Reconciler observes desired state, generation receipt, grants, bindings, Runtime/Gateway health, A3S Flow observation, and Skill/UI/OKF projection. OKF has a distinct Knowledge-host owner: missing is pending, staged is unpublished, and only exact promoted evidence is healthy. The Capability Registry publishes a new snapshot only when complete evidence agrees on one publication generation. Resident hosts can watch publication generation plus revision and hot-refresh without restarting; each advertised descriptor still carries its owning package lifecycle generation.

Flow has one engine identity. Native TypeScript is an execution adapter, flow.json is a visual design/deployment document, Code is a local host, and OS is a remote target. These paths must never create parallel package receipts or lifecycle journals.

OKF has a different host boundary from Runtime: it runs no process. Use verifies and records the exact package generation; the Knowledge host owns conformant atomic promotion, indexing, and cited retrieval. A failed new OKF generation must not replace the last searchable generation. A newly published snapshot selects N+1, while an in-flight session may retain exact N until receipt-owned retirement removes it.

Read the full Plugin Platform Architecture.