@qontinui/shared-types 2.4.1 → 3.0.0

package/src/generated/ExecutePlaybookStep.d.ts

@@ -11,6 +11,11 @@ import type { VerificationCategoryKind } from "./VerificationCategoryKind";
 /**
  * Drive a state machine through recorded transitions from a playbook.
  *
+ * The playbook travels inline in `content`, the only body the runner's
+ * executor reads. There is no path form: a `playbookPath` key on a stored
+ * step is ignored when it is decoded and dropped when the step is written
+ * back.
+ *
  * Wire tag: `"execute_playbook"`.
  */
 export interface ExecutePlaybookStep {
@@ -50,10 +55,6 @@ export interface ExecutePlaybookStep {
    * Display name for the step. Absent or `null` reads as `""`.
    */
   name: string;
-  /**
-   * Path to a playbook file.
-   */
-  playbookPath?: string | null;
   /**
    * Whether this step is required (default: `true` on consumer side).
    */

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;
+}

package/src/generated/JourneyGraph.d.ts

@@ -0,0 +1,165 @@
+/* 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 { JourneyArrivalDoubt } from "./JourneyArrivalDoubt";
+import type { JourneyCoverage } from "./JourneyCoverage";
+import type { JourneyFilter } from "./JourneyFilter";
+import type { JourneyGraphEdge } from "./JourneyGraphEdge";
+import type { JourneyLedgerHealth } from "./JourneyLedgerHealth";
+import type { JourneyNode } from "./JourneyNode";
+import type { JourneyTrigger } from "./JourneyTrigger";
+import type { JourneyUnmeasuredDepartures } from "./JourneyUnmeasuredDepartures";
+
+/**
+ * The journey graph derived from ledger rows under one filter.
+ */
+export interface JourneyGraph {
+  /**
+   * What the graph was built over.
+   */
+  coverage: JourneyCoverage;
+  /**
+   * Aggregated edges, sorted by `(fromKey, toKey, trigger, outcome)`.
+   */
+  edges: JourneyGraphEdge[];
+  /**
+   * The filter the edge set was narrowed by.
+   */
+  filterEcho: JourneyFilter;
+  /**
+   * Observed nodes, sorted by key.
+   */
+  nodes: JourneyGraphNode[];
+  /**
+   * Unmeasured departures (filtered, withdrawn, rejected frontier with a
+   * valid node, excluded back and URL arrivals) placed at a node key that
+   * is NOT in
+   * `nodes`. No component query can reach such a node, but a graph-wide
+   * question (`dead_ends`, `requires_prior_knowledge`, the whole frontier)
+   * counts them.
+   */
+  offGraphDepartures: JourneyUnmeasuredDepartures;
+  /**
+   * Rows left out as contract violations, live or withdrawn (a withdrawn one
+   * is also counted in `coverage.edgesInvalidated`), sorted.
+   */
+  rejected: JourneyRejectedRow[];
+  /**
+   * Rejected frontier rows counted at TWO node keys (their `nodeKey`
+   * column and their valid node's own key disagree). Per-node counts
+   * include both placements; graph-wide totals subtract this, so a
+   * graph-wide `rejectedFrontier` plus `unplacedRejectedFrontier` is the
+   * number of DISTINCT rejected frontier rows by full content. (`rejected`
+   * lists rows by `(kind, row, reason)`, so two rows differing only in
+   * their node JSON share one entry there but are both counted.)
+   */
+  rejectedFrontierDoublePlaced: number;
+  /**
+   * Affordance or `pop` rows whose real destination is unknown: kept or
+   * trusted-excluded ones with no `toNode` (`to_node_unobserved`), ones
+   * that closed `settle_timeout` or `error` to a DIFFERENT node (that node
+   * may be an intermediate state), and ones that closed `settle_timeout`
+   * on the SAME node (the destination may not have rendered yet). Each
+   * may arrive at any node, so `requires_prior_knowledge` lists no node as
+   * settled while this is non-zero.
+   */
+  unknownDestinationArrivals: number;
+  /**
+   * Distinct rejected frontier rows whose node fails `validate()`.
+   * Nothing in such a row is trusted, its `nodeKey` column included, so it
+   * is placed at NO node: each may be an open affordance anywhere, and
+   * EVERY negative answer counts it (dimension
+   * `unplaced_rejected_frontier`).
+   */
+  unplacedRejectedFrontier: number;
+  /**
+   * Distinct UNTRUSTED edge rows — live or withdrawn rows that fail
+   * [`trusted_edge_row`] (a failed `validate()` or an unparseable
+   * `observedAt`). Nothing in such a row is trusted, its `fromNode` and
+   * trigger included, so it is placed at NO node: it may be a click from
+   * and to anywhere, and EVERY negative answer counts it, component and
+   * graph-wide alike (dimension `unplaced_rejected_rows`). While it is
+   * non-zero, `dead_ends` lists no dead end and `requires_prior_knowledge`
+   * lists no settled node.
+   */
+  unplacedRejectedRows: number;
+}
+/**
+ * One observed vertex.
+ */
+export interface JourneyGraphNode {
+  /**
+   * Excluded affordance / pop rows arriving here from another node.
+   */
+  arrivalDoubt: JourneyArrivalDoubt;
+  /**
+   * Open frontier entries seen at this node, sorted by
+   * `affordanceFingerprint`.
+   */
+  frontier: FrontierEntry[];
+  /**
+   * [`JourneyNode::key`] — the node's identity.
+   */
+  key: string;
+  /**
+   * A representative node for the key (the smallest by its fields when
+   * rows disagree on non-identity detail such as `pageLabel`).
+   */
+  node: JourneyNode;
+  /**
+   * `true` when the node has at least one kept arrival (an edge from a
+   * DIFFERENT node whose `toNode` is this node — a self-loop is not an
+   * arrival), and NONE of them closed `changed` or
+   * `no_change`, whatever its trigger. Only those two outcomes confirm the
+   * node is a real destination: a `settle_timeout` or `error` arrival's
+   * observed node may be an intermediate state (a spinner, an error
+   * render). Such a node is never a settled dead end, nor a settled
+   * requires-prior-knowledge node.
+   */
+  unconfirmedDestination: boolean;
+  /**
+   * Departures from this node the navigation edge set leaves out but that
+   * may still lead somewhere (see [`JourneyUnmeasuredDepartures`]).
+   */
+  unmeasuredDepartures: JourneyUnmeasuredDepartures;
+  /**
+   * How many edges left this node with `outcome: to_node_unobserved` —
+   * actions whose destination was never seen.
+   */
+  unobservedDepartures: number;
+}
+/**
+ * A ledger row that broke the edge-observation contract and was left out of
+ * the graph — reported, never silently dropped.
+ */
+export interface JourneyRejectedRow {
+  /**
+   * Edge or frontier row.
+   */
+  kind: "edge" | "frontier";
+  /**
+   * The contract violation, as `JourneyContractError` renders it (or the
+   * timestamp parse failure).
+   */
+  reason: string;
+  /**
+   * The edge's `id`, or `"<nodeKey> <affordanceFingerprint>"` for a
+   * frontier row.
+   */
+  row: string;
+  /**
+   * How many DISTINCT rows (by full serialized content) this entry stands
+   * for. Two rows that share `(kind, row, reason)` but differ anywhere
+   * else — a live and a withdrawn copy, or two fromNodes under one id —
+   * are one entry here with `rows: 2`. The same full-row identity is the
+   * one `JourneyGraph::unplaced_rejected_rows` and
+   * `unplaced_rejected_frontier` count by, so for edges the `rows` of the
+   * edge entries sum to `unplaced_rejected_rows`.
+   */
+  rows: number;
+}