Crate qontinui_types

Expand description

§qontinui-types

Canonical DTO types shared across the Qontinui stack.

Rust is the single source of truth. TypeScript and Python bindings are generated from the JSON Schemas emitted by schemars on these types; see qontinui-schemas/scripts/ and the just generate-types task.

§Conventions

Every field that is optional on the wire uses #[serde(default, skip_serializing_if = "Option::is_none")] so absence and null are distinguishable and round-trip faithfully.
Dates and times are ISO 8601 Strings. Do not introduce chrono::DateTime<Utc> here — it complicates JSON Schema output and couples the DTO layer to a particular chrono version. The types crate is a wire-format layer, not a domain model.
UUIDs are Strings (wire-format), not uuid::Uuid. Same reason.
Polymorphic step arrays use Vec<serde_json::Value>. JSON Schema emits { "type": "array", "items": {} } → unknown[] in TS, list[Any] in Python. Typed step discriminated unions are a future migration (Wave 4).

Drift between these Rust sources and the checked-in TS/Python bindings is caught in CI by .github/workflows/schema-drift.yml, which regenerates the bindings on every PR touching rust/src/** and fails if git diff reports any non-timestamp change. The codegen toolchain (Tauri Linux deps, datamodel-code-generator version) is pinned in that workflow — bump the pins deliberately when upstream output changes.

§The functional-spec-contract v0 artifact set (frozen 2026-06-13)

Three modules form the keystone contract for the website → mobile regeneration program (2026-06-13-functional-spec-contract.md):

functional_spec — Artifact 1, the backend-agnostic functional_spec::FunctionalSpec that comprehension writes and generation reads. Its ui_states / navigation reuse ir::{IrState, IrTransition} (a literal type-level superset of the IR).
completeness_verdict — Artifact 2, the Completeness Rubric + completeness_verdict::CompletenessVerdict. Borrows the DriftVerdict field vocabulary and embeds spec_check::SpecCheckResult for the UI dimension.
priorities_profile — Artifact 3, the priorities_profile::Profile that parameterizes the generators.

v0 stability contract: the specVersion / profileVersion fields are "0". Until they bump to "1", changes are additive-only — new optional fields and new enum variants only, never a rename, removal, or type change of an existing field. (deny_unknown_fields is deliberately omitted on these three so a reader tolerates a forward document.) Downstream plans #1 (app-gen), #2 (backend-gen), and #3 (comprehension) build against this frozen interface in parallel.

Modules§

accessibility: Accessibility tree models.
ai_workflows: AI workflow template DTOs.
app_events: Application event envelope types.
apps: Multi-tenant app registry types.
canonical_hash: RFC 8785 canonical-JSON hashing primitive.
completeness_eval: Completeness evaluation — the deterministic rubric walk that turns a functional_spec::FunctionalSpec + coverage evidence into a completeness_verdict::CompletenessVerdict (node enumeration + gap diff + per-section breakdown). The verify-phase rubric the website→mobile slice proves. Completeness evaluation — the rubric walk that turns a crate::functional_spec::FunctionalSpec + coverage evidence into a crate::completeness_verdict::CompletenessVerdict.
completeness_verdict: Completeness Rubric + Verdict — Artifact 2 of the functional-spec-contract keystone. Scores a generated app against the functional_spec in spec units; embeds spec_check for the UI dimension and borrows the DriftVerdict field vocabulary. See 2026-06-13-functional-spec-contract.md. Completeness Verdict + Rubric (v0) — Artifact 2 of the functional-spec-contract keystone (2026-06-13-functional-spec-contract.md).
config: Config models — AI context and workflow category.
constraints: Constraint engine DTO types.
dev_signatures: Canonical DEV-* dev-event outcome signatures (effect-side classification). Companion to dev_states; same UB-*-style plain-enum template. Canonical DEV-* dev-event outcome signatures (the effect-side classification).
dev_states: Canonical dev-environment state vocabulary (cause-side context) for the dev-event cause-effect ledger. Plain Rust enum mirroring the ui_bridge_diagnostics UB-* pattern — intentionally no DB, not codegen’d to TS/Python. See plans/2026-06-07-twin-dev-event-cause-effect-ledger.md. Canonical dev-environment state vocabulary (the cause-side context).
device
discovery: Unified State Discovery models.
endpoint_for: Shared operation→endpoint derivation for the website→mobile regeneration program. The single deterministic rule the app-generator (#1) and backend-generator (#2) both call so the generated app’s data layer and the generated backend’s routes agree without a runtime handoff. See 2026-06-14-app-generator-ir-inversion.md / 2026-06-14-backend-generator-from-spec.md (the reconciliation block). Shared operation→endpoint derivation for the website→mobile regeneration program.
execution: Execution-reporting DTO types.
federation
findings: Findings models — AI-analysis result payloads.
functional_spec: Functional Spec — Artifact 1 of the functional-spec-contract keystone: the backend-agnostic contract between comprehension and generation. Reuses ir::{IrState, IrTransition} for the ui_states/navigation section. See 2026-06-13-functional-spec-contract.md. Functional Spec (v0) — the backend-agnostic contract between comprehension (which writes the spec from an observed website) and generation (which reads it to regenerate an app + backend).
geometry: Geometric primitives for screen coordinates, regions, and multi-monitor layouts.
git_ops: Coord-mediated GitOp federation wire-format types.
ir: IR (Intermediate Representation) + Legacy wire types for the Spec API.
mcp_config: MCP (Model Context Protocol) client configuration DTOs.
memory: Coord-mediated memory wire-format types.
orchestration_config: Orchestration-loop DTO types.
priorities_profile: Priorities Profile — Artifact 3 of the functional-spec-contract keystone: the declarative, gate-checkable generator parameterization. See 2026-06-13-functional-spec-contract.md. Priorities Profile (v0) — Artifact 3 of the functional-spec-contract keystone (2026-06-13-functional-spec-contract.md).
process_management: Process-management DTO types.
rag: RAG API schemas for Qontinui services.
runner: Runner DTO types.
scheduler: Scheduler DTO types.
sdk_features: UI Bridge SDK feature inventory — single source of truth for capability flags.
spec_api_events: Spec API broadcast event taxonomy.
spec_check: Spec-Check v1 wire types.
state_machine: State machine DTO types.
targets: Target configuration models for action targeting.
task_run: Task-run DTO types.
terminal: Terminal session DTO types.
text_norm: Text normalization pipeline (§5.11).
ticket_system: Ticket system DTO types.
tree_events: Tree event schemas for execution logging.
ui_bridge: UI Bridge element-state DTOs.
ui_bridge_diagnostics: Canonical UI Bridge diagnostic code enum. Generated from ui-bridge/diagnostics/codes.json by ui-bridge/scripts/gen-diagnostics.ts — not from a schemars Rust source like the rest of this crate. Hand-edits are overwritten; drift is gated by ui-bridge’s diagnostics:check.
verification: Verification-plan DTO types.
wire: Rust-only cross-crate runner↔supervisor types.
worker_output: Structured AI worker output types.
workflow: Workflow frame DTO types.
workflow_step: Canonical step DTO types — the four core step variants.