@kashscript/hudhud 0.1.0 → 0.2.0

package/src/exception/index.ts

@@ -10,21 +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;
@@ -36,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(" | ")})`,
@@ -51,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;
@@ -97,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,
@@ -134,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,
@@ -155,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);
   }
 }
@@ -184,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] };
 }
 
@@ -218,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;

package/src/ledger/writer.ts

@@ -38,14 +38,26 @@ export interface HostActorSigner {
   sign(payload: LedgerSignaturePayload): Promise<string>;
 }
 
-/** Build a HostActorSigner from a raw Ed25519 private key. `actorDid` must be a
- *  did:kash and be registered in the DidRegistry the service verifies against. */
+/** Default DID acceptance policy: the canonical `did:kash:<base58btc>` shape
+ *  (identity-core `DID_KASH_RE` / attest `KASH_DID_PATTERN`). A consumer whose
+ *  DID method-specific-ids are STRUCTURED (e.g. hierarchical role DIDs such as
+ *  `did:kash:oreoasis:kernel:host`) injects its own validator — DID-format is an
+ *  identity-method policy the CONSUMER owns; the ledger's hard gates stay
+ *  registry-resolution + signature-verification, not string shape. */
+const isCanonicalKashDid = (did: string): boolean => KASH_DID_PATTERN.test(did);
+
+/** Build a HostActorSigner from a raw Ed25519 private key. `actorDid` must be
+ *  accepted by `isValidActorDid` (default: canonical did:kash) and be registered
+ *  in the DidRegistry the service verifies against. */
 export function createEd25519HostSigner(opts: {
   readonly actorDid: string;
   readonly actorClass: ActorClass;
   readonly privateKey: Uint8Array;
+  /** Override the DID acceptance policy (default: canonical `did:kash`). */
+  readonly isValidActorDid?: (did: string) => boolean;
 }): HostActorSigner {
-  if (!KASH_DID_PATTERN.test(opts.actorDid)) {
+  const isValidActorDid = opts.isValidActorDid ?? isCanonicalKashDid;
+  if (!isValidActorDid(opts.actorDid)) {
     throw new LedgerAppendError("host signer actorDid is not a valid did:kash:… identifier");
   }
   return {
@@ -83,18 +95,26 @@ export interface ForensicLedgerServiceDeps {
   readonly didRegistry: DidRegistry;
   /** Required only for `appendActorTransition` (the self-signing path). */
   readonly hostSigner?: HostActorSigner;
+  /** DID acceptance policy for `actorDid` (default: canonical `did:kash`).
+   *  DID-format is an identity-method policy the CONSUMER owns; the ledger's
+   *  hard gates remain registry-resolution + signature-verification. */
+  readonly isValidActorDid?: (did: string) => boolean;
 }
 
 export class ForensicLedgerService {
   constructor(private readonly deps: ForensicLedgerServiceDeps) {}
 
+  private isValidActorDid(did: string): boolean {
+    return (this.deps.isValidActorDid ?? isCanonicalKashDid)(did);
+  }
+
   /** Append a caller-pre-signed transition. @throws LedgerAppendError on any
    *  validation / signature / store failure. */
   async appendTransitionLog(input: AppendTransitionLogInput): Promise<AppendedLedgerBlock> {
     if (typeof input.sessionId !== "string" || input.sessionId.length === 0) {
       throw new LedgerAppendError("sessionId is required");
     }
-    if (typeof input.actorDid !== "string" || !KASH_DID_PATTERN.test(input.actorDid)) {
+    if (typeof input.actorDid !== "string" || !this.isValidActorDid(input.actorDid)) {
       throw new LedgerAppendError("actorDid must be a valid did:kash:… identifier");
     }
     if (typeof input.signature !== "string" || input.signature.length === 0) {

package/src/runtime/escalation.ts

@@ -34,12 +34,17 @@ import { resolvePreviousBlockHash } from "../ledger/store";
 import type { LedgerStore } from "../ledger/store";
 import type { ForensicLedgerService } from "../ledger/writer";
 
-// Both identities are ordinary `did:kash` keys (base58btc, attest's
-// KASH_DID_PATTERN) so the operator sign-off is a first-class ledger actor.
-// The two-key guarantee comes from DISTINCTNESS, not a DID namespace: the agent
-// key is the one the host holds; the operator key is SEPARATE, so the host
-// cannot mint the operator (invoker) signature. Enforced below by requiring
-// agent.did ≠ operator.did (their derived DIDs differ because their keys do).
+// Both identities are `did:kash` keys so the operator sign-off is a first-class
+// ledger actor. The two-key guarantee comes from DISTINCTNESS, not a DID
+// namespace: the agent key is the one the host holds; the operator key is
+// SEPARATE, so the host cannot mint the operator (invoker) signature. Enforced
+// below by requiring agent.did ≠ operator.did (their derived DIDs differ because
+// their keys do). The DID-STRING shape is an identity-method policy the consumer
+// owns (`isValidDid`, default canonical); it is NOT a security boundary here.
+
+/** Default DID acceptance policy: the canonical `did:kash:<base58btc>` shape.
+ *  Consumers with structured DIDs (e.g. `did:kash:operator:…`) inject their own. */
+const isCanonicalKashDid = (did: string): boolean => KASH_DID_PATTERN.test(did);
 
 export type EscalationErrorCode =
   | "AGENT_DID_INVALID"
@@ -80,6 +85,9 @@ export interface BuildHumanApprovalEnvelopeInput {
   /** The OPERATOR identity — the SEPARATE human key. */
   readonly operator: { readonly did: string; readonly privateKey: Uint8Array; readonly publicKey: Uint8Array };
   readonly ttlMs?: number;
+  /** Override the DID acceptance policy for agent/operator `did` (default:
+   *  canonical `did:kash`). */
+  readonly isValidDid?: (did: string) => boolean;
 }
 
 /**
@@ -88,10 +96,11 @@ export interface BuildHumanApprovalEnvelopeInput {
  * operator), so forging human judgment would require the operator private key.
  */
 export async function buildHumanApprovalEnvelope(input: BuildHumanApprovalEnvelopeInput): Promise<SignedActionEnvelope> {
-  if (!KASH_DID_PATTERN.test(input.agent.did)) {
+  const isValidDid = input.isValidDid ?? isCanonicalKashDid;
+  if (!isValidDid(input.agent.did)) {
     throw new EscalationError("AGENT_DID_INVALID", "agent.did must be a valid did:kash identifier");
   }
-  if (!KASH_DID_PATTERN.test(input.operator.did)) {
+  if (!isValidDid(input.operator.did)) {
     throw new EscalationError("OPERATOR_DID_INVALID", "operator.did must be a valid did:kash identifier");
   }
   if (input.agent.did === input.operator.did) {
@@ -145,6 +154,8 @@ export interface AppendOperatorSignoffInput {
   /** MANDATORY classification (required `failureClass`, no "unclassified"). */
   readonly classification: ExceptionClassificationInput;
   readonly exceptionClassificationStore: ExceptionClassificationStore;
+  /** Override the DID acceptance policy for operator `did` (default: canonical). */
+  readonly isValidDid?: (did: string) => boolean;
 }
 
 /**
@@ -155,7 +166,8 @@ export interface AppendOperatorSignoffInput {
 export async function appendOperatorSignoff(
   input: AppendOperatorSignoffInput,
 ): Promise<{ stepIndex: number; classification: ExceptionClassificationRecord }> {
-  if (!KASH_DID_PATTERN.test(input.operator.did)) {
+  const isValidDid = input.isValidDid ?? isCanonicalKashDid;
+  if (!isValidDid(input.operator.did)) {
     throw new EscalationError("OPERATOR_DID_INVALID", "operator.did must be a valid did:kash identifier");
   }
   assertFailureClass(input.classification.failureClass);

package/src/sop/compiler.ts

@@ -62,7 +62,7 @@ export async function compileSopStructural(input: CompileSopInput): Promise<Comp
   const lines = input.sopText.split(/\r?\n/);
 
   if (input.sopText.trim().length === 0) {
-    throw new SopCompilationError("SOP text is empty or whitespace-only — at least one step required");
+    throw new SopCompilationError("SOP text is empty or whitespace-only — at least one step required", { kind: "empty" });
   }
 
   const nodes: TaskDagNode[] = [];
@@ -76,6 +76,7 @@ export async function compileSopStructural(input: CompileSopInput): Promise<Comp
   if (nodes.length === 0) {
     throw new SopCompilationError(
       "No numbered/bulleted steps detected — structural compiler requires `1.` / `-` / `*` / `•` prefixes",
+      { kind: "no-steps" },
     );
   }