AIKernel.NET
version: 0.1.1.1 / status: Active / edition: Draft / published: 2026-06-14 / updated: 2026-06-14

Domain Contract Surface v0.1.1.1

AIKernel.NET v0.1.1.1 expands the public contract surface without changing the existing v0.1.1 API signatures. The release line adds semantic interfaces, DTOs, and enums for adapter binding, runtime control, replay, observability, diagnostics, operator strategy, profiles, telemetry, metrics, HUD signals, and overlay annotation. It also adds contract-only governance carriers and evaluators for canonical triadic governance.

The change is additive. Existing consumers that use v0.1.1 interfaces can continue to compile against the same method signatures. New consumers can opt into the added contracts by referencing the new semantic interfaces and DTOs.

1. Compatibility Rules

  • Existing public interfaces are not renamed or replaced.
  • Existing public method signatures are not changed.
  • Existing enum values are not removed or renamed.
  • New behavior is represented by new semantic interfaces, DTO records, and enum

    • types.

  • Descriptor and snapshot DTOs that can represent failure include an optional

    • failure envelope.

  • Contract packages remain pure:
  • AIKernel.Abstractions: interfaces only
  • AIKernel.Contracts: interfaces only
  • AIKernel.Dtos: DTO records only
  • AIKernel.Enums: enum types only

2. Semantic Interface Additions

Adapters

  • AIKernel.Abstractions.Adapters.IProviderAdapter
  • AIKernel.Abstractions.Adapters.IRuntimeAdapter

Runtime

  • AIKernel.Abstractions.Runtime.ISandboxRuntimeControlProvider
  • AIKernel.Abstractions.Runtime.IProcessControlProvider

Replay and Observability

  • AIKernel.Abstractions.Replay.IReplayProvider
  • AIKernel.Abstractions.Observability.IEvidenceCollector

Diagnostics

  • AIKernel.Abstractions.Diagnostics.IDiagnosticsProvider

Operators

  • AIKernel.Abstractions.Operators.IOperatorStrategyProvider

Profiles

  • AIKernel.Abstractions.Profiles.IProfileStoreProvider
  • AIKernel.Abstractions.Profiles.IProfileOptimizationProvider

Telemetry and Metrics

  • AIKernel.Abstractions.Telemetry.ITelemetryProvider
  • AIKernel.Abstractions.Metrics.IMetricsProvider

Perception

  • AIKernel.Abstractions.Perception.IHudSignalProvider
  • AIKernel.Abstractions.Perception.IOverlayAnnotationProvider
  • AIKernel.Abstractions.Perception.IDiagnosticFramePerceptionProvider

Governance

  • AIKernel.Abstractions.Governance.ICouncilEvaluator
  • AIKernel.Abstractions.Governance.IDecisionGate
  • AIKernel.Abstractions.Governance.ITrajectoryGate
  • AIKernel.Abstractions.Governance.IRomGovernanceEngine

3. DTO Domains

The new DTO domains are:

  • AIKernel.Dtos.Adapters
  • AIKernel.Dtos.Runtime
  • AIKernel.Dtos.Replay
  • AIKernel.Dtos.Observability
  • AIKernel.Dtos.Diagnostics
  • AIKernel.Dtos.Operators
  • AIKernel.Dtos.Profiles
  • AIKernel.Dtos.Telemetry
  • AIKernel.Dtos.Metrics
  • AIKernel.Dtos.Perception
  • AIKernel.Dtos.Governance

Collections are initialized to empty values, metadata dictionaries are initialized to empty dictionaries, and result-like DTOs expose stable failure fields instead of requiring exceptions for predictable failures.

Governance DTOs use semantic carrier names. Council votes are represented by the CouncilVote carrier and the CouncilVoteValue enum, rejection details by RejectReasonInfo, and canon links by IReadOnlyList<CanonReference> so that multiple canon references can be preserved without changing the DTO shape later.

The CTG-specific architecture and developer guidance are documented in 20.CANONICAL_TRAJECTORY_GOVERNANCE-v0.1.1.1.md, 21.CTG_DEVELOPER_THEORY-v0.1.1.1.md, ../design/CTG_CONTRACT_MODEL-v0.1.1.1.md, and ../operations/CTG_DEVELOPER_GUIDE-v0.1.1.1.md. The fixed theoretical reference is ../papers/12-canonical-trajectory-governance/README.md.

4. Failure Envelope

Descriptor and snapshot DTOs that can carry success or failure add the following optional fields:

public bool? Succeeded { get; init; }\npublic string? ErrorCode { get; init; }\npublic string? ErrorMessage { get; init; }\npublic DiagnosticInfo? Diagnostics { get; init; }

The envelope is optional to preserve binary and source compatibility for existing DTO consumers. Predictable failures should flow through the envelope. Cancellation can still use OperationCanceledException.

5. Enum Domains

New domain enums live under domain namespaces such as:

  • AIKernel.Enums.Adapters
  • AIKernel.Enums.Runtime
  • AIKernel.Enums.Replay
  • AIKernel.Enums.Observability
  • AIKernel.Enums.Diagnostics
  • AIKernel.Enums.Operators
  • AIKernel.Enums.Profiles
  • AIKernel.Enums.Telemetry
  • AIKernel.Enums.Metrics
  • AIKernel.Enums.Perception
  • AIKernel.Enums.Governance

Every new enum uses Unknown = 0. Unknown values are handled by the fail-closed policy described in ../operations/ENUM_HANDLING_POLICY-v0.1.1.1.md.

6. Documentation and Comments

Public contract members must have bilingual XML documentation. Inline XML documentation can use English text followed by JA: Japanese text. Existing external documentation include files can use paired docs.en.xml and docs.ja.xml files.

The contributor-facing rule is defined in ../operations/XML_DOCUMENTATION_POLICY-v0.1.1.1.md.

7. Verification Surface

The v0.1.1.1 contract surface is verified with:

dotnet build src\AIKernel.NET.slnx\ndotnet test src\tests\AIKernel.Abstractions.Tests\AIKernel.Abstractions.Tests.csproj --no-build\ndotnet pack src\AIKernel.NET.slnx -c Release\ndotnet pack src\AIKernel.NET.slnx -c Release -p:UseLocalPackageVersion=true -p:LocalPackageBuildNumber=<build-number>

Local development package versions use:

0.1.1.1-dev<build-number>
Source: architecture/19.DOMAIN_CONTRACT_SURFACE-v0.1.1.1.md