# Runtime serving preparation: evidence and ownership

## 2026-09-03 — baseline

- Observed release: Core `329a490619c0cdeb782615f295f6c3bd8dfd942a`;
  candidate base: `9acfecf20631f89d1d8b62bdaeaa5d7a3f7e5a33`.
- A private deployment with 22 handler capabilities timed out waiting for API
  readiness after its nine workers became healthy. The exact API image/config
  became ready when started alone, after roughly two minutes. This does not
  establish that the timeout is exclusively caused by repeated verification.
- A pre-listener stack sample was CPU-active in `ReconcileAll -> prepare ->
  deploymentReceipt -> VerifySource -> ProjectRuntimeMetadataView -> marshalCanonical`.
- Local real-DirectoryStore regression reproduced six full snapshot reads for
  three capabilities, and two reads of each receipt and view. The test fails
  against the unmodified owner. A 200-object/20-field/3-capability fixture took
  481 ms in reconciliation on the development machine. This synthetic case is
  a relative benchmark, not a prediction of production startup time.
- `DirectoryStore.Get` validates an artifact, then the caller opens it again.
  Both deployment attestation and active publication independently reopen the
  same immutable data; each capability repeats the common snapshot work.

## Proposed boundary

Within ONE `ReconcileAll` attempt, reuse successfully opened content-addressed
artifacts and exact `(view digest, source snapshot digest)` verification results.
The scope is the existing local preparation, not a process-lifetime cache or
another registry. Discard it on return, success or failure. Mutable Catalog
ownership remains read from its existing statement-consistent source for every
selection; every scope, lineage, compatibility and ownership check remains.
Request admission still reads only the atomically published prepared set.

This is L0 metadata interpretation (l0-l1-standard.md §1): arbitrary app content,
no product/tenant branches, no contract or publication format changes.

Validation must cover shared input work bounds, live Catalog changes, different
deployment/current revisions, corrupted or mismatched artifacts, failure then
repair, cross-capability isolation and in-flight readers. A later attempt must
reread/revalidate immutable storage, rather than hide corruption behind an earlier
successful preparation. Repeat the measured workload after implementation; the
original full-topology deployment remains the final startup acceptance boundary.

## After implementation

- The same fixture completes reconciliation in 101 ms (baseline 481 ms, about
  4.8x faster / 79% less time). Snapshot reads drop from six to one; receipt and
  view reads drop from two to one. No timing threshold is added to CI.
- All 670 tests/subtests in `internal/runtimeapi` and `internal/runtimeproduction`
  pass with the profiling workload enabled; zero failures and zero skips.
- Native file corruption after readiness is detected on the next reconciliation,
  readiness is dropped, and repairing the file allows a fresh attempt to succeed.
  Existing publication, consumer, cross-capability, and in-flight-reader tests pass.
- Performance and correctness commands:

  ```sh
  NEXUSCRM_SERVING_STARTUP_PROFILE=1 go test ./internal/runtimeapi ./internal/runtimeproduction -count=1 -timeout=5m
  NEXUSCRM_SERVING_STARTUP_PROFILE=1 go test -race ./internal/runtimeapi -run 'Test(Serving|Publication|OpenCommandConsumer|.*Admission.*Sibling|.*Admission.*Lifecycle)' -count=1 -timeout=5m
  ```

- The deployment timeout has not been changed. The fixed full-topology image
  has NOT yet been published or deployed; this is not complete environment
  acceptance. Require exact-image startup and business readback after release.