wyrm-mcp 6.18.1 → 7.0.1

package/README.md

@@ -4,10 +4,14 @@
 
 [![npm version](https://img.shields.io/npm/v/wyrm-mcp?color=00B89F&label=npm)](https://www.npmjs.com/package/wyrm-mcp)
 [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-00B89F.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-841%20passing-00B89F)](packages/mcp-server)
+[![Tests](https://img.shields.io/badge/tests-1543%20passing-00B89F)](https://github.com/Ghosts-Protocol-Pvt-Ltd/Wyrm)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![MCP](https://img.shields.io/badge/MCP-compatible-00B89F)](https://modelcontextprotocol.io)
 
+**[wyrm.ghosts.lk](https://wyrm.ghosts.lk)**  ·  **[npm](https://www.npmjs.com/package/wyrm-mcp)**  ·  **[GitHub](https://github.com/Ghosts-Protocol-Pvt-Ltd/Wyrm)**  ·  **[Ghost Protocol](https://ghosts.lk)**  ·  `npm i -g wyrm-mcp`
+
+Local-first persistent memory for AI agents over MCP — by [Ghost Protocol](https://ghosts.lk). Runs fully offline on your machine: no cloud, no account, no LLM required. The managed cloud tier lives at **[wyrm.ghosts.lk](https://wyrm.ghosts.lk)**.
+
 ---
 
 ## What Wyrm actually is
@@ -31,11 +35,27 @@ You don't ask for memory. The AI cites it on its own. Visibly, with sources.
 
 ---
 
+## New in 7.0 — "BROOD": memory for agent FLEETS
+
+> *One agent burns its hand and a hundred siblings never touch the stove.*
+
+The unit of cognition is now the **run** — an orchestrator fanning out structured-output subagents — and 7.0 rebuilds Wyrm around it:
+
+- **The lean frozen surface.** Default ListTools advertises **32 tools** (≈7,993 tokens — chars/4, the F1-census convention — byte-stable across calls) instead of 6.x's 62-tool default / 137 full-load — and **every one of the 137 6.x names stays callable** through a generated alias spine routing to the same handlers. `WYRM_PROFILE=essential` = the core 4 (`session_prime` / `recall` / `capture` / `failure_check`); `WYRM_PROFILE=legacy` (or `full`, now its permanent synonym) re-advertises everything. Discovery is a hard CI gate: BM25 top-3 **100%** on 65 intent queries (threshold 90%).
+- **Run-native attribution.** First-class `runs`/`run_agents` tables; every write attributable to `(agent_id, run_id)` (explicit param > `_meta['wyrm/actor']` > env > clientInfo), bound into the signed Ed25519 audit chain.
+- **Fleet negative learning.** A failure recorded by one subagent **blocks the repeat for every sibling**: run-scoped quarantine with principled promotion, structured `failure_check` verdicts (`{blocked, matches[], recorded_by_agent, run_id, confidence}` — deterministic, no LLM), and **`wyrm-guard`** — a PreToolUse hook bin that enforces it harness-side (block / warn / silent when clean; measured p95 ≤70ms incl. node startup). `wyrm_stats view=failures` prints the ROI number nobody else can: *"N repeats blocked this run."*
+- **The run loop.** `wyrm_run` `action=start|join|status|debrief|end` — debrief fans each agent's learnings through LOCAL-only extraction (Ollama / deterministic fallback, never a cloud LLM) into a run-scoped review queue; `end` promotes/expires quarantined failures and releases the run's claims. Fleet-mode `session_prime {run_id, role}` returns a byte-stable cached brief (≤1,200 tokens) — 12 simultaneous primes share one prompt-cache prefix. **Distribute-once**: an orchestrator that primes one `{run_id, role, for_spawn: true}` per role gets that brief back as clean embeddable markdown (+ `brief_hash` + the `run_briefs` cache key) and embeds it in each same-role agent's spawn-prompt **prefix** — so the cacheable share of the fleet's prime cost becomes never-sent bytes (measured: a 12-agent / 4-role run's prime deliveries drop 12 → 4; bench `S3b` is −38.7% vs the `S3` floor). Agent-side prime stays the byte-identical CAS-row fallback, so a forgetful orchestrator degrades to the unchanged per-agent cost, never below.
+- **A typed machine wire.** The 7 hot-path domains (capture, recall, search, failure, quest, session/prime, review) return schema-validated `structuredContent`; `content[0].text` is *derived* from it (plain ASCII default, `WYRM_FANCY=1` for glyphs); SEP-1303 structured errors fleets self-correct on; 100% of advertised tools annotated; `prime`/`debrief` exposed as MCP protocol-level prompts.
+- **Single-channel wire (opt-in token economy).** `WYRM_CHANNEL` (vendor-neutral, set per MCP-client config) chooses which channel(s) ride the wire. Default **`both`** = today's exact bytes (no change unless you opt in). **`structured`** keeps the full `structuredContent` body byte-identical and collapses `content[0].text` to the template's summary line + a "full body in structuredContent" pointer — **lossless by construction** (the text was always *derived* from the body) and protocol-valid, but requires that your harness forwards `structuredContent` to the model. **`text`** drops `structuredContent` and keeps the full prose (the human-complete derivation) — the lean mode for harnesses that read text only; **note:** a strict MCP client rejects a body-less response for a tool that declares an `outputSchema`, so `text` is for non-strict / text-only consumers. Measured on `bench/token-economy.mjs --channel`: an opted-in working hour drops **~40%** (`structured`) to **~49%** (`text`); recall (82% of that hour) is the lever. `session_rehydrate` is exempt (its briefing markdown *is* the payload).
+- **CLI exile + deletions.** 22 operator/egress tools moved to `wyrm` subcommands — their MCP names return a structured redirect with the exact command (`wyrm_cloud_backup`/`wyrm_sync_export` keep executing through 7.0.x so scheduled backups never silently stop). The legacy `wyrm-http` server is **deleted** (its 6.18 access log measured zero traffic) — `wyrm serve` is the HTTP surface.
+
+**Compatibility:** all 137 names callable; text output reformats (exact-string consumers pin the 6.x line — kept on the `legacy` dist-tag (`wyrm-mcp@6.18.1`): `npm i wyrm-mcp@legacy`); a v6.x database opens with 100% rows (migrations 20–24, all additive + guarded). Per-name dispositions: `specs/wyrm-v7-brood/disposition.md` in the repo.
+
 ## New in 6.0 — "Present"
 
 - **Live statusline** — `wyrm-statusline` binary renders Wyrm's live state into your Claude Code (or Cursor / Windsurf) statusline: `Wyrm · ProjectName · 3 ⟶ · ~12k saved · ⬢ 7`. Auto-spawned daemon, idle-times-out, privacy mode for screen-shares.
 - **✧ Cross-project memory** — `wyrm_constellation` queries FTS5 across every registered Wyrm project at once. *"Have I solved this before in any project?"* Privacy-gated: per-row `cross_project_visibility` defaults to `'within'`.
-- **▰ Tool profiles** — `essential` / `standard` / `full` profiles auto-detected per client. VS Code Copilot / Cursor / Antigravity see a curated 27-tool surface; Claude Code / Codex / unknown clients get all 126. No functionality removed.
+- **▰ Tool profiles** — `essential` / `standard` / `full` profiles. *(7.0: client-name auto-detection removed — `WYRM_PROFILE` is the one lever; `full` = `legacy`.)*
 - **⊡ Cache markers** — `wyrm_context_build` segregates a stable preamble for Anthropic prompt-caching (10× cost cut on cached portions).
 - **↺ `wyrm_migrate_prompt`** — rewrite Wyrm-managed blocks in `.cursor/rules`, `.github/copilot-instructions.md`, `CLAUDE.md` idempotently. Operator content outside the markers is preserved verbatim.
 
@@ -44,7 +64,7 @@ Enable the statusline in Claude Code:
 { "statusLine": { "type": "command", "command": "wyrm-statusline", "padding": 0 } }
 ```
 
-## What's in the box (126 MCP tools)
+## What's in the box (32 advertised tools · 137 names callable)
 
 - **⌇ Memory** — projects, sessions, quests, ground truths, memory artifacts, hybrid FTS5 + vector search
 - **✖ Counter-pattern** — failure check / record / resolve, blocks repeated mistakes at suggestion time

package/dist/attribution.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Wyrm attribution read helpers (v7 F2, T008).
+ *
+ * @copyright 2026 Ghost Protocol (Pvt) Ltd.
+ * @license AGPL-3.0-or-later — dual-licensed; commercial terms: ghosts.lk@proton.me. See LICENSE.
+ *
+ * Migration 20 adds nullable `agent_id`/`run_id` attribution columns to 9
+ * tables. Every row written before v7 — and any v7 row written outside a fleet
+ * run — carries NULL attribution. Article VI: a v6.x DB must open under v7
+ * with 100% of its rows, and that history must stay legibly attributed, so at
+ * every READ SITE that surfaces attribution, NULL reads as actor='legacy'.
+ *
+ * Precedence when rendering "who did this" (the same order is documented in
+ * migration 20 next to the events.agent_id column):
+ *   1. agent_id     — machine identity (v7 fleet writes)
+ *   2. actor        — display identity (the existing 6.x column on
+ *                     events/audit_log; it is EXTENDED, never replaced)
+ *   3. LEGACY_ACTOR — 'legacy' (neither set: a pre-v7 row)
+ *
+ * Wire paths (eventsForPush, ingestRemoteEvent, replication) intentionally do
+ * NOT coalesce: NULL stays NULL in storage and on the wire so replication
+ * round-trips are byte-faithful. 'legacy' is a READ-TIME presentation value
+ * only — it is never written back to the database.
+ */
+/** What NULL attribution reads as at attribution-surfacing read sites. */
+export declare const LEGACY_ACTOR = "legacy";
+/**
+ * Read a display actor from a nullable actor column.
+ * NULL/undefined/blank -> 'legacy'; anything else passes through trimmed.
+ */
+export declare function readActor(actor?: string | null): string;
+/** The attribution fields migration 20 adds (all nullable). */
+export interface AttributedRow {
+    agent_id?: string | null;
+    run_id?: string | null;
+    /** Existing display-identity column on events/audit_log (6.x). */
+    actor?: string | null;
+}
+export interface ResolvedAttribution {
+    /** Display identity, never null: agent_id > actor > 'legacy'. */
+    actor: string;
+    agent_id: string | null;
+    run_id: string | null;
+}
+/**
+ * Resolve the full attribution for one row using the documented precedence.
+ * Use this at any read site that surfaces who/which-run produced a row
+ * (failure_check verdicts, wyrm_stats view=failures, event displays).
+ */
+export declare function resolveAttribution(row: AttributedRow): ResolvedAttribution;
+//# sourceMappingURL=attribution.d.ts.map

package/dist/attribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution.d.ts","sourceRoot":"","sources":["../src/attribution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,0EAA0E;AAC1E,eAAO,MAAM,YAAY,WAAW,CAAC;AAErC;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAGvD;AAED,+DAA+D;AAC/D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,aAAa,GAAG,mBAAmB,CAQ1E"}

package/dist/attribution.js

@@ -0,0 +1,49 @@
+/**
+ * Wyrm attribution read helpers (v7 F2, T008).
+ *
+ * @copyright 2026 Ghost Protocol (Pvt) Ltd.
+ * @license AGPL-3.0-or-later — dual-licensed; commercial terms: ghosts.lk@proton.me. See LICENSE.
+ *
+ * Migration 20 adds nullable `agent_id`/`run_id` attribution columns to 9
+ * tables. Every row written before v7 — and any v7 row written outside a fleet
+ * run — carries NULL attribution. Article VI: a v6.x DB must open under v7
+ * with 100% of its rows, and that history must stay legibly attributed, so at
+ * every READ SITE that surfaces attribution, NULL reads as actor='legacy'.
+ *
+ * Precedence when rendering "who did this" (the same order is documented in
+ * migration 20 next to the events.agent_id column):
+ *   1. agent_id     — machine identity (v7 fleet writes)
+ *   2. actor        — display identity (the existing 6.x column on
+ *                     events/audit_log; it is EXTENDED, never replaced)
+ *   3. LEGACY_ACTOR — 'legacy' (neither set: a pre-v7 row)
+ *
+ * Wire paths (eventsForPush, ingestRemoteEvent, replication) intentionally do
+ * NOT coalesce: NULL stays NULL in storage and on the wire so replication
+ * round-trips are byte-faithful. 'legacy' is a READ-TIME presentation value
+ * only — it is never written back to the database.
+ */
+/** What NULL attribution reads as at attribution-surfacing read sites. */
+export const LEGACY_ACTOR = 'legacy';
+/**
+ * Read a display actor from a nullable actor column.
+ * NULL/undefined/blank -> 'legacy'; anything else passes through trimmed.
+ */
+export function readActor(actor) {
+    const a = typeof actor === 'string' ? actor.trim() : '';
+    return a !== '' ? a : LEGACY_ACTOR;
+}
+/**
+ * Resolve the full attribution for one row using the documented precedence.
+ * Use this at any read site that surfaces who/which-run produced a row
+ * (failure_check verdicts, wyrm_stats view=failures, event displays).
+ */
+export function resolveAttribution(row) {
+    const agentId = row.agent_id ?? null;
+    const runId = row.run_id ?? null;
+    return {
+        actor: agentId ?? readActor(row.actor),
+        agent_id: agentId,
+        run_id: runId,
+    };
+}
+//# sourceMappingURL=attribution.js.map

package/dist/attribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution.js","sourceRoot":"","sources":["../src/attribution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,YAAY,GAAG,QAAQ,CAAC;AAErC;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,KAAqB;IAC7C,MAAM,CAAC,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACxD,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC;AACrC,CAAC;AAiBD;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAkB;IACnD,MAAM,OAAO,GAAG,GAAG,CAAC,QAAQ,IAAI,IAAI,CAAC;IACrC,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,IAAI,IAAI,CAAC;IACjC,OAAO;QACL,KAAK,EAAE,OAAO,IAAI,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC;QACtC,QAAQ,EAAE,OAAO;QACjB,MAAM,EAAE,KAAK;KACd,CAAC;AACJ,CAAC"}

package/dist/audit.d.ts

@@ -1,5 +1,6 @@
 /**
- * Compliance audit trail (Tier 3.9).
+ * Compliance audit trail (Tier 3.9) — per-agent attribution + versioned
+ * Ed25519 signing (v7 F2, T010).
  *
  * Hash-chained event log: each row records sha256(prev_hash || payload ||
  * timestamp). Tampering with any historical entry breaks the chain.
@@ -10,13 +11,59 @@
  * `wyrm_audit_export(range)` produces a tamper-evident JSON bundle that
  * an external auditor can verify offline:
  *   1. Recompute the hash chain from genesis through the range.
- *   2. Verify Ed25519 signatures against the operator's public key.
+ *   2. Verify Ed25519 signatures against the operator's public key(s).
  *   3. Confirm no gaps in IDs.
  *
+ * ## Signed-payload versioning (v7 F2, T010)
+ *
+ * Migration 20's `agent_id`/`run_id` columns are NOT part of the hash-chain
+ * input — the chain rule is byte-identical to 6.x:
+ *
+ *     row_hash = sha256(`${prev_hash}|${event_kind}|${payload_json}|${logged_at}`)
+ *
+ * so a 6.x DB opened under v7 keeps verifying and the v1→v2 transition can
+ * never break the chain (old rows verify as v1, new rows as v2, one chain).
+ * Attribution is instead bound TAMPER-EVIDENTLY into the Ed25519 signature
+ * via a payload-version byte:
+ *
+ *   v1 (legacy 6.x): signed message  = utf8(row_hash)          — no attribution
+ *                    stored signature = bare base64 (unchanged on old rows)
+ *   v2 (v7):         signed message  = 0x02 ‖ utf8(JSON.stringify(
+ *                        { row_hash, agent_id, run_id }))      — attribution bound
+ *                    stored signature = `v2:<key_fp16>:<base64>`
+ *
+ * The leading 0x02 version byte domain-separates the payloads (a v1 message
+ * is 64 ASCII-hex bytes and can never begin with 0x02), and the canonical
+ * JSON body (fixed key order, NULLs preserved) makes the agent_id/run_id
+ * field boundaries unambiguous — no delimiter-shifting forgeries.
+ * `key_fp16` = first 16 hex chars of sha256(SPKI DER of the signing public
+ * key): the "which key" answer, claimed in the row and CONFIRMED whenever
+ * public keys are handed to `verify()`.
+ *
+ * ## The rule for 6.x verifiers (explicit — locked by tests/audit-attribution.test.ts)
+ *
+ * The verify structure 6.x actually shipped (`verify()` / `verifyBundle()`)
+ * checks ONLY the hash chain and never parses the `signature` column.
+ * Therefore:
+ *   (a) a 6.x verifier verifies BOTH v1 and v2 rows exactly as today — the
+ *       chain rule is unchanged, mixed v1/v2 chains pass, and exported
+ *       bundles remain version-1 bundles that 6.x `verifyBundle()` accepts;
+ *   (b) a 6.x auditor's out-of-band Ed25519 step ("signature of the
+ *       row_hash") FAILS CLOSED on a v2 row: the stored `v2:`-prefixed value
+ *       is not the base64 of an Ed25519 signature over the row_hash, so the
+ *       6.x signature check reports INVALID — it can never silently accept a
+ *       v7 signature (and so can never silently accept forged attribution).
+ *       The chain walk itself stays green.
+ *
+ * Signing is OPT-IN (Articles I & VII): no key configured → rows are written
+ * unsigned, byte-identical to 6.x behavior. `WYRM_AUDIT_SIGNING_KEY` holds a
+ * PEM-encoded (pkcs8) Ed25519 private key, or a path to one.
+ *
  * @copyright 2024-2026 Ghost Protocol (Pvt) Ltd.
  * @license AGPL-3.0-or-later — dual-licensed; commercial terms: ghosts.lk@proton.me. See LICENSE.
  */
 import type Database from 'better-sqlite3';
+import { KeyObject } from 'crypto';
 export interface AuditEntry {
     id: number;
     event_kind: string;
@@ -27,13 +74,24 @@ export interface AuditEntry {
     row_hash: string;
     signature: string | null;
     logged_at: string;
+    /** v7 F2 (migration 20): machine attribution columns. NULL on pre-v7 rows
+     * (reads as actor='legacy'). NOT part of the hash chain — the v2 signed
+     * payload (T010) is what binds them tamper-evidently. */
+    agent_id: string | null;
+    run_id: string | null;
 }
 export interface LogInput {
     event_kind: string;
     actor?: string | null;
     project_id?: number | null;
     payload: Record<string, unknown>;
+    /** Explicit caller-supplied signature (stored as-is — the legacy 6.x v1
+     * path). When omitted and a signer is configured, the entry is auto-signed
+     * with a v2 attribution-binding signature. */
     signature?: string | null;
+    /** v7 F2 (T009): omitted → stamped from the ambient actor envelope. */
+    agent_id?: string | null;
+    run_id?: string | null;
 }
 export interface AuditBundle {
     version: 1;
@@ -49,24 +107,135 @@ export interface AuditBundle {
     final_row_hash: string;
     entries: AuditEntry[];
 }
+/** v7 F2 (T010): signature-layer report — present when public keys are
+ * handed to verify()/verifyBundle(). Chain and signature layers are reported
+ * separately so a chain-intact/signature-forged DB is precisely described. */
+export interface AuditSignatureReport {
+    /** Rows carrying any signature (v1 or v2) that were checked. */
+    checked: number;
+    valid: number;
+    invalid: number;
+    first_invalid_id?: number;
+    reason?: string;
+}
 export interface VerificationResult {
     ok: boolean;
     total: number;
     verified: number;
     first_invalid_id?: number;
     reason?: string;
+    /** v7 F2 (T010): rows by signed-payload version (v1 legacy / v2 attribution
+     * / unsigned). Computed whenever the chain verifies. */
+    payload_versions?: {
+        v1: number;
+        v2: number;
+        unsigned: number;
+    };
+    /** v7 F2 (T010): who / which-run / which-key across the verified rows.
+     * `agents` are resolved display identities (NULL attribution reads as
+     * 'legacy' per Article VI); `keys` are signing-key fingerprints seen. */
+    attribution?: {
+        agents: string[];
+        runs: string[];
+        keys: string[];
+    };
+    /** v7 F2 (T010): only present when public keys were provided. */
+    signatures?: AuditSignatureReport;
+}
+/** Stored-signature prefix marking a v2 (attribution-binding) signature. */
+export declare const AUDIT_SIG_V2_PREFIX = "v2:";
+export type AuditPayloadVersion = 1 | 2;
+export interface ParsedAuditSignature {
+    version: AuditPayloadVersion;
+    /** Claimed signing-key fingerprint (v2 only; null when absent/malformed). */
+    key_fp: string | null;
+    sig_b64: string;
 }
+/**
+ * Classify a stored signature string by payload version.
+ * Bare base64 (anything without the `v2:` prefix) = v1 legacy; `v2:<fp>:<b64>`
+ * = v2. Returns null for unsigned (NULL/empty). Never throws.
+ */
+export declare function parseAuditSignature(signature: string | null | undefined): ParsedAuditSignature | null;
+/** Fingerprint of an Ed25519 public key: sha256 over the SPKI DER, first 16 hex. */
+export declare function auditKeyFingerprint(publicKey: string | KeyObject): string;
+/**
+ * Build the exact byte string an audit Ed25519 signature covers.
+ *   v1: utf8(row_hash) — the legacy 6.x payload, no attribution.
+ *   v2: 0x02 version byte ‖ utf8(JSON.stringify({row_hash, agent_id, run_id})).
+ */
+export declare function buildSignedPayload(version: AuditPayloadVersion, fields: {
+    row_hash: string;
+    agent_id?: string | null;
+    run_id?: string | null;
+}): Buffer;
+/** A loaded Ed25519 signing identity (per-agent: each agent process may run
+ * with its own key via WYRM_AUDIT_SIGNING_KEY). */
+export interface AuditSigner {
+    privateKey: KeyObject;
+    publicKeyPem: string;
+    key_fp: string;
+}
+/** Materialize a signer from a PEM (pkcs8) Ed25519 private key; the public
+ * half and fingerprint are derived. Throws on non-Ed25519 keys. */
+export declare function createAuditSigner(privateKeyPem: string): AuditSigner;
+/** Sign the v2 payload for a row. Returns the stored form `v2:<fp>:<base64>`. */
+export declare function signAuditEntry(signer: AuditSigner, fields: {
+    row_hash: string;
+    agent_id?: string | null;
+    run_id?: string | null;
+}): string;
+/**
+ * Opt-in signer bootstrap (Articles I & VII): `WYRM_AUDIT_SIGNING_KEY` is a
+ * PEM string or a path to a PEM file. Absent → null (rows stay unsigned —
+ * exactly the 6.x behavior). Unusable → warn on STDERR (stdout is the MCP
+ * wire) and run unsigned; never throws.
+ */
+export declare function loadAuditSignerFromEnv(env?: NodeJS.ProcessEnv): AuditSigner | null;
+export interface AuditSignatureCheck {
+    ok: boolean;
+    /** null = the row carries no signature (not a failure). */
+    version: AuditPayloadVersion | null;
+    /** v2: the claimed fingerprint; v1-valid: the fingerprint of the key that verified. */
+    key_fp: string | null;
+    reason?: string;
+}
+/**
+ * Verify ONE row's signature against a set of public keys (PEM or KeyObject).
+ * Fail-closed: malformed signatures, unknown fingerprints, undecodable
+ * base64, and crypto-layer rejections all report ok=false. Never throws.
+ */
+export declare function verifyAuditEntrySignature(row: Pick<AuditEntry, 'row_hash' | 'signature' | 'agent_id' | 'run_id'>, publicKeys: Array<string | KeyObject>): AuditSignatureCheck;
 export declare class AuditLog {
     private db;
-    constructor(db: Database.Database);
+    private signer;
+    constructor(db: Database.Database, signer?: AuditSigner | null);
+    /** Swap or clear the signing identity (key rotation, tests). */
+    setSigner(signer: AuditSigner | null): void;
     /** Get the hash of the most recent entry (or 'genesis' if empty). */
     private latestHash;
-    /** Append a hash-chained event. Returns the inserted row. */
+    /** Append a hash-chained event. Returns the inserted row.
+     *
+     * v7 F2 review fix: the head-read + INSERT pair runs in ONE transaction
+     * declared IMMEDIATE, so BEGIN takes the cross-process write lock BEFORE
+     * latestHash() reads the chain head. Two concurrent OS processes appending
+     * (the T010 per-agent-key fleet shape — audit ops are not in
+     * DAEMON_WRITE_OPS, so fleet agents write audit_log directly) could
+     * otherwise both read head H and both insert prev_hash=H, FORKING the
+     * chain — after which verify() reports the compliance log as tampered
+     * forever on legitimate writes. */
     log(input: LogInput): AuditEntry;
     get(id: number): AuditEntry | null;
     /** Verify the entire chain from the first row through the latest.
-     * Useful for periodic self-audits. */
-    verify(): VerificationResult;
+     * Useful for periodic self-audits.
+     *
+     * v7 F2 (T010): pass `publicKeys` (PEM strings) to additionally verify the
+     * Ed25519 signature layer; the report then answers who / which-run /
+     * which-key. Without keys the result is the 6.x chain-only semantics plus
+     * the attribution summary. */
+    verify(opts?: {
+        publicKeys?: string[];
+    }): VerificationResult;
     /** Export a date-ranged tamper-evident bundle. Range is inclusive on
      * both ends. Verification still walks from genesis to ensure no gaps. */
     export(opts: {
@@ -74,8 +243,15 @@ export declare class AuditLog {
         range_end?: string;
     }): AuditBundle;
     /** Statically verify a previously-exported bundle (no DB required).
-     * Useful for the external auditor who only has the JSON file. */
-    static verifyBundle(bundle: AuditBundle): VerificationResult;
+     * Useful for the external auditor who only has the JSON file.
+     *
+     * The chain walk is the unchanged 6.x structure — it never parses
+     * signatures, so mixed v1/v2 bundles verify exactly as they did under 6.x.
+     * v7 F2 (T010): optional `publicKeys` adds the signature-layer check, same
+     * as the instance `verify()`. */
+    static verifyBundle(bundle: AuditBundle, opts?: {
+        publicKeys?: string[];
+    }): VerificationResult;
     /** Slim query for recent entries — UI / dashboards. */
     recent(limit?: number, kind?: string): AuditEntry[];
 }

package/dist/audit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAG3C,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,CAAC,CAAC;IACX,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAID,qBAAa,QAAQ;IACP,OAAO,CAAC,EAAE;gBAAF,EAAE,EAAE,QAAQ,CAAC,QAAQ;IAEzC,qEAAqE;IACrE,OAAO,CAAC,UAAU;IAOlB,6DAA6D;IAC7D,GAAG,CAAC,KAAK,EAAE,QAAQ,GAAG,UAAU;IAwBhC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAMlC;0CACsC;IACtC,MAAM,IAAI,kBAAkB;IA8B5B;6EACyE;IACzE,MAAM,CAAC,IAAI,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,WAAW;IA+BvE;qEACiE;IACjE,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,kBAAkB;IAoC5D,uDAAuD;IACvD,MAAM,CAAC,KAAK,SAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,EAAE;CAUjD"}
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"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"}