Migration Guide

This guide defines migration steps from the initial concept baseline (v0.0.0) to the canonical architecture baseline (v0.0.1, v0.0.2, v0.0.3), to the DSL / History ROM contract extraction introduced in v0.0.4, and to the contract-surface purity cleanup plus external Capability module contracts, DynamicSLM Model ABI / SeedSLM discipline / distillation offload, HATL external cryptographic operator contract preparation, governance admissibility gate and trajectory vocabulary, and Semantic Compilation DTO vocabulary introduced in v0.0.5.

For the synchronized 0.1.1 public release line, keep NuGet and PyPI package families on the same version. The 0.1.1 line publishes Core, Control, Providers, Tools, WASM, CUDA, and Demo surfaces together, so mixed 0.1.0 / 0.1.1 dependency graphs should be treated as stale until proven otherwise.

For 0.1.1.1, no GitHub release workflow is required. This update is an additive package-line contract expansion for already published public packages. Existing 0.1.1 consumers do not need code migration unless they opt into the new domain contracts. The 0.1.1.1 package boundary is .NET / NuGet only: do not build or publish PyPI packages for this line, and keep Python wrappers on the synchronized 0.1.1 package line. The next official v0.1.2 canonical series is expected to publish synchronized NuGet and PyPI package families.

The CTG contract vocabulary was normalized before the 0.1.1.1 package line is published: council vote carriers use CouncilVote, finite vote values use CouncilVoteValue, gate decisions are discrete-only, and CanonReference uses the normalized pointer shape.

0. v0.1.1.1 Additive Contract Expansion

0.1.1.1 adds semantic interfaces, DTOs, and enums for adapters, runtime control, process control, replay, observability, diagnostics, operator strategy, profiles, telemetry, metrics, HUD signals, overlay annotations, and CTG governance carriers.

0.1 Compatibility

• Existing public method signatures remain unchanged.
• Existing public enum values are not removed or renamed.
• New interfaces are opt-in and use semantic names rather than mechanical

expansion suffixes.

• New descriptor and snapshot DTO fields are optional.
• New domain enums use Unknown = 0 and fail-closed unknown-value handling.

0.2 Consumer Action

Existing consumers can remain on their current API usage. Consumers that need the new surface should add references to the semantic interfaces and DTO domains described in ../architecture/19.DOMAIN_CONTRACT_SURFACE-v0.1.1.1.md. For CTG-specific guidance, also read ../architecture/20.CANONICAL_TRAJECTORY_GOVERNANCE-v0.1.1.1.md, ../architecture/21.CTG_DEVELOPER_THEORY-v0.1.1.1.md, ../design/CTG_CONTRACT_MODEL-v0.1.1.1.md, and CTG_DEVELOPER_GUIDE-v0.1.1.1.md. The fixed paper reference is ../papers/12-canonical-trajectory-governance/README.md.

0.3 CTG DTO / Enum Normalization

If you adopted pre-publication CTG draft contracts, update the following names and values before consuming 0.1.1.1 packages:

These corrections do not change canon, council, gate, or reject-policy meaning. They only align DTO, enum, and serialization shape before publication.

Local development package versions use:

0.1.1.1-dev<build-number>

1. Fundamental Changes

In v0.0.1, the architecture was rebuilt around Determinism and Non-LLM Governance.

• Namespace hardening:

AIKernel.Models was removed and split into Routing, Rom, and Rules.

• DTO purification:

business logic and custom exceptions were removed from the DTO layer.

• Trust-chain enforcement:

ROM processing is now standardized as IRomCanonicalizer first, then ISemanticHasher.

2. Interface Replacement Mapping

Replacement rules from old terms to canonical terms:

3. Recommended Migration Steps

1. Namespace updates:

align using directives with physical directory structure.

2. Exception relocation:

remove DTO-layer exception assumptions and enforce fail-closed behavior in Provider/Kernel execution layers.

3. ROM pipeline update:

always call IRomCanonicalizer.Canonicalize() before hash/signature verification.

4. Test realignment:

remap use-case-driven tests to canonical interfaces and UC-xx definitions.

4. Verification Checklist

• Abstractions do not expose external SDK-specific types in signatures.
• Dtos do not contain business logic or exception contracts.
• IRomDocument -> IRomCanonicalizer -> ISemanticHasher order is enforced.
• IPdp remains deterministic with Indeterminate => Deny behavior.

5. Migrating to v0.0.2: Vfs Naming Convention

In v0.0.2, acronyms with three or more characters are treated as words according to the .NET Framework Design Guidelines. As a result, VFS is normalized to Vfs in identifiers.

This is a breaking change that affects namespaces, project/package names, and public documentation.

5.1 Replacement Mapping

Types that already use the canonical spelling, such as IVfsProvider, IVfsSession, VfsProviderHealth, and VfsEntry, remain unchanged.

5.2 Migration Steps

1. Replace using AIKernel.VFS; with using AIKernel.Vfs;.
2. Update .csproj / .slnx references to AIKernel.Vfs/AIKernel.Vfs.csproj.
3. If NuGet package references are used, replace AIKernel.VFS with AIKernel.Vfs.
4. Normalize remaining VFS references in README, design docs, and operational docs to Vfs.
5. Excluding migration examples, run a case-sensitive search to confirm that VFS, AIKernel.VFS, ProviderID, and IROMCanonicalizer no longer remain.

6. Migrating to v0.0.2: Vfs Capability Contracts

This section corresponds to Issue #4, [RFC] Interface Segregation for VFS: Transitioning to Capability-Based Abstractions.

In v0.0.2, Vfs permissions are represented by capability interfaces instead of a single monolithic contract.

6.1 New Capability Interfaces

6.2 Compatibility Contracts

Existing IVfsFile, IVfsDirectory, and IVfsSession contracts remain as composite compatibility contracts.

• IVfsFile extends IReadableVfsFile.
• IVfsDirectory extends INavigableVfsDirectory while preserving legacy IVfsFile / IVfsDirectory return types.
• IVfsSession composes readable / writable / deletable / navigable / queryable / async-disposable capabilities.

As a result, existing implementations that depend on IVfsSession do not need to be replaced immediately. However, new implementations and standard providers should narrow their dependencies to the smallest capability interface required.

6.3 Implementation Guidance

• Read-only providers should implement only IReadableVfsSession, and should not implement IWritableVfsSession or IDeletableVfsSession.
• Avoid placeholder WriteFileAsync implementations that throw NotSupportedException for providers that cannot write.
• Callers should check the required capability interface before executing an operation. If the capability is absent, deny before side effects begin.

if (session is not IWritableVfsSession writable)\n{\n    // Deny before side effects begin.\n    return;\n}\n\nawait writable.WriteFileAsync(path, content);

7. Migrating to v0.0.2: Provider and Security Capability Contracts

After Issue #4, capability-based contracts are also applied to provider and security abstractions where one interface previously exposed unrelated authority surfaces.

7.1 Provider Lifecycle Contracts

IProvider remains as a composite compatibility contract, but provider identity, capability metadata, availability, lifecycle, and health are now independently expressible.

7.2 Provider Router Contracts

IProviderRouter remains as a composite compatibility contract, but retrieval, cache, and registry responsibilities are separated.

Read-only cache adapters should implement IMaterialCacheReader without exposing cache write or provider registry capabilities.

7.3 Tool Access Validation

IToolAccessValidator remains as a composite compatibility contract, but the authority checks are now split into capability interfaces:

Callers should depend on the smallest validator capability needed for the operation. Missing capability means denial before execution begins.

7.4 Event Bus Contracts

IEventBus remains as a composite compatibility contract over IProvider, event publishing, broadcast, and subscription registry capabilities.

Subscription-only adapters should implement IEventSubscriptionRegistry without exposing publish or broadcast capabilities.

7.5 Task and Scheduler Contracts

ITaskManager and IScheduler remain as composite compatibility contracts, but execution, control, result lookup, and scheduling authority are separated.

Observation-only components should depend on result-reader or job-reader capabilities without receiving execution or cancellation authority.

7.6 Tokenizer Contracts

ITokenizer remains as a composite compatibility contract, but tokenization, counting, decoding, statistics, model support, and NPU cardinality concerns are separated.

Budget estimators should usually depend on ITokenCounter and, only when hardware alignment is required, IPhysicalCardinalityAdvisor.

7.7 Signature Trust Store Contracts

ISignatureTrustStore remains as a composite compatibility contract, but trust resolution, revocation, expiry, chain verification, trusted-anchor lookup, and health probing are separated.

Health-only checks should depend on ITrustStoreHealthProbe and should not receive trust-resolution or revocation authority.

7.8 Kernel Facade Contracts

IKernel remains as the top-level facade compatibility contract, but execution, analysis, preprocessing, provider routing, and governance access are independently expressible.

Application code should depend on the narrow kernel capability it needs. IKernel should be reserved for composition roots and facade-level orchestration.

7.9 RAG Provider Contracts

IRagProvider remains as a composite compatibility contract over IProvider, search, and index mutation capabilities.

Read-only RAG providers should implement IRagSearchProvider only, plus IProvider when provider lifecycle metadata is required. They should not implement write/delete/clear capabilities just to throw NotSupportedException.

8. v0.0.2 Verification Checklist

• No using AIKernel.VFS; remains.
• ProjectReference / solution entries point to AIKernel.Vfs/AIKernel.Vfs.csproj.
• Excluding migration examples, public docs / README / csproj metadata no longer contain VFS, ProviderID, or IROMCanonicalizer.
• Read-only Vfs implementations do not expose mutation capabilities.
• Missing capabilities are handled as pre-execution denial, not late NotSupportedException failures.
• Read-only RAG providers expose IRagSearchProvider without index mutation capabilities.
• Provider/router dependencies are narrowed to identity, lifecycle, retrieval, cache, or registry capabilities where possible.
• Event dependencies are narrowed to publisher, broadcaster, or subscription registry capabilities where possible.
• Task and scheduler dependencies are narrowed to execution, control, result reader, job reader, scheduler, or canceller capabilities where possible.
• Tokenizer dependencies are narrowed to counter, tokenizer, decoder, statistics, model support, cardinality, or padding capabilities where possible.
• Signature trust dependencies are narrowed to trust resolver, revocation checker, expiry reader, chain verifier, anchor reader, or health probe capabilities where possible.
• Kernel dependencies are narrowed to execution, analysis, preprocessing, provider-router access, guard access, or PDP access capabilities where possible.
• Tool access validation dependencies are narrowed to the required capability interface where possible.

9. Migrating to v0.0.2: Contract Purity

This section corresponds to Issue #8, Contract Purity.

Contracts now represent immutable views/descriptors only. Mutation, validation, transformation, canonicalization, hashing, extraction, and analysis responsibilities are moved into explicit service interfaces.

9.1 Removed from Contract Objects

9.2 New Material Processing Services

Contract implementations should not mutate themselves. A transformation must return a new DTO/value or derived representation.

10. Migrating to v0.0.2: Capability-Driven Providers

This section corresponds to Issue #9, Capability-Driven Providers.

Provider contracts now expose optional operations as explicit capability interfaces. Existing broad interfaces remain as composite compatibility contracts.

10.1 Model Provider Capabilities

Text-only providers should implement ITextGenerationProvider without pretending to support streaming or question answering.

10.2 Embedding Provider Capabilities

10.3 Provider Capability Metadata

Routers should select providers by the capability interface they actually require.

11. Migrating to v0.0.2: Security and Policy Separation

This section corresponds to Issue #10, Security & Policy Separation.

Security contracts now separate decision, enforcement, registry, validation, failure handling, and audit category responsibilities. Missing or indeterminate authority must fail closed at the caller boundary.

11.1 Guard Capabilities

11.2 PDP Capabilities

11.3 Rules Engine Capabilities

11.4 Audit Capabilities

12. Migrating to v0.0.2: Sandbox and Validator Isolation

This section corresponds to Issue #11, Sandbox & Validator Isolation.

Execution, file transfer, cleanup, observation, validation, store mutation, and context-buffer access are now separated into capability interfaces. Existing broad interfaces remain as composite compatibility contracts.

12.1 Tool Sandbox Capabilities

12.2 ROM Validator Capabilities

12.3 Store, Collection, and Compute Capabilities

Read-only stores and schema-only validators should implement only the capability they actually support.

13. Migrating from v0.0.2 to v0.0.3: Dependency Layer Correction

v0.0.3 corrects the package dependency graph around Vfs contracts.

v0.0.4 supersedes this compatibility facade. If you are upgrading directly to v0.0.4 or later, follow section 14.6 and remove the separate AIKernel.Vfs package/project.

The main v0.0.3 change was that Vfs interface contracts became owned by AIKernel.Abstractions. In v0.0.3 only, the separate AIKernel.Vfs package acted as a compatibility facade through type forwarding, but it was no longer the owner of the contract definitions. v0.0.4 and later remove that separate package/project.

13.1 Target Layering

The expected Phase-1 dependency direction is:

AIKernel.Enums -> (none)\nAIKernel.Dtos -> AIKernel.Enums\nAIKernel.Contracts -> AIKernel.Enums, AIKernel.Dtos\nAIKernel.Abstractions -> AIKernel.Dtos, AIKernel.Enums\nAIKernel.Vfs -> AIKernel.Abstractions

The forbidden direction is:

AIKernel.Abstractions -> AIKernel.Vfs\nAIKernel.Abstractions -> AIKernel.Core\nAIKernel.Abstractions -> Providers

13.2 Moved Vfs Contracts

The following contracts moved from the AIKernel.Vfs project to the AIKernel.Abstractions project:

The public namespace remains AIKernel.Vfs for compatibility. The ownership change is at the assembly/package layer.

13.3 Project Reference Updates

Consumers should update project references as follows:

AIKernel.Abstractions.csproj\n- <ProjectReference Include="..\AIKernel.Vfs\AIKernel.Vfs.csproj" />\n\nAIKernel.Vfs.csproj\n- <ProjectReference Include="..\AIKernel.Dtos\AIKernel.Dtos.csproj" />\n+ <ProjectReference Include="..\AIKernel.Abstractions\AIKernel.Abstractions.csproj" />

Application projects that only use Vfs contracts can reference AIKernel.Abstractions directly. Projects pinned to v0.0.3 and requiring the compatibility facade could reference AIKernel.Vfs; v0.0.4 and later consumers should remove that separate package/project.

13.4 NuGet Package Updates

When upgrading package references:

<PackageReference Include="AIKernel.Abstractions" Version="0.0.3" />\n<PackageReference Include="AIKernel.Vfs" Version="0.0.3" />

Do not mix AIKernel.Abstractions 0.0.3 with AIKernel.Vfs 0.0.2; the facade expects the Vfs contract types to be provided by the 0.0.3 Abstractions assembly.

13.5 Source Migration Steps

1. Keep existing using AIKernel.Vfs; directives because the public namespace remains valid.
2. Remove any direct AIKernel.Abstractions -> AIKernel.Vfs project reference.
3. If a library defines only contracts, prefer referencing AIKernel.Abstractions rather than AIKernel.Vfs.
4. If a runtime/provider package implements Vfs contracts, reference AIKernel.Abstractions for v0.0.4 and later package graphs.
5. For v0.0.3-only compatibility builds, rebuild all packages so type-forwarding metadata is emitted consistently.

13.6 Verification Commands

Run:

dotnet build src\AIKernel.NET.slnx\ndotnet test src\tests\AIKernel.Abstractions.Tests\AIKernel.Abstractions.Tests.csproj --no-build

Check the project-reference graph:

AIKernel.Abstractions -> AIKernel.Dtos, AIKernel.Enums\nAIKernel.Vfs -> AIKernel.Abstractions\nCYCLE CHECK: OK (no ProjectReference cycles)

Also verify that AIKernel.Abstractions.csproj contains no reference to AIKernel.Vfs.

14. Migrating from v0.0.3 to v0.0.4: DSL / History ROM Contract Extraction

v0.0.4 promotes public contracts that had started inside AIKernel.Core into the AIKernel.NET contract packages. This prepares external capability modules, server hosts, WASM clients, and future Core packages to share the same interface surface.

This release intentionally keeps AIKernel.Abstractions independent from AIKernel.Core and AIKernel.Common. Core implementations that currently expose Result<T> or ResultStep<TState,TValue> should adapt those internal results to the DTO contract surface described below.

14.1 New DTO Areas

14.2 New Abstraction Areas

14.3 Breaking Migration Notes for Core Adapters

Core-side implementations should no longer require downstream consumers to reference Core-only DSL, History ROM, or clock contracts. DslNodeTypes defines canonical DSL node type strings. Parsers may accept paper/example aliases such as CapabilityCall and SuspendForApproval, but should normalize them to CallCapability and Suspend before storage or replay hashing.

Recommended replacements:

14.4 Ambiguous Interface Renames

v0.0.4 removes public interface names that were too broad for a shared package surface.

AIKernel.Abstractions.Execution.IKernelExecutor and AIKernel.Abstractions.Rom.ISemanticHasher remain unchanged. The renamed contracts were facade/chat-chain/scheduling-specific names that collided with broader execution and ROM concepts.

When a Core implementation still uses AIKernel.Common.Results.Result<T> internally, unwrap it at the package boundary into either:

• a successful DTO return value, or
• an implementation-defined fail-closed exception/result adapter appropriate to the host.

The AIKernel.NET contract packages deliberately do not expose Result<T> until AIKernel.Common is published as a stable package.

14.5 NuGet Package Updates

Use a consistent package set:

<PackageReference Include="AIKernel.Abstractions" Version="0.0.4" />\n<PackageReference Include="AIKernel.Dtos" Version="0.0.4" />\n<PackageReference Include="AIKernel.Enums" Version="0.0.4" />

Do not mix AIKernel.Abstractions 0.0.4 with AIKernel.Dtos 0.0.3; the new DSL, History ROM, and time contracts require the v0.0.4 DTO surface.

14.6 AIKernel.Vfs Package Removal

v0.0.4 removes the separate AIKernel.Vfs compatibility package/project. Vfs contracts remain available from AIKernel.Abstractions, and their public namespace remains AIKernel.Vfs.

Migration steps:

1. Remove PackageReference Include="AIKernel.Vfs" from application, provider, and test projects.
2. Add or keep PackageReference Include="AIKernel.Abstractions" Version="0.0.4" where Vfs contracts are used.
3. Keep source imports such as using AIKernel.Vfs;; the namespace is still correct.
4. Remove project references to AIKernel.Vfs/AIKernel.Vfs.csproj in local source builds.

14.7 Interface-Only Contract Packages

v0.0.4 introduces the target that AIKernel.Abstractions and AIKernel.Contracts are interface-only packages. DTOs, enums, exception types, factories, parsing helpers, and runtime behavior must live outside those contract packages.

v0.0.5 completes enforcement of this rule by removing the remaining physical DTO, enum, and exception implementations from the contract surface. See section 15 when migrating directly to v0.0.5 or later.

v0.0.4 introduced this ownership rule while extracting DSL, History ROM, and time contracts. Representative moves include AIKernel.Contracts.ValidationResult to AIKernel.Dtos.Context.ValidationResult and AIKernel.Abstractions.Vfs.VfsCredentials to AIKernel.Dtos.Vfs.VfsCredentials.

For the complete v0.0.5 cleanup of remaining Abstractions-local DTOs, duplicate DTO enums, and contract-package exceptions, use section 15.

14.8 Verification Commands

Run:

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 --no-build

Check the project-reference graph remains:

AIKernel.Enums -> (none)\nAIKernel.Dtos -> AIKernel.Enums\nAIKernel.Contracts -> AIKernel.Enums, AIKernel.Dtos\nAIKernel.Abstractions -> AIKernel.Dtos, AIKernel.Enums\nCYCLE CHECK: OK

15. Migrating from v0.0.4 to v0.0.5: Contract Surface Purity Cleanup

v0.0.5 completes the interface-only rule for AIKernel.Abstractions and AIKernel.Contracts. The release removes remaining DTO, enum, and exception implementations that were still physically located in contract packages after the v0.0.4 extraction.

15.1 Removed Abstractions-local DTOs

Use DTO package types instead.

15.2 Removed duplicate DTO enums

Use enum package types instead.

15.3 Removed contract-package exceptions

The following exception implementations are no longer exported from AIKernel.Abstractions.

• ContextAssemblyException
• ContextAssemblyGovernanceException
• PromptGenerationException
• PromptTokenBudgetExceededException
• UnsupportedPromptCapabilityException
• VfsAuthenticationFailedException

Runtime packages such as AIKernel.Core should own these exception or result/failure adapter types.

15.4 Removed ambiguous ChatChain interfaces

The following legacy interfaces were removed because their simple names were ambiguous on the shared contract surface.

AIKernel.Abstractions.Rom.ISemanticHasher remains the ROM semantic hash contract.

15.5 Package update

Keep the contract package set aligned.

<PackageReference Include="AIKernel.Abstractions" Version="0.0.5" />\n<PackageReference Include="AIKernel.Dtos" Version="0.0.5" />\n<PackageReference Include="AIKernel.Enums" Version="0.0.5" />\n<PackageReference Include="AIKernel.Contracts" Version="0.0.5" />

Do not mix AIKernel.Abstractions 0.0.5 with AIKernel.Dtos or AIKernel.Enums 0.0.4.

15.6 DynamicSLM / SeedSLM, HATL, governance, and Semantic Compilation vocabulary preparation

v0.0.5 adds non-runtime contracts for future external Capability modules, DynamicSLM capability modules, SeedSLM discipline surfaces, HATL external cryptographic operators, pre-inference governance admission evidence, trajectory governance evidence, and Semantic Compilation descriptors. These additions are source-compatible for existing consumers, but Core/Provider implementations that plan to support capability-modular SLM artifacts, HATL-backed trust layers, Semantic DSL admission evidence, or semantic compiler runtime artifacts should target the new namespaces.

These contracts intentionally do not expose AIKernel.Common.Result<T> or Core runtime handles. Implementations should adapt their internal result pipeline to the DTO/interface boundary. LINQ SelectMany, Bind, and Map implementations belong to AIKernel.Common or Core packages, not to AIKernel.NET. Distillation planning may run in the load pipeline, but distillation execution must be offloaded through IDynamicSlmDistillationJobScheduler or IDynamicSlmBackgroundDistillationService. Pipelines should continue through teacher, remote, or cached fallback metadata instead of blocking on training work. SeedSLM discipline, delegation, thought-artifact, and memory-placement contracts are also DTO/interface-only. Core should adapt them to ResultStep/ReplayLog/SemanticDelta pipelines and must not embed runtime behavior in contract packages. DynamicSlmModelAbi, DynamicSlmPipelineContext, and DynamicSlmPipelineMetadata include SeedSLM extension fields while retaining constructor compatibility for callers that do not provide SeedSLM state; missing SeedSLM fields are interpreted as absent contract metadata, not as runtime failure. HATL cryptographic operations are also contract-only in AIKernel.NET. Bind IHatlCryptographicOperator to an AIKernel.RH-backed operator, hardware provider, or audited module in Core/host code. DTO timestamp properties no longer inject DateTime.UtcNow by default. Core/provider implementations should assign deterministic timestamps through their clock or semantic-state materialization boundary. Governance admission records are DTO/enum-only. Core semantic compilers should attach AdmissibilityReplayRecord values to their own ResultStep/ReplayLog pipeline and use SemanticIrSlot only as shared G/T/C/B vocabulary, not as a runtime graph executor. Semantic Compilation DTOs are also contract-only. Prototype-space search, semantic distance evaluation, admissibility functions, deterministic synthesis, and graph execution remain Core/runtime responsibilities.

15.7 Verification Commands

Run:

dotnet build src\AIKernel.NET.slnx -c Release\ndotnet test src\AIKernel.NET.slnx -c Release --no-build

Confirm:

AIKernel.Abstractions exports interfaces only.\nAIKernel.Contracts exports interfaces only.\nAIKernel.Dtos exports no enums.\nAIKernel.Enums owns shared enums.\nCYCLE CHECK: OK

16. Migrating to v0.1.0: MemoryRegion / MemoryMapper Contract Extraction

The v0.1.0 contract line moves the OS-independent MemoryRegion / MemoryMapper surface out of Core provisional APIs and into the AIKernel.NET contract packages. Runtime packages keep OS-specific and Result-based adapters; shared signatures belong to Abstractions, DTOs, and Enums.

16.1 New contract ownership

16.2 Migration steps

Consumers that used AIKernel.Core.Memory as a public contract surface should move to the AIKernel.NET contract packages.

using AIKernel.Abstractions.Memory;\nusing AIKernel.Dtos.Memory;\nusing AIKernel.Enums;

Core and Kernel implementations may continue to adapt their internal Result<T> pipelines to these interfaces. Do not expose AIKernel.Common.Result<T> from AIKernel.NET contract packages.

16.3 Runtime adapter guidance

Runtime packages should treat the Core v0.0.x Memory types as transition-only implementation adapters.

The contract IMemoryMapper.Open intentionally returns IMemoryRegion directly. Fail-closed Result<T> composition remains a Core/Common runtime concern and must be adapted at the implementation boundary.

16.4 Verification Commands

Run:

dotnet build src\AIKernel.NET.slnx -c Release\ndotnet test src\AIKernel.NET.slnx -c Release --no-build

Confirm that AIKernel.Abstractions still references only AIKernel.Dtos and AIKernel.Enums, and that AIKernel.Dtos references only AIKernel.Enums.

17. Migrating to v0.1.0: Control and Routing Contract Ownership

The v0.1.0 contract line also moves Control Plane contracts and provider-routing decision data into AIKernel.NET. Runtime behavior remains in Core or Control implementation packages.

17.1 Control Plane contracts

AIKernel.Control.Core no longer owns duplicate contract definitions. It should reference the AIKernel.NET packages and host Control-specific runtime adapters, emulators, schedulers, and diagnostics in the implementation repositories.

17.2 Provider routing decision DTO split

KernelProviderRoutingDecision is now a pure DTO owned by AIKernel.Dtos.Routing. Core keeps runtime behavior in extension/helper APIs.

Migration example:

using AIKernel.Dtos.Routing;\nusing AIKernel.Kernel;\n\nvar decision = KernelProviderRoutingDecisionFactory.ForProvider(\n    "llm-low",\n    "gpt-mini",\n    providerTier: "low",\n    routeReason: "short-context");\n\nvar routedRequest = decision.ApplyToRequest(request);

17.3 Core DSL and History public surface cleanup

DSL and History ROM contracts are already owned by:

Core keeps Result/ResultStep-based DSL and History runtime adapters internal. Consumers should program against the AIKernel.NET contracts and use hosting registration to obtain runtime implementations.

17.4 Local development versioning

During 0.1.0 development, local packages may use a fourth build segment to avoid NuGet cache collisions.

Before public publication, align the package family back to the release version chosen for NuGet and verify the full dependency graph.

Changelog

• v0.0.0 / v0.0.0.0: Initial draft
• v0.0.1 (2026-05-06): Version upgrade aligned with documentation guidelines
• v0.0.2 (2026-05-09): Added Issue #4 Vfs capability contract migration steps, Issue #7 Vfs naming normalization, provider/security capability contract guidance, Issue #8 contract purity migration, Issue #9 provider capability migration, Issue #10 security/policy separation migration, and Issue #11 sandbox/validator isolation migration
• v0.0.3 (2026-06-02): Added dependency-layer migration for Vfs contract ownership, AIKernel.Vfs type-forwarding compatibility, package-reference guidance, and cycle-verification steps
• v0.0.4 (2026-06-04): Added DSL pipeline, DSL ROM, History ROM, Kernel clock contract extraction, ROM store contracts, ambiguous-interface rename guidance, AIKernel.Vfs package removal steps, and interface-only contract package migration for AIKernel.Core adapter migration
• v0.0.5 (2026-06-05): Removed remaining Abstractions-local DTO/exception implementations, duplicate DTO enums, and legacy ambiguous ChatChain interfaces; added external Capability module contracts, DynamicSLM Model ABI, SeedSLM discipline, distillation offload, HATL external cryptographic operator, governance admissibility gate/trajectory, and Semantic Compilation DTO vocabulary contract preparation
• v0.1.0 (2026-06-07): Adds MemoryRegion / MemoryMapper, Control Plane, and provider-routing DTO contract ownership in AIKernel.Abstractions, AIKernel.Dtos, and AIKernel.Enums while leaving Result-based runtime adapters and routing behavior in Core/Common.
• v0.1.1 (2026-06-10): Adds the synchronized package-family rule for Core, Control, Providers, Tools, WASM, CUDA, and Demo release lines.