harnery 0.32.0 → 0.34.0

package/src/core/events/v3/recovery-record.ts

@@ -0,0 +1,244 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { canonicalJsonV3 } from "./canonical.ts";
+
+const SHA256_PATTERN = /^sha256:[a-f0-9]{64}$/;
+const RECOVERY_ID_PATTERN = /^rcv_[a-f0-9]{32}$/;
+
+export interface EventV3RecoveryDiagnostic {
+  code: string;
+  segment_ordinal: number;
+  byte_offset: number;
+  event_id?: string;
+}
+
+export interface EventV3RecoveryFailure {
+  control_reason: string;
+  authority_digest: `sha256:${string}`;
+  active_digest: `sha256:${string}`;
+  active_bytes: number;
+  validated_prefix_digest: `sha256:${string}`;
+  validated_prefix_bytes: number;
+  diagnostic: EventV3RecoveryDiagnostic;
+}
+
+export interface EventV3RecoveryIntent {
+  format: "harnery-event-v3-recovery-intent";
+  format_version: 1;
+  recovery_id: `rcv_${string}`;
+  created_at: string;
+  approval_record_id: string;
+  harnery_build: string;
+  host_build: string;
+  config_digest: `sha256:${string}`;
+  failure: EventV3RecoveryFailure;
+}
+
+export interface EventV3RecoveryReceipt {
+  format: "harnery-event-v3-recovery-receipt";
+  format_version: 1;
+  recovery_id: `rcv_${string}`;
+  created_at: string;
+  completed_at: string;
+  approval_record_id: string;
+  failure: EventV3RecoveryFailure;
+  archive_directory: string;
+  new_authority: {
+    genesis_id: string;
+    activation_id: string;
+  };
+}
+
+export function eventV3RecoveryRecordsRoot(coordRoot: string): string {
+  return join(resolve(coordRoot), ".harnery", "ledgers", "v3-recoveries");
+}
+
+export function listEventV3RecoveryReceipts(coordRoot: string): EventV3RecoveryReceipt[] {
+  const root = eventV3RecoveryRecordsRoot(coordRoot);
+  if (!existsSync(root)) return [];
+  return readdirSync(root)
+    .filter((name) => name.endsWith(".committed.json"))
+    .sort()
+    .map((name) => readEventV3RecoveryReceipt(join(root, name)));
+}
+
+export function readEventV3RecoveryIntent(path: string): EventV3RecoveryIntent {
+  return readCanonicalRecord(path, validateIntent, "V3 recovery intent");
+}
+
+export function readEventV3RecoveryReceipt(path: string): EventV3RecoveryReceipt {
+  return readCanonicalRecord(path, validateReceipt, "V3 recovery receipt");
+}
+
+export function validateEventV3RecoveryIntent(value: unknown): EventV3RecoveryIntent {
+  return validateIntent(value);
+}
+
+export function validateEventV3RecoveryReceipt(value: unknown): EventV3RecoveryReceipt {
+  return validateReceipt(value);
+}
+
+function readCanonicalRecord<T>(path: string, validate: (value: unknown) => T, label: string): T {
+  let text: string;
+  let parsed: unknown;
+  try {
+    text = readFileSync(path, "utf8");
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error(`${label} is missing or malformed`);
+  }
+  const value = validate(parsed);
+  if (text !== `${canonicalJsonV3(value)}\n`) throw new Error(`${label} is not canonical`);
+  return value;
+}
+
+function validateIntent(value: unknown): EventV3RecoveryIntent {
+  const record = object(value, "V3 recovery intent is invalid");
+  exactKeys(
+    record,
+    [
+      "approval_record_id",
+      "config_digest",
+      "created_at",
+      "failure",
+      "format",
+      "format_version",
+      "harnery_build",
+      "host_build",
+      "recovery_id",
+    ],
+    "V3 recovery intent",
+  );
+  if (
+    record.format !== "harnery-event-v3-recovery-intent" ||
+    record.format_version !== 1 ||
+    !recoveryId(record.recovery_id) ||
+    !timestamp(record.created_at) ||
+    !safeText(record.approval_record_id, 200) ||
+    !safeText(record.harnery_build, 120) ||
+    !safeText(record.host_build, 120) ||
+    !sha256(record.config_digest)
+  ) {
+    throw new Error("V3 recovery intent values are invalid");
+  }
+  return {
+    ...(record as unknown as EventV3RecoveryIntent),
+    failure: validateFailure(record.failure),
+  };
+}
+
+function validateReceipt(value: unknown): EventV3RecoveryReceipt {
+  const record = object(value, "V3 recovery receipt is invalid");
+  exactKeys(
+    record,
+    [
+      "approval_record_id",
+      "archive_directory",
+      "completed_at",
+      "created_at",
+      "failure",
+      "format",
+      "format_version",
+      "new_authority",
+      "recovery_id",
+    ],
+    "V3 recovery receipt",
+  );
+  const authority = object(record.new_authority, "V3 recovery new authority is invalid");
+  exactKeys(authority, ["activation_id", "genesis_id"], "V3 recovery new authority");
+  if (
+    record.format !== "harnery-event-v3-recovery-receipt" ||
+    record.format_version !== 1 ||
+    !recoveryId(record.recovery_id) ||
+    !timestamp(record.created_at) ||
+    !timestamp(record.completed_at) ||
+    Date.parse(String(record.completed_at)) < Date.parse(String(record.created_at)) ||
+    !safeText(record.approval_record_id, 200) ||
+    typeof record.archive_directory !== "string" ||
+    !/^epoch-[0-9]+(?:-[0-9]+)?$/.test(record.archive_directory) ||
+    typeof authority.genesis_id !== "string" ||
+    !/^gex_[a-zA-Z0-9._-]+$/.test(authority.genesis_id) ||
+    typeof authority.activation_id !== "string" ||
+    !/^act_[a-zA-Z0-9._-]+$/.test(authority.activation_id)
+  ) {
+    throw new Error("V3 recovery receipt values are invalid");
+  }
+  return {
+    ...(record as unknown as EventV3RecoveryReceipt),
+    failure: validateFailure(record.failure),
+    new_authority: authority as unknown as EventV3RecoveryReceipt["new_authority"],
+  };
+}
+
+function validateFailure(value: unknown): EventV3RecoveryFailure {
+  const record = object(value, "V3 recovery failure is invalid");
+  exactKeys(
+    record,
+    [
+      "active_bytes",
+      "active_digest",
+      "authority_digest",
+      "control_reason",
+      "diagnostic",
+      "validated_prefix_bytes",
+      "validated_prefix_digest",
+    ],
+    "V3 recovery failure",
+  );
+  const diagnostic = object(record.diagnostic, "V3 recovery diagnostic is invalid");
+  const diagnosticKeys =
+    diagnostic.event_id === undefined
+      ? ["byte_offset", "code", "segment_ordinal"]
+      : ["byte_offset", "code", "event_id", "segment_ordinal"];
+  exactKeys(diagnostic, diagnosticKeys, "V3 recovery diagnostic");
+  if (
+    !safeText(record.control_reason, 120) ||
+    !sha256(record.authority_digest) ||
+    !sha256(record.active_digest) ||
+    !nonnegativeInteger(record.active_bytes) ||
+    !sha256(record.validated_prefix_digest) ||
+    !nonnegativeInteger(record.validated_prefix_bytes) ||
+    Number(record.validated_prefix_bytes) > Number(record.active_bytes) ||
+    !safeText(diagnostic.code, 120) ||
+    !nonnegativeInteger(diagnostic.segment_ordinal) ||
+    !nonnegativeInteger(diagnostic.byte_offset) ||
+    (diagnostic.event_id !== undefined && !safeText(diagnostic.event_id, 160))
+  ) {
+    throw new Error("V3 recovery failure values are invalid");
+  }
+  return {
+    ...(record as unknown as EventV3RecoveryFailure),
+    diagnostic: diagnostic as unknown as EventV3RecoveryDiagnostic,
+  };
+}
+
+function object(value: unknown, message: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(message);
+  return value as Record<string, unknown>;
+}
+
+function exactKeys(record: Record<string, unknown>, expected: string[], label: string): void {
+  if (Object.keys(record).sort().join("\0") !== expected.join("\0")) {
+    throw new Error(`${label} has unsupported fields`);
+  }
+}
+
+function sha256(value: unknown): value is `sha256:${string}` {
+  return typeof value === "string" && SHA256_PATTERN.test(value);
+}
+
+function recoveryId(value: unknown): value is `rcv_${string}` {
+  return typeof value === "string" && RECOVERY_ID_PATTERN.test(value);
+}
+
+function timestamp(value: unknown): value is string {
+  return typeof value === "string" && Number.isFinite(Date.parse(value));
+}
+
+function safeText(value: unknown, max: number): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= max;
+}
+
+function nonnegativeInteger(value: unknown): value is number {
+  return Number.isSafeInteger(value) && Number(value) >= 0;
+}

package/src/core/events/v3/recovery.ts

@@ -0,0 +1,271 @@
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  fsyncSync,
+  linkSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { fsyncParentDirectory } from "../../workflow/durable-record.ts";
+import { initializeEventLedgerV3 } from "./bootstrap.ts";
+import { canonicalJsonV3, sha256V3 } from "./canonical.ts";
+import { readEventV3ControlState } from "./control.ts";
+import {
+  digestEventV3AuthorityDirectoryV3,
+  inspectInvalidActiveAuthorityV3,
+  readLedgerV3,
+} from "./reader.ts";
+import {
+  type EventV3RecoveryFailure,
+  type EventV3RecoveryIntent,
+  type EventV3RecoveryReceipt,
+  eventV3RecoveryRecordsRoot,
+  listEventV3RecoveryReceipts,
+  readEventV3RecoveryIntent,
+  readEventV3RecoveryReceipt,
+  validateEventV3RecoveryIntent,
+  validateEventV3RecoveryReceipt,
+} from "./recovery-record.ts";
+
+export interface RecoverInvalidEventLedgerV3Input {
+  coordRoot: string;
+  harneryBuild: string;
+  hostBuild: string;
+  configDigest: `sha256:${string}`;
+  approvalRecordId: string;
+  now?: () => Date;
+}
+
+export interface RecoverInvalidEventLedgerV3Result {
+  state: "recovered" | "already_recovered";
+  receipt: EventV3RecoveryReceipt;
+}
+
+/**
+ * Preserve one failed active authority intact and start a clean epoch.
+ *
+ * The durable intent makes retries idempotent across the archive, genesis,
+ * activation, and receipt publication boundaries. Event bytes are never
+ * copied into the new authority or retained in the recovery metadata.
+ */
+export function recoverInvalidEventLedgerV3(
+  input: RecoverInvalidEventLedgerV3Input,
+): RecoverInvalidEventLedgerV3Result {
+  const root = resolve(input.coordRoot);
+  const current = readEventV3ControlState(root);
+  const committed = listEventV3RecoveryReceipts(root);
+  if (current.state === "active") {
+    const genesisId = current.genesis.event.payload.genesis_id;
+    const existing = committed.find(({ new_authority }) => new_authority.genesis_id === genesisId);
+    if (existing) {
+      removePendingIntent(root, existing.recovery_id);
+      return { state: "already_recovered", receipt: existing };
+    }
+  }
+
+  const pending = listPendingRecoveryIntents(root);
+  if (pending.length > 1) throw new Error("event_v3_recovery_has_multiple_pending_intents");
+  let intent = pending[0];
+  let archivedEpoch: string | undefined;
+
+  if (current.state === "invalid") {
+    if (current.reason !== "ledger_integrity_failure") {
+      throw new Error(`event_v3_recovery_requires_ledger_integrity_failure:${current.reason}`);
+    }
+    const failure = inspectInvalidActiveAuthorityV3(root, current.reason);
+    const recoveryId = recoveryIdFor(failure);
+    if (intent && intent.recovery_id !== recoveryId) {
+      throw new Error("event_v3_recovery_pending_intent_conflicts_with_failed_authority");
+    }
+    intent ??= publishRecoveryIntent(root, {
+      format: "harnery-event-v3-recovery-intent",
+      format_version: 1,
+      recovery_id: recoveryId,
+      created_at: (input.now ?? (() => new Date()))().toISOString(),
+      approval_record_id: input.approvalRecordId,
+      harnery_build: input.harneryBuild,
+      host_build: input.hostBuild,
+      config_digest: input.configDigest,
+      failure,
+    });
+    const initialized = initializeEventLedgerV3({
+      coordRoot: root,
+      harneryBuild: intent.harnery_build,
+      hostBuild: intent.host_build,
+      configDigest: intent.config_digest,
+      approvalRecordId: intent.approval_record_id,
+      forceNewEpoch: true,
+      now: () => new Date(intent.created_at),
+    });
+    archivedEpoch = initialized.archived_epoch;
+  } else if (intent) {
+    const initialized = initializeEventLedgerV3({
+      coordRoot: root,
+      harneryBuild: intent.harnery_build,
+      hostBuild: intent.host_build,
+      configDigest: intent.config_digest,
+      approvalRecordId: intent.approval_record_id,
+      resumeCandidate: true,
+      now: () => new Date(intent.created_at),
+    });
+    archivedEpoch = initialized.archived_epoch;
+  } else {
+    throw new Error(`event_v3_recovery_not_required:${current.state}`);
+  }
+
+  if (!intent) throw new Error("event_v3_recovery_intent_unavailable");
+  return {
+    state: "recovered",
+    receipt: commitRecoveryReceipt(root, intent, archivedEpoch, input.now),
+  };
+}
+
+function recoveryIdFor(failure: EventV3RecoveryFailure): `rcv_${string}` {
+  const digest = createRecoveryDigest(failure);
+  return `rcv_${digest.slice(7, 39)}`;
+}
+
+function publishRecoveryIntent(root: string, value: EventV3RecoveryIntent): EventV3RecoveryIntent {
+  const intent = validateEventV3RecoveryIntent(value);
+  const records = eventV3RecoveryRecordsRoot(root);
+  mkdirSync(records, { recursive: true, mode: 0o700 });
+  chmodSync(records, 0o700);
+  const path = recoveryIntentPath(records, intent.recovery_id);
+  const serialized = `${canonicalJsonV3(intent)}\n`;
+  if (existsSync(path)) {
+    const existing = readEventV3RecoveryIntent(path);
+    if (canonicalJsonV3(existing) !== canonicalJsonV3(intent)) {
+      throw new Error("event_v3_recovery_intent_conflict");
+    }
+    return existing;
+  }
+  try {
+    publishExclusive(path, serialized);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    const existing = readEventV3RecoveryIntent(path);
+    if (canonicalJsonV3(existing) !== canonicalJsonV3(intent)) {
+      throw new Error("event_v3_recovery_intent_conflict");
+    }
+    return existing;
+  }
+  return intent;
+}
+
+function commitRecoveryReceipt(
+  root: string,
+  intent: EventV3RecoveryIntent,
+  archivedEpoch: string | undefined,
+  now: RecoverInvalidEventLedgerV3Input["now"],
+): EventV3RecoveryReceipt {
+  const control = readEventV3ControlState(root);
+  if (control.state !== "active") {
+    throw new Error(`event_v3_recovery_new_authority_unavailable:${control.state}`);
+  }
+  const current = readLedgerV3(root, { authority: "active" });
+  if (!current.complete) throw new Error("event_v3_recovery_new_authority_is_incomplete");
+  const archive = archivedEpoch ?? findArchivedAuthority(root, intent.failure.authority_digest);
+  if (!archive || digestEventV3AuthorityDirectoryV3(archive) !== intent.failure.authority_digest) {
+    throw new Error("event_v3_recovery_failed_authority_digest_mismatch");
+  }
+  const receipt = validateEventV3RecoveryReceipt({
+    format: "harnery-event-v3-recovery-receipt",
+    format_version: 1,
+    recovery_id: intent.recovery_id,
+    created_at: intent.created_at,
+    completed_at: (now ?? (() => new Date()))().toISOString(),
+    approval_record_id: intent.approval_record_id,
+    failure: intent.failure,
+    archive_directory: basename(archive),
+    new_authority: {
+      genesis_id: control.genesis.event.payload.genesis_id,
+      activation_id: control.activation.activation_id,
+    },
+  });
+  const records = eventV3RecoveryRecordsRoot(root);
+  const committedPath = recoveryReceiptPath(records, intent.recovery_id);
+  const serialized = `${canonicalJsonV3(receipt)}\n`;
+  if (existsSync(committedPath)) {
+    const existing = readEventV3RecoveryReceipt(committedPath);
+    if (canonicalJsonV3(existing) !== canonicalJsonV3(receipt)) {
+      throw new Error("event_v3_recovery_receipt_conflict");
+    }
+    removePendingIntent(root, intent.recovery_id);
+    return existing;
+  }
+  try {
+    publishExclusive(committedPath, serialized);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    const existing = readEventV3RecoveryReceipt(committedPath);
+    if (canonicalJsonV3(existing) !== canonicalJsonV3(receipt)) {
+      throw new Error("event_v3_recovery_receipt_conflict");
+    }
+    removePendingIntent(root, intent.recovery_id);
+    return existing;
+  }
+  removePendingIntent(root, intent.recovery_id);
+  return receipt;
+}
+
+function removePendingIntent(root: string, recoveryId: string): void {
+  const readyPath = recoveryIntentPath(eventV3RecoveryRecordsRoot(root), recoveryId);
+  if (!existsSync(readyPath)) return;
+  unlinkSync(readyPath);
+  fsyncParentDirectory(readyPath);
+}
+
+function listPendingRecoveryIntents(root: string): EventV3RecoveryIntent[] {
+  const records = eventV3RecoveryRecordsRoot(root);
+  if (!existsSync(records)) return [];
+  return readdirSync(records)
+    .filter((name) => name.endsWith(".ready.json"))
+    .sort()
+    .map((name) => readEventV3RecoveryIntent(join(records, name)));
+}
+
+function findArchivedAuthority(root: string, digest: string): string | undefined {
+  const archives = join(resolve(root), ".harnery", "ledgers", "v3-archives");
+  if (!existsSync(archives)) return undefined;
+  const matches = readdirSync(archives, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && /^epoch-[0-9]+(?:-[0-9]+)?$/.test(entry.name))
+    .map((entry) => join(archives, entry.name))
+    .filter((path) => digestEventV3AuthorityDirectoryV3(path) === digest);
+  if (matches.length > 1) throw new Error("event_v3_recovery_archive_digest_is_ambiguous");
+  return matches[0];
+}
+
+function createRecoveryDigest(failure: EventV3RecoveryFailure): `sha256:${string}` {
+  return sha256V3(canonicalJsonV3(failure));
+}
+
+function recoveryIntentPath(records: string, recoveryId: string): string {
+  return join(records, `${recoveryId}.ready.json`);
+}
+
+function recoveryReceiptPath(records: string, recoveryId: string): string {
+  return join(records, `${recoveryId}.committed.json`);
+}
+
+function publishExclusive(path: string, serialized: string): void {
+  const temporary = `${path}.tmp.${process.pid}`;
+  let fd: number | undefined;
+  try {
+    fd = openSync(temporary, "wx", 0o600);
+    writeFileSync(fd, serialized, "utf8");
+    fsyncSync(fd);
+    closeSync(fd);
+    fd = undefined;
+    linkSync(temporary, path);
+    fsyncParentDirectory(path);
+    unlinkSync(temporary);
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+    if (existsSync(temporary)) unlinkSync(temporary);
+  }
+}

package/src/core/events/v3/span-state.ts

@@ -0,0 +1,187 @@
+import { readFileSync } from "node:fs";
+import type { SpanSummaryV3 } from "./contract.ts";
+
+export interface SpanClockV3 {
+  observed_at: string;
+  monotonic_ns?: string;
+}
+
+export interface OpenSpanStateV3 {
+  span_id: `span_${string}`;
+  parent_span_id?: `span_${string}`;
+  opened_at: string;
+  boot_id: `boot_${string}`;
+  opened_monotonic_ns?: string;
+  open_event_id?: `evt_${string}`;
+}
+
+export interface OpenSpanV3Input {
+  span_id: `span_${string}`;
+  parent_span_id?: `span_${string}`;
+  boot_id: `boot_${string}`;
+  clock: SpanClockV3;
+  open_event_id?: `evt_${string}`;
+}
+
+export interface CloseSpanV3Input {
+  boot_id: `boot_${string}`;
+  clock: SpanClockV3;
+  recovery_reason?: string;
+}
+
+export interface RecoverSpanUpperBoundV3Input {
+  boot_id: `boot_${string}`;
+  clock: SpanClockV3;
+}
+
+/** Capture a cross-process, boot-anchored monotonic reading where the host exposes one. */
+export function captureSpanClockV3(
+  options: { now?: Date; platform?: NodeJS.Platform; linux_uptime?: string } = {},
+): SpanClockV3 {
+  const observed_at = (options.now ?? new Date()).toISOString();
+  if ((options.platform ?? process.platform) !== "linux") return { observed_at };
+  try {
+    const uptime = options.linux_uptime ?? readFileSync("/proc/uptime", "utf8");
+    return { observed_at, monotonic_ns: linuxUptimeNanosecondsV3(uptime) };
+  } catch {
+    return { observed_at };
+  }
+}
+
+/** Convert Linux's boot-relative `/proc/uptime` value without floating-point drift. */
+export function linuxUptimeNanosecondsV3(value: string): string {
+  const token = value.trim().split(/\s+/, 1)[0] ?? "";
+  if (!/^\d+(?:\.\d+)?$/.test(token)) throw new Error("invalid Linux uptime value");
+  const [whole = "0", fraction = ""] = token.split(".");
+  const nanos = `${fraction}000000000`.slice(0, 9);
+  return (BigInt(whole) * 1_000_000_000n + BigInt(nanos)).toString();
+}
+
+export function openSpanStateV3(input: OpenSpanV3Input): OpenSpanStateV3 {
+  return {
+    span_id: input.span_id,
+    ...(input.parent_span_id ? { parent_span_id: input.parent_span_id } : {}),
+    opened_at: input.clock.observed_at,
+    boot_id: input.boot_id,
+    ...(input.clock.monotonic_ns ? { opened_monotonic_ns: input.clock.monotonic_ns } : {}),
+    ...(input.open_event_id ? { open_event_id: input.open_event_id } : {}),
+  };
+}
+
+/**
+ * Materialize a self-contained terminal summary.
+ *
+ * Same-boot monotonic readings are exact. Cross-boot or unsupported hosts
+ * fall back to a high-confidence wall delta. Regressions and recovery remain
+ * explicit missing/unknown observations; they are never coerced to zero.
+ */
+export function closeSpanStateV3(span: OpenSpanStateV3, input: CloseSpanV3Input): SpanSummaryV3 {
+  const duration_ms = spanDurationV3(span, input);
+  return {
+    span_id: span.span_id,
+    ...(span.parent_span_id ? { parent_span_id: span.parent_span_id } : {}),
+    opened_at: span.opened_at,
+    duration_ms,
+    ...(span.open_event_id ? { open_event_id: span.open_event_id } : {}),
+  };
+}
+
+/**
+ * Bound a recovered span's elapsed interval only when two same-boot monotonic
+ * readings prove it. The interval is not evidence of tool execution time.
+ */
+export function recoverSpanUpperBoundV3(
+  span: OpenSpanStateV3,
+  input: RecoverSpanUpperBoundV3Input,
+): SpanSummaryV3["duration_ms"] {
+  if (span.boot_id !== input.boot_id) {
+    return { state: "unknown", reason: "recovery_clock_mismatch" };
+  }
+  if (span.opened_monotonic_ns === undefined || input.clock.monotonic_ns === undefined) {
+    return { state: "unknown", reason: "recovery_monotonic_clock_unavailable" };
+  }
+  const openedMonotonic = monotonic(span.opened_monotonic_ns);
+  const closedMonotonic = monotonic(input.clock.monotonic_ns);
+  if (openedMonotonic === undefined || closedMonotonic === undefined) {
+    return { state: "unknown", reason: "recovery_monotonic_clock_unavailable" };
+  }
+  if (closedMonotonic < openedMonotonic) {
+    return { state: "unknown", reason: "recovery_monotonic_clock_regressed" };
+  }
+  const milliseconds = Number((closedMonotonic - openedMonotonic) / 1_000_000n);
+  if (!Number.isSafeInteger(milliseconds)) {
+    return { state: "unknown", reason: "recovery_monotonic_clock_unavailable" };
+  }
+  return {
+    state: "observed",
+    value: milliseconds,
+    attestation: "derived",
+    confidence: "exact",
+  };
+}
+
+function spanDurationV3(
+  span: OpenSpanStateV3,
+  input: CloseSpanV3Input,
+): SpanSummaryV3["duration_ms"] {
+  if (input.recovery_reason) return { state: "unknown", reason: input.recovery_reason };
+  const openedAt = Date.parse(span.opened_at);
+  const closedAt = Date.parse(input.clock.observed_at);
+  if (!Number.isFinite(openedAt) || !Number.isFinite(closedAt)) {
+    return {
+      state: "expected_but_missing",
+      capability: "span_duration",
+      reason: "clock_unavailable",
+    };
+  }
+  if (closedAt < openedAt) {
+    return {
+      state: "expected_but_missing",
+      capability: "span_duration",
+      reason: "clock_regressed",
+    };
+  }
+  if (
+    span.boot_id === input.boot_id &&
+    span.opened_monotonic_ns !== undefined &&
+    input.clock.monotonic_ns !== undefined
+  ) {
+    const openedMonotonic = monotonic(span.opened_monotonic_ns);
+    const closedMonotonic = monotonic(input.clock.monotonic_ns);
+    if (openedMonotonic === undefined || closedMonotonic === undefined) {
+      return {
+        state: "expected_but_missing",
+        capability: "span_duration",
+        reason: "clock_unavailable",
+      };
+    }
+    if (closedMonotonic < openedMonotonic) {
+      return {
+        state: "expected_but_missing",
+        capability: "span_duration",
+        reason: "monotonic_clock_regressed",
+      };
+    }
+    return {
+      state: "observed",
+      value: Number((closedMonotonic - openedMonotonic) / 1_000_000n),
+      attestation: "native",
+      confidence: "exact",
+    };
+  }
+  return {
+    state: "observed",
+    value: closedAt - openedAt,
+    attestation: "derived",
+    confidence: "high",
+  };
+}
+
+function monotonic(value: string): bigint | undefined {
+  if (!/^\d+$/.test(value)) return undefined;
+  try {
+    return BigInt(value);
+  } catch {
+    return undefined;
+  }
+}