diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 73a08f2..54eca17 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -12,7 +12,7 @@ The entire Korg backend is implemented in Rust, which provides compile-time guar - **Ownership and Borrowing**: Rust's ownership model ensures that there is always one and only one "owner" of any given piece of memory. Data can be immutably borrowed by multiple parties or mutably borrowed by exactly one party. This statically prevents data races at compile time. In Korg, shared state like the `Blackboard` is wrapped in concurrency primitives like `Arc>`, which enforce these borrowing rules at runtime, ensuring that even in a highly concurrent multi-agent system, there are no data races. - **Absence of Null and Undefined Behavior**: Rust's type system eliminates null pointer dereferences through the `Option` and `Result` enums. This forces developers to handle the absence of a value explicitly, preventing entire classes of bugs and security vulnerabilities common in other systems languages. -- **Fearless Concurrency**: The combination of ownership rules and type-system constraints allows Korg to manage the 4-Persona Swarm with "fearless concurrency." The compiler guarantees that any data shared between threads (i.e., between the Leader orchestrator and its various tasks) is done so safely. +- **Fearless Concurrency**: The combination of ownership rules and type-system constraints allows Korg to manage the 5-Persona Swarm with "fearless concurrency." The compiler guarantees that any data shared between threads (i.e., between the Leader orchestrator and its various tasks) is done so safely. ### 1.2. Isolated Execution via Process Sandboxing @@ -34,9 +34,9 @@ At the heart of Korg's concurrency model is the **Blackboard**, a central, obser - **CRDT-like Merging**: The `perform_semantic_merge` function in `src/leader.rs` exemplifies this principle. It takes the outputs from all competing personas and uses a "Synthesizer" persona (Lucas) to reconcile them into a single, cohesive set of mutations. This is analogous to a CRDT merge function that resolves concurrent updates into a deterministic, final state. - **Observability**: The Blackboard is the "Gravitational Well" around which the swarm orbits. It is the single source of truth for system telemetry. Personas emit `SwarmTelemetryPulse` messages, which the Leader ingests into the Blackboard's `trace_buffer`. The `Evaluator` then reads this buffer to assess the swarm's health, creating a tight, observable feedback loop. The state is exposed via the `/api/state` endpoint for the web cockpit, providing real-time observability to the human operator. -## 3. 4-Persona Adversarial Swarm Topology +## 3. 5-Persona Adversarial Swarm Topology -Korg employs a fixed 4-persona swarm, where each agent has a specialized, adversarial role. This division of labor creates a system of checks and balances that promotes robust, high-quality output. +Korg employs a fixed 5-persona swarm, where each agent has a specialized, adversarial role. This division of labor creates a system of checks and balances that promotes robust, high-quality output. 1. **Orchestrator Captain (The Planner)**: - **Role**: High-level strategist and planner. @@ -44,7 +44,7 @@ Korg employs a fixed 4-persona swarm, where each agent has a specialized, advers 2. **Auditor Harper (The Researcher/Critic)**: - **Role**: Context-gatherer, researcher, and adversarial critic. - - **Function**: During `ContractNegotiation`, Harper (acting as part of the `Evaluator`) critiques the Captain's proposed criteria for ambiguity and relevance, forcing a more robust contract. During execution, Harper is assigned "Research" tasks, gathering information from the codebase or external sources to inform the Builder. Harper's primary function is to prevent the swarm from "hallucinating" or working with incorrect assumptions. + - **Function**: During `ContractNegotiation`, Harper critiques the Captain's proposed criteria for ambiguity and relevance, forcing a more robust contract. During execution, Harper is assigned "Research" tasks, gathering information from the codebase or external sources to inform the Builder. Harper's primary function is to prevent the swarm from "hallucinating" or working with incorrect assumptions. 3. **Builder Benjamin (The Coder)**: - **Role**: Primary code generator and implementer. @@ -54,6 +54,10 @@ Korg employs a fixed 4-persona swarm, where each agent has a specialized, advers - **Role**: Merger and finalizer. - **Function**: After all personas have submitted their work, the `LeaderOrchestrator` invokes Lucas. As shown in `perform_semantic_merge`, Lucas's job is to take the winning proposal from the **Arena** and intelligently merge it with complementary ideas from the other personas. This produces a final, cohesive patch that is more robust than any single persona's output. +5. **Evaluator (The Harsh Adversarial Critic)**: + - **Role**: Independent scoring authority and Generator/Evaluator loop. + - **Function**: Spawned separately by the Leader (`Spawning Evaluator to score persona ...`), the Evaluator receives a generator persona's output and scores it against the negotiated contract rubrics in the **Arena**, following the Anthropic-style Generator/Evaluator loop. It is a distinct persona (`Persona::Evaluator`), not a role played by any of the four workers above, and it is what turns the swarm's output into a measured, adversarially-checked verdict. + This adversarial collaboration ensures that a plan is critiqued before it's executed, code is generated based on a solid plan, and multiple proposed solutions are synthesized into a superior final product. ## 4. State Transition Sequence @@ -143,6 +147,17 @@ Korg maintains a tamper-proof audit trail of every significant action using a cr - Simultaneously, it uses the `state_merkle_root` to find the corresponding state blob and rehydrate the logical `Blackboard`. - This powerful feature allows an operator to rewind the AI's "thought process" and codebase to any valid, signed point in history and "fork" its execution in a new direction, all with cryptographic guarantees of integrity. +### 5.1. Verifiable Flight-Recorder Capabilities + +Beyond the in-process provenance chain above, Korg ships a set of independently-verifiable, "flight-recorder" capabilities that let third parties check an agent's work without trusting Korg itself: + +- **`korg-ledger@v1`**: A frozen, hash-chained, HLC-ordered, tamper-evident event ledger with cross-language conformance (Rust/Python/JS). Each event carries an Ed25519 per-event signature, and the ledger supports git-tip structural anchoring for offline structural verification. +- **Gold Seal (`goldseal@v1`)**: A public, independently-verifiable certificate of agent work, produced by the `korg-seal` CLI (mint/anchor/resolve/verify) and checkable by three conformant verifiers (`korg-verify` in Rust, plus Python and JS) as well as zero-install in-browser verifiers hosted on GitHub Pages. +- **Honest `korg run-once` pipeline**: Runs a real patch through a real `cargo check` and attests a mutation count that *equals* the real `git diff` (file count + changed paths). When it cannot produce a real result, it reports an honest null rather than fabricating one. +- **Provider model**: The default is a hermetic `DeterministicProvider` (fixture-only); `--provider ollama` runs a live local model on arbitrary tasks. + +**Planned (not yet shipped):** live *network* time-witness anchoring (the anchor structure and offline verification are shipped; only the trusted-time witness fetch remains an honest limit), `crates.io`/npm publishing of the CLIs and verifiers, and a `korg fork` / execution-checkpoint-restore CLI (the primitives exist; the shipped reversibility today is `korg rewind`). + ## 6. OCR Pixel Redaction & Visual Firewall (`src/vision_policy.rs`) Since Korg personas can interact with GUIs and web browsers, a critical security vector is the accidental exposure of sensitive data in screenshots. The Visual Policy Engine in `src/vision_policy.rs` acts as a fail-secure firewall for all visual data. diff --git a/README.md b/README.md index c0c9244..12568cb 100644 --- a/README.md +++ b/README.md @@ -178,6 +178,12 @@ korg campaign --web --prompt "Optimize the database connection pool" # Pure autonomous goal mode (--goal is a top-level flag) korg --goal "Write and validate a full test suite for src/parser.rs" +# Run the full multi-persona swarm on a REAL local model — every persona +# (Captain, Harper, Benjamin, Lucas, Evaluator) runs as a real worker +# subprocess doing real, measured, attested work. Defaults to a hermetic +# deterministic provider; `--provider ollama` makes it live. +korg --goal "Fix the failing test in src/lib.rs" --provider ollama --model qwen2.5:7b + # Preview without committing (dry-run; --preview is a top-level flag) korg --preview "Refactor the main event loop" ``` @@ -216,6 +222,14 @@ korg-verify > pipeline cannot attest a number the worktree does not actually show — that is > the guarantee, independent of model quality. +> **Verify it in your browser — sends nothing.** Zero-install, client-side +> verifiers (Web Crypto) for any `korg-ledger@v1` journal or Gold Seal: +> [verify a session](https://new1direction.github.io/korg/web/index.html) · +> [verify a Gold Seal](https://new1direction.github.io/korg/web/seal.html) · +> [time-travel explorer](https://new1direction.github.io/korg/web/explore.html). +> They hash-chain, check the causal DAG, validate Ed25519 signatures, and +> re-derive the human summary from the events — all locally. + > Speculative branch/fork and named checkpoints (`korg fork`, `korg checkpoints > list|restore`) are planned, not yet shipped. The reversibility surface today is > `korg rewind`. @@ -267,6 +281,8 @@ Korg treats AI cognition the same way a hypervisor treats compute and Git treats | Speculative branches | 🚧 planned | ❌ | ❌ | ❌ | | Execution checkpoints | 🚧 planned | ❌ | ❌ | ❌ | | Cryptographic audit trail | ✅ | ❌ | ❌ | ❌ | +| Independently-verifiable Gold Seal | ✅ | ❌ | ❌ | ❌ | +| Honest attestation (real diff, never fabricated) | ✅ | ❌ | ❌ | ❌ | | Micro-healing | ✅ | ❌ | ❌ | ❌ | | Model-agnostic | ✅ | ✅ | ✅ | ✅ | @@ -282,7 +298,7 @@ Korg treats AI cognition the same way a hypervisor treats compute and Git treats | Ledger ordering | Hybrid Logical Clocks (HLC) | | Workspace snapshots | Git Merkle tree (O(1) restore via `write-tree` / `read-tree`) | | Cryptographic attestation | Ed25519 (ed25519-dalek) | -| Semantic governance | BERT cosine similarity (Candle / Hugging Face) | +| Semantic governance | BERT cosine similarity via the optional `candle` feature (Hugging Face); a deterministic embedding fallback runs when `candle` is not built | | TUI dashboard | Ratatui + Crossterm | | Web cockpit | Axum + SSE | | Syntax highlighting | Syntect + tree-sitter | @@ -291,7 +307,7 @@ Korg treats AI cognition the same way a hypervisor treats compute and Git treats ## Architecture Deep Dive -→ **[Read the full technical write-up](https://github.com/New1Direction/korg/blob/main/ARCHITECTURE.md)** *(coming soon)* +→ **[Read the full technical write-up](https://github.com/New1Direction/korg/blob/main/ARCHITECTURE.md)** ### Real-World Audit Ledger Example You can inspect a real-world cognitive audit ledger produced by Korg. This NDJSON file records a live session where Claude Code was prompted to call Korg's MCP tools to refactor a function and rename all call sites, capturing the full HLC causal graph and `actor_id` recorder metadata: @@ -309,23 +325,28 @@ The short version: ## Status -Korg is in active development. Current test coverage: **175 tests, 0 failures** (162 cargo across 8 crates + 13 pytest for the PyO3 bridge). +Korg is in active development, built on a **frozen `korg-ledger@v1` spec with cross-language conformance** (Rust + Python + JS). Test footprint: **300+ Rust tests across the workspace plus Python/JS conformance suites**, CI-gated (build · tests · cross-language oracle · differential fuzz) and green on `main`. -- [x] Append-only cognitive ledger with HLC ordering +**Shipped:** +- [x] Append-only, hash-chained cognitive ledger with HLC ordering - [x] Deterministic replay and projection rebuilds +- [x] Reversible execution — rewind the ledger to any prior sequence point (tamper-evident `LedgerRewind`) +- [x] Per-event Ed25519 signatures + structural anchoring (`korg-ledger@v1` §8) +- [x] **Gold Seal (`goldseal@v1`)** — a public, independently-verifiable certificate of agent work, with zero-install in-browser verifiers +- [x] **Honest pipeline** (`korg run-once`) — real patch → real `cargo check` → an attested mutation count that equals the real `git diff`; never fabricates (reports an honest null instead) +- [x] **Live local model** (`--provider ollama`) — real per-persona work on arbitrary tasks +- [x] **Multi-agent swarm** (Captain, Harper, Benjamin, Lucas, Evaluator) — genuine worker subprocesses doing real, measured, attested work with DAG data-flow between personas +- [x] Zero-config Claude Code capture (PostToolUse/Stop hooks → verifiable per-session ledgers) +- [x] Micro-healing effect layer · TUI dashboard + Web cockpit +- [x] Cryptographic provenance attestation · single-authority CognitionMode governance - [x] Preview / dry-run mode (`--preview`) -- [ ] Speculative warm-boot execution (in progress) -- [ ] Execution checkpoints / restore CLI (primitive exists; CLI planned) -- [x] Micro-healing effect layer -- [x] Multi-agent swarm orchestration (Captain, Harper, Benjamin, Lucas) -- [x] TUI dashboard + Web cockpit -- [x] Cryptographic provenance attestation -- [x] Single-authority CognitionMode governance -- [ ] `cargo install korg` on crates.io -- [ ] Remote swarm workers -- [ ] WASM backends -- [ ] IDE language server integration -- [ ] Distributed checkpoint synchronization + +**Planned / not yet shipped:** +- [ ] Speculative branches / fork + execution-checkpoint restore CLI (primitives exist; CLI planned) +- [ ] `cargo install korg` on crates.io · npm-published verifier +- [ ] Live network anchoring resolver (trusted-time witness — the remaining honest limit) +- [ ] Remote swarm workers · WASM backends · IDE language-server integration · distributed checkpoint sync +- [ ] Fully passive capture without agent cooperation --- diff --git a/ROADMAP.md b/ROADMAP.md index 5dee563..534ee9a 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -15,7 +15,6 @@ without human intervention. | Feature | Description | |---|---| | `korg autoheal` | Autonomous recovery loop: detect failure → identify root cause → rewind to last clean checkpoint → retry with corrected strategy | -| Micro-healing at the effect layer | Per-tool failure recovery without full session rewind | | Incremental checkpoints | Background checkpoint compression — only delta since last checkpoint is stored | | Recovery confidence scoring | Each autoheal attempt is scored; low-confidence recoveries escalate to human approval | | Doom-loop circuit breaker | Hard limit on recursive recovery attempts with structured escalation | diff --git a/adapters/claude-code/README.md b/adapters/claude-code/README.md index 5b7b811..28a4e4e 100644 --- a/adapters/claude-code/README.md +++ b/adapters/claude-code/README.md @@ -55,17 +55,24 @@ graph identical in shape to what korgex's own agent loop produces. ## Two ways to use it -### 1. Live tail mode (recommended) +> **Recommended live path: `korg-setup` + `korg-hook`.** The verifiable, +> zero-config capture model (PostToolUse/Stop hook → per-session verifiable +> ledger at `~/.korg/sessions/.jsonl`) is described in +> [What it produces](#what-it-produces). The `korg-ingest-claude --tail/--once` +> CLI below still works, but it emits the **legacy un-chained flat ledger**; +> run `korg-backfill --migrate-flat ` to upgrade an existing flat ledger +> to the per-session format. -`korg follows you in real time` — the adapter watches -`~/.claude/projects/**/*.jsonl` and streams new events into a korg -ledger as Claude Code writes them. Install, run once, get a continuously- -growing ledger forever: +### Legacy flat-file tail (`korg-ingest-claude`) + +The adapter watches `~/.claude/projects/**/*.jsonl` and streams new events into +a **legacy flat (un-chained)** korg ledger as Claude Code writes them. Install, +run once, get a continuously-growing flat ledger: ```bash pip install -e ./adapters/claude-code -# Watch ~/.claude/projects, append events to ~/.korg/claude-events.jsonl +# Watch ~/.claude/projects, append events to ~/.korg/claude-events.jsonl (legacy flat ledger) korg-ingest-claude --tail # Just print events to stdout (no file write): @@ -83,18 +90,23 @@ The byte-offset state is persistent — kill the process and restart any time; it picks up exactly where it left off. The state file at `~/.korg/claude-tail-state.json` survives reboots. -### 2. One-shot backfill +### One-shot backfill of history + +For the existing pile of session files on your disk right now, use +`korg-backfill` — it re-derives the **verifiable per-session ledgers** under +`~/.korg/sessions/` for every historical session. -For the existing pile of session files on your disk right now: +The legacy `korg-ingest-claude --once` still exists, but it writes the **legacy +un-chained flat ledger** instead: ```bash -korg-ingest-claude --once --out ~/.korg/claude-events.jsonl -# [korg-ingest-claude] one-shot pass complete · files_active=42 events=128304 ... +korg-ingest-claude --once --out ~/.korg/claude-events.jsonl # legacy flat ledger +# [korg-ingest-claude] one-shot pass complete · files_active=N events=M ... ``` Runs once, ingests everything you haven't ingested yet, exits. -### 3. Library usage +### Library usage For embedding into your own ledger plumbing: @@ -109,7 +121,7 @@ def emit(body: dict) -> int | None: # Single-session replay: -adapter = ClaudeCodeAdapter(emit, source_agent="agent:claude-code@2.1.150") +adapter = ClaudeCodeAdapter(emit, source_agent="agent:claude-code@2.1.0") with Path("~/.claude/projects/-Users-you-Documents-foo/abc.jsonl").expanduser().open() as f: stats = adapter.ingest(f) diff --git a/adapters/korg-setup/README.md b/adapters/korg-setup/README.md index 06c3698..b0cd893 100644 --- a/adapters/korg-setup/README.md +++ b/adapters/korg-setup/README.md @@ -109,16 +109,9 @@ you can preview every action before committing. ## Tests -45 tests cover: - -- 14 for the `~/.claude.json` editor (idempotent register/remove, - atomic backups, preservation of unrelated keys, env vars). -- 13 for the launchd integration (plist shape, write idempotency, - install/uninstall, platform gating, `is_loaded` parser). -- 11 for the setup orchestrator (binary detection, dry-run, idempotency, - ledger-dir creation, launchctl-failure reporting, no-daemon path). -- 7 for the status reporter (empty install, partial install, loaded - launchd detection, format rendering). +A test suite covers the `~/.claude.json` editor, launchd integration, +setup orchestrator, status reporter, discovery, bridge registration, and +Claude settings. Run them with the Korg workspace venv: diff --git a/adapters/recall-mcp/README.md b/adapters/recall-mcp/README.md index ae4973b..e516bd2 100644 --- a/adapters/recall-mcp/README.md +++ b/adapters/recall-mcp/README.md @@ -181,17 +181,19 @@ Result text format (one line per match, designed for direct LLM consumption): ## Tests -49 cover everything end-to-end: +Tests cover everything end-to-end: - 9 tests for the text flattener (per-event-type extraction, trimming, fallbacks). -- 9 tests for the index (incremental load, malformed-line tolerance, +- 11 tests for the index (incremental load, malformed-line tolerance, partial-line hold-back, multi-file, new-file pickup, triggered_by preservation). -- 17 tests for the recall engine (substring + semantic, top_n, min_score, +- 16 tests for the recall engine (substring + semantic, top_n, min_score, tool_filter, automatic refresh, auto-mode fallback, explicit-semantic raising without fastembed). -- 14 tests for the MCP server (full initialize/list/call roundtrip, +- 16 tests for the MCP server (full initialize/list/call roundtrip, unknown-method errors, notification handling, ping, tool_filter through the JSON-RPC surface, malformed-line tolerance, serve_stdio loop). +- 17 tests for the introspect document (korg:introspect@v1 schema, + callables, exit_codes, command_id stability). Run them with the Korg workspace venv (which has fastembed): diff --git a/crates/korg-core/README.md b/crates/korg-core/README.md index fdd2eb6..c6a0ac6 100644 --- a/crates/korg-core/README.md +++ b/crates/korg-core/README.md @@ -140,7 +140,7 @@ korg-core ← types, traits, paths, metrics, telemetry (this crate; no interna route. The field names on `NormalizedEvent` intentionally mirror the server's `AgentToolCallRequest` so adopting it later is a rename-and-move, not a redesign. -7 unit tests cover `paths`, `metrics`, and `telemetry`; `event`, `adapter`, and +Unit tests cover `paths`, `metrics`, and `telemetry`; `event`, `adapter`, and `subscription` are plain type definitions and are exercised by their consumers. ## License diff --git a/crates/korg-llm/README.md b/crates/korg-llm/README.md index 3386552..b9e6fc7 100644 --- a/crates/korg-llm/README.md +++ b/crates/korg-llm/README.md @@ -26,8 +26,10 @@ format: `FunctionCall`, `ToolDefinition` (JSON-schema parameters), and `MultiModalContent::Image`. - `LlmRequest` — messages plus generation params (`temperature`, `max_tokens`, - `top_p`, penalties, `stop_sequences`, `tools`, `multimodal`) and optional - provenance metadata (`tx_id`, `session_id`, `policy_hash`). + `top_p`, penalties, `stop_sequences`, `tools`, `multimodal`, `response_format`) + and optional provenance metadata (`tx_id`, `session_id`, `policy_hash`). + `response_format = Some("json_object")` asks OpenAI-compatible providers for + strict JSON; other providers ignore it. - `LlmResponse` / `LlmDelta` (streaming chunk), `TokenUsage`, `FinishReason`, and the `LlmError` enum (`Http`, `Timeout`, `RateLimit`, `Auth`, `Parser`, `Network`, `CircuitBreakerOpen`, `Unknown`). @@ -59,6 +61,11 @@ pub trait LlmProvider: Send + Sync + 'static { - **`MockProvider`** — offline provider for tests; queue canned `Result` values via `set_response`, or stream deltas via `set_stream_deltas`. Falls back to echoing the last user message. +- **`DeterministicProvider`** — hermetic, fixture-only offline provider + (`src/deterministic.rs`). Produces reproducible, role-shaped artifacts for a + known fixture task and an honest null (empty mutations, low confidence) for + anything else — it never fabricates. Selected via `default_llm = "deterministic"` + and used by the honest `korg run-once` pipeline. ### Resilience decorators @@ -90,8 +97,8 @@ pub trait LlmProvider: Send + Sync + 'static { structs (`VisionPolicyConfig`, `PathsPolicyConfig`, `NetworkPolicyConfig`, `TokensPolicyConfig`). The `Toml*` structs are the deserialization mirror. - **`build_provider(&KorgConfig)`** — builds the default provider (selected by - `default_llm`: `openai` / `anthropic` / `grok` / `ollama` / `rotator`, else - `mock`), already wrapped in `ResilientLlmProvider`. + `default_llm`: `openai` / `anthropic` / `grok` / `ollama` / `rotator` / + `deterministic`, else `mock`), already wrapped in `ResilientLlmProvider`. - **`build_provider_for_persona(&KorgConfig, name)`** — applies a `[personas.]` override (provider/model/temperature) for the Leader, Workers (`captain`/`harper`/`benjamin`/`lucas`), and `evaluator`; returns the @@ -154,6 +161,7 @@ let req = LlmRequest { top_p: None, presence_penalty: None, frequency_penalty: None, + response_format: None, }; let resp = provider.complete(req).await?; diff --git a/crates/korg-server/README.md b/crates/korg-server/README.md index 3017250..dbe28ff 100644 --- a/crates/korg-server/README.md +++ b/crates/korg-server/README.md @@ -129,8 +129,8 @@ korg_server::run_web_with_campaign( `/api/diff`, blob, and override endpoints) to anything on the network. There is no auth on the dashboard/telemetry/control routes — only the Anthropic proxy enforces `AuthenticatedUser`. - **WASM frontend handlers are empty stubs.** `wasm_js_handler` / `wasm_bytes_handler` return - zero-length bodies. The module doc comment still describes a "glassmorphism SPA," but in the - current code every page route serves the same static `LANDING_HTML`. + zero-length bodies. There is no bundled SPA/WASM frontend; every page route serves the same + static `LANDING_HTML`. - **Vision redaction.** Before broadcasting, `Ktrans` updates carrying `vision_attachments` marked `REDACTED`/`BLOCKED` have their image bytes swapped for a blackout PNG, unless `KorgConfig.security_vision.allow_raw_screenshots` is set. diff --git a/crates/korg-tui/README.md b/crates/korg-tui/README.md index fbfadc1..669b159 100644 --- a/crates/korg-tui/README.md +++ b/crates/korg-tui/README.md @@ -111,17 +111,17 @@ partial — read these honestly before relying on a panel: - **All `TuiUpdate` variants are wired** to `KorgTui` state, so any panel the orchestrator actually emits for will update live. -- **`update_from_leader` is a stub** — it takes a `&LeaderOrchestrator` and - does nothing; the comment says "Real integration would pull live data here." - **The campaign spawn is acknowledged as a workaround.** `run_tui_with_campaign` notes in-code that proper event hooks on `LeaderOrchestrator` don't exist yet, so it "runs the campaign and periodically sends updates." -- **Several fields are seeded with placeholder data** in `KorgTui::default()` - (persona scores, lock states, the per-persona sparkline histories) and a - "demo heartbeat" nudges `h_sem` while `current_verdict` still says - "Waiting…". Telemetry shown before the first real `TuiUpdate` is cosmetic. -- **The git timeline falls back to hardcoded sample commits** if `git log` - returns nothing. +- **Telemetry, persona scores, lock states, and sparkline histories default to + empty/zero** in `KorgTui::default()` and are populated only from real + `TuiUpdate` signals — never seeded or fabricated. Before the first update, + panels read as empty rather than showing demo data (`current_verdict` + honestly defaults to "Waiting for first evaluation..."). +- **The git timeline reads real `git log` metadata;** on any failure (no git, + non-zero exit, or empty output) it leaves the timeline empty rather than + fabricating commits. - `fuzzy_match` exists both as a `KorgTui` method (used by the palette) and as a duplicate free function at the bottom of the file. diff --git a/crates/korg-verify/README.md b/crates/korg-verify/README.md index 3fff4ba..6acb10a 100644 --- a/crates/korg-verify/README.md +++ b/crates/korg-verify/README.md @@ -3,7 +3,7 @@ A standalone, dependency-light **verifier** for korg receipts and journals — no network, no Python. ``` -korg-verify [--key ] [--pubkey ] [--json] +korg-verify [--key ] [--pubkey ] [--pin-event-pubkey ] [--anchors ] [--json] ``` Exit code: `0` valid · `1` invalid/tampered · `2` usage/parse error. @@ -14,11 +14,15 @@ Exit code: `0` valid · `1` invalid/tampered · `2` usage/parse error. - **Causal DAG** — `triggered_by` links are well-formed (`verify_dag`). - **Tip** — a receipt's recorded `tip` matches the chain head. - **Signature** — if the receipt is signed, the Ed25519 signature over the tip is valid. `--pubkey ` *pins* the expected signer and rejects any other key (so a green check proves authorship against a key you trust, not merely against the one the receipt carries). +- **Per-event signatures** — with `--pin-event-pubkey `, every event's own Ed25519 `event_sig` must verify under the pinned key (a missing or invalid one fails). +- **Anchors (structural)** — with `--anchors `, an `anchors.jsonl` sidecar is checked to bind each anchor's `entry_hash` to the chain (structural / git-tip kind; this is an offline structural check, not a trusted-time witness fetch). ## Why it exists It is the third independent implementation of **korg-ledger@v1** — Python (`korgex receipt verify`), JavaScript (the self-verifying HTML report), and now Rust — all checked against the same frozen conformance vectors. That makes "verify a sealed deliverable without trusting the tool that produced it" provable rather than asserted: a single small binary anyone can run, in CI or by hand. +It also verifies a **goldseal@v1** certificate — a public, independently-verifiable Gold Seal of agent work — auto-detecting receipts, journals, and seals from the same binary; korg-verify is one of three conformant Gold Seal verifiers (Rust/Python/JS). + ## Examples ```sh diff --git a/docs/GIT_ISOLATION.md b/docs/GIT_ISOLATION.md index 22612ba..7c3760d 100644 --- a/docs/GIT_ISOLATION.md +++ b/docs/GIT_ISOLATION.md @@ -111,7 +111,7 @@ During timeline time-travel replay or manual operator branching, Korg reconstruc git read-tree --reset -u ``` -This bypasses traditional file-by-file patching, using Git's low-level tree matching algorithm to reset the directory layout to the exact millisecond-level state of the historical transaction in less than 50ms, while preserving the logical CRDT Blackboard state by importing the matching state-blob. +This bypasses traditional file-by-file patching, using Git's low-level tree matching algorithm to reset the directory layout to the exact state of the historical transaction in a single low-level tree operation, while preserving the logical CRDT Blackboard state by importing the matching state-blob. --- diff --git a/docs/goldseal/POSITIONING.md b/docs/goldseal/POSITIONING.md index c348114..35c37f3 100644 --- a/docs/goldseal/POSITIONING.md +++ b/docs/goldseal/POSITIONING.md @@ -47,7 +47,7 @@ We do not start by selling a platform. We start by giving away a primitive that issuer signature, and a human-legible summary that is **re-derived from the events** — so the "files touched / tools used / steps" a person reads literally cannot lie. (Shipped: `goldseal@v1`, this work.) -- **Re-verification needs nothing of ours.** A 200-line dependency-light Rust binary, +- **Re-verification needs nothing of ours.** A small dependency-light Rust binary, a stdlib Python module, or a single browser tab (Web Crypto) all check a seal byte-identically. **Zero trust in the tool that produced it.** That is the whole product.