@qontinui/shared-types 0.2.3 → 0.2.5

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

@@ -1,105 +1,114 @@
-/**
- * Top-level IR document.
- *
- * Versioned (`'1.0'`) container for the states + transitions that describe
- * a page or scope of an application. Build plugins emit this shape; the
- * adapter folds it into ui-bridge-auto's `WorkflowConfig`.
- */
-
-import type { IRMetadata, IRProvenance } from "./primitives";
-import type { IRState } from "./state";
-import type { IRTransition } from "./transition";
-
-/**
- * IR schema version. Bump when the shape changes in a backwards-incompatible
- * way. The adapter rejects documents whose version it does not understand.
- */
-export type IRVersion = "1.0";
-
-/**
- * Axes that the spec <-> IR pairing gate compares. A document's
- * `pairingPolicy.acceptDrift.axes` lists which of these are
- * intentionally allowed to diverge between the legacy spec and the
- * IR's forward projection.
- */
-export type IRPairingAxis = "groupCount" | "groupIds" | "assertionCount";
-
-/**
- * Per-document opt-out for specific spec<->IR pairing axes.
- *
- * The canonical use case is a hand-authored IR that uses a different
- * grouping convention than the legacy spec. Without an explicit policy
- * the pairing gate flags it as a mismatch on every PR, which trains
- * reviewers to ignore the gate. The policy makes the divergence
- * explicit and audit-friendly:
- *
- *   - `axes`     — which fingerprint comparisons to skip
- *   - `reason`   — human-readable justification (required, surfaced in
- *                  `check-spec-pairing` summary output)
- *   - `since`    — ISO date (YYYY-MM-DD) the exemption was added
- *   - `expiresAt` — optional ISO date (YYYY-MM-DD) after which the
- *                   exemption stops applying. Forces periodic
- *                   re-justification: the pairing gate downgrades
- *                   expired exemptions back to ordinary mismatches.
- *
- * Mismatches NOT covered by the listed `axes` still fail the gate as
- * usual — you can accept drift on `groupCount` while still requiring
- * the assertion total to match.
- */
-export interface IRAcceptDriftPolicy {
-  /** Fingerprint axes whose mismatches are tolerated. */
-  axes: IRPairingAxis[];
-  /** Human-readable justification for the exemption. */
-  reason: string;
-  /** ISO date (YYYY-MM-DD) the exemption was added. */
-  since: string;
-  /**
-   * Optional ISO date (YYYY-MM-DD) after which the exemption stops
-   * applying. The pairing gate then surfaces the document as an
-   * ordinary mismatch.
-   */
-  expiresAt?: string;
-}
-
-/**
- * Per-document pairing policy block. Currently only carries
- * `acceptDrift`; future policies (e.g. assertion-shape exemptions)
- * can extend this without breaking the IR schema.
- */
-export interface IRPairingPolicy {
-  /** Opt-out from specific spec<->IR pairing mismatch axes. */
-  acceptDrift?: IRAcceptDriftPolicy;
-}
-
-/**
- * Top-level IR document.
- */
-export interface IRDocument {
-  /** Schema version. */
-  version: IRVersion;
-  /** Stable document identifier (typically the page or scope name). */
-  id: string;
-  /** Human-readable document name. */
-  name: string;
-  /** Optional description of what this document covers. */
-  description?: string;
-  /** Document-level semantic metadata. */
-  metadata?: IRMetadata;
-  /** Where this document came from. */
-  provenance?: IRProvenance;
-
-  /**
-   * Per-document policy block — opt-out from specific spec<->IR
-   * pairing mismatches. Used by hand-authored IRs that intentionally
-   * diverge from the legacy spec shape.
-   */
-  pairingPolicy?: IRPairingPolicy;
-
-  /** State declarations within this document. */
-  states: IRState[];
-  /** Transition declarations within this document. */
-  transitions: IRTransition[];
-
-  /** ID of the initial/starting state, if applicable. */
-  initialState?: string;
-}
+/**
+ * Top-level IR document.
+ *
+ * Versioned (`'1.0'`) container for the states + transitions that describe
+ * a page or scope of an application. Build plugins emit this shape; the
+ * 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";
+
+/**
+ * IR schema version. Bump when the shape changes in a backwards-incompatible
+ * way. The adapter rejects documents whose version it does not understand.
+ */
+export type IRVersion = "1.0";
+
+/**
+ * Axes that the spec <-> IR pairing gate compares. A document's
+ * `pairingPolicy.acceptDrift.axes` lists which of these are
+ * intentionally allowed to diverge between the legacy spec and the
+ * IR's forward projection.
+ */
+export type IRPairingAxis = "groupCount" | "groupIds" | "assertionCount";
+
+/**
+ * Per-document opt-out for specific spec<->IR pairing axes.
+ *
+ * The canonical use case is a hand-authored IR that uses a different
+ * grouping convention than the legacy spec. Without an explicit policy
+ * the pairing gate flags it as a mismatch on every PR, which trains
+ * reviewers to ignore the gate. The policy makes the divergence
+ * explicit and audit-friendly:
+ *
+ *   - `axes`     — which fingerprint comparisons to skip
+ *   - `reason`   — human-readable justification (required, surfaced in
+ *                  `check-spec-pairing` summary output)
+ *   - `since`    — ISO date (YYYY-MM-DD) the exemption was added
+ *   - `expiresAt` — optional ISO date (YYYY-MM-DD) after which the
+ *                   exemption stops applying. Forces periodic
+ *                   re-justification: the pairing gate downgrades
+ *                   expired exemptions back to ordinary mismatches.
+ *
+ * Mismatches NOT covered by the listed `axes` still fail the gate as
+ * usual — you can accept drift on `groupCount` while still requiring
+ * the assertion total to match.
+ */
+export interface IRAcceptDriftPolicy {
+  /** Fingerprint axes whose mismatches are tolerated. */
+  axes: IRPairingAxis[];
+  /** Human-readable justification for the exemption. */
+  reason: string;
+  /** ISO date (YYYY-MM-DD) the exemption was added. */
+  since: string;
+  /**
+   * Optional ISO date (YYYY-MM-DD) after which the exemption stops
+   * applying. The pairing gate then surfaces the document as an
+   * ordinary mismatch.
+   */
+  expiresAt?: string;
+}
+
+/**
+ * Per-document pairing policy block. Currently only carries
+ * `acceptDrift`; future policies (e.g. assertion-shape exemptions)
+ * can extend this without breaking the IR schema.
+ */
+export interface IRPairingPolicy {
+  /** Opt-out from specific spec<->IR pairing mismatch axes. */
+  acceptDrift?: IRAcceptDriftPolicy;
+}
+
+/**
+ * Top-level IR document.
+ */
+export interface IRDocument {
+  /** Schema version. */
+  version: IRVersion;
+  /** Stable document identifier (typically the page or scope name). */
+  id: string;
+  /** Human-readable document name. */
+  name: string;
+  /** Optional description of what this document covers. */
+  description?: string;
+  /** Document-level semantic metadata. */
+  metadata?: IRMetadata;
+  /** Where this document came from. */
+  provenance?: IRProvenance;
+
+  /**
+   * Per-document policy block — opt-out from specific spec<->IR
+   * pairing mismatches. Used by hand-authored IRs that intentionally
+   * diverge from the legacy spec shape.
+   */
+  pairingPolicy?: IRPairingPolicy;
+
+  /** State declarations within this document. */
+  states: IRState[];
+  /** 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/element-criteria.ts

@@ -1,48 +1,48 @@
-/**
- * IR's canonical element-matching shape.
- *
- * Per decision #7 (SESSION_PROMPTS.md): IR adopts ui-bridge-auto's
- * `ElementCriteria` as the canonical authoring shape — criteria survive ID
- * drift and are descriptive rather than identity-based. The shape mirrors
- * ui-bridge-auto/src/types/match.ts:20 exactly so the IR -> WorkflowConfig
- * adapter is structurally identity (no rewriting at the criteria level).
- *
- * `elementIds: string[]` is an OPTIONAL companion the runtime SDK fills in at
- * registration time when criteria resolve to specific registered elements.
- * Authors write criteria; the runtime caches resolutions.
- */
-
-/**
- * Minimal criteria to identify a DOM element.
- *
- * Mirrors `ElementCriteria` from `ui-bridge-auto/src/types/match.ts:20`.
- * Kept as a separate copy here (not re-exported) so the IR module has no
- * runtime dependency on ui-bridge-auto. The adapter is the single point of
- * type-level reconciliation.
- */
-export interface IRElementCriteria {
-  /** ARIA role or inferred role. */
-  role?: string;
-  /** HTML tag name (e.g. "div", "button"). Heavily used in legacy specs. */
-  tagName?: string;
-  /** Exact text content (trimmed). */
-  text?: string;
-  /** Substring match on text content (case-insensitive). */
-  textContains?: string;
-  /**
-   * ARIA label (case-insensitive substring match). Synonym of `accessibleName`
-   * for the runtime SDK; the projection prefers `accessibleName` when both are
-   * present.
-   */
-  ariaLabel?: string;
-  /**
-   * Computed accessible name (the same concept legacy specs serialize as
-   * `accessibleName`). Added section 3 so the inverse projection can
-   * round-trip without rewriting to `ariaLabel`.
-   */
-  accessibleName?: string;
-  /** Element ID (exact string or pattern-source string). */
-  id?: string;
-  /** HTML attributes to check (exact string match). */
-  attributes?: Record<string, string>;
-}
+/**
+ * IR's canonical element-matching shape.
+ *
+ * Per decision #7 (SESSION_PROMPTS.md): IR adopts ui-bridge-auto's
+ * `ElementCriteria` as the canonical authoring shape — criteria survive ID
+ * drift and are descriptive rather than identity-based. The shape mirrors
+ * ui-bridge-auto/src/types/match.ts:20 exactly so the IR -> WorkflowConfig
+ * adapter is structurally identity (no rewriting at the criteria level).
+ *
+ * `elementIds: string[]` is an OPTIONAL companion the runtime SDK fills in at
+ * registration time when criteria resolve to specific registered elements.
+ * Authors write criteria; the runtime caches resolutions.
+ */
+
+/**
+ * Minimal criteria to identify a DOM element.
+ *
+ * Mirrors `ElementCriteria` from `ui-bridge-auto/src/types/match.ts:20`.
+ * Kept as a separate copy here (not re-exported) so the IR module has no
+ * runtime dependency on ui-bridge-auto. The adapter is the single point of
+ * type-level reconciliation.
+ */
+export interface IRElementCriteria {
+  /** ARIA role or inferred role. */
+  role?: string;
+  /** HTML tag name (e.g. "div", "button"). Heavily used in legacy specs. */
+  tagName?: string;
+  /** Exact text content (trimmed). */
+  text?: string;
+  /** Substring match on text content (case-insensitive). */
+  textContains?: string;
+  /**
+   * ARIA label (case-insensitive substring match). Synonym of `accessibleName`
+   * for the runtime SDK; the projection prefers `accessibleName` when both are
+   * present.
+   */
+  ariaLabel?: string;
+  /**
+   * Computed accessible name (the same concept legacy specs serialize as
+   * `accessibleName`). Added section 3 so the inverse projection can
+   * round-trip without rewriting to `ariaLabel`.
+   */
+  accessibleName?: string;
+  /** Element ID (exact string or pattern-source string). */
+  id?: string;
+  /** HTML attributes to check (exact string match). */
+  attributes?: Record<string, 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

@@ -1,23 +1,24 @@
-/**
- * @qontinui/shared-types/ui-bridge-ir
- *
- * Authoring-time intermediate representation for the UI Bridge redesign.
- * Build plugins (Vite, Next.js, Metro) emit `IRDocument` instances; the
- * adapter (`adaptIRToWorkflowConfig`) folds them into ui-bridge-auto's
- * runtime shape.
- *
- * Boundary with `@qontinui/shared-types/state-machine` (per ADR-001 /
- * decision #6): `state-machine` houses snake_case Rust-generated wire types
- * for the runtime/db. `ui-bridge-ir` is camelCase, authoring-time, and
- * carries IR-only fields (provenance, metadata, effect, crossRefs,
- * visualRefs). The adapter is the single point of translation between the
- * two namespaces.
- */
-
-export * from "./primitives";
-export * from "./element-criteria";
-export * from "./state";
-export * from "./transition";
-export * from "./document";
-export * from "./adapter";
-export * from "./projection";
+/**
+ * @qontinui/shared-types/ui-bridge-ir
+ *
+ * Authoring-time intermediate representation for the UI Bridge redesign.
+ * Build plugins (Vite, Next.js, Metro) emit `IRDocument` instances; the
+ * adapter (`adaptIRToWorkflowConfig`) folds them into ui-bridge-auto's
+ * runtime shape.
+ *
+ * Boundary with `@qontinui/shared-types/state-machine` (per ADR-001 /
+ * decision #6): `state-machine` houses snake_case Rust-generated wire types
+ * for the runtime/db. `ui-bridge-ir` is camelCase, authoring-time, and
+ * carries IR-only fields (provenance, metadata, effect, crossRefs,
+ * visualRefs). The adapter is the single point of translation between the
+ * two namespaces.
+ */
+
+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";