@adia-ai/gen-ui 0.8.37

package/compose/strategies/_shared/chunk-loader.js

@@ -0,0 +1,282 @@
+/**
+ * Dual-environment chunk loader — Node + browser.
+ *
+ * Mirrors the dual-environment loading approach historically used by
+ * pattern-library.js (retired §64) so the gen-UI training chunks at
+ * packages/gen-ui/corpus/chunks/*.json are reachable from BOTH server-side
+ * engines (monolithic-pro via /api/generate's Node process) AND
+ * browser-side engines (monolithic-pro called directly from
+ * gen-ui playground's IIFE).
+ *
+ * The existing packages/gen-ui/corpus/scripts/chunk-library.js is Node-only
+ * (uses node:fs / readdirSync). This module exists so monolithic-pro can
+ * search + fetch chunks WITHOUT pulling node:fs into the browser bundle.
+ *
+ * Surface:
+ *   - searchChunks(query, { kind, limit }): keyword-ranked chunk matches
+ *   - getChunk(name): full chunk record by name
+ *
+ * Both are async because the browser path uses dynamic imports.
+ */
+
+const IS_NODE =
+  typeof process !== 'undefined' &&
+  typeof process.versions?.node === 'string';
+
+// ── State ──────────────────────────────────────────────────────────
+let _state = null;       // { chunks: Map<name, record>, byKind: Map<kind, Set<name>> }
+let _loadPromise = null;
+
+// ── Browser glob ───────────────────────────────────────────────────
+// Vite rewrites this CALL at transform time. On the static deploy (raw
+// source, no Vite) the call hits the real `import.meta.glob` — which is
+// undefined at runtime — and throws → caught → `_globModules` null → fetch
+// branch. `import.meta.glob` is a compile-time macro, NOT a runtime
+// function, so `typeof import.meta.glob` is undefined in BOTH Vite and
+// static — the only reliable discriminator is whether this CALL yielded
+// loaders. See composition-library.js for the full tri-mode rationale.
+let _globModules = null;
+if (!IS_NODE) {
+  try {
+    _globModules = import.meta.glob('../../../corpus/chunks/*.json', {
+      query: '?raw',
+      import: 'default',
+    });
+  } catch {
+    // No Vite transform here (static deploy) — fall back to the fetch branch.
+  }
+}
+const HAS_VITE_GLOB =
+  !IS_NODE && !!_globModules && Object.keys(_globModules).length > 0;
+
+// Relative-to-module corpus base for the static branch (same path the glob
+// trusts; mount-point-independent). Verified 2026-06-10.
+const _CORPUS_CHUNKS_BASE =
+  !IS_NODE && !HAS_VITE_GLOB
+    ? new URL('../../../corpus/chunks/', import.meta.url)
+    : null;
+
+// ── Public API ─────────────────────────────────────────────────────
+async function _load() {
+  if (_state) return _state;
+  if (_loadPromise) return _loadPromise;
+  _loadPromise = (async () => {
+    if (IS_NODE) {
+      _state = await _loadNode();
+    } else if (HAS_VITE_GLOB) {
+      _state = await _loadBrowser();
+    } else {
+      _state = await _loadStatic();
+    }
+    return _state;
+  })();
+  return _loadPromise;
+}
+
+/**
+ * Static-browser loader — fetch `_index.json` for keyword scoring. The
+ * index carries name/kind/primary/nested/pages (everything `searchChunks`
+ * ranks on); chunk BODIES (html / template) are fetched lazily by
+ * `getChunk` so page-load is one request, not 339. Degrades to an empty
+ * corpus (not a throw) on fetch / parse failure.
+ */
+async function _loadStatic() {
+  const chunks = new Map();
+  const byKind = new Map();
+  if (!_CORPUS_CHUNKS_BASE) return { chunks, byKind };
+  let index;
+  try {
+    const res = await fetch(new URL('_index.json', _CORPUS_CHUNKS_BASE));
+    if (!res.ok) return { chunks, byKind };
+    index = await res.json();
+  } catch {
+    return { chunks, byKind };
+  }
+  const entries = Array.isArray(index?.chunks) ? index.chunks : [];
+  for (const entry of entries) {
+    if (!entry?.name) continue;
+    // Normalize the index entry to the per-chunk record shape `searchChunks`
+    // expects: `pages` (array) → `source`/`page` (string). `_bodyUrl` +
+    // `_hydrated` mark the record for lazy body-fetch in getChunk.
+    const rec = {
+      ...entry,
+      source: Array.isArray(entry.pages) ? entry.pages[0] : (entry.source || entry.page || ''),
+      _bodyUrl: new URL(`${entry.name}.json`, _CORPUS_CHUNKS_BASE).href,
+      _hydrated: false,
+    };
+    chunks.set(rec.name, rec);
+    const kind = rec.kind || 'block';
+    if (!byKind.has(kind)) byKind.set(kind, new Set());
+    byKind.get(kind).add(rec.name);
+  }
+  return { chunks, byKind };
+}
+
+async function _loadNode() {
+  const fs = await import(/* @vite-ignore */ 'node:fs/promises');
+  const path = await import(/* @vite-ignore */ 'node:path');
+  const url = await import(/* @vite-ignore */ 'node:url');
+
+  const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+  const chunksDir = path.resolve(__dirname, '..', '..', '..', 'corpus', 'chunks');
+
+  const chunks = new Map();
+  const byKind = new Map();
+  let entries;
+  try {
+    entries = await fs.readdir(chunksDir);
+  } catch {
+    return { chunks, byKind };
+  }
+  for (const file of entries) {
+    if (file === '_index.json' || !file.endsWith('.json')) continue;
+    try {
+      const raw = await fs.readFile(path.join(chunksDir, file), 'utf8');
+      const rec = JSON.parse(raw);
+      if (!rec?.name) continue;
+      chunks.set(rec.name, rec);
+      const kind = rec.kind || 'block';
+      if (!byKind.has(kind)) byKind.set(kind, new Set());
+      byKind.get(kind).add(rec.name);
+    } catch {
+      // Skip malformed chunks rather than fail the whole load
+    }
+  }
+  return { chunks, byKind };
+}
+
+async function _loadBrowser() {
+  const chunks = new Map();
+  const byKind = new Map();
+  if (!_globModules) return { chunks, byKind };
+
+  await Promise.all(
+    Object.entries(_globModules).map(async ([path, loader]) => {
+      if (path.endsWith('/_index.json')) return;
+      try {
+        const raw = await loader();
+        const rec = JSON.parse(raw);
+        if (!rec?.name) return;
+        chunks.set(rec.name, rec);
+        const kind = rec.kind || 'block';
+        if (!byKind.has(kind)) byKind.set(kind, new Set());
+        byKind.get(kind).add(rec.name);
+      } catch {
+        // Skip malformed
+      }
+    })
+  );
+
+  return { chunks, byKind };
+}
+
+/**
+ * Keyword-rank chunks against a query. Mirrors the scoring shape of
+ * corpus/scripts/chunk-library.js so behavior is consistent regardless
+ * of which loader was used.
+ *
+ * Scoring (per chunk):
+ *   +3  query word in name (exact part match)
+ *   +2  query word in primary tag
+ *   +1  query word in nested chunk name
+ *   +1  query word in source page path
+ *
+ * @param {string} query   — user intent
+ * @param {object} [opts]  — { kind?: 'block'|'page'|'panel', limit?: number }
+ * @returns {Promise<Array<{ name, score, kind, primary, record }>>}
+ */
+export async function searchChunks(query, { kind, limit = 20 } = {}) {
+  if (!query || typeof query !== 'string') return [];
+  const { chunks } = await _load();
+  if (!chunks.size) return [];
+
+  const words = query.toLowerCase().split(/\s+/).filter((w) => w.length > 2);
+  if (!words.length) return [];
+
+  const candidates = [];
+  for (const [name, rec] of chunks) {
+    if (kind && rec.kind !== kind) continue;
+    let score = 0;
+    const nameLow = name.toLowerCase();
+    const primary = (rec.primary || '').toLowerCase();
+    const source = (rec.source || rec.page || '').toLowerCase();
+    const nested = (rec.nested || []).map((n) => n.toLowerCase());
+
+    for (const w of words) {
+      if (nameLow.includes(w)) score += 3;
+      if (primary && primary.includes(w)) score += 2;
+      for (const n of nested) {
+        if (n.includes(w)) {
+          score += 1;
+          break;
+        }
+      }
+      if (source && source.includes(w)) score += 1;
+    }
+    if (score > 0) {
+      candidates.push({ name, score, kind: rec.kind, primary: rec.primary, record: rec });
+    }
+  }
+
+  candidates.sort((a, b) => b.score - a.score);
+  return candidates.slice(0, limit);
+}
+
+/**
+ * Fetch a chunk record by name.
+ * @param {string} name
+ * @returns {Promise<object|null>}
+ */
+export async function getChunk(name) {
+  if (!name) return null;
+  const { chunks } = await _load();
+  const rec = chunks.get(name) || null;
+  if (!rec) return null;
+  // Static-browser: the record came from `_index.json` (scoring fields only).
+  // Fetch + merge the full body (html / template / slots / attrs) on first
+  // access, then cache. No-op in Node / Vite (full record already loaded).
+  if (rec._bodyUrl && !rec._hydrated) {
+    try {
+      const res = await fetch(rec._bodyUrl);
+      if (res.ok) {
+        const body = await res.json();
+        Object.assign(rec, body);
+      }
+    } catch {
+      // Leave the scoring-only record; consumers must tolerate a missing body.
+    }
+    rec._hydrated = true; // don't retry on every access, even if the fetch failed
+  }
+  return rec;
+}
+
+/**
+ * Recursively expand a chunk's nested-chunk references into a flat array
+ * of chunk records. Useful for materializing the "full structural context"
+ * of a top-level chunk into a single prompt-injection payload.
+ *
+ * Cycle-safe: tracks visited names. Depth-limited to prevent runaway.
+ *
+ * @param {string|object} nameOrRecord
+ * @param {object} [opts] — { maxDepth?: 4 }
+ * @returns {Promise<Array<object>>} — flat list of resolved chunk records, root first
+ */
+export async function expandChunkGraph(nameOrRecord, { maxDepth = 4 } = {}) {
+  const visited = new Set();
+  const out = [];
+
+  async function walk(item, depth) {
+    if (depth > maxDepth) return;
+    const rec = typeof item === 'string' ? await getChunk(item) : item;
+    if (!rec || visited.has(rec.name)) return;
+    visited.add(rec.name);
+    out.push(rec);
+
+    for (const childName of rec.nested || []) {
+      await walk(childName, depth + 1);
+    }
+  }
+
+  await walk(nameOrRecord, 0);
+  return out;
+}

package/compose/strategies/cascade.d.ts

@@ -0,0 +1,67 @@
+/** The engine context registry.js's adapters take. */
+export interface EngineContext {
+  intent: string;
+  executionId?: string;
+  storeId?: string | null;
+  llmAdapter?: unknown;
+  sessionId?: string | null;
+  analysis?: unknown;
+  priorComponentsFromPayload?: unknown[] | null;
+  context?: unknown;
+  model?: string;
+}
+
+export interface CascadeOptions {
+  /** Engine names, cheapest first. Defaults to ENGINE_LADDER. */
+  ladder?: string[];
+  /** Extra async accept check for a result the escalation rule accepted. */
+  gate?: (result: any, ctx: EngineContext) => boolean | Promise<boolean>;
+  name?: string;
+}
+
+export interface CascadeAttempt {
+  step: string;
+  accepted: boolean;
+  result: any;
+  /** The verdict code that rejected this attempt — a `judgeEngineResult`
+   *  feedback code, or `'gate-rejected'` from the workflow exit gate. */
+  reason?: string;
+  detail?: string;
+  data?: unknown;
+  round: number;
+  gateRejected?: boolean;
+}
+
+export interface CascadeOutcome {
+  result: any;
+  step: string | null;
+  accepted: boolean;
+  attempts: CascadeAttempt[];
+}
+
+export interface Escalation {
+  from: string;
+  to: string;
+  trigger: string;
+}
+
+export const ENGINE_LADDER: string[];
+
+export function defineCascade(opts?: CascadeOptions): {
+  name: string;
+  steps: Array<{
+    name: string;
+    run: (ctx: any) => any;
+    until?: (result: any, ctx: any) => { accepted: boolean; reason?: string; detail?: string; data?: unknown };
+  }>;
+  /** Present only when a `gate` was supplied — the workflow-level exit gate
+   *  every non-terminal accepted result passes through. */
+  exitGate?: (result: any, ctx: any) => Promise<{ accepted: boolean; reason?: string }>;
+};
+
+export function runCascade(
+  ctx: EngineContext,
+  opts?: CascadeOptions & { emit?: (event: unknown) => void },
+): Promise<CascadeOutcome>;
+
+export function escalationsOf(outcome: CascadeOutcome): Escalation[];

package/compose/strategies/cascade.js

@@ -0,0 +1,165 @@
+/**
+ * The engine escalation ladder, declared as an `@adia-ai/agent` workflow
+ * (gh#664).
+ *
+ * zettel → free-form → monolithic-instant → monolithic-pro, cheapest first,
+ * each step's `until` predicate carrying the escalation rule
+ * (`escalation.js`'s `accepts`) and the last step terminal. The ladder is
+ * DATA — `ENGINE_LADDER` — so a consumer can read the order without running
+ * it, and the harness's `WorkflowResult.attempts` is the escalation trace.
+ *
+ * Reserved engine names (registry.js's `RESERVED`) are the step names
+ * verbatim: a step IS the engine, never a reinterpretation of it. Engines
+ * are resolved out of `ENGINES` at RUN time, not at module load, so a
+ * `registerMonolithicEngines()` that happens later (core/generator.js does
+ * it at ITS load) still wires up.
+ *
+ * The optional `gate` — an async accept check the caller supplies, e.g. the
+ * schema + catalog exit gate — runs after the strategy rule for a step that
+ * would otherwise be accepted. That is why the harness's `until` had to
+ * become awaitable (gh#664 contract change): the real acceptance test for a
+ * generated surface reads catalog JSON off disk.
+ *
+ * gh#665: the gate is no longer restated inside every step's `until` — it
+ * is declared ONCE as the workflow's `exitGate`, the seam the harness grew
+ * for exactly this. The ladder's floor keeps its floor property: a terminal
+ * step (no `until`) is not exit-gated, matching the pre-harness cascades,
+ * which returned monolithic-pro's output whatever it was. Rejections now
+ * carry a REASON (`judgeEngineResult`'s feedback code, or `gate-rejected`)
+ * on the attempt, so `escalationsOf` reads the recorded trigger instead of
+ * recomputing it.
+ */
+
+import { defineWorkflow, runWorkflow } from '@adia-ai/agent';
+
+import { ENGINES } from './registry.js';
+import { judgeEngineResult } from './escalation.js';
+
+/** The ladder, cheapest tier first. Names are reserved engine names. */
+export const ENGINE_LADDER = ['zettel', 'free-form', 'monolithic-instant', 'monolithic-pro'];
+
+/**
+ * @param {string} name
+ * @param {import('@adia-ai/agent').WorkflowContext} wctx — the harness
+ *   context: `input` is what the run is ABOUT (intent, prior components),
+ *   `services` is what it may USE (the LLM adapter). Engines still take one
+ *   flat ctx, so this is where the two channels are recombined; the adapter
+ *   falls back to `input.llmAdapter` for a caller that hasn't moved yet.
+ */
+function runEngine(name, wctx) {
+  const fn = ENGINES[name];
+  if (typeof fn !== 'function') {
+    throw new Error(`cascade: ENGINES["${name}"] is not registered`);
+  }
+  const ctx = wctx.input;
+  return fn({
+    intent: ctx.intent,
+    executionId: ctx.executionId,
+    storeId: ctx.storeId ?? ctx.executionId,
+    llmAdapter: wctx.services?.llmAdapter ?? ctx.llmAdapter ?? null,
+    sessionId: ctx.sessionId,
+    analysis: ctx.analysis ?? null,
+    priorComponentsFromPayload: ctx.priorComponentsFromPayload ?? null,
+    context: ctx.context,
+    model: ctx.model,
+  });
+}
+
+/**
+ * Build the cascade workflow.
+ *
+ * @param {object} [opts]
+ * @param {string[]} [opts.ladder=ENGINE_LADDER] — engine names, cheapest first.
+ * @param {(result: object, ctx: object) => boolean | Promise<boolean>} [opts.gate]
+ *   — extra accept check for a step the strategy rule already accepted
+ *   (the schema + catalog exit gate lives here).
+ * @param {string} [opts.name='generate-ui']
+ */
+export function defineCascade({ ladder = ENGINE_LADDER, gate, name = 'generate-ui' } = {}) {
+  const steps = ladder.map((engineName, i) => {
+    const terminal = i === ladder.length - 1;
+    return {
+      name: engineName,
+      run: (ctx) => runEngine(engineName, ctx),
+      // The terminal step is the ladder's floor: its result is returned
+      // whatever it is, exactly as the pre-harness cascades did when
+      // monolithic-pro was reached. Omitting `until` is how the harness
+      // spells that — and it also exempts the floor from the exit gate.
+      ...(terminal ? {} : {
+        // The strategy rule, as a VERDICT: the feedback code that made the
+        // ladder climb travels with the attempt (gh#665) instead of being
+        // recomputed downstream.
+        until: (result) => {
+          const judged = judgeEngineResult(result);
+          return judged.ok
+            ? { accepted: true }
+            : {
+                accepted: false,
+                reason: judged.feedback[0]?.code ?? 'rejected',
+                detail: judged.feedback[0]?.message,
+                data: judged.feedback,
+              };
+        },
+      }),
+    };
+  });
+  return defineWorkflow(name, steps, gate
+    ? {
+        exitGate: async (result, ctx) => {
+          const passed = !!(await gate(result, ctx.input));
+          return passed ? { accepted: true } : { accepted: false, reason: 'gate-rejected' };
+        },
+      }
+    : {});
+}
+
+/**
+ * Run the ladder once for one intent.
+ *
+ * @param {object} ctx — the engine context registry.js's adapters take:
+ *   `{ intent, executionId, storeId, llmAdapter, sessionId, analysis,
+ *      priorComponentsFromPayload, context, model }`
+ * @param {object} [opts] — `defineCascade` options, plus:
+ * @param {(event: object) => void} [opts.emit] — step events.
+ * @returns {Promise<import('@adia-ai/agent').WorkflowResult>} — `result` is
+ *   the winning engine's own result shape; `step` is the engine that won;
+ *   `attempts` is the full escalation trace.
+ */
+export async function runCascade(ctx, opts = {}) {
+  const { emit, ...defineOpts } = opts;
+  return runWorkflow(defineCascade(defineOpts), {
+    input: ctx,
+    // The dependency the ladder USES, on the channel that means "may use"
+    // (gh#665). `input` still carries it too, so an engine context assembled
+    // by an older caller keeps working.
+    services: { llmAdapter: ctx.llmAdapter ?? null },
+    sessionId: ctx.sessionId ?? ctx.executionId ?? 'cascade',
+    ...(emit ? { emit } : {}),
+  });
+}
+
+/**
+ * The escalation trace in the `{from, to, trigger}` shape trace-rendering
+ * consumers already speak (handleAuto.js's reasoning strip).
+ *
+ * The trigger is the REASON the rejecting verdict recorded (gh#665) — no
+ * longer re-judged here, so a gate rejection reads as `gate-rejected`
+ * because that is what happened, not because re-judging found nothing else.
+ * The re-judge survives only as the fallback for an attempt produced by a
+ * boolean-returning predicate, which records no reason.
+ *
+ * @param {import('@adia-ai/agent').WorkflowResult} outcome
+ */
+export function escalationsOf(outcome) {
+  const out = [];
+  for (let i = 0; i < outcome.attempts.length - 1; i++) {
+    const from = outcome.attempts[i];
+    const to = outcome.attempts[i + 1];
+    out.push({
+      from: from.step,
+      to: to.step,
+      trigger: from.reason ?? judgeEngineResult(from.result).feedback?.[0]?.code ?? 'rejected',
+    });
+  }
+  return out;
+}

package/compose/strategies/escalation.d.ts

@@ -0,0 +1,13 @@
+export interface EngineFeedback {
+  code: 'no-emission' | 'non-emission-strategy' | 'schema-invalid' | 'strong-emission-invalid';
+  message: string;
+}
+
+export type EngineVerdict =
+  | { ok: true }
+  | { ok: false; feedback: EngineFeedback[] };
+
+export function isNonEmissionStrategy(strategy: string | undefined): boolean;
+export function isStrongEmissionStrategy(strategy: string | undefined): boolean;
+export function judgeEngineResult(result: unknown): EngineVerdict;
+export function accepts(result: unknown): boolean;

package/compose/strategies/escalation.js

@@ -0,0 +1,132 @@
+/**
+ * Escalation rules — the ONE answer to "did this engine's attempt count as
+ * a hit, or should the ladder climb?"
+ *
+ * The rules used to live in `@genui/adia-producer/outcome-to-verdict.js`
+ * (gh#583), one layer above compose, even though every fact they read
+ * (`strategy` labels, the uniform `{messages, validation}` result shape) is
+ * authored HERE by `strategies/registry.js`'s adapters. gh#664 moves them
+ * down to the layer that owns the shape: compose's own cascade
+ * (`strategies/cascade.js`) and the producer bridge now consult the same
+ * function, so a new strategy label is declared once, next to the adapter
+ * that emits it. `outcome-to-verdict.js` re-exports this module verbatim —
+ * its public name and behavior are unchanged.
+ *
+ * This module is deliberately dependency-free and browser-safe: it reads a
+ * plain result object and returns a verdict. Anything needing disk (the
+ * schema + catalog exit gate) stays with the caller.
+ */
+
+// Strategies an engine returns when it deliberately emitted NOTHING
+// grounded — the zettel/free-form/chunk-zettel equivalent of a hard
+// validation failure. Compiled from registry.js's own adapters and their
+// sibling generator modules' documented strategy labels.
+const NON_EMISSION_STRATEGIES = new Set([
+  'fragment-candidates',    // zettel: retrieval ran, nothing strong enough to emit verbatim
+  'free-form-empty-plan',   // free-form: LLM picked zero ingredients
+  'free-form-hallucinated', // free-form: LLM named ingredients outside the corpus vocabulary
+  'free-form-no-llm',       // free-form: no adapter available, picker never ran
+  'chunk-zettel-empty',     // chunk-zettel: composeFromIntent produced no template/html
+]);
+
+/** @param {string|undefined} strategy */
+export function isNonEmissionStrategy(strategy) {
+  return NON_EMISSION_STRATEGIES.has(strategy);
+}
+
+/**
+ * A strategy treated as a strong-enough hit to accept before any exit gate
+ * runs — the labels the pre-gh#583 consumer cascades checked as
+ * `isStrongMatch` / `freeFormComposed`. An exit gate, where the caller has
+ * one, still runs afterward; this only decides whether the LADDER treats
+ * the round as a hit.
+ */
+const STRONG_EMISSION_STRATEGIES = new Set([
+  'composition-match',
+  'composition-iterated',
+  'free-form-composed',
+]);
+
+/** @param {string|undefined} strategy */
+export function isStrongEmissionStrategy(strategy) {
+  return STRONG_EMISSION_STRATEGIES.has(strategy);
+}
+
+/**
+ * Maps one ENGINES[*] adapter result (registry.js's uniform return shape:
+ * `{ executionId, messages, validation, strategy, engine, ... }`) to a
+ * ladder verdict.
+ *
+ * @param {object} result
+ * @returns {{ ok: true } | { ok: false, feedback: {code: string, message: string}[] }}
+ */
+export function judgeEngineResult(result) {
+  const engineName = result?.engine ?? 'unknown';
+  const strategy = result?.strategy;
+
+  if (!Array.isArray(result?.messages) || result.messages.length === 0) {
+    return {
+      ok: false,
+      feedback: [{
+        code: 'no-emission',
+        message: `engine "${engineName}" emitted no messages (strategy: ${strategy ?? 'none'})`,
+      }],
+    };
+  }
+
+  if (isNonEmissionStrategy(strategy)) {
+    return {
+      ok: false,
+      feedback: [{
+        code: 'non-emission-strategy',
+        message: `engine "${engineName}" signaled non-emission strategy "${strategy}"`,
+      }],
+    };
+  }
+
+  // A strong-match strategy skips the generic no-emission/non-emission
+  // checks above, but REQ-02 (spec-factory-dx-ws4-acceptance) still judges
+  // it on its OWN reported verdict when the engine normalized one — a
+  // strong-emission strategy is no longer a blanket bypass, only a bypass
+  // of the WEAKER schema-invalid fallback below. An engine with no
+  // `validation.valid` field (zettel's strong-emission strategies, until
+  // they normalize one — see the SPEC's REQ-02 non-goal) rides the same
+  // no-valid-field pass-through it always did, caught instead by the
+  // default acceptance gate (registry.js's `generateAutoAdapter`).
+  if (isStrongEmissionStrategy(strategy)) {
+    if (result.validation && result.validation.valid === false) {
+      return {
+        ok: false,
+        feedback: [{
+          code: 'strong-emission-invalid',
+          message: `engine "${engineName}" strong-emission strategy "${strategy}" failed its own validation (score ${result.validation.score ?? 0}/100)`,
+        }],
+      };
+    }
+    return { ok: true };
+  }
+
+  if (result.validation && result.validation.valid === false) {
+    return {
+      ok: false,
+      feedback: [{
+        code: 'schema-invalid',
+        message: `engine "${engineName}" result failed its own validation (score ${result.validation.score ?? 0}/100)`,
+      }],
+    };
+  }
+
+  return { ok: true };
+}
+
+/**
+ * The boolean form — a workflow `until` predicate. `judgeEngineResult` when
+ * you need the feedback entries, this when you only need the fall-through
+ * decision.
+ *
+ * @param {object} result
+ * @returns {boolean}
+ */
+export function accepts(result) {
+  return judgeEngineResult(result).ok === true;
+}