@qontinui/shared-types 0.2.3 → 0.2.4

package/src/tauri-events/_api.ts

@@ -74,3 +74,17 @@ export type { RecommendationReviewDecisionPayload } from "../generated/Recommend
 //    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/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),
   );