@agencer/reverie-loop 0.1.0-alpha.0 → 0.1.0

package/CHANGELOG.md

@@ -1,71 +1,150 @@
 # Changelog
 
-All notable changes to `@agencer/reverie-loop`.
-
-## 0.1.0-alpha.0
-
-Initial alpha release. Extracted from the agencer-ox
-`packages/server/src/services/reverie-logger.ts` source.
-
-Shipped:
-
-- `ReverieLogger` class: synchronous, append-only JSONL writer with a
-  single `logDir` and two output files (`reveries.jsonl`,
-  `whisper-results.jsonl`), both filenames overridable.
-  Constructor validates `logDir` (required, non-empty) and both
-  filenames (plain basename, no path separators). Methods:
-  `logReverie`, `logWhisperResult`, `readReverieLog`,
-  `readWhisperResultLog`, `close`.
-- Module-level compat API: `initReverieLogger`, `logReverie`,
-  `logWhisperResult`, `readReverieLog`, `readWhisperResultLog`,
-  `resetReverieLoggerSingletonForTests`. Function signatures match
-  the extracted source so callsite migration in agencer-ox is a
-  one-line import change. Pre-init calls are silent no-ops.
-  `read*Log(logDir)` with an explicit directory honors the active
-  singleton's custom filenames when set (internal consistency with
-  writes).
-- Types: `ReverieEntry`, `WhisperResultEntry`, `ReverieFailureReason`,
-  `ReverieLoggerConfig`.
-- Constants: `DEFAULT_REVERIE_FILENAME`,
-  `DEFAULT_WHISPER_RESULT_FILENAME`,
-  `WHISPER_RESULT_USER_MESSAGE_MAX_LENGTH` (200).
-- 24 unit tests (logger / compat) covering JSONL format for both
-  files, append semantics, dual-file separation, 200-char
-  user_message truncation for whisper results, custom filenames,
-  nested-dir auto-create, torn-line resilience, both-filename path
-  traversal guards, init-time validation, and the NEVER-throws
-  runtime discipline for unwritable disks. First tests this code
-  has ever shipped with: the extracted source had zero coverage.
-
-Hardened vs the extracted source:
-
-- **Lenient `read*Log`.** One bad line no longer erases the entire
-  diagnostic view. Per-line `JSON.parse` with torn-line skip.
-- **Init-time config validation.** Missing/empty `logDir` and
-  path-traversal filenames throw at construction instead of being
-  silently swallowed by the runtime catch-all. The NEVER-throws
-  discipline is intentionally scoped to the runtime path, not the
-  config path.
-- **Filename path-traversal guards.** Both `reverieFilename` and
-  `whisperResultFilename` must be plain basenames so env-driven or
-  attacker-influenced config cannot redirect writes outside `logDir`.
-
-Breaking changes vs the extracted source:
-
-- The `~/.operative-x/training-data` default path is removed.
-  `logDir` is now a required config field. OX, O2, and future
-  consumers each wire their own path at startup (Hot-Swappable
-  Providers principle).
-
-Known limitations (tracked for alpha.1):
-
-- Single-process write safety. `appendFileSync` relies on `O_APPEND`
-  atomicity, which only guarantees atomic writes under `PIPE_BUF`
-  (~4 KB). Large exchanges from concurrent writers may interleave.
-- Synchronous I/O on the caller's thread. A wedged disk or slow
-  network mount blocks the event loop. Async variant tracked for
-  alpha.1.
-- `read*Log` reads the whole file — diagnostic only, not for large
-  production logs.
-
-Apache-2.0 license.
+All notable changes to `@agencer/reverie-loop` will be documented in this file.
+
+## [0.1.0] - 2026-05-14
+
+Initial release. Reverie Loop — Strange Loop training-signal capture for AI agents — extracted from agencer-ox into a portable Lego with zero `@agencer/*` runtime dependencies and zero `@anthropic-ai/sdk` runtime coupling on the public API.
+
+### Public API
+
+Six Layer-A interfaces in `contracts.ts`:
+- `LoggerLike` (pino-compatible)
+- `UsageMeter` (recordCall + getUserUsage)
+- `ReverieUserContext` (userId + sessionId)
+- `CostCalculator` (function signature)
+- `ReverieInferenceRequest` + `ReverieInferenceResponse` + `ReverieInferenceProvider` (Anthropic-shaped but provider-agnostic)
+
+Two factory + class entry points:
+- `createReverieLogger({ reveriesPath, whisperResultsPath })` returns `{ logReverie, logWhisperResult }`. NEVER-throws disk writers.
+- `new ReverieTrigger({ meter, logger, costCalculator, inferenceProvider?, reveriePairsPath, reverieSafetyFlagsPath, legacyReverieLogPath, idleMs?, dailyBudgetUsd?, forceMock? })`. Session-end orchestrator with `markActive`, `endCohort`, `cancelAll`.
+
+Plus orchestrator entry points consumed by ReverieTrigger and exposed for tests:
+- `triggerReverie(sessionId, getHistory, deps)`
+- `executeReverie(sessionId, history, deps)` (branches on `deps.forceMock`)
+- `executeReflection(args)` (single Opus reflection)
+- `splitResultByCategory(result, reveriePairsPath)`
+- `appendReverieResult(path, result, logger)`
+- `appendSafetyFlag(path, result, logger)`
+- `validateCorrectionPairs(raw)`
+- `mapErrorKind(err)` (structural duck-typing on `.code`)
+- `getLastReverie() / getLastReverieReal() / cancelAllReveries()` (state accessors + test teardown)
+- `REVERIE_PAIR_SCHEMA_VERSION = "reverie-pair-v1"`
+- `REVERIE_SAFETY_FLAG_SCHEMA_VERSION = "reverie-safety-flag-v1"`
+- `_REFLECTION_SYSTEM_PROMPT_FOR_TEST` (verbatim equality test access)
+
+### Package shape
+
+- `dependencies`: `{}` (zero `@agencer/*`, zero `@anthropic-ai/sdk`)
+- `peerDependencies`: `pino: ">=8.0.0"` (required), `@agencer/usage-accountant: "0.1.0"` (optional via `peerDependenciesMeta`)
+- `devDependencies`: `@agencer/usage-accountant`, `@anthropic-ai/sdk`, `better-sqlite3` (for integration tests only)
+
+The Greg test invariant — `dependencies: {}` plus `ls node_modules/@agencer/` showing only `reverie-loop` after a scratch-dir install — is codified in `PUBLISH.md`.
+
+## Migration guide
+
+For external consumers (currently only agencer-ox) integrating `@agencer/reverie-loop`:
+
+### From pre-Leg-G agencer-ox internal paths
+
+Pre-Leg-G call sites lived under `packages/server/src/{services,brain}/reverie-*.ts`. Post-Leg-G, the canonical home is `@agencer/reverie-loop`. The agencer-ox composition root (and any other consumer) imports from the Lego barrel.
+
+| Pre-Leg-G path | Post-Leg-G import |
+|---|---|
+| `services/reverie-logger.ts: logReverie, logWhisperResult` | `@agencer/reverie-loop: createReverieLogger(opts).logReverie / .logWhisperResult` |
+| `services/reverie-loop.ts: triggerReverie, executeReverie, ...` | `@agencer/reverie-loop: triggerReverie / executeReverie / ...` |
+| `services/reverie-loop.ts: ReverieResult, ReverieObservation (legacy aliases)` | `@agencer/reverie-loop: ReverieResultLegacy / ReverieObservation` |
+| `brain/reverie-pair-sink.ts: splitResultByCategory, appendReverieResult, appendSafetyFlag` | `@agencer/reverie-loop: splitResultByCategory / appendReverieResult / appendSafetyFlag` |
+| `brain/reverie-opus-client.ts: executeReflection, schema versions, types` | `@agencer/reverie-loop: executeReflection / REVERIE_PAIR_SCHEMA_VERSION / ...` |
+| `brain/reverie-trigger.ts: ReverieTrigger` | `@agencer/reverie-loop: ReverieTrigger` |
+
+### Constructor field renames
+
+Pre-Leg-G `ReverieTrigger`:
+```ts
+new ReverieTrigger({
+  accountant,      // UsageAccountant
+  logger,
+  anthropic,       // AnthropicProvider, optional
+  idleMs?,
+  dailyBudgetUsd?,
+});
+```
+
+Post-Leg-G:
+```ts
+new ReverieTrigger({
+  meter,                     // UsageMeter (structurally compat with UsageAccountant)
+  logger,                    // LoggerLike (structurally compat with pino.Logger)
+  costCalculator,            // CostCalculator (calculateCost from @agencer/usage-accountant works)
+  inferenceProvider?,        // ReverieInferenceProvider (structurally compat with AnthropicProvider)
+  reveriePairsPath,          // absolute path (REQUIRED; composition root resolves from os.homedir())
+  reverieSafetyFlagsPath,    // absolute path (REQUIRED)
+  legacyReverieLogPath,      // absolute path (REQUIRED)
+  forceMock?: boolean,       // replaces env-toggle MOCK_REVERIE
+  idleMs?,
+  dailyBudgetUsd?,
+});
+```
+
+Two structural-type widenings cross the Lego boundary (compile-time-only brands; runtime identical):
+- `family: ModelFamily` (server) → `family: string` (Lego) — the Lego only emits `"opus"`
+- `component: UsageComponentType` (server) → `component: string` (Lego) — the Lego only emits canonical `reverie.*` strings
+
+Consumers passing concrete `UsageAccountant` / `AnthropicProvider` instances need `as unknown as` casts at the call site OR a small adapter at the composition root. The agencer-ox composition root uses the inline-cast pattern.
+
+### Env-toggle removal: MOCK_REVERIE → forceMock
+
+Pre-Leg-G code branched on `process.env["MOCK_REVERIE"] === "true"` inside `reverie-loop.ts:178`. The Lego no longer reads env. Consumers thread the equivalent via `deps.forceMock`:
+
+```ts
+const forceMock = process.env["MOCK_REVERIE"] === "true";
+new ReverieTrigger({ ..., forceMock });
+// or per-call:
+executeReverie(sid, history, { ..., forceMock });
+```
+
+The composition root reads the env once at startup and threads `forceMock` into every deps object thereafter.
+
+### OperativeError → structural duck-typing
+
+Pre-Leg-G `mapErrorKind` used `if (err instanceof OperativeError) { switch (err.code) {...} }`. The Lego replaced this with structural duck-typing on `.code`:
+
+```ts
+if (err && typeof err === "object" && "code" in err && typeof (err as { code?: unknown }).code === "string") {
+  switch ((err as { code: string }).code) { ... }
+}
+```
+
+Consumers' `OperativeError` instances (and any other `Error` subclass with a string `.code` field) classify identically. Plain `Error` instances with no `.code` fall through to `"unknown"`, same as the pre-Leg-G non-OperativeError throws.
+
+### Path config: agencer-ox composition root pattern
+
+The composition root resolves the three jsonl paths from `os.homedir()` and threads them into `ReverieTriggerOptions`:
+
+```ts
+const reverieLogDir = path.join(
+  process.env["HOME"] || os.homedir(),
+  ".operative-x",
+  "logs",
+);
+const reverieTrainingDir = path.join(
+  process.env["HOME"] || os.homedir(),
+  ".operative-x",
+  "training-data",
+);
+
+new ReverieTrigger({
+  ...,
+  reveriePairsPath: path.join(reverieLogDir, "reverie-pairs.jsonl"),
+  reverieSafetyFlagsPath: path.join(reverieLogDir, "reverie-safety-flags.jsonl"),
+  legacyReverieLogPath: path.join(reverieLogDir, "reverie-log.jsonl"),
+});
+
+const { logReverie, logWhisperResult } = createReverieLogger({
+  reveriesPath: path.join(reverieTrainingDir, "reveries.jsonl"),
+  whisperResultsPath: path.join(reverieTrainingDir, "whisper-results.jsonl"),
+});
+```
+
+Tests that mutate `process.env["HOME"]` between calls (e.g., per-test tmpDir) must do so before invoking the composition root. The Lego itself never reads HOME, so post-construct mutation is invisible to it.

package/LICENSE

@@ -1,202 +1,11 @@
+Copyright (c) 2026 Agencer, Inc. All rights reserved.
 
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
+This software and associated documentation files (the "Software") are the
+proprietary property of Agencer, Inc. and are licensed for use only under the
+terms of a written license agreement between Agencer, Inc. and the licensee.
 
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+Unauthorized use, reproduction, modification, distribution, or disclosure of
+the Software, in whole or in part, is strictly prohibited.
 
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright [yyyy] [name of copyright owner]
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+This LICENSE applies to all files in this package directory unless explicitly
+stated otherwise.

package/README.md

@@ -1,82 +1,144 @@
 # @agencer/reverie-loop
 
-Append-only JSONL writer for reverie training signals. One of three signal sources for the Agencer Learning Loop (alongside `session-logger` and `whisper-router`).
+Reverie Loop. Strange Loop training-signal capture for AI agents. Post-session Opus reflection produces correction pairs, split into behavioral and safety JSONL files for fine-tune corpus generation. Portable Lego with zero `@agencer/*` runtime dependencies and zero `@anthropic-ai/sdk` runtime coupling on the public API.
 
-Extracted from agencer-ox. Path-configurable so every consumer (OX, O2, future Agencer master) owns its own filesystem namespace without forking.
+## Status
 
-## What ships
+v0.1.0. Extraction arc complete (Leg G-1 through G-6). Published to npm under `@agencer/reverie-loop`; consumable by agencer-ox, future operatives, and external integrators.
 
-- **`ReverieLogger`** class: `logReverie`, `logWhisperResult`, `readReverieLog`, `readWhisperResultLog`, `close`.
-- **Module compat API**: `initReverieLogger`, `logReverie`, `logWhisperResult`, `readReverieLog`, `readWhisperResultLog`, `resetReverieLoggerSingletonForTests` — drop-in for the legacy `services/reverie-logger.ts` callsites.
-- **Types**: `ReverieEntry`, `WhisperResultEntry`, `ReverieFailureReason`, `ReverieLoggerConfig`.
+## What it does
 
-## Two files, one logger
+Reverie fires at session end (last WebSocket disconnect or 5-minute idle) and runs a single Anthropic Opus reflection over the conversation history. The reflection produces correction pairs across six categories (`factual_error | tone_miss | tool_misuse | verbosity | safety_concern | other`). Pairs split into a behavioral JSONL log (training corpus for the next fine-tune) and a safety JSONL log (constitutional corpus, never co-mingled per Day 159 Betley amendment).
 
-Writes are split across two JSONL files inside the configured `logDir`:
-
-- `reveries.jsonl` — whisper-failure deltas. Each entry captures `user_message`, `mini_response` (whisper output), `opus_response` (the rescue), `failure_reason` (`weak_response | user_corrected | timeout | error`), `whisper_model_id`, ISO-8601 `timestamp`. This is the training signal for whisper-model fine-tuning.
-- `whisper-results.jsonl` — whisper model outcomes for monitoring. Each entry captures `outcome` (`success | failure`), `model_id`, `user_message` (truncated to 200 chars), `response_length`, `timestamp`.
-
-Both filenames are overridable via `reverieFilename` / `whisperResultFilename`.
-
-## NEVER-throws discipline (runtime only)
-
-Runtime methods swallow write and parse errors internally — failed `mkdir`, read-only disk, corrupt line, none propagate into the voice pipeline.
-
-The **constructor is the exception**: invalid config (`logDir` empty/missing, either filename containing a path separator or `..`) throws synchronously. Misconfiguration is a programmer bug, silencing it hides deploy problems.
+```
+Session ends (WS disconnect / idle)
+  -> ReverieTrigger.endCohort  [debounced 10s; budget-guarded $1/day per user]
+     -> executeReflection      [Opus inference via injected ReverieInferenceProvider]
+        -> splitResultByCategory  [behavioral / safety / mixed partitions]
+           -> appendReverieResult  -> ~/.operative-x/logs/reverie-pairs.jsonl
+           -> appendSafetyFlag     -> ~/.operative-x/logs/reverie-safety-flags.jsonl
+```
 
-`readReverieLog` / `readWhisperResultLog` are lenient: torn/corrupt lines are skipped, valid records around them are returned. One bad tail line after a crash does not erase the log.
+## Install
 
-## Known limitations (alpha.0)
+```bash
+npm install @agencer/reverie-loop pino
+```
 
-- **Single-process, single-writer.** `appendFileSync` relies on POSIX `O_APPEND` atomicity, which only guarantees atomic writes under `PIPE_BUF` (~4 KB). Multi-process writers on the same file may interleave on larger exchanges.
-- **Synchronous I/O.** `log*` blocks the event loop for the duration of the syscalls. Sub-millisecond on local disk, dangerous on a wedged network mount. Async variant tracked for alpha.1.
-- **`read*Log` reads the whole file.** Tests and diagnostics only. For large logs, stream-read the JSONL directly.
-- **`user_message` truncation for whisper results is pre-write.** Matches the extracted source semantics so the learning-loop `sync.py` ingestion shape stays stable.
+`pino` is a required peer. If you already use `UsageAccountant` from `@agencer/usage-accountant`, the optional `@agencer/usage-accountant` peer satisfies the `UsageMeter` interface with type alignment.
 
 ## Usage
 
-### OX-style consumer (compat API)
-
 ```ts
-import { homedir } from "node:os";
-import path from "node:path";
 import {
-  initReverieLogger,
-  logReverie,
-  logWhisperResult,
+  ReverieTrigger,
+  createReverieLogger,
 } from "@agencer/reverie-loop";
-
-initReverieLogger({
-  logDir: path.join(homedir(), ".operative-x", "training-data"),
+import { calculateCost, UsageAccountant } from "@agencer/usage-accountant";
+import os from "node:os";
+import path from "node:path";
+import pino from "pino";
+
+const logger = pino();
+const accountant = new UsageAccountant(db, logger);
+
+const logDir = path.join(os.homedir(), ".operative-x", "logs");
+const trainingDir = path.join(os.homedir(), ".operative-x", "training-data");
+
+const reverieTrigger = new ReverieTrigger({
+  meter: accountant,                 // satisfies UsageMeter structurally
+  logger,
+  costCalculator: calculateCost,     // signature-compatible
+  inferenceProvider: anthropicProvider, // your AnthropicProvider adapter
+  reveriePairsPath: path.join(logDir, "reverie-pairs.jsonl"),
+  reverieSafetyFlagsPath: path.join(logDir, "reverie-safety-flags.jsonl"),
+  legacyReverieLogPath: path.join(logDir, "reverie-log.jsonl"),
+  forceMock: process.env["MOCK_REVERIE"] === "true",
 });
 
-logReverie(userText, miniResponse, opusResponse, "weak_response", modelId);
-logWhisperResult("success", modelId, userText, assistantResponse);
-```
+// On every routing decision:
+reverieTrigger.markActive(userContext, () => conversationHistory);
 
-### O2-style consumer (class API, custom filenames)
+// On last WebSocket disconnect:
+reverieTrigger.endCohort();
 
-```ts
-import path from "node:path";
-import { ReverieLogger } from "@agencer/reverie-loop";
-
-const logger = new ReverieLogger({
-  logDir: path.join(process.cwd(), "data", "training"),
-  reverieFilename: "o2-reveries.jsonl",
-  whisperResultFilename: "o2-whisper-outcomes.jsonl",
+// Separate from the orchestrator: factory-bound disk loggers for the
+// whisper-failure -> Opus-takeover training-signal capture.
+const { logReverie, logWhisperResult } = createReverieLogger({
+  reveriesPath: path.join(trainingDir, "reveries.jsonl"),
+  whisperResultsPath: path.join(trainingDir, "whisper-results.jsonl"),
 });
-
-logger.logReverie(u, m, o, "timeout", modelId);
 ```
 
-## What this Lego deliberately does NOT do
-
-- **No rescue-decision logic.** *When* to fire a reverie — weak-response thresholds, timeouts, user-correction detection — lives in the caller. This Lego is an append-only writer.
-- **No anonymization.** PII stripping belongs downstream in sync, not at write time.
-- **No hardcoded path.** `config.logDir` is required; the legacy `~/.operative-x/training-data` default is removed.
-- **No buffering.** `close()` is a no-op today, reserved for future fd pooling.
+## Public API
+
+| Export | Kind | Description |
+|---|---|---|
+| `ReverieTrigger` | class | Session-end orchestrator. `markActive` + `endCohort` + `cancelAll`. |
+| `createReverieLogger(opts)` | factory | Returns `{ logReverie, logWhisperResult }` bound to absolute paths. |
+| `executeReflection(args)` | function | Single Opus reflection call. Returns `ReverieResult`. NEVER throws. |
+| `validateCorrectionPairs(raw)` | function | Hand-rolled validator for the 6-category enum + pair shape. |
+| `mapErrorKind(err)` | function | Structural duck-typing on `.code` for the auth/network/etc taxonomy. |
+| `splitResultByCategory(result, reveriePairsPath)` | function | Behavioral vs safety partitioning. |
+| `appendReverieResult(path, result, logger)` | function | JSONL writer for behavioral records. NEVER throws. |
+| `appendSafetyFlag(path, result, logger)` | function | JSONL writer for safety records. NEVER throws. |
+| `triggerReverie(sid, getHistory, deps)` | function | 10s-debounced trigger. |
+| `executeReverie(sid, history, deps)` | function | Immediate execution; branches on `deps.forceMock`. |
+| `getLastReverie() / getLastReverieReal()` | function | Test-scaffolding state accessors. |
+| `cancelAllReveries()` | function | Clears all pending debounce timers. |
+| `REVERIE_PAIR_SCHEMA_VERSION` | const | `"reverie-pair-v1"` |
+| `REVERIE_SAFETY_FLAG_SCHEMA_VERSION` | const | `"reverie-safety-flag-v1"` |
+| 6 contracts | types | `LoggerLike`, `UsageMeter`, `ReverieUserContext`, `CostCalculator`, `ReverieInferenceRequest`, `ReverieInferenceResponse`, `ReverieInferenceProvider` |
+| `ReverieDeps`, `ReverieTriggerOptions` | types | Per-invocation deps + constructor opts |
+| Plus types for `ReverieResult`, `CorrectionPair`, `ReverieCategory`, `ReverieErrorKind`, etc. |
+
+## Sub-meter component vocabulary
+
+The Lego emits six observable sub-meter strings via the injected `UsageMeter`. Downstream dashboards filter by these names:
+
+| Component | When | Cost |
+|---|---|---|
+| `reverie.opus.reflection` | Real Opus call returns (Law 16 paid record) | injected `costCalculator` result |
+| `reverie.trigger.opus.attempt` | A cohort fired and intended to invoke reflection | 0 |
+| `reverie.trigger.disconnect` | Cohort fired from `endCohort` | 0 |
+| `reverie.trigger.idle_timer` | Cohort fired from 5-minute idle | 0 |
+| `reverie.skipped.budget_exceeded` | Daily $1.00 cost guard tripped | 0 |
+| `reverie.skipped.deduped` | Same cohort fired twice (defensive) | 0 |
+
+These strings are part of the public observable contract. They are preserved verbatim across leg refactors.
+
+## Configuration
+
+| Option | Required | Default | Purpose |
+|---|---|---|---|
+| `meter` | yes | — | Metered ledger (UsageMeter) |
+| `logger` | yes | — | pino-compatible LoggerLike |
+| `costCalculator` | yes | — | Cost USD calculator |
+| `inferenceProvider` | no | none (forces mock path) | Anthropic adapter |
+| `reveriePairsPath` | yes | — | Absolute path to behavioral JSONL |
+| `reverieSafetyFlagsPath` | yes | — | Absolute path to safety JSONL |
+| `legacyReverieLogPath` | yes | — | Absolute path to legacy mock JSONL |
+| `idleMs` | no | 300_000 | Idle window |
+| `dailyBudgetUsd` | no | 1.0 | Per-user daily cost ceiling |
+| `forceMock` | no | false | Force legacy mock path |
+
+## Sacred constraints
+
+Per Canon Law 8, the following invariants are sacred. Changes require the explicit Reverie Loop change protocol (test harness run + verification + operator sign-off):
+
+- **No `process.env` reads inside the Lego.** The Lego accepts resolved absolute paths via `ReverieDeps` / `ReverieTriggerOptions` / `createReverieLogger` options. The consumer composition root owns env parsing. Test scaffolding that mutates `process.env["HOME"]` resolves paths at the SHIM/composition root, never inside the Lego.
+- **No `os.homedir()` reads inside the Lego.** Same rule, same reason. Path resolution is the consumer's job.
+- **NEVER-throws on every public function.** Reverie is fire-and-forget session-end observability; a throw would surface as `uncaughtException` at the WebSocket teardown boundary or break the voice handler. Every public function wraps fallible work in try/catch and returns a safe default on error.
+- **Sub-meter component name strings are observable contract.** The six `reverie.*` strings are emitted verbatim to the injected `UsageMeter`. Downstream dashboards filter on these exact names. Renames are breaking changes.
+- **REFLECTION_SYSTEM_PROMPT is locked text.** The Day 159 Betley emergent-misalignment safety amendment defined the 6-category enum and the `safety_concern` definition verbatim. Any change to the system prompt requires re-running the eval suite + operator sign-off + a new schema version bump.
+- **Schema version strings are immutable.** `reverie-pair-v1` and `reverie-safety-flag-v1` are inscribed on every JSONL row. `ox-data-factory` and the constitutional pipeline both filter by these strings. Bumping the schema is a breaking change to the data contract.
+- **C-1 Option B cost attribution.** In mixed cohorts (safety + behavioral pairs in the same reflection), the behavioral record carries full `cost_usd` and the safety twin carries `cost_usd: 0` + `cost_attributed_to: reveriePairsPath`. Pure-safety cohorts keep cost on the safety record (no twin to attribute to).
+
+## Operator-facing knobs
+
+- `MOCK_REVERIE=true` env at the composition root forces the legacy mock path (test scaffolding only — produces the `observations[]` schema instead of the real `pairs[]` schema). The composition root reads this env and threads `forceMock: true` into deps. The Lego itself never reads `MOCK_REVERIE`.
+- `dailyBudgetUsd` (constructor option) caps per-user paid Opus calls. The guard fires before `triggerReverie` schedules the reflection, so a budget-exceeded cohort never invokes the inference provider.
 
 ## License
 
-Apache-2.0. See `LICENSE`.
+Proprietary. See [LICENSE](./LICENSE).