Hexalith.Conversations.Contracts 1.0.0

Hexalith.Conversations.Contracts

Hexalith.Conversations.Contracts contains the adopter-safe command, projection, domain event, typed error, schema version, and compatibility metadata contracts for Hexalith Conversations.

Compatibility Discovery

The active v1 metadata is exposed by ConversationContractCompatibility.Current.

• commandContracts, projectionContracts, and eventContracts identify the active and minimum supported schema versions.
• contractsPackage identifies Hexalith.Conversations.Contracts.
• clientPackage identifies the aligned Hexalith.Conversations.Client package.
• status uses the closed vocabulary supported, deprecated, unsupported, or invalid.
• remediations contain bounded guidance codes and HTTPS documentation pointers.

Use ConversationContractCompatibility.Evaluate(...) to evaluate adopter-supplied schema and package versions without leaking implementation details. Malformed schema versions, zero or negative schema versions, unsupported schema versions, and unsupported package versions return typed compatibility results.

Compatibility failures use the same ConversationError shape as runtime command and client failures. Unsupported or invalid schema/package inputs return schema_version_unsupported with versioning, use-supported-version, a safe message, and the package documentation pointer.

For release-owner additive-change, breaking-change, deprecation-window, minimum-version, unsupported-version, and FR81 classification rules, see the Contract Compatibility and Deprecation Policy.

Supported v1 Integration Path

The supported v1 integration path is shared contracts plus the .NET client package. This package publishes the public DTOs and compatibility metadata. The client happy path is implemented separately, so this package does not define transport behavior, retries, onboarding diagnostics, or raw HTTP fallback examples.

Direct HTTP examples are intentionally outside normal v1 adopter guidance unless a later buyer-approved diagnostics scope records that exception.

Conversation Project Assignment

ReassignConversationProjectCommand is the additive v1 command for setting, changing, or explicitly clearing the Conversations-owned ProjectId after a conversation has been created. The matching public event is ConversationProjectChanged, which carries the previous and current ProjectId values as stable identifiers only.

The command target is explicit: use ConversationProjectAssignmentOperation.Assign with a non-null target ProjectId, or ConversationProjectAssignmentOperation.Clear with no target ProjectId. Missing target fields are validation failures, not implicit clear requests.

Adopters should call the aligned client method IConversationClient.ReassignConversationProjectAsync(...) and branch on ConversationCommandAcceptedResult, idempotency_conflict, idempotency_outcome_unknown, and the standard tenant/validation errors. The opt-in HTTP command route used by the client is POST /api/v1/conversations/{conversationId}/project; route and body conversation identities must match.

Typed Errors

ConversationError is the canonical adopter-safe error contract. It exposes structured fields only: code, category, isRetryable, clientAction, safeMessage, correlationId, optional allowed auditHandle, safeFieldDiagnostics, and an HTTPS documentation pointer. developerGuidance remains for backward-compatible safe text, but adopter applications should branch on code, category, and clientAction.

CORE Preconditions and Onboarding Diagnostics

CORE preconditions describe the environment state an adopter integration depends on before relying on Conversations behavior. The canonical, contract-owned catalog is ConversationCorePreconditionCatalog.All; each entry carries a preconditionId, the diagnostic check that evaluates it, the required trust state (only Current is trust-bearing), the typed unmetErrorCode reused from ConversationErrorCatalog, and a safe-failure description. When a precondition is unknown, failing, stale, or unsupported, dependent operations return a typed safe failure or a degraded-read result and never silently weaken tenant isolation, audit pairing, freshness, or schema compatibility.

Onboarding diagnostics evaluate the closed OnboardingDiagnosticCheck set (tenant context, contract version, provider configuration, projection subscription, schema compatibility, audit availability, Parties integration) and return an OnboardingDiagnosticRunResultV1. Each OnboardingDiagnosticCheckResultV1 carries a closed OnboardingDiagnosticStatus (ready, degraded, blocked, unknown) mapped to the shared trust/freshness vocabulary, a safe message, a bounded remediation guidance code, an HTTPS documentation pointer, and the same typed ConversationError shape used elsewhere. Diagnostics never disclose tenant data, Party data, conversation existence, provider payloads, or production secrets; a denied, missing, or cross-tenant request collapses to a single unknown result.

Adopter Conformance Tests and CORE Fixture

Adopters can prove their integration respects Conversations contracts before deployment by running the adopter-facing conformance suite against the synthetic CORE fixture. The suite reuses the contracts in this package (compatibility metadata, the typed error catalog, and the CORE precondition catalog) plus the shared trust/freshness vocabulary; it does not introduce a parallel model.

The conformance contracts live under Hexalith.Conversations.Contracts.Conformance:

• ConformanceCheck is the closed vocabulary covering the CORE integration surface.
• ConformanceOutcome reuses the Story 4.4 readiness language (ready, degraded, blocked, unknown) aligned to the shared trust/freshness vocabulary; only ready is trust-bearing. No conformance-only synonyms are introduced.
• ConformanceFailureClassification distinguishes conformant from product-invariant, infrastructure, configuration, unavailable-dependency, and execution failures.
• ConformanceCheckResultV1 and ConformanceRunResultV1 carry only structured, content-safe data and serialize to deterministic camelCase web JSON for CI consumption. Typed failures embed the shared ConversationError.

Each check maps to the relevant requirement, CORE precondition, and release-gate category so release-gate aggregation can consume the local evidence without rework:

The reusable synthetic CORE fixture ships in Hexalith.Conversations.Testing as ConversationConformanceCoreFixtures. It is deterministic, content-safe, and clearly marked (synthetic-conformance-data); it requires no production tenant data, provider credentials, or nested submodule initialization. It provides one authorized tenant-scoped happy-path conversation (participants, message attribution, business references, and Current projection freshness) plus typed failure cases for unsupported schema/version, stale projection, cross-tenant denial (hidden shape), duplicate-command idempotency conflict, and a sanitized error. Unique cross-tenant poison sentinel values are scanned by content-safety tests and must never appear in any authorized-tenant output.

To run the adopter suite in CI, execute the conformance test project and consume the serialized ConformanceRunResultV1:

dotnet test tests/Hexalith.Conversations.Conformance.Tests/Hexalith.Conversations.Conformance.Tests.csproj

Conformance assertions and the fixture target Conversations contracts and the supported Hexalith.Conversations.Client, not raw HTTP fallback. Release signing, versioned conformance manifests, and waiver aggregation are intentionally out of scope for the local-evidence slice.

Caller Metadata (Provenance Only)

CallerMetadata is an optional, bounded, content-safe provenance bag adopters can attach to CreateConversationCommand, AppendMessageCommand, UpdateConversationMetadataCommand, and ReassignConversationProjectCommand. It carries client/composer/origin attribution for audit, downstream projection, and Hexalith front-end composition surfaces. Correlation and causation identifiers are NOT part of caller metadata; they remain first-class on ConversationCommandMetadata and propagate onto events through ConversationEventMetadata.

Caller metadata is provenance only. It is never authorization, tenant truth, governance truth, or UI-inferred trust state. Tenant access stays decided by the claims-derived tenant context and the local Tenants projection; caller-supplied values can never override tenant scope, command availability, or freshness/trust signals. Every displayed trust claim still maps to Conversations-owned projection freshness or command-availability metadata.

Malformed, oversized, unbounded, sensitive, or unsupported metadata is rejected with a typed command_validation_failed diagnostic rather than silently truncated, because a truncated content-unsafe value cannot guarantee a safe residual fragment. Forbidden as caller-metadata keys or values: tenant identity, user/Party identity, tokens, claims, provider payloads, raw prompts, message/redacted text, business-reference values, secrets, local paths, and raw exception text. The same free-text content-safety guardrail used by ConversationError rejects these by construction, and the command boundary re-bounds caller metadata (and the existing UpdateConversationMetadataCommand.Attributes bag) before dispatch.

Safe Surface

The package is limited to public Conversations contracts. It does not publish runtime topology, local build paths, UI implementation details, provider-specific content fields, Party personal data, or operational failure text. Compatibility metadata is not tenant authorization, governance truth, projection freshness, or runtime health; it only tells adopters which contract and package versions are supported and where to find safe remediation guidance.