productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/researchReceipt.d.ts

@@ -0,0 +1,76 @@
+import { type AcceptedEnvelopeState, type EnvelopeFailureReason, type JsonValue, type SignedEnvelope, type SplitTrustStores } from "./trustEnvelope.js";
+export declare const RESEARCH_COMPLETION_KIND = "research.completion";
+/** The only states a *completion* receipt may carry. `planned` and `abandoned`
+ *  are real run states, but they are not completions and are never signed as one:
+ *  a signed record is a claim that a run finished, and nothing else may wear it. */
+export declare const TERMINAL_STATES: readonly ["completed", "validated"];
+export type TerminalState = (typeof TERMINAL_STATES)[number];
+export interface ReceiptSourceFact {
+    source_class: string;
+    reached: boolean;
+    item_count: number;
+}
+export interface CompletionReceiptPayload {
+    kind: typeof RESEARCH_COMPLETION_KIND;
+    run_id: string;
+    topic: string;
+    state: TerminalState;
+    sources: ReceiptSourceFact[];
+    evidence_sha256: string;
+    provider: {
+        adapter: string;
+        model: string;
+    };
+    evaluator_version: string;
+    paper_sha256: string;
+    /** Versioned executor evidence; absent in legacy, declaration-only receipts. */
+    retrieval?: JsonValue;
+}
+export interface CompletionReceiptInput {
+    run_id: string;
+    topic: string;
+    state: TerminalState;
+    sources: ReceiptSourceFact[];
+    evidence_sha256: string;
+    provider: {
+        adapter: string;
+        model: string;
+    };
+    evaluator_version: string;
+    paper_sha256: string;
+    /** Versioned executor evidence; absent in legacy, declaration-only receipts. */
+    retrieval?: JsonValue;
+    issued_at: string;
+    sequence: number;
+    previous_hash: string | null;
+}
+export interface VerifyCompletionReceiptOptions {
+    paper_bytes: Buffer;
+    trust_stores: SplitTrustStores;
+    accepted_state: AcceptedEnvelopeState | null;
+    now: string;
+    expected_run_id?: string;
+    expected_provider?: {
+        adapter: string;
+        model: string;
+    };
+    expected_sources?: readonly string[];
+}
+export type CompletionReceiptFailure = EnvelopeFailureReason | "malformed_receipt" | "not_terminal" | "id_mismatch" | "paper_mismatch" | "provider_mismatch" | "source_mismatch";
+export type VerifyCompletionReceiptResult = {
+    ok: true;
+    receipt: CompletionReceiptPayload;
+    next_state: AcceptedEnvelopeState;
+} | {
+    ok: false;
+    reason: CompletionReceiptFailure;
+};
+/** Sign a terminal completion record. Refuses any non-terminal state up front:
+ *  a planning or abandoned record must never exist as a signed completion. */
+export declare function mintCompletionReceipt(input: CompletionReceiptInput, privateKeyPem: string, keyId: string): SignedEnvelope<JsonValue>;
+/** Verify a completion receipt against the paper it claims to certify.
+ *  The signature is necessary but not sufficient: the receipt must also bind the
+ *  paper bytes in front of us, and (when the caller knows them) the expected run,
+ *  provider, and source set. Any mismatch fails — a valid signature over the wrong
+ *  paper is exactly the forgery this record exists to refuse. */
+export declare function verifyCompletionReceipt(envelopeValue: unknown, options: VerifyCompletionReceiptOptions): VerifyCompletionReceiptResult;

package/dist-public/src/researchReceipt.js

@@ -0,0 +1,148 @@
+// A research completion receipt is a productfoo-signed terminal record of a run.
+//
+// It replaces the pre-quarantine receipt, which was a plain `{run_id, topic, at}`
+// file whose "verification" was "a file with this id exists on disk" — forgeable
+// by anyone who can write a file (T-005 finding, B5 incident: a paper of invented
+// citations passed every check foo had). This record instead binds, under an
+// Ed25519 signature over the T-002 canonical envelope, the facts that make a run
+// real: its sources, its evidence set, the provider that produced it, the
+// evaluator version, and the exact bytes of the final paper. A receipt that does
+// not match the paper it is presented with, or is signed by a key productfoo does not
+// trust, or is replayed, does not verify — so it cannot become evidence.
+import { createHash } from "node:crypto";
+import { signEnvelope, verifyEnvelope, } from "./trustEnvelope.js";
+export const RESEARCH_COMPLETION_KIND = "research.completion";
+/** The only states a *completion* receipt may carry. `planned` and `abandoned`
+ *  are real run states, but they are not completions and are never signed as one:
+ *  a signed record is a claim that a run finished, and nothing else may wear it. */
+export const TERMINAL_STATES = ["completed", "validated"];
+const TEN_YEARS_MS = 315_576_000_000;
+function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function isTerminal(state) {
+    return TERMINAL_STATES.includes(state);
+}
+/** Sign a terminal completion record. Refuses any non-terminal state up front:
+ *  a planning or abandoned record must never exist as a signed completion. */
+export function mintCompletionReceipt(input, privateKeyPem, keyId) {
+    if (!isTerminal(input.state)) {
+        throw new TypeError(`a completion receipt cannot carry the non-terminal state "${input.state}"`);
+    }
+    const payload = {
+        kind: RESEARCH_COMPLETION_KIND,
+        run_id: input.run_id,
+        topic: input.topic,
+        state: input.state,
+        sources: input.sources.map((s) => ({
+            source_class: s.source_class,
+            reached: s.reached,
+            item_count: s.item_count,
+        })),
+        evidence_sha256: input.evidence_sha256,
+        provider: { adapter: input.provider.adapter, model: input.provider.model },
+        evaluator_version: input.evaluator_version,
+        paper_sha256: input.paper_sha256,
+        ...(input.retrieval ? { retrieval: input.retrieval } : {}),
+    };
+    const expiresAt = new Date(Date.parse(input.issued_at) + TEN_YEARS_MS).toISOString();
+    return signEnvelope({
+        namespace: "foo",
+        artifact_kind: RESEARCH_COMPLETION_KIND,
+        artifact_id: input.run_id,
+        payload: payload,
+        key_id: keyId,
+        issued_at: input.issued_at,
+        not_before: input.issued_at,
+        expires_at: expiresAt,
+        sequence: input.sequence,
+        previous_hash: input.previous_hash,
+    }, privateKeyPem);
+}
+function readField(value, field) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    return value[field];
+}
+function parsePayload(payload) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload))
+        return null;
+    const p = payload;
+    if (p.kind !== RESEARCH_COMPLETION_KIND)
+        return null;
+    if (typeof p.run_id !== "string" || typeof p.topic !== "string")
+        return null;
+    if (typeof p.state !== "string" || !isTerminal(p.state))
+        return null;
+    if (!Array.isArray(p.sources))
+        return null;
+    const sources = [];
+    for (const s of p.sources) {
+        const sc = readField(s, "source_class");
+        const reached = readField(s, "reached");
+        const count = readField(s, "item_count");
+        if (typeof sc !== "string" || typeof reached !== "boolean" || typeof count !== "number" || !Number.isSafeInteger(count) || count < 0)
+            return null;
+        sources.push({ source_class: sc, reached, item_count: count });
+    }
+    const provider = p.provider;
+    if (!provider || typeof provider.adapter !== "string" || typeof provider.model !== "string")
+        return null;
+    if (typeof p.evidence_sha256 !== "string" || typeof p.evaluator_version !== "string" || typeof p.paper_sha256 !== "string") {
+        return null;
+    }
+    return {
+        kind: RESEARCH_COMPLETION_KIND,
+        run_id: p.run_id,
+        topic: p.topic,
+        state: p.state,
+        sources,
+        evidence_sha256: p.evidence_sha256,
+        provider: { adapter: provider.adapter, model: provider.model },
+        evaluator_version: p.evaluator_version,
+        paper_sha256: p.paper_sha256,
+        ...(p.retrieval ? { retrieval: p.retrieval } : {}),
+    };
+}
+/** Verify a completion receipt against the paper it claims to certify.
+ *  The signature is necessary but not sufficient: the receipt must also bind the
+ *  paper bytes in front of us, and (when the caller knows them) the expected run,
+ *  provider, and source set. Any mismatch fails — a valid signature over the wrong
+ *  paper is exactly the forgery this record exists to refuse. */
+export function verifyCompletionReceipt(envelopeValue, options) {
+    const artifactId = readField(envelopeValue, "artifact_id");
+    const env = verifyEnvelope(envelopeValue, {
+        expected_namespace: "foo",
+        expected_artifact_kind: RESEARCH_COMPLETION_KIND,
+        expected_artifact_id: options.expected_run_id ?? (typeof artifactId === "string" ? artifactId : ""),
+        trust_stores: options.trust_stores,
+        accepted_state: options.accepted_state,
+        verification_mode: "accept",
+        now: options.now,
+    });
+    if (!env.ok)
+        return { ok: false, reason: env.reason };
+    const payload = parsePayload(env.verified_envelope.payload);
+    if (!payload)
+        return { ok: false, reason: "malformed_receipt" };
+    if (!isTerminal(payload.state))
+        return { ok: false, reason: "not_terminal" };
+    if (payload.run_id !== env.verified_envelope.artifact_id)
+        return { ok: false, reason: "id_mismatch" };
+    if (sha256Hex(options.paper_bytes) !== payload.paper_sha256) {
+        return { ok: false, reason: "paper_mismatch" };
+    }
+    if (options.expected_provider &&
+        (options.expected_provider.adapter !== payload.provider.adapter ||
+            options.expected_provider.model !== payload.provider.model)) {
+        return { ok: false, reason: "provider_mismatch" };
+    }
+    if (options.expected_sources) {
+        const have = [...payload.sources.map((s) => s.source_class)].sort();
+        const want = [...options.expected_sources].sort();
+        if (have.length !== want.length || have.some((c, i) => c !== want[i])) {
+            return { ok: false, reason: "source_mismatch" };
+        }
+    }
+    return { ok: true, receipt: payload, next_state: env.next_state };
+}

package/dist-public/src/researchRender.d.ts

@@ -0,0 +1,2 @@
+/** Render a research report markdown into a self-contained HTML page. */
+export declare function renderReportHtml(md: string): string;

package/dist-public/src/researchRender.js

@@ -0,0 +1,267 @@
+// Renders a research/*.md into a self-contained HTML page, using the same renderer
+// proven in the initiative-brief preview: a markdown → HTML pass, the reusable
+// analytical block registry (```heatmap → Harvey-ball matrix), a report-header card,
+// an "On this page" jump-nav, and reading-measure prose. This is the shared render
+// module (research-format-render-v0 R-003) so the preview and `foo research view`
+// cannot drift. Self-contained: no CDN, CSP-safe.
+function esc(s) {
+    return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
+}
+// Escape the quote characters that would let a value break out of an href="…"
+// attribute. Callers pass strings that have already had &<> escaped upstream.
+function attr(s) {
+    return s.replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+// Validate a markdown link target for use in an href. Returns an
+// attribute-safe string, or null when the scheme is not allowed (so the caller
+// renders the raw text instead of a clickable link). Only http(s), mailto, and
+// scheme-less (relative/anchor) targets are permitted — `javascript:`, `data:`,
+// `vbscript:`, etc. are rejected. Tab/newline/CR are stripped before the scheme
+// check because browsers strip them from URLs before resolving the scheme.
+function safeHref(h) {
+    const scheme = h.replace(/[\t\n\r]/g, "").trim().match(/^([a-z][a-z0-9+.-]*):/i);
+    if (scheme && !/^(https?|mailto)$/i.test(scheme[1]))
+        return null;
+    return attr(h.trim());
+}
+// ---- reusable analytical block components (```<type> routes here) ----
+function renderHeatmap(src) {
+    let dims = [];
+    let legend = "";
+    const rows = [];
+    src.split("\n").filter((s) => s.trim()).forEach((l) => {
+        const t = l.trim();
+        if (/^legend:/i.test(t)) {
+            legend = t.replace(/^legend:/i, "").trim();
+            return;
+        }
+        if (/^dims:/i.test(t)) {
+            dims = t.replace(/^dims:/i, "").split("|").map((x) => x.trim());
+            return;
+        }
+        if (/^tier:/i.test(t)) {
+            rows.push({ tier: t.replace(/^tier:/i, "").trim() });
+            return;
+        }
+        const self = /^self:/i.test(t);
+        const body = self ? t.replace(/^self:/i, "").trim() : t;
+        const parts = body.split("|").map((x) => x.trim());
+        const name = parts.shift();
+        rows.push({ name, self, vals: parts.map((v) => parseInt(v, 10)) });
+    });
+    const ball = (lvl) => {
+        lvl = isNaN(lvl) ? 0 : Math.max(0, Math.min(4, lvl));
+        const w = { 1: "M9,9 L9,1 A8,8 0 0 1 17,9 Z", 2: "M9,9 L9,1 A8,8 0 0 1 9,17 Z", 3: "M9,9 L9,1 A8,8 0 1 1 1,9 Z" };
+        const inner = lvl >= 4 ? '<circle cx="9" cy="9" r="8" fill="currentColor"/>' : lvl > 0 ? `<path d="${w[lvl]}" fill="currentColor"/>` : "";
+        return `<svg class="hb" width="15" height="15" viewBox="0 0 18 18" role="img" aria-label="${lvl} of 4"><circle cx="9" cy="9" r="8" fill="none" stroke="currentColor" stroke-width="1.4" opacity="0.4"/>${inner}</svg>`;
+    };
+    let html = `<div class="hmap"><table class="hm"><thead><tr><th></th>${dims.map((d) => `<th>${esc(d)}</th>`).join("")}</tr></thead><tbody>`;
+    rows.forEach((r) => {
+        if (r.tier) {
+            html += `<tr class="hm-tier"><td colspan="${dims.length + 1}">${esc(r.tier)}</td></tr>`;
+            return;
+        }
+        html += `<tr${r.self ? ' class="hm-self"' : ""}><td class="hm-name">${esc(r.name || "")}</td>${(r.vals || []).map((v) => `<td class="hm-cell" title="${isNaN(v) ? 0 : v} of 4">${ball(v)}</td>`).join("")}</tr>`;
+    });
+    html += `</tbody></table>${legend ? `<div class="hm-legend">${esc(legend)}</div>` : ""}</div>`;
+    return html;
+}
+const BLOCKS = { heatmap: renderHeatmap };
+function mdToHtml(md) {
+    const e = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+    const inl = (s) => e(s)
+        .replace(/`([^`]+)`/g, "<code>$1</code>")
+        .replace(/\*\*([\s\S]+?)\*\*/g, "<strong>$1</strong>")
+        .replace(/(^|[^*])\*([^*\s][^*]*?)\*/g, "$1<em>$2</em>")
+        .replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_m, t, h) => { const href = safeHref(h); return href === null ? `[${t}](${h})` : `<a href="${href}"${/^https?:/i.test(href) ? ' target="_blank" rel="noopener"' : ""}>${t}</a>`; })
+        .replace(/(^|[\s(])(https?:\/\/[^\s<]+)/g, (_m, pre, u) => { let tl = ""; const mt = u.match(/[.,;:)\]]+$/); if (mt) {
+        tl = mt[0];
+        u = u.slice(0, -tl.length);
+    } return `${pre}<a href="${attr(u)}" target="_blank" rel="noopener">${u}</a>${tl}`; });
+    const L = md.replace(/\r/g, "").split("\n");
+    const out = [];
+    let n = 0;
+    const cells = (r) => r.replace(/^\s*\|?|\|?\s*$/g, "").split("|").map((c) => c.trim());
+    const cont = (s, nx) => !!s && !!s.trim() && !/^\s*([-*+]|\d+\.)\s+/.test(s) && !/^\s*(#{1,6}\s|>|```|---)/.test(s) && !(/\|/.test(s) && /^\s*\|?\s*:?-{2,}/.test(nx || ""));
+    while (n < L.length) {
+        const line = L[n];
+        if (/^\s*```/.test(line)) {
+            const lang = line.trim().slice(3).trim().toLowerCase();
+            const buf = [];
+            n++;
+            while (n < L.length && !/^\s*```/.test(L[n])) {
+                buf.push(L[n]);
+                n++;
+            }
+            n++;
+            out.push(lang && BLOCKS[lang] ? BLOCKS[lang](buf.join("\n")) : `<pre class="cb"><code>${e(buf.join("\n"))}</code></pre>`);
+            continue;
+        }
+        if (/^\s*(---|\*\*\*|___)\s*$/.test(line)) {
+            out.push("<hr>");
+            n++;
+            continue;
+        }
+        const h = line.match(/^(#{1,6})\s+(.*)$/);
+        if (h) {
+            const d = h[1].length;
+            const id = "s-" + h[2].toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "").slice(0, 48);
+            out.push(`<h${d}${d >= 2 && d <= 3 ? ` id="${id}"` : ""}>${inl(h[2])}</h${d}>`);
+            n++;
+            continue;
+        }
+        if (/^\s*>\s?/.test(line)) {
+            const buf = [];
+            while (n < L.length && /^\s*>\s?/.test(L[n])) {
+                buf.push(L[n].replace(/^\s*>\s?/, ""));
+                n++;
+            }
+            out.push(`<blockquote>${mdToHtml(buf.join("\n"))}</blockquote>`);
+            continue;
+        }
+        if (/\|/.test(line) && n + 1 < L.length && /^\s*\|?\s*:?-{2,}/.test(L[n + 1])) {
+            const head = line;
+            const trows = [];
+            n += 2;
+            while (n < L.length && /\|/.test(L[n]) && L[n].trim()) {
+                trows.push(L[n]);
+                n++;
+            }
+            let t = `<table><thead><tr>${cells(head).map((c) => `<th>${inl(c)}</th>`).join("")}</tr></thead><tbody>`;
+            trows.forEach((r) => { t += `<tr>${cells(r).map((c) => `<td>${inl(c)}</td>`).join("")}</tr>`; });
+            out.push(`<div class="tblw">${t}</tbody></table></div>`);
+            continue;
+        }
+        if (/^\s*[-*+]\s+/.test(line)) {
+            const items = [];
+            while (n < L.length && /^\s*[-*+]\s+/.test(L[n])) {
+                let txt = L[n].replace(/^\s*[-*+]\s+/, "");
+                n++;
+                while (n < L.length && cont(L[n], L[n + 1])) {
+                    txt += " " + L[n].trim();
+                    n++;
+                }
+                items.push(`<li>${inl(txt)}</li>`);
+            }
+            out.push(`<ul>${items.join("")}</ul>`);
+            continue;
+        }
+        if (/^\s*\d+\.\s+/.test(line)) {
+            const items = [];
+            while (n < L.length && /^\s*\d+\.\s+/.test(L[n])) {
+                let txt = L[n].replace(/^\s*\d+\.\s+/, "");
+                n++;
+                while (n < L.length && cont(L[n], L[n + 1])) {
+                    txt += " " + L[n].trim();
+                    n++;
+                }
+                items.push(`<li>${inl(txt)}</li>`);
+            }
+            out.push(`<ol>${items.join("")}</ol>`);
+            continue;
+        }
+        if (!line.trim()) {
+            n++;
+            continue;
+        }
+        const buf = [line];
+        n++;
+        while (n < L.length && L[n].trim() && !/^\s*(#{1,6}\s|>|[-*+]\s|\d+\.\s|```|---)/.test(L[n]) && !(/\|/.test(L[n]) && /^\s*\|?\s*:?-{2,}/.test(L[n + 1] || ""))) {
+            buf.push(L[n]);
+            n++;
+        }
+        out.push(`<p>${inl(buf.join(" "))}</p>`);
+    }
+    return out.join("\n");
+}
+function reportChrome(md) {
+    const inl = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/`([^`]+)`/g, "<code>$1</code>").replace(/\*\*([\s\S]+?)\*\*/g, "<strong>$1</strong>");
+    const lines = md.replace(/\r/g, "").split("\n");
+    let n = 0;
+    let title = null;
+    let kicker = null;
+    const rows = [];
+    if (/^#\s+/.test(lines[0] || "")) {
+        title = lines[0].replace(/^#\s+/, "");
+        n = 1;
+    }
+    while (n < lines.length) {
+        const ln = lines[n].trim();
+        if (!ln) {
+            n++;
+            continue;
+        }
+        if (/^---+$/.test(ln)) {
+            n++;
+            break;
+        }
+        const m = ln.match(/^\*\*(.+?):\*\*\s*(.*)$/);
+        if (m) {
+            rows.push([m[1], m[2]]);
+            n++;
+            continue;
+        }
+        const k = ln.match(/^\*\*(.+?)\*\*$/);
+        if (k && !kicker && !rows.length) {
+            kicker = k[1];
+            n++;
+            continue;
+        }
+        break;
+    }
+    if (!rows.length && !title)
+        return { card: "", rest: md };
+    let card = '<div class="rpt-head">';
+    if (kicker)
+        card += `<div class="rpt-kicker">${inl(kicker)}</div>`;
+    if (title)
+        card += `<h1 class="rpt-title">${inl(title)}</h1>`;
+    if (rows.length)
+        card += `<dl class="rpt-meta">${rows.map((r) => `<div><dt>${inl(r[0])}</dt><dd>${inl(r[1])}</dd></div>`).join("")}</dl>`;
+    card += "</div>";
+    return { card, rest: lines.slice(n).join("\n") };
+}
+function docToc(md) {
+    const heads = [];
+    md.replace(/\r/g, "").split("\n").forEach((l) => { const m = l.match(/^##\s+(.+)$/); if (m)
+        heads.push(m[1].trim()); });
+    if (heads.length < 4)
+        return "";
+    const slug = (t) => "s-" + t.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "").slice(0, 48);
+    return `<nav class="toc"><div class="toc-k">On this page</div><ul>${heads.map((h) => `<li><a href="#${slug(h)}">${esc(h)}</a></li>`).join("")}</ul></nav>`;
+}
+const CSS = `
+:root{--bg:#fff;--ink:#252525;--muted:#6b6b6b;--border:#e8e8e8;--border-2:#d8d8d8;--oxblood:#8a2b28;--oxblood-soft:#faf3f2;--oxblood-line:#e6c9c6;--proof:#177f86;--proof-soft:#f0f8f8;--code-bg:#201b1a;--code-ink:#f3efee;--sans:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;--mono:ui-monospace,"SF Mono",Menlo,Consolas,monospace}
+@media(prefers-color-scheme:dark){:root{--bg:#161311;--ink:#f0ece9;--muted:#a49c98;--border:#2c2725;--border-2:#3a3431;--oxblood:#d98a86;--oxblood-soft:#241a19;--oxblood-line:#4a302e;--proof:#6fc6cc;--proof-soft:#14201f}}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--ink);font-family:var(--sans)}
+.doc{max-width:min(1000px,92vw);margin:40px auto;padding:0 24px;font-size:14.5px;line-height:1.62}
+.doc h1{font-size:25px;font-weight:720;letter-spacing:-.02em;line-height:1.2;margin:2px 0 6px}
+.doc h2{font-size:19px;font-weight:680;letter-spacing:-.01em;line-height:1.25;margin:30px 0 10px;padding-top:16px;border-top:1px solid var(--border)}
+.doc hr + h2{border-top:0;padding-top:0;margin-top:18px}
+.doc h3{font-size:16px;font-weight:660;margin:22px 0 8px;max-width:74ch}
+.doc h4{font-size:13.5px;font-weight:660;margin:16px 0 6px;max-width:74ch}
+.doc h5,.doc h6{font-size:12px;font-family:var(--mono);text-transform:uppercase;letter-spacing:.06em;color:var(--muted);margin:14px 0 4px}
+.doc p{margin:0 0 12px;max-width:74ch}.doc ul,.doc ol{margin:0 0 12px;padding-left:22px}.doc li{margin:0 0 6px;max-width:72ch}.doc li::marker{color:var(--muted)}
+.doc a{color:var(--oxblood);text-underline-offset:2px}.doc strong{font-weight:680}
+.doc code{font-family:var(--mono);font-size:.87em;background:#00000008;padding:1px 5px;border-radius:4px}
+.doc pre.cb{background:var(--code-bg);color:var(--code-ink);border-radius:9px;padding:12px 14px;overflow-x:auto;margin:0 0 14px;font-size:12.5px;line-height:1.5}.doc pre.cb code{background:none;padding:0;color:inherit}
+.doc blockquote{margin:0 0 14px;padding:11px 15px;background:var(--oxblood-soft);border:1px solid var(--oxblood-line);border-radius:9px}.doc blockquote p:last-child{margin-bottom:0}
+.doc hr{border:0;border-top:1px solid var(--border);margin:24px 0}
+.doc table{border-collapse:collapse;width:100%;margin:0;font-size:13px}.doc .tblw{overflow-x:auto;margin:0 0 16px}
+.doc th,.doc td{border:1px solid var(--border);padding:7px 10px;text-align:left;vertical-align:top}.doc th{background:#00000006;font-weight:660;font-size:12px}.doc tbody tr:nth-child(even){background:#00000003}
+.rpt-kicker{font-family:var(--mono);font-size:10px;letter-spacing:.09em;text-transform:uppercase;color:var(--oxblood);font-weight:700;margin-bottom:7px}
+.rpt-title{font-size:26px;font-weight:720;letter-spacing:-.02em;line-height:1.18;margin:0 0 14px}
+.rpt-meta{display:grid;gap:9px;border:1px solid var(--border);border-radius:10px;padding:13px 15px;background:#00000003;margin:0 0 6px}.rpt-meta>div{display:grid;grid-template-columns:120px 1fr;gap:12px;font-size:13px;line-height:1.5}.rpt-meta dt{font-family:var(--mono);font-size:10.5px;text-transform:uppercase;letter-spacing:.04em;color:var(--muted);font-weight:700}.rpt-meta dd{margin:0}
+.toc{border:1px solid var(--border);border-radius:10px;padding:11px 15px;margin:16px 0 22px;background:#00000003}.toc-k{font-family:var(--mono);font-size:10px;letter-spacing:.07em;text-transform:uppercase;color:var(--muted);font-weight:700;margin-bottom:7px}.toc ul{margin:0;padding:0;list-style:none;columns:2;column-gap:30px}.toc li{margin:0 0 4px;font-size:12.5px}.toc a{color:var(--oxblood);text-decoration:none}
+.plainbox{background:var(--proof-soft);border:1px solid var(--proof-soft);border-radius:10px;padding:12px 15px;margin:2px 0 18px;font-size:14.5px;line-height:1.58}.plainbox .pb-k{font-family:var(--mono);font-size:10px;letter-spacing:.07em;text-transform:uppercase;color:var(--proof);font-weight:700;margin-bottom:5px}
+.hmap{margin:0 0 16px;overflow-x:auto}.hmap .hm{display:table;width:auto;border-collapse:collapse;font-size:12.5px}.hmap .hm thead th{font-weight:600;font-size:11px;color:var(--muted);text-align:center;padding:7px 8px;vertical-align:bottom;line-height:1.2;min-width:94px;max-width:120px;white-space:normal}.hmap .hm thead th:first-child{min-width:0;text-align:left}.hmap .hm .hm-name{text-align:left;font-weight:600;padding:8px 16px 8px 4px;white-space:nowrap}.hmap .hm .hm-cell{text-align:center;padding:6px 8px}.hmap .hm .hb{color:var(--ink);vertical-align:middle}.hmap .hm-self{background:var(--oxblood-soft)}.hmap .hm-self .hm-name,.hmap .hm-self .hb{color:var(--oxblood)}.hmap .hm-tier td{font-family:var(--mono);font-size:10px;text-transform:uppercase;letter-spacing:.06em;color:var(--muted);padding:14px 4px 4px;font-weight:700}.hmap .hm-legend{font-size:11.5px;color:var(--muted);margin-top:10px}
+`;
+/** Render a research report markdown into a self-contained HTML page. */
+export function renderReportHtml(md) {
+    const { card, rest } = reportChrome(md);
+    const toc = docToc(rest);
+    const body = mdToHtml(rest);
+    const titleMatch = md.match(/^#\s+(.+)$/m);
+    const title = titleMatch ? titleMatch[1].replace(/[`*]/g, "") : "Research report";
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${esc(title)}</title><style>${CSS}</style></head><body><article class="doc">${card}${toc}${body}</article></body></html>`;
+}

package/dist-public/src/researchSigningKey.d.ts

@@ -0,0 +1,19 @@
+import type { SplitTrustStores } from "./trustEnvelope.js";
+export interface FooSigningKey {
+    keyId: string;
+    privateKeyPem: string;
+    publicKeyPem: string;
+}
+export interface KeyProvisionOptions {
+    /** Override the machine-local key directory (tests only). */
+    keyDir?: string;
+    /** Timestamp for a freshly-minted key's valid_from (tests inject; prod uses now). */
+    now?: string;
+}
+/** The split trust stores a verifier loads: productfoo's published research keys, and an
+ *  empty customer store (research receipts are foo-namespace). */
+export declare function loadFooResearchTrustStores(root: string): SplitTrustStores;
+/** Load productfoo's research signing key, generating it on first use. Generating also
+ *  publishes the public key into the tracked trust store, so a receipt minted
+ *  here verifies for anyone who clones the repo. Idempotent. */
+export declare function loadOrCreateFooSigningKey(root: string, options?: KeyProvisionOptions): FooSigningKey;

package/dist-public/src/researchSigningKey.js

@@ -0,0 +1,95 @@
+// productfoo's research signing key — T-005 wiring, Decision 1 (owner-agreed 2026-07-20).
+//
+// productfoo self-signs research completion receipts. The private key is machine-local
+// (never committed — B1); the public key is published in a repo-tracked trust
+// store so any reviewer on a fresh clone can verify a paper's receipt. Forgery
+// needs the private key, which never leaves the machine; verification is public.
+//
+// Residual (recorded, deferred): one active key, no rotation/revocation ceremony
+// yet. The envelope already carries key status (active/retired/revoked), so
+// rotation is additive later. This is the minimal answer for the foo namespace
+// only — it does not resolve the customer key ceremony verdict still waits on.
+import { createHash, createPublicKey, generateKeyPairSync } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+const defaultKeyDir = () => path.join(homedir(), ".foo", "keys");
+const privPath = (dir) => path.join(dir, "research-signing.pem");
+const pubPath = (dir) => path.join(dir, "research-signing.pub.pem");
+const trustStorePath = (root) => path.join(root, "research", ".trust", "foo-research.json");
+function keyIdFor(publicKeyPem) {
+    const der = createPublicKey(publicKeyPem).export({ type: "spki", format: "der" });
+    return `foo-research-${createHash("sha256").update(der).digest("hex").slice(0, 16)}`;
+}
+function readTrustStoreFile(root) {
+    const file = trustStorePath(root);
+    if (!existsSync(file))
+        return { namespace: "foo", keys: [] };
+    try {
+        const raw = JSON.parse(readFileSync(file, "utf8"));
+        if (raw && typeof raw === "object" && raw.namespace === "foo" && Array.isArray(raw.keys)) {
+            return raw;
+        }
+    }
+    catch {
+        /* fall through to empty — an unreadable store verifies nothing, which is safe */
+    }
+    return { namespace: "foo", keys: [] };
+}
+function writeTrustStore(root, store) {
+    const file = trustStorePath(root);
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(store, null, 2)}\n`);
+}
+/** Add a public key to the tracked trust store if not already present. */
+function publishPublicKey(root, key) {
+    const store = readTrustStoreFile(root);
+    if (store.keys.some((k) => k.key_id === key.key_id))
+        return;
+    writeTrustStore(root, { namespace: "foo", keys: [...store.keys, key] });
+}
+/** The split trust stores a verifier loads: productfoo's published research keys, and an
+ *  empty customer store (research receipts are foo-namespace). */
+export function loadFooResearchTrustStores(root) {
+    return {
+        customer: { namespace: "customer", keys: [] },
+        foo: readTrustStoreFile(root),
+    };
+}
+/** Load productfoo's research signing key, generating it on first use. Generating also
+ *  publishes the public key into the tracked trust store, so a receipt minted
+ *  here verifies for anyone who clones the repo. Idempotent. */
+export function loadOrCreateFooSigningKey(root, options = {}) {
+    const dir = options.keyDir ?? defaultKeyDir();
+    if (existsSync(privPath(dir))) {
+        const privateKeyPem = readFileSync(privPath(dir), "utf8");
+        const publicKeyPem = existsSync(pubPath(dir))
+            ? readFileSync(pubPath(dir), "utf8")
+            : createPublicKey(privateKeyPem).export({ type: "spki", format: "pem" }).toString();
+        const keyId = keyIdFor(publicKeyPem);
+        // ensure the tracked store carries this key (e.g. a clone missing the store)
+        publishPublicKey(root, {
+            key_id: keyId,
+            public_key_pem: publicKeyPem,
+            status: "active",
+            valid_from: options.now ?? new Date().toISOString(),
+            valid_until: null,
+        });
+        return { keyId, privateKeyPem, publicKeyPem };
+    }
+    const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+    const privateKeyPem = privateKey.export({ type: "pkcs8", format: "pem" }).toString();
+    const publicKeyPem = publicKey.export({ type: "spki", format: "pem" }).toString();
+    const keyId = keyIdFor(publicKeyPem);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(privPath(dir), privateKeyPem, { mode: 0o600 });
+    writeFileSync(pubPath(dir), publicKeyPem, { mode: 0o644 });
+    publishPublicKey(root, {
+        key_id: keyId,
+        public_key_pem: publicKeyPem,
+        status: "active",
+        valid_from: options.now ?? new Date().toISOString(),
+        valid_until: null,
+    });
+    return { keyId, privateKeyPem, publicKeyPem };
+}

package/dist-public/src/riskClassify.d.ts

@@ -0,0 +1,42 @@
+export type RiskDimension = "irreversible" | "agentic" | "outbound";
+/**
+ * How much the verdict is worth. A keyword hit is evidence, not proof — say so.
+ * high   : the work names a behaviour only risky work has (a loop, an autonomous actor).
+ * medium : risky terms, no governing frame. Treated as risky; the usual case.
+ * low    : risky terms, but the work reads as *governing* them rather than doing them.
+ */
+export type RiskConfidence = "high" | "medium" | "low";
+export type RiskClassification = {
+    work: string;
+    risky: boolean;
+    dimensions: Record<RiskDimension, string[]>;
+    confidence: RiskConfidence;
+    /** True when risky terms matched but the work reads as governing, testing, or documenting them. */
+    governed_frame: boolean;
+    rationale: string;
+    override?: string;
+    spec_first_required: boolean;
+};
+/**
+ * Is the work *governing* the risky thing rather than *doing* it?
+ *
+ * "Add a hook that denies raw research agents" mentions agents; it does not act
+ * agentically — it is the thing that stops agents. "Add a test for the delete path"
+ * mentions delete; it deletes nothing. A bag of words cannot tell those from "delete
+ * the production table", and this classifier used to call all three risky.
+ *
+ * The tell is grammatical, and it is cheap to read: the statement OPENS with a build
+ * verb (so the risky term is an object, not the action) and names a governing
+ * construct (a hook, a gate, a test, an audit). Real risky work does not open with
+ * "add a guard that…".
+ *
+ * This is a heuristic and it will be wrong sometimes. That is why it lowers confidence
+ * and prints its reasoning instead of silently flipping the verdict.
+ */
+export declare function isGovernedFrame(work: string): boolean;
+export interface ClassifyOptions {
+    /** Block on any keyword hit — the pre-calibration behaviour. `--strict`. */
+    strict?: boolean;
+}
+export declare function classifyWork(work: string, override?: string, options?: ClassifyOptions): RiskClassification;
+export declare function renderClassification(classification: RiskClassification, asJson: boolean, glyphsOn?: boolean): string;