Skip to content

Commit bcc014e

Browse files
egumaruegumaru
authored
Finalize CTG contract surface for AIKernel.NET v0.1.1.1 (#20)
# AIKernel.NET v0.1.1.1 AIKernel.NET v0.1.1.1 updates the public contract packages with the finalized CTG / Monolith-ROM contract surface. This release focuses on interface, DTO, enum, and documentation alignment only. It does not add runtime implementation code. ## Highlights - Finalized CTG governance contract carriers. - Normalized `GateInput` as a pure triadic vote-only DTO. - Updated `DecisionGateRequest` to accept a single `GateInput`. - Preserved the Logos / Ethos / Pathos council model. - Kept Gate and Trajectory Gate decisions discrete-only. - Updated CTG developer documentation and contract model guidance. - Rebuilt NuGet packages for `0.1.1.1`. ## Packages - `AIKernel.Abstractions` `0.1.1.1` - `AIKernel.Contracts` `0.1.1.1` - `AIKernel.Dtos` `0.1.1.1` - `AIKernel.Enums` `0.1.1.1` ## Notes - No GitHub release is required for this update. - No PyPI package is produced for the `0.1.1.1` line. - Runtime implementations remain outside this repository.
1 parent 2f25d48 commit bcc014e

420 files changed

Lines changed: 18497 additions & 682 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎Directory.Build.props‎

Lines changed: 28 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,15 @@
11
<Project>
22
<PropertyGroup>
3-
<Version>0.1.1</Version>
4-
<AssemblyVersion>0.1.1</AssemblyVersion>
5-
<FileVersion>0.1.1</FileVersion>
6-
<InformationalVersion>0.1.1</InformationalVersion>
3+
<StablePackageVersion>0.1.1.1</StablePackageVersion>
4+
<LocalPackageVersionPrefix>0.1.1</LocalPackageVersionPrefix>
5+
<LocalPackageBuildNumber Condition="'$(LocalPackageBuildNumber)' == ''">0</LocalPackageBuildNumber>
6+
<UseLocalPackageVersion Condition="'$(UseLocalPackageVersion)' == ''">false</UseLocalPackageVersion>
7+
<PackageVersion Condition="'$(UseLocalPackageVersion)' == 'true'">$(LocalPackageVersionPrefix)-dev$(LocalPackageBuildNumber)</PackageVersion>
8+
<PackageVersion Condition="'$(UseLocalPackageVersion)' != 'true'">$(StablePackageVersion)</PackageVersion>
9+
<Version>$(PackageVersion)</Version>
10+
<AssemblyVersion>$(StablePackageVersion)</AssemblyVersion>
11+
<FileVersion>$(StablePackageVersion)</FileVersion>
12+
<InformationalVersion>$(PackageVersion)</InformationalVersion>
713
<GenerateDocumentationFile>true</GenerateDocumentationFile>
814
<Authors>Takuya Sogawa</Authors>
915
<Company>AIKernel-NET</Company>
@@ -14,6 +20,24 @@
1420
<PackageTags>aikernel;aikernel-core;ai-os;architecture;category-separation;context-isolation;contract-driven;governance;admissibility;preprocessing;semantic-context-os;semantic-compilation;deterministic-replay;fail-closed;rom;canonicalization;pdp;signed-prompt;interface-contracts;dto;enum;capability-modules;dynamicslm;seedslm;hatl</PackageTags>
1521
<PackageReleaseNotes>
1622
<![CDATA[
23+
AIKernel.NET v0.1.1.1 — Interface Extension Update
24+
25+
• Prepares the AIKernel.NET contract packages for package-level interface extension updates.
26+
• Keeps the v0.1.1 public contract baseline backward-compatible.
27+
• Uses package-public updates only; no GitHub release is required for this line.
28+
• Keeps AIKernel.Abstractions and AIKernel.Contracts interface-only.
29+
• Keeps DTO ownership in AIKernel.Dtos and enum ownership in AIKernel.Enums.
30+
• Supports local development package versions as 0.1.1-dev{buildNumber}.
31+
32+
AIKernel.NET v0.1.1.1 — Interface Extension Update
33+
34+
• AIKernel.NET contract package を package-level の interface 拡張更新向けに準備。
35+
• v0.1.1 の公開 contract baseline との後方互換性を維持。
36+
• GitHub release は作成せず、公開済み個別 package の更新として扱う。
37+
• AIKernel.Abstractions / AIKernel.Contracts は interface-only を維持。
38+
• DTO は AIKernel.Dtos、enum は AIKernel.Enums が所有。
39+
• ローカル開発 package version は 0.1.1-dev{buildNumber} を使用。
40+
1741
AIKernel.NET v0.1.1 — First Stable Contract Baseline
1842
1943
• Promotes the AIKernel.NET contract packages to the first 0.1.1 baseline.

‎README.md‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
updated: 2026-06-07
2+
updated: 2026-06-14
33
published: 2026-06-10
4-
version: "0.1.1"
4+
version: "0.1.1.1"
55
edition: "Release"
66
status: "Release"
77
issuer: ai-kernel@aikernel.net
@@ -289,6 +289,23 @@ For the latest structure and cross-links, use the category indexes:
289289
- `docs/papers/README.md`
290290
- `docs/theory/README.md` / `docs/theory/README-jp.md`
291291

292+
For the v0.1.1.1 additive contract surface, start with:
293+
294+
- `docs/architecture/19.DOMAIN_CONTRACT_SURFACE-v0.1.1.1.md`
295+
- `docs/architecture/20.CANONICAL_TRAJECTORY_GOVERNANCE-v0.1.1.1.md`
296+
- `docs/architecture/21.CTG_DEVELOPER_THEORY-v0.1.1.1.md`
297+
- `docs/design/CTG_CONTRACT_MODEL-v0.1.1.1.md`
298+
- `docs/operations/CTG_DEVELOPER_GUIDE-v0.1.1.1.md`
299+
- `docs/operations/CTG_ROM_LAYOUT-v0.1.1.1.md`
300+
- `docs/papers/12-canonical-trajectory-governance/README.md`
301+
- `docs/operations/INTERFACE_EXTENSION_NAMING-v0.1.1.1.md`
302+
- `docs/operations/ENUM_HANDLING_POLICY-v0.1.1.1.md`
303+
- `docs/operations/XML_DOCUMENTATION_POLICY-v0.1.1.1.md`
304+
305+
The `0.1.1.1` package line is .NET / NuGet-only. Do not build or publish PyPI
306+
packages for `0.1.1.1`; Python wrappers remain on the synchronized `0.1.1`
307+
package line.
308+
292309
---
293310

294311
## Repository Mapping

‎docs/CONTRIBUTING-jp.md‎

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@ title: "AIKernel Contributing Guide"
44
scope:
55
- repo: AIKernel.NET
66
createdAt: 2026-04-28T00:00:00Z
7-
updated: 2026-05-16
7+
updated: 2026-06-14
88
published: 2026-05-16
9-
version: "0.0.2"
9+
version: "0.1.1.1"
1010
edition: "Draft"
1111
status: "Refactor"
1212
issuer: ai-kernel@aikernel.net
@@ -60,19 +60,26 @@ CI は build と test を実行し、ベースライン品質を確認します
6060
- 大規模変更は小さな PR に分割してください。
6161

6262
### 5. XML documentation
63-
- Public API には XML ドキュメント（`/// <summary>`、パラメータ説明、remarks）を付与してください。
63+
- Public API にはバイリンガル XML ドキュメント（`/// <summary>`、パラメータ説明、型パラメータ説明、戻り値説明）を付与してください。
64+
- inline XML docs では英語本文に続けて `JA:` で日本語本文を記述してください。既存の external docs を使う場合は `docs.en.xml` と `docs.ja.xml` を対で include してください。
65+
- [`operations/XML_DOCUMENTATION_POLICY-v0.1.1.1-jp.md`](operations/XML_DOCUMENTATION_POLICY-v0.1.1.1-jp.md) に従ってください。
6466
- ドキュメントは常に最新化し、`docs/` と README に反映してください。
6567

6668
### 6. Mark breaking changes
6769
- 必要な場合は PR タイトルに **[Breaking]** を付けてください。
6870
- 例: `[Breaking] Modify RetrievalQuery structure`
6971
- 破壊的変更の理由と移行計画を Issue に記載してください。
7072

71-
### 7. APM and package management
73+
### 7. CTG contract changes
74+
- CTG の変更は contract-only、つまり interface、DTO record、enum に限定する。
75+
- [`operations/CTG_DEVELOPER_GUIDE-v0.1.1.1-jp.md`](operations/CTG_DEVELOPER_GUIDE-v0.1.1.1-jp.md) に従う。
76+
- canon rule body や runtime behavior を AIKernel.NET に追加しない。
77+
78+
### 8. APM and package management
7279
- AIKernel.NET は skills / prompts / agents / hooks / MCP servers のための APM を利用します。
7380
- 新規アーティファクトは Issue 経由で追加し、リポジトリのパッケージ規約に従ってください。
7481

75-
### 8. Link Issues and PRs
82+
### 9. Link Issues and PRs
7683
- 可能な限り PR と関連 Issue を相互リンクしてください。
7784
- 明示的な解決なしに Issue を close しないでください。
7885

@@ -107,7 +114,10 @@ CI は build と test を実行し、ベースライン品質を確認します
107114
- PR が 1 つの目的に集中している
108115
- Contract/interface/DTO 変更に対して Issue がある
109116
- 破壊的変更に `[Breaking]` が付いている
110-
- Public API の XML ドキュメントがある
117+
- Public API のバイリンガル XML ドキュメントがある
118+
- semantic interface naming を確認し、機械的な expansion suffix を使っていない
119+
- enum 追加時に `Unknown = 0` と fail-closed handling guidance を確認している
120+
- CTG の変更では `operations/CTG_DEVELOPER_GUIDE-v0.1.1.1-jp.md` に従っている
111121
- `guidelines/AIKERNEL_DEVELOPMENT_GUIDELINES.md` または
112122
`guidelines/AIKERNEL_DEVELOPMENT_GUIDELINES-jp.md` への適合を確認している
113123
- CI が成功している
@@ -136,3 +146,4 @@ AIKernel は **.NET 10 / C# 14** を対象とする、プロダクション品
136146
# 変更履歴
137147
- v0.0.0 / v0.0.0.0: 初期ドラフト
138148
- v0.0.1 (2026-05-06): ドキュメント規約に基づくバージョン更新
149+
- v0.1.1.1 (2026-06-14): バイリンガル XML documentation、semantic interface naming、enum handling policy、CTG developer guide の参照を追加

‎docs/CONTRIBUTING.md‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@ title: "AIKernel Contributing Guide"
44
scope:
55
- repo: AIKernel.NET
66
createdAt: 2026-04-28T00:00:00Z
7-
updated: 2026-05-16
7+
updated: 2026-06-14
88
published: 2026-05-16
9-
version: "0.0.2"
9+
version: "0.1.1.1"
1010
edition: "Draft"
1111
status: "Refactor"
1212
issuer: ai-kernel@aikernel.net
@@ -61,19 +61,26 @@ CI runs build and tests to ensure baseline quality.
6161
- Large changes should be split into smaller PRs.
6262

6363
### 5. XML documentation
64-
- Public APIs must include XML docs (`/// <summary>`, parameter descriptions, remarks).
64+
- Public APIs must include bilingual XML docs (`/// <summary>`, parameter descriptions, type parameter descriptions, and return descriptions).
65+
- Inline XML docs use English followed by `JA:` Japanese text. Existing external docs must use paired `docs.en.xml` and `docs.ja.xml` includes.
66+
- Follow [`operations/XML_DOCUMENTATION_POLICY-v0.1.1.1.md`](operations/XML_DOCUMENTATION_POLICY-v0.1.1.1.md).
6567
- Keep docs up to date and reflect in `docs/` and README.
6668

6769
### 6. Mark breaking changes
6870
- Prefix PR titles with **[Breaking]** when applicable.
6971
- Example: `[Breaking] Modify RetrievalQuery structure`
7072
- Create an Issue to explain the breaking change and migration plan.
7173

72-
### 7. APM and package management
74+
### 7. CTG contract changes
75+
- CTG changes must remain contract-only: interfaces, DTO records, and enums.
76+
- Follow [`operations/CTG_DEVELOPER_GUIDE-v0.1.1.1.md`](operations/CTG_DEVELOPER_GUIDE-v0.1.1.1.md).
77+
- Do not add canon rule bodies or runtime behavior to AIKernel.NET.
78+
79+
### 8. APM and package management
7380
- AIKernel.NET uses an APM (Agent Package Manager) for skills, prompts, agents, hooks, MCP servers.
7481
- Add new artifacts via Issue and follow repository packaging conventions.
7582

76-
### 8. Link Issues and PRs
83+
### 9. Link Issues and PRs
7784
- Link PRs to the related Issue when applicable.
7885
- Avoid closing Issues without explicit resolution.
7986

@@ -109,6 +116,10 @@ CI runs build and tests to ensure baseline quality.
109116
- Create Issues for contract/interface/DTO changes
110117
- Mark breaking changes with `[Breaking]`
111118
- Provide XML docs for public APIs
119+
- Confirm bilingual XML documentation for public APIs
120+
- Confirm semantic interface naming and avoid mechanical expansion suffixes
121+
- Confirm enum `Unknown = 0` and fail-closed handling guidance when adding enums
122+
- Confirm CTG changes follow `operations/CTG_DEVELOPER_GUIDE-v0.1.1.1.md` when applicable
112123
- Confirm compliance with `guidelines/AIKERNEL_DEVELOPMENT_GUIDELINES.md`
113124
or `guidelines/AIKERNEL_DEVELOPMENT_GUIDELINES-jp.md`
114125
- Ensure CI passes
@@ -137,3 +148,4 @@ AIKernel targets **.NET 10 / C# 14** and aims to be a production-grade contract-
137148
# Changelog
138149
- v0.0.0 / v0.0.0.0: Initial draft
139150
- v0.0.1 (2026-05-06): Version upgrade aligned with documentation guidelines
151+
- v0.1.1.1 (2026-06-14): Added bilingual XML documentation, semantic interface naming, enum handling policy, and CTG developer guide references

‎docs/architecture/19.DOMAIN_CONTRACT_SURFACE-v0.1.1.1-jp.md‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
---
2+
updated: 2026-06-14
3+
published: 2026-06-14
4+
version: "0.1.1.1"
5+
edition: "Draft"
6+
status: "Active"
7+
issuer: ai-kernel@aikernel.net
8+
maintainer: "拓也（AIKernel プロジェクト メンテナー）"
9+
---
10+
11+
# Domain Contract Surface v0.1.1.1
12+
13+
AIKernel.NET v0.1.1.1 は、既存の v0.1.1 API シグネチャを変更せずに、
14+
公開 contract surface を拡張する。adapter binding、runtime control、
15+
replay、observability、diagnostics、operator strategy、profiles、
16+
telemetry、metrics、HUD signal、overlay annotation のための semantic
17+
interface、DTO、enum を追加する。また、canonical triadic governance のための
18+
contract-only な governance carrier と evaluator を追加する。
19+
20+
この変更は追加型である。v0.1.1 の既存 interface を利用する consumer は、
21+
同じ method signature のままコンパイルを継続できる。新機能を利用する
22+
consumer は、新しい semantic interface と DTO を opt-in で参照する。
23+
24+
---
25+
26+
## 1. 互換性ルール
27+
28+
- 既存 public interface は rename / replace しない。
29+
- 既存 public method signature は変更しない。
30+
- 既存 enum value は削除・rename しない。
31+
- 新しい振る舞いは、新しい semantic interface、DTO record、enum type で表現する。
32+
- failure を表現しうる descriptor / snapshot DTO は optional failure envelope を持つ。
33+
- contract package の純度を維持する。
34+
- `AIKernel.Abstractions`: interface のみ
35+
- `AIKernel.Contracts`: interface のみ
36+
- `AIKernel.Dtos`: DTO record のみ
37+
- `AIKernel.Enums`: enum type のみ
38+
39+
---
40+
41+
## 2. 追加 semantic interface
42+
43+
### Adapters
44+
45+
- `AIKernel.Abstractions.Adapters.IProviderAdapter`
46+
- `AIKernel.Abstractions.Adapters.IRuntimeAdapter`
47+
48+
### Runtime
49+
50+
- `AIKernel.Abstractions.Runtime.ISandboxRuntimeControlProvider`
51+
- `AIKernel.Abstractions.Runtime.IProcessControlProvider`
52+
53+
### Replay / Observability
54+
55+
- `AIKernel.Abstractions.Replay.IReplayProvider`
56+
- `AIKernel.Abstractions.Observability.IEvidenceCollector`
57+
58+
### Diagnostics
59+
60+
- `AIKernel.Abstractions.Diagnostics.IDiagnosticsProvider`
61+
62+
### Operators
63+
64+
- `AIKernel.Abstractions.Operators.IOperatorStrategyProvider`
65+
66+
### Profiles
67+
68+
- `AIKernel.Abstractions.Profiles.IProfileStoreProvider`
69+
- `AIKernel.Abstractions.Profiles.IProfileOptimizationProvider`
70+
71+
### Telemetry / Metrics
72+
73+
- `AIKernel.Abstractions.Telemetry.ITelemetryProvider`
74+
- `AIKernel.Abstractions.Metrics.IMetricsProvider`
75+
76+
### Perception
77+
78+
- `AIKernel.Abstractions.Perception.IHudSignalProvider`
79+
- `AIKernel.Abstractions.Perception.IOverlayAnnotationProvider`
80+
- `AIKernel.Abstractions.Perception.IDiagnosticFramePerceptionProvider`
81+
82+
### Governance
83+
84+
- `AIKernel.Abstractions.Governance.ICouncilEvaluator`
85+
- `AIKernel.Abstractions.Governance.IDecisionGate`
86+
- `AIKernel.Abstractions.Governance.ITrajectoryGate`
87+
- `AIKernel.Abstractions.Governance.IRomGovernanceEngine`
88+
89+
---
90+
91+
## 3. DTO domain
92+
93+
追加 DTO domain は次の通り。
94+
95+
- `AIKernel.Dtos.Adapters`
96+
- `AIKernel.Dtos.Runtime`
97+
- `AIKernel.Dtos.Replay`
98+
- `AIKernel.Dtos.Observability`
99+
- `AIKernel.Dtos.Diagnostics`
100+
- `AIKernel.Dtos.Operators`
101+
- `AIKernel.Dtos.Profiles`
102+
- `AIKernel.Dtos.Telemetry`
103+
- `AIKernel.Dtos.Metrics`
104+
- `AIKernel.Dtos.Perception`
105+
- `AIKernel.Dtos.Governance`
106+
107+
collection は空値で初期化し、metadata dictionary は空 dictionary で初期化する。
108+
Result-like DTO は、予測可能な failure を例外ではなく安定した failure field で表す。
109+
110+
Governance DTO は semantic carrier name を使う。Council vote は
111+
`CouncilVote` carrier と `CouncilVoteValue` enum、reject detail は
112+
`RejectReasonInfo`、canon link は `IReadOnlyList<CanonReference>` で表現し、
113+
将来の複数 canon reference を DTO shape の変更なしに保持できるようにする。
114+
115+
CTG 固有の architecture と developer guidance は
116+
[`20.CANONICAL_TRAJECTORY_GOVERNANCE-v0.1.1.1-jp.md`](20.CANONICAL_TRAJECTORY_GOVERNANCE-v0.1.1.1-jp.md)、
117+
[`21.CTG_DEVELOPER_THEORY-v0.1.1.1-jp.md`](21.CTG_DEVELOPER_THEORY-v0.1.1.1-jp.md)、
118+
[`../design/CTG_CONTRACT_MODEL-v0.1.1.1-jp.md`](../design/CTG_CONTRACT_MODEL-v0.1.1.1-jp.md)、
119+
[`../operations/CTG_DEVELOPER_GUIDE-v0.1.1.1-jp.md`](../operations/CTG_DEVELOPER_GUIDE-v0.1.1.1-jp.md)
120+
に整理する。
121+
固定された理論参照は
122+
[`../papers/12-canonical-trajectory-governance/README.md`](../papers/12-canonical-trajectory-governance/README.md)
123+
である。
124+
125+
---
126+
127+
## 4. Failure Envelope
128+
129+
成功・失敗を運びうる descriptor / snapshot DTO は、次の optional field を追加する。
130+
131+
```csharp
132+
public bool? Succeeded { get; init; }
133+
public string? ErrorCode { get; init; }
134+
public string? ErrorMessage { get; init; }
135+
public DiagnosticInfo? Diagnostics { get; init; }
136+
```
137+
138+
これらは optional であり、既存 DTO consumer の binary/source 互換性を維持する。
139+
予測可能な failure は envelope 経由で返す。cancellation は
140+
`OperationCanceledException` を引き続き利用できる。
141+
142+
---
143+
144+
## 5. Enum domain
145+
146+
新規 domain enum は次のような domain namespace に配置する。
147+
148+
- `AIKernel.Enums.Adapters`
149+
- `AIKernel.Enums.Runtime`
150+
- `AIKernel.Enums.Replay`
151+
- `AIKernel.Enums.Observability`
152+
- `AIKernel.Enums.Diagnostics`
153+
- `AIKernel.Enums.Operators`
154+
- `AIKernel.Enums.Profiles`
155+
- `AIKernel.Enums.Telemetry`
156+
- `AIKernel.Enums.Metrics`
157+
- `AIKernel.Enums.Perception`
158+
- `AIKernel.Enums.Governance`
159+
160+
すべての新規 enum は `Unknown = 0` を持つ。未知値は
161+
[`../operations/ENUM_HANDLING_POLICY-v0.1.1.1-jp.md`](../operations/ENUM_HANDLING_POLICY-v0.1.1.1-jp.md)
162+
で定義する fail-closed policy に従って扱う。
163+
164+
---
165+
166+
## 6. ドキュメントとコメント
167+
168+
public contract member にはバイリンガル XML documentation を付与する。
169+
inline XML documentation では、英語本文に続けて `JA:` で日本語本文を記述できる。
170+
既存の external documentation include を使う場合は、`docs.en.xml` と
171+
`docs.ja.xml` を対で用意する。
172+
173+
コントリビュータ向け規約は
174+
[`../operations/XML_DOCUMENTATION_POLICY-v0.1.1.1-jp.md`](../operations/XML_DOCUMENTATION_POLICY-v0.1.1.1-jp.md)
175+
に定義する。
176+
177+
---
178+
179+
## 7. 検証サーフェス
180+
181+
v0.1.1.1 の contract surface は次で検証する。
182+
183+
```powershell
184+
dotnet build src\AIKernel.NET.slnx
185+
dotnet test src\tests\AIKernel.Abstractions.Tests\AIKernel.Abstractions.Tests.csproj --no-build
186+
dotnet pack src\AIKernel.NET.slnx -c Release
187+
dotnet pack src\AIKernel.NET.slnx -c Release -p:UseLocalPackageVersion=true -p:LocalPackageBuildNumber=<build-number>
188+
```
189+
190+
local development package version は次を使う。
191+
192+
```text
193+
0.1.1-dev<build-number>
194+
```

0 commit comments

Comments
 (0)