scripts/companion/session.mjs

import { createHash, randomBytes } from "node:crypto";
import {
  classify,
  effectiveMode,
  scan,
  searchVariants,
  untrustedNotice,
} from "./policy.mjs";
import {
  decideCloseout,
  decideError,
  decideFetch,
  decideStartup,
  sessionBudgets,
} from "./default-policy.mjs";
const digest = (x) =>
  createHash("sha256").update(JSON.stringify(x)).digest("hex");
const bindingFor = ({ origin, identity, session }) => ({
  origin,
  identity,
  session_hash: digest(["kfa-session", session]),
});
const fields = {
  problem: [
    "title",
    "body",
    "observed_symptom",
    "context",
    "product",
    "symptom_signature",
    "candidate_solution",
    "provenance",
  ],
  solution: [
    "problem_id",
    "title",
    "body",
    "proposed_action",
    "applicability",
    "limitations",
    "success_criteria",
    "product",
    "provenance",
  ],
  outcome: [
    "problem_id",
    "solution_id",
    "solution_revision",
    "signal",
    "executed",
    "actual_action",
    "observation",
    "criterion",
    "environment",
    "provenance",
  ],
  failure: [
    "report_kind",
    "target_id",
    "target_revision",
    "approach",
    "observation",
    "affected_versions",
    "provenance",
  ],
  discussion: [
    "title",
    "body",
    "discussion_type",
    "benchmark_task_id",
    "benchmark_id",
    "provenance",
  ],
  reply: ["discussion_id", "body", "provenance"],
  ack: ["inbox_item_id"],
  benchmark: [
    "benchmark_task_id",
    "result",
    "summary",
    "approach_summary",
    "environment",
    "evidence_reference",
    "provenance",
  ],
  edit_problem: [
    "id",
    "expected_revision",
    "title",
    "body",
    "observed_symptom",
    "context",
    "product",
    "symptom_signature",
    "provenance",
  ],
  edit_solution: [
    "id",
    "expected_revision",
    "title",
    "body",
    "proposed_action",
    "applicability",
    "limitations",
    "success_criteria",
    "product",
    "provenance",
  ],
};
function route(kind, p) {
  const id = (x) => encodeURIComponent(x ?? "");
  return {
    problem: { method: "POST", path: "/api/problems" },
    solution: { method: "POST", path: "/api/solutions" },
    outcome: { method: "POST", path: `/api/solutions/${id(p.solution_id)}/outcomes` },
    failure: { method: "POST", path: "/api/feedback-reports" },
    discussion: { method: "POST", path: "/api/discussions" },
    reply: { method: "POST", path: `/api/discussions/${id(p.discussion_id)}/replies` },
    ack: { method: "POST", path: `/api/inbox/${id(p.inbox_item_id)}/ack` },
    benchmark: { method: "POST", path: `/api/v1/benchmark-tasks/${id(p.benchmark_task_id)}/attempts` },
    edit_problem: { method: "PATCH", path: `/api/problems/${id(p.id)}` },
    edit_solution: { method: "PATCH", path: `/api/solutions/${id(p.id)}` },
  }[kind];
}
function requestPayload(kind, payload) {
  if (["edit_problem", "edit_solution"].includes(kind)) {
    const { id, ...rest } = payload;
    return rest;
  }
  return payload;
}
export function newLedger(binding) {
  return {
    version: 2,
    binding: bindingFor(binding),
    nonce: randomBytes(16).toString("hex"),
    started: false,
    unavailable: false,
    availability: "unknown",
    authentication: "unknown",
    failure_states: [],
    lifecycle: { startup_searches: 0, error_groups: {}, fetches: 0 },
    queries: {},
    fetched: [],
    consulted: [],
    closeout: {
      candidates: 0,
      dedup: [],
      pending: [],
      created: [],
      revisioned: [],
      held: [],
      deferred: [],
    },
    operations: {},
    metrics: {
      queries: 0,
      cache_hits: 0,
      fetched: 0,
      published: 0,
      duplicates: 0,
      outages: 0,
      blocked: 0,
      response_bytes: 0,
      latency_ms: 0,
    },
  };
}

export function sessionReceipt(ledger) {
  return {
    agent: ledger.binding.identity,
    session_hash: ledger.binding.session_hash,
    availability: ledger.availability,
    authentication: ledger.authentication,
    searches: ledger.metrics.queries,
    fetched: ledger.metrics.fetched,
    consulted: ledger.consulted,
    closeout: {
      candidates: ledger.closeout.candidates,
      created: ledger.closeout.created.length,
      revisioned: ledger.closeout.revisioned.length,
      held: ledger.closeout.held.length,
      deferred: ledger.closeout.deferred.length,
    },
    failure: ledger.failure_states.at(-1) ?? (ledger.unavailable ? "FAIL_OPEN" : null),
    latency_ms: ledger.metrics.latency_ms,
    response_bytes: ledger.metrics.response_bytes,
  };
}
export class Companion {
  constructor({ config = {}, ledger, save = () => {}, transport }) {
    this.config = config;
    this.mode = effectiveMode(config.mode, config.restriction);
    this.ledger = ledger;
    this.save = save;
    this.transport = transport;
    const legacyBinding = {
      origin: config.origin,
      identity: config.identity,
      session: config.session,
    };
    const migratedLegacyBinding =
      JSON.stringify(ledger.binding) === JSON.stringify(legacyBinding);
    if (migratedLegacyBinding) {
      ledger.version = 2;
      ledger.binding = bindingFor(config);
    }
    ledger.started ??= false;
    ledger.unavailable ??= false;
    ledger.availability ??= "unknown";
    ledger.authentication ??= "unknown";
    ledger.failure_states ??= [];
    ledger.lifecycle ??= { startup_searches: 0, error_groups: {}, fetches: 0 };
    ledger.lifecycle.error_groups ??= {};
    ledger.lifecycle.startup_searches ??= 0;
    ledger.lifecycle.fetches ??= 0;
    ledger.queries ??= {};
    ledger.fetched ??= [];
    ledger.consulted ??= [];
    ledger.operations ??= {};
    ledger.closeout ??= {};
    Object.assign(ledger.closeout, {
      candidates: ledger.closeout.candidates ?? 0,
      dedup: ledger.closeout.dedup ?? [],
      pending: ledger.closeout.pending ?? [],
      created: ledger.closeout.created ?? [],
      revisioned: ledger.closeout.revisioned ?? [],
      held: ledger.closeout.held ?? [],
      deferred: ledger.closeout.deferred ?? [],
    });
    ledger.metrics ??= {};
    Object.assign(ledger.metrics, {
      queries: ledger.metrics.queries ?? 0,
      cache_hits: ledger.metrics.cache_hits ?? 0,
      fetched: ledger.metrics.fetched ?? 0,
      published: ledger.metrics.published ?? 0,
      duplicates: ledger.metrics.duplicates ?? 0,
      outages: ledger.metrics.outages ?? 0,
      blocked: ledger.metrics.blocked ?? 0,
      response_bytes: ledger.metrics.response_bytes ?? 0,
      latency_ms: ledger.metrics.latency_ms ?? 0,
    });
    if (
      JSON.stringify(ledger.binding) !==
      JSON.stringify(bindingFor(config))
    )
      throw Error("SESSION_BINDING_MISMATCH");
    if (migratedLegacyBinding) this.persist();
  }
  persist() {
    this.save(this.ledger);
  }
  failOpen(state) {
    if (!this.ledger.failure_states.includes(state))
      this.ledger.failure_states.push(state);
    this.ledger.failure_states = this.ledger.failure_states.slice(-8);
    this.persist();
  }
  markAuthUnavailable() {
    this.ledger.unavailable = true;
    this.ledger.availability = "unavailable";
    this.ledger.authentication = "unavailable";
    this.failOpen("KFA_AUTH_UNAVAILABLE");
  }
  markIdentityUnavailable() {
    this.ledger.unavailable = true;
    this.ledger.availability = "unavailable";
    this.ledger.authentication = "identity_mismatch";
    this.failOpen("IDENTITY_MISMATCH");
  }
  async request(method, path, body, operation) {
    if (this.mode === "off") return { status: 0, error: "MODE_OFF" };
    if (this.ledger.unavailable) return { status: 0, error: "KFA_UNAVAILABLE" };
    const started = Date.now();
    try {
      const r = await this.transport(method, path, body, operation);
      this.ledger.metrics.response_bytes += r.bytes ?? 0;
      this.ledger.metrics.latency_ms += Date.now() - started;
      if (r.status >= 500 || r.status === 429) throw Error("unavailable");
      if (r.status === 401 || r.status === 403) {
        this.markAuthUnavailable();
        return { ...r, error: "KFA_AUTH_UNAVAILABLE" };
      }
      return r;
    } catch {
      this.ledger.unavailable = true;
      this.ledger.availability = "unavailable";
      this.ledger.metrics.outages++;
      this.failOpen(method === "GET" ? "KFA_UNAVAILABLE" : "PUBLICATION_FAILURE_DEFERRED");
      this.persist();
      return {
        status: 0,
        error: method === "GET" ? "KFA_UNAVAILABLE" : "TRANSPORT_UNKNOWN",
      };
    }
  }
  async start() {
    if (this.mode === "off") {
      this.ledger.availability = "off";
      this.ledger.authentication = "not_checked";
      this.persist();
      return { mode: this.mode };
    }
    if (this.ledger.started) return { mode: this.mode, already_started: true };
    this.ledger.started = true;
    this.persist();
    if (!this.config.credentialAvailable) {
      this.ledger.availability = "available";
      this.ledger.authentication = "missing";
      this.ledger.unavailable = true;
      this.failOpen("KFA_AUTH_UNAVAILABLE");
      this.persist();
      return { mode: this.mode, authenticated: false };
    }
    const who = await this.request("GET", "/api/whoami");
    if (who.status !== 200 || who.data?.authenticated !== true) {
      this.markAuthUnavailable();
      this.persist();
      return {
        mode: this.mode,
        authenticated: false,
        error: who.error ?? "AUTH_UNAVAILABLE",
      };
    }
    const s = who.data.subject;
    if (
      (this.config.agent_id && s?.id !== this.config.agent_id) ||
      (this.config.operator_id &&
        who.data.operator?.id !== this.config.operator_id)
    ) {
      this.markIdentityUnavailable();
      return { error: "IDENTITY_MISMATCH" };
    }
    this.ledger.identity = {
      id: s.id,
      operator_id: who.data.operator.id,
      epoch: who.data.write_epoch,
    };
    this.ledger.availability = "available";
    this.ledger.authentication = "authenticated";
    this.persist();
    const inbox = await this.request("GET", "/api/inbox?limit=10");
    return {
      mode: this.mode,
      identity: this.ledger.identity,
      inbox: {
        status: inbox.status,
        count: Array.isArray(inbox.data?.items) ? inbox.data.items.length : 0,
      },
      notice: untrustedNotice,
      acknowledged: false,
    };
  }
  async search(trigger) {
    const variants = searchVariants(trigger);
    if (!variants.length) return { error: "QUERY_REQUIRED" };
    for (const v of variants) if (scan(v.q)) return { error: "UNSAFE_QUERY" };
    const key = digest(variants);
    if (this.ledger.queries[key]) {
      this.ledger.metrics.cache_hits++;
      this.persist();
      return { cached: true, query_key: key, ...this.ledger.queries[key] };
    }
    if (Object.keys(this.ledger.queries).length >= 24)
      return { error: "SEARCH_BOUND" };
    const results = [];
    let complete = true;
    for (const v of variants) {
      const r = await this.request(
        "GET",
        "/api/search?" +
          new URLSearchParams({ q: v.q, mode: v.mode, limit: "5" }),
      );
      if (r.status !== 200) {
        complete = false;
        break;
      }
      this.ledger.metrics.queries++;
      const items =
        r.data?.candidates ?? r.data?.results ?? r.data?.items ?? [];
      // Persist IDs only. Community text stays out of the operational ledger.
      const refs = items
        .map((x) => ({
          id: x.id ?? x.entity_id,
          type: x.type ?? x.kind,
          revision: x.revision,
        }))
        .filter((x) => x.id)
        .slice(0, 5);
      results.push(...refs);
      if (refs.length) break;
    }
    const result = {
      complete,
      records: results.slice(0, 5),
      notice: untrustedNotice,
    };
    this.ledger.queries[key] = result;
    this.persist();
    return { query_key: key, ...result };
  }
  async fetch(kind, id) {
    const plural = {
      problem: "problems",
      solution: "solutions",
      discussion: "discussions",
      attempt: "attempts",
      outcome: "outcomes",
      benchmark: "benchmarks",
      benchmark_task: "benchmark-tasks",
    };
    if (!plural[kind] || !/^[A-Za-z0-9_-]{1,100}$/.test(id))
      return { error: "INVALID_RECORD" };
    const key = kind + ":" + id;
    if (this.ledger.fetched.includes(key))
      return { cached: true, record_id: id };
    if (this.ledger.fetched.length >= 32) return { error: "FETCH_BOUND" };
    const r = await this.request(
      "GET",
      kind === "benchmark" || kind === "benchmark_task"
        ? `/api/v1/${plural[kind]}/${id}`
        : `/${plural[kind]}/${id}.json`,
    );
    if (r.status === 200) {
      this.ledger.fetched.push(key);
      this.ledger.consulted.push({
        kind,
        id,
        revision: r.data?.revision ?? r.data?.result?.revision,
      });
      this.ledger.metrics.fetched++;
      this.persist();
    }
    return { ...r, notice: untrustedNotice };
  }
  async publish(input) {
    const decision = classify(input);
    if (!decision.allowed) {
      this.ledger.metrics.blocked++;
      this.persist();
      return { decision };
    }
    const p =
      input.kind === "discussion"
        ? {
            ...input.payload,
            discussion_type: input.payload.discussion_type ?? "question",
          }
        : input.payload;
    if (
      input.kind === "problem" &&
      typeof p.product === "string" &&
      typeof p.symptom_signature?.tool_product === "string" &&
      p.product !== p.symptom_signature.tool_product
    )
      return { error: "CONFLICTING_PRODUCT" };
    if (
      !fields[input.kind] ||
      Object.keys(p).some((k) => !fields[input.kind].includes(k))
    )
      return { error: "UNSUPPORTED_PAYLOAD_FIELD" };
    if (this.mode !== "safe_autopilot")
      return {
        decision: {
          allowed: false,
          reason:
            this.mode === "manual"
              ? "OWNER_CONFIRMATION_REQUIRED"
              : "MODE_READ_ONLY",
        },
      };
    if (!this.ledger.identity) return { error: "AUTHENTICATED_START_REQUIRED" };
    if (
      typeof input.observation_key !== "string" ||
      !input.observation_key ||
      scan(input.observation_key)
    )
      return { error: "SAFE_OBSERVATION_KEY_REQUIRED" };
    const key = digest(input.observation_key);
    const fingerprint = digest({ kind: input.kind, payload: p });
    const existing = this.ledger.operations[key];
    if (existing) {
      if (existing.fingerprint !== fingerprint)
        return { error: "OPERATION_PAYLOAD_CONFLICT" };
      this.ledger.metrics.duplicates++;
      this.persist();
      if (existing.phase === "committed")
        return { duplicate: true, receipt: existing.receipt };
      // No automatic resend: readback first, keep unknown fail-closed.
      const recovered = await this.request(
        "GET",
        "/operations/" + encodeURIComponent(existing.id),
      );
      return {
        recovery:
          recovered.status === 200
            ? "READBACK_REQUIRES_REVIEW"
            : "UNKNOWN_DO_NOT_RESEND",
        status: recovered.status,
      };
    }
    const closeout = input.closeout;
    const pending = closeout && this.ledger.closeout.pending.find(
      (entry) =>
        entry.action === closeout.action && entry.key === closeout.candidate_key,
    );
    const current = await this.request("GET", "/api/whoami");
    if (
      current.status !== 200 ||
      current.data?.authenticated !== true ||
      current.data.subject?.id !== this.ledger.identity.id ||
      current.data.operator?.id !== this.ledger.identity.operator_id ||
      current.data.write_epoch !== this.ledger.identity.epoch
    ) {
      if (current.error === "KFA_UNAVAILABLE") {
        if (pending)
          this.deferCloseout(closeout.candidate_key, "PUBLICATION_FAILURE_DEFERRED");
      }
      else if (current.error === "KFA_AUTH_UNAVAILABLE") {
        this.markAuthUnavailable();
        if (pending) this.deferCloseout(closeout.candidate_key, "KFA_AUTH_UNAVAILABLE");
      } else {
        this.markIdentityUnavailable();
        if (pending) this.deferCloseout(closeout.candidate_key, "IDENTITY_MISMATCH");
      }
      return { error: "CURRENT_IDENTITY_REQUIRED" };
    }
    if (!pending) return { error: "CLOSEOUT_DECISION_REQUIRED" };
    const ops = Object.values(this.ledger.operations);
    if (ops.length >= 8) return { error: "SESSION_WRITE_BOUND" };
    if (!["reply", "ack"].includes(input.kind)) {
      const prior = this.ledger.queries[pending.query_key];
      if (!prior?.complete) return { error: "DUPLICATE_SEARCH_REQUIRED" };
      if (
        ["problem", "discussion"].includes(input.kind) &&
        prior.records.length
      )
        return { error: "REUSE_EXISTING_RECORD" };
      if (input.kind === "discussion" && input.blocked !== true)
        return { error: "BLOCKING_ISSUE_REQUIRED" };
      if (
        input.kind === "discussion" &&
        ops.some((x) => x.kind === "discussion")
      )
        return { error: "DISCUSSION_BOUND" };
      if (
        input.kind !== "discussion" &&
        ops.filter((x) => !["reply", "ack", "discussion"].includes(x.kind))
          .length >= 3
      )
        return { error: "LESSON_BOUND" };
    }
    if (input.kind === "ack" && input.processed !== true)
      return { error: "PROCESSING_REQUIRED" };
    if (["edit_problem", "edit_solution"].includes(input.kind)) {
      const consultedKind = input.kind === "edit_problem" ? "problem" : "solution";
      if (
        closeout.action !== "REVISION" ||
        !this.ledger.consulted.some(
          (record) =>
            record.kind === consultedKind &&
            record.id === p.id &&
            record.revision === p.expected_revision,
        )
      )
        return { error: "EXACT_REVISION_FETCH_REQUIRED" };
    }
    const op = {
      id: `${this.ledger.identity.epoch}:companion-${digest([this.ledger.nonce, key]).slice(0, 40)}`,
      fingerprint,
      kind: input.kind,
      phase: "pending",
    };
    this.ledger.operations[key] = op;
    this.persist();
    const target = route(input.kind, p);
    const r = await this.request(
      target.method,
      target.path,
      requestPayload(input.kind, p),
      op.id,
    );
    if (r.status >= 200 && r.status < 300) {
      op.phase = "committed";
      op.receipt = {
        id: r.data?.result?.id ?? r.data?.id,
        publication_status:
          r.data?.result?.publication_status ?? r.data?.publication_status,
      };
      this.ledger.metrics.published++;
      this.commitCloseout(closeout.action, closeout.candidate_key);
    } else {
      op.phase = r.status === 0 ? "unknown" : "refused";
      this.deferCloseout(
        closeout.candidate_key,
        r.status === 409 ? "REVISION_CONFLICT" : "PUBLICATION_FAILURE_DEFERRED",
      );
    }
    this.persist();
    return {
      decision,
      status: r.status,
      phase: op.phase,
      receipt: op.receipt,
      error: r.error ?? (r.status >= 400 ? "SERVER_REFUSED" : undefined),
    };
  }

  closeoutKey(input) {
    return digest(["kfa-closeout-candidate", input]);
  }
  rememberCloseout(action, candidateKey, reason, queryKey) {
    if (!/^[a-f0-9]{64}$/.test(candidateKey)) return { action: "HOLD_PRIVACY" };
    const closeout = this.ledger.closeout;
    if (closeout.candidates >= 12)
      return { action: "DEFER", reason: "CLOSEOUT_CANDIDATE_BOUND" };
    closeout.candidates++;
    if (action === "CREATE" || action === "REVISION") {
      if (!closeout.pending.some((entry) => entry.key === candidateKey))
        closeout.pending.push({ action, key: candidateKey, query_key: queryKey });
    } else if (action === "DEFER") closeout.deferred.push(candidateKey);
    else closeout.held.push(candidateKey);
    closeout.pending = closeout.pending.slice(-3);
    closeout.dedup = closeout.dedup.slice(-12);
    closeout.deferred = closeout.deferred.slice(-12);
    closeout.held = closeout.held.slice(-12);
    this.persist();
    return { action, ...(reason ? { reason } : {}) };
  }
  deferCloseout(candidateKey, state) {
    const closeout = this.ledger.closeout;
    closeout.pending = closeout.pending.filter((entry) => entry.key !== candidateKey);
    if (/^[a-f0-9]{64}$/.test(candidateKey))
      closeout.deferred = [...closeout.deferred, candidateKey].slice(-12);
    this.failOpen(state);
  }
  commitCloseout(action, candidateKey) {
    const closeout = this.ledger.closeout;
    closeout.pending = closeout.pending.filter((entry) => entry.key !== candidateKey);
    const target = action === "CREATE" ? closeout.created : closeout.revisioned;
    if (!target.includes(candidateKey)) target.push(candidateKey);
    this.persist();
  }
  async lifecycle(event, input = {}) {
    const decisions = {
      startup: decideStartup,
      error: decideError,
      fetch: decideFetch,
      closeout: decideCloseout,
    };
    if (!decisions[event]) return { error: "LIFECYCLE_EVENT_REQUIRED" };
    const decision = decisions[event]({
      ...input,
      availability: this.ledger.availability,
      authentication: this.ledger.authentication,
      fetch_count: this.ledger.lifecycle.fetches,
      publication_count:
        this.ledger.closeout.created.length + this.ledger.closeout.revisioned.length,
    });
    if (decision.action === "SEARCH") {
      if (event === "startup") {
        if (this.ledger.lifecycle.startup_searches >= sessionBudgets.startup_searches)
          return {
            decision: { action: "SKIP_SEARCH", reason: "STARTUP_SEARCH_BOUND" },
            receipt: sessionReceipt(this.ledger),
          };
        this.ledger.lifecycle.startup_searches++;
      }
      if (event === "error") {
        if (!/^[a-z0-9][a-z0-9_-]{7,63}$/.test(input.failure_key ?? ""))
          return {
            decision: { action: "SKIP_SEARCH", reason: "ERROR_FINGERPRINT_REQUIRED" },
            receipt: sessionReceipt(this.ledger),
          };
        const group = digest(["kfa-error", input.failure_key]);
        if (this.ledger.lifecycle.error_groups[group])
          return {
            decision: { action: "SKIP_SEARCH", reason: "ERROR_ALREADY_SEARCHED" },
            receipt: sessionReceipt(this.ledger),
          };
        this.ledger.lifecycle.error_groups[group] = true;
      }
      this.persist();
      const result = await this.search({
        exact: decision.queries[0],
        context: decision.queries[1],
        broad: decision.queries[2],
      });
      return { decision, result, receipt: sessionReceipt(this.ledger) };
    }
    if (decision.action === "FETCH_EXACT") {
      if (this.ledger.lifecycle.fetches >= sessionBudgets.startup_fetches)
        return {
          decision: { action: "SKIP_SEARCH", reason: "FETCH_BOUND_OR_INVALID_REFERENCE" },
          receipt: sessionReceipt(this.ledger),
        };
      this.ledger.lifecycle.fetches++;
      this.persist();
      const result = await this.fetch(decision.reference.kind, decision.reference.id);
      return { decision, result, receipt: sessionReceipt(this.ledger) };
    }
    if (event === "closeout") {
      const candidateKey = this.closeoutKey(input);
      if (decision.action === "FAIL_OPEN") this.failOpen(decision.reason);
      let dedupQueryKey;
      if (["CREATE", "REVISION"].includes(decision.action)) {
        const dedup = decideError({
          availability: this.ledger.availability,
          authentication: this.ledger.authentication,
          non_obvious: true,
          exact: input.duplicate_signature,
        });
        if (dedup.action !== "SEARCH")
          decision.action = "HOLD_PRIVACY";
        else {
          const signatureKey = digest(["kfa-closeout-dedup", dedup.queries[0]]);
          const existingDedup = this.ledger.closeout.dedup[0];
          let result;
          if (existingDedup && existingDedup.signature_key !== signatureKey)
            decision.action = "DEFER";
          else if (existingDedup) {
            dedupQueryKey = existingDedup.query_key;
            result = this.ledger.queries[dedupQueryKey];
          } else {
            result = await this.search({ exact: dedup.queries[0] });
            dedupQueryKey = result.query_key;
            this.ledger.closeout.dedup = [
              { query_key: dedupQueryKey, signature_key: signatureKey },
            ];
            this.persist();
          }
          if (decision.action === "DEFER") {
            // A different candidate would require another remote duplicate pass.
          }
          else if (!result?.complete)
            decision.action = this.ledger.unavailable ? "FAIL_OPEN" : "HOLD_UNVERIFIED";
          else if (decision.action === "CREATE" && result.records.length)
            decision.action = "HOLD_DUPLICATE_AMBIGUITY";
          else if (
            decision.action === "REVISION" &&
            (!/^[A-Za-z0-9_-]{1,100}$/.test(input.duplicate_id ?? "") ||
              !result.records.some((record) => record.id === input.duplicate_id))
          )
            decision.action = "HOLD_DUPLICATE_AMBIGUITY";
        }
      }
      if (decision.action === "FAIL_OPEN") this.failOpen(decision.reason ?? "KFA_UNAVAILABLE");
      const recorded = this.rememberCloseout(
        decision.action,
        candidateKey,
        decision.reason,
        dedupQueryKey,
      );
      return {
        decision: recorded,
        ...(decision.action === "CREATE" || decision.action === "REVISION"
          ? { candidate_key: candidateKey }
          : {}),
        receipt: sessionReceipt(this.ledger),
      };
    }
    if (decision.action === "FAIL_OPEN") this.failOpen(decision.reason);
    return { decision, receipt: sessionReceipt(this.ledger) };
  }
}