Roadmap: From TransactionContext → TypeScript SDK with MAP Commands via IntegrationHub

[evomimic]

Roadmap: From TransactionContext → Minimal TypeScript SDK → Expanded MAP Capabilities

(Revised to foreground v0 / v0.1+ / v0.2+ milestones)

This roadmap charts the remaining concrete steps required to deliver a TypeScript MAP SDK backed by the MAP Commands interface, following the introduction of TransactionContext and TransactionManager in MAP Core.

The roadmap is explicitly structured to enable earliest delivery of a minimal but functional TS SDK (v0) so that MAP DAHN development can proceed in parallel with continued SDK and core enhancements.

Milestone Summary

v0 — DAHN-Unblocking SDK
Deliver a minimal TypeScript SDK that supports single-space transactional staging and commit, providing a stable API foundation for MAP DAHN development.

v0.1+ — Safety & Reliability
Add transaction rollback and hardened error semantics to improve developer safety and correctness without expanding the SDK’s conceptual scope.

v0.2+ — Power & Experience
Introduce undo/redo and multi-space workflows to support richer human interaction patterns and advanced application use cases.

NOTE: Progress of this plan is tracked in "Comment" immediately following this discussion body.

---

Phase 0 — Baseline Assumption (Pre-v0)

This roadmap assumes the TransactionContext PR has landed with the following properties:

• TransactionContext is the primary execution surface
• HolonsContextBehavior is implemented by TransactionContext
• Exactly one implicit open transaction per space/context
• No MAP Commands layer exists yet
• No TypeScript SDK changes have been made

All phases below build on this foundation.

---

v0 Milestone — “DAHN-Unblocking SDK”

Deliverable:
A minimal, stable TypeScript SDK that supports transactional staging and commit in a single space.

DAHN can begin real development against this milestone.

---

Phase 1 — Core Stabilization (Rust Only, v0-critical)

Goal: Ensure MAP Core is transaction-correct and SDK-safe before any IPC surface is exposed.

1.1 Eliminate Residual “Context” Leakage

Tasks:

• Audit all call sites that:
  • Accept &dyn HolonsContextBehavior
  • Immediately call get_space_manager()
• Inline or refactor these calls to:
  • Use TransactionContext methods directly, or
  • Use explicitly delegated space-scoped methods

Outcome:

• TransactionContext is the true execution surface
• Execution semantics are explicit and auditable
• SDK semantics map cleanly to core behavior

Pull Requests and Issues:

• PR 370 implement initial transaction support #372 for Issue Implement Initial Transaction Support #370

---

1.2 Reference Layer Transaction Awareness (v0-critical)

This step must precede any Commands or SDK work.

Tasks:

• Decide and implement one of:
  • References embed TxId, or
  • References embed a Weak
• Update all reference types:
  • SmartReference
  • StagedReference
  • TransientReference
• Enforce:
  • References resolve only within their originating transaction
  • Cross-transaction misuse fails deterministically

Outcome:

• Eliminates isolation bugs
• Makes transaction boundaries self-describing
• Simplifies SDK mental model

Pull Requests and Issues:

• PR 379 transaction bound self resolving reference layer phase 12 #384 for Issue Transaction-bound, Self-Resolving Reference Layer (Phase 1.2) #379

---

1.3 Minimal Transaction Lifecycle Semantics (Commit-only)

Scope is intentionally minimal for v0.

Tasks:

• Add explicit transaction states:
  • Open
  • Committed
• Enforce invariants:
  • Queries allowed only in Open
  • Mutations allowed only in Open
• Implement:
  • commit()

Explicitly deferred:

• Rollback semantics
• Undo stacks
• Redo semantics

Outcome:

• Stable execution contract for Commands and SDK
• DAHN can rely on commit as a persistence boundary

Pull Requests and Issues:

• PR 383 minimal transaction lifecycle semantics commit only phase 13 #401 for Issue Minimal Transaction Lifecycle Semantics (Commit-only) (Phase 1.3) #383

---

Revision Note (2026-01-27):
Phase 1.4 — Execution Surface Consolidation was introduced after the original roadmap was drafted, based on follow-up discussion during implementation of Phase 1.2.

Earlier phases (1.1–1.3) are unchanged; 1.4 clarifies when and how the transition from HolonsContextBehavior to TransactionContext should occur.

Phase 1.4 — Execution Surface Consolidation (Rust Only, v0-critical)

Goal:
Complete the transition from a context-routed execution model to a TransactionContext-centric execution model, in preparation for the MAP Commands layer.

This phase is intentionally sequenced after 1.2 (Reference Layer Transaction Awareness) and 1.3 (Minimal Transaction Lifecycle) so that the refactor is mechanical, not semantic.

---

1.4.1 Retire HolonsContextBehavior as an Execution Abstraction

By the end of Phase 1.3:

• All holon references are transaction-bound and self-resolving
• ReadableHolon / WritableHolon no longer accept a context parameter
• Commit semantics are explicit and enforced by TransactionContext

At this point, HolonsContextBehavior no longer represents a meaningful abstraction.

Tasks:

• Remove HolonsContextBehavior from all new call paths
• Stop treating it as an execution surface
• Eliminate any remaining APIs that conceptually depend on it

Outcome:

• TransactionContext is the only execution surface
• Execution semantics are explicit, concrete, and auditable

---

1.4.2 Migrate Holon Operations onto TransactionContext

The existing standalone APIs (currently in holon_operations_api.rs) are migrated as methods on TransactionContext, grouped into coherent façades.

Examples (illustrative):

• TransactionContext::commit()
• TransactionContext::new_transient_holon(...)
• TransactionContext::stage_new_version(...)
• TransactionContext::get_all_holons()

Key rule:
Any operation that creates, resolves, stages, mutates, or commits holons is a method on TransactionContext.

Outcome:

• No standalone “glue” functions remain
• No implicit service lookup via traits
• The API surface directly mirrors execution semantics

---

1.4.3 Preserve Semantic Grouping via Facades (Not a Monolith)

To avoid a monolithic impl TransactionContext block, introduce internal façade structs that are owned by TransactionContext but exposed ergonomically.

Example pattern (conceptual):

• TransactionContext::holons() → read/write/query operations
• TransactionContext::staging() → staging/versioning operations
• TransactionContext::transient() → transient construction and lookup

These façades:

• Are thin, zero-logic delegators
• Exist purely for semantic grouping and readability
• Do not own state independently of the transaction

Outcome:

• Clean API surface
• Maintainable implementation files
• Natural alignment with future MAP Commands and SDK facades

---

1.4.4 Introduce TransactionContextFactory (Environment Boundary)

Construction of a TransactionContext is environment-specific (client, guest, test, integration hub).

Introduce a factory abstraction to isolate that concern:

• init_client_context(...)
• init_guest_context(...)
• init_fixture_context(...)

Internally, these are unified behind a TransactionContextFactory, but execution code never depends on the factory — only on the resulting TransactionContext.

Outcome:

• Clear separation between:
  • how a transaction is created
  • how a transaction is executed
• Commands layer can depend on a single, concrete execution surface

---

1.4.5 Hard Boundary Before Phase 2

Phase 1.4 must be complete before Phase 2 (MAP Commands Layer) begins.

Invariant enforced by this phase:

• Commands dispatch against TransactionContext, not traits
• No legacy context abstractions leak into the Commands or SDK layers

---

Definition of Done (Phase 1.4)

• HolonsContextBehavior removed or reduced to a thin, non-executing compatibility shim
• All holon operations are methods on TransactionContext
• Execution APIs are grouped via internal facades
• TransactionContextFactory isolates environment-specific construction
• No new code depends on context traits
• Phase 2 can be implemented without architectural debt

---

Rationale:
This sequencing ensures that reference correctness (1.2) and lifecycle safety (1.3) land early, while deferring the noisier—but now purely mechanical—API consolidation until the system is ready to expose a stable Commands interface.

In other words: 1.4 removes scaffolding; it does not change behavior.

---

Phase 2 — MAP Commands Layer (Rust Side, v0-critical)

Goal: Introduce the privileged Commands interface used exclusively by the TypeScript SDK.

2.1 Define Command Model (Shared Types)

Introduce a new crate or module, for example: holons_commands/

Define:

• MapRequest
• MapResponse
• CommandBody
  • QueryCommand
  • MutationCommand
• CommandResult
• CommandError

Invariant:

• Each Command maps 1:1 to an existing MAP Core API call
• No batching, chaining, or implicit side effects

---

2.2 Command Dispatch Layer (IntegrationHub)

Tasks:

• Implement a single Rust ingress function:

  fn dispatch_map_command(request: MapRequest) -> Result<MapResponse, CommandError>

Responsibilities:

• Resolve TransactionContext
• Enforce transaction state invariants
• Dispatch to MAP Core
• Return structured results and errors

Explicitly NOT in scope for v0:

• Undo
• Rollback
• Multi-space routing

Outcome:

• Single authoritative choke point
• Clean contract for TS SDK

---

Phase 3 — IntegrationHub Wiring (Rust ↔ Tauri, v0-critical)

Goal: Make MAP Commands callable from the TypeScript runtime.

3.1 Tauri Command Surface

Expose exactly one Tauri command:

invoke_map_command(request: MapRequest) -> MapResponse

Rules:

• No other MAP APIs exposed
• All validation occurs in Rust

---

3.2 Serialization Contracts

Tasks:

• Define stable JSON schemas for:
  • MapRequest
  • MapResponse
• Ensure:
  • TxId serialized as opaque identifier
  • Holon references round-trip
  • Errors are structured

Outcome:

• Stable IPC boundary
• Enables independent SDK testing

---

Phase 4 — TypeScript Command Layer (Thin IPC, v0-critical)

Goal: Provide a minimal transport layer with zero policy.

4.1 TypeScript Commands Module

Implement exactly one function:

invokeMapCommand(request: MapRequest): Promise<MapResponse>

Responsibilities:

• IPC only
• No sequencing, retries, or logic

Outcome:

• Clean separation between transport and SDK semantics

---

Phase 5 — TypeScript MAP SDK (v0 Delivery)

Goal: Deliver the minimal human-facing SDK required for DAHN development.

5.1 Minimal Transaction Handling (Single Space)

Capabilities:

• One implicit active transaction
• Commit only

API shape (illustrative):

• beginTransaction() (implicit or explicit)
• commit()

Explicitly deferred:

• Rollback
• Undo / redo
• Multiple concurrent transactions

---

5.2 SDK Facades (Minimal)

Implement:

• ReadableHolon
• WritableHolon
• HolonOperations

Invariant:

• Each SDK method:
  • Emits exactly one MapRequest
  • Calls invokeMapCommand
  • Decodes MapResponse

Outcome:

• DAHN can read, write, relate, and commit holons
• SDK surface is intentionally small but real

---

v0.1+ Milestone — “Safety & Experience”

Focus: Improve developer ergonomics and safety without expanding core scope.

Phase 6 — Rollback & Failure Semantics (v0.1+)

6.1 Transaction Rollback

• Implement rollback() in TransactionContext
• Enforce:
  • No mutations after rollback
  • Queries fail on closed transaction

6.2 Error & Validation Hardening

• Deterministic errors for:
  • Commit-after-commit
  • Mutation-after-rollback
  • Invalid reference resolution

---

v0.2+ Milestone — “Power Features”

Focus: Human experience and advanced workflows.

Phase 7 — Undo / Redo (SDK-driven)

Undo:

• Rust:
  • Minimal mutation history in TransactionContext
  • undo_last_mutation()
• SDK:
  • One user gesture → N undo calls
• LIFO only
• Invalid after commit or rollback

Redo:

• SDK-only
• Re-emit original mutation commands

---

Phase 8 — Multi-Space & Advanced Workflows

• Multiple active spaces
• Explicit transaction selection
• Cross-space safety validation

---

Final Note

This sequencing preserves a crucial principle:

Undo exists to serve human experience, not core mechanics.

By delivering a commit-capable TS SDK as early as possible, MAP DAHN development is unblocked while MAP Core and the SDK continue to evolve in parallel.

[evomimic]

Progress Tracker

Let’s use (and update) this comment to identify the specific GitHub Issues created for each milestone and track completion.
Milestones are aligned to v0 / v0.1+ / v0.2+ delivery goals.

---

v0 — DAHN-Unblocking SDK

Goal: Deliver a minimal TypeScript SDK that supports single-space transactional staging and commit.

• Phase 0 — Baseline Assumption Confirmed

  • TransactionContext PR merged (PR 370 implement initial transaction support #372)

• Phase 1 — Core Stabilization (Rust Only)
  Goal: Ensure MAP Core is transaction-correct and SDK-safe before any IPC surface is exposed.

  • 1.1 Eliminate Residual “Context” Leakage — confirmed via PR 370 implement initial transaction support #372
  • 1.2 Reference Layer Transaction Awareness (Tx-scoped references) — Issue Transaction-bound, Self-Resolving Reference Layer (Phase 1.2) #379
  • 1.3 Minimal Transaction Lifecycle Semantics (Open → Committed, commit only) — Issue Minimal Transaction Lifecycle Semantics (Commit-only) (Phase 1.3) #383

• Phase 2 — MAP Commands Layer (Rust Side)
  Goal: Introduce the privileged Commands interface used exclusively by the TypeScript SDK.

  • 2.1 Define Command Model (MapRequest / MapResponse / CommandBody) — Issue MAP Commands -- Phase 2.1 -- Define initial command set (v0) #404
  • 2.2 Command Dispatch Layer (IntegrationHub ingress + enforcement) — Issue MAP Commands -- Phase 2.2 — Implement IntegrationHub MAP Command dispatcher #405

• Phase 3 — IntegrationHub Wiring (Rust ↔ Tauri)
  Goal: Make MAP Commands callable from the TypeScript runtime.

  • 3.1 Tauri Command Surface (invoke_map_command) — Issue TBD
  • 3.2 Serialization Contracts (stable JSON schemas, structured errors) — Issue TBD

• Phase 4 — TypeScript Command Layer (Thin IPC)
  Goal: Provide a minimal, testable transport layer with zero policy.

  • 4.1 TypeScript Commands Module (invokeMapCommand) — Issue TBD

• Phase 5 — TypeScript MAP SDK (v0 Delivery)
  Goal: Deliver the minimal human-facing SDK required for DAHN development.

  • 5.1 Minimal Transaction Handling (single space, commit only) — Issue TBD
  • 5.2 SDK Facades (ReadableHolon, WritableHolon, HolonOperations) — Issue TBD

---

v0.1+ — Safety & Reliability

Goal: Improve developer safety and correctness without expanding core scope.

• Phase 6 — Rollback & Failure Semantics
  • 6.1 Transaction Rollback (rollback(), closed-transaction enforcement) — Issue TBD
  • 6.2 Error & Validation Hardening (deterministic failures) — Issue TBD

---

v0.2+ — Power & Experience

Goal: Enable richer human interaction patterns and advanced workflows.

• Phase 7 — Undo / Redo (SDK-driven)

  • 7.1 Rust-side Minimal Undo Support (undo_last_mutation) — Issue TBD
  • 7.2 SDK-side Undo / Redo Orchestration — Issue TBD

• Phase 8 — Multi-Space & Advanced Workflows

  • 8.1 Multi-Space Transaction Support — Issue TBD
  • 8.2 Cross-Space Safety & Validation — Issue TBD