19  Workspace UI contracts

Evidence, findings, actions, and Assistant boundaries

The Data Explorer and Integrity Engineer workspaces are two views over a shared KAP workflow. This document defines the contracts that keep the UI truthful as the backend grows. A contract is an observable payload, state transition, or permission rule—not an ownership boundary.

19.1 Contract map

flowchart TD
  E["Evidence package"] --> F["Finding lifecycle"]
  F --> A["Action and connector"]
  V["View context"] <--> X["Assistant action"]
  X --> V
  E --> H["Audit events"]
  F --> H
  A --> H

19.2 Evidence readiness

Every campaign view should be able to request a compact evidence package with:

• organization, facility, campaign, and stable asset identifiers;
• source and modality (rgb, thermal, ogi, gas, cad, or other);
• capture and processing timestamps, spatial registration, and provenance;
• quality exceptions, indexing status, and a readiness state; and
• the actor and timestamp for the latest state change.

Readiness is explicit: created, indexing, review_required, ready, blocked, or failed. A campaign being selectable is not equivalent to being ready for Integrity review.

19.3 Finding lifecycle

The Findings and Investigate views consume a finding packet containing the evidence references, asset identity, source modality, confidence basis, correlation category, deterministic gate results, and review state. The minimum state machine is:

detected → review_required → confirmed | dismissed | reclassified → actionable_insight → handoff_pending → acknowledged → scheduled → completed

Each transition includes an actor, timestamp, rationale, and source event. A Critical finding or Remaining Life change requires qualified engineer confirmation. Uncertain, inconsistent, rejected, and out-of-scope findings must remain visibly distinct from actionable findings.

19.4 Actions and external connectors

Actions owns the KAP-local work record. It may reference a finding, inspection plan, target system, and requested operation. Connector status is explicit: unavailable, preview, connected, submitted, acknowledged, or failed.

The UI must not claim that an IDMS, CMMS, SAP PM, or register action succeeded without an external response containing a request or acknowledgement ID. KAP recommendations remain read-only toward SCADA and other control systems.

19.5 View-to-Assistant context

Every Assistant request carries the current workspace, view, organization, campaign, optional finding, and selected AI system. A view can provide context; the Assistant can propose a navigation, focus, filter, or draft command back to the view. Scope changes and mutations are never silent.

Assistant commands use a typed allowlist such as navigate, set_scope, select_or_focus, view_command, draft, and mutation. The client previews the command, checks permissions, and applies it only after the required user confirmation. The authoritative view form remains the source of truth for finding decisions, lifecycle transitions, exports, and connector actions.

19.6 Audit and privacy

Record scope identifiers, view transitions, decision and connector states, Assistant launcher, command type, confirmation, application, failure, and undo events. Do not place evidence contents, credentials, or general free-text chat in product analytics. Lifecycle and handoff events must be immutable and attributable.

19.7 Implementation status

Contract	Current UI	Remaining backend work
Evidence readiness	Campaign/default scope and indexing views exist	Persist readiness, quality exceptions, and handoff state
Finding lifecycle	Findings, Investigate, and local work-order notes exist	Decision queue, transitions, evidence packet, and audit events
Actions/connectors	KAP-local action form and truthful disabled states	Connector adapters, request/ack IDs, retry and failure states
View ↔︎ Assistant	Shared context-aware panel, launcher, Full screen, Close, /ask deep link	Typed server commands, confirmation records, citations, and audit integration
Audit/privacy	UI events and scope payloads are defined	Durable immutable event stream and retention policy

These contracts complement the Data Explorer workflow, Integrity Engineer workflow, and the Kav AI PRD.