Dragan Spiridonov 6236a2cdc7 feat(kernel): kernel-side dream cycles + hooks-as-producers boundary (ADR-094, #488 Phase 2) ...

Moves dream cycles out of hook subprocesses into the long-lived kernel
process via the DreamScheduler that already existed but was never wired.
Single cutover, no feature flag — per maintainer decision on ADR-094.

Why this matters
================

Before this commit, every ~20 Edit/Write tool uses triggered a dream cycle
inside a short-lived `npx aqe hooks post-edit` subprocess. The cycle held
a SQLite write transaction for up to 10 seconds while the kernel-owning
MCP server, other hook subprocesses, and user MCP tool calls queued
behind it. stderr from the cycle was consumed by Claude Code's hook
reader and lost from operator visibility. Cold DreamEngine init paid
every ~20 edits.

Now the kernel's `QEKernelImpl.initialize()` boots a `DreamScheduler`
that runs cycles on its own cadence inside the long-lived process. Hook
subprocesses keep only `incrementDreamExperience` (a counter bump that
returns in ~50ms). Operators see `aqe learning loop-health` report the
`dreamScheduler` component as live within one tick.

What landed
===========

src/kernel/kernel.ts
  - new private `_dreamScheduler?: DreamScheduler`
  - new config flag `enableDreamScheduler` (default `true`, mirrors
    `enableExperienceBridge`)
  - initialize() constructs DreamEngine + DreamScheduler after the
    bridge starts, wraps in try/catch (best-effort), failure logs a
    warning and continues (kernel boot never blocks on this)
  - dispose() stops the scheduler BEFORE bus/memory cleanup so a dream
    in-progress doesn't write to a disposed backend

src/learning/dream/dream-scheduler.ts
  - executeDream() now records loop-health on every tick (success or
    failure) via the helper from #488 Phase 1 B.2. Operators see
    `learning:loop-health.components.dreamScheduler.successesSinceBoot`
    grow on each cycle.

src/cli/commands/hooks-handlers/editing-hooks.ts
src/cli/commands/hooks-handlers/task-hooks.ts
  - dropped `checkAndTriggerDream` import + call
  - kept `incrementDreamExperience` (the counter is the producer-side
    signal the kernel scheduler reads)
  - JSON output now emits `dreamTriggered: false, dreamReason:
    'deferred-to-kernel'` so operator scripts grepping the field see
    *where* the cycle actually runs

src/cli/commands/hooks-handlers/hooks-shared.ts
  - removed the `checkAndTriggerDream` re-export. The function itself
    is still defined in hooks-dream-learning.ts and exported there for
    direct test access and the documented rollback path.

tests/unit/architecture/hooks-boundary.test.ts (NEW)
  - greps `src/cli/commands/hooks-handlers/` for forbidden patterns:
    imports from `src/learning/dream/` and references to
    `checkAndTriggerDream`. Skips comment lines so explanatory mentions
    don't false-positive. `hooks-dream-learning.ts` is in `allowedFiles`
    since it DEFINES the function.
  - This is the enforcement mechanism for the boundary contract. A
    contributor accidentally re-adding heavy hook-side work gets a
    clear CI failure pointing them at ADR-094.

tests/unit/kernel/dream-scheduler-wiring.test.ts (NEW)
  - asserts `enableDreamScheduler` default, opt-out path, init+dispose
    cleanliness with and without the scheduler, idempotent dispose

tests/unit/cli/commands/post-edit-dream-trigger.test.ts (REWRITTEN)
  - was asserting checkAndTriggerDream was called from post-edit (the
    #480 fix). That contract is now wrong — the kernel is the only
    place that triggers dreams.
  - now asserts: counter is bumped (the kernel reads it), no inline
    cycle trigger, JSON emits `deferred-to-kernel`, hook stays robust
    when the memory backend throws.

docs/implementation/adrs/ADR-094-kernel-side-dream-cycles.md
  - status: Implemented
  - migration section replaced with the single-cutover rationale and
    a documented 4-line rollback path

583/583 tests pass across CLI, workers, bridge, learning, init/phases,
architecture, and kernel suites. Build clean.

Boundary contract (now enforced in CI)
======================================

Hook subprocesses MUST NOT do work that exceeds ~100ms. Acceptable
hook-side work: producer SQLite writes, counter increments, in-memory
routing lookups. Unacceptable: DreamEngine init, multi-second SQLite
transactions, anything that depends on long-lived state.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-15 14:25:45 +00:00

..

hooks-boundary.test.ts

feat(kernel): kernel-side dream cycles + hooks-as-producers boundary (ADR-094, #488 Phase 2)

2026-05-15 14:25:45 +00:00