@qontinui/shared-types 2.1.0 → 2.2.0

package/dist/refusal.d.cts

@@ -50,6 +50,10 @@ interface NextAction {
   /**
    * What the action applies to: the command to run, the page to open, the
    * setting to set, the gate to wait for. Its meaning is fixed by `kind`.
+   * On [`NextActionKind::RetryLater`] it is what to re-check BEFORE
+   * retrying, because the earlier attempt may already have taken effect (a
+   * [`RefusalCode::UpstreamTimeout`] write); [`NextAction::render`] then
+   * says so. Omit it on a retry that is safe to repeat blindly.
    */
   target?: string | null;
   /**
@@ -80,6 +84,19 @@ type RefusalCode =
   | "sibling_checkout_absent"
   | "endpoint_unresolved"
   | "glossary_term_unknown"
+  | "authentication_required"
+  | "credential_rejected"
+  | "permission_denied"
+  | "not_found"
+  | "conflict"
+  | "invalid_request"
+  | "rate_limited"
+  | "quota_exceeded"
+  | "upstream_unavailable"
+  | "upstream_timeout"
+  | "device_not_connected"
+  | "service_unavailable"
+  | "internal_error"
   | "unknown";
 
 /* eslint-disable */

package/dist/refusal.d.ts

@@ -50,6 +50,10 @@ interface NextAction {
   /**
    * What the action applies to: the command to run, the page to open, the
    * setting to set, the gate to wait for. Its meaning is fixed by `kind`.
+   * On [`NextActionKind::RetryLater`] it is what to re-check BEFORE
+   * retrying, because the earlier attempt may already have taken effect (a
+   * [`RefusalCode::UpstreamTimeout`] write); [`NextAction::render`] then
+   * says so. Omit it on a retry that is safe to repeat blindly.
    */
   target?: string | null;
   /**
@@ -80,6 +84,19 @@ type RefusalCode =
   | "sibling_checkout_absent"
   | "endpoint_unresolved"
   | "glossary_term_unknown"
+  | "authentication_required"
+  | "credential_rejected"
+  | "permission_denied"
+  | "not_found"
+  | "conflict"
+  | "invalid_request"
+  | "rate_limited"
+  | "quota_exceeded"
+  | "upstream_unavailable"
+  | "upstream_timeout"
+  | "device_not_connected"
+  | "service_unavailable"
+  | "internal_error"
   | "unknown";
 
 /* eslint-disable */

package/package.json

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

package/src/generated/FrontierEntry.d.ts

@@ -0,0 +1,62 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+import type { JourneyNode } from "./JourneyNode";
+
+/**
+ * An interactive affordance seen at a node and not yet the trigger of an
+ * edge from it — a row of `project.journey_frontier`, keyed
+ * `(app_id, node_key, affordance_fingerprint)`.
+ */
+export interface FrontierEntry {
+  /**
+   * Structural fingerprint of the affordance.
+   */
+  affordanceFingerprint: string;
+  /**
+   * ARIA role of the affordance; `None` = not reported.
+   */
+  affordanceRole?: string | null;
+  /**
+   * The registered app id.
+   */
+  appId: string;
+  /**
+   * The affordance's declared effect; `None` = undeclared.
+   */
+  declaredEffect?: ("read" | "write" | "destructive") | null;
+  /**
+   * First time it was seen at this node (ISO 8601).
+   */
+  firstSeenAt: string;
+  /**
+   * Most recent time it was seen at this node (ISO 8601).
+   */
+  lastSeenAt: string;
+  /**
+   * The run that most recently saw it; `None` = not reported.
+   */
+  lastSeenRunId?: string | null;
+  /**
+   * The node the affordance was seen at.
+   */
+  node: JourneyNode;
+  /**
+   * `node.key()` — stored so the primary key is a plain text column.
+   */
+  nodeKey: string;
+  /**
+   * Why it is on the frontier.
+   */
+  reason:
+    | "not_yet_activated"
+    | "effect_undeclared"
+    | "effect_write"
+    | "effect_destructive"
+    | "budget_exhausted"
+    | "activation_failed";
+}

package/src/generated/JourneyEdgeObservation.d.ts

@@ -0,0 +1,91 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+import type { JourneyNode } from "./JourneyNode";
+import type { JourneyTrigger } from "./JourneyTrigger";
+
+/**
+ * One observed edge of the journey graph — a row of
+ * `project.journey_edge_observations`.
+ *
+ * Invariants (checked by [`JourneyEdgeObservation::validate`]; the first also
+ * by the migration's CHECK): `to_node` is `None` iff `outcome` is
+ * [`EdgeOutcome::ToNodeUnobserved`]; `no_change` joins nodes with equal
+ * keys (a `changed` edge may also join equal keys).
+ *
+ * The ledger's `timeline` column is deliberately unrepresented until
+ * Phase 4; readers select explicit columns rather than `*`.
+ */
+export interface JourneyEdgeObservation {
+  /**
+   * The registered app id.
+   */
+  appId: string;
+  /**
+   * The SDK's self-reported version (`SdkAppInfo.version`, semver or git
+   * short-SHA); `None` = not reported, never "no version".
+   */
+  appVersion?: string | null;
+  /**
+   * The configuration the action was taken from.
+   */
+  fromNode: JourneyNode;
+  /**
+   * Row id (UUID).
+   */
+  id: string;
+  /**
+   * When the row was withdrawn (ISO 8601); `None` = live.
+   */
+  invalidatedAt?: string | null;
+  /**
+   * Who withdrew the row.
+   */
+  invalidatedBy?: string | null;
+  /**
+   * Why the row was withdrawn.
+   */
+  invalidatedReason?: string | null;
+  /**
+   * Token grouping one bulk withdrawal, as on `co_occurrence_observations`.
+   */
+  invalidationToken?: string | null;
+  /**
+   * When the edge CLOSED (to-snapshot seen, or diff returned), ISO 8601.
+   */
+  observedAt: string;
+  /**
+   * How the edge closed.
+   */
+  outcome:
+    "changed" | "no_change" | "error" | "settle_timeout" | "to_node_unobserved";
+  /**
+   * Agent session / task-run / recording-session id; `None` = not reported.
+   */
+  runId?: string | null;
+  /**
+   * Who produced the edge.
+   */
+  runKind: "agent_action" | "explorer" | "passive_session";
+  /**
+   * The runner's own `buildId`.
+   */
+  runnerBuildId: string;
+  /**
+   * Same meaning as `co_occurrence_observations.runner_instance`.
+   */
+  runnerInstance: string;
+  /**
+   * The configuration observed after it; `None` iff
+   * `outcome == to_node_unobserved`.
+   */
+  toNode?: JourneyNode | null;
+  /**
+   * What caused the edge.
+   */
+  trigger: JourneyTrigger;
+}

package/src/generated/JourneyLedgerHealth.d.ts

@@ -0,0 +1,21 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * Body of `GET /apps/{app_id}/journey/health`, and the ledger block every
+ * journey query response repeats.
+ */
+export interface JourneyLedgerHealth {
+  /**
+   * Human-readable cause, e.g. `"embedded DB predates the journey tables"`.
+   */
+  detail: string;
+  /**
+   * The ledger's state.
+   */
+  state: "writing" | "schema_absent" | "write_failing";
+}

package/src/generated/JourneyNode.d.ts

@@ -0,0 +1,72 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * A vertex of the journey graph: one observed configuration of one page.
+ *
+ * Identity is a deterministic predicate, not a judgment: a node is
+ * `(spec_id, sorted active IR state ids)` within an app. When the page has
+ * no spec, or no state was classified present, the node is UNMODELLED and is
+ * identified by its route template (else its page label) — it still takes
+ * part in reachability and is counted as unmodelled in coverage.
+ *
+ * Build one with [`JourneyNode::new`], which sorts and dedups `state_ids`
+ * and derives `modelled`; [`JourneyNode::key`] is the canonical string form
+ * stored in `journey_frontier.node_key`.
+ *
+ * Node identity is `key()` / `node_key` — NEVER jsonb equality of the
+ * serialized node (which also carries non-identity detail such as
+ * `pageLabel` on a modelled node).
+ * Unlike the crate's other optional fields, this struct's optional fields
+ * always serialize, as `null` when absent, so every stored node has the same
+ * key set.
+ */
+export interface JourneyNode {
+  /**
+   * True iff `spec_id` is present AND `state_ids` is non-empty.
+   */
+  modelled: boolean;
+  /**
+   * An APP-DECLARED page identifier — never a URL path, never user input.
+   *
+   * PRODUCER OBLIGATION (this is the privacy guarantee): fill it only from
+   * the snapshot's `page.pageContext.meta.tabId`, then `activeTab`, then
+   * `page.pageContext.name`, and NEVER from `page.pathname` in any form,
+   * raw or slugged. (The runner's existing `resolve_page_label` in
+   * `state_discovery/capture.rs` has a fourth fallback that slugs
+   * `page.pathname`; the journey producer must not use that fallback.)
+   * `pageContext.name` is a free-form display name (e.g. `"Import /
+   * Export"`), so the producer SLUGS it before storing — which leaves a
+   * `/` meaning only one thing: a leaked, unslugged path.
+   *
+   * [`JourneyNode::validate`] rejects a `/` as a TRIPWIRE for that leak.
+   * It is not the guarantee: a slugged path contains no `/` and passes.
+   */
+  pageLabel: string | null;
+  /**
+   * The framework route PATTERN the snapshot's page was served under
+   * (e.g. `/admin/coord/runs/[id]`), when known. Never a concrete URL path:
+   * a concrete path can embed user input (`/search/<term>`,
+   * `/users/<email>`). Not heuristically validated — the producer must
+   * fill it from the router's pattern, not from `location.pathname`.
+   */
+  pathnameTemplate: string | null;
+  /**
+   * The page spec the snapshot matched; `None` = no spec for this page.
+   * Load-bearing: some state ids are declared on more than one page.
+   * Must not contain `#` or start with `unmodelled:` (see [`JourneyNode::key`]).
+   */
+  specId: string | null;
+  /**
+   * Ids of the IR states classified present — deduped, in BYTE-WISE
+   * (UTF-8) ascending order, i.e. Rust's `str` ordering. Producers in
+   * other languages must sort by UTF-8 bytes (not UTF-16 code units, not
+   * a locale collation) or their keys will not match. No id may contain
+   * `,` (see [`JourneyNode::key`]).
+   */
+  stateIds: string[];
+}

package/src/generated/JourneyTrigger.d.ts

@@ -0,0 +1,47 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * What caused an edge — structurally only.
+ *
+ * `deny_unknown_fields` and the deliberate absence of any text/value field
+ * are the privacy control: a caller cannot smuggle a typed value into the
+ * ledger, because no such key deserializes and no such field exists to set.
+ */
+export interface JourneyTrigger {
+  /**
+   * The action verb (`click`, `type`, `select`, a component action id, …).
+   */
+  actionType: string;
+  /**
+   * Which runner choke point captured it.
+   */
+  chokePoint:
+    | "element_action"
+    | "batch_action"
+    | "component_action"
+    | "sdk_element_action"
+    | "execute_with_diff"
+    | "navigation";
+  /**
+   * The affordance's declared effect; `None` = undeclared (NOT "safe").
+   */
+  declaredEffect?: ("read" | "write" | "destructive") | null;
+  /**
+   * How the transition was initiated.
+   */
+  navigationTrigger:
+    "affordance" | "push" | "replace" | "pop" | "initial" | "hash";
+  /**
+   * Structural fingerprint of the target element; `None` = not resolved.
+   */
+  targetFingerprint?: string | null;
+  /**
+   * ARIA role of the target; `None` = not reported.
+   */
+  targetRole?: string | null;
+}

package/src/generated/NextAction.d.ts

@@ -21,6 +21,10 @@ export interface NextAction {
   /**
    * What the action applies to: the command to run, the page to open, the
    * setting to set, the gate to wait for. Its meaning is fixed by `kind`.
+   * On [`NextActionKind::RetryLater`] it is what to re-check BEFORE
+   * retrying, because the earlier attempt may already have taken effect (a
+   * [`RefusalCode::UpstreamTimeout`] write); [`NextAction::render`] then
+   * says so. Omit it on a retry that is safe to repeat blindly.
    */
   target?: string | null;
   /**

package/src/generated/RefusalCode.d.ts

@@ -17,4 +17,17 @@ export type RefusalCode =
   | "sibling_checkout_absent"
   | "endpoint_unresolved"
   | "glossary_term_unknown"
+  | "authentication_required"
+  | "credential_rejected"
+  | "permission_denied"
+  | "not_found"
+  | "conflict"
+  | "invalid_request"
+  | "rate_limited"
+  | "quota_exceeded"
+  | "upstream_unavailable"
+  | "upstream_timeout"
+  | "device_not_connected"
+  | "service_unavailable"
+  | "internal_error"
   | "unknown";

package/src/generated/index.ts

@@ -188,6 +188,7 @@ export type { FindingUpdate } from './FindingUpdate';
 export type { FindingUserInput } from './FindingUserInput';
 export type { FindingsSummary } from './FindingsSummary';
 export type { FlowEvent } from './FlowEvent';
+export type { FrontierEntry } from './FrontierEntry';
 export type { FullRunnerStep } from './FullRunnerStep';
 export type { FunctionalSpec } from './FunctionalSpec';
 export type { GUIElementChunk } from './GUIElementChunk';
@@ -241,6 +242,10 @@ export type { JobItem } from './JobItem';
 export type { JobListResponse } from './JobListResponse';
 export type { JobStatus } from './JobStatus';
 export type { JobSummary } from './JobSummary';
+export type { JourneyEdgeObservation } from './JourneyEdgeObservation';
+export type { JourneyLedgerHealth } from './JourneyLedgerHealth';
+export type { JourneyNode } from './JourneyNode';
+export type { JourneyTrigger } from './JourneyTrigger';
 export type { LLMCostSummary } from './LLMCostSummary';
 export type { LLMMetrics } from './LLMMetrics';
 export type { LegacyAssertion } from './LegacyAssertion';