@adia-ai/a2ui-compose 0.0.1 → 0.2.0

package/CHANGELOG.md

@@ -10,7 +10,149 @@ generator graph.
 
 ## [Unreleased]
 
-_Nothing yet._
+_No pending changes._
+
+---
+
+## [0.2.0] - 2026-05-02
+
+**Lockstep cut + boundary cleanup.** All 8 published `@adia-ai/*`
+packages now share one version, governed by
+[`docs/specs/package-architecture.md` § 15 (Versioning Policy)](../../../docs/specs/package-architecture.md#15-versioning-policy).
+This release also lands the `engine/` ↔ `engines/` collision fix from
+T3 of the
+[`docs/plans/packages-architecture-fixes-2026-05-02.md`](../../../docs/plans/packages-architecture-fixes-2026-05-02.md)
+plan.
+
+### Changed
+
+- `version`: `0.1.0` → `0.2.0`.
+- `dependencies["@adia-ai/a2ui-utils"]`: `^0.0.2` → `^0.2.0`.
+- `dependencies["@adia-ai/a2ui-retrieval"]`: `^0.0.1` → `^0.2.0`.
+- `dependencies["@adia-ai/a2ui-validator"]`: `^0.0.1` → `^0.2.0`.
+
+- **Directory renames — `engine/` → `core/`, `engines/` → `strategies/`**
+  to remove the singular/plural collision that read as a typo. The
+  orchestrator (`generator.js`, `state.js`, `context-store.js`,
+  `artifacts.js`, `pattern-export.js`, `reference.js`, `pipeline/`) now
+  lives at `core/`; the pluggable strategies (`monolithic/`, `zettel/`,
+  `registry.js`) live at `strategies/`. The `transpiler/` directory's
+  internal imports were also rewritten by the same sweep (no behavior
+  change). All internal imports updated in one sweep.
+- **`constitution.md` moved out of the package source** to
+  [`docs/specs/compose-constitution.md`](../../../docs/specs/compose-constitution.md)
+  so it doesn't ship in the published tarball. Pointer added in
+  README.
+- **`package.json` `exports` map updated** with new keys (`./core`,
+  `./strategies/registry`, `./strategies/zettel`); old keys
+  (`./engine`, `./engines/registry`, `./engines/zettel`) retained as
+  aliases for one release cycle and removed in the next major.
+- Spec [`docs/specs/package-architecture.md`](../../../docs/specs/package-architecture.md)
+  bumped 0.5.0 → 0.6.0 with the directory tree updated to reflect the
+  new layout; new § 15 documents the lockstep versioning policy.
+
+### Migration
+
+Consumers importing from the old paths still work for one release
+cycle, but should update on next touch:
+
+```diff
+- import { generateUI } from '@adia-ai/a2ui-compose/engine';
++ import { generateUI } from '@adia-ai/a2ui-compose/core';
+
+- import { pick, registerEngine } from '@adia-ai/a2ui-compose/engines/registry';
++ import { pick, registerEngine } from '@adia-ai/a2ui-compose/strategies/registry';
+
+- import { generateZettel } from '@adia-ai/a2ui-compose/engines/zettel';
++ import { generateZettel } from '@adia-ai/a2ui-compose/strategies/zettel';
+```
+
+---
+
+## [0.1.0] - 2026-04-28
+
+**Multi-turn refinement engine (Phase A).** Adds three new modules to the
+zettel engine that turn `compose_from_chunks` from single-shot into a
+multi-turn surface, plus a first-class telemetry surface that auto-fires
+issue tickets on engine failure paths.
+
+Spec: [`docs/specs/genui-multiturn-architecture.md`](../../../docs/specs/genui-multiturn-architecture.md) (Active v0.1.0).
+Plan: [`docs/plans/genui-multiturn-rollout-2026-04-28.md`](../../../docs/plans/genui-multiturn-rollout-2026-04-28.md) (Phase A scoped).
+ADR: [`0008-multiturn-genui-architecture.md`](../../../.brain/adrs/0008-multiturn-genui-architecture.md).
+
+### Added (engine modules)
+
+- **`engines/zettel/state-cache.js`** — bounded LRU cache for multi-turn
+  compositions (default 64 entries; configurable via
+  `A2UI_STATE_CACHE_SIZE`). API: `set / get / peek / has / evict / list /
+  size / clear`. State-id minting helpers `mintStateId(intent, version)`
+  and `mintNextStateId(parent, version)` produce stems of the form
+  `<intent-prefix>-<rand4>-v<N>-<unix-min>` so refinement chains keep a
+  visible lineage. Module-level singleton via `getStateCache() /
+  resetStateCache()`. Pure data structure; no I/O, no async.
+- **`engines/zettel/issue-reporter.js`** — first-class telemetry surface.
+  `reportIssue(input, ctx)` writes immutable JSON to
+  `.brain/audit-history/issues/<issue_id>.json` (matches the existing
+  audit-ledger convention). `autoReport(reason, autoCtx, ctx)` looks up
+  a 6-row policy table for engine-side auto-fires (`synthesizer-exhausted`,
+  `validator-exhausted`, `locator-empty-targets`,
+  `retrieval-zero-then-synthesis-fail`, `cache-miss-on-known-state`,
+  `ops-failed-after-apply`) and threads severity / type / suggested-owner
+  defaults. `attachTrace(state_id, depth, cache)` pulls from the
+  state-cache via `peek` (no recency disturbance). Sidecar trace files
+  for traces > 200 KB. Three reporter kinds: `auto | user | llm`.
+  `evalMode: true` in ctx suppresses auto-fire (manual `reportIssue`
+  calls still write). Per-tool-call `IssueAccumulator` coalesces
+  multiple auto-fires into a single issue with the highest-severity
+  policy as primary; reasons listed in body + tags.
+- **`engines/zettel/chunk-refiner.js`** — sibling to `chunk-synthesizer.js`.
+  Two-pass synthesis (locator → modifier) for refinement intents.
+  `refineFromIntent({ priorState, intent, llmAdapter, maxAttempts,
+  issueAccumulator, catalog })` runs a locator pass to identify which
+  slots to modify, then a modifier pass to emit chunk-plan ops on the
+  targeted slice. Validator-driven retry loop with feedback-on-error
+  (default `maxAttempts: 2`, mirrors `chunk-synthesizer`). `validateOps`
+  checks op shape, slot references, chunk references, page-kind
+  contracts. `applyOps({ priorState, ops })` mutates a deep-cloned
+  plan and re-materializes HTML via `composeFromPlan`. `opsToA2UI(ops,
+  newState)` translates chunk-plan ops to wire-format `updateComponents`
+  A2UI messages (Phase A simplification: `components[].html` carries
+  the materialized payload; Phase B will upgrade to component-tree shape).
+
+### Phase A op format
+
+Internal: `rebindSlot | appendToSlot | removeFromSlot | replacePage`.
+Wire: standard `updateComponents` messages targeting `slot-<name>` ids
+(or `main` for `replacePage`). Documented as a Phase A simplification —
+the chunk pipeline emits HTML, so the wire-format wrapper is intentionally
+thin until Phase B introduces typed component-tree refinements.
+
+### Smoke + eval
+
+- `npm run smoke:state-cache` — 34/34 (LRU recency, peek, env-driven sizing,
+  state-id minting + chain).
+- `npm run smoke:issues` — 62/62 (write, validation, trace attach, sidecar
+  spill, auto-fire policy lookup, evalMode suppression, coalescing).
+- `npm run smoke:refine` — 51/51 (validateOps, applyOps × 4 op types,
+  opsToA2UI, two-pass with stub LLM, retries, exhaustion auto-fire,
+  end-to-end refine → apply → wire).
+- **`npm run eval:refine-synthesis`** — **15/15 PASS** real-LLM eval.
+  Ops rate 100%, validate rate 100%, 0 auto-fires, 67 s. All 15
+  refinements completed on the first attempt.
+
+### Out of scope (Phase B / C)
+
+- Persistent state across server restarts (filesystem-JSON-backed cache at `.brain/state-cache/`; mirrors the existing audit-ledger convention; design in plan §2).
+- Branching / version trees.
+- LLM-streamed op emission.
+- Multi-user concurrent refinement (CRDT / OT).
+- A2UI `updateDataModel` + `wireComponents` synthesis (current scope is
+  `updateComponents` + `deleteSurface` only).
+
+### Migration
+
+Additive surface; no breaking changes. Existing consumers calling
+`composeFromIntent` continue to work unchanged.
 
 ---
 

package/README.md

@@ -1,19 +1,20 @@
 # @adia-ai/a2ui-compose
 
-Framework-agnostic UI generation engine. Takes a natural-language intent +
+Framework-agnostic UI generation engine. Constitution doc:
+[`docs/specs/compose-constitution.md`](../../../docs/specs/compose-constitution.md).
+Takes a natural-language intent +
 an A2UI component catalog and produces a tree of A2UI protocol messages
 ready for a renderer.
 
 > This package is pipeline runtime only. UI components live in
-> [`@adia-ai/web-components`](../web-components); the A2UI runtime (renderer,
-> registry, streams, wiring) in [`@adia-ai/a2ui-utils`](../a2ui/utils);
+> [`@adia-ai/web-components`](../../web-components); the A2UI runtime (renderer,
+> registry, streams, wiring) in [`@adia-ai/a2ui-utils`](../utils);
 > the pattern corpus in [`@adia-ai/a2ui-corpus`](../corpus);
 > the MCP server in [`@adia-ai/a2ui-mcp`](../mcp).
 >
-> Note: this package still lives under the legacy `@adiahealth` scope in its
-> own `package.json` name. The `@adia-ai` scope is the public npm scope
-> (only `@adia-ai/web-components` and `@adia-ai/a2ui-utils` are currently
-> published).
+> Published to the public `@adia-ai` scope on 2026-04-24 alongside
+> `a2ui-corpus`, `a2ui-mcp`, `a2ui-retrieval`, and `a2ui-validator`.
+> Install with `npm i @adia-ai/a2ui-compose`.
 
 ## What it does
 
@@ -25,7 +26,7 @@ intent  ─▶  classify  ─▶  retrieve  ─▶  compose / adapt  ─▶  val
 One entry point, two generation strategies, pluggable LLM back-end.
 
 ```javascript
-import { generateUI } from '@adia-ai/a2ui-compose/engine';
+import { generateUI } from '@adia-ai/a2ui-compose/core';
 
 const result = await generateUI({
   intent: 'login form with email, password, and remember-me',
@@ -42,11 +43,13 @@ const result = await generateUI({
 ## Layout
 
 ```
-gen-ui/
-├── engine/
-│   └── generator.js        generateUI() — the one public entry point
+a2ui-compose/
+├── core/                   orchestrator — state, dispatch, pipeline (formerly engine/)
+│   ├── generator.js        generateUI() — the one public entry point
+│   ├── state.js            ArtifactStore + PipelineEngine singletons
+│   └── pipeline/           6-stage pipeline engine
 │
-├── engines/                pluggable strategies via registerEngine()
+├── strategies/             pluggable engines via registerEngine() (formerly engines/)
 │   ├── registry.js         engine selector + reserved-name guard
 │   ├── monolithic/         pattern-match + LLM-adapt (3 modes)
 │   │   ├── generate-instant.js   no LLM — pattern-match only
@@ -55,7 +58,7 @@ gen-ui/
 │   └── zettel/             fragment-graph composition
 │       ├── generator-adapter.js  entry point
 │       ├── composer.js           assembles fragments → compositions
-│       └── session.js            multi-turn state
+│       └── session-store.js      multi-turn state (Phase A)
 │
 ├── retrieval/
 │   ├── catalog.js          loads component schemas from sibling .a2ui.json
@@ -99,7 +102,7 @@ and assembles them into compositions. Verbatim retrieval above a threshold
 across multi-turn iterations.
 
 ```javascript
-import { registerEngine } from '@adia-ai/a2ui-compose/engines/registry';
+import { registerEngine } from '@adia-ai/a2ui-compose/strategies/registry';
 
 registerEngine('my-engine', async (ctx) => {
   // ctx: intent, catalog, patterns, concepts, session, llm, …

package/{engine → core}/generator.js

@@ -14,21 +14,21 @@
 import { validateSchema } from '../../validator/validator.js';
 import { getContext, searchBlocks, searchBlocksSemantic, lookupDomain, listPatterns } from './reference.js';
 import { store, engine } from './state.js';
-import { checkIntentAlignment } from '../../retrieval/intent-alignment.js';
-import { decomposeIntent, composeSubtasks } from '../../retrieval/decomposer.js';
+import { checkIntentAlignment } from '../../retrieval/intent/intent-alignment.js';
+import { decomposeIntent, composeSubtasks } from '../../retrieval/intent/decomposer.js';
 import { getWiringCatalog } from '../../retrieval/wiring-catalog.js';
 import { getComponentData } from '../../retrieval/pattern-library.js';
 
 import { StubLLMAdapter } from '../llm/llm-stub.js';
 import { createAdapter } from '../llm/llm-bridge.js';
-import { assessClarity } from '../../retrieval/clarity.js';
-import { isConversational } from '../../retrieval/intent-gate.js';
+import { assessClarity } from '../../retrieval/intent/clarity.js';
+import { isConversational } from '../../retrieval/intent/intent-gate.js';
 import { classifyIntent } from '../../retrieval/domain-router.js';
-import { researchIntent, detectReferences } from '../../retrieval/web-research.js';
-import { feedbackStore } from '../../retrieval/feedback-store.js';
-import { pick as pickEngine, registerMonolithicEngines } from '../engines/registry.js';
-import { analyzePrompt } from '../../retrieval/prompt-analyzer.js';
-import { recordTurn, isRecording } from '../../retrieval/dialog-recorder.js';
+import { researchIntent, detectReferences } from '../../retrieval/authoring/web-research.js';
+import { feedbackStore } from '../../retrieval/feedback/feedback-store.js';
+import { pick as pickEngine, registerMonolithicEngines } from '../strategies/registry.js';
+import { analyzePrompt } from '../../retrieval/intent/prompt-analyzer.js';
+import { recordTurn, isRecording } from '../../retrieval/feedback/dialog-recorder.js';
 import {
   buildSystemPrompt,
   buildChatMessages,
@@ -38,10 +38,10 @@ import {
   parseA2UIResponse,
   buildRepairPrompt,
   generateSuggestions,
-} from '../engines/monolithic/_shared.js';
-import { generateInstant }  from '../engines/monolithic/generate-instant.js';
-import { generatePro }      from '../engines/monolithic/generate-pro.js';
-import { generateThinking } from '../engines/monolithic/generate-thinking.js';
+} from '../strategies/monolithic/_shared.js';
+import { generateInstant }  from '../strategies/monolithic/generate-instant.js';
+import { generatePro }      from '../strategies/monolithic/generate-pro.js';
+import { generateThinking } from '../strategies/monolithic/generate-thinking.js';
 
 
 /**

package/{engine → core}/state.js

@@ -1,8 +1,8 @@
 /**
  * Shared module-level singletons for the monolithic engine.
  *
- * These were previously private to engine/generator.js. Extracted so that
- * engines/monolithic/generate-{instant,pro,thinking}.js can share the same
+ * These were previously private to core/generator.js. Extracted so that
+ * strategies/monolithic/generate-{instant,pro,thinking}.js can share the same
  * artifact store and pipeline engine without going through the dispatcher.
  *
  * Same instances, imported by reference — do NOT re-instantiate per-call.

package/index.js

@@ -5,12 +5,12 @@
  * via subpaths:
  *
  *   import { generateUI }      from '@adia-ai/a2ui-compose';
- *   import { pick, registerEngine } from '@adia-ai/a2ui-compose/engines/registry';
- *   import { generateZettel }  from '@adia-ai/a2ui-compose/engines/zettel';
+ *   import { pick, registerEngine } from '@adia-ai/a2ui-compose/strategies/registry';
+ *   import { generateZettel }  from '@adia-ai/a2ui-compose/strategies/zettel';
  *   import { llmBridge }       from '@adia-ai/a2ui-compose/llm';
  *
  * See README for the full public surface.
  */
 
-export { generateUI, generateUIStream } from './engine/generator.js';
-export { pick, listEngines, registerEngine, unregisterEngine, ENGINES } from './engines/registry.js';
+export { generateUI, generateUIStream } from './core/generator.js';
+export { pick, listEngines, registerEngine, unregisterEngine, ENGINES } from './strategies/registry.js';

package/package.json

@@ -1,21 +1,24 @@
 {
   "name": "@adia-ai/a2ui-compose",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "description": "AdiaUI A2UI compose engine — framework-agnostic. Takes natural-language intents + a catalog and produces A2UI protocol messages. Pairs with `@adia-ai/a2ui-retrieval` (intent classification, catalog lookup) and `@adia-ai/a2ui-validator` (schema + semantic checks).",
   "type": "module",
   "exports": {
-    ".":                    "./index.js",
-    "./engine":             "./engine/generator.js",
-    "./engines/zettel":     "./engines/zettel/generator-adapter.js",
-    "./engines/registry":   "./engines/registry.js",
-    "./llm":                "./llm/llm-bridge.js",
-    "./llm/*":              "./llm/*.js",
-    "./transpiler":         "./transpiler/transpiler.js",
-    "./evals":              "./evals/harness.mjs"
+    ".":                       "./index.js",
+    "./core":                  "./core/generator.js",
+    "./strategies/zettel":     "./strategies/zettel/generator-adapter.js",
+    "./strategies/registry":   "./strategies/registry.js",
+    "./llm":                   "./llm/llm-bridge.js",
+    "./llm/*":                 "./llm/*.js",
+    "./transpiler":            "./transpiler/transpiler.js",
+    "./evals":                 "./evals/harness.mjs",
+    "./engine":                "./core/generator.js",
+    "./engines/zettel":        "./strategies/zettel/generator-adapter.js",
+    "./engines/registry":      "./strategies/registry.js"
   },
   "files": [
-    "engine/",
-    "engines/",
+    "core/",
+    "strategies/",
     "llm/",
     "evals/",
     "transpiler/",
@@ -34,8 +37,8 @@
     "directory": "packages/a2ui/compose"
   },
   "dependencies": {
-    "@adia-ai/a2ui-utils": "^0.0.2",
-    "@adia-ai/a2ui-retrieval": "^0.0.1",
-    "@adia-ai/a2ui-validator": "^0.0.1"
+    "@adia-ai/a2ui-utils": "^0.2.0",
+    "@adia-ai/a2ui-retrieval": "^0.2.0",
+    "@adia-ai/a2ui-validator": "^0.2.0"
   }
 }

package/{engines → strategies}/monolithic/_shared.js

@@ -1,16 +1,16 @@
 /**
  * @adia-ai/a2ui-compose — monolithic engine, shared helpers.
  *
- * Pure helpers extracted from engine/generator.js per spec §11 Phase 2:
+ * Pure helpers extracted from core/generator.js per spec §11 Phase 2:
  * prompt builders, JSON parsers, canvas diff utilities, suggestion
  * generators. All stateless (the only module-level state is the lazy
  * component-catalog cache inside getComponentCatalog).
  */
 
-import { listPatterns } from '../../engine/reference.js';
-import { store } from '../../engine/state.js';
-import { checkIntentAlignment } from '../../../retrieval/intent-alignment.js';
-import { composeSubtasks } from '../../../retrieval/decomposer.js';
+import { listPatterns } from '../../core/reference.js';
+import { store } from '../../core/state.js';
+import { checkIntentAlignment } from '../../../retrieval/intent/intent-alignment.js';
+import { composeSubtasks } from '../../../retrieval/intent/decomposer.js';
 import { getWiringCatalog } from '../../../retrieval/wiring-catalog.js';
 import { getComponentData } from '../../../retrieval/pattern-library.js';
 
@@ -412,10 +412,10 @@ STATE LAYER:
   Controllers: ${wc.controllers.map(c => c.type).join(', ')} (extensible via registerController)
   "bind" maps controller state ↔ model paths for two-way sync.
 
-ACTIONS LAYER — AdiaEvent → handler chains:
-  Each action binds a AdiaEvent to a handler. The event is a typed object, not a string.
+ACTIONS LAYER — UIEvent → handler chains:
+  Each action binds a UIEvent to a handler. The event is a typed object, not a string.
 
-  AdiaEvent types: ${wc.adiaEvents.map(e => e.event).join(', ')}
+  UIEvent types: ${wc.adiaEvents.map(e => e.event).join(', ')}
   Each carries a typed payload:
 ${wc.adiaEvents.filter(e => e.payload).map(e => `    ${e.event} → ${e.payload}`).join('\n')}
 
@@ -434,7 +434,7 @@ ${wc.adiaEvents.filter(e => e.payload).map(e => `    ${e.event} → ${e.payload}
     }
   ]
 
-  AdiaEvent shape: { "event": "<type>", "target": "<componentId>", "debounce"?: ms, "throttle"?: ms, "condition"?: { "path", "equals"|"notEquals"|"exists" } }
+  UIEvent shape: { "event": "<type>", "target": "<componentId>", "debounce"?: ms, "throttle"?: ms, "condition"?: { "path", "equals"|"notEquals"|"exists" } }
   "target" scopes to a component id. Omit for surface-level events (mount, unmount).
   "onSuccess" / "onError" are follow-up action arrays — NOT separate entries.
   Handlers: ${wc.handlers.map(h => h.name).join(', ')} (extensible via registerHandler)

package/{engines → strategies}/monolithic/generate-instant.js

@@ -1,17 +1,17 @@
 /**
  * @adia-ai/a2ui-compose — monolithic engine, instant mode.
  *
- * Extracted from engine/generator.js per spec §11 Phase 2. Shares state
- * (ArtifactStore, PipelineEngine) via engine/state.js. Pure helpers live
- * in engines/monolithic/_shared.js.
+ * Extracted from core/generator.js per spec §11 Phase 2. Shares state
+ * (ArtifactStore, PipelineEngine) via core/state.js. Pure helpers live
+ * in strategies/monolithic/_shared.js.
  */
 
 import { validateSchema } from '../../../validator/validator.js';
-import { getContext, searchBlocks, lookupDomain } from '../../engine/reference.js';
-import { assessClarity } from '../../../retrieval/clarity.js';
-import { feedbackStore } from '../../../retrieval/feedback-store.js';
-import { store, engine } from '../../engine/state.js';
-import { isRecording } from '../../../retrieval/dialog-recorder.js';
+import { getContext, searchBlocks, lookupDomain } from '../../core/reference.js';
+import { assessClarity } from '../../../retrieval/intent/clarity.js';
+import { feedbackStore } from '../../../retrieval/feedback/feedback-store.js';
+import { store, engine } from '../../core/state.js';
+import { isRecording } from '../../../retrieval/feedback/dialog-recorder.js';
 import {
   generateSuggestions,
 } from './_shared.js';

package/{engines → strategies}/monolithic/generate-pro.js

@@ -1,19 +1,19 @@
 /**
  * @adia-ai/a2ui-compose — monolithic engine, pro mode.
  *
- * Extracted from engine/generator.js per spec §11 Phase 2. Shares state
- * (ArtifactStore, PipelineEngine) via engine/state.js. Pure helpers live
- * in engines/monolithic/_shared.js.
+ * Extracted from core/generator.js per spec §11 Phase 2. Shares state
+ * (ArtifactStore, PipelineEngine) via core/state.js. Pure helpers live
+ * in strategies/monolithic/_shared.js.
  */
 
 import { validateSchema } from '../../../validator/validator.js';
-import { getContext, searchBlocks, lookupDomain } from '../../engine/reference.js';
-import { decomposeIntent } from '../../../retrieval/decomposer.js';
-import { assessClarity } from '../../../retrieval/clarity.js';
-import { isConversational } from '../../../retrieval/intent-gate.js';
-import { feedbackStore } from '../../../retrieval/feedback-store.js';
-import { store, engine } from '../../engine/state.js';
-import { isRecording } from '../../../retrieval/dialog-recorder.js';
+import { getContext, searchBlocks, lookupDomain } from '../../core/reference.js';
+import { decomposeIntent } from '../../../retrieval/intent/decomposer.js';
+import { assessClarity } from '../../../retrieval/intent/clarity.js';
+import { isConversational } from '../../../retrieval/intent/intent-gate.js';
+import { feedbackStore } from '../../../retrieval/feedback/feedback-store.js';
+import { store, engine } from '../../core/state.js';
+import { isRecording } from '../../../retrieval/feedback/dialog-recorder.js';
 import {
   buildSystemPrompt,
   buildChatMessages,

package/{engines → strategies}/monolithic/generate-thinking.js

@@ -1,18 +1,18 @@
 /**
  * @adia-ai/a2ui-compose — monolithic engine, thinking mode.
  *
- * Extracted from engine/generator.js per spec §11 Phase 2. Shares state
- * (ArtifactStore, PipelineEngine) via engine/state.js. Pure helpers live
- * in engines/monolithic/_shared.js.
+ * Extracted from core/generator.js per spec §11 Phase 2. Shares state
+ * (ArtifactStore, PipelineEngine) via core/state.js. Pure helpers live
+ * in strategies/monolithic/_shared.js.
  */
 
 import { validateSchema } from '../../../validator/validator.js';
 import { validateMessages as validateCatalog } from '../../../validator/catalog-validator.js';
-import { getContext, searchBlocksSemantic, lookupDomain } from '../../engine/reference.js';
-import { assessClarity } from '../../../retrieval/clarity.js';
-import { feedbackStore } from '../../../retrieval/feedback-store.js';
-import { store, engine } from '../../engine/state.js';
-import { isRecording } from '../../../retrieval/dialog-recorder.js';
+import { getContext, searchBlocksSemantic, lookupDomain } from '../../core/reference.js';
+import { assessClarity } from '../../../retrieval/intent/clarity.js';
+import { feedbackStore } from '../../../retrieval/feedback/feedback-store.js';
+import { store, engine } from '../../core/state.js';
+import { isRecording } from '../../../retrieval/feedback/dialog-recorder.js';
 import {
   buildSystemPrompt,
   buildChatMessages,

package/{engines → strategies}/registry.js

@@ -7,7 +7,7 @@
  *   - zettel      → fragment-graph composition (single mode: instant)
  *
  * The registry deliberately does NOT own intent-gating, clarity assessment, or
- * execution lifecycle — the public `generateUI()` in engine/generator.js does
+ * execution lifecycle — the public `generateUI()` in core/generator.js does
  * that, then delegates the actual work through `pick()`.
  *
  * Shape invariant: every engine function returns
@@ -15,8 +15,8 @@
  */
 
 // Zettel is lazy-loaded — it transitively imports node:fs / node:path / node:url
-// (engines/zettel/fragment-library.js), which Vite externalizes in the browser.
-// Static-importing it here would break browser loads of engine/generator.js.
+// (strategies/zettel/fragment-library.js), which Vite externalizes in the browser.
+// Static-importing it here would break browser loads of core/generator.js.
 // In-browser callers reach zettel via POST /api/generate (server-side), never
 // through this registry, so lazy-loading is safe and incurs only a one-time
 // import on first server-side invocation.
@@ -33,15 +33,15 @@ async function getGenerateZettel() {
 let _isRecording = null;
 async function getIsRecording() {
   if (!_isRecording) {
-    const mod = await import('../../retrieval/dialog-recorder.js');
+    const mod = await import('../../retrieval/feedback/dialog-recorder.js');
     _isRecording = mod.isRecording;
   }
   return _isRecording;
 }
 
-// The three monolithic paths live inside engine/generator.js as internal
+// The three monolithic paths live inside core/generator.js as internal
 // functions. They're injected at boot via `registerMonolithicEngines()` to
-// avoid a circular import (engine/generator.js owns the registry caller).
+// avoid a circular import (core/generator.js owns the registry caller).
 let _monolithicInstant = null;
 let _monolithicPro = null;
 let _monolithicThinking = null;