DAHN Phase 0 PR 3 — Implement SDK-Backed Holon Access Adapter and Descriptor Handle Seam

[evomimic]

DAHN Phase 0 PR 3 — Implement SDK-Backed Holon Access Adapter and Descriptor Handle Seam

1. Summary (Required)

What is the enhancement?
Implement the DAHN SDK-backed holon access adapter that bridges the public TS SDK into DAHN’s runtime contracts, including descriptor handles and a minimal action hierarchy derived from dances.

This PR delivers:

• SdkBackedHolonAccessAdapter
• HolonViewAccess
• HolonViewContext
• descriptor-handle mapping/wrapping
• minimal ActionNode[] construction from dances
• the first DAHN-side runtime seam for reading real holon data through the public SDK only

This PR is about data access and descriptor-handle modeling, not yet about full generic HolonNodeVisualizer rendering.

---

2. Problem Statement (Required)

Why is this needed?
DAHN needs a runtime-safe, public-SDK-only way to access:

• a target holon
• its summary/content
• its HolonTypeDescriptor
• its property descriptors and value type descriptors
• its relationship descriptors, including declared vs inverse distinction
• its dances
• a minimal action hierarchy for action visualizers

Without this PR:

• DAHN cannot access live holon semantics
• later generic node visualization would have no real data source
• there would be no code seam enforcing the “Rust authoritative state / TS accessor handles” model
• descriptor flattening and relationship nuance could be reinterpreted incorrectly in TS

This PR establishes the Phase 0 DAHN-side data boundary.

---

3. Dependencies (Required)

Does this depend on other issues or features?

• DAHN Phase 0 PR 1 contracts/skeleton
• DAHN Phase 0 PR 2 runtime substrate
• Issue 408 public TypeScript SDK available for DAHN use
• DAHN Phase 0 spec and blueprint remain authoritative:
  • docs/dahn/phase-0-post-408-spec.md
  • docs/dahn/phase-0-implementation-blueprint.md

This PR assumes the public SDK model has been clarified as follows:

• holon-scoped access occurs through transaction-bound public HolonReference objects
• TS should not manufacture a separate public ReadableHolon wrapper for DAHN use
• descriptor inheritance flattening is provided by Rust
• TS consumes descriptor handles over the flattened/effective descriptor surface

---

4. Proposed Solution (Required)

How would you solve it?

Implement the SDK-backed adapter and supporting handle wrappers that map public SDK behavior into DAHN contracts.

This PR should implement, at minimum:

Adapter

• DahnHolonAccessAdapter
• SdkBackedHolonAccessAdapter
• open(target): Promise<HolonViewContext>

Responsibilities:

• create or receive a public MapClient
• begin/select the appropriate transaction context for DAHN access
• obtain/select a transaction-bound public HolonReference for the target
• wrap bound reference reads in HolonViewAccess
• construct a HolonViewContext
• derive a minimal ActionNode[] tree from dances

HolonViewAccess

Implement a DAHN-facing wrapper over bound reference methods, including:

• reference()
• holonId()
• key()
• versionedKey()
• summarize()
• essentialContent()
• holonTypeDescriptor()
• propertyValue(name)
• relatedHolons(name)
• availableDances()

Descriptor Handles

Implement reference-backed descriptor handles, including:

• HolonTypeDescriptorHandle
• PropertyDescriptorHandle
• ValueTypeDescriptorHandle
• RelationshipDescriptorHandle
• DanceDescriptorHandle

Important architectural rules:

• descriptor handles must remain accessor-based and reference-backed
• TS must not replicate descriptor state as authoritative local objects
• TS must not implement inheritance flattening
• Rust-side flattened/effective descriptors should be treated as the source for DAHN rendering
• relationship descriptor handles must preserve relationshipKind(): 'declared' | 'inverse'

Action Hierarchy Builder

Implement minimal action hierarchy construction from dances:

• build ActionNode[]
• allow either:
  • a flat action list, or
  • one shallow top-level action group
• no adaptive grouping yet

Future-oriented rule to record in code/docs/tests where useful:

• only declared relationship types are directly mutable
• inverse relationship types are viewable/navigable but not directly mutated

This PR does not need to implement editing behavior, but it should preserve that distinction in the descriptor-handle model.

---

4.1 Implementation Notes

• Target modules:
  • host/ui/src/dahn/adapters/sdk/sdk-holon-access-adapter.ts
  • host/ui/src/dahn/adapters/sdk/descriptor-mappers.ts
  • host/ui/src/dahn/adapters/sdk/action-hierarchy-builder.ts
• Expected new public seams:
  • SdkBackedHolonAccessAdapter
  • working HolonViewAccess
  • working descriptor handles
  • working HolonViewContext
• Explicit non-goals for this PR:
  • no full HolonNodeVisualizer rendering logic yet
  • no DAHN route integration yet
  • no graph/collection visualizers
  • no edit-mode behavior
  • no relationship mutation UI
• Verification path:
  • open a known target holon
  • obtain HolonViewContext
  • verify descriptor handles are accessible
  • verify property value reads work
  • verify relationship descriptor kinds are preserved
  • verify dances produce ActionNode[]

---

5. Scope and Impact (Required)

What does this impact?

• Adds the first real public-SDK-backed DAHN data access path
• Establishes the descriptor-handle seam DAHN will build on
• Locks in the “Rust authoritative state / TS accessor handles” architecture

This PR does not:

• implement generic holon rendering UI
• implement selector behavior beyond the trivial Phase 0 assumptions
• implement editing
• implement graph or collection behavior
• implement action invocation unless already trivial and clearly in-scope
• expose MAP SDK internal transport concerns to DAHN

---

6. Testing Considerations (Required)

How will this enhancement be tested?

• Unit tests for SdkBackedHolonAccessAdapter
• Tests verifying open(target) returns HolonViewContext
• Tests verifying HolonViewAccess delegates through the public SDK only
• Tests verifying descriptor handles are accessor-based and reference-backed
• Tests verifying relationship descriptor handles preserve declared | inverse
• Tests verifying action hierarchy creation from dances
• Boundary tests verifying no imports from MAP SDK internal/*

Representative checks should verify:

• holonTypeDescriptor() returns a descriptor handle, not a replicated state object
• TS does not perform inheritance flattening locally
• ValueTypeDescriptorHandle drives property visualization metadata access
• inverse relationship descriptors are preserved distinctly from declared ones

Integration smoke tests, where feasible, should verify DAHN can open a known target holon into a usable HolonViewContext.

---

7. Definition of Done (Required)

When is this enhancement complete?

• SdkBackedHolonAccessAdapter is implemented
• open(target) returns a valid HolonViewContext
• HolonViewAccess delegates through bound public HolonReference methods
• Descriptor handles are implemented as reference-backed accessor objects
• Rust-side flattened/effective descriptor behavior is assumed; TS does not flatten inheritance
• RelationshipDescriptorHandle preserves declared | inverse
• ActionNode[] is derived from dances
• No DAHN adapter code imports MAP SDK internal/*
• Tests cover adapter behavior, descriptor handles, action hierarchy, and boundary constraints

---

Optional Details (Expand if needed)

8. Alternatives Considered

• Materialize flattened descriptor objects in TS
  Rejected: TS should not replicate authoritative descriptor state.

• Reconstruct inheritance in TS by following Extends
  Rejected: inheritance flattening belongs in Rust.

• Hide descriptor nuance behind one opaque descriptor blob
  Rejected: DAHN needs ergonomic descriptor-specific accessors and relationship-kind visibility.

• Delay action hierarchy work until action visualizers are implemented
  Rejected: dances are already in scope for Phase 0 and need a runtime representation.

9. Risks or Concerns

• ambiguity in how the public SDK exposes descriptor holons and dances
• accidental leakage of transport or runtime internals into the DAHN adapter layer
• over-materializing descriptor state in TS
• losing declared vs inverse relationship nuance

Mitigations:

• keep the adapter public-SDK-only
• use narrow accessor-based handles
• preserve relationship kind explicitly in the handle API
• keep Rust flattening assumptions explicit in code and tests

10. Additional Context

This PR corresponds to PR 3 in the DAHN Phase 0 implementation blueprint.

It is the key seam between DAHN runtime contracts and live MAP data, and should be kept architecturally tight before UI-heavy rendering begins.