@kashscript/hudhud 0.1.1 → 0.2.0

package/src/certificate/certificate.ts

@@ -16,9 +16,12 @@ import type { DsseEnvelope, DsseSigner } from "@kashscript/attest";
 
 import type { AnchorRecord } from "../anchor";
 import { FAILURE_CLASSES } from "../exception";
-import type { ExceptionClassificationRecord, FailureClass } from "../exception";
+import type { AnyExceptionClassificationRecord, FailureClass } from "../exception";
 
-export const WORK_CERTIFICATE_FORMAT_VERSION = "kash-work-certificate/1" as const;
+/** /2 (2026-09-23, d43 §4.7): the summary no longer carries `automationRatePct`.
+ *  /1 certificates still verify — including their rate, when present. */
+export const WORK_CERTIFICATE_FORMAT_VERSION = "kash-work-certificate/2" as const;
+export const WORK_CERTIFICATE_FORMAT_VERSION_V1 = "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). */
@@ -53,7 +56,7 @@ export interface CertifiedWorkRecord {
   readonly ledgerRowCount: number;
   readonly ledgerTipHash: string;
   readonly signoff: { readonly operatorDid: string; readonly ledgerStepIndex: number } | null;
-  readonly classification: ExceptionClassificationRecord | null;
+  readonly classification: AnyExceptionClassificationRecord | null;
   readonly anchor: AnchorRecord | null;
 }
 
@@ -75,7 +78,11 @@ export interface BuildWorkCertificateInput {
 export interface WorkCertificateSummary {
   readonly workVolumeDelivered: number;
   readonly workVolumeDeclined: number;
-  readonly automationRatePct: number;
+  /** @deprecated Present only on `kash-work-certificate/1` certificates; never
+   *  minted since /2 — founder decision 2026-09-23 under d43 §4.7 (no
+   *  productivity metric). Still recomputed on verify when present, so an old
+   *  certificate cannot claim a rate its own outcomes do not support. */
+  readonly automationRatePct?: number;
   readonly exceptionCount: number;
   readonly exceptionsByClass: Record<FailureClass, number>;
   readonly humanSignoffCount: number;
@@ -138,26 +145,23 @@ function emptyClassMix(): Record<FailureClass, number> {
 }
 
 function summarize(records: ReadonlyArray<CertifiedWorkRecord>, slaTargetPct: number | undefined): WorkCertificateSummary {
-  let autonomous = 0;
-  let withSignoff = 0;
+  let delivered = 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.status === "declined") declined += 1;
+    else delivered += 1;
     if (r.slaMet) slaMet += 1;
     if (r.anchor !== null) anchored += 1;
-    if (r.classification !== null) exceptionsByClass[r.classification.failureClass] += 1;
+    const fc = r.classification?.failureClass;
+    if (fc !== undefined) exceptionsByClass[fc] += 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,
@@ -179,9 +183,9 @@ function mapAiuc1Coverage(records: ReadonlyArray<CertifiedWorkRecord>, summary:
       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."] };
+        return { ...d, status: "evidenced", evidence: [`${summary.exceptionCount} exception(s) flagged for human review and resolved this period; each classified and signed by a named human (and, where a model was involved, by where the model failed).`, "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.`] };
+        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."] };
       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":
@@ -273,7 +277,6 @@ function recomputeCountsMatch(body: WorkCertificateBody): ReadonlyArray<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;
@@ -288,8 +291,13 @@ function recomputeCountsMatch(body: WorkCertificateBody): ReadonlyArray<string>
   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}`);
+  // /1 certificates carried a rate; it is still held to its own outcomes. /2
+  // never mints one, and a /2 body that claims one is checked all the same.
+  if (s.automationRatePct !== undefined) {
+    const autonomous = o.filter((x) => x.status === "delivered_autonomous").length;
+    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();

package/src/certificate/html.ts

@@ -89,7 +89,7 @@ export function renderWorkCertificateHtml(body: WorkCertificateBody, brand: Work
   .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; }
+  .cards { display: grid; grid-template-columns: repeat(3, 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; }
@@ -124,7 +124,6 @@ export function renderWorkCertificateHtml(body: WorkCertificateBody, brand: Work
     <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>

package/src/exception/index.ts

@@ -10,24 +10,72 @@
 //      bytes (`id` + `timestampIso` minted INTO the signed payload).
 // Ported from the oreoasis-core-host engine (M5); the DST is neutralized, the
 // error reuses hudhud's `ExceptionClassificationError`, id generation inlined.
+//
+// ── Schema v2 (2026-09-23, ECOSYSTEM d43 §4.2) ──────────────────────────────
+// v1 classifies WHERE A MODEL FAILED. d43 classifies HOW A DOER DEVIATED —
+// error · at-risk · reckless · improvement — and an improvement is not a
+// failure, so the second taxonomy is not an extension of the first. v2 carries
+// both as ORTHOGONAL fields on one record: a mandatory `deviationClass` and an
+// optional `failureClass`, present only when a model was involved (`model` is
+// optional too; its absence means "no model", never "unknown"). One record, one
+// operator signature, one fact; the model-failure dataset survives intact.
+// v1 is frozen as a wire format: its DST, schema label and header are unchanged
+// and `verifyClassificationSignature` accepts both versions forever.
+//
+// ── The doer's account (d43: no classification of a person is one-sided) ────
+// The doer may attach their own account, countersigned over the exact body the
+// operator signed. Two guards, both structural rather than policy:
+//   • UNLINKABLE. `attachDoerAccount` never accepts a DID — only the doer's
+//     seed, from which it derives a key for exactly ONE classification
+//     (identity-server's relationship derivation, salted by operator + record
+//     id). The same doer at two establishments — or twice at one — shows two
+//     unrelated DIDs, so the records cannot be joined into a per-person
+//     deviation history (§4.7). The doer, holding the seed, can re-derive each
+//     key and prove authorship of their own records (§4.8).
+//   • DECLINING IS FREE. Not signing is represented by ABSENCE of the
+//     `doerAccount` key — no null, no status, no "invited"/"declined" flag. A
+//     record without an account names no doer at all, so there is nothing to
+//     aggregate against a person; and absence reads identically whether the doer
+//     declined, was never asked, or is an AI helper.
+// Limit, stated: an operator can still type a name into `resolutionSummary`.
+// The schema cannot stop free text; it only refuses to make the join easy.
 // ============================================================================
 
-import { signEvent, verifyEvent } from "@kashscript/identity-core";
+import { parseDid, signEvent, verifyEvent } from "@kashscript/identity-core";
+import { deriveRelationshipSalt, deriveRelationshipSigningKey } from "@kashscript/identity-server";
+import type { Did, RelationshipSigningKey } from "@kashscript/identity-server";
 import { ExceptionClassificationError } from "../errors";
 // Re-export the error this module throws so a consumer can catch it from the
 // same subpath it imports the mandatory gate from.
 export { ExceptionClassificationError } from "../errors";
 
-/** The failure classes. No "unclassified": classification is mandatory. */
+/** The model-failure classes — v1's mandatory class, v2's OPTIONAL one
+ *  (meaningful only when a model was involved). No "unclassified". */
 export const FAILURE_CLASSES = ["judgment", "gap-filling", "ambiguous"] as const;
 export type FailureClass = (typeof FAILURE_CLASSES)[number];
 
-/** DST so a classification signature can't replay as a ledger/attestation sig.
- *  Neutral default; a venture passes its own DST at swap for wire-compat. */
+/** d43 §4.2 — how a doer deviated. Mandatory on v2 records; no default, no
+ *  "unclassified". error → adjust the system, not the person · at-risk → coach
+ *  · reckless → the only punitive branch · improvement → adopt. */
+export const DEVIATION_CLASSES = ["error", "at-risk", "reckless", "improvement"] as const;
+export type DeviationClass = (typeof DEVIATION_CLASSES)[number];
+
+/** v1 signed label (DST) — v1 records verify under it forever. New records are
+ *  v2 (`HUDHUD_EXCEPTION_CLASSIFICATION_V2_DST`). */
 export const HUDHUD_EXCEPTION_CLASSIFICATION_DST = "kash-exception-classification-v1\n" as const;
+/** v1 schema label — frozen; see `EXCEPTION_CLASSIFICATION_SCHEMA_VERSION_V2`. */
 export const EXCEPTION_CLASSIFICATION_SCHEMA_VERSION = "exception-classification/1" as const;
 const SIGN_HEADER = { kind: "exception-classification/1" } as const;
 
+/** v2 labels — registered in `@kashscript/attest/dst` (0.1.7) before first use. */
+export const HUDHUD_EXCEPTION_CLASSIFICATION_V2_DST = "kash-exception-classification-v2\n" as const;
+export const EXCEPTION_CLASSIFICATION_SCHEMA_VERSION_V2 = "exception-classification/2" as const;
+const SIGN_HEADER_V2 = { kind: "exception-classification/2" } as const;
+/** The doer's countersignature DST — so it can never replay as the operator's. */
+export const HUDHUD_EXCEPTION_DOER_ACCOUNT_DST = "kash-exception-doer-account-v1\n" as const;
+const DOER_SIGN_HEADER = { kind: "exception-doer-account/1" } as const;
+const DOER_CONTEXT_PREFIX = "hudhud/exception-doer-account:";
+
 let lastIdMicros = 0;
 function newRecordId(): string {
   let micros = Date.now() * 1000;
@@ -39,9 +87,7 @@ function newRecordId(): string {
   return `exc_${micros.toString(36)}_${hex}`;
 }
 
-/** The mandatory gate — throws `ExceptionClassificationError` if `value` is
- *  absent/empty or not one of the classes. NOT merely the TS type. */
-export function assertFailureClass(value: unknown): asserts value is FailureClass {
+function gateFailureClass(value: unknown): asserts value is FailureClass {
   if (value === undefined || value === null || value === "") {
     throw new ExceptionClassificationError(
       `FAILURE_CLASS_REQUIRED — an exception cannot be resolved without a failureClass (one of ${FAILURE_CLASSES.join(" | ")})`,
@@ -54,6 +100,29 @@ export function assertFailureClass(value: unknown): asserts value is FailureClas
   }
 }
 
+/** The v1 mandatory gate — throws `ExceptionClassificationError` if `value` is
+ *  absent/empty or not one of the classes. NOT merely the TS type.
+ *  @deprecated New records are v2: gate with `assertDeviationClass`; the model
+ *  class is optional there. Kept so existing callers compile unchanged. */
+export function assertFailureClass(value: unknown): asserts value is FailureClass {
+  gateFailureClass(value);
+}
+
+/** The v2 mandatory gate — throws `ExceptionClassificationError` if `value` is
+ *  absent/empty or not one of the four deviation classes. */
+export function assertDeviationClass(value: unknown): asserts value is DeviationClass {
+  if (value === undefined || value === null || value === "") {
+    throw new ExceptionClassificationError(
+      `DEVIATION_CLASS_REQUIRED — a deviation cannot be resolved without a deviationClass (one of ${DEVIATION_CLASSES.join(" | ")})`,
+    );
+  }
+  if (!(DEVIATION_CLASSES as ReadonlyArray<string>).includes(value as string)) {
+    throw new ExceptionClassificationError(
+      `DEVIATION_CLASS_INVALID — deviationClass must be one of ${DEVIATION_CLASSES.join(" | ")} (got ${String(value)})`,
+    );
+  }
+}
+
 export interface ExceptionClassificationInput {
   readonly failureClass: FailureClass;
   readonly failureTag: string;
@@ -100,14 +169,15 @@ function unsignedOf(record: ExceptionClassificationRecord): UnsignedClassificati
   return rest;
 }
 
-/** Mint + sign a classification record (id/timestamp minted into the signed
- *  payload). Throws the mandatory gate if `failureClass` is missing/invalid. */
+/** Mint + sign a v1 classification record (id/timestamp minted into the signed
+ *  payload). Throws the mandatory gate if `failureClass` is missing/invalid.
+ *  @deprecated Mint v2 with `buildSignedDeviationClassification` (d43). */
 export async function buildSignedClassification(
   input: ExceptionClassificationInput,
   operator: { readonly did: string; readonly privateKey: Uint8Array },
   link: { readonly escalationId?: string | null; readonly signoffLedgerStepIndex?: number | null } = {},
 ): Promise<ExceptionClassificationRecord> {
-  assertFailureClass(input.failureClass);
+  gateFailureClass(input.failureClass);
   const unsigned: UnsignedClassification = {
     id: newRecordId(),
     schemaVersion: EXCEPTION_CLASSIFICATION_SCHEMA_VERSION,
@@ -137,15 +207,138 @@ export async function buildSignedClassification(
   };
 }
 
-/** Verify a record's operator signature. Returns false on a well-formed mismatch. */
+// ── Schema v2 ──────────────────────────────────────────────────────────────
+
+export interface DeviationClassificationInput {
+  readonly deviationClass: DeviationClass;
+  /** Where a model failed — ONLY when a model was involved; requires `model`. */
+  readonly failureClass?: FailureClass;
+  readonly deviationTag: string;
+  readonly workflowId: string;
+  /** The rule version the work was judged against (d43: due process in the schema). */
+  readonly sopVersion: string;
+  readonly inputRef: string;
+  readonly contentHash: string;
+  /** Omit for human work. Absence means "no model was involved". */
+  readonly model?: string;
+  /** Requires `model`. */
+  readonly modelVersion?: string;
+  readonly resolutionSummary: string;
+  readonly resolutionActionRefs: ReadonlyArray<string>;
+}
+
+/** The doer's own account, countersigned with a per-classification key. */
+export interface DoerAccount {
+  /** A `did:kash` derived for THIS classification only — never the doer's
+   *  stable identifier. Self-certifying: the verifier needs no lookup. */
+  readonly doerDid: string;
+  readonly account: string;
+  readonly signedEnvelope: ClassificationSignedEnvelope;
+}
+
+export interface ExceptionClassificationRecordV2 {
+  readonly id: string;
+  readonly schemaVersion: typeof EXCEPTION_CLASSIFICATION_SCHEMA_VERSION_V2;
+  readonly timestampIso: string;
+  readonly workflowId: string;
+  readonly sopVersion: string;
+  readonly inputRef: string;
+  readonly contentHash: string;
+  readonly model?: string;
+  readonly modelVersion?: string;
+  readonly deviationClass: DeviationClass;
+  readonly failureClass?: FailureClass;
+  readonly deviationTag: string;
+  readonly operatorDid: string;
+  readonly resolutionSummary: string;
+  readonly resolutionActionRefs: ReadonlyArray<string>;
+  readonly escalationId: string | null;
+  readonly signoffLedgerStepIndex: number | null;
+  /** The operator's signature over every field above. */
+  readonly signedEnvelope: ClassificationSignedEnvelope;
+  /** Present only when the doer signed. Absence is the ONLY representation of
+   *  declining — see the module header. */
+  readonly doerAccount?: DoerAccount;
+}
+
+export type AnyExceptionClassificationRecord = ExceptionClassificationRecord | ExceptionClassificationRecordV2;
+
+export function isV2Classification(record: AnyExceptionClassificationRecord): record is ExceptionClassificationRecordV2 {
+  return record.schemaVersion === EXCEPTION_CLASSIFICATION_SCHEMA_VERSION_V2;
+}
+
+type UnsignedClassificationV2 = Omit<ExceptionClassificationRecordV2, "signedEnvelope" | "doerAccount">;
+function unsignedOfV2(record: ExceptionClassificationRecordV2): UnsignedClassificationV2 {
+  const { signedEnvelope: _sig, doerAccount: _doer, ...rest } = record;
+  return rest;
+}
+
+/** Mint + sign a v2 (d43) classification. Gates: `deviationClass` mandatory;
+ *  `failureClass` only with `model`; `model`/`modelVersion` non-empty when
+ *  present and OMITTED (never "") when there was no model. */
+export async function buildSignedDeviationClassification(
+  input: DeviationClassificationInput,
+  operator: { readonly did: string; readonly privateKey: Uint8Array },
+  link: { readonly escalationId?: string | null; readonly signoffLedgerStepIndex?: number | null } = {},
+): Promise<ExceptionClassificationRecordV2> {
+  assertDeviationClass(input.deviationClass);
+  if (input.model !== undefined && (typeof input.model !== "string" || input.model === "")) {
+    throw new ExceptionClassificationError("MODEL_INVALID — `model`, when present, must be non-empty; omit it for work no model touched");
+  }
+  if (input.modelVersion !== undefined && (input.model === undefined || typeof input.modelVersion !== "string" || input.modelVersion === "")) {
+    throw new ExceptionClassificationError("MODEL_VERSION_INVALID — `modelVersion` must be non-empty and requires `model`");
+  }
+  if (input.failureClass !== undefined) {
+    gateFailureClass(input.failureClass);
+    if (input.model === undefined) {
+      throw new ExceptionClassificationError("FAILURE_CLASS_WITHOUT_MODEL — failureClass classifies where a model failed; it requires `model`");
+    }
+  }
+  const unsigned: UnsignedClassificationV2 = {
+    id: newRecordId(),
+    schemaVersion: EXCEPTION_CLASSIFICATION_SCHEMA_VERSION_V2,
+    timestampIso: new Date().toISOString(),
+    workflowId: input.workflowId,
+    sopVersion: input.sopVersion,
+    inputRef: input.inputRef,
+    contentHash: input.contentHash,
+    ...(input.model !== undefined ? { model: input.model } : {}),
+    ...(input.modelVersion !== undefined ? { modelVersion: input.modelVersion } : {}),
+    deviationClass: input.deviationClass,
+    ...(input.failureClass !== undefined ? { failureClass: input.failureClass } : {}),
+    deviationTag: input.deviationTag,
+    operatorDid: operator.did,
+    resolutionSummary: input.resolutionSummary,
+    resolutionActionRefs: [...input.resolutionActionRefs],
+    escalationId: link.escalationId ?? null,
+    signoffLedgerStepIndex: link.signoffLedgerStepIndex ?? null,
+  };
+  const signed = await signEvent(SIGN_HEADER_V2, unsigned, operator.privateKey, {
+    dst: HUDHUD_EXCEPTION_CLASSIFICATION_V2_DST,
+    encoding: "hex",
+    kid: operator.did,
+  });
+  return {
+    ...unsigned,
+    signedEnvelope: { alg: "ed25519", sig: signed.sig, dst: HUDHUD_EXCEPTION_CLASSIFICATION_V2_DST, kid: operator.did },
+  };
+}
+
+/** Verify a record's operator signature — v1 or v2, dispatched on
+ *  `schemaVersion`. Returns false on a well-formed mismatch. The doer's
+ *  account, if any, is outside the operator's bytes: check it with
+ *  `verifyDoerAccount`. */
 export async function verifyClassificationSignature(
-  record: ExceptionClassificationRecord,
+  record: AnyExceptionClassificationRecord,
   operatorPublicKey: Uint8Array,
 ): Promise<boolean> {
+  const v2 = isV2Classification(record);
+  // v2 pins its DST: a v2 body is never accepted under any other tag.
+  if (v2 && record.signedEnvelope.dst !== HUDHUD_EXCEPTION_CLASSIFICATION_V2_DST) return false;
   return verifyEvent(
     {
-      header: SIGN_HEADER,
-      body: unsignedOf(record),
+      header: v2 ? SIGN_HEADER_V2 : SIGN_HEADER,
+      body: v2 ? unsignedOfV2(record) : unsignedOf(record as ExceptionClassificationRecord),
       signature: {
         alg: "ed25519",
         sig: record.signedEnvelope.sig,
@@ -158,27 +351,111 @@ export async function verifyClassificationSignature(
   );
 }
 
+// ── The doer's account ─────────────────────────────────────────────────────
+
+function doerSignedBody(record: ExceptionClassificationRecordV2, doerDid: string, account: string) {
+  return { subject: unsignedOfV2(record), doerDid, account };
+}
+
+/** Derive the doer's signing key for exactly ONE classification. Deterministic,
+ *  so the doer (holding the seed) can re-derive it and prove a record is theirs;
+ *  unlinkable to every other classification without the seed. */
+export async function deriveDoerAccountKey(
+  masterSeed: Uint8Array,
+  record: Pick<ExceptionClassificationRecordV2, "id" | "operatorDid">,
+): Promise<RelationshipSigningKey> {
+  if (!(masterSeed instanceof Uint8Array) || masterSeed.length < 32) {
+    throw new ExceptionClassificationError("DOER_SEED_INVALID — the doer's master seed must be at least 32 bytes");
+  }
+  const relationshipSalt = await deriveRelationshipSalt({
+    requesterDid: record.operatorDid as Did,
+    contextLabel: DOER_CONTEXT_PREFIX + record.id,
+  });
+  return deriveRelationshipSigningKey({ masterSeed, relationshipSalt });
+}
+
+/** Attach the doer's own account + countersignature over the exact bytes the
+ *  operator signed. Takes the doer's SEED, never a DID — so no caller can write
+ *  a stable identifier into the record. Declining = never calling this. */
+export async function attachDoerAccount(
+  record: ExceptionClassificationRecordV2,
+  doer: { readonly masterSeed: Uint8Array },
+  account: string,
+): Promise<ExceptionClassificationRecordV2> {
+  if (!isV2Classification(record)) {
+    throw new ExceptionClassificationError("DOER_ACCOUNT_REQUIRES_V2 — a doer account attaches to an exception-classification/2 record");
+  }
+  if (record.doerAccount !== undefined) {
+    throw new ExceptionClassificationError("DOER_ACCOUNT_ALREADY_ATTACHED — a record carries at most one doer account");
+  }
+  if (typeof account !== "string" || account.trim() === "") {
+    throw new ExceptionClassificationError("DOER_ACCOUNT_EMPTY — an attached account must say something; to decline, attach nothing");
+  }
+  const key = await deriveDoerAccountKey(doer.masterSeed, record);
+  const signed = await signEvent(DOER_SIGN_HEADER, doerSignedBody(record, key.did, account), key.privateKey, {
+    dst: HUDHUD_EXCEPTION_DOER_ACCOUNT_DST,
+    encoding: "hex",
+    kid: key.did,
+  });
+  return {
+    ...record,
+    doerAccount: {
+      doerDid: key.did,
+      account,
+      signedEnvelope: { alg: "ed25519", sig: signed.sig, dst: HUDHUD_EXCEPTION_DOER_ACCOUNT_DST, kid: key.did },
+    },
+  };
+}
+
+/** Verify the doer's countersignature offline (the key comes from the
+ *  self-certifying `doerDid`). False when absent, tampered, or re-bound to a
+ *  different classification. Absence is not a failure of the doer — callers
+ *  must not treat `false`-because-absent as a mark (check `doerAccount` first). */
+export async function verifyDoerAccount(record: ExceptionClassificationRecordV2): Promise<boolean> {
+  const d = record.doerAccount;
+  if (d === undefined) return false;
+  if (d.signedEnvelope.dst !== HUDHUD_EXCEPTION_DOER_ACCOUNT_DST || d.signedEnvelope.kid !== d.doerDid) return false;
+  let publicKey: Uint8Array;
+  try {
+    publicKey = parseDid(d.doerDid);
+  } catch {
+    return false;
+  }
+  return verifyEvent(
+    {
+      header: DOER_SIGN_HEADER,
+      body: doerSignedBody(record, d.doerDid, d.account),
+      signature: { alg: "ed25519", sig: d.signedEnvelope.sig, dst: d.signedEnvelope.dst, encoding: "hex", kid: d.signedEnvelope.kid },
+    },
+    publicKey,
+  );
+}
+
 // ── Store (append-only) ────────────────────────────────────────────────────
 
-export interface ExceptionClassificationStore {
-  append(record: ExceptionClassificationRecord): Promise<void>;
-  history(): Promise<ReadonlyArray<ExceptionClassificationRecord>>;
-  latest(): Promise<ExceptionClassificationRecord | null>;
-  byWorkflow(workflowId: string): Promise<ReadonlyArray<ExceptionClassificationRecord>>;
+/** Generic over the record version; defaults to v1 so existing implementers
+ *  compile unchanged. */
+export interface ExceptionClassificationStore<R extends AnyExceptionClassificationRecord = ExceptionClassificationRecord> {
+  append(record: R): Promise<void>;
+  history(): Promise<ReadonlyArray<R>>;
+  latest(): Promise<R | null>;
+  byWorkflow(workflowId: string): Promise<ReadonlyArray<R>>;
 }
 
-export class InMemoryExceptionClassificationStore implements ExceptionClassificationStore {
-  private readonly rows: ExceptionClassificationRecord[] = [];
-  async append(record: ExceptionClassificationRecord): Promise<void> {
+export class InMemoryExceptionClassificationStore<R extends AnyExceptionClassificationRecord = ExceptionClassificationRecord>
+  implements ExceptionClassificationStore<R>
+{
+  private readonly rows: R[] = [];
+  async append(record: R): Promise<void> {
     this.rows.push(record);
   }
-  async history(): Promise<ReadonlyArray<ExceptionClassificationRecord>> {
+  async history(): Promise<ReadonlyArray<R>> {
     return [...this.rows];
   }
-  async latest(): Promise<ExceptionClassificationRecord | null> {
+  async latest(): Promise<R | null> {
     return this.rows.length === 0 ? null : this.rows[this.rows.length - 1]!;
   }
-  async byWorkflow(workflowId: string): Promise<ReadonlyArray<ExceptionClassificationRecord>> {
+  async byWorkflow(workflowId: string): Promise<ReadonlyArray<R>> {
     return this.rows.filter((r) => r.workflowId === workflowId);
   }
 }
@@ -187,18 +464,18 @@ export class InMemoryExceptionClassificationStore implements ExceptionClassifica
 
 export const EXCEPTION_DATASET_FORMAT_VERSION = "kash-exception-dataset/1" as const;
 
-export interface ExceptionClassificationDatasetExport {
+export interface ExceptionClassificationDatasetExport<R extends AnyExceptionClassificationRecord = ExceptionClassificationRecord> {
   readonly formatVersion: string;
   readonly exportedAtIso: string;
   readonly count: number;
-  readonly records: ReadonlyArray<ExceptionClassificationRecord>;
+  readonly records: ReadonlyArray<R>;
 }
 
 /** Bundle the dataset for hand-off (records carry their own signatures). */
-export function exportExceptionClassificationDataset(
-  records: ReadonlyArray<ExceptionClassificationRecord>,
+export function exportExceptionClassificationDataset<R extends AnyExceptionClassificationRecord = ExceptionClassificationRecord>(
+  records: ReadonlyArray<R>,
   exportedAtIso: string = new Date().toISOString(),
-): ExceptionClassificationDatasetExport {
+): ExceptionClassificationDatasetExport<R> {
   return { formatVersion: EXCEPTION_DATASET_FORMAT_VERSION, exportedAtIso, count: records.length, records: [...records] };
 }
 
@@ -221,15 +498,17 @@ function emptyClassMix(): Record<FailureClass, number> {
   return mix;
 }
 
-/** Class mix + per-workflow (+ over-time) exception counts (the rate numerator). */
+/** Model-failure class mix + per-workflow (+ over-time) exception counts. A v2
+ *  record counts toward `classMix` only when it carries a `failureClass`.
+ *  Deliberately NO deviation-class mix and nothing per doer (d43 §4.7). */
 export function computeExceptionClassificationStats(
-  records: ReadonlyArray<ExceptionClassificationRecord>,
+  records: ReadonlyArray<AnyExceptionClassificationRecord>,
 ): ExceptionClassificationStats {
   const classMix = emptyClassMix();
   const perWorkflow = new Map<string, number>();
   const perWfMonth = new Map<string, number>();
   for (const r of records) {
-    classMix[r.failureClass] += 1;
+    if (r.failureClass !== undefined) classMix[r.failureClass] += 1;
     perWorkflow.set(r.workflowId, (perWorkflow.get(r.workflowId) ?? 0) + 1);
     const key = `${r.workflowId} ${r.timestampIso.slice(0, 7)}`;
     perWfMonth.set(key, (perWfMonth.get(key) ?? 0) + 1);

package/src/index.ts

@@ -30,4 +30,4 @@ export * from "./identity";
 export * from "./runtime";
 
 /** The hudhud protocol/package version (M5 initial cut). */
-export const HUDHUD_VERSION = "0.1.0" as const;
+export const HUDHUD_VERSION = "0.1.1" as const;