Replace HolonsContextBehavior with TransactionContext Execution Surface (Phase 1.4)

[evomimic]

1. Summary (Required)

What is the enhancement?

Complete the architectural transition from HolonsContextBehavior to TransactionContext as the sole transaction-scoped execution surface for MAP Core.

This phase:

• Removes HolonsContextBehavior as a public abstraction
• Moves the remaining MAP Rust API surface onto TransactionContext (or facades owned by it)
• Establishes a single, authoritative execution model for:
  • MAP Commands (Phase 2+)
  • IntegrationHub
  • TypeScript SDK (v0)

This is a structural cleanup and consolidation step that prepares MAP Core for safe, minimal SDK exposure.

---

2. Problem Statement (Required)

Why is this needed?

After Phases 1.2 and 1.3:

• References are transaction-bound and self-resolving
• Transaction lifecycle semantics are explicit (Open → Committed)
• TransactionContext is already the de facto execution surface

However, the codebase still contains a legacy abstraction:

• HolonsContextBehavior remains in public APIs
• Many operations are expressed as:
  • free functions, or
  • trait methods that immediately delegate back into TransactionContext
• Transaction lifecycle entry is conceptually mixed with transaction-scoped execution

Before introducing MAP Commands and a TypeScript SDK, we must ensure that:

• There is exactly one transaction-scoped execution surface
• Lifecycle entry (begin) is clearly separated from transaction-scoped execution
• Transaction semantics are not split across traits, helpers, and managers
• The API exposed to Commands is explicit, auditable, and minimal

---

3. Dependencies (Required)

This enhancement assumes:

• Phase 1.1 (space-manager fully wrapped behind transaction context) complete
• Phase 1.2 (transaction-aware, self-resolving references) complete
• Phase 1.3 (explicit transaction lifecycle semantics) complete
• Exactly one implicit open transaction per space/context (current v0 model)

This enhancement must land before:

• MAP Commands layer
• TypeScript SDK (v0)

---

4. Proposed Solution (Required)

4.0 Introduce semantic facades to avoid API monolith

As TransactionContext becomes the sole execution surface, simply moving all APIs directly onto it would create an unwieldy and semantically flat implementation.

Instead, Phase 1.4 introduces small, semantically grouped facades owned by TransactionContext.

These facades:

• Partition the transaction execution surface
• Do not represent alternate execution surfaces
• Do not own state
• Do not bypass lifecycle enforcement
• Are thin semantic wrappers over internal managers
• Exist solely to group related operations and prevent API sprawl

MAP operations fall into three semantic domains:

1. Lifecycle control — transaction state transitions (commit, future rollback)
2. Mutation — state-changing operations (write path)
3. Lookup — indexed and convenience read operations

This separation is forward-looking:

• mutation() aligns with future MutationCommand
• lookup() preserves indexed reads distinct from future graph-native querying
• Lifecycle remains on the root because it defines execution semantics

The public execution shape after Phase 1.4 becomes:

TransactionContext
  ├─ lifecycle (root)
  ├─ mutation()
  └─ lookup()

This structure anticipates future graph() support without requiring further refactoring.

---

4.1 Make TransactionContext the sole transaction-scoped execution surface

After Phase 1.4:

• No public APIs accept HolonsContextBehavior
• No free-standing functions act as execution entrypoints
• All reads and writes flow through TransactionContext
• Managers (Nursery, TransientHolonManager, etc.) remain internal implementation details

---

4.2 Lifecycle stays on the root

Remain inherent methods on TransactionContext:

• tx_id()
• lifecycle_state()
• is_open()
• commit()

Future lifecycle operations (e.g., rollback()) also live here.

Lifecycle methods apply only to an already-begun transaction.

---

4.3 Introduce mutation() facade

Grouped under:

transaction.mutation()

Includes:

• Transient construction
• Staging operations
• Write operations
• load_holons

Properties:

• Represents the full write path
• Enforces lifecycle invariants
• Provides a clean future insertion point for undo/redo support

---

4.4 Introduce lookup() facade

Grouped under:

transaction.lookup()

Includes:

• Indexed and convenience read operations
• Staged/transient lookup
• Counts
• get_all_holons

Properties:

• Read-only
• Backward compatible
• Distinct from future graph-native querying

---

4.5 Explicitly reserve future graph-native surface

Phase 1.4 does not introduce graph().

However, the facade structure allows future addition of:

transaction.graph()

without restructuring execution semantics.

Indexed lookup and graph-native querying remain conceptually distinct.

---

4.6 Absorb HolonOperationsApi

All functions currently in HolonOperationsApi:

• Removed as free functions
• Reintroduced under TransactionContext
  • via mutation()
  • via lookup()
  • or lifecycle root

No execution-facing APIs remain outside TransactionContext.

---

4.7 Keep managers internal

The following remain internal collaborators:

• Nursery
• TransientHolonManager
• HolonServiceApi
• HolonCacheAccess

They do not:

• Escape as execution surfaces
• Expose public behavior traits
• Accept lifecycle responsibility

Execution semantics are enforced only at the TransactionContext level.

---

4.8 Review TransactionManager (Owned by Space Manager)

What we need is:

• A space-scoped authority responsible for:
  • Beginning transactions
  • Registering transactions
  • Looking up active transactions
  • Preserving transaction identity uniqueness

This is governance, not construction.

Responsibilities include:

• Space-level ownership of transaction lifecycle entry
• Clear separation between lifecycle entry and transaction-scoped execution
• A single authoritative source of transaction creation per space

---

4.8.1 Architectural Role of TransactionManager

TransactionManager:

• Is scoped to a single HolonSpace
• Is owned by HolonSpaceManager
• Is responsible for:
  • begin_transaction()
  • begin_transaction_with_id(tx_id)
  • get_transaction(tx_id)
• Maintains a weak registry of open transactions
• Does not own transaction lifetime

Transactions are owned by whoever holds Arc<TransactionContext>.

---

4.8.2 Clarified Role of HolonSpaceManager

HolonSpaceManager is:

• The space-scoped infrastructure registry
• The owner of:
  • Cache routing
  • Holon service access
  • Dance initiator
  • Transient state
  • TransactionManager

It is not:

• A transaction execution surface
• A public lifecycle surface
• A semantic domain object

It exposes TransactionManager for lifecycle entry:

space_manager.transaction_manager().begin_transaction()

This makes lifecycle commands clearly space-scoped and outside any existing transaction context.

---

4.8.3 Execution Boundary Clarification

After Phase 1.4:

• Transaction lifecycle entry (open_transaction) is:

  • Space-scoped
  • Provided by TransactionManager
  • Not callable from within TransactionContext

• Transaction lifecycle state transitions (commit, future rollback) are:

  • Transaction-scoped
  • Provided by TransactionContext

This cleanly separates:

• Lifecycle entry (outside transaction)
• Execution and state mutation (inside transaction)

---

5. Scope and Impact (Required)

Impacted areas:

• Removal of HolonsContextBehavior
• Refactoring of call sites
• Migration of free-standing APIs
• Removal of TransactionContextFactory concept

Not impacted:

• Reference model
• Transaction lifecycle semantics
• Persistence formats
• MAP Commands (next phase)
• TypeScript SDK (next phase)

This is a large but mostly mechanical refactor guided by an already-established execution model.

---

6. Testing Considerations (Required)

• Existing tests should continue to pass
• New tests ensure:
  • No public APIs accept HolonsContextBehavior
  • All transaction-scoped execution flows through TransactionContext
  • Transaction lifecycle entry flows through TransactionManager
  • Lifecycle enforcement remains intact
• Test fixtures use HolonSpaceManager → TransactionManager → TransactionContext

---

7. Definition of Done (Required)

This enhancement is complete when:

• HolonsContextBehavior is removed from public APIs
• No execution-facing APIs accept &dyn HolonsContextBehavior
• HolonOperationsApi is removed
• TransactionContext exposes:
  • lifecycle (root)
  • mutation()
  • lookup()
• All write operations live under mutation()
• All indexed read operations live under lookup()
• Transaction lifecycle entry is provided by TransactionManager
• Managers remain internal and do not act as execution surfaces
• All tests pass with updated call sites

[evomimic]

Clarification: Impact of Issue 403 on TransactionManager

Issue 403 (Phase 1.4 — Replace HolonsContextBehavior with TransactionContext Execution Surface) does not prescribe structural changes to TransactionManager.

Specifically:

What Issue 403 Requires Regarding TransactionManager

Only this:

• TransactionManager must not be used as an execution surface.
• TransactionContext must not reacquire itself via TransactionManager once HolonsContextBehavior is removed.
• All execution must flow directly through TransactionContext.

This implies:

• Methods inside TransactionContext that currently reacquire Arc<TransactionContext> through TransactionManager (due to trait object constraints) should be refactored to use self: &Arc<Self> instead.
• After refactoring, TransactionContext should not depend on TransactionManager for internal operation.

What Issue 403 Does Not Require

Issue 403 does not require:

• Renaming TransactionManager
• Splitting it into separate abstractions (e.g., Authority vs Registry)
• Hiding it behind SpaceManager
• Removing get_transaction_manager()
• Changing its ownership (it remains owned by HolonSpaceManager)
• Altering its responsibilities (id generation + weak registry)

TransactionManager remains infrastructure responsible for:

• Opening transactions
• Generating TxIds
• Maintaining weak references
• Resolving TxId → Arc<TransactionContext>

No additional encapsulation or abstraction is mandated by Issue 403.

---

Summary

Relative to the current implementation, Issue 403 prescribes no structural changes to TransactionManager itself.

The only requirement is that TransactionContext becomes execution-self-sufficient and no longer reacquires itself through the transaction registry once HolonsContextBehavior is removed.

[owleyeview]

@evomimic
I'm still not clear on why the TransactionAuthority is needed. As described, the TransactionManager already acts as the TransactionAuthority. If you replace the word TransactionAuthority with TransactionManager in section 4.8 above, all of the requirements are already in place.

The clarification you posted doesn't explain how the proposed TransactionAuthority relates to the TransactionManager.

What Issue 403 Requires Regarding TransactionManager

• TransactionManager must not be used as an execution surface.
• TransactionContext must not reacquire itself via TransactionManager once HolonsContextBehavior is removed.
• All execution must flow directly through TransactionContext.

This implies:

• Methods inside TransactionContext that currently reacquire Arc<TransactionContext> through TransactionManager (due to trait object constraints) should be refactored to use self: &Arc<Self> instead.
• After refactoring, TransactionContext should not depend on TransactionManager for internal operation.

The above requirements in the clarification are already mostly met and an additional TransactionAuthority isn't necessary to meet them.

I think we can drop TransactionAuthority from required Phase 1.4 scope.

If we want a cleaner lifecycle-entry API contract (space_manager.begin_transaction()), we can add HolonSpaceManager delegators without introducing a new abstraction.

[evomimic]

The above requirements in the clarification are already mostly met and an additional TransactionAuthority isn't necessary to meet them.

I think we can drop TransactionAuthority from required Phase 1.4 scope.

If we want a cleaner lifecycle-entry API contract (space_manager.begin_transaction()), we can add HolonSpaceManager delegators without introducing a new abstraction.

Sorry my last comment wasn't clear enough. I agree. No need to introduce TransactionAuthority or rename TransactionManager to TransactionRegistry. Stick with TransactionManager and just make the minor changes suggested in:
Clarification: Impact of Issue 403 on TransactionManager.

[owleyeview]

I edited the original issue description to remove TransactionAuthority

[owleyeview]

Observation: Guest Init Boundary Leak (Proposed Phase 1.4 Scope Addition)

While reviewing Phase 1.4, I noticed that guest initialization currently reaches into TransactionContext internals via transaction_context.nursery() in:

• guest_context.rs (/map-holons/happ/crates/holons_guest/src/guest_context.rs:82)

This is done solely to populate GuestHolonService.internal_nursery_access in:

• guest_holon_service.rs (/map-holons/happ/crates/holons_guest/src/guest_shared_objects/guest_holon_service.rs:42)

Functionally this works, but it weakens the execution boundary established in Phase 1.4. The intent of this phase is that managers (Nursery, TransientHolonManager, etc.) remain
internal implementation details, and that transaction-scoped behavior flows through TransactionContext APIs.

Why internal_nursery_access is a good removal candidate

The current internal_nursery_access path appears to be legacy scaffolding from the context-threading era rather than a necessary execution abstraction:

• It is populated only during guest init, not as a general execution surface.
• It exists to let GuestHolonService access staged data for commit, but this can be expressed via TransactionContext state APIs.
• It introduces a manager-level dependency (Nursery) into guest wiring, which is precisely what Phase 1.4 is trying to remove.

There is also a concurrency-model clarity issue: the extra RwLock<dyn NurseryAccessInternal> wrapper in GuestHolonService is not the authoritative lock for staged mutation. Actual
staging mutations lock Nursery’s internal staged pool directly. So the wrapper does not provide a true global mutation gate; it mainly adds an indirection layer around access.

Given that, keeping internal_nursery_access increases coupling without establishing a stronger execution invariant.

Suggested Direction

I suggest we include this in Phase 1.4 scope while we are already consolidating execution surfaces:

• Remove GuestHolonService.internal_nursery_access and its registration/getter plumbing.
• Stop using TransactionContext::nursery() in guest initialization.
• In guest commit flow, use explicit TransactionContext APIs for staged state access (export/import staged pool + handle-based staged reference derivation as needed).
• After that migration, tighten TransactionContext::nursery() visibility (pub(crate) or remove if unused externally).

This aligns directly with the Phase 1.4 DoD item that managers remain internal and do not act as execution surfaces.

[evomimic]

Observation: Guest Init Boundary Leak (Proposed Phase 1.4 Scope Addition)

Hmm... this question caused me to take a closer look at the TransactionContext API... I somehow missed on the last PR review that the very tightly controlled public API has now been broadened significantly. What we'd work hard to make private, is now wide open to the world and, predictably, now being called from places they shouldn't be. TransactionContext is supposed to be tightly controlling the public API surface... not exposing internals.

Time to put the genie back in the bottle. That will require an end-to-end assessment of the public functions. I've started working on that now. Will update this Issue with another comment once analysis is completed.