This repository was archived by the owner on Sep 23, 2026. It is now read-only.
Repository navigation
Extract reflection engine to devonian; depend on it instead - #58
Merged
Merged
Conversation
Per the decision recorded in ontola/atomic-plugins#6: reflector's bidirectional GitHub-issue reflection engine (origin markers, id-map, echo suppression, state reconciliation, comment reflection) has been generalized and extracted to devonian/reflect (localthought/devonian@0.6.0, not yet published). Reflector now depends on it instead of keeping its own copy. - src/reflect/sides.ts (new) builds devonian's ReflectionSide from reflector's own document/overlay/resource-model/OAuth machinery — the reflector-specific half devonian's generic engine doesn't know about. - src/reflect/engine.ts is gone; ReflectionEngine now comes from devonian/reflect. - marker.ts/id-map.ts/kv-store.ts are now thin wrappers/re-exports. marker.ts pins the `reflector` namespace so markers already embedded in production records keep parsing unchanged. - service.ts keeps its exact public API (fromConfig/start/stop/reflectNow/ status) but delegates the loop/status machinery to devonian's ReflectionRunner. __tests__/unit/reflect/engine.test.ts is rewritten as an integration test through reflector's real document/overlay pipeline driving devonian's real engine, per this project's stated preference for real-engine-plus-fake-HTTP tests over mocking internals; marker/id-map/service tests needed no changes. Verified (against a locally-linked devonian build, not committed) with tsc --noEmit, eslint, `pnpm test` (88 passing), and `pnpm test:harness` (9 passing). pnpm-lock.yaml is intentionally left as-is: devonian@0.6.0 isn't published yet, so `pnpm install` on this branch will correctly report the lockfile out of sync with package.json until that publish happens — this commit's dependency bump is meant to land after devonian's does. Claude-Session: https://claude.ai/code/session_01B2mbssSNDiu8GpKjaCFRn1 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
devonian@0.6.0's tarball shipped with a stale build/ missing src/reflect (fixed upstream in devonian's 0.6.1, which adds a prepublishOnly build step so this can't recur). Re-resolves the devonian@^0.6.0 dependency added in the previous commit against the real, now-published 0.6.1. Verified: tsc --noEmit, eslint, prettier --check, `pnpm test` (88 passing), `pnpm test:harness` (9 passing), and `pnpm build` all green against the actual npm-resolved package (no local link). Claude-Session: https://claude.ai/code/session_01B2mbssSNDiu8GpKjaCFRn1 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Reflector's generic bidirectional reflection engine (
ReflectionEngine, markers, id-map, state ledger) has been extracted into a newdevonianpackage and is now a dependency. Reflector continues to provide the same public API (ReflectionService) but now delegates the core reflection logic todevonianwhile retaining only the reflector-specific machinery: buildingReflectionSides from reflector's document/overlay/OAuth stack, and the background loop/on-demand trigger/status reporting.This resolves localthought/atomic-plugins#6 by enabling other plugins to reuse the same generic reflection engine without duplicating code.
Key Changes
src/reflect/engine.ts(deleted) —ReflectionEnginenow comes fromdevonian/reflect; the generic reflect-loop logic is no longer reflector-specific.src/reflect/sides.ts(new) —buildReflectionSide()encapsulates the reflector-specific half: builds adevonianReflectionSidefrom reflector's document/overlay/resource-model/OAuth machinery. Extracted from private methods that lived in the oldReflectionEngine(bind(),commentClient(),setState()).src/reflect/marker.ts— Now a thin wrapper arounddevonian/reflect's namespaced marker codec, pinned to thereflectornamespace so existing<!-- reflector:origin ... -->markers in production records continue to parse identically.src/reflect/id-map.ts&src/reflect/kv-store.ts— Re-exported fromdevonian/reflect(these were already fully generic).src/reflect/service.ts—ReflectionServiceretains its exact public shape (fromConfig/start/stop/reflectNow/status) but now:ReflectionSides viabuildReflectionSide().devonian'sReflectionEnginewithnamespace: 'reflector'.devonian'sReflectionRunner.package.json— Addeddevonian@^0.6.0as a dependency.__tests__/unit/reflect/engine.test.ts— Rewritten as an integration test through reflector's real document/overlay/resource-discovery pipeline drivingdevonian's engine. Unit coverage of the engine itself now lives indevonian's own test suite.Implementation Details
reflectorinsrc/reflect/marker.tsto ensure backward compatibility with already-embedded markers in production records.ReflectionServicecontinues to expose the same interface tosrc/server/app.tsandsrc/main.ts; no changes needed in callers.ReflectionSidethatdevonian's engine can drive, rather than testing the engine in isolation (which is nowdevonian's responsibility).https://claude.ai/code/session_01B2mbssSNDiu8GpKjaCFRn1