@qontinui/shared-types 0.2.2 → 0.2.4

package/src/tauri-events/_api.ts

@@ -0,0 +1,90 @@
+/**
+ * Tauri Event Payload Types
+ *
+ * Wire-format types for payloads emitted on Tauri event channels by the
+ * runner. Use these to type the generic parameter of `listen<T>(...)` so
+ * future Rust serde renames (e.g. snake_case → camelCase) and shape
+ * changes break the TypeScript build instead of silently dropping events
+ * at the listener guard.
+ *
+ * ## Adjacently-tagged envelope (`AppEvent`)
+ *
+ * Most runner events are variants of the `AppEvent` enum, which is
+ * serialized via `#[serde(tag = "event_type", content = "data")]`. The
+ * wire payload is therefore `{ event_type: "<VariantName>", data: { ... } }`
+ * and consumers MUST read `event.payload.data.<field>` (NOT
+ * `event.payload.<field>`). The `AppEvent` discriminated union below
+ * encodes that envelope; reaching `data.<field>` after narrowing by
+ * `event_type` is type-safe.
+ *
+ * ## Direct-payload events
+ *
+ * A handful of events bypass `AppEvent` and emit a payload struct
+ * directly:
+ *  - `terminal-output` → `TerminalOutputEvent`
+ *  - `terminal-exit` → `TerminalExitEvent`
+ *  - `terminal-created` → `TerminalInfo`
+ *  - `finding_detected` / `finding_resolved` → wrap a `RunnerFinding`
+ *    inside the `AppEvent` envelope's `data.finding` field as untyped
+ *    JSON; consumers should cast `data.finding as RunnerFinding`.
+ *
+ * Source of truth:
+ *  - `AppEvent`: `qontinui-runner/src-tauri/src/event_system/types.rs`
+ *  - Terminal events: `qontinui-schemas/rust/src/terminal.rs`
+ *  - `RunnerFinding`: `qontinui-runner/src-tauri/src/tauri_event_payloads.rs`
+ *
+ * Regenerate via `cd qontinui-runner && npm run gen-events`.
+ */
+
+export type { AppEvent } from "../generated/AppEvent";
+
+// ── Terminal events (direct payloads, not wrapped in AppEvent) ──
+export type { TerminalInfo } from "../generated/TerminalInfo";
+export type { TerminalOutputEvent } from "../generated/TerminalOutputEvent";
+export type { TerminalExitEvent } from "../generated/TerminalExitEvent";
+
+// ── Runner-local finding payload (carried inside AppEvent::FindingDetected /
+//    AppEvent::FindingResolved as `data.finding`). Distinct from
+//    `qontinui_types::verification::Finding`. ──
+export type { RunnerFinding } from "../generated/RunnerFinding";
+export type { RunnerFindingCodeContext } from "../generated/RunnerFindingCodeContext";
+export type { RunnerFindingUserInput } from "../generated/RunnerFindingUserInput";
+
+// ── WS relay envelopes (runner→backend) and backend→client status events.
+//    Discriminated unions tagged on `type`. Source of truth lives in
+//    `qontinui-runner/src-tauri/src/relay_envelopes.rs`; backend-originated
+//    events mirror `qontinui-web/backend/app/services/runner/event_publisher.py`. ──
+export type { RunnerRelayMessage } from "../generated/RunnerRelayMessage";
+export type { RunnerStatusEvent } from "../generated/RunnerStatusEvent";
+export type { RunnerConnectedConnection } from "../generated/RunnerConnectedConnection";
+
+// ── Dev-only seed-finding payload (`dev:seed-finding` Tauri event from
+//    `commands/dev_findings.rs`). Sibling to the camelCase RunnerFinding
+//    fields so the TS listener can spread them straight into a Finding. ──
+export type { DevSeedFindingPayload } from "../generated/DevSeedFindingPayload";
+
+// ── Recommendation review decision payloads (`review-approved` /
+//    `review-rejected` from `commands/productivity.rs`). One struct
+//    covers both channels — only `userDecision` differs. ──
+export type { RecommendationReviewDecisionPayload } from "../generated/RecommendationReviewDecisionPayload";
+
+// ── Canvas panel payload carried inside AppEvent::CanvasUpdate's
+//    `data.panel` field. Wire-format mirror of the runner's `StoredPanel`
+//    (`mcp/canvas.rs`). The hand-written `CanvasPanel` in `../canvas/index.ts`
+//    pre-dates this generated re-export; both shapes are intentionally
+//    identical. New consumers should prefer this generated import. ──
+export type { CanvasPanel as CanvasUpdatePanel } from "../generated/CanvasPanel";
+
+// ── UI Bridge IPC envelope payloads carried on the `ui-bridge-request` and
+//    `ui-bridge-response` Tauri channels. Stage 1 of the ui-bridge-request
+//    envelope concretization (deferral note in commit ea5d9a61f). The Rust
+//    sources live in `qontinui-schemas/rust/src/app_events.rs`; the runner's
+//    React handler in `src/hooks/ui-bridge-events/types.ts` should pick the
+//    `requestId | type` fields off these to keep the envelope head in sync
+//    while leaving its rich set of optional payload fields hand-written.
+//    Stage 2 (per-payload tagged union of all 171 request_types) is deferred
+//    indefinitely — the existing AssertEqual<AllHandledTypes,
+//    UIBridgeRequestType> + per-hook never checks already enforce dispatch
+//    exhaustiveness from the right end of the pipeline. ──
+export type { UiBridgeRequestEnvelope } from "../generated/UiBridgeRequestEnvelope";
+export type { UiBridgeResponseEnvelope } from "../generated/UiBridgeResponseEnvelope";

package/src/tauri-events/index.ts

@@ -0,0 +1 @@
+export * from "./_api";

package/src/ui-bridge-ir/document.ts

@@ -6,6 +6,7 @@
  * adapter folds it into ui-bridge-auto's `WorkflowConfig`.
  */
 
+import type { IRGroup } from "./group";
 import type { IRMetadata, IRProvenance } from "./primitives";
 import type { IRState } from "./state";
 import type { IRTransition } from "./transition";
@@ -100,6 +101,14 @@ export interface IRDocument {
   /** Transition declarations within this document. */
   transitions: IRTransition[];
 
+  /**
+   * Groups produced by workflow-criteria synthesis (not by IR state authoring).
+   * Synthesis appends to this list; the projection emits them after state-derived
+   * groups in legacy `groups[]` output. Authoring tools should treat this field
+   * as read-only.
+   */
+  synthesizedGroups?: IRGroup[];
+
   /** ID of the initial/starting state, if applicable. */
   initialState?: string;
 }

package/src/ui-bridge-ir/group.ts

@@ -0,0 +1,84 @@
+/**
+ * IR-side group + assertion types.
+ *
+ * The IR's primary authoring surface is `states + transitions`, which the
+ * projection maps into legacy `groups[]` (one group per state). However, the
+ * runner's `workflow_generation::spec_synthesis` pipeline produces "free-form"
+ * groups from acceptance criteria — these are NOT tied to any state and
+ * therefore have no home in the state-derived projection path.
+ *
+ * `IRGroup` is the dedicated channel for those synthesized groups. The IR
+ * carries them in the optional `IRDocument.synthesizedGroups` field; the
+ * projection appends them after the state-derived groups, in declared order,
+ * to preserve byte-stable output.
+ *
+ * The shape mirrors the legacy `SpecGroup` / `SpecAssertion` (canonical
+ * definitions live in `@qontinui/ui-bridge/specs`), but is re-defined here to
+ * keep `qontinui-schemas/ts` free of any runtime dep on `@qontinui/ui-bridge/*`
+ * (per the schemas package's "zero ui-bridge deps" policy).
+ *
+ * Note on field shape: the IR-side `IRAssertion` keeps the legacy assertion's
+ * field types as loose as the synthesis path emits them. Strict consumers
+ * (e.g. the canonical `SpecAssertion` in `@qontinui/ui-bridge/specs`) can
+ * narrow as needed at the consumer boundary; the projection preserves the
+ * objects verbatim into the legacy output.
+ */
+
+/**
+ * IR-side assertion target. Always `type: "search"` for synthesis-emitted
+ * assertions; the wider legacy schema also supports point/region targets but
+ * the IR doesn't express those today.
+ */
+export interface IRAssertionTarget {
+  /** Always `"search"` for synthesis-emitted assertions. */
+  type: string;
+  /**
+   * Free-form criteria object. Kept as a loose record so synthesis can emit
+   * partially-populated criteria without tripping the schema.
+   */
+  criteria: Record<string, unknown>;
+  label: string;
+}
+
+/**
+ * IR-side assertion. Mirrors the legacy `SpecAssertion` shape.
+ */
+export interface IRAssertion {
+  id: string;
+  description: string;
+  category: string;
+  severity: string;
+  assertionType: string;
+  target: IRAssertionTarget;
+  source: string;
+  reviewed: boolean;
+  enabled: boolean;
+  /**
+   * Optional human-readable precondition. Synthesis populates this from the
+   * acceptance criterion's verification hint.
+   */
+  precondition?: string;
+}
+
+/**
+ * IR-side group produced by workflow-criteria synthesis (i.e. NOT derived
+ * from `IRState` annotations). Mirrors the legacy `SpecGroup` shape one-to-one
+ * so the projection can pass it through to legacy `groups[]` without loss.
+ */
+export interface IRGroup {
+  id: string;
+  name: string;
+  description: string;
+  category: string;
+  assertions: IRAssertion[];
+  /**
+   * Provenance of the group itself (typically `"ai-generated"` for synthesis
+   * output, but kept open for future authoring channels).
+   */
+  source?: string;
+  /**
+   * Free-form tags. Synthesis emits e.g. `["workflow-generated",
+   * "acceptance-criteria"]` so downstream tooling can filter.
+   */
+  tags?: string[];
+}

package/src/ui-bridge-ir/index.ts

@@ -18,6 +18,7 @@ export * from "./primitives";
 export * from "./element-criteria";
 export * from "./state";
 export * from "./transition";
+export * from "./group";
 export * from "./document";
 export * from "./adapter";
 export * from "./projection";

package/src/ui-bridge-ir/ir.schema.json

@@ -24,6 +24,10 @@
     "transitions": {
       "type": "array",
       "items": { "$ref": "#/$defs/IRTransition" }
+    },
+    "synthesizedGroups": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/IRGroup" }
     }
   },
   "$defs": {
@@ -230,6 +234,60 @@
         "provenance": { "$ref": "#/$defs/IRProvenance" },
         "crossRefs": { "type": "array", "items": { "$ref": "#/$defs/IRCrossRef" } }
       }
+    },
+    "IRAssertionTarget": {
+      "type": "object",
+      "required": ["type", "criteria", "label"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "type": "string" },
+        "criteria": { "type": "object", "additionalProperties": true },
+        "label": { "type": "string" }
+      }
+    },
+    "IRAssertion": {
+      "type": "object",
+      "required": [
+        "id",
+        "description",
+        "category",
+        "severity",
+        "assertionType",
+        "target",
+        "source",
+        "reviewed",
+        "enabled"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string" },
+        "description": { "type": "string" },
+        "category": { "type": "string" },
+        "severity": { "type": "string" },
+        "assertionType": { "type": "string" },
+        "target": { "$ref": "#/$defs/IRAssertionTarget" },
+        "source": { "type": "string" },
+        "reviewed": { "type": "boolean" },
+        "enabled": { "type": "boolean" },
+        "precondition": { "type": "string" }
+      }
+    },
+    "IRGroup": {
+      "type": "object",
+      "required": ["id", "name", "description", "category", "assertions"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string" },
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "category": { "type": "string" },
+        "assertions": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/IRAssertion" }
+        },
+        "source": { "type": "string" },
+        "tags": { "type": "array", "items": { "type": "string" } }
+      }
     }
   }
 }

package/src/ui-bridge-ir/projection.ts

@@ -179,6 +179,7 @@
 
 import type { IRElementCriteria } from "./element-criteria";
 import type { IRDocument } from "./document";
+import type { IRAssertion, IRGroup } from "./group";
 import type { IRState } from "./state";
 import type { IRTransition, IRTransitionAction, IRWaitSpec } from "./transition";
 
@@ -432,6 +433,55 @@ function buildGroup(state: IRState): LegacyGroup {
   };
 }
 
+/**
+ * Convert an `IRAssertion` (IR-side, free-form criteria) into a `LegacyAssertion`.
+ * The shapes are near-identical; the only meaningful difference is that the
+ * IR-side `target.criteria` is `Record<string, unknown>` while the legacy
+ * shape is `LegacyCriteria` (a typed but extensible record). We pass the
+ * criteria object through verbatim — the open `[key: string]: unknown` index
+ * signature on `LegacyCriteria` accepts any record shape.
+ */
+function synthesizedAssertionToLegacy(assertion: IRAssertion): LegacyAssertion {
+  const target: LegacyAssertionTarget = {
+    type: "search",
+    criteria: assertion.target.criteria as LegacyCriteria,
+    label: assertion.target.label,
+  };
+  const out: LegacyAssertion = {
+    id: assertion.id,
+    description: assertion.description,
+    category: assertion.category,
+    severity: assertion.severity as LegacyAssertion["severity"],
+    assertionType: assertion.assertionType,
+    target,
+    source: assertion.source,
+    reviewed: assertion.reviewed,
+    enabled: assertion.enabled,
+  };
+  if (assertion.precondition !== undefined) {
+    out.precondition = assertion.precondition;
+  }
+  return out;
+}
+
+/**
+ * Convert a synthesized `IRGroup` into a `LegacyGroup`. Mirrors the legacy
+ * shape one-to-one (modulo the free-form criteria pass-through described in
+ * `synthesizedAssertionToLegacy`). The synthesized group always carries a
+ * `source` (synthesis emits `"ai-generated"`); fall back to `"ai-generated"`
+ * for hand-written IR documents that omit it.
+ */
+function synthesizedGroupToLegacy(group: IRGroup): LegacyGroup {
+  return {
+    id: group.id,
+    name: group.name,
+    description: group.description,
+    category: group.category,
+    assertions: group.assertions.map(synthesizedAssertionToLegacy),
+    source: group.source ?? "ai-generated",
+  };
+}
+
 /**
  * Convert an IR transition action into the legacy `process[]` step shape.
  * Renames IR's `type` to legacy `action` (matches the runtime engine
@@ -520,6 +570,14 @@ export function projectIRToBundledPage(doc: IRDocument, notes?: string): LegacyS
   if (doc.metadata?.tags !== undefined) metadata.tags = doc.metadata.tags;
 
   const groups: LegacyGroup[] = doc.states.map(buildGroup);
+  if (doc.synthesizedGroups !== undefined) {
+    // Append synthesis-produced groups AFTER state-derived ones, in declared
+    // order. Byte-stable output (see file header) requires this exact ordering
+    // — anything else breaks `check-spec-pairing` style hashes.
+    for (const g of doc.synthesizedGroups) {
+      groups.push(synthesizedGroupToLegacy(g));
+    }
+  }
   const smStates: LegacyStateMachineState[] = doc.states.map((s) =>
     buildStateMachineState(s, doc.transitions, doc),
   );

package/src/ui-bridge-ir/__tests__/legacy-roster.test.ts

@@ -1,182 +0,0 @@
-/**
- * Legacy spec roster test (Phase A2 fixture gate).
- *
- * Walks the entire `qontinui_parent` monorepo, collects every shipping
- * `*.spec.uibridge.json`, and round-trips each through:
- *
- *     legacy --projectLegacyToIR-->  IR  --projectIRToBundledPage-->  legacy'
- *
- * For each fixture we assert (semantically — not byte-strict):
- *   - same number of groups
- *   - same group ids in input order
- *   - same total assertion count across all groups
- *
- * This is coarse but effective: it catches any data loss in the inverse
- * projection without forcing the inverse to preserve hand-edited assertion
- * ids / severity / category / etc. (which the forward direction regenerates
- * from defaults). Phase A4 will tighten the contract for hand-authored
- * fields.
- *
- * The walker fails fast if it finds < 100 fixtures (canary against a
- * misconfigured directory walk) — current expected count is 121 (96 runner +
- * 19 web + 5 mobile + 2 supervisor) as of 2026-04. The number is allowed to
- * grow; the lower bound just guards against accidentally testing nothing.
- */
-
-import { readdirSync, readFileSync, statSync } from "node:fs";
-import path from "node:path";
-
-import { describe, expect, it } from "vitest";
-
-import {
-  projectIRToBundledPage,
-  projectLegacyToIR,
-  type LegacySpec,
-} from "../projection";
-
-// ---------------------------------------------------------------------------
-// Discovery
-// ---------------------------------------------------------------------------
-
-/**
- * Resolve the monorepo root from the test file's location. The test file
- * lives at `qontinui-schemas/ts/src/ui-bridge-ir/__tests__/`, so five
- * `..` segments take us to `qontinui_parent/`.
- *
- * Use `process.cwd()` as a fallback only when the test runs from outside the
- * usual layout (e.g. CI checkout with renamed parent) — vitest sets cwd to
- * the package root by default.
- */
-const MONOREPO_ROOT = path.resolve(
-  __dirname,
-  "..",
-  "..",
-  "..",
-  "..",
-  "..",
-);
-
-// Directories to skip. Note: do NOT include "build" — Next.js apps have route
-// folders named `build/` (e.g., qontinui-web/frontend/src/app/(app)/build/)
-// that legitimately contain spec fixtures.
-const SKIP_DIRS = new Set([
-  "node_modules",
-  "target",
-  "target-agent",
-  "dist",
-  ".git",
-  ".next",
-  ".venv",
-  "__pycache__",
-  "out",
-]);
-
-/**
- * Recursively walk `root`, collecting every `*.spec.uibridge.json` file.
- * Skips the directory names in `SKIP_DIRS`. Synchronous; the fixture set is
- * small (low hundreds) so we don't bother with worker threads.
- */
-function collectSpecs(root: string): string[] {
-  const out: string[] = [];
-  const stack: string[] = [root];
-  while (stack.length > 0) {
-    const current = stack.pop()!;
-    let entries: import("node:fs").Dirent[];
-    try {
-      entries = readdirSync(current, { withFileTypes: true });
-    } catch {
-      // Permission errors / vanished dirs — skip silently.
-      continue;
-    }
-    for (const entry of entries) {
-      if (SKIP_DIRS.has(entry.name)) continue;
-      const full = path.join(current, entry.name);
-      if (entry.isDirectory()) {
-        stack.push(full);
-      } else if (entry.isFile() && entry.name.endsWith(".spec.uibridge.json")) {
-        out.push(full);
-      } else if (entry.isSymbolicLink()) {
-        // Resolve symlinks defensively — some plugin checkouts use them.
-        try {
-          const stat = statSync(full);
-          if (stat.isDirectory()) {
-            stack.push(full);
-          } else if (stat.isFile() && entry.name.endsWith(".spec.uibridge.json")) {
-            out.push(full);
-          }
-        } catch {
-          // ignore
-        }
-      }
-    }
-  }
-  // Sort for deterministic test ordering.
-  out.sort();
-  return out;
-}
-
-const SPECS = collectSpecs(MONOREPO_ROOT);
-
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
-
-describe("legacy spec roster — discovery sanity", () => {
-  it("finds at least 100 *.spec.uibridge.json files in the monorepo", () => {
-    expect(SPECS.length).toBeGreaterThanOrEqual(100);
-  });
-
-  it("does not include node_modules / dist / target paths", () => {
-    for (const f of SPECS) {
-      expect(f).not.toMatch(/[\\/](?:node_modules|dist|target|\.git)[\\/]/);
-    }
-  });
-});
-
-describe("legacy spec roster — round-trip via IR", () => {
-  // Use it.each so every fixture gets its own test name and failures pinpoint
-  // the exact file. Pre-load each fixture as a tuple for the iterator.
-  const cases: ReadonlyArray<readonly [string, string]> = SPECS.map((p) => [
-    path.relative(MONOREPO_ROOT, p),
-    p,
-  ] as const);
-
-  it.each(cases)("%s round-trips through IR without data loss", (_relpath, full) => {
-    let raw = readFileSync(full, "utf-8");
-    // Strip UTF-8 BOM if present — at least one shipping spec
-    // (settings-security.spec.uibridge.json) was saved with a BOM.
-    if (raw.charCodeAt(0) === 0xfeff) raw = raw.slice(1);
-    const legacy = JSON.parse(raw) as LegacySpec;
-
-    const ir = projectLegacyToIR(legacy);
-    const projected = projectIRToBundledPage(ir);
-
-    // 1. Same number of groups.
-    expect(projected.groups.length).toBe(legacy.groups.length);
-
-    // 2. Same group ids in input order.
-    expect(projected.groups.map((g) => g.id)).toEqual(legacy.groups.map((g) => g.id));
-
-    // 3. Same total assertion count across all groups (coarse data-loss check).
-    const projectedAssertionCount = projected.groups.reduce(
-      (sum, g) => sum + g.assertions.length,
-      0,
-    );
-    const legacyAssertionCount = legacy.groups.reduce(
-      (sum, g) => sum + (Array.isArray(g.assertions) ? g.assertions.length : 0),
-      0,
-    );
-    // The forward projection emits a placeholder assertion for any state with
-    // zero requiredElements. Real legacy fixtures never have zero-assertion
-    // groups, but be defensive: allow projected >= legacy when legacy had
-    // groups with zero assertions.
-    const legacyHasEmptyGroup = legacy.groups.some(
-      (g) => !Array.isArray(g.assertions) || g.assertions.length === 0,
-    );
-    if (legacyHasEmptyGroup) {
-      expect(projectedAssertionCount).toBeGreaterThanOrEqual(legacyAssertionCount);
-    } else {
-      expect(projectedAssertionCount).toBe(legacyAssertionCount);
-    }
-  });
-});