@adia-ai/gen-ui 0.8.37

package/compose/strategies/registry.js

@@ -0,0 +1,495 @@
+/**
+ * Engine registry + dispatcher — the seam between gen-ui's public API and the
+ * per-engine implementations. Per .claude/docs/specs/package-architecture.md §11 Phase 5.
+ *
+ * Wired engines:
+ *   - monolithic   → pattern-match + adapt (instant | pro | thinking modes)
+ *   - zettel       → fragment-graph composition (single mode: instant)
+ *   - chunk-zettel → slot-binding plan over corpus chunks
+ *   - free-form    → LLM-picked chunk ingredients, grounded composition
+ *   - auto         → the escalation ladder over the four above, declared as
+ *                    an `@adia-ai/agent` workflow in cascade.js (gh#664)
+ *
+ * The registry deliberately does NOT own intent-gating, clarity assessment, or
+ * execution lifecycle — the public `generateUI()` in core/generator.js does
+ * that, then delegates the actual work through `pick()`.
+ *
+ * Shape invariant: every engine function returns
+ *   { executionId, messages, validation, suggestions?, strategy?, ... }
+ */
+
+// Zettel is lazy-loaded — it transitively imports node:fs / node:path / node:url
+// (strategies/zettel/composition-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.
+let _generateZettel = null;
+async function getGenerateZettel() {
+  if (!_generateZettel) {
+    const mod = await import('./zettel/generator-adapter.js');
+    _generateZettel = mod.generateZettel;
+  }
+  return _generateZettel;
+}
+
+// Same lazy-load story for isRecording — keeps the cold-import surface tight.
+let _isRecording = null;
+async function getIsRecording() {
+  if (!_isRecording) {
+    const mod = await import('../../retrieval/feedback/dialog-recorder.js');
+    _isRecording = mod.isRecording;
+  }
+  return _isRecording;
+}
+
+// The three monolithic paths live inside core/generator.js as internal
+// functions. They're injected at boot via `registerMonolithicEngines()` to
+// avoid a circular import (core/generator.js owns the registry caller).
+let _monolithicInstant = null;
+let _monolithicPro = null;
+let _monolithicThinking = null;
+
+export function registerMonolithicEngines({ instant, pro, thinking }) {
+  _monolithicInstant = instant;
+  _monolithicPro = pro;
+  _monolithicThinking = thinking;
+}
+
+// A2UI overhaul plan, Phase 4: instant mode never repairs (it makes no LLM
+// calls at all — that's its whole cost/latency identity) and previously
+// returned a hard-fail's broken output silently. Escalation to pro lives
+// HERE, at the dispatcher, not inside generate-instant.js itself — it's the
+// caller's policy decision, matching validate-and-repair.js's "escalation
+// stays with the caller" contract, and this is the one place that already
+// holds both `ctx.llmAdapter` and `_monolithicPro` in scope.
+//
+// Capped at exactly one hop by construction: generateProAdapter has no
+// escalation logic of its own, so a pro-mode failure after an instant
+// escalation returns straight to the original caller — it can never chain
+// into thinking. Only escalates when an llmAdapter is actually available;
+// many instant-mode callers pass none (that's the 0-cost tier's point), and
+// validate-and-repair.js's own contract for that case is "report the
+// failure, don't invent a repair path" — same discipline here.
+//
+// This silently converts a 0-cost request into a billed LLM call, which is
+// a product/cost-visibility concern, not just an engineering one — hence
+// the counter + the warn log, from day one, not added later once someone
+// asks "why did our LLM spend spike".
+let _instantEscalationCount = 0;
+export function getInstantEscalationCount() {
+  return _instantEscalationCount;
+}
+
+// Engine adapters — uniform call signature `(ctx) => Promise<result>` where
+// ctx is prepared by the public generateUI() orchestrator.
+//
+// gh#664: the instant → pro hop is a two-step `@adia-ai/agent` workflow now
+// rather than an inline `if`. The rule is unchanged and still lives here at
+// the dispatcher (see the note above); what changed is that it's declared
+// as a step sequence with an `until` predicate, the same shape the full
+// ladder in cascade.js uses, so there is one way to spell "escalate" in
+// this package instead of two. The harness import is lazy for the same
+// browser-load reason zettel is: this module is imported by
+// core/generator.js, which the gen-ui playground loads directly.
+async function generateInstantAdapter(ctx) {
+  if (!_monolithicInstant) throw new Error('monolithic-instant engine not registered');
+  const canEscalate = !!(ctx.llmAdapter && _monolithicPro);
+  const { defineWorkflow, runWorkflow } = await import('@adia-ai/agent');
+  const outcome = await runWorkflow(defineWorkflow('monolithic-escalation', [
+    {
+      name: 'monolithic-instant',
+      // A PURE verdict (gh#665 / PR #669 nit N2): the counter and the warn
+      // used to live in here, correct only while the harness called `until`
+      // exactly once per step. They moved to the pro step's `run`, which by
+      // construction executes once and only when the hop actually happens.
+      until: (result) =>
+        result.validation?.valid || !canEscalate
+          ? { accepted: true }
+          : {
+              accepted: false,
+              reason: 'instant-validation-failed',
+              detail: `score=${result.validation?.score}`,
+            },
+      run: () => _monolithicInstant(ctx),
+    },
+    // Terminal by construction — generateProAdapter has no escalation of
+    // its own, so the hop is capped at exactly one, as before.
+    {
+      name: 'monolithic-pro',
+      run: (wctx) => {
+        _instantEscalationCount++;
+        console.warn(`[a2ui] monolithic-instant hard-failed validation (${wctx.feedback?.detail ?? 'no score'}) for intent "${ctx.intent}" — escalating to monolithic-pro (escalation #${_instantEscalationCount})`);
+        return _monolithicPro(ctx);
+      },
+    },
+  ]), { input: ctx, sessionId: ctx.sessionId ?? ctx.executionId ?? 'monolithic' });
+  return outcome.result;
+}
+async function generateProAdapter(ctx) {
+  if (!_monolithicPro) throw new Error('monolithic-pro engine not registered');
+  return _monolithicPro(ctx);
+}
+async function generateThinkingAdapter(ctx) {
+  if (!_monolithicThinking) throw new Error('monolithic-thinking engine not registered');
+  return _monolithicThinking(ctx);
+}
+
+async function generateZettelAdapter(ctx) {
+  // Map the monolithic ctx to the zettel adapter's expected shape.
+  // storeId (monolithic's multi-turn handle) → sessionId (zettel's turn history).
+  // The steelman from the baseline analyzer drives both retrieval (better
+  // keyword match against the corpus) and LLM synthesis (richer brief). Falls
+  // back to raw intent on iteration turns when analyzer was skipped.
+  // Note: ctx.priorComponentsFromPayload is forwarded for forward-compat —
+  // zettel's session-store currently owns iteration history, but a future
+  // pass should let payload override session state for true statelessness.
+  const generateZettel = await getGenerateZettel();
+  const enrichedIntent = ctx.analysis?.steelman || ctx.intent;
+  const result = await generateZettel({
+    intent: enrichedIntent,
+    mode: 'instant',
+    llmAdapter: ctx.llmAdapter || null,
+    sessionId: ctx.storeId || ctx.executionId || null,
+    priorComponentsFromPayload: ctx.priorComponentsFromPayload || null,
+  });
+
+  // Dialog-recorder hook for zettel. No "system prompt" to capture (the
+  // synthesizer builds its own internally), but the strategy + composition +
+  // candidates are the equivalent reasoning surface — they explain why this
+  // turn produced what it did. Surfaced via _debug so the recorder picks
+  // them up the same way it picks up monolithic engines' system prompts.
+  const isRecording = await getIsRecording();
+  return {
+    executionId: ctx.executionId,
+    messages: result.messages,
+    validation: result.validation,
+    suggestions: [],
+    strategy: result.strategy,
+    engine: 'zettel',
+    _debug: isRecording() ? {
+      systemPrompt: null,
+      rawLLMResponse: null,
+      tokens: null,
+      patterns: (result.candidates || []).slice(0, 8).map(c => ({
+        name: c.name,
+        score: c.score,
+        type: c.type,
+      })),
+      strategy: result.strategy || null,
+      composition: result.composition || result.patternName || null,
+      fragmentsUsed: result.fragments_used || null,
+      retrievalScore: result.retrievalScore ?? null,
+      synthesisAttempts: result.synthesis?.attempts ?? null,
+      sessionTurns: result.sessionTurns ?? null,
+    } : undefined,
+  };
+}
+
+// §108 (v0.5.1): pin free-form's ingredient-picker to Haiku 4.5.
+// Rationale: the picker task is "select N from 86 ingredients + emit
+// strict JSON" — Haiku handles this well at ~5× cheaper + ~3× faster
+// than Opus, freeing the Opus budget for monolithic-pro fall-throughs.
+// User-decided pre-A/B per v0.5.1 plan question 2: "Haiku is a good
+// default."
+//
+// §127 (v0.5.2): env override for the A/B harness. Set
+// `FREE_FORM_MODEL_OVERRIDE` env var to e.g. `claude-opus-4-7` to run
+// the eval against Opus for the §127 Haiku-vs-Opus comparison.
+// Default behavior unchanged when env var unset — the Haiku-pin holds
+// for every consumer that doesn't explicitly override. Read at
+// call-time (not module-load) so eval harnesses can set the env after
+// static imports complete.
+const FREE_FORM_MODEL_DEFAULT = 'claude-haiku-4-5-20251001';
+
+async function generateFreeFormAdapter(ctx) {
+  // Lazy-load: free-form-composer imports composition-library which
+  // top-level-awaits a node:fs read. Same browser-safety story as zettel.
+  const { generateFreeForm } = await import('./free-form-composer/index.js');
+
+  // Pin Haiku for the picker task even when harness model is Opus.
+  // Auto-engine + factory-chat may pass any-model llmAdapter; free-form
+  // mints its own to keep the picker cost-bounded.
+  //
+  // §127 (v0.5.2): `ctx.model` overrides the FREE_FORM pin (highest
+  // priority). `FREE_FORM_MODEL_OVERRIDE` env var is the second-priority
+  // override (set by `eval-diff.mjs --model <id>`). Default Haiku-pin
+  // holds otherwise. Empirical result from §127 records the production
+  // default; if Opus wins, FREE_FORM_MODEL_DEFAULT flips.
+  const modelToUse = ctx.model || process.env.FREE_FORM_MODEL_OVERRIDE || FREE_FORM_MODEL_DEFAULT;
+  let pickerAdapter = ctx.llmAdapter || null;
+  try {
+    const { createAdapter } = await import('@adia-ai/llm/bridge');
+    pickerAdapter = await createAdapter({ model: modelToUse });
+  } catch {
+    // Adapter mint failed (proxy down, no key) — fall back to whatever
+    // ctx provides. Strategy will emit `free-form-no-llm` if both fail.
+  }
+
+  const result = await generateFreeForm({
+    intent: ctx.intent,
+    llmAdapter: pickerAdapter,
+  });
+  const isRecording = await getIsRecording();
+  return {
+    executionId: ctx.executionId,
+    messages: result.messages,
+    validation: result.validation,
+    suggestions: [],
+    strategy: result.strategy,
+    engine: 'free-form',
+    // §109 (v0.5.1): usedIngredients graduates from `_debug.*` to
+    // first-class. Auto-engine + factory-chat UI both depend on it for
+    // trace labels; coupling visibility to dialog-recorder state was
+    // fragile. `rationale` joins it for the same reason — trace
+    // copy quotes the LLM's one-line rationale when present.
+    usedIngredients: result.usedIngredients || [],
+    rationale: result.rationale || null,
+    // §107a (v0.5.1): plan graduates to first-class so eval-diff's
+    // `--report-substitutions` can read it without `_debug` gating.
+    // The plan carries the LLM's emitted substitutions per ingredient
+    // — the substitution-coverage measurement needs this surface even
+    // when dialog-recorder is off (production eval scenarios).
+    plan: result.plan || null,
+    // §131 (v0.5.2): `_debug` is **volatile** — dialog-recorder-gated,
+    // shape may change without semver coordination. Consumers MUST read
+    // first-class fields instead: `usedIngredients` (§109 v0.5.1),
+    // `rationale` (§109 v0.5.1), `plan` (§107a v0.5.2). The old soft-API
+    // paths (`_debug.usedIngredients`, `_debug.rationale`, `_debug.plan`)
+    // were removed by §109 / §107a; this block is now strictly debug-
+    // recorder fodder. Scheduled removal: v0.6.0 will fold `attempts` +
+    // `warnings` into first-class result fields and drop `_debug` here.
+    //
+    // §146 (v0.5.3): finalize the v0.6.0 deprecation schedule for the
+    // last two `_debug.*` fields that any consumer might still read.
+    //
+    // @deprecated `_debug.attempts` and `_debug.warnings` — both fields
+    //   are dialog-recorder-gated (silently `undefined` when not
+    //   recording), which is exactly the access pattern §109+§107a
+    //   removed for `usedIngredients`/`rationale`/`plan`. v0.6.0 folds
+    //   both into first-class result fields:
+    //
+    //     - `result.attempts: number` — number of LLM round-trips taken
+    //       to produce the final plan (1 normally; 2-3 with hallucination
+    //       retry or paraphrase-retry; same value as §106's loop counter)
+    //     - `result.warnings: string[]` — non-fatal transpile findings
+    //       (unknown substitution keys, layout-value fall-throughs,
+    //       chunk-resolution warns); same value as transpilePlan output
+    //
+    //   Consumers should switch reads from `result._debug?.attempts` →
+    //   `result.attempts` and `result._debug?.warnings` → `result.warnings`
+    //   before v0.6.0 ships. The `_debug` block itself disappears from
+    //   the free-form-composed result shape entirely in v0.6.0; the
+    //   dialog-recorder will read first-class fields directly.
+    //
+    //   No in-repo consumers currently read these fields (verified
+    //   `grep -rn '_debug\?.attempts\|_debug.attempts\|_debug\?.warnings\|_debug.warnings'
+    //   apps/ playgrounds/ catalog/ packages/` → 0 hits at v0.5.3 cut).
+    //   External consumers should treat v0.6.0 as the migration window.
+    _debug: isRecording() ? {
+      systemPrompt: null,
+      rawLLMResponse: null,
+      tokens: null,
+      attempts: result.attempts,
+      warnings: result.warnings,
+    } : undefined,
+  };
+}
+
+async function generateChunkZettelAdapter(ctx) {
+  const { composeFromIntent } = await import('./zettel/chunk-synthesizer.js');
+  const { validateAndRepair } = await import('../shared/validate-and-repair.js');
+  const result = await composeFromIntent({
+    intent: ctx.intent,
+    llmAdapter: ctx.llmAdapter || null,
+    maxAttempts: 2,
+  });
+
+  // TKT-0009: composeFromIntent now returns a real component array
+  // (`result.template`) whenever it can, instead of only an HTML string —
+  // use it directly; the pre-fix fallback (a single node carrying an
+  // UNREGISTERED `component: 'article'` type) only fires if transpilation
+  // itself somehow produced nothing, which should not happen in practice.
+  const messages = result.template
+    ? [{ type: 'updateComponents', components: result.template }]
+    : result.html
+      ? [{ type: 'updateComponents', components: [{ id: 'chunk-root', component: 'article', html: result.html }] }]
+      : [];
+
+  // Full schema/catalog/anti-pattern conformance — the same final pass
+  // every other engine runs (see validate-and-repair.js). Validate-only:
+  // no natural repair target here (the LLM authored a slot-binding PLAN,
+  // not this A2UI JSON directly) — chunk-composer's own `validatePlan`
+  // is this engine's repair-relevant check and already ran upstream.
+  const schemaCheck = messages.length ? await validateAndRepair({ messages }) : { valid: false, validation: { score: 0 } };
+
+  return {
+    executionId: ctx.executionId,
+    messages,
+    validation: schemaCheck.validation,
+    strategy: result.source === 'retrieval' ? 'chunk-retrieval' : 'chunk-synthesis',
+    engine: 'chunk-zettel',
+    _debug: {
+      plan: result.plan || null,
+      warnings: result.warnings || [],
+      scopeDrift: result.scopeDrift || null,
+      schemaValid: schemaCheck.valid,
+    },
+  };
+}
+
+// REQ-01 (spec-factory-dx-ws4-acceptance): the schema+catalog exit gate
+// every default `auto` run gets even when the caller supplies none — the
+// same validators the adia-producer's always-on gate composes
+// (packages/genui/adia-producer/exit-gate.js#acceptDialectCandidate), reused
+// directly rather than importing that consumer's module (a different
+// consumer — that gate's `wireFormat`/envelope-translation concerns don't
+// belong here). Lazy-imported for the same node:fs/browser-safety reason
+// zettel is (validator.js and catalog-validator.js are both server-side-only
+// in practice: the catalog check reads corpus JSON off disk).
+async function defaultAcceptanceGate(result, callCtx) {
+  const messages = result?.messages;
+  if (!Array.isArray(messages) || messages.length === 0) return false;
+  const { validateSchema } = await import('@adia-ai/a2ui/validate');
+  const { validateMessages: validateCatalog } = await import('../../validate/catalog-validator.js');
+  const schema = validateSchema(messages, callCtx);
+  if (!schema.valid) return false;
+  const catalog = await validateCatalog(messages);
+  return catalog.valid;
+}
+
+// gh#664: `auto` is the whole ladder as one engine — zettel -> free-form ->
+// monolithic-instant -> monolithic-pro, declared in cascade.js as an
+// `@adia-ai/agent` workflow. It is an ENGINE rather than a separate export
+// so every existing caller reaches it the way it reaches the others
+// (`generateUI({ engine: 'auto' })`, `pick({ engine: 'auto' })`), and so it
+// inherits the reserved-name protection below.
+//
+// Lazy import for the same reason zettel is lazy — and because cascade.js
+// imports ENGINES from this module, so a static import here would be a
+// load-time cycle.
+async function generateAutoAdapter(ctx) {
+  const { runCascade, escalationsOf } = await import('./cascade.js');
+  // REQ-01: a caller-supplied ctx.gate is ANDed with the default gate, never
+  // a replacement — a lax caller gate cannot re-open the schema+catalog
+  // seam. No caller gate → the default alone runs.
+  const callerGate = ctx.gate;
+  const gate = callerGate
+    ? async (result, gateCtx) => (await defaultAcceptanceGate(result, gateCtx)) && (await callerGate(result, gateCtx))
+    : defaultAcceptanceGate;
+  const outcome = await runCascade(ctx, {
+    ...(ctx.ladder ? { ladder: ctx.ladder } : {}),
+    gate,
+    ...(ctx.onStep ? { emit: ctx.onStep } : {}),
+  });
+  const result = outcome.result;
+  return {
+    ...result,
+    executionId: result.executionId ?? ctx.executionId,
+    engine: result.engine ?? outcome.step,
+    // The ladder's own record of what it tried and why it climbed — the
+    // `{from, to, trigger}` shape trace consumers already render.
+    escalations: escalationsOf(outcome),
+  };
+}
+
+// REQ-04 (spec-factory-dx-ws4-acceptance): the canonical consumer-facing
+// projection of an ENGINES[*] result — every field a caller may render,
+// including `acceptance` (REQ-03). A serialization boundary (the MCP
+// `generate_ui` tool, the HTTP `/api/generate` proxy) that hand-rolls its
+// own field whitelist silently drops a newly added first-class field
+// (REQ-04's falsifier); consumers should build their response off THIS
+// projection instead of restating the field list.
+export function projectEngineResult(result, fallbackEngine) {
+  return {
+    engine: result?.engine ?? fallbackEngine,
+    executionId: result?.executionId,
+    strategy: result?.strategy,
+    messages: result?.messages,
+    validation: result?.validation,
+    suggestions: result?.suggestions,
+    composition: result?.composition,
+    fragments_used: result?.fragments_used,
+    sessionTurns: result?.sessionTurns,
+    acceptance: result?.acceptance,
+  };
+}
+
+export const ENGINES = {
+  'auto':                generateAutoAdapter,
+  'monolithic-instant':  generateInstantAdapter,
+  'monolithic-pro':      generateProAdapter,
+  'monolithic-thinking': generateThinkingAdapter,
+  'zettel':              generateZettelAdapter,
+  'chunk-zettel':        generateChunkZettelAdapter,
+  'free-form':           generateFreeFormAdapter,
+};
+
+/**
+ * Register a third-party generation engine at runtime (OD-5 plugin path).
+ *
+ * Contract:
+ *   generate(ctx) → Promise<{ executionId, messages, validation, strategy?, suggestions?, engine }>
+ *
+ *   ctx = { intent, executionId, storeId, llmAdapter, sessionId, catalog? }
+ *
+ * Built-in engine names (`monolithic-*`, `zettel`) are reserved and cannot be
+ * overwritten. Custom engines are dispatched via `pick({ engine: name })` —
+ * mode is ignored for custom engines unless the implementation uses it.
+ *
+ *   @example
+ *   import { registerEngine } from '@adia-ai/gen-ui';
+ *   registerEngine('my-hybrid', async (ctx) => {
+ *     const result = await myCustomPipeline(ctx.intent);
+ *     return { executionId: ctx.executionId, messages: result.messages,
+ *              validation: { score: result.score }, strategy: 'hybrid',
+ *              engine: 'my-hybrid' };
+ *   });
+ *   generateUI({ engine: 'my-hybrid', intent: '...' });
+ */
+const RESERVED = new Set(['monolithic', 'monolithic-instant', 'monolithic-pro', 'monolithic-thinking', 'zettel', 'chunk-zettel', 'free-form', 'auto']);
+
+export function registerEngine(name, generateFn) {
+  if (typeof name !== 'string' || !name.length) {
+    throw new Error('registerEngine: name must be a non-empty string');
+  }
+  if (RESERVED.has(name)) {
+    throw new Error(`registerEngine: "${name}" is a reserved built-in engine name`);
+  }
+  if (typeof generateFn !== 'function') {
+    throw new Error('registerEngine: generateFn must be a function');
+  }
+  ENGINES[name] = generateFn;
+}
+
+/**
+ * Remove a previously-registered custom engine. Reserved built-ins are
+ * protected — this throws rather than silently noop-ing on a reserved name.
+ */
+export function unregisterEngine(name) {
+  if (RESERVED.has(name)) {
+    throw new Error(`unregisterEngine: "${name}" is a reserved built-in engine name`);
+  }
+  return delete ENGINES[name];
+}
+
+/**
+ * Pick the right engine function for an `{ engine, mode }` pair.
+ * Dispatch order:
+ *   1. Custom-registered name → direct lookup
+ *   2. engine === 'zettel' → zettel adapter
+ *   3. `monolithic-${mode}` → monolithic variant
+ *   4. Fallback → monolithic-instant
+ */
+export function pick({ engine = 'monolithic', mode = 'instant' } = {}) {
+  // Custom engines have priority over built-in name-parsing.
+  if (engine && engine !== 'monolithic' && ENGINES[engine]) return ENGINES[engine];
+  if (engine === 'zettel') return ENGINES.zettel;
+  const key = `monolithic-${mode}`;
+  return ENGINES[key] || ENGINES['monolithic-instant'];
+}
+
+/** Introspection for tooling / docs. */
+export function listEngines() {
+  return Object.keys(ENGINES);
+}

package/compose/strategies/zettel/_smoke.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/** Smoke test: load library, resolve login-form composition, print template. */
+import { loadAll, getAllCompositions, searchAll, getComposition } from './composition-library.js';
+import { resolveComposition } from './composer.js';
+
+const boot = loadAll();
+console.log('boot:', boot);
+
+console.log('\n=== Compositions ===');
+for (const c of getAllCompositions()) console.log(` - ${c.name} (${c.domain})`);
+
+console.log('\n=== Search: "login" ===');
+console.log(searchAll('login form password', { limit: 5 }));
+
+console.log('\n=== Search: "card header title" ===');
+console.log(searchAll('card header title', { limit: 5 }));
+
+console.log('\n=== Resolve login-form ===');
+const comp = getComposition('login-form');
+const resolved = resolveComposition(comp);
+console.log(`resolved ${resolved.length} nodes:`);
+for (const n of resolved) {
+  const kids = n.children ? `→[${n.children.join(',')}]` : '';
+  const text = n.textContent ? ` "${n.textContent}"` : '';
+  const label = n.label ? ` label="${n.label}"` : '';
+  console.log(`  ${n.id.padEnd(20)} ${n.component}${label}${text} ${kids}`);
+}