Japanese version: IMessageContract (契約仕様)

IMessageContract (Contract Specification)

1. Responsibility Boundary

IMessageContract defines the standard envelope format for messages exchanged inside the kernel and across external integration boundaries.

• Role:

Provide common fields for identity, type, timestamp, source/destination, headers, and payload to enable loose coupling.

• Non-role:

Delivery control, retry behavior, queueing, and payload interpretation are out of scope.

2. Contract Signature

namespace AIKernel.Contracts;\n\n/// <summary>\n/// メッセージ契約を定義します。\n/// カーネル内通信のメッセージ形式を標準化します。\n/// </summary>\npublic interface IMessageContract\n{\n    /// <summary>\n    /// メッセージの一意識別子を取得します。\n    /// </summary>\n    string MessageId { get; }\n\n    /// <summary>\n    /// メッセージの種類を取得します。\n    /// </summary>\n    string MessageType { get; }\n\n    /// <summary>\n    /// メッセージ送信時刻を取得します。\n    /// </summary>\n    DateTime Timestamp { get; }\n\n    /// <summary>\n    /// メッセージの送信元を取得します。\n    /// </summary>\n    string Source { get; }\n\n    /// <summary>\n    /// メッセージの宛先を取得します。\n    /// </summary>\n    string Destination { get; }\n\n    /// <summary>\n    /// メッセージのペイロードを取得します。\n    /// </summary>\n    object? Payload { get; }\n\n    /// <summary>\n    /// メッセージのヘッダーを取得します。\n    /// </summary>\n    IReadOnlyDictionary<string, string>? Headers { get; }\n}

3. Related Use Cases

• UC-25 Event bus distribution:

Serves as the common packet contract for inter-component event flow.

• UC-20 Deterministic replay and audit trail:

Supports timeline reconstruction with Timestamp and correlation headers.

• UC-29 Task pipeline management:

Used for asynchronous progress signals and phase-transition notifications.

4. Governance & Determinism

• Immutability in transit:

Preserve MessageId and Payload integrity during delivery.

• Traceability:

Include CorrelationId (or equivalent) in Headers to trace message chains end-to-end.

• Time coherence:

Timestamp should follow a consistent UTC convention for reliable audit ordering.

5. Implementation Notes

• Serialization portability:

Use DTO implementations that serialize stably (e.g., JSON) for transport and persistence.

• Type safety:

When using object? Payload, pair with typed wrappers or generic contracts for safer runtime handling.

Changelog

• v0.0.0 / v0.0.0.0: Initial draft
• v0.0.1 (2026-05-06): Version upgrade aligned with documentation guidelines