@adia-ai/gen-ui 0.8.37

package/compose/core/pipeline/engine.js

@@ -0,0 +1,289 @@
+/**
+ * PipelineEngine — State machine for generative pipeline executions.
+ *
+ * Manages execution lifecycle: start → stage submissions → completion/abort.
+ * Enforces stage ordering (interpret → analyze → plan → generate → validate → render)
+ * with doNotRedo support for skipping stages on iteration.
+ */
+
+import { STAGES, stageIndex, createStepReport, createEvent } from './types.js';
+
+let nextId = 1;
+
+/** Generate a unique execution ID */
+function uid() {
+  return `exec_${Date.now().toString(36)}_${(nextId++).toString(36)}`;
+}
+
+/**
+ * @typedef {object} PipelineExecution
+ * @property {string} id — Unique execution ID
+ * @property {string} intent — Original user intent
+ * @property {'instant'|'thinking'|'pro'|'god'} mode — Generation mode
+ * @property {'active'|'completed'|'failed'|'aborted'} state — Current state
+ * @property {Map<string, object>} stages — Stage outputs keyed by stage name
+ * @property {object[]} reports — StepReports in order
+ * @property {object[]} events — PipelineEvent log
+ * @property {string[]} doNotRedo — Stages to skip on iteration
+ * @property {number} created — Timestamp
+ * @property {number} updated — Timestamp
+ */
+
+export class PipelineEngine {
+  #executions = new Map();
+
+  /**
+   * Start a new pipeline execution.
+   *
+   * @param {object} opts
+   * @param {string} opts.intent — User intent text
+   * @param {'instant'|'thinking'|'pro'|'god'} [opts.mode='instant'] — Generation mode
+   * @returns {string} — executionId
+   */
+  start({ intent, mode = 'instant' }) {
+    const id = uid();
+    const execution = {
+      id,
+      intent,
+      mode,
+      state: 'active',
+      stages: new Map(),
+      reports: [],
+      events: [],
+      doNotRedo: [],
+      created: Date.now(),
+      updated: Date.now(),
+    };
+
+    execution.events.push(createEvent({
+      executionId: id,
+      type: 'pipeline:start',
+      message: `Pipeline started for intent: "${intent}" (mode: ${mode})`,
+      data: { intent, mode },
+    }));
+
+    this.#executions.set(id, execution);
+    return id;
+  }
+
+  /**
+   * Submit a stage output to an active execution.
+   *
+   * Validates stage ordering: stages must proceed in STAGES order.
+   * Stages listed in doNotRedo are skipped automatically.
+   *
+   * @param {string} executionId
+   * @param {string} stage — Stage name (from STAGES)
+   * @param {object} output — Stage output data
+   * @param {object} [opts] — Options
+   * @param {boolean} [opts.force=false] — Skip ordering check
+   * @param {string[]} [opts.doNotRedo] — Stages to skip on future iterations
+   * @returns {object} — StepReport
+   */
+  submitStage(executionId, stage, output, { force = false, doNotRedo = [] } = {}) {
+    const execution = this.#executions.get(executionId);
+    if (!execution) throw new Error(`Unknown execution: ${executionId}`);
+    if (execution.state !== 'active') throw new Error(`Execution ${executionId} is ${execution.state}, not active`);
+
+    const idx = stageIndex(stage);
+    if (idx === -1) throw new Error(`Unknown stage: ${stage}`);
+
+    // Check ordering: the submitted stage must come after the last completed stage
+    if (!force && execution.stages.size > 0) {
+      const completedStages = [...execution.stages.keys()];
+      const lastCompleted = completedStages[completedStages.length - 1];
+      const lastIdx = stageIndex(lastCompleted);
+
+      // Allow re-submission of same stage (iteration) or next stage
+      if (idx < lastIdx) {
+        throw new Error(`Stage "${stage}" (${idx}) cannot precede already completed "${lastCompleted}" (${lastIdx}). Use force to override.`);
+      }
+
+      // Check for skipped stages (unless they're in doNotRedo)
+      const allSkippable = [...execution.doNotRedo, ...doNotRedo];
+      for (let i = lastIdx + 1; i < idx; i++) {
+        const skippedName = STAGES[i];
+        if (!allSkippable.includes(skippedName) && !execution.stages.has(skippedName)) {
+          throw new Error(`Stage "${skippedName}" must be completed before "${stage}". Add to doNotRedo to skip.`);
+        }
+      }
+    }
+
+    // Record doNotRedo additions
+    if (doNotRedo.length > 0) {
+      for (const s of doNotRedo) {
+        if (!execution.doNotRedo.includes(s)) execution.doNotRedo.push(s);
+      }
+    }
+
+    // Store stage output
+    execution.stages.set(stage, output);
+    execution.updated = Date.now();
+
+    // Create step report
+    const report = createStepReport({
+      stage,
+      status: 'passed',
+      goal: `Complete ${stage} stage`,
+      summary: `Stage "${stage}" submitted successfully`,
+      confidence: output.confidence ?? 0.8,
+      checks: output.checks ?? [],
+      assumptions: output.assumptions ?? [],
+    });
+
+    execution.reports.push(report);
+
+    // Log event
+    execution.events.push(createEvent({
+      executionId,
+      type: 'stage:complete',
+      stage,
+      message: `Stage "${stage}" completed`,
+      data: { output: summarizeOutput(output) },
+    }));
+
+    // Auto-complete if render stage is done
+    if (stage === 'render') {
+      execution.state = 'completed';
+      execution.events.push(createEvent({
+        executionId,
+        type: 'pipeline:complete',
+        message: 'Pipeline completed successfully',
+      }));
+    }
+
+    return report;
+  }
+
+  /**
+   * Get the current state of an execution.
+   *
+   * @param {string} executionId
+   * @returns {object|null} — Execution state snapshot (or null if not found)
+   */
+  getState(executionId) {
+    const execution = this.#executions.get(executionId);
+    if (!execution) return null;
+
+    return {
+      id: execution.id,
+      intent: execution.intent,
+      mode: execution.mode,
+      state: execution.state,
+      completedStages: [...execution.stages.keys()],
+      currentStage: this.#currentStage(execution),
+      reports: [...execution.reports],
+      eventCount: execution.events.length,
+      doNotRedo: [...execution.doNotRedo],
+      created: execution.created,
+      updated: execution.updated,
+    };
+  }
+
+  /**
+   * Get the full event log for an execution.
+   *
+   * @param {string} executionId
+   * @returns {object[]}
+   */
+  getEvents(executionId) {
+    const execution = this.#executions.get(executionId);
+    return execution ? [...execution.events] : [];
+  }
+
+  /**
+   * Get the output from a specific stage.
+   *
+   * @param {string} executionId
+   * @param {string} stage
+   * @returns {object|null}
+   */
+  getStageOutput(executionId, stage) {
+    const execution = this.#executions.get(executionId);
+    if (!execution) return null;
+    return execution.stages.get(stage) ?? null;
+  }
+
+  /**
+   * Abort an active execution.
+   *
+   * @param {string} executionId
+   * @param {string} [reason] — Abort reason
+   */
+  abort(executionId, reason = 'Aborted by caller') {
+    const execution = this.#executions.get(executionId);
+    if (!execution) throw new Error(`Unknown execution: ${executionId}`);
+    if (execution.state !== 'active') return; // already terminal
+
+    execution.state = 'aborted';
+    execution.updated = Date.now();
+
+    execution.events.push(createEvent({
+      executionId,
+      type: 'pipeline:abort',
+      message: reason,
+    }));
+  }
+
+  /**
+   * Mark an execution as failed.
+   *
+   * @param {string} executionId
+   * @param {string} stage — Stage where failure occurred
+   * @param {string} error — Error description
+   */
+  fail(executionId, stage, error) {
+    const execution = this.#executions.get(executionId);
+    if (!execution) throw new Error(`Unknown execution: ${executionId}`);
+    if (execution.state !== 'active') return;
+
+    execution.state = 'failed';
+    execution.updated = Date.now();
+
+    const report = createStepReport({
+      stage,
+      status: 'failed',
+      goal: `Complete ${stage} stage`,
+      summary: error,
+      confidence: 0,
+    });
+    execution.reports.push(report);
+
+    execution.events.push(createEvent({
+      executionId,
+      type: 'stage:fail',
+      stage,
+      message: error,
+    }));
+
+    execution.events.push(createEvent({
+      executionId,
+      type: 'pipeline:fail',
+      message: `Pipeline failed at stage "${stage}": ${error}`,
+    }));
+  }
+
+  /**
+   * Determine the next expected stage for an execution.
+   * @param {object} execution
+   * @returns {string|null}
+   */
+  #currentStage(execution) {
+    if (execution.state !== 'active') return null;
+    const completed = new Set(execution.stages.keys());
+    for (const stage of STAGES) {
+      if (!completed.has(stage) && !execution.doNotRedo.includes(stage)) {
+        return stage;
+      }
+    }
+    return null;
+  }
+}
+
+/** Summarize output for event log (avoid storing huge payloads in events) */
+function summarizeOutput(output) {
+  if (!output) return null;
+  const keys = Object.keys(output);
+  if (keys.length <= 5) return output;
+  return { _keys: keys, _size: JSON.stringify(output).length };
+}

package/compose/core/pipeline/types.js

@@ -0,0 +1,91 @@
+/**
+ * Pipeline Type Definitions — Stage names, StepReport, Handoff, PipelineEvent.
+ *
+ * Pure data constructors for the pipeline state machine.
+ * No dependencies — usable from browser and Node.
+ */
+
+/** Ordered pipeline stages */
+export const STAGES = ['interpret', 'analyze', 'plan', 'generate', 'validate', 'render'];
+
+/** Stage index lookup for ordering enforcement */
+const STAGE_INDEX = Object.fromEntries(STAGES.map((s, i) => [s, i]));
+
+/**
+ * Get the numeric index of a stage (for ordering checks).
+ * @param {string} stage
+ * @returns {number} — -1 if unknown
+ */
+export function stageIndex(stage) {
+  return STAGE_INDEX[stage] ?? -1;
+}
+
+/**
+ * Create a StepReport — per-stage quality gate.
+ *
+ * @param {object} opts
+ * @param {string} opts.stage — Stage name (from STAGES)
+ * @param {'passed'|'failed'|'skipped'} opts.status — Gate result
+ * @param {string} opts.goal — What this stage aimed to accomplish
+ * @param {string} opts.summary — What actually happened
+ * @param {number} opts.confidence — 0-1 confidence score
+ * @param {object[]} [opts.checks] — Individual check results
+ * @param {string[]} [opts.assumptions] — Assumptions made during this stage
+ * @returns {object}
+ */
+export function createStepReport({ stage, status, goal, summary, confidence, checks = [], assumptions = [] }) {
+  return {
+    stage,
+    status,
+    goal,
+    summary,
+    confidence: Math.max(0, Math.min(1, confidence)),
+    checks,
+    assumptions,
+    timestamp: Date.now(),
+  };
+}
+
+/**
+ * Create a Handoff — stage boundary contract.
+ *
+ * @param {object} opts
+ * @param {string} opts.from — Source stage
+ * @param {string} opts.to — Target stage
+ * @param {object} opts.completed — Data produced by the source stage
+ * @param {string[]} [opts.unresolved] — Open questions or gaps
+ * @param {string[]} [opts.doNotRedo] — Stages that should be skipped on iteration
+ * @returns {object}
+ */
+export function createHandoff({ from, to, completed, unresolved = [], doNotRedo = [] }) {
+  return {
+    from,
+    to,
+    completed,
+    unresolved,
+    doNotRedo,
+    timestamp: Date.now(),
+  };
+}
+
+/**
+ * Create a PipelineEvent — event log entry.
+ *
+ * @param {object} opts
+ * @param {string} opts.executionId
+ * @param {'stage:start'|'stage:complete'|'stage:fail'|'stage:skip'|'pipeline:start'|'pipeline:complete'|'pipeline:fail'|'pipeline:abort'} opts.type
+ * @param {string} [opts.stage] — Stage name (if stage-level event)
+ * @param {string} opts.message — Human-readable description
+ * @param {*} [opts.data] — Arbitrary event payload
+ * @returns {object}
+ */
+export function createEvent({ executionId, type, stage = null, message, data = null }) {
+  return {
+    executionId,
+    type,
+    stage,
+    message,
+    data,
+    timestamp: Date.now(),
+  };
+}

package/compose/core/plan-primitives.js

@@ -0,0 +1,120 @@
+/**
+ * R-O11/R-O12's two pure plan primitives, resident in this package (gh#1186).
+ *
+ * WHY A COPY LIVES HERE. `plan-turn.js` used to import these from
+ * `@genui/producer`, which is a VENDORED tree (`packages/genui/*`, synced by
+ * `scripts/build/sync-genui.mjs`, guarded by `check:genui-vendor`) and is
+ * marked `"private": true`. A published `@adia-ai/gen-ui` that depends
+ * on it can never be installed — `npm install` 404s on `@genui/producer`
+ * before any code runs, which is what made `@adia-ai/a2ui-mcp@0.8.35`
+ * uninstallable, not merely unbootable.
+ *
+ * The two functions are pure, dependency-free, and defined by the spec
+ * (docs/ORCHESTRATION.md §Plan envelope) rather than by the vendored tree, so
+ * carrying them here costs nothing at runtime. The vendored tree stays the
+ * upstream reference: `plan-primitives.test.js` runs both implementations
+ * against the same fixtures and fails if they diverge, so the copy cannot
+ * drift silently. That test is monorepo-only — it never ships in the tarball.
+ *
+ * Never hand-edit `packages/genui/producer/dist/plan.js` to match this file;
+ * the sync direction is upstream → vendored tree → here.
+ */
+
+/**
+ * R-O11's one shared predicate: an executor (gen-ui-kit-side) and any
+ * producer-side self-check call THIS function, so "off-manifest" and
+ * "out-of-order" are defined exactly once.
+ *
+ * - A surfaceId executed that the manifest never named → `off-manifest-surface`.
+ * - A surfaceId the manifest named, executed out of the manifest's relative
+ *   order → `out-of-order`.
+ *
+ * Order is checked only over the subsequence of executed ids that ARE in the
+ * manifest — an off-manifest surface is reported once (as off-manifest) and
+ * does not itself break the in-manifest ordering check for the surfaces
+ * around it.
+ */
+export function checkExecutionAgainstPlan(plan, executedSurfaceIds) {
+  const diagnostics = [];
+  const manifestIds = plan.surfaces.map((s) => s.surfaceId);
+  const manifestIndex = new Map(manifestIds.map((id, i) => [id, i]));
+  let lastSeenIndex = -1;
+  for (const surfaceId of executedSurfaceIds) {
+    const idx = manifestIndex.get(surfaceId);
+    if (idx === undefined) {
+      diagnostics.push({
+        code: 'off-manifest-surface',
+        surfaceId,
+        message: `surface "${surfaceId}" was executed but is not in the plan manifest (turn ${plan.turnId})`,
+      });
+      continue;
+    }
+    if (idx < lastSeenIndex) {
+      diagnostics.push({
+        code: 'out-of-order',
+        surfaceId,
+        message:
+          `surface "${surfaceId}" (manifest position ${idx}) was executed after a surface at ` +
+          `manifest position ${lastSeenIndex} — manifest order was not respected`,
+      });
+    } else {
+      lastSeenIndex = idx;
+    }
+  }
+  return diagnostics.length > 0 ? { ok: false, diagnostics } : { ok: true };
+}
+
+/**
+ * R-O12's pure derivation: "what changed" this turn, from the manifest plus
+ * the envelopes actually emitted — never a hand-maintained side channel.
+ * DATA, never an envelope (ruling 3) — the caller renders it as feed chrome,
+ * never mints a surface from it.
+ *
+ * - A surfaceId first touched this turn (not in `previouslyKnownSurfaceIds`) → `new`.
+ * - A previously-known surfaceId touched by updateComponents/updateDataModel
+ *   this turn → `updated`.
+ * - A previously-known surfaceId touched by deleteSurface this turn → `closed`.
+ *
+ * Deterministic ordering: each list preserves the manifest's surface order,
+ * then any emitted surfaceId not in the manifest, in first-seen order — same
+ * inputs always yield deep-equal output.
+ */
+export function synthesizeTurn(plan, emitted, previouslyKnownSurfaceIds) {
+  const known = new Set(previouslyKnownSurfaceIds);
+  const newSet = new Set();
+  const updatedSet = new Set();
+  const closedSet = new Set();
+  for (const event of emitted) {
+    const { surfaceId, kind } = event;
+    if (kind === 'deleteSurface') {
+      if (known.has(surfaceId)) closedSet.add(surfaceId);
+      continue;
+    }
+    if (!known.has(surfaceId)) {
+      newSet.add(surfaceId);
+    } else if (kind === 'updateComponents' || kind === 'updateDataModel') {
+      updatedSet.add(surfaceId);
+    }
+  }
+  const orderedIds = [
+    ...plan.surfaces.map((s) => s.surfaceId),
+    ...emitted.map((e) => e.surfaceId).filter((id) => !plan.surfaces.some((s) => s.surfaceId === id)),
+  ];
+  const dedupOrdered = (set) => {
+    const seen = new Set();
+    const out = [];
+    for (const id of orderedIds) {
+      if (set.has(id) && !seen.has(id)) {
+        seen.add(id);
+        out.push(id);
+      }
+    }
+    return out;
+  };
+  return {
+    turnId: plan.turnId,
+    new: dedupOrdered(newSet),
+    updated: dedupOrdered(updatedSet),
+    closed: dedupOrdered(closedSet),
+  };
+}

package/compose/core/plan-turn.js

@@ -0,0 +1,145 @@
+/**
+ * Plan-envelope executor (gh#648, docs/ORCHESTRATION.md §Plan envelope,
+ * R-O10–R-O13 in the vendored `@genui/producer`).
+ *
+ * gen-ui-kit's own compose engines (`../strategies/registry.js`) never call
+ * the vendored `@genui/producer#produce()` loop — `packages/genui/adia-
+ * producer` deliberately bypasses it (see that package's own header: the
+ * dialect these engines emit isn't genui v1.0's JSONL envelope grammar). So
+ * `deps.plan`/`deps.onPlan` (R-O10, produce()-only) never reach this repo's
+ * engines directly. What DOES travel from the vendored package is the two
+ * PURE primitives R-O11/R-O12 name as the one shared definition:
+ * `checkExecutionAgainstPlan` and `synthesizeTurn`. This module is gen-ui-
+ * kit's own executor built on top of them — the "gen-ui-kit-side executor"
+ * ORCHESTRATION.md's Data section describes.
+ *
+ * Scope ruling (recorded here, not reopened): a multi-surface TURN is a
+ * sequence of otherwise-independent single-surface engine calls — the
+ * engines in registry.js each still produce exactly one surface's messages
+ * per call, unchanged. `runPlannedTurn` is the new caller-facing seam that
+ * strings several such calls together under one inspectable manifest.
+ * Ruling 2 (ORCHESTRATION.md) names zettel/chunk-zettel as the natural
+ * opt-in strategies (retrieval already plans) and exempts monolithic-
+ * instant by design (latency) — `PLAN_STAGE_ENGINES` encodes exactly that
+ * set; `monolithic-instant` (and any engine not listed) throws rather than
+ * silently accepting a plan, so the exemption can't be violated by a
+ * caller forgetting the ruling.
+ */
+// R-O11/R-O12's two primitives live in this package rather than in the
+// vendored (and unpublishable) `@genui/producer` — see plan-primitives.js
+// for why, and plan-primitives.test.js for the anti-drift guard (gh#1186).
+import { checkExecutionAgainstPlan, synthesizeTurn } from './plan-primitives.js';
+import { pick } from '../strategies/registry.js';
+
+export { checkExecutionAgainstPlan, synthesizeTurn };
+
+/** Ruling 2 — the strategies whose retrieval step already plans, so
+ *  surfacing that plan costs nothing new. Not the RESERVED engine-name set
+ *  (registry.js) — this is strictly narrower, and intentionally not every
+ *  reserved name: `monolithic-instant` stays exempt by design. */
+export const PLAN_STAGE_ENGINES = new Set(['zettel', 'chunk-zettel']);
+
+export function isPlanStageEngine(engineName) {
+  return PLAN_STAGE_ENGINES.has(engineName);
+}
+
+/** Thrown when the executed surface order doesn't match the manifest
+ *  (R-O11) — surfaced the same way every other engine's validation failure
+ *  is (`validation`/`diagnostics` on the error, never a silent extra
+ *  render). */
+export class PlanViolationError extends Error {
+  constructor(diagnostics) {
+    super(
+      `plan-turn: execution violated the plan manifest — ` +
+      diagnostics.map((d) => `[${d.code}] ${d.message}`).join('; '),
+    );
+    this.name = 'PlanViolationError';
+    this.diagnostics = diagnostics;
+  }
+}
+
+/**
+ * Runs a multi-surface turn against a caller-supplied plan (R-O10's shape:
+ * the plan is an INPUT, never derived here — deciding *which* surfaces a
+ * turn needs is the caller's planning step, out of this module's scope).
+ *
+ * @param {object} opts
+ * @param {string} opts.turnId
+ * @param {string} opts.engine — must be in PLAN_STAGE_ENGINES
+ * @param {{surfaceId: string, rationale: string, intent: string}[]} opts.surfaces
+ *   — non-empty, in EXECUTION order (R-O11: array order IS execution order)
+ * @param {object} [opts.llmAdapter]
+ * @param {string} [opts.sessionId]
+ * @param {object} [opts.context]
+ * @param {string[]} [opts.previouslyKnownSurfaceIds] — for synthesizeTurn (R-O12)
+ * @param {(plan: {turnId: string, surfaces: {surfaceId: string, rationale: string}[]}) => void} [opts.onPlan]
+ *   — fires exactly once, before the first engine call (mirrors R-O10)
+ * @returns {Promise<{
+ *   plan: object,
+ *   results: {surfaceId: string, result: object}[],
+ *   planCheck: {ok: true} | {ok: false, diagnostics: object[]},
+ *   synthesis: {turnId: string, new: string[], updated: string[], closed: string[]},
+ * }>}
+ */
+export async function runPlannedTurn({
+  turnId,
+  engine,
+  surfaces,
+  llmAdapter,
+  sessionId,
+  context,
+  previouslyKnownSurfaceIds = [],
+  onPlan,
+}) {
+  if (!turnId) throw new Error('runPlannedTurn: opts.turnId is required');
+  if (!Array.isArray(surfaces) || surfaces.length === 0) {
+    throw new Error('runPlannedTurn: opts.surfaces must be a non-empty array (R-O10: non-empty manifest)');
+  }
+  if (!isPlanStageEngine(engine)) {
+    throw new Error(
+      `runPlannedTurn: engine "${engine}" is not plan-stage-eligible — only ` +
+      `${[...PLAN_STAGE_ENGINES].join(', ')} opt in (ruling 2, docs/ORCHESTRATION.md); ` +
+      `monolithic-instant is exempt by design (latency).`,
+    );
+  }
+
+  const plan = {
+    turnId,
+    surfaces: surfaces.map(({ surfaceId, rationale }) => ({ surfaceId, rationale })),
+  };
+
+  // R-O10: the manifest is the turn's first observable output, before any
+  // generation call.
+  onPlan?.(plan);
+
+  const generate = pick({ engine, mode: 'instant' });
+  const results = [];
+  const executedSurfaceIds = [];
+  const emitted = [];
+
+  for (const surface of surfaces) {
+    const result = await generate({
+      intent: surface.intent,
+      llmAdapter,
+      sessionId,
+      context,
+      storeId: sessionId,
+      executionId: surface.surfaceId,
+    });
+    results.push({ surfaceId: surface.surfaceId, result });
+    executedSurfaceIds.push(surface.surfaceId);
+    const kind = previouslyKnownSurfaceIds.includes(surface.surfaceId)
+      ? 'updateComponents'
+      : 'createSurface';
+    emitted.push({ surfaceId: surface.surfaceId, kind });
+  }
+
+  const planCheck = checkExecutionAgainstPlan(plan, executedSurfaceIds);
+  if (!planCheck.ok) {
+    throw new PlanViolationError(planCheck.diagnostics);
+  }
+
+  const synthesis = synthesizeTurn(plan, emitted, previouslyKnownSurfaceIds);
+
+  return { plan, results, planCheck, synthesis };
+}