first commit

docs/foundation/flow/rules-hono/src/engine/default.md

@@ -0,0 +1,60 @@
+# Default engine — `@suaveplan/rules-hono/engine`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`getDefaultEngine()` exposes a lazy, per-process `RuleEngine` instance for callers who do not want to construct or thread an engine through their middleware stack. It is constructed exactly once on first call and cached for the lifetime of the process; every subsequent call returns the identical reference. Tests break the cache via `resetDefaultEngine()` exposed under the `./testing` subpath.
+
+This pattern replaces the upstream module-level singleton `defaultEngine = new RuleEngine()` — eager module-scope instantiation is a hidden global per AGENTS.md §6a and creates a side-effect on import that prevents tree-shaking even when no caller uses the default. Lazy construction defers the cost until a real call site fires.
+
+## Features
+
+- Lazy singleton, identity-stable across calls.
+- Cache reset hook surfaced only via the `./testing` subpath — production import paths cannot drop the cache.
+- Zero arguments — the default engine is constructed with the `RuleEngine` defaults; consumers that want a configured engine should instantiate `new RuleEngine(config)` themselves and pass it explicitly to the relevant middleware factory.
+
+## Usage: Basic Example
+
+```ts
+import { getDefaultEngine } from "@suaveplan/rules-hono/engine";
+
+const engine = getDefaultEngine();
+// engine is the process singleton — every other caller of getDefaultEngine sees the same instance
+```
+
+## Usage: Advanced Example
+
+```ts
+import { describe, it, expect } from "@suaveplan/testing/runner";
+import { getDefaultEngine } from "@suaveplan/rules-hono/engine";
+import { resetDefaultEngine } from "@suaveplan/rules-hono/testing";
+
+describe("my middleware", () => {
+    it("uses a fresh engine per test", () => {
+        resetDefaultEngine();
+        const a = getDefaultEngine();
+        // ... test against a ...
+        resetDefaultEngine();
+        const b = getDefaultEngine();
+        expect(a).not.toBe(b);
+    });
+});
+```
+
+## API Reference
+
+### `getDefaultEngine(): RuleEngine`
+
+Returns the cached default engine; constructs it on first call.
+
+### `resetDefaultEngine(): void` (`./testing` subpath only)
+
+Drops the cache. Strictly test-only — production code that needs a fresh engine should call `new RuleEngine()` directly.
+
+## Implementation Notes
+
+- The cache lives in module scope, so identity is per-process (matching every other ES-module-loaded singleton in Suaveplan).
+- The exported reset symbol is named `__resetDefaultEngineForTesting` internally and re-exported from the `./testing` subpath as `resetDefaultEngine`. The double-underscore prefix is a soft convention to discourage accidental production imports; the hard guarantee is the subpath split.
+- If consumers want telemetry-instrumented or plugin-configured engines, they construct their own and pass it via the `engine` option on every middleware factory. The default engine is for the "I just want this to work" path.