@qontinui/shared-types 2.4.0 → 2.5.0

package/src/generated/CriterionVerification.d.ts

@@ -0,0 +1,11 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * How an acceptance criterion is verified.
+ */
+export type CriterionVerification = "command" | "ui_bridge" | "test" | "manual";

package/src/generated/DetectedAnimation.d.ts

@@ -0,0 +1,32 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * One CSS animation or transition, as the SDK's idle signals and the
+ * timeline report it (`idle/detected-animation.ts`).
+ */
+export interface DetectedAnimation {
+  /**
+   * Duration (ms) when known — the elapsed time at end, or the effect's
+   * timing.
+   */
+  durationMs?: number | null;
+  /**
+   * Whether the animation repeats forever.
+   */
+  isInfinite: boolean;
+  /**
+   * `animationName`, or `transition:<property>` for a CSS transition.
+   */
+  name: string;
+  /**
+   * `ElementFingerprintData.hash` of the animated element, when it could
+   * be computed.
+   */
+  targetElement?: string | null;
+  [k: string]: unknown;
+}

package/src/generated/EarsPattern.d.ts

@@ -0,0 +1,20 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * EARS requirement pattern (Easy Approach to Requirements Syntax).
+ * Categorizes criteria by their trigger/condition pattern for better
+ * verification step generation.
+ */
+export type EarsPattern =
+  | "ubiquitous"
+  | "event_driven"
+  | "state_driven"
+  | "optional"
+  | "complex"
+  | "unwanted_behavior"
+  | "not_applicable";

package/src/generated/EdgeTiming.d.ts

@@ -0,0 +1,156 @@
+/* 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 { CacheProvenance } from "./CacheProvenance";
+import type { MetricDistribution } from "./MetricDistribution";
+import type { Observation } from "./Observation";
+import type { ObservationCoverage } from "./ObservationCoverage";
+import type { Producer } from "./Producer";
+import type { Provenance } from "./Provenance";
+import type { UnknownCode } from "./UnknownCode";
+import type { UnknownInfo } from "./UnknownInfo";
+import type { UnmeasuredDimension } from "./UnmeasuredDimension";
+
+/**
+ * One UI Bridge observation: `measured` (with `value`), `absent` (the
+ * producer considered at least one item, measured all of it, and found
+ * nothing), or `unknown` (the producer could not answer; `unknown.code` says
+ * why). `provenance` is always present and every one of its keys is always
+ * present.
+ *
+ * This type describes the wire SHAPE only; it is not a validator. It
+ * accepts envelopes the canonical parser refuses: `absent` carrying `value`
+ * or `unknown`, a present `"unknown": null`, and `absent` over non-empty
+ * `provenance.coverage.unmeasured` or over `provenance.coverage.considered`
+ * of 0. Parse an envelope you did not build with
+ * `qontinui_vision_core::Observation` (Rust) or a parser enforcing the same
+ * rules.
+ */
+export type Observation2 =
+  | {
+      provenance: Provenance;
+      status: "measured";
+      value: number;
+      [k: string]: unknown;
+    }
+  | {
+      provenance: Provenance;
+      status: "absent";
+      [k: string]: unknown;
+    }
+  | {
+      provenance: Provenance;
+      status: "unknown";
+      unknown: UnknownInfo;
+      [k: string]: unknown;
+    };
+
+/**
+ * The answer of [`edge_timing`].
+ */
+export interface EdgeTiming {
+  /**
+   * Distinct reported app versions, sorted, `null` (= not reported) first.
+   */
+  appVersions: (string | null)[];
+  /**
+   * `summary.firstResponseMs`.
+   */
+  firstResponseMs: MetricDistribution;
+  /**
+   * `summary.layoutShiftAfterFirstResponseMs`.
+   */
+  layoutShiftAfterFirstResponseMs: MetricDistribution;
+  /**
+   * `summary.layoutShiftCount`.
+   */
+  layoutShiftCount: MetricDistribution;
+  /**
+   * `summary.layoutShiftTotal`.
+   */
+  layoutShiftTotal: MetricDistribution;
+  /**
+   * `summary.longTaskTotalMs`.
+   */
+  longTaskTotalMs: MetricDistribution;
+  /**
+   * Samples (ledger rows) the answer is over.
+   */
+  n: number;
+  /**
+   * Latest `observedAt`; `null` when `n` is 0.
+   */
+  newestObservedAt?: string | null;
+  /**
+   * Every observation's raw values, ordered by `(observedAt,
+   * observationId)`, ties broken by the serialized `(appVersion,
+   * timeline)`.
+   */
+  observations: EdgeTimingRow[];
+  /**
+   * Earliest `observedAt`; `null` when `n` is 0.
+   */
+  oldestObservedAt?: string | null;
+  /**
+   * `summary.settleMs`.
+   */
+  settleMs: MetricDistribution;
+  /**
+   * Of those, rows with no timeline.
+   */
+  withoutTimeline: number;
+  [k: string]: unknown;
+}
+/**
+ * One observation's values as its timeline summary stated them,
+ * ledger-projected (status, value, coverage and unknown code kept; unknown
+ * detail replaced by its code; source and cache keys redacted). `null` (for
+ * every metric) = the row has no timeline.
+ */
+export interface EdgeTimingRow {
+  /**
+   * `null` = not reported.
+   */
+  appVersion?: string | null;
+  /**
+   * `summary.firstResponseMs`.
+   */
+  firstResponseMs?: Observation | null;
+  /**
+   * Whether the row carried a timeline.
+   */
+  hasTimeline: boolean;
+  /**
+   * `summary.layoutShiftAfterFirstResponseMs`.
+   */
+  layoutShiftAfterFirstResponseMs?: Observation | null;
+  /**
+   * `summary.layoutShiftCount`.
+   */
+  layoutShiftCount?: Observation2 | null;
+  /**
+   * `summary.layoutShiftTotal`.
+   */
+  layoutShiftTotal?: Observation | null;
+  /**
+   * `summary.longTaskTotalMs`.
+   */
+  longTaskTotalMs?: Observation | null;
+  /**
+   * The ledger row id — a `/vision/assert` `timeline_ref`.
+   */
+  observationId: string;
+  /**
+   * RFC 3339 UTC.
+   */
+  observedAt: string;
+  /**
+   * `summary.settleMs`.
+   */
+  settleMs?: Observation | null;
+  [k: string]: unknown;
+}

package/src/generated/ExternalRef.d.ts

@@ -0,0 +1,22 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * The same item in an external system (a Jira issue, say).
+ */
+export interface ExternalRef {
+  /**
+   * The item's key in that system, e.g. `PAY-123`.
+   */
+  key: string;
+  /**
+   * The external system, e.g. `jira`.
+   */
+  system: string;
+  url?: string | null;
+  [k: string]: unknown;
+}

package/src/generated/InterfaceMappingFrontmatter.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`.
+ */
+
+import type { MappingRow } from "./MappingRow";
+import type { TemplateRef } from "./TemplateRef";
+
+/**
+ * A field-level mapping between two systems.
+ */
+export interface InterfaceMappingFrontmatter {
+  id: string;
+  rows?: MappingRow[];
+  source_system: string;
+  target_system: string;
+  template?: TemplateRef | null;
+  [k: string]: unknown;
+}

package/src/generated/JourneyArrivalDoubt.d.ts

@@ -0,0 +1,26 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * Trusted affordance or `pop` rows, excluded from the graph, that ARRIVE at
+ * a node from a different node with outcome `changed`. Any of them may be a
+ * way in that the user did not need a URL for, so
+ * [`requires_prior_knowledge`] cannot list the node as settled. An excluded
+ * row that closed `error` or `settle_timeout` (or has no `toNode`) is not
+ * here: its recorded destination may be an intermediate state, so it routes
+ * to the graph-wide [`JourneyGraph::unknown_destination_arrivals`].
+ */
+export interface JourneyArrivalDoubt {
+  /**
+   * Arrivals the request's filter excluded.
+   */
+  filtered: number;
+  /**
+   * Withdrawn arrivals.
+   */
+  withdrawn: number;
+}

package/src/generated/JourneyCoverage.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 { JourneyLedgerHealth } from "./JourneyLedgerHealth";
+
+/**
+ * What a graph was built over — the resolution and freshness of every answer
+ * read from it. Rides inside the runner's `provenance.coverage`.
+ */
+export interface JourneyCoverage {
+  /**
+   * Distinct `appVersion`s among the edges observed, sorted, `null`
+   * (= not reported) first.
+   */
+  appVersions: (string | null)[];
+  /**
+   * Valid, live edge rows the filter excluded.
+   */
+  edgesFilteredOut: number;
+  /**
+   * Withdrawn edge rows (`invalidatedAt` set), excluded.
+   */
+  edgesInvalidated: number;
+  /**
+   * Edge rows the graph was built from (after exclusions), INCLUDING
+   * `to_node_unobserved` rows.
+   */
+  edgesObserved: number;
+  /**
+   * How many of `edgesObserved` closed as `to_node_unobserved`.
+   */
+  edgesToNodeUnobserved: number;
+  /**
+   * Edges observed that reported no `runId`.
+   */
+  edgesWithoutRunId: number;
+  /**
+   * Open frontier entries per reason — every reason present, zeros
+   * included.
+   */
+  frontierByReason: {
+    [k: string]: number;
+  };
+  /**
+   * Nodes with at least one open frontier entry.
+   */
+  frontierNodes: number;
+  /**
+   * Open frontier entries across the graph.
+   */
+  frontierOpen: number;
+  /**
+   * Whether the ledger these rows were read from is being written — the
+   * runner's `/journey/health` block, repeated here so a graph that
+   * stopped growing (`schemaAbsent` / `writeFailing`) can never read as a
+   * finished one in any query response.
+   */
+  ledger: JourneyLedgerHealth;
+  /**
+   * Latest `observedAt` among the edges observed; `null` = no edges.
+   */
+  newestEdgeAt?: string | null;
+  /**
+   * Distinct nodes (by key) seen as an edge endpoint, as the from-node of
+   * an unobserved departure, or as a frontier node.
+   */
+  nodesObserved: number;
+  /**
+   * How many of those are unmodelled (`modelled: false`) — the graph's
+   * resolution, as a number.
+   */
+  nodesUnmodelled: number;
+  /**
+   * Earliest `observedAt` among the edges observed; `null` = no edges.
+   */
+  oldestEdgeAt?: string | null;
+  /**
+   * ENTRIES in [`JourneyGraph::rejected`] — one per `(kind, row,
+   * reason)`. The sum of their `rows` gives the number of distinct
+   * rejected rows (by full content).
+   */
+  rowsRejected: number;
+  /**
+   * Distinct reported `runId`s among the edges observed.
+   */
+  runs: number;
+}

package/src/generated/JourneyDeadEnds.d.ts

@@ -0,0 +1,109 @@
+/* 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 { FrontierEntry } from "./FrontierEntry";
+import type { JourneyCoverage } from "./JourneyCoverage";
+import type { JourneyFilter } from "./JourneyFilter";
+import type { JourneyLedgerHealth } from "./JourneyLedgerHealth";
+import type { JourneyNode } from "./JourneyNode";
+import type { JourneySearchFrontier } from "./JourneySearchFrontier";
+import type { JourneySearchFrontierNode } from "./JourneySearchFrontierNode";
+import type { JourneyUnmeasuredDepartures } from "./JourneyUnmeasuredDepartures";
+
+/**
+ * The answer of [`dead_ends`].
+ */
+export interface JourneyDeadEnds {
+  /**
+   * The graph's coverage.
+   */
+  coverage: JourneyCoverage;
+  /**
+   * Nodes with no navigation edge to a DIFFERENT node, an empty frontier,
+   * no unobserved departure and no unmeasured NAVIGATION departure (an
+   * excluded back arrival only makes `backOnly` unknown), sorted by key.
+   */
+  deadEnds: JourneyDeadEnd[];
+  /**
+   * The graph's filter.
+   */
+  filterEcho: JourneyFilter;
+  /**
+   * What the whole graph did not look at.
+   */
+  frontier: JourneySearchFrontier;
+  /**
+   * Nodes with no navigation edge to a different node that still have an
+   * open frontier, an unobserved departure or an unmeasured navigation
+   * departure — or whose arrival is unconfirmed (`unconfirmedDestination`:
+   * no arrival from another node closed `changed` / `no_change`, so it may
+   * be an intermediate state), or that the graph as a whole cannot settle
+   * (`unsettledByGraph`) — never dead ends. Sorted.
+   */
+  unexplored: JourneyUnexploredNode[];
+}
+/**
+ * A node a user cannot leave by any affordance.
+ */
+export interface JourneyDeadEnd {
+  /**
+   * `true` when a kept `pop` edge with outcome `changed` leaves this node
+   * for a different node — the only way out is the browser's back button,
+   * a journey finding rather than an exit. `null` = unknown: no such edge
+   * was kept, but a `pop` row from this node was filtered or withdrawn, a
+   * kept `pop` edge to another node ended `error` / `settle_timeout`, or a
+   * kept `pop` self-loop ended `settle_timeout`
+   * (`unmeasuredDepartures.excludedBackArrivals > 0`). `false` otherwise.
+   * (A rejected `pop`-claiming row is untrusted and counts in
+   * `JourneyGraph::unplaced_rejected_rows`, which lists no node as a dead
+   * end at all.)
+   */
+  backOnly?: boolean | null;
+  /**
+   * The node.
+   */
+  nodeKey: string;
+}
+/**
+ * A node with no observed affordance exit that was NOT fully looked at, so
+ * it cannot be called a dead end.
+ */
+export interface JourneyUnexploredNode {
+  /**
+   * The node.
+   */
+  nodeKey: string;
+  /**
+   * Its open frontier entries per reason (only reasons present).
+   */
+  openByReason: {
+    [k: string]: number;
+  };
+  /**
+   * `true` when no observed arrival at the node closed `changed` or
+   * `no_change` (they were all `settle_timeout` / `error`), so nothing
+   * confirms it is a real destination rather than an intermediate state
+   * ([`JourneyGraphNode::unconfirmed_destination`]).
+   */
+  unconfirmedDestination: boolean;
+  /**
+   * Departures from it the navigation edge set left out (filtered,
+   * withdrawn, `settle_timeout` / `error` to another node, `settle_timeout`
+   * self-loops, rejected frontier rows with a valid node).
+   */
+  unmeasuredDepartures: JourneyUnmeasuredDepartures;
+  /**
+   * Departures from it whose destination was never observed.
+   */
+  unobservedDepartures: number;
+  /**
+   * `true` when the node itself was fully explored but the GRAPH cannot
+   * support a dead-end verdict: an unplaced untrusted row (edge or
+   * frontier) may belong to it, or the ledger is not `writing`.
+   */
+  unsettledByGraph: boolean;
+}

package/src/generated/JourneyEdgeObservation.d.ts

@@ -17,8 +17,9 @@ import type { JourneyTrigger } from "./JourneyTrigger";
  * [`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 `*`.
+ * The ledger's `timeline` column is not a field here: it holds a
+ * `qontinui-vision-core` `ChangeTimeline::for_ledger()` projection (see the
+ * module's PRIVACY note); readers select explicit columns rather than `*`.
  */
 export interface JourneyEdgeObservation {
   /**

package/src/generated/JourneyEdgeTimingAnswer.d.ts

@@ -0,0 +1,88 @@
+/* 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 { CacheProvenance } from "./CacheProvenance";
+import type { EdgeTiming } from "./EdgeTiming";
+import type { JourneyFilter } from "./JourneyFilter";
+import type { JourneyLedgerHealth } from "./JourneyLedgerHealth";
+import type { MetricDistribution } from "./MetricDistribution";
+import type { Observation } from "./Observation";
+import type { ObservationCoverage } from "./ObservationCoverage";
+import type { Producer } from "./Producer";
+import type { Provenance } from "./Provenance";
+import type { UnknownCode } from "./UnknownCode";
+import type { UnknownInfo } from "./UnknownInfo";
+import type { UnmeasuredDimension } from "./UnmeasuredDimension";
+
+/**
+ * The answer value of `GET /apps/{app_id}/journey/edge-timing`.
+ *
+ * **Samples POOL every trigger and outcome of the `(from, to)` pair**:
+ * affordance clicks and typed URLs alike, and `changed`, `settle_timeout`
+ * and `error` closes alike. Keeping only `affordance` + `changed` would drop
+ * exactly the slow and failing interactions (a `settle_timeout` close is the
+ * slowest sample there is) and bias every percentile fast. The pooled
+ * composition is reported in `samplesByOutcome` / `samplesByTrigger`, so a
+ * reader who wants one slice can see whether the pool is dominated by
+ * another.
+ */
+export interface JourneyEdgeTimingAnswer {
+  /**
+   * Live (not withdrawn) observations of this edge the filter removed.
+   */
+  edgesFilteredOut: number;
+  /**
+   * Withdrawn observations of this edge, excluded.
+   */
+  edgesInvalidated: number;
+  /**
+   * The filter the observations were narrowed by.
+   */
+  filterEcho: JourneyFilter;
+  /**
+   * The from-node key asked about.
+   */
+  fromKey: string;
+  /**
+   * The ledger the rows were read from.
+   */
+  ledger: JourneyLedgerHealth;
+  /**
+   * Untrusted EDGE rows anywhere in the read (an edge row that fails
+   * `validate()` or whose `observedAt` is not RFC 3339) — the edge rows
+   * the graph routes list as `rejected` (that list also holds frontier
+   * rows; this count does not). Their node keys cannot be trusted, so none is matched
+   * to this edge, and any of them may be one of its observations; never
+   * samples, never "filtered out".
+   */
+  rowsRejected: number;
+  /**
+   * Samples per edge outcome (wire string), pooled into `timing`.
+   */
+  samplesByOutcome: {
+    [k: string]: number;
+  };
+  /**
+   * Samples per navigation trigger (wire string), pooled into `timing`.
+   */
+  samplesByTrigger: {
+    [k: string]: number;
+  };
+  /**
+   * Observations whose stored timeline did not parse (counted in `timing`
+   * as without a timeline).
+   */
+  timelinesUnparseable: number;
+  /**
+   * The distribution, with its sample size.
+   */
+  timing: EdgeTiming;
+  /**
+   * The to-node key asked about.
+   */
+  toKey: string;
+}

package/src/generated/JourneyFilter.d.ts

@@ -0,0 +1,35 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * Narrows the EDGE set a graph is built from. Staleness is a filter, not a
+ * verdict: the caller decides what window to ask about, and every result
+ * echoes the filter it was computed under (`filterEcho`).
+ *
+ * The frontier is never filtered: an open frontier entry is current state,
+ * and hiding one behind an edge filter would turn "not looked at" into
+ * "nothing there".
+ *
+ * `since` is a `chrono::DateTime<Utc>` (serialized RFC 3339), an exception
+ * to the crate's string-timestamp convention for the same reason as
+ * `page::KeysetPosition`: it is compared, not merely carried.
+ */
+export interface JourneyFilter {
+  /**
+   * Keep edges whose `appVersion` equals this; `None` = every version.
+   * An edge that reported no version never matches a set filter.
+   */
+  appVersion: string | null;
+  /**
+   * Keep edges of this run kind; `None` = every kind.
+   */
+  runKind: ("agent_action" | "explorer" | "passive_session") | null;
+  /**
+   * Keep edges with `observedAt >= since`; `None` = no lower bound.
+   */
+  since: string | null;
+}

package/src/generated/JourneyFrontier.d.ts

@@ -0,0 +1,51 @@
+/* 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 { FrontierEntry } from "./FrontierEntry";
+import type { JourneyCoverage } from "./JourneyCoverage";
+import type { JourneyFilter } from "./JourneyFilter";
+import type { JourneyLedgerHealth } from "./JourneyLedgerHealth";
+import type { JourneyNode } from "./JourneyNode";
+import type { JourneySearchFrontier } from "./JourneySearchFrontier";
+import type { JourneySearchFrontierNode } from "./JourneySearchFrontierNode";
+import type { JourneyUnmeasuredDepartures } from "./JourneyUnmeasuredDepartures";
+
+/**
+ * The answer of [`frontier`] — the open frontier of one node, or of the
+ * whole graph.
+ */
+export interface JourneyFrontier {
+  /**
+   * The graph's coverage.
+   */
+  coverage: JourneyCoverage;
+  /**
+   * The open, listable frontier entries, sorted by `(nodeKey,
+   * affordanceFingerprint)`.
+   */
+  entries: FrontierEntry[];
+  /**
+   * The graph's filter.
+   */
+  filterEcho: JourneyFilter;
+  /**
+   * Everything not looked at in the part asked about — including rows
+   * that could not be listed (`rejected_frontier`). An EMPTY `entries` is
+   * a real "nothing left to explore" only when this is settled and
+   * [`JourneySearchFrontier::unsettled_because`] returns `None`.
+   */
+  frontier: JourneySearchFrontier;
+  /**
+   * The node asked about; `null` = the whole graph.
+   */
+  nodeKey?: string | null;
+  /**
+   * Whether that node was observed (always `true` for the whole graph).
+   * `false` means "never seen", never "nothing open there".
+   */
+  nodeObserved: boolean;
+}