Repository navigation
feat(spec): korg-ledger@v1 rev 1.1 — canonical flight-recorder contract - #25
Merged
Merged
Conversation
Make spec/korg-ledger-v1/ the authoritative contract and close the gaps between it and what producers actually write. - Causal parent (SPEC §9): Rust, Python and JS verify_dag now read triggered_by from flat records AND nested JournalEvents (metadata.triggered_by). Before, every production journal skipped the link check, so forward/dangling links verified VALID. Non-integer and conflicting links are errors; DAG error strings are byte-identical across implementations (Rust's `seq Some(3)` is gone). - One vector set: the drifted copy in crates/korg-registry/tests/ conformance is removed; all harnesses read spec/korg-ledger-v1. New nested / mixed / malformed-link / redaction vectors, generated and drift-checked by tools/generate_vectors.py (asserts frozen v1.0 tips). - Redaction at persistence (korg-redact@v1, REDACTION.md): Python and Rust implementations pinned by shared hand-authored cases; applied before hashing in LedgerWriter (default), POST /api/agent/tool-call and korg-bridge; `korg-verify --require-redacted` lint; rechain-redacted migration tool. - Import envelopes (korg-import@v1, IMPORT.md): allowlisted, atomic imports for sanitized Okto diagnostics and ningen-shikkaku lifecycle metadata, with projection-only exporters and a CLI. - korg-server answers 422 for an invalid triggered_by instead of persisting it. Migration notes in spec/korg-ledger-v1/MIGRATION.md. Amp-Thread-ID: https://ampcode.com/threads/T-01a135b8-72ec-7590-9a2b-f6d4c07220fb Co-authored-by: aisle9angel@gmail.com <aisle9angel@gmail.com>
🛡️ ✅ Certificate verifiedIndependently verified — zero trust in the tool that produced it. ✅
|
| claim | CI demo: agent added a /healthz endpoint with a passing test |
| who (issuer) | dccab2524edb9397… |
| what | 5 events · Bash×1 Edit×1 Read×1 Write×1 user_prompt×1 |
| files | src/app.py, tests/test_health.py |
| integrity | chain ✓ · summary re-derived ✓ · seal ✓ |
Verified by the independent korg verifier. Re-check in a browser: seal.html.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Makes
spec/korg-ledger-v1/the authoritative contract for korg as an agent flight recorder and closes the gaps between it and what producers actually write. No hash rule changed — every v1.0 vector reproduces its frozen tip.Fixed: causal links in real journals were never checked
All three verifiers read
triggered_byonly at the top level, but every production writer (LedgerWriter, korg-server, korg-bridge, the Claude Code hook) stores it undermetadata.triggered_by. A nested journal with a forward or dangling link verified VALID in Rust, Python and JS. Now (SPEC §9) all three resolve the parent from either shape, reject non-integer / conflicting links, and emit byte-identical DAG errors. The old verdict splits (triggered_by: truechecked by Python only,1.5by JS only) are closed.Added
crates/korg-registry/tests/conformance/is removed; every harness readsspec/korg-ledger-v1/. New nested, mixed-shape, malformed-link and redaction vectors, generated and drift-checked in CI bytools/generate_vectors.py, which asserts the frozen v1.0 tips.korg-redact@v1, REDACTION.md): Python and Rust implementations, pinned by shared hand-authored cases and differentially fuzzed against each other. Applied before hashing inLedgerWriter(on by default),POST /api/agent/tool-calland korg-bridge. Also addskorg-verify --require-redactedand thepython -m korg_ledger rechain-redactedmigration tool.korg-import@v1, IMPORT.md): allowlisted, atomic imports for sanitized Okto diagnostics and ningen-shikkaku lifecycle metadata (never secret values), plus projection-only exporters and a CLI.Behaviour changes (see
spec/korg-ledger-v1/MIGRATION.md)POST /api/agent/tool-callanswers 422 for atriggered_bythat is not an existing, strictly-earlierseq_id. It used to persist it.LedgerWriterredacts by default (opt out withredaction=None) and rejects atriggered_bythat is not anint.Verification
cargo test --workspace,cargo fmt --checkand clippy correctness all pass.diff_fuzz.py: 65 candidates, 0 divergences. That includes 36 DAG cases (flat/nested, integer domain, conflicts) and a Python-vs-Rust redaction lint over 400 random events with 537 findings.https://ampcode.com/threads/T-01a135b8-72ec-7590-9a2b-f6d4c07220fb