@qontinui/shared-types 2.0.0 → 2.2.0

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

@@ -0,0 +1,37 @@
+/* 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 { NextActionKind } from "./NextActionKind";
+
+/**
+ * The typed next step of a [`Refusal`]. Decoding is lenient toward newer
+ * producers (module docs, "Forward compatibility").
+ */
+export interface NextAction {
+  kind: NextActionKind;
+  /**
+   * For [`NextActionKind::RetryLater`]: the earliest useful retry, in whole
+   * seconds. Absent when no delay is known.
+   */
+  retry_after_s?: number | null;
+  /**
+   * 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;
+  /**
+   * READER-SIDE: the raw `kind` when this reader did not recognise it
+   * (`kind` is then [`NextActionKind::Unrecognised`]). Producers must not
+   * emit it.
+   */
+  unrecognised_kind?: string | null;
+  [k: string]: unknown;
+}

package/src/generated/NextActionKind.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`.
+ */
+
+/**
+ * What the reader does next. A closed set: every refusal names exactly one.
+ */
+export type NextActionKind =
+  | "retry_later"
+  | "run_command"
+  | "open_page"
+  | "sign_in"
+  | "pair_device"
+  | "set_setting"
+  | "wait_for_gate"
+  | "none_terminal"
+  | "report_defect"
+  | "fix_request"
+  | "resnapshot"
+  | "scroll_into_view"
+  | "wait_for_enabled"
+  | "broaden_selector"
+  | "unrecognised";

package/src/generated/ProbeCondition.d.ts

@@ -0,0 +1,44 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * Condition that runs an external command and is met iff it exits 0.
+ *
+ * The runner execs `command` directly — argv, never a shell — so `command[0]`
+ * is the program and the rest are its arguments; wrap it in `sh -c` yourself
+ * if you want shell syntax. The condition is **NOT met** on a non-zero exit,
+ * on a timeout (the probe is killed at `timeout_seconds`) and on a spawn
+ * failure (including an empty `command`); each is logged distinctly. An
+ * unobserved or failed probe never reads as met.
+ *
+ * The probe is rate-limited to one run per `poll_seconds` per task: between
+ * polls the runner reuses the last result. `poll_seconds` is floored at 60
+ * because the scheduler re-evaluates conditions once per 60 s tick — a shorter
+ * interval could not be honoured. The runner's create/update API REFUSES a
+ * value below the floor (and an empty `command`, and a `timeout_seconds` of
+ * 0 or above 3600) rather than silently rewriting it; a stored row that
+ * predates that validation is clamped up to 60 at evaluation time.
+ */
+export interface ProbeCondition {
+  /**
+   * Program and arguments to exec (no shell). Must be non-empty.
+   */
+  command: string[];
+  /**
+   * Whether this condition is active.
+   */
+  enabled: boolean;
+  /**
+   * Minimum seconds between two probe runs for the same task. Minimum 60.
+   */
+  pollSeconds: number;
+  /**
+   * Seconds a single probe run may take before it is killed and counted as
+   * NOT met. 1..=3600.
+   */
+  timeoutSeconds: number;
+}

package/src/generated/Refusal.d.ts

@@ -0,0 +1,63 @@
+/* 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 { GlossaryTerm } from "./GlossaryTerm";
+import type { NextAction } from "./NextAction";
+import type { NextActionKind } from "./NextActionKind";
+import type { RefusalCode } from "./RefusalCode";
+import type { RefusalSource } from "./RefusalSource";
+
+/**
+ * One operator-facing refusal: what went wrong, and what to do next.
+ *
+ * Construct with [`Refusal::new`] and the `with_*` builders. `next_action` is
+ * deliberately not optional — see the module docs. Decoding is lenient toward
+ * newer producers (module docs, "Forward compatibility").
+ */
+export interface Refusal {
+  code: RefusalCode;
+  /**
+   * Raw diagnostic text (the underlying error, the unrecognised reason).
+   * Shown beside the rendered sentence, never inside it.
+   */
+  detail?: string | null;
+  /**
+   * Narrows `code` to the specific case (the setting that was empty, the
+   * service whose address was missing). Rendered after the headline.
+   */
+  discriminator?: string | null;
+  /**
+   * Glossary terms a reader may need to act on this refusal. Typed, so a
+   * producer cannot cite a term the glossary does not define. Always
+   * present on the wire (an empty list, never null).
+   */
+  glossary_terms: GlossaryTerm[];
+  next_action: NextAction;
+  /**
+   * When the refusal was observed (ISO 8601).
+   */
+  observed_at: string;
+  source: RefusalSource;
+  /**
+   * READER-SIDE: the raw `code` when this reader did not recognise it
+   * (`code` is then [`RefusalCode::Unknown`]). Absent when the producer
+   * itself said `unknown`. Producers must not emit it.
+   */
+  unrecognised_code?: string | null;
+  /**
+   * READER-SIDE: glossary ids this reader's glossary does not define,
+   * removed from `glossary_terms`. Producers must not emit it.
+   */
+  unrecognised_glossary_terms?: string[];
+  /**
+   * READER-SIDE: the raw `source` when this reader did not recognise it
+   * (`source` is then [`RefusalSource::Unrecognised`]). Producers must not
+   * emit it.
+   */
+  unrecognised_source?: string | null;
+  [k: string]: unknown;
+}

package/src/generated/RefusalCode.d.ts

@@ -0,0 +1,33 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * What went wrong, as a stable machine-readable code.
+ *
+ * Extend by adding a variant (and its row in [`RefusalCode::headline`] and
+ * [`RefusalCode::from_wire`]); the tables are exhaustive `match`es, so a new
+ * code without a sentence is a compile error.
+ */
+export type RefusalCode =
+  | "workspace_root_unresolved"
+  | "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/RefusalSource.d.ts

@@ -0,0 +1,12 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * The component that produced a [`Refusal`].
+ */
+export type RefusalSource =
+  "runner" | "coord" | "web_backend" | "web_frontend" | "unrecognised";

package/src/generated/ScheduleConditions.d.ts

@@ -6,6 +6,7 @@
  */
 
 import type { IdleCondition } from "./IdleCondition";
+import type { ProbeCondition } from "./ProbeCondition";
 import type { RepositoryInactiveCondition } from "./RepositoryInactiveCondition";
 import type { RepositoryWatch } from "./RepositoryWatch";
 
@@ -17,6 +18,10 @@ export interface ScheduleConditions {
    * Require the runner to be idle.
    */
   requireIdle?: IdleCondition | null;
+  /**
+   * Require an external probe command to exit 0 (see [`ProbeCondition`]).
+   */
+  requireProbe?: ProbeCondition | null;
   /**
    * Require repository file inactivity across one or more paths.
    */

package/src/generated/ScheduledTask.d.ts

@@ -10,6 +10,7 @@ import type { ConditionScheduleConfig } from "./ConditionScheduleConfig";
 import type { ConditionStatus } from "./ConditionStatus";
 import type { IdleCondition } from "./IdleCondition";
 import type { McpConnectionRef } from "./McpConnectionRef";
+import type { ProbeCondition } from "./ProbeCondition";
 import type { RepositoryInactiveCondition } from "./RepositoryInactiveCondition";
 import type { RepositoryWatch } from "./RepositoryWatch";
 import type { ScheduleConditions } from "./ScheduleConditions";

package/src/generated/UpdateScheduledTaskRequest.d.ts

@@ -9,6 +9,7 @@ import type { CatchUpPolicy } from "./CatchUpPolicy";
 import type { ConditionScheduleConfig } from "./ConditionScheduleConfig";
 import type { IdleCondition } from "./IdleCondition";
 import type { McpConnectionRef } from "./McpConnectionRef";
+import type { ProbeCondition } from "./ProbeCondition";
 import type { RepositoryInactiveCondition } from "./RepositoryInactiveCondition";
 import type { RepositoryWatch } from "./RepositoryWatch";
 import type { ScheduleConditions } from "./ScheduleConditions";

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';
@@ -197,6 +198,7 @@ export type { GitCommitLite } from './GitCommitLite';
 export type { GitLite } from './GitLite';
 export type { GitOpListResponse } from './GitOpListResponse';
 export type { GitOpRecord } from './GitOpRecord';
+export type { GlossaryTerm } from './GlossaryTerm';
 export type { HealthCheckUrl } from './HealthCheckUrl';
 export type { HealthLevel } from './HealthLevel';
 export type { HealthLite } from './HealthLite';
@@ -240,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';
@@ -287,6 +293,8 @@ export type { MultiLoopStatus } from './MultiLoopStatus';
 export type { NativeAccessibilityStep } from './NativeAccessibilityStep';
 export type { NavigationResult } from './NavigationResult';
 export type { NewConstraintProposal } from './NewConstraintProposal';
+export type { NextAction } from './NextAction';
+export type { NextActionKind } from './NextActionKind';
 export type { NextTaskInfo } from './NextTaskInfo';
 export type { NodeMetadata } from './NodeMetadata';
 export type { NodeStatus } from './NodeStatus';
@@ -318,6 +326,7 @@ export type { PolicyConjunct } from './PolicyConjunct';
 export type { PolicyEvaluation } from './PolicyEvaluation';
 export type { PolicyStatus } from './PolicyStatus';
 export type { PollingConfig } from './PollingConfig';
+export type { ProbeCondition } from './ProbeCondition';
 export type { ProcessConfig } from './ProcessConfig';
 export type { ProcessState } from './ProcessState';
 export type { ProcessStatus } from './ProcessStatus';
@@ -336,6 +345,9 @@ export type { ReadConfigResponse } from './ReadConfigResponse';
 export type { RecommendedState } from './RecommendedState';
 export type { RecordGitOpRequest } from './RecordGitOpRequest';
 export type { ReflectionFixOutput } from './ReflectionFixOutput';
+export type { Refusal } from './Refusal';
+export type { RefusalCode } from './RefusalCode';
+export type { RefusalSource } from './RefusalSource';
 export type { Region } from './Region';
 export type { RegisterAppRequest } from './RegisterAppRequest';
 export type { Relationship } from './Relationship';

package/src/glossary/__tests__/glossary.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  GLOSSARY,
+  GLOSSARY_CONTENT_SHA256,
+  GLOSSARY_TERMS,
+  GLOSSARY_VERSION,
+  glossaryEntry,
+  isGlossaryTerm,
+  lookupGlossaryTerm,
+} from "../index";
+
+describe("glossary table", () => {
+  it("lists every keyed entry exactly once, in order", () => {
+    expect([...GLOSSARY_TERMS]).toEqual(Object.keys(GLOSSARY));
+    expect(new Set(GLOSSARY_TERMS).size).toBe(GLOSSARY_TERMS.length);
+    expect(GLOSSARY_TERMS.length).toBeGreaterThanOrEqual(20);
+  });
+
+  it("keys each entry by its own id, with no dangling see_also", () => {
+    for (const id of GLOSSARY_TERMS) {
+      const e = GLOSSARY[id];
+      expect(e.id).toBe(id);
+      expect(e.term.trim()).not.toBe("");
+      expect([...e.short].length).toBeLessThanOrEqual(160);
+      expect([...e.long].length).toBeLessThanOrEqual(1200);
+      for (const s of e.see_also) expect(isGlossaryTerm(s)).toBe(true);
+      expect(e.since).toBeGreaterThanOrEqual(1);
+      expect(e.since).toBeLessThanOrEqual(GLOSSARY_VERSION);
+    }
+  });
+
+  it("carries its version and content digest", () => {
+    expect(GLOSSARY_VERSION).toBeGreaterThanOrEqual(1);
+    expect(GLOSSARY_CONTENT_SHA256).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it("looks up by id and refuses what it does not define", () => {
+    expect(glossaryEntry("gate").id).toBe("gate");
+    expect(lookupGlossaryTerm("work_unit")?.term).toBe(GLOSSARY.work_unit.term);
+    expect(lookupGlossaryTerm("no_such_term")).toBeNull();
+    // Own keys only: an inherited property is not a term.
+    expect(isGlossaryTerm("toString")).toBe(false);
+    expect(isGlossaryTerm("__proto__")).toBe(false);
+  });
+});