@kashscript/hudhud 0.1.0

package/src/certificate/certificate.ts

@@ -0,0 +1,340 @@
+// ============================================================================
+// @kashscript/hudhud/certificate — the Work Certificate (AIUC-1, DSSE-signed)
+// ----------------------------------------------------------------------------
+// A monthly, per-client, SIGNED document rendered from the signed ledger — the
+// billing unit (it enumerates the warranted outcomes) and the retention
+// artifact. Everything DERIVES from the ledger: each CertifiedWorkRecord carries
+// its evidence (chain-tip hash, sign-off row, exception classification, anchor);
+// the certificate aggregates the counts and a third party RE-DERIVES them
+// (verifyWorkCertificate). Sections map onto the six AIUC-1 control domains
+// (web-verified, not invented). DSSE via `@kashscript/attest`. Ported from the
+// oreoasis-core-host engine (M5); format/payload identifiers neutralized.
+// ============================================================================
+
+import { signEnvelope, verifyEnvelope } from "@kashscript/attest";
+import type { DsseEnvelope, DsseSigner } from "@kashscript/attest";
+
+import type { AnchorRecord } from "../anchor";
+import { FAILURE_CLASSES } from "../exception";
+import type { ExceptionClassificationRecord, FailureClass } from "../exception";
+
+export const WORK_CERTIFICATE_FORMAT_VERSION = "kash-work-certificate/1" as const;
+export const WORK_CERTIFICATE_PAYLOAD_TYPE = "application/vnd.kash.work-certificate+json" as const;
+
+/** The AIUC-1 standard's canonical reference (web-verified). */
+export const AIUC1_SOURCE = "https://www.aiuc-1.com/" as const;
+
+export interface Aiuc1Domain {
+  readonly code: "A" | "B" | "C" | "D" | "E" | "F";
+  readonly name: string;
+  readonly covers: string;
+}
+
+export const AIUC1_DOMAINS: ReadonlyArray<Aiuc1Domain> = [
+  { code: "A", name: "Data & Privacy", covers: "Customer-data policy, access controls, and safeguards against data leakage / PII exposure / IP infringement / unauthorized training." },
+  { code: "B", name: "Security", covers: "Adversarial-robustness testing, input filtering, access-privilege enforcement, deployment security, and output-exposure limits." },
+  { code: "C", name: "Safety", covers: "Risk-taxonomy definition, harmful/out-of-scope output prevention, human-review flagging, and third-party testing." },
+  { code: "D", name: "Reliability", covers: "Preventing hallucinated outputs and unsafe tool calls." },
+  { code: "E", name: "Accountability", covers: "Failure-response plans, access monitoring, regulatory compliance, quality management, activity logging, and transparency." },
+  { code: "F", name: "Society", covers: "Preventing AI cyber-misuse and catastrophic-misuse scenarios." },
+];
+
+export type WorkOutcomeStatus = "delivered_autonomous" | "delivered_with_signoff" | "declined";
+
+export interface CertifiedWorkRecord {
+  readonly workItemId: string;
+  readonly sessionId: string;
+  readonly workflowId: string;
+  readonly workflowLabel?: string;
+  readonly status: WorkOutcomeStatus;
+  readonly slaDeadlineIso: string;
+  readonly completedAtIso: string;
+  readonly slaMet: boolean;
+  readonly ledgerRowCount: number;
+  readonly ledgerTipHash: string;
+  readonly signoff: { readonly operatorDid: string; readonly ledgerStepIndex: number } | null;
+  readonly classification: ExceptionClassificationRecord | null;
+  readonly anchor: AnchorRecord | null;
+}
+
+export interface WorkCertificatePeriod {
+  readonly clientDid: string;
+  readonly clientName: string;
+  readonly month: string;
+  readonly fromIso: string;
+  readonly toIso: string;
+}
+
+export interface BuildWorkCertificateInput {
+  readonly period: WorkCertificatePeriod;
+  readonly issuerDid: string;
+  readonly records: ReadonlyArray<CertifiedWorkRecord>;
+  readonly slaTargetPct?: number;
+}
+
+export interface WorkCertificateSummary {
+  readonly workVolumeDelivered: number;
+  readonly workVolumeDeclined: number;
+  readonly automationRatePct: number;
+  readonly exceptionCount: number;
+  readonly exceptionsByClass: Record<FailureClass, number>;
+  readonly humanSignoffCount: number;
+  readonly slaAdherencePct: number;
+  readonly slaTargetPct: number | null;
+  readonly anchoredCount: number;
+}
+
+export interface Aiuc1DomainCoverage extends Aiuc1Domain {
+  readonly evidence: ReadonlyArray<string>;
+  readonly status: "evidenced" | "partial";
+}
+
+export interface CertifiedOutcome {
+  readonly workItemId: string;
+  readonly workflowId: string;
+  readonly status: WorkOutcomeStatus;
+  readonly slaMet: boolean;
+  readonly completedAtIso: string;
+  readonly ledgerTipHash: string;
+  readonly signoffLedgerStepIndex: number | null;
+  readonly classificationId: string | null;
+  readonly failureClass: FailureClass | null;
+  readonly anchorMerkleRoot: string | null;
+  readonly anchorWitnessBackend: string | null;
+}
+
+export interface WorkCertificateAnchorRef {
+  readonly merkleRoot: string;
+  readonly witnessBackend: string;
+  readonly witnessedAtIso: string | null;
+  readonly verifyWith: string;
+}
+
+export interface WorkCertificateBody {
+  readonly formatVersion: string;
+  readonly standard: { readonly name: "AIUC-1"; readonly source: string };
+  readonly period: WorkCertificatePeriod;
+  readonly issuerDid: string;
+  readonly issuedAtIso: string;
+  readonly summary: WorkCertificateSummary;
+  readonly aiuc1Coverage: ReadonlyArray<Aiuc1DomainCoverage>;
+  readonly outcomes: ReadonlyArray<CertifiedOutcome>;
+  readonly anchors: ReadonlyArray<WorkCertificateAnchorRef>;
+  readonly verification: { readonly instructions: string };
+}
+
+export interface WorkCertificate {
+  readonly body: WorkCertificateBody;
+  readonly envelope: DsseEnvelope;
+}
+
+function round1(n: number): number {
+  return Math.round(n * 10) / 10;
+}
+function emptyClassMix(): Record<FailureClass, number> {
+  const mix = {} as Record<FailureClass, number>;
+  for (const c of FAILURE_CLASSES) mix[c] = 0;
+  return mix;
+}
+
+function summarize(records: ReadonlyArray<CertifiedWorkRecord>, slaTargetPct: number | undefined): WorkCertificateSummary {
+  let autonomous = 0;
+  let withSignoff = 0;
+  let declined = 0;
+  let slaMet = 0;
+  let anchored = 0;
+  const exceptionsByClass = emptyClassMix();
+  for (const r of records) {
+    if (r.status === "delivered_autonomous") autonomous += 1;
+    else if (r.status === "delivered_with_signoff") withSignoff += 1;
+    else declined += 1;
+    if (r.slaMet) slaMet += 1;
+    if (r.anchor !== null) anchored += 1;
+    if (r.classification !== null) exceptionsByClass[r.classification.failureClass] += 1;
+  }
+  const delivered = autonomous + withSignoff;
+  const total = records.length;
+  return {
+    workVolumeDelivered: delivered,
+    workVolumeDeclined: declined,
+    automationRatePct: delivered === 0 ? 0 : round1((autonomous / delivered) * 100),
+    exceptionCount: records.filter((r) => r.classification !== null).length,
+    exceptionsByClass,
+    humanSignoffCount: records.filter((r) => r.signoff !== null).length,
+    slaAdherencePct: total === 0 ? 0 : round1((slaMet / total) * 100),
+    slaTargetPct: slaTargetPct ?? null,
+    anchoredCount: anchored,
+  };
+}
+
+function mapAiuc1Coverage(records: ReadonlyArray<CertifiedWorkRecord>, summary: WorkCertificateSummary): ReadonlyArray<Aiuc1DomainCoverage> {
+  const anchoredEvidence =
+    summary.anchoredCount > 0
+      ? `${summary.anchoredCount} of ${records.length} chain tips anchored to a public transparency log (Rekor / OpenTimestamps) — existence provable to a third party.`
+      : "Ledger is tamper-evident and independently exportable; public-witness anchoring available (none attached this period).";
+  return AIUC1_DOMAINS.map((d): Aiuc1DomainCoverage => {
+    switch (d.code) {
+      case "A":
+        return { ...d, status: "evidenced", evidence: ["PII/secret redaction runs before every model call (privacy interceptor); category tags — never raw values — enter the signed ledger."] };
+      case "B":
+        return { ...d, status: "evidenced", evidence: [`Every action Ed25519-signed into an append-only, hash-chained ledger (${records.reduce((n, r) => n + r.ledgerRowCount, 0)} signed rows this period).`, anchoredEvidence] };
+      case "C":
+        return { ...d, status: "evidenced", evidence: [`${summary.exceptionCount} exception(s) flagged for human review and resolved this period; each classified under a fixed risk taxonomy (judgment / gap-filling / ambiguous).`, "Restricted actions suspend for human judgment rather than proceed autonomously."] };
+      case "D":
+        return { ...d, status: "evidenced", evidence: ["Tools restricted to a per-provider allowlist (scope-gating): an out-of-allowlist or restricted tool call cannot be dispatched by construction.", `Automation rate this period: ${summary.automationRatePct}% delivered without human intervention.`] };
+      case "E":
+        return { ...d, status: "evidenced", evidence: ["Complete signed activity log (the ledger) for every work item; a self-contained audit bundle is independently verifiable offline.", `${summary.humanSignoffCount} human sign-off(s), each a SECOND-key signed ledger row (the host cannot forge human judgment).`] };
+      case "F":
+        return { ...d, status: "partial", evidence: ["Money-moving / restricted tools require a two-key human sign-off; no autonomous execution of restricted actions in this period's ledger."] };
+    }
+  });
+}
+
+function toOutcome(r: CertifiedWorkRecord): CertifiedOutcome {
+  return {
+    workItemId: r.workItemId,
+    workflowId: r.workflowId,
+    status: r.status,
+    slaMet: r.slaMet,
+    completedAtIso: r.completedAtIso,
+    ledgerTipHash: r.ledgerTipHash,
+    signoffLedgerStepIndex: r.signoff?.ledgerStepIndex ?? null,
+    classificationId: r.classification?.id ?? null,
+    failureClass: r.classification?.failureClass ?? null,
+    anchorMerkleRoot: r.anchor?.merkleRoot ?? null,
+    anchorWitnessBackend: r.anchor?.witness?.backend ?? null,
+  };
+}
+
+function collectAnchors(records: ReadonlyArray<CertifiedWorkRecord>): ReadonlyArray<WorkCertificateAnchorRef> {
+  const seen = new Set<string>();
+  const out: WorkCertificateAnchorRef[] = [];
+  for (const r of records) {
+    const a = r.anchor;
+    if (a === null || seen.has(a.merkleRoot)) continue;
+    seen.add(a.merkleRoot);
+    const backend = a.witness?.backend ?? "none";
+    out.push({
+      merkleRoot: a.merkleRoot,
+      witnessBackend: backend,
+      witnessedAtIso: a.witness?.witnessedAt ?? null,
+      verifyWith:
+        backend === "rekor"
+          ? "rekor-cli get --uuid <uuid in the anchor receipt>"
+          : backend === "opentimestamps"
+            ? "ots upgrade <proof>.ots && ots verify <proof>.ots"
+            : "no public witness attached (locally tamper-evident only)",
+    });
+  }
+  return out;
+}
+
+const VERIFY_INSTRUCTIONS =
+  "This certificate is a DSSE envelope signed by the issuer's Ed25519 key. " +
+  "To verify: (1) check the envelope signature against the issuer DID's published key; " +
+  "(2) re-derive every summary count from the `outcomes` array (they must match `summary`); " +
+  "(3) for each outcome, re-verify the underlying audit bundle (chain + signatures) with the shipped verifier, " +
+  "and confirm the anchor with public tooling per each entry in `anchors`. Counts derive from the signed ledger — " +
+  "there is no separate metering system to trust.";
+
+/** Build + DSSE-sign a Work Certificate from a period's ledger-derived records. */
+export async function buildWorkCertificate(
+  input: BuildWorkCertificateInput,
+  issuer: DsseSigner,
+  issuedAtIso: string = new Date().toISOString(),
+): Promise<WorkCertificate> {
+  const summary = summarize(input.records, input.slaTargetPct);
+  const body: WorkCertificateBody = {
+    formatVersion: WORK_CERTIFICATE_FORMAT_VERSION,
+    standard: { name: "AIUC-1", source: AIUC1_SOURCE },
+    period: input.period,
+    issuerDid: input.issuerDid,
+    issuedAtIso,
+    summary,
+    aiuc1Coverage: mapAiuc1Coverage(input.records, summary),
+    outcomes: input.records.map(toOutcome),
+    anchors: collectAnchors(input.records),
+    verification: { instructions: VERIFY_INSTRUCTIONS },
+  };
+  const envelope = await signEnvelope(body, WORK_CERTIFICATE_PAYLOAD_TYPE, issuer);
+  return { body, envelope };
+}
+
+export interface WorkCertificateVerifyReport {
+  readonly ok: boolean;
+  readonly signatureOk: boolean;
+  readonly countsRecomputeOk: boolean;
+  readonly mismatches: ReadonlyArray<string>;
+  readonly body: WorkCertificateBody | null;
+}
+
+function recomputeCountsMatch(body: WorkCertificateBody): ReadonlyArray<string> {
+  const mismatches: string[] = [];
+  const o = body.outcomes;
+  const delivered = o.filter((x) => x.status !== "declined").length;
+  const declined = o.filter((x) => x.status === "declined").length;
+  const autonomous = o.filter((x) => x.status === "delivered_autonomous").length;
+  const slaMet = o.filter((x) => x.slaMet).length;
+  const exceptionCount = o.filter((x) => x.classificationId !== null).length;
+  const signoffCount = o.filter((x) => x.signoffLedgerStepIndex !== null).length;
+  const anchored = o.filter((x) => x.anchorMerkleRoot !== null).length;
+  const total = o.length;
+  const s = body.summary;
+  const check = (label: string, got: number, want: number): void => {
+    if (got !== want) mismatches.push(`${label}: outcomes=${got} vs summary=${want}`);
+  };
+  check("workVolumeDelivered", delivered, s.workVolumeDelivered);
+  check("workVolumeDeclined", declined, s.workVolumeDeclined);
+  check("exceptionCount", exceptionCount, s.exceptionCount);
+  check("humanSignoffCount", signoffCount, s.humanSignoffCount);
+  check("anchoredCount", anchored, s.anchoredCount);
+  const wantAutomation = delivered === 0 ? 0 : round1((autonomous / delivered) * 100);
+  if (wantAutomation !== s.automationRatePct) mismatches.push(`automationRatePct: recomputed=${wantAutomation} vs summary=${s.automationRatePct}`);
+  const wantSla = total === 0 ? 0 : round1((slaMet / total) * 100);
+  if (wantSla !== s.slaAdherencePct) mismatches.push(`slaAdherencePct: recomputed=${wantSla} vs summary=${s.slaAdherencePct}`);
+  const classMix = emptyClassMix();
+  for (const x of o) if (x.failureClass !== null) classMix[x.failureClass] += 1;
+  for (const c of FAILURE_CLASSES) {
+    if (classMix[c] !== s.exceptionsByClass[c]) mismatches.push(`exceptionsByClass.${c}: outcomes=${classMix[c]} vs summary=${s.exceptionsByClass[c]}`);
+  }
+  return mismatches;
+}
+
+function isWorkCertificateBody(x: unknown): x is WorkCertificateBody {
+  if (x === null || typeof x !== "object") return false;
+  const b = x as Record<string, unknown>;
+  return (
+    typeof b.issuerDid === "string" &&
+    Array.isArray(b.outcomes) &&
+    b.summary !== null &&
+    typeof b.summary === "object"
+  );
+}
+
+/** Verify a Work Certificate: the DSSE signature is by the DECLARED issuer, the
+ *  payload type matches, and every summary count re-derives from the enumerated
+ *  outcomes. audit r1 F2: a valid signature from the wrong key, a different
+ *  document type, or a malformed body must all fail — not slip through or throw. */
+export async function verifyWorkCertificate(
+  envelope: DsseEnvelope,
+  resolveIssuerKey: (keyid: string) => Uint8Array | null,
+): Promise<WorkCertificateVerifyReport> {
+  const dsse = await verifyEnvelope(envelope, resolveIssuerKey);
+
+  if (dsse.payloadType !== WORK_CERTIFICATE_PAYLOAD_TYPE) {
+    return { ok: false, signatureOk: dsse.ok, countsRecomputeOk: false, mismatches: [`payloadType is "${dsse.payloadType}", expected "${WORK_CERTIFICATE_PAYLOAD_TYPE}"`], body: null };
+  }
+  const body = isWorkCertificateBody(dsse.payloadJson) ? dsse.payloadJson : null;
+  if (!dsse.ok || body === null) {
+    return { ok: false, signatureOk: dsse.ok, countsRecomputeOk: false, mismatches: body === null ? ["malformed work-certificate body"] : [], body };
+  }
+  // The signer must be the issuer the certificate NAMES. A valid signature from
+  // any OTHER resolvable key is not a valid certificate from `issuerDid`.
+  if (!dsse.verifiedKeyids.includes(body.issuerDid)) {
+    return { ok: false, signatureOk: true, countsRecomputeOk: false, mismatches: [`signer ${JSON.stringify(dsse.verifiedKeyids)} is not the declared issuer "${body.issuerDid}"`], body };
+  }
+
+  const mismatches = recomputeCountsMatch(body);
+  const countsRecomputeOk = mismatches.length === 0;
+  return { ok: countsRecomputeOk, signatureOk: true, countsRecomputeOk, mismatches, body };
+}

package/src/certificate/html.ts

@@ -0,0 +1,156 @@
+// ============================================================================
+// @kashscript/hudhud/certificate — the human-readable Work Certificate (HTML)
+// ----------------------------------------------------------------------------
+// A self-contained, client-branded HTML document a CFO can read and a browser
+// can "Print → Save as PDF" (no headless-browser dependency). Renders a
+// WorkCertificateBody; all styling inline so the file is portable. Ported from
+// the oreoasis-core-host engine (M5); the footer is neutralized/brandable.
+// ============================================================================
+
+import type { Aiuc1DomainCoverage, CertifiedOutcome, WorkCertificateBody } from "./certificate";
+
+export interface WorkCertificateBrand {
+  readonly accentColor?: string;
+  readonly logoText?: string;
+  /** Footer attribution line (default neutral). */
+  readonly footerText?: string;
+}
+
+function esc(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+/** audit r1 F10: `accentColor` is interpolated into a CSS declaration (not an
+ *  HTML text node), where `esc()` is insufficient — a `;`/`{`/`}` would break out
+ *  of the rule and rewrite the document's styles (content-hiding / banner spoof).
+ *  Accept ONLY a CSS colour literal, else fall back to the default. */
+function safeAccent(s: string | undefined, fallback: string): string {
+  if (s === undefined) return fallback;
+  return /^(#[0-9a-fA-F]{3,8}|[a-z]{3,20}|rgb\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}\s*\))$/.test(s) ? s : fallback;
+}
+/** audit r1 F10: the body can arrive from a signature-valid-but-untrusted
+ *  envelope, so only hyperlink an `http(s)` source (no `javascript:` URIs). */
+function safeUrl(s: string): string {
+  return /^https?:\/\//i.test(s) ? s : "#";
+}
+function short(hash: string, n = 16): string {
+  return hash.length > n ? `${hash.slice(0, n)}…` : hash;
+}
+
+const STATUS_LABEL: Record<CertifiedOutcome["status"], string> = {
+  delivered_autonomous: "Delivered (autonomous)",
+  delivered_with_signoff: "Delivered (human sign-off)",
+  declined: "Declined at sign-off",
+};
+
+function metricCard(label: string, value: string, sub: string): string {
+  return `<div class="card"><div class="card-v">${esc(value)}</div><div class="card-l">${esc(label)}</div><div class="card-s">${esc(sub)}</div></div>`;
+}
+
+function aiuc1Row(d: Aiuc1DomainCoverage): string {
+  const badge = d.status === "evidenced" ? `<span class="pill pill-ok">Evidenced</span>` : `<span class="pill pill-part">Partial</span>`;
+  const items = d.evidence.map((e) => `<li>${esc(e)}</li>`).join("");
+  return `<tr><td class="dom"><span class="dom-code">${esc(d.code)}</span> ${esc(d.name)} ${badge}<div class="dom-covers">${esc(d.covers)}</div></td><td><ul class="ev">${items}</ul></td></tr>`;
+}
+
+function outcomeRow(o: CertifiedOutcome): string {
+  const cls = o.failureClass ? esc(o.failureClass) : "—";
+  const anchor = o.anchorMerkleRoot ? `${esc(short(o.anchorMerkleRoot, 12))} <span class="mut">(${esc(o.anchorWitnessBackend ?? "none")})</span>` : "—";
+  const sla = o.slaMet ? `<span class="pill pill-ok">met</span>` : `<span class="pill pill-bad">missed</span>`;
+  return `<tr><td class="mono">${esc(o.workItemId)}</td><td>${esc(STATUS_LABEL[o.status])}</td><td>${sla}</td><td class="mono">${esc(short(o.ledgerTipHash, 12))}</td><td>${o.signoffLedgerStepIndex === null ? "—" : `#${o.signoffLedgerStepIndex}`}</td><td>${cls}</td><td class="mono">${anchor}</td></tr>`;
+}
+
+/** Render a self-contained, print-to-PDF-ready HTML certificate. */
+export function renderWorkCertificateHtml(body: WorkCertificateBody, brand: WorkCertificateBrand = {}): string {
+  const accent = safeAccent(brand.accentColor, "#0f2a4a");
+  const logo = brand.logoText ?? body.period.clientName;
+  const footer = brand.footerText ?? "Accountable AI workforce";
+  const s = body.summary;
+  const classMix = Object.entries(s.exceptionsByClass).map(([k, v]) => `${esc(k)}: <b>${v}</b>`).join(" &nbsp;·&nbsp; ");
+  const anchors =
+    body.anchors.length === 0
+      ? `<p class="mut">No public-witness anchor attached to this period (ledger is tamper-evident and independently exportable).</p>`
+      : `<table class="tbl"><thead><tr><th>Merkle root</th><th>Witness</th><th>Witnessed</th><th>Verify with</th></tr></thead><tbody>${body.anchors
+          .map((a) => `<tr><td class="mono">${esc(short(a.merkleRoot, 20))}</td><td>${esc(a.witnessBackend)}</td><td>${esc(a.witnessedAtIso ?? "pending")}</td><td class="mono">${esc(a.verifyWith)}</td></tr>`)
+          .join("")}</tbody></table>`;
+
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Work Certificate — ${esc(body.period.clientName)} — ${esc(body.period.month)}</title>
+<style>
+  :root { --accent: ${esc(accent)}; }
+  * { box-sizing: border-box; }
+  body { font-family: -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif; color: #1a1f26; margin: 0; background: #f4f6f8; }
+  .page { max-width: 900px; margin: 24px auto; background: #fff; box-shadow: 0 1px 6px rgba(0,0,0,.08); }
+  .band { background: var(--accent); color: #fff; padding: 28px 40px; }
+  .band .logo { font-size: 13px; letter-spacing: .18em; text-transform: uppercase; opacity: .85; }
+  .band h1 { margin: 6px 0 2px; font-size: 26px; font-weight: 650; }
+  .band .sub { opacity: .9; font-size: 14px; }
+  .band .verifiable { margin-top: 12px; display: inline-block; font-size: 12px; background: rgba(255,255,255,.16); padding: 4px 10px; border-radius: 3px; }
+  .body { padding: 28px 40px 40px; }
+  h2 { font-size: 15px; text-transform: uppercase; letter-spacing: .06em; color: var(--accent); border-bottom: 2px solid #eceff2; padding-bottom: 6px; margin: 30px 0 14px; }
+  .cards { display: grid; grid-template-columns: repeat(4, 1fr); gap: 12px; }
+  .card { border: 1px solid #e6eaee; border-radius: 5px; padding: 14px; }
+  .card-v { font-size: 24px; font-weight: 680; color: var(--accent); }
+  .card-l { font-size: 12px; font-weight: 600; margin-top: 2px; }
+  .card-s { font-size: 11px; color: #6b7683; margin-top: 2px; }
+  table { width: 100%; border-collapse: collapse; font-size: 12.5px; }
+  .aiuc td { border-top: 1px solid #eceff2; padding: 12px 8px; vertical-align: top; }
+  .aiuc .dom { width: 40%; }
+  .dom-code { display: inline-block; background: var(--accent); color: #fff; width: 20px; height: 20px; text-align: center; line-height: 20px; border-radius: 3px; font-size: 11px; font-weight: 700; margin-right: 4px; }
+  .dom-covers { color: #6b7683; font-size: 11.5px; margin-top: 4px; }
+  ul.ev { margin: 0; padding-left: 16px; } ul.ev li { margin: 3px 0; }
+  .tbl th { text-align: left; background: #f7f9fb; border-bottom: 1px solid #e6eaee; padding: 8px; font-size: 11px; text-transform: uppercase; letter-spacing: .04em; color: #6b7683; }
+  .tbl td { border-bottom: 1px solid #f0f2f5; padding: 8px; }
+  .mono { font-family: "SFMono-Regular", Consolas, "Liberation Mono", monospace; font-size: 11.5px; }
+  .mut { color: #94a0ac; }
+  .pill { font-size: 10.5px; padding: 1px 7px; border-radius: 10px; font-weight: 600; }
+  .pill-ok { background: #e3f5ea; color: #1a7a44; }
+  .pill-part { background: #fbf1dc; color: #8a6414; }
+  .pill-bad { background: #fbe4e4; color: #a52222; }
+  .verify { background: #f7f9fb; border: 1px solid #e6eaee; border-radius: 5px; padding: 14px 16px; font-size: 12.5px; }
+  .foot { color: #94a0ac; font-size: 11px; margin-top: 24px; border-top: 1px solid #eceff2; padding-top: 12px; }
+  a { color: var(--accent); }
+  @media print { body { background: #fff; } .page { box-shadow: none; margin: 0; max-width: none; } h2 { break-after: avoid; } tr { break-inside: avoid; } }
+</style></head>
+<body><div class="page">
+  <div class="band">
+    <div class="logo">${esc(logo)}</div>
+    <h1>Work Certificate</h1>
+    <div class="sub">${esc(body.period.clientName)} &nbsp;·&nbsp; ${esc(body.period.month)} &nbsp;·&nbsp; ${esc(body.period.fromIso.slice(0, 10))} → ${esc(body.period.toIso.slice(0, 10))}</div>
+    <div class="verifiable">🔒 Cryptographically signed &amp; independently verifiable — structured to AIUC-1</div>
+  </div>
+  <div class="body">
+    <h2>Delivered work this period</h2>
+    <div class="cards">
+      ${metricCard("Outcomes delivered", String(s.workVolumeDelivered), `${s.workVolumeDeclined} declined at sign-off`)}
+      ${metricCard("Automation rate", `${s.automationRatePct}%`, "delivered without human touch")}
+      ${metricCard("Exceptions", String(s.exceptionCount), `${s.humanSignoffCount} human sign-off(s)`)}
+      ${metricCard("SLA adherence", `${s.slaAdherencePct}%`, s.slaTargetPct === null ? "no target set" : `target ${s.slaTargetPct}%`)}
+    </div>
+    <p style="font-size:12.5px;color:#6b7683;margin-top:12px">Exception classification mix — ${classMix}. Every count on this certificate derives from the signed ledger; there is no separate metering system.</p>
+
+    <h2>AIUC-1 control coverage</h2>
+    <table class="aiuc"><tbody>
+      ${body.aiuc1Coverage.map(aiuc1Row).join("\n")}
+    </tbody></table>
+    <p class="mut" style="font-size:11px;margin-top:8px">Categories per the AIUC-1 standard (<a href="${esc(safeUrl(body.standard.source))}">${esc(body.standard.source)}</a>). Evidence statements are factual records from this period's signed ledger.</p>
+
+    <h2>Warranted outcomes (${body.outcomes.length})</h2>
+    <table class="tbl"><thead><tr><th>Work item</th><th>Outcome</th><th>SLA</th><th>Chain tip</th><th>Sign-off</th><th>Class</th><th>Anchor</th></tr></thead>
+      <tbody>${body.outcomes.map(outcomeRow).join("\n")}</tbody></table>
+
+    <h2>Public-witness anchors</h2>
+    ${anchors}
+
+    <h2>How to verify this certificate</h2>
+    <div class="verify">
+      <p style="margin:0 0 8px">${esc(body.verification.instructions)}</p>
+      <div class="mono">issuer: ${esc(body.issuerDid)}</div>
+      <div class="mono">format: ${esc(body.formatVersion)} &nbsp;·&nbsp; issued: ${esc(body.issuedAtIso)}</div>
+    </div>
+
+    <div class="foot">${esc(footer)}. This certificate enumerates the warranted outcomes it is the billing unit for. AIUC-1 categories: ${esc(body.standard.source)}.</div>
+  </div>
+</div></body></html>`;
+}

package/src/certificate/index.ts

@@ -0,0 +1,4 @@
+// @kashscript/hudhud/certificate — the AIUC-1 Work Certificate: DSSE-signed
+// billing/retention document derived from the signed ledger, + an HTML renderer.
+export * from "./certificate";
+export * from "./html";

package/src/did-registry/index.ts

@@ -0,0 +1,11 @@
+// ============================================================================
+// @kashscript/hudhud/did-registry — DID → Ed25519 public-key resolution
+// ----------------------------------------------------------------------------
+// The DID registry the ledger verifies actor signatures against. The interface
+// + in-memory reference live in `@kashscript/attest` (seeded from the same
+// Oreoasis `did-registry.ts` in M1); hudhud re-exports them so ventures reach
+// the registry through the runtime, and add a durable/PDS resolver at swap.
+// ============================================================================
+
+export { InMemoryDidRegistry } from "@kashscript/attest";
+export type { DidRegistry, DidPublicKey } from "@kashscript/attest";

package/src/errors.ts

@@ -0,0 +1,79 @@
+// ============================================================================
+// @kashscript/hudhud — provider-neutral error vocabulary
+// ----------------------------------------------------------------------------
+// Replaces the Oreoasis `@oreoasis/ks-bridge` exception classes with neutral
+// `Hudhud*Error`s. A consuming venture maps them to its own HTTP envelope at
+// its perimeter (ADR-0016 guard b); this package never emits a venture code.
+//
+// Ledger tamper is surfaced by `@kashscript/attest`'s `TamperError` (the ledger
+// runs on attest) — hudhud does not re-declare it.
+// ============================================================================
+
+/** Base class for every error this package throws. */
+export class HudhudError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string) {
+    super(`[${code}] ${message}`);
+    this.name = "HudhudError";
+    this.code = code;
+  }
+}
+
+/** Thrown when an SOP manual cannot be compiled (cycle, malformed goto, empty). */
+export class SopCompilationError extends HudhudError {
+  constructor(message: string) {
+    super("SOP_COMPILATION", message);
+    this.name = "SopCompilationError";
+  }
+}
+
+/** Thrown when an MCP tool call exceeds the hard timeout. */
+export class McpTimeoutError extends HudhudError {
+  readonly timeoutMs: number;
+  constructor(timeoutMs: number, message: string) {
+    super("MCP_TIMEOUT", message);
+    this.name = "McpTimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+/** The security-violation discriminants raised at MCP dispatch time. */
+export type McpSecurityViolationReason =
+  | "TOOL_NOT_ALLOWLISTED"
+  | "ARG_NOT_ALLOWED"
+  | "REQUIRED_ARG_MISSING"
+  | "TOOL_NAME_MALFORMED"
+  | "SCOPE_VIOLATION"
+  | "CIRCUIT_OPEN";
+
+/** Thrown when a dispatch is refused by the allowlist / scope / breaker gates.
+ *  `track` mirrors the Oreoasis four-track wire vocabulary. */
+export class McpSecurityViolationError extends HudhudError {
+  readonly reason: McpSecurityViolationReason;
+  readonly track: "error" | "security";
+  constructor(reason: McpSecurityViolationReason, message: string, track: "error" | "security" = "security") {
+    super("MCP_SECURITY_VIOLATION", message);
+    this.name = "McpSecurityViolationError";
+    this.reason = reason;
+    this.track = track;
+  }
+}
+
+/** Thrown when a required exception classification is missing/invalid — the
+ *  mandatory `failureClass` gate (no "unclassified" state is representable). */
+export class ExceptionClassificationError extends HudhudError {
+  constructor(message: string) {
+    super("EXCEPTION_CLASSIFICATION", message);
+    this.name = "ExceptionClassificationError";
+  }
+}
+
+/** Thrown by the ForensicLedgerService append pipeline (stepIndex mismatch,
+ *  signature-verify failure, store write failure). Ledger *tamper* detected by
+ *  the forensic scan surfaces as attest's `TamperError`, not this. */
+export class LedgerAppendError extends HudhudError {
+  constructor(message: string) {
+    super("LEDGER_APPEND", message);
+    this.name = "LedgerAppendError";
+  }
+}