Skip to content

AIKernel.NET v0.0.2 — Interface Rectification & Contract Stabilization Release#13

Merged
egumaru merged 32 commits into
mainfrom
dev
May 9, 2026
Merged

AIKernel.NET v0.0.2 — Interface Rectification & Contract Stabilization Release#13
egumaru merged 32 commits into
mainfrom
dev

Conversation

@egumaru

@egumaru egumaru commented May 9, 2026

Copy link
Copy Markdown
Contributor

AIKernel.NET v0.0.2 — Interface Rectification & Contract Stabilization Release

May 9th — The day the Kernel received its proper names, boundaries, and Phase 1 slots.
5月9日 — Kernel に正しい名前・境界・Phase 1 の抽象スロットを与えた日。

Rectify the Interfaces. Stabilize the Contracts.
名前を正し、境界を分け、契約を安定させる。


Overview / 概要

This release is not a feature release.

It is a structural refinement release for stabilizing the AIKernel.NET abstract contract layer before v0.1.0.

このリリースは、機能追加リリースではありません。

v0.1.0 に向けて、AIKernel.NET の抽象契約レイヤーを安定化させるための構造的リファクタリングリリースです。

This release includes the work from Issue #7 through Issue #12, covering naming normalization, interface segregation, contract purity, provider capability separation, security/policy boundary separation, and Phase 1 Query Processing abstractions.

本リリースでは、Issue #7 から Issue #12 までの対応を含みます。
命名規約の正規化、Interface の責務分離、Contract Purity、Provider Capability 分離、Security / Policy 境界の整理、そして Phase 1 Query Processing 抽象の追加を行いました。


Key Changes / 主な変更点

1. Naming Normalization / 命名規約の正規化

Acronym-based identifiers were normalized according to .NET naming conventions.

.NET の命名規約に従い、頭字語を含む識別子を正規化しました。

Changes include:

  • AIKernel.VFSAIKernel.Vfs
  • AIKernel.VFS.csprojAIKernel.Vfs.csproj
  • namespace updates from AIKernel.VFS to AIKernel.Vfs
  • IROMCanonicalizerIRomCanonicalizer

これにより、コードベース全体の命名が .NET の慣習に沿った自然な形へ整理されました。


2. Contract Purity / 契約純度の向上

Contract objects were reviewed to avoid mixing immutable contract definitions with mutation or transformation behavior.

不変であるべき Contract に mutation や transformation の責務が混入しないよう、契約の純度を見直しました。

In particular, material-related contracts were moved toward immutable views, while processing responsibilities are expected to live in dedicated service interfaces.

特に Material 系の Contract は immutable view に寄せ、正規化・構造化などの処理責務は専用 service interface 側へ分離する方針に整理しました。


3. Capability-Driven Provider Interfaces / Capability 単位の Provider 分離

Provider interfaces were refined to avoid forcing implementations to support capabilities they do not actually provide.

Provider が実際には対応していない capability の実装を強制されないよう、Interface を capability 単位へ分離しました。

This includes the embedding provider split:

  • ITextEmbeddingProvider
  • IBatchEmbeddingProvider
  • IEmbeddingDimensionProvider

これにより、single embedding / batch embedding / dimension metadata を必要に応じて個別に実装できるようになりました。


4. Provider Capability Metadata / Provider Capability Metadata の拡張

Provider capability metadata was extended to support richer Phase 1 and Provider-routing scenarios.

Phase 1 および Provider Routing のために、Provider capability metadata を拡張しました。

Added or refined concepts include:

  • query-processing capability metadata
  • embedding capability metadata
  • semantic projection capability
  • provider routing metadata

これにより、Provider をモデル名ではなく capability に基づいて選択する設計がさらに明確になりました。


5. Security & Policy Boundary Refinement / Security と Policy 境界の整理

Security, policy decision, rule evaluation, and enforcement boundaries were reviewed to avoid overly broad contracts.

Security、Policy Decision、Rule Evaluation、Enforcement の責務が単一の巨大な Contract に混在しないよう、境界を見直しました。

This prepares the ABI for future Governance Plane implementation without forcing premature runtime behavior.

これにより、将来の Governance Plane 実装に向けて、実行時の実装を急がずに ABI 境界を整える準備ができました。


6. Phase 1 Query Processing Abstractions / Phase 1 Query Processing 抽象の追加

New abstractions were added for Phase 1 Context Build.

Phase 1 Context Build のために、Query Processing 系の抽象を追加しました。

Added interfaces and DTOs:

  • IQueryAugmentor
  • IQueryDecomposer
  • IQueryRouter
  • QueryPart
  • IQueryProcessingCapabilities
  • IEmbeddingCapabilityMetadata

These abstractions do not embed RAG directly into Core.

これらの抽象は、RAG を Core に直接組み込むものではありません。

Instead, they define extension slots where RAG and other query-processing strategies can be selected and composed through the pipeline.

RAG を含む Query Processing 技術を Pipeline 上で選択・合成するための抽象スロットを定義するものです。


Documentation Updates / ドキュメント更新

The following documentation areas were updated:

以下のドキュメントを更新しました。

  • README / README-jp
  • Architecture docs
  • Pipeline specs
  • Provider docs
  • Capability definition schema
  • Query Processing interface docs
  • Migration guides
  • Use-case and dependency rule documents

Key documentation additions include:

  • Phase 1 Query Processing architecture
  • Provider capability examples
  • Query Processing pipeline flow
  • Embedding capability metadata
  • clarification that RAG remains a provider / pipeline strategy, not Core retrieval

主な追加内容:

  • Phase 1 Query Processing アーキテクチャ
  • Provider capability 例
  • Query Processing pipeline flow
  • Embedding capability metadata
  • RAG は Core retrieval ではなく Provider / Pipeline strategy であることの明記

Verification / 検証

The solution builds successfully.

ソリューションのビルドが成功することを確認しました。

dotnet build src\AIKernel.NET.slnxSucceeded.

The abstraction tests also pass successfully.

抽象レイヤーのテストも正常に通過しています。

dotnet test src\tests\AIKernel.Abstractions.Tests\AIKernel.Abstractions.Tests.csproj --no-buildSucceeded: 73 tests passed.

Notes / 補足

Some identifiers were intentionally left unchanged.

一部の識別子は、意図的に変更対象外としています。

  • IOException was left unchanged because it is a .NET BCL type name.
  • DTO, API, and ROM were left unchanged where used as descriptive prose.
  • ProviderId was already using the correct spelling and was left unchanged.
  • IEmbeddingProvider was not recreated because embedding contracts were already split into capability-specific interfaces.
  • IOException は .NET BCL 型名のため変更対象外です。
  • DTO, API, ROM は説明文中の一般語として使われている箇所では変更対象外です。
  • ProviderId はすでに正しい表記だったため維持しました。
  • IEmbeddingProvider は、すでに capability 単位の Interface へ分離済みだったため、重複作成していません。

Why This Matters / このリリースの意味

This release is small in runtime behavior, but large in architectural meaning.

このリリースは、実行時の振る舞いとしては小さいものです。
しかし、アーキテクチャ上の意味は大きいものです。

Before v0.1.0 turns the contracts into executable runtime components, the abstract layer must have correct names, clean boundaries, capability-driven providers, and Phase 1 extension slots.

v0.1.0 で Contract を実行可能なランタイムコンポーネントへ進化させる前に、抽象レイヤーには正しい名前、明確な境界、capability-driven な Provider、そして Phase 1 の拡張スロットが必要です。

This release prepares that foundation.

本リリースは、そのための基盤を整えるものです。


Closing / 結び

Names define boundaries.
Boundaries define contracts.
Contracts define execution.

名前は境界を定義する。
境界は契約を定義する。
契約は実行を定義する。

Rectify the Interfaces. Stabilize the Contracts.
名前を正し、境界を分け、契約を安定させる。

egumaru added 30 commits May 2, 2026 04:10
…osed use-case tests

Re-define IExecutionConstraints for SGS-007 (allowed_tools, scopes, max_token_budget)
Rework prompt governance contracts to result-based fail-closed decisions
Add spec-alignment tests for Execution Pipeline, Signed Prompt Governance, and ROM Core using interface composition stubs
Verify all abstraction tests pass (30 passed)
…-core leakage

Remove AIKernel.Abstractions project references to AIKernel.Dtos and AIKernel.Enums
Introduce core-local contract data types/enums under AIKernel.Abstractions.Core
Add global using for core-local types to keep interface signatures cohesive
Normalize namespace-to-folder alignment across UseCases and Governance
Eliminate abstraction-layer implementation logic from IExecutionOutput (PhaseHandoverResult factories removed)
Reduce leaky abstraction patterns by replacing object-based dictionaries/signatures with typed string-based contracts
Update tests to match new contract namespaces/signatures; verify all abstraction tests pass (30/30)
- docs/architecture に Semantic Context OS ビジョン(v0.0.0)を新規追加
- Thinkingモードによる「抽象汚染(Abstract Pollution)」のリスクを明文化
- 「高速モード = 純粋推論」の原則(Fast-as-Pure)を設計原則に統合
- 思考ステップ制約(Step Constraint)による中間プロセスのガバナンスを定義
- 三層隔離メモリモデル(MMU)によるコンテキスト統治の概念を確立
…replay/rom integrity updates

integrate updated drafts into 02/03/04/06 specs (JP/EN) with deterministic governance, canonicalization-first hashing, replay lock contracts, and force-provider replay flow
reorganize 16.SEMANTIC_CONTEXT_OS_VISION (JP/EN) with SIR requirements, kernel startup state machine, and logical audit constraints
fix architecture index reference mismatches and update 1.15 summaries to reflect new SIR/state-machine model
preserve fail-closed semantics across updated documents and align section numbering for cross-doc consistency
AIKernel.Abstractions から public class/record/enum/struct を排除し、interface-only 構成へ再編
AIKernel.Dtos / AIKernel.Enums に契約データ型を移設・新設(Routing/Context/Governance/Prompt など)
Abstractions の参照を Dtos / Enums に統一し、GlobalUsings と csproj 依存を整理
旧重複定義(CoreDataTypes, ModelCapacityVector, StandardCapacityAxis ほか)を削除
テスト参照を新しい DTO/Enum 名前空間に追従させ、ビルド成立を確認 (AIKernel.Abstractions.Tests)
AIKernel.Abstractions / AIKernel.Dtos / AIKernel.Enums の複数型同居ファイルを解消し、1 class|record|enum|struct = 1 file に統一
TransferTrace / Purpose、Prompt系DTO、ROM系DTO、Buffer系DTOを個別ファイルへ分離
LatencyClass から ModelType / Modality を分離、PdpDecision から RejectCode を分離
Abstractions内の具体型(KernelExecutionResult、AttentionAnalysis、AccessRequest など)を個別ファイル化し、可読性と保守性を向上
ROM検証関連型を分割し、型定義の責務境界を明確化
AIKernel.VFSをInterface専用に整理し、具象データ型をAIKernel.Dtos.Vfsへ移管
VfsEntryTypeをAIKernel.Enumsへ移管し、VFS境界の責務を明確化
VFSインターフェースのシグネチャをDTO参照へ更新(object辞書をstring辞書へ型安全化)
AIKernel.VFS.csprojの未使用参照(KernelContext/Enums)を削除し依存を最小化
Prompt系DTOのrequired/初期化子を統一しnullable警告を解消
関連テスト(SignedPrompt/MaterialQuarantine)を新DTO初期化方式へ追従
AuditEventの型不整合(AuditSeverity/Metadata)を契約に合わせて修正
REPO_DEPENDENCY_RULES(英日)およびVFSインターフェース文書/indexを最新構成へ同期
- Consolidate 'KernelContext' and 'Events' projects into Abstractions/Dtos/Core to eliminate project fragmentation and clarify architectural layers.
- Split files containing multiple definitions into individual files.
- Remove 'UseCases' namespace to purge application-level leakage (Ref: Issue #2).
- Restructure directory and namespace hierarchy to improve modularity.
- Ensure all types are organized by their architectural roles (VFS, Kernel, etc.).
- Align project with strict C# conventions for upcoming AIKernel.Core implementation.
- Remove DTO-layer exception classes and exception-oriented tests to keep DTOs as pure data contracts.
- Align DTO namespaces with physical paths (Context/Core/Messaging) for full Structure Integrity.
- Replace ambiguous router contracts:
  - Routing: IModelVectorRouter -> IRoutingDecisionEngine
  - Execution: IModelVectorRouter -> IExecutionVectorRouter
- Update related references/global usings and verify build integrity across Abstractions/DTOs/Tests.

This structural refinement establishes a clean, navigable 'Canonical Source'
at version 0.0.1, ensuring deterministic dependency management.

Fixes #2
リプレイ機能の保証範囲について、「LLM の内部推論アルゴリズム自体の再現は目的とせず、実行時のコンテキスト構成・パイプライン通過順序・各ステップのデータ変換が記録と同一の論理パスを辿ることのみを保証する」旨を明記しました。英語・日本語両方のドキュメントに追記しています。
AIKernel.NET の設計意図や契約レイヤの意義を明確化し、C#によるホスティング例・curlによるAPI実行例・レスポンス例を README-jp.md/README.md に追加。アーキテクチャやリポジトリ構成の説明も整理し、実装分離の方針を強調。英語READMEも同様に刷新。
Directory.Build.props のリリースノートを英日両言語で詳細化し、AIKernel.NET の設計思想やコアスペックを明記。各 csproj から <Version> 記述を削除し、バージョン管理を共通プロパティに集約。
README-jp.md/README.md を全面的にリライトし、構成・表記・内容を整理・強化しました。NuGetパッケージ一覧やリポジトリ構成表を刷新し、各レイヤーや設計原則の説明を体系化。API実行例・起動ログ例を追加し、コントリビューションやライセンスの指針も明文化。英語READMEも日本語版と同等の内容にアップデートしました。
すべてのcsprojから著者・会社・ライセンス等のパッケージメタデータを削除し、Directory.Build.propsに集約しました。バージョンも0.0.2へ更新し、全プロジェクトで一貫した情報管理を実現しました。ビルド設定や説明文には変更ありません。
VFSインターフェースをcapability-based設計に大幅リファクタリング。`IReadableVfsSession`等の細分化interfaceを新設し、権限を型安全に表現。従来の合成契約は後方互換で維持。ドキュメントも責務・設計方針・fail-closed原則を明記し刷新。ユニットテストでcapability分離の動作を検証。権限管理・拡張性・型安全性を強化。
#4
v0.0.2対応として、VFSの命名を.NETガイドライン準拠の「Vfs」へ統一する破壊的変更手順を追加。namespace・プロジェクト名・パッケージ名・ドキュメント表記の変更、`ProviderID`→`ProviderId`への統一も明記。
Vfs権限をcapability interfaceベースへ移行する手順・指針を追加し、既存contractとの互換性や新規実装の推奨方針も記載。
移行チェックリストと変更履歴(v0.0.2: Issue #4, #7)も追記。
全ドキュメントで「VFS」を「Vfs」へ統一しました。タイトル、見出し、表、契約名、依存関係表などVFS関連の表記揺れを修正し、設計・拡張点・ユースケース・ガイド等の用語一貫性を向上。仕様自体の変更はありません。#4, #7
仮想ファイルシステム層の命名を `VFS` から `Vfs` へ統一しました。プロジェクト名、名前空間、NuGet パッケージ名、ドキュメント、テスト、依存関係など全体を対象にリネームを実施し、表記ゆれを解消しました。
#4, #7
IROMCanonicalizer→IRomCanonicalizer等、acronym命名を.NET標準に統一。Provider/RAG/ToolAccess等の大規模インターフェースをcapability contract群に分割し、合成インターフェースで再構成。全ドキュメント・テスト・マイグレーションガイドを反映。型安全性・拡張性・責務分離を強化し、実行時挙動は不変。
#7
EventBus/Task/Scheduler/Tokenizer/SignatureTrustStore/Kernel等の主要インターフェースをcapability interface群として細分化・再設計。合成インターフェースは用途ごとに必要最小限のcapabilityのみを継承し、観測専用・購読専用adapter等が不要な権限を持たない設計に。MIGRATION_GUIDEも更新。各capability分離の正当性を検証するテストを追加。
#7
egumaru added 2 commits May 9, 2026 17:05
v0.0.2対応として、各種契約インターフェースから正規化・検証・変換・分析などの責務を排除し、専用サービスインターフェースへ移動。不変ビュー/記述子のみを契約で表現。Provider/Store/Validator/Sandbox/Compute/Security/Policy/Rule/Audit等の広いインターフェースを細粒度capability interfaceに分割し、合成互換インターフェースを追加。テスト・ドキュメントも新設計に対応。MIGRATION_GUIDEに移行ガイドを追記。
#8, #9, #10, #11
AIKernelにPhase 1 Query Processing(補間・分解・意味空間化・routing)抽象を追加し、`IQueryAugmentor`/`IQueryDecomposer`/`IQueryRouter`/`QueryPart`を新設。
Provider capabilityにquery-processing/embeddingメタデータを拡張し、責務境界・Fail-Closed条件を明確化。
主要ドキュメント・テスト・usingも対応。RAG/embeddingのCore分離を徹底。
#12
@egumaru egumaru merged commit 9ba2005 into main May 9, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant