414 phase 14 follow up transactioncontext api hardening mutation policy encapsulation

[evomimic]

Summary

Post-merge follow-up for Phase 1.4 hardening (Issue 414) to further tighten TransactionContext boundaries and reduce manager/internal leakage while preserving current runtime behavior.

This PR focuses on:

• API hardening and visibility tightening in TransactionContext
• Centralizing commit input ownership in TransactionContext
• Removing remaining guest-side internal nursery coupling
• Keeping receptor behavior routing-focused, with temporary commit-ingress guard bridge until Phase 2 CommandDispatcher
• Adding lightweight routing tests in receptor
• Documenting a single authoritative lifecycle/operation policy matrix

---

What Changed

1) Removed transient_state plumbing

HolonSpaceManager no longer owns/exposes transient_state, and TransactionContext::get_transient_state is removed.

• Removed from:
  • space_manager.rs
  • space_manager_behavior.rs
  • transaction_context.rs
• Updated affected transaction-manager test to validate space-backed access via get_space_holon().

---

2) Commit inputs are now context-owned (guest-init boundary leak cleanup)

TransactionContext::commit() now owns commit input extraction and stage clear behavior:

• Extracts staged references directly from nursery (get_staged_references)
• Passes staged refs into service commit_internal(...)
• Clears stage only when commit status is Complete
• Applies lifecycle transition locally

This removes the need for guest services to hold injected internal nursery access for commit orchestration.

---

3) HolonServiceApi::commit_internal signature hardened

Changed from nursery-internal access to explicit staged refs:

• Before: commit_internal(context, nursery_access_internal)
• After: commit_internal(context, staged_references: &[StagedReference])

Updated all implementations/callers:

• guest GuestHolonService
• host ClientHolonService
• test doubles in transaction tests

---

4) Removed guest internal nursery wiring path

GuestHolonService no longer depends on internal nursery registration/getter path for commit execution.

This reaps the boundary benefits of prior refactors: commit now receives required inputs from TransactionContext.

---

5) Receptor routing tests (lightweight)

Added routing-classifier tests only (no lifecycle/guard policy assertions):

• commit route classification
• read-only route inclusion
• read-only route exclusion

This keeps receptor tests scoped to dispatch behavior.

---

6) Authoritative lifecycle/operation matrix docs

Added a single policy matrix directly above TransactionContext::assert_allowed(...) documenting:

• Operation vs lifecycle state (Open, Committed)
• Host commit-ingress interaction
• Expected rejection/error semantics

This is the canonical in-code policy reference.

---

Explicitly Deferred

Per discussion, the following are intentionally deferred:

1. API re-expansion guardrail test/lint (allowlist enforcement)
2. Access-key strengthening hygiene
3. core_runtime crate-split prep
4. Moving commit-ingress guard ownership to CommandDispatcher (Phase 2)

---

Transitional Note (Phase 1.5 Bridge)

Receptor continues to acquire commit-ingress guard for commit-like host requests as a temporary bridge.
Policy/lifecycle invariants remain enforced in TransactionContext.
In Phase 2, ingress guard ownership is expected to move to CommandDispatcher.

---

Validation

Locally validated with targeted checks during refactor:

• cargo check for holons_core
• cargo check for holons_guest
• cargo check for holochain_receptor

Full workflow (build:happ, build:host, npm test) rerun requested before PR open.

[owleyeview]

Requesting some small changes and one slightly more significant change that's not directly related to the issue but should be addressed now.

[evomimic]

Implemented all review feedback and re-ran full validation.

What was addressed

1. Host mutation precheck ordering regression

• Added fail-fast host mutation admission check before ClientDanceBuilder::validate_and_execute(...) for non-read-only ingress, so side-effecting request builders cannot mutate state before rejection.
• Added regression coverage for this behavior.

2. load_holons routing cleanup

• Folded load_holons into handle_map_request and removed the command-level bypass.
• Removed ReceptorBehavior::load_holons.
• Removed the old get_all_holons_dance() response hack from load handling.
• All map requests now flow through handle_map_request.

3. Transaction policy surface tightening

• Narrowed TransactionOperation visibility to internal module scope.
• Removed public re-export.
• Clarified docs on assert_allowed to explicitly apply to mutation/commit ingress paths (lookup/read-only paths intentionally excluded).

4. Comment/doc cleanups from review

• Removed stale “Temporary — to be tightened in Phase 6” artifact.
• Added/updated authoritative policy docs in TransactionContext.

Architecture note

The receptor precheck is intentionally a temporary correctness bridge in the current transitional MapRequest -> DanceRequest flow.
Planned Phase 2 end-state remains:

• ingress admission/concurrency checks at CommandDispatcher,
• operation invariants in TransactionContext,
• receptor reduced back to routing.

Validation

• Confirmed with full build/test workflow (build:happ, build:host, npm test, npm start) and local runtime smoke checks.
• All CI Checks pass
• No merge conflicts

All requested changes have been resolved and validated. No need for another review.