@qontinui/shared-types 0.6.0 → 0.7.0

package/dist/ui-bridge-ir.d.cts

@@ -477,7 +477,53 @@ interface IRDocument {
     synthesizedGroups?: IRGroup[];
     /** ID of the initial/starting state, if applicable. */
     initialState?: string;
+    /** Per-page API-contract assertions evaluated by the Spec CI harness. */
+    apiAssertions?: IRApiCheck[];
 }
+/**
+ * A single API-contract check: issue a request, validate the response.
+ */
+interface IRApiCheck {
+    id: string;
+    description?: string;
+    request: {
+        method: string;
+        path: string;
+        headers?: Record<string, string>;
+        body?: unknown;
+    };
+    effect?: "read" | "write" | "destructive";
+    assertions: IRApiAssertion[];
+}
+/**
+ * API assertion: either a value-level assertion (status_code, json_path, etc.)
+ * or a schema-conformance assertion (conforms_to -- Phase 2 placeholder).
+ */
+type IRApiAssertion = {
+    type: "status_code";
+    expected: unknown;
+    operator?: string;
+} | {
+    type: "json_path";
+    jsonPath: string;
+    expected: unknown;
+    operator?: string;
+} | {
+    type: "header";
+    headerName: string;
+    expected: unknown;
+    operator?: string;
+} | {
+    type: "body_contains";
+    expected: unknown;
+} | {
+    type: "response_time";
+    expected: unknown;
+    operator?: string;
+} | {
+    type: "conforms_to";
+    schema: string;
+};
 
 /**
  * IR -> WorkflowConfig adapter.
@@ -978,4 +1024,4 @@ interface ProjectLegacyToIROptions {
  */
 declare function projectLegacyToIR(legacy: LegacySpec, opts?: ProjectLegacyToIROptions): IRDocument;
 
-export { type AdaptedState, type AdaptedTransition, type AdaptedTransitionAction, type AdaptedWaitAfter, type AdaptedWorkflowConfig, type IRAcceptDriftPolicy, type IRAssertion, type IRAssertionTarget, type IRCrossRef, type IRDocument, type IREffect, type IRElementCriteria, type IRGroup, type IRMetadata, type IRPairingAxis, type IRPairingPolicy, type IRProvenance, type IRState, type IRStateCondition, type IRTransition, type IRTransitionAction, type IRVersion, type IRVisualRef, type IRWaitSpec, type LegacyAssertion, type LegacyAssertionTarget, type LegacyCriteria, type LegacyGroup, type LegacyMetadata, type LegacyProcessStep, type LegacySpec, type LegacyStateMachine, type LegacyStateMachineState, type LegacyTransition, type ProjectLegacyToIROptions, adaptIRDocumentToWorkflowConfig, adaptIRState, adaptIRTransition, adaptIRTransitionAction, projectIRToBundledPage, projectLegacyToIR, projectionVersion };
+export { type AdaptedState, type AdaptedTransition, type AdaptedTransitionAction, type AdaptedWaitAfter, type AdaptedWorkflowConfig, type IRAcceptDriftPolicy, type IRApiAssertion, type IRApiCheck, type IRAssertion, type IRAssertionTarget, type IRCrossRef, type IRDocument, type IREffect, type IRElementCriteria, type IRGroup, type IRMetadata, type IRPairingAxis, type IRPairingPolicy, type IRProvenance, type IRState, type IRStateCondition, type IRTransition, type IRTransitionAction, type IRVersion, type IRVisualRef, type IRWaitSpec, type LegacyAssertion, type LegacyAssertionTarget, type LegacyCriteria, type LegacyGroup, type LegacyMetadata, type LegacyProcessStep, type LegacySpec, type LegacyStateMachine, type LegacyStateMachineState, type LegacyTransition, type ProjectLegacyToIROptions, adaptIRDocumentToWorkflowConfig, adaptIRState, adaptIRTransition, adaptIRTransitionAction, projectIRToBundledPage, projectLegacyToIR, projectionVersion };

package/dist/ui-bridge-ir.d.ts

@@ -477,7 +477,53 @@ interface IRDocument {
     synthesizedGroups?: IRGroup[];
     /** ID of the initial/starting state, if applicable. */
     initialState?: string;
+    /** Per-page API-contract assertions evaluated by the Spec CI harness. */
+    apiAssertions?: IRApiCheck[];
 }
+/**
+ * A single API-contract check: issue a request, validate the response.
+ */
+interface IRApiCheck {
+    id: string;
+    description?: string;
+    request: {
+        method: string;
+        path: string;
+        headers?: Record<string, string>;
+        body?: unknown;
+    };
+    effect?: "read" | "write" | "destructive";
+    assertions: IRApiAssertion[];
+}
+/**
+ * API assertion: either a value-level assertion (status_code, json_path, etc.)
+ * or a schema-conformance assertion (conforms_to -- Phase 2 placeholder).
+ */
+type IRApiAssertion = {
+    type: "status_code";
+    expected: unknown;
+    operator?: string;
+} | {
+    type: "json_path";
+    jsonPath: string;
+    expected: unknown;
+    operator?: string;
+} | {
+    type: "header";
+    headerName: string;
+    expected: unknown;
+    operator?: string;
+} | {
+    type: "body_contains";
+    expected: unknown;
+} | {
+    type: "response_time";
+    expected: unknown;
+    operator?: string;
+} | {
+    type: "conforms_to";
+    schema: string;
+};
 
 /**
  * IR -> WorkflowConfig adapter.
@@ -978,4 +1024,4 @@ interface ProjectLegacyToIROptions {
  */
 declare function projectLegacyToIR(legacy: LegacySpec, opts?: ProjectLegacyToIROptions): IRDocument;
 
-export { type AdaptedState, type AdaptedTransition, type AdaptedTransitionAction, type AdaptedWaitAfter, type AdaptedWorkflowConfig, type IRAcceptDriftPolicy, type IRAssertion, type IRAssertionTarget, type IRCrossRef, type IRDocument, type IREffect, type IRElementCriteria, type IRGroup, type IRMetadata, type IRPairingAxis, type IRPairingPolicy, type IRProvenance, type IRState, type IRStateCondition, type IRTransition, type IRTransitionAction, type IRVersion, type IRVisualRef, type IRWaitSpec, type LegacyAssertion, type LegacyAssertionTarget, type LegacyCriteria, type LegacyGroup, type LegacyMetadata, type LegacyProcessStep, type LegacySpec, type LegacyStateMachine, type LegacyStateMachineState, type LegacyTransition, type ProjectLegacyToIROptions, adaptIRDocumentToWorkflowConfig, adaptIRState, adaptIRTransition, adaptIRTransitionAction, projectIRToBundledPage, projectLegacyToIR, projectionVersion };
+export { type AdaptedState, type AdaptedTransition, type AdaptedTransitionAction, type AdaptedWaitAfter, type AdaptedWorkflowConfig, type IRAcceptDriftPolicy, type IRApiAssertion, type IRApiCheck, type IRAssertion, type IRAssertionTarget, type IRCrossRef, type IRDocument, type IREffect, type IRElementCriteria, type IRGroup, type IRMetadata, type IRPairingAxis, type IRPairingPolicy, type IRProvenance, type IRState, type IRStateCondition, type IRTransition, type IRTransitionAction, type IRVersion, type IRVisualRef, type IRWaitSpec, type LegacyAssertion, type LegacyAssertionTarget, type LegacyCriteria, type LegacyGroup, type LegacyMetadata, type LegacyProcessStep, type LegacySpec, type LegacyStateMachine, type LegacyStateMachineState, type LegacyTransition, type ProjectLegacyToIROptions, adaptIRDocumentToWorkflowConfig, adaptIRState, adaptIRTransition, adaptIRTransitionAction, projectIRToBundledPage, projectLegacyToIR, projectionVersion };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qontinui/shared-types",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Shared TypeScript types for the Qontinui ecosystem",
   "type": "module",
   "main": "./dist/index.js",

package/src/generated/ActionResponse.d.ts

@@ -16,6 +16,25 @@ export interface ActionResponse {
    * Time taken to execute the action in milliseconds.
    */
   durationMs: number;
+  /**
+   * D3 effect-calculus verification: the predicted-vs-observed outcome for
+   * this action, present only when a handler effect signature resolved for
+   * the `(action, element)` (opt-in; absent otherwise).
+   *
+   * Carried as an opaque JSON object on the wire, deliberately matching the
+   * established lean-wire / rich-SDK split (the SDK's `EffectVerification`
+   * has a richer shape than any consumer needs to type). The runner
+   * deserializes the sub-shape it asserts on (`outcome` / `cause` /
+   * `containment` / `durationMs`) with its own local struct in the
+   * `effect_check` step handler, and relays the rest into `result_json`. See
+   * `ui-bridge/.../control/effect-types.ts` for the SDK-side producer. Kept
+   * opaque here so the nested effect types need no top-level codegen
+   * registration (which would couple this crate's bindings to a runner
+   * `schema_export.rs` change).
+   */
+  effectVerification?: {
+    [k: string]: unknown;
+  };
   /**
    * Updated element state after the action (if applicable).
    */

package/src/generated/IrPageSpec.d.ts

@@ -27,6 +27,12 @@ import type { ProposalStatus } from './ProposalStatus';
  * surface — the projection layer derives the runtime `LegacySpec` from this.
  */
 export interface IrPageSpec {
+  /**
+   * Per-page API-contract assertions evaluated by the Spec CI harness.
+   * Phase 1: value-level assertions (status_code, json_path, header,
+   * body_contains, response_time). Phase 2 will add schema conformance.
+   */
+  apiAssertions?: IrApiCheck[] | null;
   description?: string | null;
   id: string;
   initialState?: string | null;

package/src/generated/UiBridgeHttpErrorEnvelope.d.ts

@@ -0,0 +1,47 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with `just generate-types` or
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * Canonical error envelope for the qontinui-web Next.js UI-Bridge proxy.
+ *
+ * The catch-all route at
+ * `qontinui-web/frontend/src/app/api/ui-bridge/[...path]/route.ts`
+ * short-circuits requests the SDK would otherwise 404 on — and the
+ * browser-required routes that can't respond without a live SDK client —
+ * to a structured HTTP 503 with this body
+ * (`route.ts::noBrowserResponse`):
+ *
+ * ```json
+ * { "success": false, "code": "NO_BROWSER_CONNECTED",
+ *   "message": "<path> requires a browser SDK client" }
+ * ```
+ *
+ * Modeled as a *generic* error envelope rather than a one-off
+ * `NoBrowserConnected` type: the `{success:false, code, message}` shape is
+ * the canonical structured-error contract for the whole proxy surface (not
+ * just the no-browser path), so a single reusable type is the more
+ * scalable and cleaner home. `code` stays a free-form `String` — the
+ * discriminator set (currently just `NO_BROWSER_CONNECTED`) is expected to
+ * grow, and pinning it to an enum here would force a schemas release on every
+ * new proxy error code. `success` is always `false` on this envelope (the
+ * success path uses [`UiBridgeHttpHealthEnvelope`] / the SDK's own envelopes).
+ */
+export interface UiBridgeHttpErrorEnvelope {
+  /**
+   * Machine-readable error discriminator (e.g. `"NO_BROWSER_CONNECTED"`).
+   */
+  code: string;
+  /**
+   * Human-readable explanation (e.g. `"<path> requires a browser SDK client"`).
+   */
+  message: string;
+  /**
+   * Always `false` — this envelope is only emitted on the error path.
+   */
+  success: boolean;
+  [k: string]: unknown;
+}

package/src/generated/UiBridgeHttpHealthAppInfo.d.ts

@@ -0,0 +1,36 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with `just generate-types` or
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * UI-Bridge metadata block included in the health envelope for the app
+ * discovery scanner. Spread of `config.appInfo` plus a fixed `capabilities`
+ * list. Present only when the server is configured with `appInfo` (the
+ * qontinui-web proxy always is — `route.ts` sets `appId: "qontinui-web"`).
+ */
+export interface UiBridgeHttpHealthAppInfo {
+  /**
+   * Stable app identifier (e.g. `"qontinui-web"`).
+   */
+  appId: string;
+  /**
+   * Human-readable app name.
+   */
+  appName: string;
+  /**
+   * App surface type (e.g. `"web"`).
+   */
+  appType: string;
+  /**
+   * Advertised UI-Bridge capabilities (e.g. `["control","renderLog","debug"]`).
+   */
+  capabilities: string[];
+  /**
+   * UI framework (e.g. `"nextjs"`).
+   */
+  framework: string;
+  [k: string]: unknown;
+}

package/src/generated/UiBridgeHttpHealthData.d.ts

@@ -0,0 +1,30 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with `just generate-types` or
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * Inner `data` payload of the UI-Bridge SDK HTTP health envelope.
+ *
+ * Emitted by the SDK's relay-transport handler for `GET /health`
+ * (`@qontinui/ui-bridge/server` `handleRelayRoute`, `nextjs.ts`): the
+ * `responsive` + `lastHeartbeat` fields plus a spread of the relay's
+ * `TransportDiagnostics`. Only `responsive` and `lastHeartbeat` are modeled
+ * explicitly here — the diagnostics spread (pendingCommandCount, connectedTabs,
+ * buildId, …) is intentionally left open (no `additionalProperties: false`,
+ * which schemars omits by default) so the diagnostics surface can evolve
+ * without a schemas release while the two stable health signals stay typed.
+ */
+export interface UiBridgeHttpHealthData {
+  /**
+   * Max heartbeat timestamp (ms since epoch) across all tabs; `0` when none.
+   */
+  lastHeartbeat: number;
+  /**
+   * True when at least one connected tab has a fresh heartbeat.
+   */
+  responsive: boolean;
+  [k: string]: unknown;
+}

package/src/generated/UiBridgeHttpHealthEnvelope.d.ts

@@ -0,0 +1,44 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with `just generate-types` or
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+import type { UiBridgeHttpHealthAppInfo } from './UiBridgeHttpHealthAppInfo';
+import type { UiBridgeHttpHealthData } from './UiBridgeHttpHealthData';
+
+/**
+ * Canonical success envelope for `GET /api/ui-bridge/health`.
+ *
+ * Distinct from [`UiBridgeResponseEnvelope`]: the HTTP health envelope has
+ * no `requestId` / `type`, and carries an app-discovery `uiBridge` block.
+ * Wire shape (`nextjs.ts::handleRelayRoute`):
+ *
+ * ```json
+ * { "success": true,
+ *   "data": { "responsive": false, "lastHeartbeat": 0, ...diagnostics },
+ *   "timestamp": 1713200000000,
+ *   "uiBridge": { "appId": "qontinui-web", ..., "capabilities": [...] } }
+ * ```
+ *
+ * `uiBridge` is optional (omitted when the server has no `appInfo`); the
+ * other three fields are always present.
+ */
+export interface UiBridgeHttpHealthEnvelope {
+  data: UiBridgeHttpHealthData;
+  /**
+   * Always `true` on the health path.
+   */
+  success: boolean;
+  /**
+   * Server-side timestamp (ms since epoch) of when the response was produced.
+   */
+  timestamp: number;
+  /**
+   * App-discovery metadata; present only when the server is configured
+   * with `appInfo`.
+   */
+  uiBridge?: UiBridgeHttpHealthAppInfo | null;
+  [k: string]: unknown;
+}

package/src/generated/index.ts

@@ -445,6 +445,10 @@ export type { UiBridgeAction } from './UiBridgeAction';
 export type { UiBridgeAssertType } from './UiBridgeAssertType';
 export type { UiBridgeComparisonMode } from './UiBridgeComparisonMode';
 export type { UiBridgeDesignAuditStep } from './UiBridgeDesignAuditStep';
+export type { UiBridgeHttpErrorEnvelope } from './UiBridgeHttpErrorEnvelope';
+export type { UiBridgeHttpHealthAppInfo } from './UiBridgeHttpHealthAppInfo';
+export type { UiBridgeHttpHealthData } from './UiBridgeHttpHealthData';
+export type { UiBridgeHttpHealthEnvelope } from './UiBridgeHttpHealthEnvelope';
 export type { UiBridgeRequestEnvelope } from './UiBridgeRequestEnvelope';
 export type { UiBridgeResponseEnvelope } from './UiBridgeResponseEnvelope';
 export type { UiBridgeSeverity } from './UiBridgeSeverity';

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

@@ -111,4 +111,39 @@ export interface IRDocument {
 
   /** ID of the initial/starting state, if applicable. */
   initialState?: string;
+
+  /** Per-page API-contract assertions evaluated by the Spec CI harness. */
+  apiAssertions?: IRApiCheck[];
 }
+
+// ---------------------------------------------------------------------------
+// API-contract checks (Spec CI harness)
+// ---------------------------------------------------------------------------
+
+/**
+ * A single API-contract check: issue a request, validate the response.
+ */
+export interface IRApiCheck {
+  id: string;
+  description?: string;
+  request: {
+    method: string;
+    path: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+  };
+  effect?: "read" | "write" | "destructive";
+  assertions: IRApiAssertion[];
+}
+
+/**
+ * API assertion: either a value-level assertion (status_code, json_path, etc.)
+ * or a schema-conformance assertion (conforms_to -- Phase 2 placeholder).
+ */
+export type IRApiAssertion =
+  | { type: "status_code"; expected: unknown; operator?: string }
+  | { type: "json_path"; jsonPath: string; expected: unknown; operator?: string }
+  | { type: "header"; headerName: string; expected: unknown; operator?: string }
+  | { type: "body_contains"; expected: unknown }
+  | { type: "response_time"; expected: unknown; operator?: string }
+  | { type: "conforms_to"; schema: string };