Extract reflection engine from reflector into devonian

[michielbdejong]

Summary

Extracts the bidirectional reflection engine from localthought/reflector into devonian as a reusable, platform-agnostic component. This enables other hosts (reflector itself, bridges, and future integrations) to share the same battle-tested reflection logic instead of maintaining separate copies.

Key Changes

• src/reflect/engine.ts — Core ReflectionEngine class that orchestrates bidirectional synchronization of records between two syncables-backed systems:

  • Issue creation with echo suppression (via origin markers) and idempotency (via id-map + destination marker scan)
  • Open/closed state reconciliation using a persisted ledger to detect which side changed
  • Comment reflection under counterpart issues
  • Configurable direction (bidirectional or a-to-b), retry behavior, and drain timeout

• src/reflect/marker.ts — Origin marker codec for embedding/parsing hidden HTML comments that link reflected copies back to their originals:

  • embedMarker() / parseMarker() / stripMarker() / hasMarker() / renderMarker()
  • Namespaced tags (<!-- <namespace>:origin ... -->) to avoid collisions
  • Percent-encoded payload to prevent early comment closure

• src/reflect/id-map.ts — Persisted correspondence between originals and reflected copies:

  • InMemoryIdMap for in-memory storage
  • FileIdMap for JSON-file-backed persistence
  • Symmetric, kind-scoped (issue/comment) linking

• src/reflect/kv-store.ts — Tiny persisted string→string store for reflection metadata:

  • InMemoryKvStore for in-memory storage
  • FileKvStore for JSON-file-backed persistence
  • Used to track last-agreed state per reflected pair

• src/reflect/runner.ts — Background loop + on-demand trigger wrapper:

  • ReflectionRunner serializes concurrent reflectNow() calls so they never overlap
  • Runs immediately on start(), then repeats on a configurable interval
  • Tracks last run summary and errors for status endpoints

• src/reflect/index.ts — Public API barrel export

• Comprehensive test suite (__tests__/unit/reflect/):

  • engine.test.ts — 13 tests covering issue creation, state reflection, comment reflection, bidirectionality, idempotency, and error handling
  • marker.test.ts — 10 tests for the origin marker codec
  • id-map.test.ts — Tests for in-memory and file-backed id-map
  • kv-store.test.ts — Tests for in-memory and file-backed kv-store
  • runner.test.ts — Tests for background loop serialization and interval behavior

• Documentation:

  • AI session log (docs/ai-logs/sessions/2026-09-21-...md) documenting the extraction decision and implementation
  • AI disclosure infrastructure (docs/ai-logs/README.md, pending-historical-sessions.md) per NLnet policy

Notable Implementation Details

• Echo suppression: Reflected copies carry an origin marker naming their source system; a copy is never reflected onward by checking the marker before reflection.
• Idempotency: Combines id-map lookup with a destination marker scan, so a lost id-map doesn't cause duplicate reflections.
• State reconciliation: Uses a persisted ledger of last-agreed state to detect which side changed, avoiding bouncing when both sides diverge.
• Platform agnostic: ReflectionEngine has no notion of OpenAPI, overlays, or auth — a host provides two ReflectionSide objects already bound to syncables clients, keeping the engine portable across any two compatible endpoints.
• Serialized concurrency: ReflectionRunner ensures manual triggers and scheduled ticks never overlap via a promise chain.

Version

Bumped to 0.6.0 and added ./reflect export to `package

https://claude.ai/code/session_01B2mbssSNDiu8GpKjaCFRn1