03. ROM Core Spec

1. Purpose

Define minimum grammar, canonicalization, and validation contracts for Relation-Oriented Markdown (ROM). In particular, establish a canonicalization process that removes non-deterministic ordering and guarantees deterministic hash invariance.

2. Scope

• YAML front matter (entity identity)
• Headings (scope)
• Bullets (facts/properties)
• [[id]] (relations)

3. Normative Requirements

• RCS-001 A ROM document MUST include entity.id and entity.type.
• RCS-002 [[id]] references MUST be resolvable.
• RCS-003 Facts MUST be declared in bullet form.

3.1 Canonicalization-First Hashing

• RCS-CANON-001 IRomCanonicalizer MUST be applied before semantic hash computation.
• RCS-CANON-002 IRomCanonicalizer MUST sort entity sets by EntityId or Timestamp in ascending order and generate order-independent structure.
• RCS-CANON-003 ISemanticHasher MUST accept only canonicalized payload (CanonicalRomDocument) as input.

4. Canonicalization (Detailed Rules)

To guarantee hash invariance and minimize Git diff noise, canonicalization is applied in the following order.

1. Linguistic Normalization

Normalize full-width/half-width characters, identifier case, and redundant expressions.

2. Structural Sorting (Essential)

Sort entity and bullet sets under the same heading level by EntityId in ascending order. This ensures semantically equivalent edits produce minimal Git diffs, and pure order swaps do not generate semantic diff.

3. Reference Anchoring

Resolve [[entity.id]] into fully qualified identifiers (for example namespace.project.id) before hashing.

Notes:

• Heading numbering variance is treated as equivalent.
• Whitespace/newline/indentation formatting noise is ignored.

5. Required Interfaces

Physically separate canonicalization responsibility from hashing responsibility.

public interface IRomCanonicalizer\n{\n    // Physically sorts and normalizes ROM data to preserve semantic identity in Git diffs\n    CanonicalRomDocument Canonicalize(RomDocument document);\n}\n\npublic interface ISemanticHasher\n{\n    // Computes hash from canonicalized document only\n    string ComputeHash(CanonicalRomDocument canonicalDocument);\n    bool VerifyHash(CanonicalRomDocument canonicalDocument, string expectedHash);\n}\n\npublic sealed record CanonicalRomDocument(\n    string CanonicalBody,\n    IReadOnlyList<CanonicalEntity> Entities,\n    string CanonicalizationVersion);\n\npublic sealed record CanonicalEntity(\n    string EntityId,\n    DateTime? TimestampUtc,\n    string EntityType,\n    IReadOnlyDictionary<string, string> Properties);

6. Fail-Closed

• RCS-F001 Missing mandatory IDs invalidate ROM.
• RCS-F002 Unresolved links reject reasoning input.
• RCS-F003 Hash mismatch (canonicalized recomputation does not match signature) is treated as verification failure.
• RCS-F004 Type Consistency: Reject when entity.type conflicts with declared properties (including missing required properties).
• RCS-F005 Circular Reference Guard: Halt immediately when circular references may trigger reasoning loops.

7. Relation Syntax

ROM relations are expressed in the following three forms.

6.1 Property Relation

Defines static attributes for an entity. Form: * [property_name]: [[target_id]] or value Example: * [author]: [[user.tky]]

6.2 Action Relation

Defines dynamic interaction between entities. Form: * [verb] -> [[target_id]] Example: * [executes] -> [[task.validation]]

6.3 Quantitative Relation

Defines numeric relations used in models such as ModelCapacityVector. Form: * [metric_name]: {numerical_value} Example: * [reasoning_score]: 0.95

8. Integrity Verification

IPromptVerifier validates ROM in the following sequence.

1. Schema Check

Confirm required YAML fields (id, type, version).

2. Graph Linkage Check

Resolve all [[id]] via ISignatureTrustStore and IPromptRepository against trusted nodes.

3. Semantic Hash Match

Verify canonicalized hash equals signed hash field.

9. Acceptance Criteria

• AC1: Equivalent expression variants and reordered item declarations yield identical Semantic Hash.
• AC2: Documents with orphan links, or failures in canonicalization process, are rejected.
• AC3: In Git diff, no diff should occur unless semantic content changes.

Changelog

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