feat: Validation Kernel — Patch Schema, Invariants, and Cryptographic Verification

[flyingrobots]

Summary

Extracts the Validation Kernel from Milestone 3 as a standalone, reviewable PR. This provides the cryptographic and schema foundation for patch validation.

• Patch Validation Kernel: Strict AJV schema validator + 13-invariant checker with structured error codes
• Ed25519 Signature Verification: Full detached-signature pipeline with Blake3 payload digests and keyring-based key resolution
• Test Matrix: 31-test single-fault mutation suite systematically covering all patch invariants via golden fixture
• Machine Error Codes: InvariantCode enum for stable, machine-assertable validation errors
• CI Gate: GitHub workflow (patch-ops-gate.yml) for automated patch validation on PRs

Key Components

• src/validation/validatePatchOps.ts - Core validator with schema + invariant checking
• src/validation/crypto.ts - Ed25519 signature verification, Blake3 hashing, canonicalization
• src/validation/InvariantCode.ts - Structured error codes (13 invariants)
• schemas/PATCH_OPS_SCHEMA.v1.json - Locked JSON schema for patch operations
• test/matrix/* - Comprehensive test matrix with golden fixture methodology
• scripts/create-fixture.ts - Deterministic golden fixture generator
• .github/workflows/patch-ops-gate.yml - CI gate for patch validation

Schema Hardening

• Fixed 5 AJV strict-mode blockers (if/then schemas, additionalProperties)
• Added support for KEY- and did:key:z6 keyId formats
• Changed signature to hex encoding (128-char pattern)
• Added edge, revertsOpId, schemaVersion properties

Test Coverage

✅ 31/31 tests passing

• 17 invariant tests (single-fault mutation)
• 8 schema boundary tests
• 6 signature verification tests

Golden fixture methodology with deterministic lineage metadata.

Security

• Removed committed test private key, added to .gitignore
• Keys derived from deterministic non-secret seed for testing
• Keyring-based public key resolution (trust/keyring.json)

Test Plan

• npm test — 31/31 tests pass
• Docker build + test execution
• Schema validation (AJV strict mode)
• Signature verification (Ed25519 + Blake3)
• CI gate integration

Dependencies

This PR is self-contained and has no dependencies. The parent Milestone 3 PR (#4) will be rebased on top of this once merged.

Related

• Extracted from feat: Milestone 3 — Triage, Kernel Validator, and Test Matrix #4 (Milestone 3)
• Part of BEDROCK milestone validation infrastructure

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

Warning

Rate limit exceeded

@flyingrobots has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 15 minutes and 23 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

Walkthrough

This PR introduces a comprehensive Patch Operations validation system featuring JSON schema enforcement, Ed25519 cryptographic signing and verification, invariant validation across operations, test fixtures, and CI/CD integration via GitHub Actions workflow.

Changes

Cohort / File(s)	Summary
Schema & Invariants Documentation docs/canonical/PATCH_OPS_INVARIANTS.md, docs/canonical/PATCH_OPS_SCHEMA.json, schemas/PATCH_OPS_SCHEMA.v1.json	Defines 13 patch operation invariants and comprehensive JSON schema with 567+ lines enforcing strict constraints on operation cardinality, reverse mapping, canonical ordering, dependency handling, approvals, signatures, and metadata.
Validation Core Logic src/validation/validatePatchOps.ts, src/validation/InvariantCode.ts, src/validation/InvariantError.ts	Implements AJV-based schema validation with invariant checking, digest verification, and Ed25519 signature validation. Exports ValidateResult type and validatePatchOpsDocument function. Introduces InvariantCode enum and InvariantError interface for error reporting.
Cryptographic Utilities src/validation/crypto.ts, src/validation/signPatchFixture.ts	Provides blake3 hashing, Ed25519 signature generation/verification, deterministic JSON canonicalization, keyring loading/validation, and test keypair generation. Includes payload assembly for digest computation.
Test Infrastructure & Helpers test/matrix/helpers/*.ts, test/matrix/invariants.test.ts, test/matrix/schema-boundary.test.ts, test/matrix/signature.test.ts	Supplies builder functions (buildTwoOpPatch, buildLinkDependencyOp), fixture loaders, patch cloning/resigning utilities, and 207+ lines of invariant validation tests covering cardinality, reverse mapping, canonical ordering, duplicates, self-loops, and signature verification.
Test Fixtures test/fixtures/valid/minimal-valid.patch.json	Golden fixture with complete patch including operations, rollbacks, approvals, metadata, and Ed25519 signature for baseline validation testing.
Trust & Key Management trust/keyring.json, scripts/setup-test-keys.ts	Keyring JSON store with Ed25519 public keys and setup script for test key generation and keyring initialization.
Build & Verification Scripts scripts/create-fixture.ts, scripts/verify-patch-ops.mjs	Fixture generation script using deterministic signing and batch validation script for JSON patch files with detailed error reporting.
Configuration & CI/CD .github/workflows/patch-ops-gate.yml, eslint.config.js, tsconfig.json, tsconfig.test.json, Dockerfile, .gitignore, package.json	GitHub Actions workflow for patch verification, TypeScript strict configs, ESLint setup with typescript-eslint, Node.js 22 Docker image, npm scripts (lint, build, test, verify:patch-ops), and dependency additions (@noble/ed25519, @noble/hashes, vitest, ajv).
Project Metadata CHANGELOG.md	Version bump to 1.0.0-alpha.2 with entries for Patch Validation Kernel, Ed25519 support, test matrix, machine error codes, CI gate, and schema hardening.

Sequence Diagram(s)

sequenceDiagram
    participant Client as Patch Document
    participant Validator as validatePatchOpsDocument()
    participant AJV as AJV Schema Validator
    participant InvariantChecker as Invariant Checker
    participant Crypto as Crypto Utilities
    participant Keyring as Keyring

    Client->>Validator: validatePatchOpsDocument(doc)
    Validator->>AJV: Validate against PATCH_OPS_SCHEMA.v1.json
    alt Schema Valid
        AJV-->>Validator: ok
        Validator->>InvariantChecker: Run invariant checks
        InvariantChecker->>InvariantChecker: Check cardinality, reverse mapping, ordering, duplicates
        InvariantChecker->>Crypto: canonicalize(payload)
        Crypto-->>InvariantChecker: canonical JSON
        InvariantChecker->>Crypto: prefixedBlake3(canonical)
        Crypto-->>InvariantChecker: payloadDigest
        InvariantChecker->>InvariantChecker: Compare with signature.payloadDigest
        alt Digest Mismatch
            InvariantChecker-->>Validator: INV_011_DIGEST_MISMATCH
        else Digest Match
            InvariantChecker->>Keyring: loadKeyring()
            Keyring-->>InvariantChecker: KeyringEntry map
            InvariantChecker->>Crypto: verifyEd25519DetachedHex(sig, payload, pubKey)
            Crypto-->>InvariantChecker: verification result
            alt Sig Valid
                InvariantChecker-->>Validator: all invariants pass
            else Sig Invalid
                InvariantChecker-->>Validator: INV_012_SIG_FAILED
            end
        end
    else Schema Invalid
        AJV-->>Validator: validation errors
        Validator-->>Client: ValidateResult { ok: false, errors: [...SCHEMA errors] }
    end
    Validator-->>Client: ValidateResult { ok, errors? }

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Rationale: Heterogeneous additions spanning cryptographic logic (Ed25519 detached signatures, blake3 hashing, keyring management), comprehensive schema validation with 13 invariants enforced across multiple files, and dense logic in validatePatchOps.ts (410 lines with caching, payload canonicalization, and invariant aggregation). Requires careful verification of signature verification correctness, invariant logic soundness, schema enforcement rigor, and cryptographic utility reliability. Multiple high-impact files demand separate reasoning pathways.

Poem

🔐 Signatures sealed with Ed25519's might,
Invariants carved in stone, burning bright,
Schemas enforce the ops' sacred dance,
From patch to rollback, locked in a trance—
Validation gates the keeper's advance! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Merge Conflict Detection	⚠️ Warning	❌ Merge conflicts detected (7 files): ⚔️ .gitignore (content) ⚔️ CHANGELOG.md (content) ⚔️ Dockerfile (content) ⚔️ README.md (content) ⚔️ eslint.config.js (content) ⚔️ package-lock.json (content) ⚔️ package.json (content) These conflicts must be resolved before merging into main.	Resolve conflicts locally and push changes to this branch.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title precisely captures the main contribution: a validation kernel combining schema validation, 13 invariants, and cryptographic Ed25519 verification. It's specific, concise, and reflects the core architectural addition.
Description check	✅ Passed	The description is directly related to the changeset, providing comprehensive context: it explains the validation kernel extraction, lists all key components, documents schema hardening, test coverage metrics, security improvements, and dependencies. This level of detail fully justifies the scope of changes.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/validation-kernel

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}