harnery 0.32.0 → 0.34.0

package/dist/core/events/v3/recovery-record.d.ts

@@ -0,0 +1,47 @@
+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 declare function eventV3RecoveryRecordsRoot(coordRoot: string): string;
+export declare function listEventV3RecoveryReceipts(coordRoot: string): EventV3RecoveryReceipt[];
+export declare function readEventV3RecoveryIntent(path: string): EventV3RecoveryIntent;
+export declare function readEventV3RecoveryReceipt(path: string): EventV3RecoveryReceipt;
+export declare function validateEventV3RecoveryIntent(value: unknown): EventV3RecoveryIntent;
+export declare function validateEventV3RecoveryReceipt(value: unknown): EventV3RecoveryReceipt;
+//# sourceMappingURL=recovery-record.d.ts.map

package/dist/core/events/v3/recovery-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-record.d.ts","sourceRoot":"","sources":["../../../../src/core/events/v3/recovery-record.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,UAAU,MAAM,EAAE,CAAC;IACrC,aAAa,EAAE,UAAU,MAAM,EAAE,CAAC;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,uBAAuB,EAAE,UAAU,MAAM,EAAE,CAAC;IAC5C,sBAAsB,EAAE,MAAM,CAAC;IAC/B,UAAU,EAAE,yBAAyB,CAAC;CACvC;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,kCAAkC,CAAC;IAC3C,cAAc,EAAE,CAAC,CAAC;IAClB,WAAW,EAAE,OAAO,MAAM,EAAE,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,UAAU,MAAM,EAAE,CAAC;IAClC,OAAO,EAAE,sBAAsB,CAAC;CACjC;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,mCAAmC,CAAC;IAC5C,cAAc,EAAE,CAAC,CAAC;IAClB,WAAW,EAAE,OAAO,MAAM,EAAE,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,sBAAsB,CAAC;IAChC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE;QACb,UAAU,EAAE,MAAM,CAAC;QACnB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,GAAG,sBAAsB,EAAE,CAOvF;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,CAE7E;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,sBAAsB,CAE/E;AAED,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,CAEnF;AAED,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,OAAO,GAAG,sBAAsB,CAErF"}

package/dist/core/events/v3/recovery-record.js

@@ -0,0 +1,167 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { canonicalJsonV3 } from "./canonical.js";
+const SHA256_PATTERN = /^sha256:[a-f0-9]{64}$/;
+const RECOVERY_ID_PATTERN = /^rcv_[a-f0-9]{32}$/;
+export function eventV3RecoveryRecordsRoot(coordRoot) {
+    return join(resolve(coordRoot), ".harnery", "ledgers", "v3-recoveries");
+}
+export function listEventV3RecoveryReceipts(coordRoot) {
+    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) {
+    return readCanonicalRecord(path, validateIntent, "V3 recovery intent");
+}
+export function readEventV3RecoveryReceipt(path) {
+    return readCanonicalRecord(path, validateReceipt, "V3 recovery receipt");
+}
+export function validateEventV3RecoveryIntent(value) {
+    return validateIntent(value);
+}
+export function validateEventV3RecoveryReceipt(value) {
+    return validateReceipt(value);
+}
+function readCanonicalRecord(path, validate, label) {
+    let text;
+    let parsed;
+    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) {
+    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,
+        failure: validateFailure(record.failure),
+    };
+}
+function validateReceipt(value) {
+    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,
+        failure: validateFailure(record.failure),
+        new_authority: authority,
+    };
+}
+function validateFailure(value) {
+    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,
+        diagnostic: diagnostic,
+    };
+}
+function object(value, message) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(message);
+    return value;
+}
+function exactKeys(record, expected, label) {
+    if (Object.keys(record).sort().join("\0") !== expected.join("\0")) {
+        throw new Error(`${label} has unsupported fields`);
+    }
+}
+function sha256(value) {
+    return typeof value === "string" && SHA256_PATTERN.test(value);
+}
+function recoveryId(value) {
+    return typeof value === "string" && RECOVERY_ID_PATTERN.test(value);
+}
+function timestamp(value) {
+    return typeof value === "string" && Number.isFinite(Date.parse(value));
+}
+function safeText(value, max) {
+    return typeof value === "string" && value.length > 0 && value.length <= max;
+}
+function nonnegativeInteger(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 0;
+}

package/dist/core/events/v3/recovery.d.ts

@@ -0,0 +1,22 @@
+import { type EventV3RecoveryReceipt } from "./recovery-record.js";
+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 declare function recoverInvalidEventLedgerV3(input: RecoverInvalidEventLedgerV3Input): RecoverInvalidEventLedgerV3Result;
+//# sourceMappingURL=recovery.d.ts.map

package/dist/core/events/v3/recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../../../../src/core/events/v3/recovery.ts"],"names":[],"mappings":"AAsBA,OAAO,EAGL,KAAK,sBAAsB,EAO5B,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,gCAAgC;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,UAAU,MAAM,EAAE,CAAC;IACjC,gBAAgB,EAAE,MAAM,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,iCAAiC;IAChD,KAAK,EAAE,WAAW,GAAG,mBAAmB,CAAC;IACzC,OAAO,EAAE,sBAAsB,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,gCAAgC,GACtC,iCAAiC,CAoEnC"}

package/dist/core/events/v3/recovery.js

@@ -0,0 +1,227 @@
+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.js";
+import { initializeEventLedgerV3 } from "./bootstrap.js";
+import { canonicalJsonV3, sha256V3 } from "./canonical.js";
+import { readEventV3ControlState } from "./control.js";
+import { digestEventV3AuthorityDirectoryV3, inspectInvalidActiveAuthorityV3, readLedgerV3, } from "./reader.js";
+import { eventV3RecoveryRecordsRoot, listEventV3RecoveryReceipts, readEventV3RecoveryIntent, readEventV3RecoveryReceipt, validateEventV3RecoveryIntent, validateEventV3RecoveryReceipt, } from "./recovery-record.js";
+/**
+ * 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) {
+    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;
+    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) {
+    const digest = createRecoveryDigest(failure);
+    return `rcv_${digest.slice(7, 39)}`;
+}
+function publishRecoveryIntent(root, value) {
+    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.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, intent, archivedEpoch, now) {
+    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.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, recoveryId) {
+    const readyPath = recoveryIntentPath(eventV3RecoveryRecordsRoot(root), recoveryId);
+    if (!existsSync(readyPath))
+        return;
+    unlinkSync(readyPath);
+    fsyncParentDirectory(readyPath);
+}
+function listPendingRecoveryIntents(root) {
+    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, digest) {
+    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) {
+    return sha256V3(canonicalJsonV3(failure));
+}
+function recoveryIntentPath(records, recoveryId) {
+    return join(records, `${recoveryId}.ready.json`);
+}
+function recoveryReceiptPath(records, recoveryId) {
+    return join(records, `${recoveryId}.committed.json`);
+}
+function publishExclusive(path, serialized) {
+    const temporary = `${path}.tmp.${process.pid}`;
+    let fd;
+    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/dist/core/events/v3/span-state.d.ts

@@ -0,0 +1,52 @@
+import type { SpanSummaryV3 } from "./contract.js";
+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 declare function captureSpanClockV3(options?: {
+    now?: Date;
+    platform?: NodeJS.Platform;
+    linux_uptime?: string;
+}): SpanClockV3;
+/** Convert Linux's boot-relative `/proc/uptime` value without floating-point drift. */
+export declare function linuxUptimeNanosecondsV3(value: string): string;
+export declare function openSpanStateV3(input: OpenSpanV3Input): OpenSpanStateV3;
+/**
+ * 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 declare function closeSpanStateV3(span: OpenSpanStateV3, input: CloseSpanV3Input): SpanSummaryV3;
+/**
+ * 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 declare function recoverSpanUpperBoundV3(span: OpenSpanStateV3, input: RecoverSpanUpperBoundV3Input): SpanSummaryV3["duration_ms"];
+//# sourceMappingURL=span-state.d.ts.map

package/dist/core/events/v3/span-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-state.d.ts","sourceRoot":"","sources":["../../../../src/core/events/v3/span-state.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,QAAQ,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,QAAQ,MAAM,EAAE,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,QAAQ,MAAM,EAAE,CAAC;IAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,aAAa,CAAC,EAAE,OAAO,MAAM,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,QAAQ,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,QAAQ,MAAM,EAAE,CAAC;IAClC,OAAO,EAAE,QAAQ,MAAM,EAAE,CAAC;IAC1B,KAAK,EAAE,WAAW,CAAC;IACnB,aAAa,CAAC,EAAE,OAAO,MAAM,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,QAAQ,MAAM,EAAE,CAAC;IAC1B,KAAK,EAAE,WAAW,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,QAAQ,MAAM,EAAE,CAAC;IAC1B,KAAK,EAAE,WAAW,CAAC;CACpB;AAED,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAChC,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9E,WAAW,CASb;AAED,uFAAuF;AACvF,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,eAAe,GAAG,eAAe,CASvE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,gBAAgB,GAAG,aAAa,CAS9F;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,4BAA4B,GAClC,aAAa,CAAC,aAAa,CAAC,CAyB9B"}

package/dist/core/events/v3/span-state.js

@@ -0,0 +1,142 @@
+import { readFileSync } from "node:fs";
+/** Capture a cross-process, boot-anchored monotonic reading where the host exposes one. */
+export function captureSpanClockV3(options = {}) {
+    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) {
+    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) * 1000000000n + BigInt(nanos)).toString();
+}
+export function openSpanStateV3(input) {
+    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, input) {
+    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, input) {
+    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) / 1000000n);
+    if (!Number.isSafeInteger(milliseconds)) {
+        return { state: "unknown", reason: "recovery_monotonic_clock_unavailable" };
+    }
+    return {
+        state: "observed",
+        value: milliseconds,
+        attestation: "derived",
+        confidence: "exact",
+    };
+}
+function spanDurationV3(span, input) {
+    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) / 1000000n),
+            attestation: "native",
+            confidence: "exact",
+        };
+    }
+    return {
+        state: "observed",
+        value: closedAt - openedAt,
+        attestation: "derived",
+        confidence: "high",
+    };
+}
+function monotonic(value) {
+    if (!/^\d+$/.test(value))
+        return undefined;
+    try {
+        return BigInt(value);
+    }
+    catch {
+        return undefined;
+    }
+}