rhi

Appearance

Daily Log: 2026-07-11 ​

A sustained day of deep routing architecture work on fractal. The session spanned from late 2026-07-10 into 2026-07-11 and 2026-07-12 — primarily design refinement, coordinated refactoring across the monorepo, and systematic prior-art research into effect systems and multi-transport frameworks.

Sessions and Activity ​

fractal ​

One extended session (continuing from 2026-07-10) dominated the day. Organized into distinct phases:

Phase 1: Routing model refinement (01:49–06:16) Deep discussion on the graph/state-machine framing of dispatch. Settled key distinctions: trees as authoring convenience (not canonical), routers as directed graphs, edges as Request → (Request', Bindings) | NoMatch, and combinators as first-class expressions (DU variants, not closures). Two agent tasks completed design-doc updates reflecting this evolution.

Phase 2: Core refactoring (06:16–13:06) Coordinated refactor across the fractal monorepo, removing six pending items:

  • Removed dead dispatch() from core
  • Reshaped ParamNode → fallback field (children as flat record, fallback as {name, subtree})
  • Replaced effectiveTags walk with mapNodes visitor; tags now read from leaf's own meta, not inherited
  • Retired named keys (verb, segment, when, legacyPath) and replaced with DU-ified HttpDirective[] and DispatchMarker variants
  • Direct tree-walk dispatch via candidatesForUrl replacing buildRoutes/Route[]
  • Updated all consumers: packages/client, packages/cli, packages/codegen, examples/library-api
  • Verification: 233 tests across 8 workspaces pass, no failures

This task was substantial — ~1.77M milliseconds (~30 minutes of compute) — and landed with commit 7d50b9e.

Phase 3: Prior-art research (08:44–09:36) Four parallel agents researched effect systems and multi-transport routing frameworks to inform the cross-cutting/caller-context layer design:

  • Effect-TS: Layer/Service pattern, context flow via type-level R union, middleware as service transformations, multi-transport via Layers
  • tRPC: Router/procedure definition, chainable .use() middleware with context merging, transport adapters, inspectable router definitions
  • Hono: Koa-style onion middleware, generic context types, multi-runtime via Fetch API, decoupled OpenAPI registry
  • Elysia: Method-chained routes, schema-first (TypeBox/Standard Schema), type-level context accumulation via Derive/Resolve, four-tier lifecycle phases

Findings written to docs/design/prior-art/{effect,trpc,hono,elysia}.md. Key insight: all systems cleanly separate transport surfaces from handler definitions via either Layers (Effect), Adapters (tRPC), or schema merging (Elysia/Hono).

Phase 4: Unsettled questions (09:36–10:25) Returned to synthesis. Clarified that fractal solves the surface-projection half (one def → HTTP + CLI + MCP) but does not touch caller-context or cross-cutting concerns. Those remain orthogonal design problems requiring a separate solution. Discussion on whether TypeScript build-time metaprogramming (procedures as expressions) is sufficient without proc macros — deferred to next phase with recommendation to write settled items and handoff.

Token Usage ​

ProjectSessionsCompute Time (est.)
fractal1~2.1M ms (large agent task + parallel research agents)

Observations ​

  1. Major refactor committed: The coordinated removal of six pending items in fractal's core reduced technical debt in node shapes, dispatch walks, and consumer coupling. All tests pass.

  2. Architecture converged enough to research: Prior-art review was comprehensive and well-timed — the team now has concrete examples of how Effect, tRPC, Hono, and Elysia handle composition, middleware, and multi-transport, informing the remaining design layer.

  3. Caller-context still open: The key unsettled question is how to inject actor/IP/session/timestamp across surfaces without monolithic wiring. The research suggests several approaches (Effect Layers, tRPC middleware chains, Hono context merging) — next phase should evaluate which pattern fits fractal's priorities.

  4. TypeScript question flagged: Whether build-step macro-like generation (procedures as data structures) vs. reflection-based discovery is the right approach. No blocking decision yet.

Projects Touched ​

  • fractal — routing model, coordinated refactoring (6 pending removals), prior-art research into effect systems and multi-transport frameworks.

Next Steps (inferred) ​

  1. Settle the annotation/caller-context layer: Decide between monolithic dispatch core, per-surface adapters, or Layers-style dependency injection. Evaluate tradeoffs.
  2. TypeScript procedural generation: Finalize whether build-step code gen or runtime reflection for procedure introspection.
  3. Handoff: Document settled items and open threads; prepare next session with focus areas.