harnery 0.33.0 → 0.34.0

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

@@ -0,0 +1,778 @@
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+import { closeSync, existsSync, lstatSync, openSync, readdirSync, readFileSync, readSync, statSync, } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { canonicalJsonV3, sha256V3 } from "./canonical.js";
+import { readEventV3Catalog, readEventV3SegmentManifest, } from "./catalog.js";
+import { EVENT_V3_SCHEMA_DIGEST } from "./generated.js";
+import { eventV3RecoveryRecordsRoot, listEventV3RecoveryReceipts, } from "./recovery-record.js";
+import { validateEventV3 } from "./validate.js";
+/** Inspect one failed active authority without weakening the canonical read boundary. */
+export function inspectInvalidActiveAuthorityV3(coordRoot, controlReason) {
+    const paths = eventV3Paths(coordRoot);
+    const ledger = readLedgerV3(coordRoot, { authority: "active" });
+    if (ledger.complete || ledger.diagnostics.length === 0) {
+        throw new Error("event_v3_recovery_requires_incomplete_ledger");
+    }
+    const diagnostic = [...ledger.diagnostics].sort((left, right) => left.segment_ordinal - right.segment_ordinal || left.byte_offset - right.byte_offset)[0];
+    const activeOrdinal = existsSync(paths.catalog)
+        ? readEventV3Catalog(paths.catalog).active.ordinal
+        : 1;
+    if (diagnostic.segment_ordinal !== activeOrdinal) {
+        throw new Error("event_v3_recovery_first_failure_is_not_in_active_authority");
+    }
+    const active = readFileSync(paths.active);
+    if (diagnostic.byte_offset > active.length) {
+        throw new Error("event_v3_recovery_diagnostic_offset_exceeds_active_authority");
+    }
+    return {
+        control_reason: controlReason,
+        authority_digest: digestEventV3AuthorityDirectoryV3(paths.root),
+        active_digest: sha256V3(active),
+        active_bytes: active.length,
+        validated_prefix_digest: sha256V3(active.subarray(0, diagnostic.byte_offset)),
+        validated_prefix_bytes: diagnostic.byte_offset,
+        diagnostic: {
+            code: diagnostic.code,
+            segment_ordinal: diagnostic.segment_ordinal,
+            byte_offset: diagnostic.byte_offset,
+            ...(diagnostic.event_id ? { event_id: diagnostic.event_id } : {}),
+        },
+    };
+}
+/** Hash one preserved V3 authority by relative path, byte count, and file digest. */
+export function digestEventV3AuthorityDirectoryV3(root) {
+    const base = resolve(root);
+    if (!lstatSync(base).isDirectory())
+        throw new Error("V3 authority root is not a directory");
+    const files = [];
+    const visit = (directory) => {
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            const path = join(directory, entry.name);
+            if (entry.isSymbolicLink())
+                throw new Error("V3 authority contains a symbolic link");
+            if (entry.isDirectory()) {
+                visit(path);
+                continue;
+            }
+            if (!entry.isFile())
+                throw new Error("V3 authority contains a non-regular file");
+            const bytes = readFileSync(path);
+            files.push({
+                path: relative(base, path).replaceAll("\\", "/"),
+                bytes: bytes.length,
+                digest: sha256V3(bytes),
+            });
+        }
+    };
+    visit(base);
+    files.sort((left, right) => left.path.localeCompare(right.path));
+    return `sha256:${createHash("sha256").update(canonicalJsonV3(files)).digest("hex")}`;
+}
+const MAX_CACHED_LEDGER_READS = 4;
+const ledgerReadCacheV3 = new Map();
+export const EVENT_V3_LEDGER_RELATIVE_ROOT = ".harnery/ledgers/v3";
+export function eventV3Paths(coordRoot) {
+    const root = join(resolve(coordRoot), EVENT_V3_LEDGER_RELATIVE_ROOT);
+    return {
+        root,
+        active: join(root, "active.ndjson"),
+        catalog: join(root, "catalog.json"),
+        segments: join(root, "segments"),
+    };
+}
+/** Stable file target for change notification only; reads still go through readLedgerV3. */
+export function eventV3ActiveWatchPath(coordRoot) {
+    return eventV3Paths(coordRoot).active;
+}
+/** Read the complete V3 ledger through catalog-bound filesystem discovery. */
+export function readLedgerV3(coordRoot, options = {}) {
+    const cacheKey = ledgerReadCacheKeyV3(coordRoot, options);
+    const storage = ledgerStorageVersionV3(coordRoot);
+    const cached = ledgerReadCacheV3.get(cacheKey);
+    if (cached?.storage.fingerprint === storage.fingerprint) {
+        ledgerReadCacheV3.delete(cacheKey);
+        ledgerReadCacheV3.set(cacheKey, cached);
+        return cached.result;
+    }
+    const resumed = cached ? resumeCachedLedgerReadV3(cached, storage, options) : undefined;
+    if (resumed) {
+        rememberLedgerReadV3(cacheKey, resumed);
+        return resumed.result;
+    }
+    const discovered = discoverLedgerFramesV3(coordRoot);
+    const validated = validateLedgerFramesV3(discovered.frames, options);
+    const recovery = discoverRecoveryReceiptsV3(coordRoot);
+    const diagnostics = [
+        ...discovered.diagnostics,
+        ...validated.result.diagnostics,
+        ...recovery.diagnostics,
+    ];
+    const result = {
+        ...validated.result,
+        diagnostics,
+        complete: diagnostics.length === 0,
+        bytes: discovered.bytes,
+        failed_epochs: recovery.receipts,
+    };
+    rememberLedgerReadV3(cacheKey, {
+        storage,
+        active: discovered.active,
+        validation_state: isolateValidationStateV3(validated.state),
+        result,
+    });
+    return result;
+}
+function rememberLedgerReadV3(cacheKey, cached) {
+    ledgerReadCacheV3.delete(cacheKey);
+    ledgerReadCacheV3.set(cacheKey, cached);
+    while (ledgerReadCacheV3.size > MAX_CACHED_LEDGER_READS) {
+        const oldestKey = ledgerReadCacheV3.keys().next().value;
+        if (oldestKey === undefined)
+            break;
+        ledgerReadCacheV3.delete(oldestKey);
+    }
+}
+export function readLedgerV3Since(coordRoot, cursor, options = {}) {
+    const discovered = discoverLedgerFramesV3(coordRoot);
+    const read = readLedgerFramesV3Since(discovered.frames, cursor, options);
+    const recovery = discoverRecoveryReceiptsV3(coordRoot);
+    const diagnostics = [...discovered.diagnostics, ...read.diagnostics, ...recovery.diagnostics];
+    return {
+        ...read,
+        events: diagnostics.length === 0 ? read.events : [],
+        diagnostics,
+        complete: diagnostics.length === 0,
+        bytes: discovered.bytes,
+        failed_epochs: recovery.receipts,
+    };
+}
+function discoverRecoveryReceiptsV3(coordRoot) {
+    try {
+        return { receipts: listEventV3RecoveryReceipts(coordRoot), diagnostics: [] };
+    }
+    catch {
+        return {
+            receipts: [],
+            diagnostics: [storageDiagnostic("recovery_record_invalid", 0)],
+        };
+    }
+}
+/**
+ * Validate an already-discovered V3 event stream in exact physical order.
+ * Filesystem/catalog discovery feeds this boundary; every downstream reader
+ * and projection consumes its positioned, authority-checked result.
+ */
+export function readLedgerFramesV3(frames, options = {}) {
+    return validateLedgerFramesV3(frames, options).result;
+}
+function validateLedgerFramesV3(frames, options) {
+    const state = {
+        diagnostics: [],
+        events: [],
+        advances: [],
+        accepted: new Set(options.accepted_schema_digests ?? [EVENT_V3_SCHEMA_DIGEST]),
+        reader_build: options.reader_build ?? "build_harnery-v3",
+        seen_ids: new Map(),
+        producer_sequences: new Map(),
+        attestations: new Set(),
+        clocks: new Map(),
+    };
+    validateLedgerFramesIntoStateV3(frames, state);
+    return { result: finishLedgerValidationV3(state, options, ledgerFramesBytesV3(frames)), state };
+}
+function validateLedgerFramesIntoStateV3(frames, state) {
+    state.first_position ??= frames[0]?.position;
+    const { diagnostics, events, advances, accepted, reader_build: readerBuild, seen_ids: seenIds, producer_sequences: producerSequences, attestations, clocks, } = state;
+    for (const frame of frames) {
+        if (state.pending) {
+            const comparison = comparePosition(frame.position, state.pending.position);
+            if (comparison === 0) {
+                state.active_schema_digest = state.pending.next_schema_digest;
+                state.pending = undefined;
+            }
+            else if (comparison > 0) {
+                diagnostics.push(diagnostic("advance_boundary_missed", frame, state.pending.event_id));
+                state.pending = undefined;
+            }
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(frame.raw);
+        }
+        catch {
+            diagnostics.push(diagnostic("malformed_json", frame));
+            continue;
+        }
+        const loose = parsed;
+        const looseContract = record(loose.contract);
+        if (looseContract.major !== 3) {
+            diagnostics.push(diagnostic("unsupported_major", frame));
+            continue;
+        }
+        const validation = validateEventV3(parsed);
+        if (!validation.ok || !validation.event) {
+            diagnostics.push(diagnostic("invalid_contract", frame));
+            continue;
+        }
+        const event = validation.event;
+        const shape = event;
+        if (canonicalJsonV3(event) !== frame.raw) {
+            diagnostics.push(diagnostic("noncanonical_frame", frame, shape.event_id));
+            continue;
+        }
+        const priorFrame = seenIds.get(shape.event_id);
+        if (priorFrame !== undefined) {
+            if (priorFrame !== frame.raw) {
+                diagnostics.push(diagnostic("conflicting_event_id", frame, shape.event_id));
+            }
+            continue;
+        }
+        seenIds.set(shape.event_id, frame.raw);
+        if (shape.event_type === "ledger.genesis") {
+            if (state.genesis_id !== undefined) {
+                diagnostics.push(diagnostic("multiple_genesis", frame, shape.event_id));
+                continue;
+            }
+            if (events.length !== 0)
+                diagnostics.push(diagnostic("genesis_not_first", frame, shape.event_id));
+            const payload = shape.payload;
+            state.genesis_id = string(payload.genesis_id);
+            state.active_schema_digest = string(payload.generated_schema_digest);
+            if (state.active_schema_digest !== shape.contract.schema_digest) {
+                diagnostics.push(diagnostic("genesis_digest_mismatch", frame, shape.event_id));
+            }
+        }
+        else if (state.genesis_id === undefined) {
+            diagnostics.push(diagnostic("missing_genesis", frame, shape.event_id));
+        }
+        if (!accepted.has(shape.contract.schema_digest)) {
+            diagnostics.push(diagnostic("unsupported_schema_digest", frame, shape.event_id));
+        }
+        if (state.active_schema_digest !== undefined &&
+            shape.contract.schema_digest !== state.active_schema_digest) {
+            diagnostics.push(diagnostic("unexpected_schema_digest", frame, shape.event_id));
+        }
+        for (const parentId of shape.links.caused_by) {
+            if (!seenIds.has(parentId)) {
+                diagnostics.push(diagnostic("causal_parent_missing", frame, shape.event_id));
+                break;
+            }
+        }
+        validateClock(shape, frame, clocks, diagnostics);
+        validateAttestation(shape, frame, attestations, diagnostics);
+        validateProducerSequence(shape, frame, producerSequences, diagnostics);
+        if (shape.event_type === "ledger.schema_advanced") {
+            const payload = shape.payload;
+            const nextDigest = string(payload.next_schema_digest);
+            const priorDigest = string(payload.prior_schema_digest);
+            const effectivePosition = {
+                segment_ordinal: number(payload.effective_segment_ordinal),
+                byte_offset: number(payload.effective_byte_offset),
+            };
+            if (priorDigest !== state.active_schema_digest) {
+                diagnostics.push(diagnostic("advance_prior_mismatch", frame, shape.event_id));
+            }
+            if (!accepted.has(nextDigest)) {
+                diagnostics.push(diagnostic("advance_digest_unsupported", frame, shape.event_id));
+            }
+            const compatibleBuilds = stringArray(payload.compatible_reader_builds);
+            if (!compatibleBuilds.includes(readerBuild)) {
+                diagnostics.push(diagnostic("advance_reader_incompatible", frame, shape.event_id));
+            }
+            if (comparePosition(effectivePosition, frame.position) <= 0 || state.pending) {
+                diagnostics.push(diagnostic("advance_boundary_invalid", frame, shape.event_id));
+            }
+            else {
+                state.pending = {
+                    event_id: shape.event_id,
+                    next_schema_digest: nextDigest,
+                    position: effectivePosition,
+                };
+                advances.push({
+                    event_id: shape.event_id,
+                    prior_schema_digest: priorDigest,
+                    next_schema_digest: nextDigest,
+                    effective_position: effectivePosition,
+                });
+            }
+        }
+        events.push({ event, position: frame.position });
+    }
+}
+function finishLedgerValidationV3(state, options, bytes) {
+    const diagnostics = [...state.diagnostics];
+    if (state.genesis_id === undefined &&
+        !diagnostics.some(({ code }) => code === "missing_genesis")) {
+        diagnostics.push({
+            code: "missing_genesis",
+            segment_ordinal: state.first_position?.segment_ordinal ?? 0,
+            byte_offset: state.first_position?.byte_offset ?? 0,
+        });
+    }
+    if (options.authority === "active" && state.genesis_id !== undefined) {
+        const activations = state.events.filter(({ event }) => event.event_type === "ledger.activated");
+        if (activations.length === 0) {
+            diagnostics.push({ code: "missing_activation", segment_ordinal: 0, byte_offset: 0 });
+        }
+        else {
+            const activation = activations.at(-1);
+            const payload = activation.event.payload;
+            if (payload.genesis_id !== state.genesis_id) {
+                diagnostics.push(diagnostic("activation_genesis_mismatch", {
+                    raw: "",
+                    position: activation.position,
+                }, activation.event.event_id));
+            }
+        }
+    }
+    return {
+        events: state.events,
+        diagnostics,
+        complete: diagnostics.length === 0,
+        genesis_id: state.genesis_id,
+        active_schema_digest: state.active_schema_digest,
+        advances: state.advances,
+        bytes,
+        failed_epochs: [],
+    };
+}
+function ledgerFramesBytesV3(frames) {
+    return frames.reduce((total, frame) => total + Buffer.byteLength(frame.raw, "utf8") + 1, 0);
+}
+export function readLedgerFramesV3Since(frames, cursor, options = {}) {
+    const read = readLedgerFramesV3(frames, options);
+    if (!read.genesis_id || !read.complete) {
+        return { ...read, events: [], cursor, reset_required: Boolean(cursor) };
+    }
+    if (cursor?.genesis_id !== undefined && cursor.genesis_id !== read.genesis_id) {
+        return withCursorDiagnostic(read, "cursor_genesis_mismatch", cursor);
+    }
+    let startIndex = 0;
+    if (cursor) {
+        const index = read.events.findIndex(({ event, position }) => event.event_id === cursor.event_id &&
+            position.segment_ordinal === cursor.segment_ordinal &&
+            position.byte_offset === cursor.byte_offset);
+        if (index < 0)
+            return withCursorDiagnostic(read, "cursor_position_missing", cursor);
+        startIndex = index + 1;
+    }
+    const last = read.events.at(-1);
+    return {
+        ...read,
+        events: read.events.slice(startIndex),
+        cursor: last
+            ? {
+                genesis_id: read.genesis_id,
+                segment_ordinal: last.position.segment_ordinal,
+                byte_offset: last.position.byte_offset,
+                event_id: last.event.event_id,
+            }
+            : cursor,
+        reset_required: false,
+    };
+}
+function validateAttestation(event, frame, attestations, diagnostics) {
+    if (event.event_type === "session.started") {
+        if (event.attestation_id)
+            attestations.add(event.attestation_id);
+        return;
+    }
+    if (event.event_type === "session.attestation_changed") {
+        const prior = string(event.payload.prior_attestation_id);
+        if (!attestations.has(prior)) {
+            diagnostics.push(diagnostic("unresolved_attestation", frame, event.event_id));
+        }
+        if (event.attestation_id)
+            attestations.add(event.attestation_id);
+        return;
+    }
+    if (event.attestation_id && !attestations.has(event.attestation_id)) {
+        diagnostics.push(diagnostic("unresolved_attestation", frame, event.event_id));
+    }
+}
+function validateClock(event, frame, clocks, diagnostics) {
+    const prior = clocks.get(event.time.clock_id);
+    const observedAtMs = Date.parse(event.time.observed_at);
+    if (prior && observedAtMs < prior.observed_at_ms && event.time.skew !== "regressed") {
+        diagnostics.push(diagnostic("wall_clock_regression_unmarked", frame, event.event_id));
+    }
+    const monotonicNs = event.time.monotonic_ns ? BigInt(event.time.monotonic_ns) : undefined;
+    if (prior?.monotonic_ns !== undefined &&
+        monotonicNs !== undefined &&
+        monotonicNs < prior.monotonic_ns) {
+        diagnostics.push(diagnostic("monotonic_clock_regression", frame, event.event_id));
+    }
+    clocks.set(event.time.clock_id, {
+        observed_at_ms: observedAtMs,
+        ...(monotonicNs !== undefined ? { monotonic_ns: monotonicNs } : {}),
+    });
+}
+function validateProducerSequence(event, frame, sequences, diagnostics) {
+    const key = `${event.producer.producer_id}\0${event.producer.boot_id}`;
+    const prior = sequences.get(key);
+    if ((prior === undefined && event.producer.sequence !== 1) ||
+        (prior !== undefined && event.producer.sequence !== prior + 1)) {
+        diagnostics.push(diagnostic("producer_sequence_gap", frame, event.event_id));
+    }
+    sequences.set(key, event.producer.sequence);
+}
+function withCursorDiagnostic(read, code, cursor) {
+    return {
+        ...read,
+        events: [],
+        diagnostics: [
+            ...read.diagnostics,
+            {
+                code,
+                segment_ordinal: cursor.segment_ordinal,
+                byte_offset: cursor.byte_offset,
+                event_id: cursor.event_id,
+            },
+        ],
+        complete: false,
+        reset_required: true,
+    };
+}
+function diagnostic(code, frame, eventId) {
+    return {
+        code,
+        segment_ordinal: frame.position.segment_ordinal,
+        byte_offset: frame.position.byte_offset,
+        ...(eventId ? { event_id: eventId } : {}),
+    };
+}
+function comparePosition(left, right) {
+    return left.segment_ordinal - right.segment_ordinal || left.byte_offset - right.byte_offset;
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function string(value) {
+    return typeof value === "string" ? value : "";
+}
+function number(value) {
+    return typeof value === "number" ? value : -1;
+}
+function stringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string")
+        : [];
+}
+function ledgerReadCacheKeyV3(coordRoot, options) {
+    const accepted = [...new Set(options.accepted_schema_digests ?? [EVENT_V3_SCHEMA_DIGEST])].sort();
+    return JSON.stringify([
+        resolve(coordRoot),
+        options.authority ?? "",
+        options.reader_build ?? "",
+        accepted,
+    ]);
+}
+function resumeCachedLedgerReadV3(cached, storage, options) {
+    if (!cached.result.complete ||
+        !cached.active ||
+        !storage.active ||
+        cached.storage.stable_fingerprint !== storage.stable_fingerprint ||
+        cached.active.path !== storage.active.path ||
+        storage.active.size <= cached.active.bytes) {
+        return undefined;
+    }
+    const appended = readActiveRangeV3(storage.active.path, cached.active.bytes, storage.active.size, cached.active.segment_ordinal);
+    if (!appended)
+        return undefined;
+    const state = {
+        ...cached.validation_state,
+        diagnostics: [],
+        events: [...cached.validation_state.events],
+        advances: [...cached.validation_state.advances],
+    };
+    validateLedgerFramesIntoStateV3(appended.frames, state);
+    const validated = finishLedgerValidationV3(state, options, cached.result.bytes + appended.bytes);
+    const diagnostics = [...appended.diagnostics, ...validated.diagnostics];
+    return {
+        storage,
+        active: {
+            ...cached.active,
+            bytes: storage.active.size,
+        },
+        validation_state: isolateValidationStateV3(state),
+        result: {
+            ...validated,
+            diagnostics,
+            complete: diagnostics.length === 0,
+            failed_epochs: cached.result.failed_epochs,
+        },
+    };
+}
+function isolateValidationStateV3(state) {
+    return {
+        ...state,
+        diagnostics: [...state.diagnostics],
+        events: [...state.events],
+        advances: [...state.advances],
+    };
+}
+function readActiveRangeV3(path, start, end, segmentOrdinal) {
+    const length = end - start;
+    const bytes = Buffer.alloc(length);
+    let offset = 0;
+    let fd;
+    try {
+        fd = openSync(path, "r");
+        while (offset < length) {
+            const read = readSync(fd, bytes, offset, length - offset, start + offset);
+            if (read === 0)
+                return undefined;
+            offset += read;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+    return framesFromBytes(bytes, segmentOrdinal, true, start);
+}
+/**
+ * Cheap identity for every filesystem object that can change discovery.
+ * Capture it before reading: a concurrent append then changes the next call's
+ * fingerprint, so a read that raced the writer is never retained as current.
+ */
+function ledgerStorageVersionV3(coordRoot) {
+    const paths = eventV3Paths(coordRoot);
+    const catalog = pathStorageVersionV3(paths.catalog);
+    const active = pathStorageVersionV3(paths.active);
+    const parts = [`catalog:${catalog.fingerprint}`];
+    const stableParts = [`catalog:${catalog.fingerprint}`, `active:${active.stable_fingerprint}`];
+    let names;
+    try {
+        names = readdirSync(paths.segments)
+            .filter((name) => /^(\d{12})\.(ndjson|manifest\.json)$/.test(name))
+            .sort();
+    }
+    catch (error) {
+        const segmentError = `segments:${filesystemErrorCode(error)}`;
+        parts.push(segmentError);
+        stableParts.push(segmentError);
+        return {
+            fingerprint: [...parts, `active:${active.fingerprint}`].join("|"),
+            stable_fingerprint: stableParts.join("|"),
+            ...(active.regular ? { active: { path: paths.active, size: active.size } } : {}),
+        };
+    }
+    for (const name of names) {
+        const part = `segment:${name}:${pathStorageVersionV3(join(paths.segments, name)).fingerprint}`;
+        parts.push(part);
+        stableParts.push(part);
+    }
+    const recoveryRoot = eventV3RecoveryRecordsRoot(coordRoot);
+    let recoveryNames = [];
+    try {
+        recoveryNames = readdirSync(recoveryRoot)
+            .filter((name) => name.endsWith(".committed.json"))
+            .sort();
+    }
+    catch (error) {
+        const code = filesystemErrorCode(error);
+        if (code !== "ENOENT") {
+            const part = `recoveries:${code}`;
+            parts.push(part);
+            stableParts.push(part);
+        }
+    }
+    for (const name of recoveryNames) {
+        const part = `recovery:${name}:${pathStorageVersionV3(join(recoveryRoot, name)).fingerprint}`;
+        parts.push(part);
+        stableParts.push(part);
+    }
+    return {
+        fingerprint: [...parts, `active:${active.fingerprint}`].join("|"),
+        stable_fingerprint: stableParts.join("|"),
+        ...(active.regular ? { active: { path: paths.active, size: active.size } } : {}),
+    };
+}
+function pathStorageVersionV3(path) {
+    try {
+        const stat = lstatSync(path, { bigint: true });
+        const stableFingerprint = [stat.mode, stat.dev, stat.ino, stat.birthtimeNs].join(":");
+        return {
+            fingerprint: [stableFingerprint, stat.size, stat.mtimeNs, stat.ctimeNs].join(":"),
+            stable_fingerprint: stableFingerprint,
+            regular: stat.isFile() && !stat.isSymbolicLink(),
+            size: Number(stat.size),
+        };
+    }
+    catch (error) {
+        const code = filesystemErrorCode(error);
+        return { fingerprint: code, stable_fingerprint: code, regular: false, size: 0 };
+    }
+}
+function filesystemErrorCode(error) {
+    return error && typeof error === "object" && "code" in error
+        ? String(error.code)
+        : "unavailable";
+}
+function discoverLedgerFramesV3(coordRoot) {
+    const paths = eventV3Paths(coordRoot);
+    if (!existsSync(paths.catalog)) {
+        if (hasSealedV3Metadata(paths.segments)) {
+            return {
+                frames: [],
+                diagnostics: [storageDiagnostic("catalog_invalid", 0)],
+                bytes: 0,
+            };
+        }
+        if (!existsSync(paths.active))
+            return { frames: [], diagnostics: [], bytes: 0 };
+        const bytes = readFileSync(paths.active);
+        return {
+            ...framesFromBytes(bytes, 1, true),
+            active: { bytes: bytes.length, path: paths.active, segment_ordinal: 1 },
+        };
+    }
+    let catalog;
+    try {
+        catalog = readEventV3Catalog(paths.catalog);
+    }
+    catch {
+        return {
+            frames: [],
+            diagnostics: [storageDiagnostic("catalog_invalid", 0)],
+            bytes: 0,
+        };
+    }
+    const discovered = { frames: [], diagnostics: [], bytes: 0 };
+    for (const entry of catalog.segments) {
+        discoverSealedSegment(paths.segments, entry, discovered);
+    }
+    discoverActiveSegment(paths.active, catalog, discovered);
+    return discovered;
+}
+function discoverSealedSegment(segmentsRoot, entry, discovered) {
+    const segmentPath = join(segmentsRoot, entry.segment_file);
+    const manifestPath = join(segmentsRoot, entry.manifest_file);
+    if (!regularFile(segmentPath) || !regularFile(manifestPath)) {
+        discovered.diagnostics.push(storageDiagnostic("missing_segment", entry.ordinal));
+        return;
+    }
+    const segmentBytes = readFileSync(segmentPath);
+    const manifestBytes = readFileSync(manifestPath);
+    discovered.bytes += segmentBytes.length;
+    if (segmentBytes.length !== entry.bytes || sha256V3(segmentBytes) !== entry.segment_digest) {
+        discovered.diagnostics.push(storageDiagnostic("segment_digest_mismatch", entry.ordinal));
+        return;
+    }
+    if (sha256V3(manifestBytes) !== entry.manifest_digest) {
+        discovered.diagnostics.push(storageDiagnostic("manifest_digest_mismatch", entry.ordinal));
+        return;
+    }
+    let manifest;
+    try {
+        manifest = readEventV3SegmentManifest(manifestPath);
+    }
+    catch {
+        discovered.diagnostics.push(storageDiagnostic("manifest_segment_mismatch", entry.ordinal));
+        return;
+    }
+    const segment = framesFromBytes(segmentBytes, entry.ordinal, false);
+    if (!manifestMatchesCatalog(manifest, entry) ||
+        !manifestMatchesFrames(manifest, segment.frames)) {
+        discovered.diagnostics.push(storageDiagnostic("manifest_segment_mismatch", entry.ordinal));
+        return;
+    }
+    discovered.frames.push(...segment.frames);
+    discovered.diagnostics.push(...segment.diagnostics);
+}
+function discoverActiveSegment(activePath, catalog, discovered) {
+    if (!regularFile(activePath)) {
+        discovered.diagnostics.push(storageDiagnostic("active_replaced", catalog.active.ordinal));
+        return;
+    }
+    const stat = statSync(activePath);
+    const bigintStat = statSync(activePath, { bigint: true });
+    if (String(stat.dev) !== catalog.active.device ||
+        String(stat.ino) !== catalog.active.inode ||
+        String(bigintStat.birthtimeNs) !== catalog.active.birthtime_ns) {
+        discovered.diagnostics.push(storageDiagnostic("active_replaced", catalog.active.ordinal));
+        return;
+    }
+    const bytes = readFileSync(activePath);
+    const active = framesFromBytes(bytes, catalog.active.ordinal, true);
+    discovered.frames.push(...active.frames);
+    discovered.diagnostics.push(...active.diagnostics);
+    discovered.bytes += bytes.length;
+    discovered.active = {
+        bytes: bytes.length,
+        path: activePath,
+        segment_ordinal: catalog.active.ordinal,
+    };
+}
+function framesFromBytes(bytes, segmentOrdinal, allowPartialFinalFrame, initialByteOffset = 0) {
+    const raw = bytes.toString("utf8");
+    const frames = [];
+    const diagnostics = [];
+    const lines = raw.split("\n");
+    let byteOffset = initialByteOffset;
+    for (const [index, line] of lines.entries()) {
+        const final = index === lines.length - 1;
+        const lineBytes = Buffer.byteLength(line, "utf8");
+        if (line.length === 0) {
+            if (!final) {
+                diagnostics.push(storageDiagnostic("malformed_json", segmentOrdinal, byteOffset));
+                byteOffset += 1;
+            }
+            continue;
+        }
+        if (final && !raw.endsWith("\n")) {
+            diagnostics.push(storageDiagnostic(allowPartialFinalFrame ? "partial_final_frame" : "malformed_json", segmentOrdinal, byteOffset));
+            break;
+        }
+        frames.push({
+            raw: line,
+            position: { segment_ordinal: segmentOrdinal, byte_offset: byteOffset },
+        });
+        byteOffset += lineBytes + 1;
+    }
+    return { frames, diagnostics, bytes: bytes.length };
+}
+function manifestMatchesCatalog(manifest, entry) {
+    return (manifest.ordinal === entry.ordinal &&
+        manifest.segment_file === entry.segment_file &&
+        manifest.segment_digest === entry.segment_digest &&
+        manifest.bytes === entry.bytes &&
+        manifest.row_count === entry.row_count);
+}
+function manifestMatchesFrames(manifest, frames) {
+    if (frames.length !== manifest.row_count)
+        return false;
+    try {
+        const records = frames.map(({ raw }) => record(JSON.parse(raw)));
+        const schemaDigests = [
+            ...new Set(records.map((event) => string(record(event.contract).schema_digest))),
+        ].sort();
+        return (records[0]?.event_id === manifest.first_event_id &&
+            records.at(-1)?.event_id === manifest.last_event_id &&
+            schemaDigests.join("\0") === manifest.schema_digests.join("\0"));
+    }
+    catch {
+        return false;
+    }
+}
+function hasSealedV3Metadata(segmentsPath) {
+    if (!existsSync(segmentsPath))
+        return false;
+    return readdirSync(segmentsPath).some((name) => /^(\d{12})\.(ndjson|manifest\.json)$/.test(name));
+}
+function regularFile(path) {
+    if (!existsSync(path))
+        return false;
+    const stat = lstatSync(path);
+    return stat.isFile() && !stat.isSymbolicLink();
+}
+function storageDiagnostic(code, segmentOrdinal, byteOffset = 0) {
+    return { code, segment_ordinal: segmentOrdinal, byte_offset: byteOffset };
+}