Uniform API -- Lightweight Dances

[evomimic]

OBSOLETE

This approach to re-factoring the Dance API was never fully fleshed out and actually misses the mark by a large margin. Rather than try to fix it... I'm just going to close this discussion.

MAP: Rust ⇆ TypeScript layering with lightweight Dances (HolonReference-based)

Goals

• One clean message-passing surface between TypeScript ↔ Rust Host and Host ↔ Guest.
• All dance requests carry a HolonReference for the body; all responses return HolonReference(s) only.
• Enable cross-cutting infra (undo/redo, logging, transactions, authz) without changing handlers.
• Keep today’s static dance dispatch; leave a smooth on-ramp to descriptor-driven dynamic dispatch later.

---

1) High-level layering

A. Rust “Dance Host” (in Tauri)

• Single exported entry: dance(envelope_bytes) -> envelope_bytes.
• Decodes envelope → applies middleware (authz, txn, undo, logs) → dispatches → encodes response.
• Maintains in-memory Transient/Nursery state for the TS hop (stateful here).

B. TypeScript SDK (“true TS API”)

• Thin, typed functions per dance; all call the same transport.
• Builders create/shape Request Holons (transient/staged) and return HolonReference for body.
• Transaction helpers; undo controls; correlation IDs.

C. (Later) Host ↔ Guest Gateway

• Same envelope & HolonReference shapes.
• Adds channel/session_state only at this boundary (infra concern, not dance/body concern).
• Can do Full→Delta optimization later without touching TS.

---

2) Uniform envelope (v1) — HolonReference in/out

Request

• v: "1"
• id: string (correlation)
• ts: ISO-8601
• dance: "Namespace.VerbNoun" (e.g., HolonLoader.LoadSegment)
• kind: "query" | "command"
• body: HolonReference ← the only payload field
• txn?: { id: string }
• undo?: { policy: "Record" | "Skip" }
• meta?: { actor?: string, caps?: string[], locale?: string }
• (infra-only, set by gateway if needed) channel?, session_state_mode?, session_state?

Response

• v: "1"
• id: string
• ok: boolean
• result: HolonReference | HolonReference[] | null ← always refs, never raw data
• error?: { code: string, reason: string, details?: any }
• logs?: any[]
• effects?: { events?: any[] }
• (infra-only) session_state?

---

3) HolonReference (canonical forms)

A HolonReference may point to:

• Transient: {"transient":"<opaque-id>"} (host-local, non-forgeable)
• Saved by Id: {"id":"<HolonId>"}
• Saved by Type:Key: {"tk":"TypeName:Key"}
• External via proxy: {"proxy":"ProxyName","tk":"Type:Key"} or {"ext":"<ProxyId>:<LocalId>"}

Rules:

• Envelope never inlines holon content.
• Handlers resolve refs via host stores (and authz).
• Return result(s) as refs to transient/saved/result holons.

---

4) Mapping methods → dances (initial set)

• HolonLoader.load_segment → command: HolonLoader.LoadSegment
• HolonLoader.commit_all → command: HolonLoader.Commit
• HolonReader.get_holon → query: Holon.Read
• HolonReader.search → query: Holon.Search
• Validation.validate_import → query: Validation.ValidateImport
• Txn.begin / Txn.end → commands: Txn.Begin / Txn.End

Naming: Namespace.CamelVerb (queries) / Namespace.CamelVerbNoun (commands).

---

5) Handlers (single signature)

fn handle(ctx: DanceContext, body: HolonReference) -> Result<ResultRef, DanceError>

• DanceContext supplies correlation id, actor/caps, txn context, undo sink, logger.
• Handler resolves body to a request holon (transient/staged/saved), reads props/rels, performs logic.
• Returns ResultRef = HolonReference | Vec<HolonReference> | Null.

---

6) Request holon pattern (builders & shaping)

• TS builders create/shape a request holon in host memory (transient/staged), then pass its HolonReference as body.
• Common helper dances for TS hop (stateful host):
  • Transient.CreateEmpty → returns HolonReference
  • Transient.SetProperty / RemoveProperty
  • Transient.AddRelationship / RemoveRelationship
  • Transient.Seal
• These are not forwarded to the guest as-is; on Host↔Guest you’ll use coarser dances (same names, richer bodies).

---

7) Undo/redo (compensations)

• For kind:"command", host preps a compensation entry only after a successful mutation.
• Prefer explicit revert dances (e.g., HolonLoader.RevertStage) recorded with minimal facts.
• Default undo.policy = "Record", SDK can override per call.
• LIFO semantics, idempotent compensations.

---

8) Transactions

• Txn.Begin → host creates/returns a txn context (ref by id).
• Commands may declare requires_txn (hardcoded table for now).
• Txn.End with Commit|Rollback drives apply/compensate.
• Handlers see ctx.txn_id and route to staged persistence paths.

---

9) Logging & tracing

• Correlation id required; host adds span_id, latency, outcome.
• Structured logs with fields: time, level, dance, id, txn, actor, error.code.
• Optional logs echoed in dev builds.

---

10) Error model (stable wire values)

• BadRequest — shape/validation/type errors
• Forbidden — authz/capability/ownership/sealed violations
• NotFound — missing ref / expired lease
• Conflict — version/CAS/lease problems at boundaries
• UnprocessableEntity — domain rule failed
• ServerError — unexpected
• NotImplemented, ServiceUnavailable

---

11) Dispatch: static now, dynamic later

Static table (today)

[
  ("HolonLoader.LoadSegment", holon_loader::load_segment),
  ("HolonLoader.Commit", holon_loader::commit),
  ("Holon.Read", holon::read),
  ("Holon.Search", holon::search),
  ("Txn.Begin", txn::begin),
  ("Txn.End", txn::end),
]

Dynamic (future)

• Add optional descriptor_ref to envelope/meta.
• Resolve via loaded DanceDescriptors (ABI boundary).
• Keep static as fallback for core dances.

---

12) TypeScript SDK skeleton

Transport

type Envelope = { v:'1'; id:string; ts:string; dance:string; kind:'query'|'command';
  body: HolonReference; txn?:{id:string}; undo?:{policy:'Record'|'Skip'};
  meta?:{actor?:string; caps?:string[]; locale?:string} }

type EnvelopeResponse = { v:'1'; id:string; ok:boolean;
  result: HolonReference | HolonReference[] | null;
  error?: { code:string; reason:string; details?:any };
  logs?: any[]; effects?: any }

type Transport = (e: Envelope) => Promise<EnvelopeResponse>

Client

class MapClient {
  constructor(private tx: Transport) {}
  async perform(dance:string, kind:'query'|'command', body:HolonReference, opts?:{txnId?:string, undo?:'Record'|'Skip'}) { … }

  // helpers
  async readHolon(ref:HolonReference) { return this.perform('Holon.Read','query', ref) }
  async loadSegment(reqRef:HolonReference, txnId:string) { return this.perform('HolonLoader.LoadSegment','command', reqRef, {txnId}) }
  async beginTxn() { … }  async endTxn(id:string, action:'Commit'|'Rollback') { … }
}

---

13) Serialization, versioning, idempotency

• Canonical encoding for holon state (stable map orders, stable rel ordering).
• Envelope v1 frozen; add fields compatibly or bump to v2.
• Idempotency: meta.idempotency_key for commands (host dedupes).
• Compression on big bodies at Host↔Guest (infra concern; TS unaware).

---

14) Authz & ownership (quick guards)

• Enforce origin-side mutability: local-only writes; foreign refs are read-only (copy-on-write if mutation requested).
• Respect sealed flags and capability checks (meta.caps).
• Clear errors: Forbidden for illegal writes; NotFound/Conflict for dead/expired refs.

---

15) Rollout plan (practical)

1. Freeze envelope v1 (HolonReference body / result) in Rust & TS.
2. Implement static dispatch host entry + middlewares (authz, undo, txn, logs, error mapping).
3. Ship TS SDK: perform(), beginTxn/endTxn, a few ergonomic wrappers.
4. Convert 2–3 core dances to new handler signature (e.g., Holon.Read, HolonLoader.LoadSegment, HolonLoader.Commit).
5. Keep fine-grained Transient.* helpers for TS↔Host; use coarse dances for Host↔Guest later.
6. (Later) Introduce DanceDescriptors → dynamic dispatch + codegen builders.
7. (Later) Add Host↔Guest session-state optimization (Full→Delta) without changing TS or handlers.

---

16) What “result refs” point to

• Result holon (transient): properties summarize outcomes (counts, ids, messages), rels point to items.
• Collection: result is a single holon whose rels Items reference saved/transient items.
• Cursor: result holon with cursor props + Items rel; further pages via new dances.

---

This plan gives you a uniform, future-proof API surface: HolonReference in, HolonReference(s) out, with all the important platform semantics (undo, txn, authz, logging) living in the host middleware—clean for today, extensible for tomorrow.

[evomimic]

This approach to re-factoring the Dance API was never fully fleshed out and actually misses the mark by a large margin. Rather than try to fix it... I'm just going to close this discussion.