UiContracts

Purpose and authority boundary

NexusScholar.UiContracts lets application services create one WorkspacePlan that desktop, CLI, web, or mobile renderers can present differently. The contract transports display-ready facts and action descriptors. It does not execute commands, mutate Core records, persist state, or grant authority.

The package has no project references and no UI-framework dependency. Architecture tests keep Core domain packages from referencing it. This makes UI a consumer of scientific authority rather than part of that authority.

Contract graph

WorkspacePlan
  workspace id, title, mode, description, context refs
  |
  +-- ResearchBlockDescriptor[]
        id, kind, title, mode, severity, source kind
        |
        +-- EvidenceRef[]
        +-- ValidationRef[]
        +-- BlockActionDescriptor[]
        +-- optional object-root PayloadJson

BlockContracts.cs contains the complete public surface. Constructors trim required strings, copy incoming collections into read-only collections, reject null list elements, and require optional payload JSON to have an object root.

Vocabularies

• BlockMode: Beginner, Audit, Review, Repair.
• BlockSeverity: Info, Success, Warning, ReviewRequired, Blocking, Critical.
• BlockSourceKind: CoreValidated, ValidationReport, WorkflowState, AIProposal, UserDraft, AppProjection, ExternalEvidence, Sample.
• BlockActionKind: evidence/detail navigation, proposal acceptance/rejection, editing, validation, deduplication decisions, workflow continuation, and bundle export.
• KnownBlockKinds, KnownBlockActionCommandKinds, and KnownEvidenceRefKinds provide interoperable initial labels without introducing execution.

SourceKind is a display provenance classification, not proof. In particular, AppProjection and AIProposal must not be mistaken for Core-validated authority.

Serialization and deterministic use

UiContractJson.SerializerOptions uses web defaults, string enum converters, and indented output. UiContracts validates shape, not canonical scientific identity. AppServices is responsible for deterministic block order and canonical payload construction when reproducibility matters.

Renderers must preserve action metadata such as RequiresHumanConfirmation, IsDestructive, CommandKind, and TargetRef. A renderer may change layout, but it must not silently weaken confirmation or relabel a proposal as a decision.

Dependencies and extension points

Consumers include AppServices, ResearchWorkspace projections, Avalonia Blocks, Desktop.AppServices, and Desktop. To add a block kind, first decide whether existing evidence, validation, action, and object-payload fields can express it. Typed scientific meaning still belongs to the owning domain package.

Do not turn PayloadJson into an arbitrary runtime-object or UI-code transport. Do not add Avalonia, ASP.NET Core, provider SDKs, or model clients to this package.

Tests and evidence

UiContractTests cover guards, immutability, payload validation, and serialization. SampleBlockPlanTests verify illustrative plans. Architecture tests enforce the framework-free dependency boundary.

The design boundary is documented in UI-CONTRACTS-v0; the first real AppServices composition is accepted by ADR 0015.

Explicit nonclaims

UiContracts is not a renderer, persistence model, command bus, schema registry, domain record, AI runtime, authority resolver, or compatibility layer. A serialized workspace plan is not by itself a reproducible scientific record.