Skip to content

feat(spec): korg-ledger@v1 rev 1.1 — canonical flight-recorder contract - #25

Merged
New1Direction merged 1 commit into
mainfrom
feat/flight-recorder-contract-v1.1
Oct 13, 2026
Merged

New1Direction merged 1 commit into
mainfrom
feat/flight-recorder-contract-v1.1

Conversation

@New1Direction

Copy link
Copy Markdown
Owner

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_by only at the top level, but every production writer (LedgerWriter, korg-server, korg-bridge, the Claude Code hook) stores it under metadata.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: true checked by Python only, 1.5 by JS only) are closed.

Added

  • One canonical vector set: the drifted duplicate in crates/korg-registry/tests/conformance/ is removed; every harness reads spec/korg-ledger-v1/. New nested, mixed-shape, malformed-link and redaction vectors, generated and drift-checked in CI by tools/generate_vectors.py, which asserts the frozen v1.0 tips.
  • Redaction at persistence (korg-redact@v1, REDACTION.md): Python and Rust implementations, pinned by shared hand-authored cases and differentially fuzzed against each other. Applied before hashing in LedgerWriter (on by default), POST /api/agent/tool-call and korg-bridge. Also adds korg-verify --require-redacted and the python -m korg_ledger rechain-redacted migration tool.
  • Import envelopes (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-call answers 422 for a triggered_by that is not an existing, strictly-earlier seq_id. It used to persist it.
  • LedgerWriter redacts by default (opt out with redaction=None) and rejects a triggered_by that is not an int.
  • A nested journal with a malformed link that 1.0 verifiers passed now fails.

Verification

  • cargo test --workspace, cargo fmt --check and clippy correctness all pass.
  • pytest: 285 passed across the producer, capture, setup, reader and seal suites.
  • The Python oracle and the JS conformance harness both pass on all 11 vectors.
  • 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

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>
@github-actions

Copy link
Copy Markdown

🛡️ ✅ Certificate verified

Independently verified — zero trust in the tool that produced it.

✅ demo.korgcert.json — korgcert VALID

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.

@New1Direction
New1Direction merged commit 781bc41 into main Oct 13, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants