DAHN Phase 0 PR 1 — Establish Runtime Skeleton and Core Contracts

[evomimic]

DAHN Phase 0 PR 1 — Establish Runtime Skeleton and Core Contracts

1. Summary (Required)

What is the enhancement?
Establish the initial DAHN Phase 0 code skeleton and core runtime contracts inside the host UI codebase, following the Phase 0 DAHN spec and implementation blueprint.

This PR creates the initial DAHN package-shaped module boundary and defines the foundational TypeScript interfaces that later PRs will implement against.

This phase delivers:

• the initial host/ui/src/dahn/ module scaffold
• DAHN runtime-facing contracts
• target, holon access, descriptor handle, action hierarchy, visualizer, canvas, selector, and theme interfaces
• a minimal runtime interface and error scaffolding
• the initial TS-side selector/resolution seam for Phase 0
• no real rendering, loader, adapter, or UI behavior yet

This PR is about establishing stable seams, not implementing DAHN behavior.

---

2. Problem Statement (Required)

Why is this needed?
Phase 0 DAHN implementation depends on having a stable internal module layout and runtime contract surface before behavior is added.

Without this PR:

• later PRs would invent interfaces ad hoc while implementing behavior
• DAHN architectural boundaries could drift into Angular-specific or transport-specific patterns
• adapter, selector, canvas, and visualizer implementations would lack a shared contract
• the repo would have no stable code seam corresponding to the living DAHN spec

This PR creates the code-level substrate that later Phase 0 slices can safely build on.

It also establishes the initial selector seam in a way that does not incorrectly assign all long-term selector responsibility to TypeScript. In the long-term architecture, Rust is expected to own semantic recommendation while TypeScript owns final runtime presentation resolution.

---

3. Dependencies (Required)

Does this depend on other issues or features?

• Issue 408 public TypeScript SDK is assumed to exist or be sufficiently available for downstream DAHN integration
• DAHN Phase 0 implementation spec is the authoritative spec for this slice:
  • phase-0-post-408-spec.md if published, otherwise local repo doc
• DAHN Phase 0 implementation blueprint is the implementation-oriented companion for this slice:
  • phase-0-implementation-blueprint.md if published, otherwise local repo doc

If the public docs are not yet published, the local repo docs are authoritative:

• docs/dahn/phase-0-post-408-spec.md
• docs/dahn/phase-0-implementation-blueprint.md

---

4. Proposed Solution (Required)

How would you solve it?

Create the initial DAHN module skeleton under host/ui/src/dahn/ and define the foundational runtime contracts described in the blueprint.

This PR should establish the following code areas:

• index.ts
• runtime/
• contracts/
• adapters/
• registry/
• selector/
• canvas/
• visualizers/
• themes/
• integration/

Only the minimum files needed for stable typing and later implementation should be added in this PR.

The contracts should include, at minimum:

Targets

• DahnTarget

Holon Access

• HolonViewAccess
• HolonViewContext

Descriptor Handles

• HolonTypeDescriptorHandle
• PropertyDescriptorHandle
• ValueTypeDescriptorHandle
• RelationshipDescriptorHandle
• DanceDescriptorHandle

Actions

• ActionNode

Visualizers

• VisualizerDefinition
• VisualizerContext
• VisualizerElement

Canvas

• CanvasApi
• VisualizerMountPlan
• CanvasDescriptor

Selector / Resolution Seam

• SelectorInput
• SelectorOutput
• SelectorFunction

For this PR, these selector contracts should be interpreted as the Phase 0 TS-side presentation-resolution seam, not as a claim that the entire long-term DAHN selector belongs in TypeScript.

The seam introduced here must preserve a future split between:

• Rust-side semantic recommendation
• TypeScript-side final runtime presentation resolution

Themes

• DahnTheme

Runtime

• DahnRuntime
• initial runtime error types or placeholders as needed

Architectural rules for this PR:

• contracts must remain transport-free
• DAHN contracts must not expose MAP wire types, IPC envelope types, or internal TS command-layer types
• contracts must remain framework-agnostic
• descriptor handles must be modeled as reference-backed accessor objects, not replicated TS-side descriptor state
• descriptor inheritance flattening must be assumed to come from Rust; TS must not model local inheritance-merging behavior
• relationship descriptor handles must preserve declared vs inverse kind
• action hierarchy contracts must support both actions and action groups, including nesting
• selector contracts must be future-compatible with Rust-side semantic recommendation feeding into TS-side resolution
• no behaviorful implementation should be introduced beyond what is needed to make the contracts compile cleanly

---

4.1 Implementation Notes

• Target modules:
  • host/ui/src/dahn/index.ts
  • host/ui/src/dahn/runtime/*
  • host/ui/src/dahn/contracts/*
• Expected new public seams:
  • the contract interfaces listed above
  • a minimal DahnRuntime interface
  • the initial TS-side selector/resolution seam
• Explicit non-goals for this PR:
  • no visualizer loader
  • no canvas mounting behavior
  • no SDK-backed adapter implementation
  • no selector implementation
  • no Angular route or component wiring
  • no real Web Component implementation
  • no Rust-side selector/recommendation behavior
• Verification path:
  • TypeScript compiles
  • DAHN contract modules can be imported cleanly
  • no contract imports from MAP SDK internal/*
  • no contract exports leak transport-layer types
  • selector contracts do not assume TypeScript owns all long-term selector logic

---

5. Scope and Impact (Required)

What does this impact?

• Adds the initial DAHN code footprint under host/ui/src/dahn/
• Establishes the code-level boundaries for later Phase 0 work
• Gives future PRs stable interfaces to implement against

This PR does not:

• render any holons
• mount any visualizers
• talk to the public SDK at runtime
• add DAHN routes/components
• implement selector, canvas, loader, adapter, or themes beyond contract definition
• introduce graph or collection behavior
• add editing behavior
• decide the full long-term selector placement beyond preserving the intended Rust/TS split

---

6. Testing Considerations (Required)

How will this enhancement be tested?

• Type-level or unit tests verifying contract modules can be imported without transport leakage
• Boundary tests verifying DAHN contracts do not import MAP SDK internal/*
• Public export checks for the DAHN module root, if applicable
• Basic compile/typecheck validation for the new DAHN module scaffold

Representative checks should verify:

• descriptor handles are modeled as accessor-based handles
• relationship descriptor handles preserve declared | inverse
• HolonViewContext includes ActionNode[]
• contracts remain framework-agnostic
• selector contracts preserve the future split between Rust-side semantic recommendation and TS-side runtime resolution

---

7. Definition of Done (Required)

When is this enhancement complete?

• host/ui/src/dahn/ exists with the initial package-shaped scaffold
• Core DAHN contract modules exist
• DahnRuntime interface exists
• Descriptor handles are defined as reference-backed accessor interfaces
• RelationshipDescriptorHandle preserves declared | inverse
• ActionNode supports action | group and nested children
• Selector contracts exist as the Phase 0 TS-side resolution seam
• Selector contracts preserve future compatibility with Rust-side semantic recommendation
• No DAHN contract leaks MAP wire/internal transport concerns
• DAHN modules compile/typecheck cleanly
• This PR introduces no premature runtime behavior beyond scaffolding and stable seams

---

Optional Details (Expand if needed)

8. Alternatives Considered

• Skip scaffolding and define contracts while implementing behavior
  Rejected: this would increase architectural drift and make the first behavior PRs harder to reason about.

• Put DAHN contracts directly into Angular app/component modules
  Rejected: DAHN should remain package-shaped and framework-agnostic in its core runtime.

• Materialize descriptor view objects instead of descriptor handles
  Rejected: authoritative state should remain in Rust; TS contracts should remain accessor-based and reference-backed.

• Define the selector seam as if the full selector permanently belongs in TypeScript
  Rejected: long-term DAHN architecture should preserve Rust-side semantic recommendation and TS-side presentation resolution.

9. Risks or Concerns

• over-scaffolding with too many unused files
• accidental import of Angular or MAP internal transport concerns into DAHN contracts
• naming churn if contracts are underspecified
• drifting from the updated descriptor-handle model
• accidentally baking full selector ownership into TS contracts

Mitigations:

• add only the files needed for stable seams
• keep contracts narrow and implementation-free
• preserve direct alignment with the DAHN Phase 0 spec and blueprint
• verify no MAP SDK internal imports leak into contracts
• keep the selector seam abstract and future-compatible with Rust-side recommendation

10. Additional Context

This PR corresponds to PR 1 in the DAHN Phase 0 implementation blueprint:

• scaffold and contracts first
• behavior later

It is intentionally low-risk and should make subsequent PRs more straightforward.