@kernel.chat/kbot-finance 0.2.0

package/dist/demo.js

@@ -0,0 +1,133 @@
+/**
+ * End-to-end demo of the kbot-finance architecture.
+ *
+ * Run with: npm run demo
+ *
+ * Hits the live Polymarket Gamma API. No keys required. The Replit
+ * entrypoint runs this on first launch so visitors see the full
+ * envelope + verifier + audit-log flow light up.
+ */
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AppendOnlyAuditLog, makePositionLimitRule, makeKellyCapRule, polymarketQuery, runVerifier, } from "./index.js";
+const SESSION_ID = `demo-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+async function main() {
+    const banner = (s) => {
+        process.stdout.write(`\n${"=".repeat(72)}\n${s}\n${"=".repeat(72)}\n`);
+    };
+    banner("kbot-finance v0.1 — audit-grade AI infrastructure for capital markets");
+    process.stdout.write(`session_id: ${SESSION_ID}\n` +
+        `architecture: deterministic engine + AI intelligence + human governance\n` +
+        `engine for this demo: Polymarket Gamma (https://gamma-api.polymarket.com)\n`);
+    const dir = await mkdtemp(join(tmpdir(), "kbot-finance-demo-"));
+    const audit_path = join(dir, "audit.jsonl");
+    const auditLog = await AppendOnlyAuditLog.open(audit_path);
+    process.stdout.write(`audit log: ${audit_path}\n`);
+    // Compose a minimal global ruleset. v0.1 ships two rules; later jurisdictions
+    // layer more rules on top.
+    const rules = [
+        makePositionLimitRule({ default_max_size: 10_000, default_max_notional: 50_000 }),
+        makeKellyCapRule({ kelly_fraction: 0.5, bankroll: 100_000 }),
+    ];
+    banner("Step 1 — query Polymarket: top 3 active markets by 24h volume");
+    const result = await polymarketQuery({
+        mode: "list_active",
+        limit: 3,
+        data_as_of: new Date().toISOString(),
+    }, {
+        auditLog,
+        rules,
+        verifierContext: {
+            session_id: SESSION_ID,
+            state: {},
+            jurisdiction: "US",
+        },
+    });
+    if (!result.ok) {
+        process.stdout.write(`FAIL at ${result.stage}: ${JSON.stringify(result.detail)}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    process.stdout.write(`request_hash: ${result.response.request_hash}\n`);
+    process.stdout.write(`engine_version: ${result.response.engine_version}\n`);
+    process.stdout.write(`produced_at: ${result.response.produced_at}\n`);
+    process.stdout.write(`byte_identical_replayable: ${result.response.byte_identical_replayable} ` +
+        `(false because Gamma is live HTTPS; replay needs an indexer pinned to block)\n`);
+    for (const m of result.response.value.markets) {
+        process.stdout.write(`\n  ${m.question ?? "(no question)"}\n`);
+        if (m.outcomes && m.outcome_prices) {
+            for (let i = 0; i < m.outcomes.length; i++) {
+                const price = m.outcome_prices[i];
+                process.stdout.write(`    ${m.outcomes[i]}: ${price !== undefined ? (price * 100).toFixed(1) + "%" : "—"}\n`);
+            }
+        }
+        process.stdout.write(`    24h volume: $${(m.volume_24h ?? 0).toFixed(0)}\n`);
+    }
+    banner("Step 2 — verifier rejects an oversized trade proposal");
+    // The AI proposes a hypothetical trade; the verifier checks it against every
+    // applicable rule BEFORE any engine call. Half-Kelly + position limits both fire.
+    const proposed_trade = {
+        instrument_id: result.response.value.markets[0]?.id ?? "demo-market",
+        size: 50_000, // exceeds default_max_size (10_000)
+        notional: 75_000, // exceeds default_max_notional (50_000)
+        edge_probability: 0.55, // p=0.55, b=1 → Kelly = 0.1 → half-Kelly cap = 5,000
+        payoff_b: 1.0,
+    };
+    const verdict = runVerifier(rules, {
+        operation: "polymarket.trade",
+        inputs: proposed_trade,
+        materiality: "material",
+    }, { session_id: SESSION_ID, state: {}, jurisdiction: "US" });
+    await auditLog.append({
+        action: "verifier_check",
+        subject: "polymarket.trade",
+        session_id: SESSION_ID,
+        payload: verdict,
+    });
+    process.stdout.write(`verifier ok: ${verdict.ok}\n`);
+    for (const check of verdict.checks) {
+        if (check.result.pass) {
+            process.stdout.write(`  ✓ ${check.rule_id}: pass\n`);
+        }
+        else {
+            process.stdout.write(`  ✗ ${check.rule_id}: ${check.result.reason.code} — ${check.result.reason.summary}\n`);
+        }
+    }
+    banner("Step 3 — audit log integrity check");
+    const integrity = await AppendOnlyAuditLog.verify(audit_path);
+    if (integrity.ok) {
+        process.stdout.write("audit log: HASH CHAIN INTACT — every entry verified\n");
+    }
+    else {
+        process.stdout.write(`audit log: BROKEN at seq=${integrity.broken_at_seq}\n`);
+        process.exitCode = 1;
+    }
+    banner("Audit log contents");
+    const log_content = await readFile(audit_path, "utf8");
+    const lines = log_content.split("\n").filter((l) => l.length > 0);
+    process.stdout.write(`entries written: ${lines.length}\n\n`);
+    for (const line of lines) {
+        const entry = JSON.parse(line);
+        process.stdout.write(`  [${entry.seq}] ${entry.action.padEnd(16)} ${entry.subject.padEnd(30)} hash=${entry.self_hash.slice(0, 12)}…\n`);
+    }
+    banner("Demo complete");
+    process.stdout.write(`\nWhat just happened:\n` +
+        `  1. AI agent requested a Polymarket query inside a content-addressed envelope.\n` +
+        `  2. Regulatory verifier ran every active rule against the request.\n` +
+        `  3. Engine (Gamma API) was called; result sealed with request_hash.\n` +
+        `  4. Audit log recorded verifier check + engine request + engine response.\n` +
+        `  5. Verifier successfully blocked an oversized request without reaching the engine.\n` +
+        `  6. Audit log hash-chain integrity verified end-to-end.\n` +
+        `\nThe AI never produced a price. The engine did. Every step is replayable.\n`);
+    // Clean up the temp audit log and force exit so Node's fetch keepalive
+    // doesn't hold the event loop open in Replit.
+    await rm(dir, { recursive: true, force: true });
+}
+main()
+    .then(() => process.exit(0))
+    .catch((e) => {
+    process.stderr.write(`fatal: ${e.message}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=demo.js.map

package/dist/demo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"demo.js","sourceRoot":"","sources":["../src/demo.ts"],"names":[],"mappings":"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"}

package/dist/envelope.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Content-addressed envelope for engine calls.
+ *
+ * The single load-bearing primitive of the audit substrate. Every engine
+ * request resolves to a deterministic SHA-256 hash over canonicalized inputs;
+ * identical hash → identical result, byte-for-byte. The AI layer cannot
+ * produce a number — it can only request one inside an envelope, and the
+ * envelope is the only thing regulators replay.
+ *
+ * This is the gap in current MCP. We ship it as a wrapper now and propose
+ * the spec extension separately.
+ */
+export interface ContentAddressedRequest {
+    /** Logical operation, e.g. "polymarket.get_market", "alts.nav_compute". */
+    readonly operation: string;
+    /** Pinned engine version, e.g. "polymarket-adapter@0.1.0". */
+    readonly engine_version: string;
+    /** SHA-256 of the JSON schema used to validate `inputs`. */
+    readonly schema_hash: string;
+    /** Operation inputs. Will be canonicalized before hashing. */
+    readonly inputs: JsonValue;
+    /** As-of timestamp (ISO 8601, UTC) for the market data snapshot. */
+    readonly data_as_of: string;
+    /** Optional deterministic seed for any Monte Carlo paths. */
+    readonly deterministic_seed?: string;
+}
+export interface ContentAddressedResponse<T = JsonValue> {
+    /** SHA-256 hash of the canonical request — the replay key. */
+    readonly request_hash: string;
+    /** Engine version that produced this response. Must match the request. */
+    readonly engine_version: string;
+    /** ISO 8601 timestamp when the engine produced this result. */
+    readonly produced_at: string;
+    /** Hardware-determinism honesty flag. False if running on non-deterministic GPU/etc. */
+    readonly byte_identical_replayable: boolean;
+    /** The actual numerical/structured payload. */
+    readonly value: T;
+}
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+/**
+ * Canonical JSON serialization (RFC 8785 JCS, simplified).
+ *
+ * Sorts object keys lexicographically. Numbers are emitted in the shortest
+ * round-trip form. Strings are JSON-escaped. This is the foundation of
+ * deterministic content hashing — two callers producing the same logical
+ * request must produce byte-identical canonical bytes.
+ */
+export declare function canonicalize(value: JsonValue): string;
+/** SHA-256 of a string, hex-encoded. */
+export declare function sha256(input: string): string;
+/** Compute the content-addressed hash of a request. */
+export declare function requestHash(request: ContentAddressedRequest): string;
+/**
+ * Wrap an engine call: compute the hash, invoke the engine, return the
+ * envelope. The engine function must be deterministic given the same
+ * canonicalized inputs — if it isn't, the replay primitive is a lie.
+ */
+export declare function sealEnvelope<T>(request: ContentAddressedRequest, engine: (req: ContentAddressedRequest) => Promise<T>, options?: {
+    byte_identical_replayable: boolean;
+}): Promise<ContentAddressedResponse<T>>;
+/**
+ * Generate a deterministic seed from a string source. Useful when the AI
+ * layer needs to commit to a seed before the engine call — the seed itself
+ * is content-addressed so the agent can't retroactively pick a favourable one.
+ */
+export declare function deriveSeed(source: string): string;
+/** Generate a fresh random seed for cases where determinism is not yet required. */
+export declare function freshSeed(): string;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,uBAAuB;IACtC,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,wBAAwB,CAAC,CAAC,GAAG,SAAS;IACrD,8DAA8D;IAC9D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,wFAAwF;IACxF,QAAQ,CAAC,yBAAyB,EAAE,OAAO,CAAC;IAC5C,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,EAAE,GACX;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAE1C;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAsBrD;AAED,wCAAwC;AACxC,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,uDAAuD;AACvD,wBAAgB,WAAW,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAcpE;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,OAAO,EAAE,uBAAuB,EAChC,MAAM,EAAE,CAAC,GAAG,EAAE,uBAAuB,KAAK,OAAO,CAAC,CAAC,CAAC,EACpD,OAAO,GAAE;IAAE,yBAAyB,EAAE,OAAO,CAAA;CAAyC,GACrF,OAAO,CAAC,wBAAwB,CAAC,CAAC,CAAC,CAAC,CAStC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,oFAAoF;AACpF,wBAAgB,SAAS,IAAI,MAAM,CAElC"}

package/dist/envelope.js

@@ -0,0 +1,83 @@
+import { createHash, randomBytes } from "node:crypto";
+/**
+ * Canonical JSON serialization (RFC 8785 JCS, simplified).
+ *
+ * Sorts object keys lexicographically. Numbers are emitted in the shortest
+ * round-trip form. Strings are JSON-escaped. This is the foundation of
+ * deterministic content hashing — two callers producing the same logical
+ * request must produce byte-identical canonical bytes.
+ */
+export function canonicalize(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new Error(`canonicalize: non-finite number is not representable: ${value}`);
+        }
+        return JSON.stringify(value);
+    }
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return "[" + value.map(canonicalize).join(",") + "]";
+    }
+    const keys = Object.keys(value).sort();
+    const parts = keys.map((k) => {
+        const v = value[k];
+        if (v === undefined) {
+            throw new Error(`canonicalize: undefined values not permitted (key: ${k})`);
+        }
+        return JSON.stringify(k) + ":" + canonicalize(v);
+    });
+    return "{" + parts.join(",") + "}";
+}
+/** SHA-256 of a string, hex-encoded. */
+export function sha256(input) {
+    return createHash("sha256").update(input, "utf8").digest("hex");
+}
+/** Compute the content-addressed hash of a request. */
+export function requestHash(request) {
+    // The hash is over the canonicalized request envelope. We exclude any
+    // future fields by being explicit about what enters the hash.
+    const hashable = {
+        operation: request.operation,
+        engine_version: request.engine_version,
+        schema_hash: request.schema_hash,
+        inputs: request.inputs,
+        data_as_of: request.data_as_of,
+        ...(request.deterministic_seed !== undefined
+            ? { deterministic_seed: request.deterministic_seed }
+            : {}),
+    };
+    return sha256(canonicalize(hashable));
+}
+/**
+ * Wrap an engine call: compute the hash, invoke the engine, return the
+ * envelope. The engine function must be deterministic given the same
+ * canonicalized inputs — if it isn't, the replay primitive is a lie.
+ */
+export async function sealEnvelope(request, engine, options = { byte_identical_replayable: false }) {
+    const value = await engine(request);
+    return {
+        request_hash: requestHash(request),
+        engine_version: request.engine_version,
+        produced_at: new Date().toISOString(),
+        byte_identical_replayable: options.byte_identical_replayable,
+        value: value,
+    };
+}
+/**
+ * Generate a deterministic seed from a string source. Useful when the AI
+ * layer needs to commit to a seed before the engine call — the seed itself
+ * is content-addressed so the agent can't retroactively pick a favourable one.
+ */
+export function deriveSeed(source) {
+    return sha256(`seed:${source}`).slice(0, 32);
+}
+/** Generate a fresh random seed for cases where determinism is not yet required. */
+export function freshSeed() {
+    return randomBytes(16).toString("hex");
+}
+//# sourceMappingURL=envelope.js.map

package/dist/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"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"}

package/dist/exporters/annex-iv.d.ts

@@ -0,0 +1,40 @@
+/**
+ * EU AI Act Annex IV technical documentation exporter.
+ *
+ * Walks the kbot-finance audit log and emits a markdown bundle aligned to
+ * the structure required by EU AI Act Article 11 / Annex IV. The same
+ * bundle satisfies Fed SR 26-02 technical documentation requirements
+ * because both regimes converge on the same artifact set.
+ *
+ * v0.1 emits a single markdown document. v0.2 will emit a structured
+ * directory (model card, training-data manifest, evaluation logs,
+ * deployment config, prompt templates, drift reports, incident records)
+ * matching the AI Act's Annex IV sections 1-9 verbatim.
+ *
+ * This is the artifact compliance teams buy from the platform; the
+ * audit log is the raw material, the exporter is the user-visible
+ * deliverable.
+ */
+export interface AnnexIvBundle {
+    readonly format: "markdown";
+    readonly content: string;
+    readonly meta: {
+        readonly generated_at: string;
+        readonly audit_log_path: string;
+        readonly audit_log_intact: boolean;
+        readonly entry_count: number;
+        readonly first_seq: number | null;
+        readonly last_seq: number | null;
+    };
+}
+/**
+ * Read a JSONL audit log and emit an Annex IV-shaped markdown bundle.
+ * Returns the rendered string plus a small metadata block — caller writes
+ * the bundle to disk, e-mails it, or uploads to a regulator portal.
+ */
+export declare function exportAnnexIv(audit_log_path: string, options?: {
+    system_name?: string;
+    deployer?: string;
+    jurisdiction?: "EU" | "US" | "UK" | "SG" | "HK" | "UAE" | "GLOBAL";
+}): Promise<AnnexIvBundle>;
+//# sourceMappingURL=annex-iv.d.ts.map

package/dist/exporters/annex-iv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annex-iv.d.ts","sourceRoot":"","sources":["../../src/exporters/annex-iv.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;QACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;KAClC,CAAC;CACH;AA0DD;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE;IACP,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,GAAG,QAAQ,CAAC;CAC/D,GACL,OAAO,CAAC,aAAa,CAAC,CAyIxB"}

package/dist/exporters/annex-iv.js

@@ -0,0 +1,154 @@
+import { readFile } from "node:fs/promises";
+import { AppendOnlyAuditLog } from "../audit-log.js";
+function aggregate(entries) {
+    const operations = new Map();
+    const rule_failures = new Map();
+    const incidents = [];
+    const engine_versions = new Set();
+    const jurisdictions = new Set();
+    const sessions = new Set();
+    for (const e of entries) {
+        operations.set(e.subject, (operations.get(e.subject) ?? 0) + 1);
+        if (e.action === "incident")
+            incidents.push(e);
+        if (e.action === "verifier_check") {
+            const p = e.payload;
+            if (p.checks) {
+                for (const c of p.checks) {
+                    if (!c.result.pass) {
+                        const key = `${c.rule_id}/${c.result.reason?.code ?? "unknown"}`;
+                        rule_failures.set(key, (rule_failures.get(key) ?? 0) + 1);
+                    }
+                }
+            }
+        }
+        if (e.action === "engine_response") {
+            const p = e.payload;
+            if (typeof p.engine_version === "string")
+                engine_versions.add(p.engine_version);
+        }
+        sessions.add(e.session_id);
+    }
+    return {
+        entries: entries.slice(),
+        operations,
+        rule_failures,
+        incidents,
+        engine_versions,
+        jurisdictions,
+        sessions,
+    };
+}
+function formatNumber(n) {
+    return n.toLocaleString("en-US");
+}
+function section(title, body) {
+    return `## ${title}\n\n${body}\n`;
+}
+/**
+ * Read a JSONL audit log and emit an Annex IV-shaped markdown bundle.
+ * Returns the rendered string plus a small metadata block — caller writes
+ * the bundle to disk, e-mails it, or uploads to a regulator portal.
+ */
+export async function exportAnnexIv(audit_log_path, options = {}) {
+    const integrity = await AppendOnlyAuditLog.verify(audit_log_path);
+    const raw = await readFile(audit_log_path, "utf8").catch(() => "");
+    const lines = raw.split("\n").filter((l) => l.length > 0);
+    const entries = lines.map((l) => JSON.parse(l));
+    const agg = aggregate(entries);
+    const first = entries[0];
+    const last = entries[entries.length - 1];
+    const system_name = options.system_name ?? "kbot-finance AI Intelligence Layer";
+    const deployer = options.deployer ?? "(deployer not specified)";
+    const jurisdiction = options.jurisdiction ?? "EU";
+    const header = `# Annex IV Technical Documentation Pack
+
+**System name:** ${system_name}
+**Deployer:** ${deployer}
+**Jurisdiction filed under:** ${jurisdiction}
+**Generated:** ${new Date().toISOString()}
+**Audit log:** ${audit_log_path}
+**Hash chain integrity:** ${integrity.ok ? "INTACT" : `BROKEN at seq=${integrity.ok ? "" : integrity.broken_at_seq}`}
+**Period covered:** ${first?.timestamp ?? "(empty)"} → ${last?.timestamp ?? "(empty)"}
+**Entries:** ${formatNumber(entries.length)}
+`;
+    const sec1 = section("1. General description of the AI system", `An AI-orchestration ("Intelligence") layer that issues content-addressed engine requests on behalf of authenticated callers. The system **never produces a financial number itself** — numbers are produced by deterministic engine adapters wrapped in SHA-256-hashed request envelopes. Each response carries a \`request_hash\` that uniquely identifies the call and is reproducible from the canonicalized inputs.
+
+The system operates in the seconds-to-minutes latency band; sub-millisecond execution paths are explicitly out of scope.
+
+Engine adapters wired into this deployment:
+${[...agg.engine_versions].sort().map((v) => `- ${v}`).join("\n") || "- (none recorded)"}
+`);
+    const opLines = [...agg.operations.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .map(([op, n]) => `- ${op}: ${formatNumber(n)} entries`)
+        .join("\n");
+    const sec2 = section("2. Detailed description of elements and process of development", `Engine adapters expose typed read/write operations; the AI orchestration layer composes them through a content-addressed envelope. Every operation is governed by a regulatory verifier that evaluates jurisdiction-aware rules-as-code before the engine is invoked. Operation traffic in the audited period:
+
+${opLines || "- (no operations recorded)"}
+`);
+    const sec3 = section("3. Detailed description of monitoring, functioning and control", `Every request and response is logged into a hash-chained append-only audit log (\`AppendOnlyAuditLog\`). Each entry includes \`prev_hash\`, \`self_hash\`, and a strictly monotonic \`seq\`. The chain is verifiable by walking the log and recomputing entry hashes (\`AppendOnlyAuditLog.verify\`). Drift, hallucination, and incident reports flow into the same log under action codes \`incident\`, \`replay_mismatch\`.
+
+Hash chain integrity at time of export: **${integrity.ok ? "INTACT" : "BROKEN"}**.
+`);
+    const ruleLines = [...agg.rule_failures.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .map(([k, n]) => `- ${k}: ${formatNumber(n)} occurrences`)
+        .join("\n");
+    const sec4 = section("4. Risk management system", `A pre-action regulatory verifier evaluates rules-as-code before any engine call. Failures emit adverse-action-style reason codes patterned on ECOA. The verifier never short-circuits — every applicable rule runs so the audit log records the full evaluation, not just the first failure.
+
+Verifier rejections during the audited period:
+
+${ruleLines || "- (no verifier rejections recorded)"}
+
+Material-gate approval tokens (HMAC-SHA256-signed; Ed25519 in v0.2) bind every approver decision to the exact \`request_hash\` they signed off on. Tokens cannot be replayed across requests, sessions, or materiality classes.
+`);
+    const sec5 = section("5. Description of any changes to the system through its lifecycle", `Engine adapters and verifier rules are versioned independently. The audit log records every engine_version observed during the audited period (see §1). Adapter upgrades are non-breaking when they preserve the same \`engine_version\` namespace; breaking upgrades produce a new version string and therefore a new \`request_hash\` for any otherwise-identical request.
+
+No retraining cycles occur within the kbot-finance substrate itself; AI model versions are external dependencies whose lineage is captured in \`model_version\` fields on each request envelope (enforced by \`rule.model_version_pinned\`).
+`);
+    const sec6 = section("6. List of harmonised standards / common specifications applied", `- IEEE 754-2019 floating-point arithmetic (numerical determinism preconditions)
+- RFC 8785 JSON Canonicalization Scheme (canonical input hashing)
+- SHA-256 (content addressing, audit-log chain)
+- HMAC-SHA256 (approval token signing, v0.1)
+- ISO 8601 UTC timestamps
+- FINOS AI Governance Framework v2.0 risk catalog
+- Mapped to: EU AI Act Art. 11-15, Fed SR 26-02, ESMA MiFID II RTS 6 (Article 9 self-assessment), FINRA 2026 ROR GenAI section, FCA SS1/23.
+`);
+    const incidentLines = agg.incidents.length === 0
+        ? "- (no incidents recorded)"
+        : agg.incidents.map((i) => `- ${i.timestamp} seq=${i.seq} subject=${i.subject} payload=${JSON.stringify(i.payload).slice(0, 200)}`).join("\n");
+    const sec7 = section("7. EU declaration of conformity / serious-incident records", `Serious-incident reports flow through the same audit log under action=\`incident\`. The reportable surface satisfies Reg S-P 72-hour notification timelines and AI Act Art. 73 serious-incident reporting through the same plumbing — incidents are not parallel records, they are entries in the chain.
+
+Incidents observed during the audited period:
+
+${incidentLines}
+`);
+    const sec8 = section("8. Records of post-market monitoring", `Drift, hallucination, and verifier-rejection rates are computable from this log directly (see §4). Long-term retention is configured to the longest applicable bar: 10 years post-decommission for high-risk AI Act systems (Art. 19); 6 years for Exchange Act 17a-4 records; 5 years for Advisers Act 204-2 / MiFID II.
+`);
+    const content = header +
+        "\n---\n\n" +
+        sec1 +
+        sec2 +
+        sec3 +
+        sec4 +
+        sec5 +
+        sec6 +
+        sec7 +
+        sec8 +
+        "\n---\n\n" +
+        `*Generated by @kernel.chat/kbot-finance Annex IV exporter. Audit log integrity verifiable via \`AppendOnlyAuditLog.verify("${audit_log_path}")\`.*\n`;
+    return {
+        format: "markdown",
+        content,
+        meta: {
+            generated_at: new Date().toISOString(),
+            audit_log_path,
+            audit_log_intact: integrity.ok,
+            entry_count: entries.length,
+            first_seq: first?.seq ?? null,
+            last_seq: last?.seq ?? null,
+        },
+    };
+}
+//# sourceMappingURL=annex-iv.js.map

package/dist/exporters/annex-iv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annex-iv.js","sourceRoot":"","sources":["../../src/exporters/annex-iv.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAmB,MAAM,iBAAiB,CAAC;AA2CtE,SAAS,SAAS,CAAC,OAAkC;IACnD,MAAM,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC7C,MAAM,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAC;IAChD,MAAM,SAAS,GAAiB,EAAE,CAAC;IACnC,MAAM,eAAe,GAAG,IAAI,GAAG,EAAU,CAAC;IAC1C,MAAM,aAAa,GAAG,IAAI,GAAG,EAAU,CAAC;IACxC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAChE,IAAI,CAAC,CAAC,MAAM,KAAK,UAAU;YAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC/C,IAAI,CAAC,CAAC,MAAM,KAAK,gBAAgB,EAAE,CAAC;YAClC,MAAM,CAAC,GAAG,CAAC,CAAC,OAA8H,CAAC;YAC3I,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;gBACb,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;oBACzB,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;wBACnB,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,IAAI,SAAS,EAAE,CAAC;wBACjE,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;oBAC5D,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QACD,IAAI,CAAC,CAAC,MAAM,KAAK,iBAAiB,EAAE,CAAC;YACnC,MAAM,CAAC,GAAG,CAAC,CAAC,OAAsC,CAAC;YACnD,IAAI,OAAO,CAAC,CAAC,cAAc,KAAK,QAAQ;gBAAE,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC;QAClF,CAAC;QACD,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,KAAK,EAAE;QACxB,UAAU;QACV,aAAa;QACb,SAAS;QACT,eAAe;QACf,aAAa;QACb,QAAQ;KACT,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CAAC,CAAS;IAC7B,OAAO,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;AACnC,CAAC;AAED,SAAS,OAAO,CAAC,KAAa,EAAE,IAAY;IAC1C,OAAO,MAAM,KAAK,OAAO,IAAI,IAAI,CAAC;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,cAAsB,EACtB,UAII,EAAE;IAEN,MAAM,SAAS,GAAG,MAAM,kBAAkB,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IAClE,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;IACnE,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC1D,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAe,CAAC,CAAC;IAC9D,MAAM,GAAG,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IAE/B,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACzB,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACzC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,oCAAoC,CAAC;IAChF,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,0BAA0B,CAAC;IAChE,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,IAAI,CAAC;IAElD,MAAM,MAAM,GAAG;;mBAEE,WAAW;gBACd,QAAQ;gCACQ,YAAY;iBAC3B,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;iBACxB,cAAc;4BACH,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,iBAAiB,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,aAAa,EAAE;sBAC9F,KAAK,EAAE,SAAS,IAAI,SAAS,MAAM,IAAI,EAAE,SAAS,IAAI,SAAS;eACtE,YAAY,CAAC,OAAO,CAAC,MAAM,CAAC;CAC1C,CAAC;IAEA,MAAM,IAAI,GAAG,OAAO,CAClB,yCAAyC,EACzC;;;;;EAKF,CAAC,GAAG,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,mBAAmB;CACvF,CACE,CAAC;IAEF,MAAM,OAAO,GAAG,CAAC,GAAG,GAAG,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;SAC1C,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;SAC3B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,KAAK,YAAY,CAAC,CAAC,CAAC,UAAU,CAAC;SACvD,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,MAAM,IAAI,GAAG,OAAO,CAClB,gEAAgE,EAChE;;EAEF,OAAO,IAAI,4BAA4B;CACxC,CACE,CAAC;IAEF,MAAM,IAAI,GAAG,OAAO,CAClB,gEAAgE,EAChE;;4CAEwC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ;CAC7E,CACE,CAAC;IAEF,MAAM,SAAS,GAAG,CAAC,GAAG,GAAG,CAAC,aAAa,CAAC,OAAO,EAAE,CAAC;SAC/C,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;SAC3B,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,YAAY,CAAC,CAAC,CAAC,cAAc,CAAC;SACzD,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,MAAM,IAAI,GAAG,OAAO,CAClB,2BAA2B,EAC3B;;;;EAIF,SAAS,IAAI,qCAAqC;;;CAGnD,CACE,CAAC;IAEF,MAAM,IAAI,GAAG,OAAO,CAClB,mEAAmE,EACnE;;;CAGH,CACE,CAAC;IAEF,MAAM,IAAI,GAAG,OAAO,CAClB,iEAAiE,EACjE;;;;;;;CAOH,CACE,CAAC;IAEF,MAAM,aAAa,GAAG,GAAG,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;QAC9C,CAAC,CAAC,2BAA2B;QAC7B,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,SAAS,QAAQ,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,OAAO,YAAY,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjJ,MAAM,IAAI,GAAG,OAAO,CAClB,4DAA4D,EAC5D;;;;EAIF,aAAa;CACd,CACE,CAAC;IAEF,MAAM,IAAI,GAAG,OAAO,CAClB,sCAAsC,EACtC;CACH,CACE,CAAC;IAEF,MAAM,OAAO,GACX,MAAM;QACN,WAAW;QACX,IAAI;QACJ,IAAI;QACJ,IAAI;QACJ,IAAI;QACJ,IAAI;QACJ,IAAI;QACJ,IAAI;QACJ,IAAI;QACJ,WAAW;QACX,8HAA8H,cAAc,UAAU,CAAC;IAEzJ,OAAO;QACL,MAAM,EAAE,UAAU;QAClB,OAAO;QACP,IAAI,EAAE;YACJ,YAAY,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACtC,cAAc;YACd,gBAAgB,EAAE,SAAS,CAAC,EAAE;YAC9B,WAAW,EAAE,OAAO,CAAC,MAAM;YAC3B,SAAS,EAAE,KAAK,EAAE,GAAG,IAAI,IAAI;YAC7B,QAAQ,EAAE,IAAI,EAAE,GAAG,IAAI,IAAI;SAC5B;KACF,CAAC;AACJ,CAAC"}

package/dist/governance.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Material-gate approval tokens.
+ *
+ * Any action tagged `material: true` requires a signed approval token from
+ * an authorized human approver before the engine executes. The token binds:
+ *
+ *   - approver identity
+ *   - the exact action envelope the approver saw
+ *   - timestamp
+ *   - a cryptographic signature (HMAC-SHA256 for v0.1; Ed25519 in v0.2)
+ *
+ * v0.1 uses a shared secret per approver because it's the smallest landing
+ * artifact. v0.2 replaces it with public-key signatures so approvers can
+ * sign offline and the system only verifies.
+ */
+export interface ApprovalRequest {
+    /** Action being approved — typically a content-addressed request_hash. */
+    readonly request_hash: string;
+    /** Human-readable summary of what the approver is signing off on. */
+    readonly summary: string;
+    /** Session ID. */
+    readonly session_id: string;
+    /** Materiality classification, e.g. "trade.execute", "model.deploy". */
+    readonly materiality: string;
+}
+export interface ApprovalToken {
+    readonly request_hash: string;
+    readonly summary: string;
+    readonly session_id: string;
+    readonly materiality: string;
+    readonly approver_id: string;
+    readonly approved_at: string;
+    readonly signature: string;
+}
+/**
+ * Approver — issues signed approval tokens. In production this is a separate
+ * service held by compliance; for v0.1 it's an in-process module.
+ */
+export declare class Approver {
+    private readonly approver_id;
+    private readonly secret;
+    constructor(approver_id: string, secret: Buffer);
+    approve(request: ApprovalRequest): ApprovalToken;
+}
+/**
+ * Verify an approval token. Returns true iff the signature matches and the
+ * approver is in the provided trust set.
+ */
+export declare function verifyApproval(token: ApprovalToken, trusted: ReadonlyMap<string, Buffer>, request: ApprovalRequest): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+//# sourceMappingURL=governance.d.ts.map

package/dist/governance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"governance.d.ts","sourceRoot":"","sources":["../src/governance.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kBAAkB;IAClB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAeD;;;GAGG;AACH,qBAAa,QAAQ;IAEjB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM;IAGjC,OAAO,CAAC,OAAO,EAAE,eAAe,GAAG,aAAa;CAYjD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,OAAO,EAAE,eAAe,GACvB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CA2B9C"}