harnery 0.35.0 → 0.37.0

package/dist/core/events/legacy-storage/compression.js

@@ -0,0 +1,107 @@
+/** Verified in-place compression for sealed, non-terminal legacy V1 shards. */
+import { createReadStream, createWriteStream } from "node:fs";
+import { chmod, lstat, rename, rm } from "node:fs/promises";
+import { basename } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { createGzip } from "node:zlib";
+import { verifyLegacyV1HardFence } from "./fence.js";
+import { inventoryLegacyV1Segments } from "./inventory.js";
+import { streamLegacyV1Rows } from "./reader.js";
+export async function compressSealedLegacyV1Segments(coordRoot, opts = {}) {
+    const fence = await verifyLegacyV1HardFence(coordRoot);
+    const terminal = basename(fence.terminal_archive_path);
+    const inventory = await inventoryLegacyV1Segments(coordRoot);
+    const rows = inventory.map((entry) => {
+        if (entry.filename === terminal) {
+            return {
+                filename: entry.filename,
+                path: entry.path,
+                bytes_before: entry.bytes,
+                bytes_after: null,
+                action: "keep",
+                reason: "terminal shard is bound by the V1 hard-fence digest",
+            };
+        }
+        if (entry.compressed) {
+            return {
+                filename: entry.filename,
+                path: entry.path,
+                bytes_before: entry.bytes,
+                bytes_after: entry.bytes,
+                action: "keep",
+                reason: "already compressed",
+            };
+        }
+        return {
+            filename: entry.filename,
+            path: entry.path,
+            bytes_before: entry.bytes,
+            bytes_after: null,
+            action: "would-compress",
+            reason: "sealed non-terminal V1 shard",
+        };
+    });
+    if (!opts.yes)
+        return rows;
+    for (const row of rows) {
+        if (row.action !== "would-compress")
+            continue;
+        const expected = inventory.find((entry) => entry.path === row.path);
+        const current = (await inventoryLegacyV1Segments(coordRoot)).find((entry) => entry.path === row.path);
+        if (!current ||
+            current.bytes !== expected.bytes ||
+            current.digest !== expected.digest ||
+            current.compressed) {
+            throw new Error(`legacy_v1_segment_changed_before_compression:${row.filename}`);
+        }
+        const sourceStat = await lstat(row.path);
+        const destination = `${row.path}.gz`;
+        const temporary = `${row.path}.partial-${process.pid}.gz`;
+        try {
+            try {
+                await lstat(destination);
+                throw new Error(`legacy_v1_compressed_destination_exists:${row.filename}`);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            await pipeline(createReadStream(row.path), createGzip({ level: 9 }), createWriteStream(temporary, { flags: "wx", mode: 0o600 }));
+            await proveRowParity(row.path, temporary);
+            const unchanged = (await inventoryLegacyV1Segments(coordRoot)).find((entry) => entry.path === row.path);
+            if (!unchanged ||
+                unchanged.bytes !== expected.bytes ||
+                unchanged.digest !== expected.digest) {
+                throw new Error(`legacy_v1_segment_changed_during_compression:${row.filename}`);
+            }
+            await chmod(temporary, sourceStat.mode & 0o777);
+            await rename(temporary, destination);
+            await rm(row.path);
+            row.action = "compressed";
+            row.reason = "verified gzip replacement preserved every logical row";
+            row.bytes_after = (await lstat(destination)).size;
+            row.path = destination;
+            row.filename = basename(destination);
+        }
+        catch (error) {
+            await rm(temporary, { force: true });
+            throw error;
+        }
+    }
+    return rows;
+}
+async function proveRowParity(loose, compressed) {
+    const left = streamLegacyV1Rows(loose)[Symbol.asyncIterator]();
+    const right = streamLegacyV1Rows(compressed)[Symbol.asyncIterator]();
+    while (true) {
+        const [looseRow, packedRow] = await Promise.all([left.next(), right.next()]);
+        if (looseRow.done || packedRow.done) {
+            if (looseRow.done !== packedRow.done)
+                throw new Error("legacy_v1_compression_row_count_mismatch");
+            return;
+        }
+        if (!looseRow.value.bytes.equals(packedRow.value.bytes)) {
+            throw new Error(`legacy_v1_compression_row_mismatch:${looseRow.value.row_number}`);
+        }
+    }
+}

package/dist/core/events/legacy-storage/fence.d.ts

@@ -0,0 +1,15 @@
+export interface LegacyV1HardFence {
+    manifest_version: 1;
+    kind: "v1_hard_path_fence";
+    terminal_archive: string;
+    terminal_digest: `sha256:${string}`;
+}
+export interface VerifiedLegacyV1HardFence {
+    fence_directory: string;
+    marker_path: string;
+    terminal_archive_path: string;
+    marker: LegacyV1HardFence;
+}
+/** Verify the exact read-only V1 path fence and its terminal sealed segment. */
+export declare function verifyLegacyV1HardFence(coordRoot: string): Promise<VerifiedLegacyV1HardFence>;
+//# sourceMappingURL=fence.d.ts.map

package/dist/core/events/legacy-storage/fence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fence.d.ts","sourceRoot":"","sources":["../../../../src/core/events/legacy-storage/fence.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,iBAAiB;IAChC,gBAAgB,EAAE,CAAC,CAAC;IACpB,IAAI,EAAE,oBAAoB,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,UAAU,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,yBAAyB;IACxC,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,MAAM,EAAE,iBAAiB,CAAC;CAC3B;AAKD,gFAAgF;AAChF,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,yBAAyB,CAAC,CA0DpC"}

package/dist/core/events/legacy-storage/fence.js

@@ -0,0 +1,115 @@
+import { createHash } from "node:crypto";
+import { constants, createReadStream } from "node:fs";
+import { lstat, open, readdir, realpath } from "node:fs/promises";
+import { basename, join, relative, resolve } from "node:path";
+import { canonicalJsonV3 } from "../v3/canonical.js";
+const MARKER = "V1-SEALED.json";
+const LEGACY_ACTIVE_NAME = ["events", "ndjson"].join(".");
+/** Verify the exact read-only V1 path fence and its terminal sealed segment. */
+export async function verifyLegacyV1HardFence(coordRoot) {
+    const root = resolve(coordRoot);
+    const harnery = join(root, ".harnery");
+    const harneryStat = await lstat(harnery);
+    if (!harneryStat.isDirectory() || harneryStat.isSymbolicLink()) {
+        throw new Error("legacy_v1_harnery_root_invalid");
+    }
+    const harneryReal = await realpath(harnery);
+    const fence = join(harnery, LEGACY_ACTIVE_NAME);
+    let fenceStat;
+    try {
+        fenceStat = await lstat(fence);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error("legacy_v1_hard_fence_missing");
+        }
+        throw error;
+    }
+    if (!fenceStat.isDirectory() || fenceStat.isSymbolicLink()) {
+        throw new Error("legacy_v1_active_file_present_or_fence_invalid");
+    }
+    if ((fenceStat.mode & 0o222) !== 0)
+        throw new Error("legacy_v1_hard_fence_is_writable");
+    const fenceReal = await realpath(fence);
+    if (relative(harneryReal, fenceReal).startsWith(".."))
+        throw new Error("legacy_v1_hard_fence_escape");
+    const names = (await readdir(fence)).sort();
+    if (names.length !== 1 || names[0] !== MARKER)
+        throw new Error("legacy_v1_hard_fence_not_exact");
+    const markerPath = join(fence, MARKER);
+    const markerStat = await lstat(markerPath);
+    if (!markerStat.isFile() || markerStat.isSymbolicLink()) {
+        throw new Error("legacy_v1_hard_fence_marker_invalid");
+    }
+    if ((markerStat.mode & 0o222) !== 0)
+        throw new Error("legacy_v1_hard_fence_marker_writable");
+    if (markerStat.size > 64 * 1024)
+        throw new Error("legacy_v1_hard_fence_marker_too_large");
+    const markerText = await readFileNoFollow(markerPath);
+    const marker = validateFenceMarker(JSON.parse(markerText));
+    if (markerText.trim() !== canonicalJsonV3(marker)) {
+        throw new Error("legacy_v1_hard_fence_marker_noncanonical");
+    }
+    const terminalName = marker.terminal_archive.replace(/^\.harnery\//, "");
+    if (!/^events-[0-9]{4}-[0-9]{2}-[0-9]{2}(?:\.[1-9][0-9]*)?\.ndjson$/.test(terminalName)) {
+        throw new Error("legacy_v1_terminal_archive_name_invalid");
+    }
+    const terminalPath = join(harnery, terminalName);
+    const terminalStat = await lstat(terminalPath);
+    if (!terminalStat.isFile() || terminalStat.isSymbolicLink()) {
+        throw new Error("legacy_v1_terminal_archive_invalid");
+    }
+    if ((await hashFile(terminalPath)) !== marker.terminal_digest) {
+        throw new Error("legacy_v1_terminal_archive_digest_mismatch");
+    }
+    return {
+        fence_directory: fence,
+        marker_path: markerPath,
+        terminal_archive_path: terminalPath,
+        marker,
+    };
+}
+function validateFenceMarker(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("legacy_v1_hard_fence_marker_invalid");
+    }
+    const marker = value;
+    if (Object.keys(marker).sort().join("\0") !==
+        ["kind", "manifest_version", "terminal_archive", "terminal_digest"].sort().join("\0") ||
+        marker.manifest_version !== 1 ||
+        marker.kind !== "v1_hard_path_fence" ||
+        typeof marker.terminal_archive !== "string" ||
+        typeof marker.terminal_digest !== "string" ||
+        !/^sha256:[0-9a-f]{64}$/.test(marker.terminal_digest)) {
+        throw new Error("legacy_v1_hard_fence_marker_invalid");
+    }
+    return marker;
+}
+async function readFileNoFollow(path) {
+    const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile())
+            throw new Error("legacy_v1_hard_fence_marker_invalid");
+        return handle.readFile("utf8");
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function hashFile(path) {
+    const hash = createHash("sha256");
+    const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile())
+            throw new Error(`legacy_v1_segment_not_regular:${basename(path)}`);
+        const stream = createReadStream(path, { fd: handle.fd, autoClose: false });
+        for await (const current of stream)
+            hash.update(current);
+    }
+    finally {
+        await handle.close();
+    }
+    return `sha256:${hash.digest("hex")}`;
+}

package/dist/core/events/legacy-storage/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./canary.js";
+export * from "./compression.js";
+export * from "./fence.js";
+export * from "./inventory.js";
+export * from "./manifest.js";
+export * from "./reader.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/events/legacy-storage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/events/legacy-storage/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC"}

package/dist/core/events/legacy-storage/index.js

@@ -0,0 +1,6 @@
+export * from "./canary.js";
+export * from "./compression.js";
+export * from "./fence.js";
+export * from "./inventory.js";
+export * from "./manifest.js";
+export * from "./reader.js";

package/dist/core/events/legacy-storage/inventory.d.ts

@@ -0,0 +1,10 @@
+export interface LegacyV1SegmentInventoryEntry {
+    filename: string;
+    path: string;
+    bytes: number;
+    digest: `sha256:${string}`;
+    compressed: boolean;
+}
+/** Enumerate all root events*.ndjson* frozen-history candidates, including manual variants. */
+export declare function inventoryLegacyV1Segments(coordRoot: string): Promise<LegacyV1SegmentInventoryEntry[]>;
+//# sourceMappingURL=inventory.d.ts.map

package/dist/core/events/legacy-storage/inventory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inventory.d.ts","sourceRoot":"","sources":["../../../../src/core/events/legacy-storage/inventory.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,UAAU,MAAM,EAAE,CAAC;IAC3B,UAAU,EAAE,OAAO,CAAC;CACrB;AAID,+FAA+F;AAC/F,wBAAsB,yBAAyB,CAC7C,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,6BAA6B,EAAE,CAAC,CA0B1C"}

package/dist/core/events/legacy-storage/inventory.js

@@ -0,0 +1,40 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, readdir, realpath } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+const LEGACY_ACTIVE_NAME = ["events", "ndjson"].join(".");
+/** Enumerate all root events*.ndjson* frozen-history candidates, including manual variants. */
+export async function inventoryLegacyV1Segments(coordRoot) {
+    const harnery = resolve(coordRoot, ".harnery");
+    const stat = await lstat(harnery);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error("legacy_v1_inventory_root_invalid");
+    const rootReal = await realpath(harnery);
+    const result = [];
+    for (const name of (await readdir(harnery)).sort()) {
+        if (!/^events.*\.ndjson(?:\.gz)?$/.test(name) || name === LEGACY_ACTIVE_NAME)
+            continue;
+        const path = join(harnery, name);
+        const entryStat = await lstat(path);
+        if (!entryStat.isFile() || entryStat.isSymbolicLink()) {
+            throw new Error(`legacy_v1_inventory_segment_invalid:${name}`);
+        }
+        const pathReal = await realpath(path);
+        if (relative(rootReal, pathReal).startsWith(".."))
+            throw new Error("legacy_v1_inventory_escape");
+        result.push({
+            filename: name,
+            path,
+            bytes: entryStat.size,
+            digest: await hashFile(path),
+            compressed: name.endsWith(".gz"),
+        });
+    }
+    return result;
+}
+async function hashFile(path) {
+    const hash = createHash("sha256");
+    for await (const current of createReadStream(path))
+        hash.update(current);
+    return `sha256:${hash.digest("hex")}`;
+}

package/dist/core/events/legacy-storage/manifest.d.ts

@@ -0,0 +1,23 @@
+export interface LegacyV1SegmentManifest {
+    format: "harnery-legacy-v1-segment";
+    format_version: 1;
+    segment_id: `v1s_${string}`;
+    source: {
+        filename: string;
+        bytes: number;
+        digest: `sha256:${string}`;
+        row_count: number;
+        minimum_recorded_at: string | null;
+        maximum_recorded_at: string | null;
+    };
+    payload: {
+        algorithm: "gzip";
+        path: string;
+        bytes: number;
+        digest: `sha256:${string}`;
+    };
+    minimum_harnery_version: string;
+    created_at: string;
+}
+export declare function validateLegacyV1SegmentManifest(value: unknown): LegacyV1SegmentManifest;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/core/events/legacy-storage/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../../src/core/events/legacy-storage/manifest.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,2BAA2B,CAAC;IACpC,cAAc,EAAE,CAAC,CAAC;IAClB,UAAU,EAAE,OAAO,MAAM,EAAE,CAAC;IAC5B,MAAM,EAAE;QACN,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,UAAU,MAAM,EAAE,CAAC;QAC3B,SAAS,EAAE,MAAM,CAAC;QAClB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;QACnC,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;KACpC,CAAC;IACF,OAAO,EAAE;QACP,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,UAAU,MAAM,EAAE,CAAC;KAC5B,CAAC;IACF,uBAAuB,EAAE,MAAM,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,uBAAuB,CAmEvF"}

package/dist/core/events/legacy-storage/manifest.js

@@ -0,0 +1,108 @@
+export function validateLegacyV1SegmentManifest(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("legacy_v1_manifest_invalid");
+    }
+    const manifest = value;
+    exact(manifest, [
+        "format",
+        "format_version",
+        "segment_id",
+        "source",
+        "payload",
+        "minimum_harnery_version",
+        "created_at",
+    ]);
+    if (manifest.format !== "harnery-legacy-v1-segment" || manifest.format_version !== 1) {
+        throw new Error("legacy_v1_manifest_version_unsupported");
+    }
+    const segmentId = text(manifest.segment_id);
+    if (!/^v1s_[0-9a-f]{32}$/.test(segmentId))
+        throw new Error("legacy_v1_segment_id_invalid");
+    const source = object(manifest.source);
+    exact(source, [
+        "filename",
+        "bytes",
+        "digest",
+        "row_count",
+        "minimum_recorded_at",
+        "maximum_recorded_at",
+    ]);
+    const filename = text(source.filename);
+    if (!/^events.+\.ndjson$/.test(filename) || filename.includes("/") || filename.includes("\\")) {
+        throw new Error("legacy_v1_source_filename_invalid");
+    }
+    const minimum = nullableTimestamp(source.minimum_recorded_at);
+    const maximum = nullableTimestamp(source.maximum_recorded_at);
+    if ((minimum === null) !== (maximum === null) || (minimum && maximum && minimum > maximum)) {
+        throw new Error("legacy_v1_manifest_time_range_invalid");
+    }
+    const payload = object(manifest.payload);
+    exact(payload, ["algorithm", "path", "bytes", "digest"]);
+    if (payload.algorithm !== "gzip" || payload.path !== `${segmentId}.ndjson.gz`) {
+        throw new Error("legacy_v1_payload_contract_invalid");
+    }
+    const version = text(manifest.minimum_harnery_version);
+    if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
+        throw new Error("legacy_v1_minimum_version_invalid");
+    }
+    return {
+        format: "harnery-legacy-v1-segment",
+        format_version: 1,
+        segment_id: segmentId,
+        source: {
+            filename,
+            bytes: integer(source.bytes),
+            digest: digest(source.digest),
+            row_count: integer(source.row_count),
+            minimum_recorded_at: minimum,
+            maximum_recorded_at: maximum,
+        },
+        payload: {
+            algorithm: "gzip",
+            path: text(payload.path),
+            bytes: integer(payload.bytes),
+            digest: digest(payload.digest),
+        },
+        minimum_harnery_version: version,
+        created_at: timestamp(manifest.created_at),
+    };
+}
+function object(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("legacy_v1_manifest_object_invalid");
+    }
+    return value;
+}
+function exact(value, keys) {
+    if (Object.keys(value).sort().join("\0") !== [...keys].sort().join("\0")) {
+        throw new Error("legacy_v1_manifest_unknown_field");
+    }
+}
+function text(value) {
+    if (typeof value !== "string")
+        throw new Error("legacy_v1_manifest_string_invalid");
+    return value;
+}
+function integer(value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error("legacy_v1_manifest_integer_invalid");
+    }
+    return value;
+}
+function digest(value) {
+    const result = text(value);
+    if (!/^sha256:[0-9a-f]{64}$/.test(result))
+        throw new Error("legacy_v1_manifest_digest_invalid");
+    return result;
+}
+function timestamp(value) {
+    const result = text(value);
+    if (!/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(result) ||
+        !Number.isFinite(Date.parse(result))) {
+        throw new Error("legacy_v1_manifest_timestamp_invalid");
+    }
+    return result;
+}
+function nullableTimestamp(value) {
+    return value === null ? null : timestamp(value);
+}

package/dist/core/events/legacy-storage/reader.d.ts

@@ -0,0 +1,15 @@
+export interface LegacyV1LogicalRow {
+    row_number: number;
+    bytes: Buffer;
+}
+export interface LegacyV1ReaderLimits {
+    max_manifest_bytes?: number;
+    max_payload_bytes?: number;
+    max_decompressed_bytes?: number;
+    max_row_bytes?: number;
+    max_rows?: number;
+    fault?: (boundary: "after_source_digest", path: string) => void;
+}
+/** Stream rows from one loose sealed segment or one manifest-bound gzip canary. */
+export declare function streamLegacyV1Rows(sourcePath: string, limits?: LegacyV1ReaderLimits): AsyncGenerator<LegacyV1LogicalRow>;
+//# sourceMappingURL=reader.d.ts.map

package/dist/core/events/legacy-storage/reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../../../../src/core/events/legacy-storage/reader.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,oBAAoB;IACnC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,qBAAqB,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACjE;AAUD,mFAAmF;AACnF,wBAAuB,kBAAkB,CACvC,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,oBAAyB,GAChC,cAAc,CAAC,kBAAkB,CAAC,CAyFpC"}

package/dist/core/events/legacy-storage/reader.js

@@ -0,0 +1,154 @@
+import { createHash } from "node:crypto";
+import { constants, createReadStream } from "node:fs";
+import { lstat, open, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { createGunzip } from "node:zlib";
+import { validateLegacyV1SegmentManifest } from "./manifest.js";
+const DEFAULTS = {
+    max_manifest_bytes: 1024 * 1024,
+    max_payload_bytes: 8 * 1024 * 1024 * 1024,
+    max_decompressed_bytes: 16 * 1024 * 1024 * 1024,
+    max_row_bytes: 64 * 1024 * 1024,
+    max_rows: 20_000_000,
+};
+/** Stream rows from one loose sealed segment or one manifest-bound gzip canary. */
+export async function* streamLegacyV1Rows(sourcePath, limits = {}) {
+    const bounded = { ...DEFAULTS, ...limits };
+    const source = resolve(sourcePath);
+    let input = source;
+    let expectedRows;
+    let expectedSourceBytes;
+    let expectedSourceDigest;
+    let expectedPayloadBytes;
+    let expectedPayloadDigest;
+    let containmentRoot;
+    if (source.endsWith(".manifest.json")) {
+        const manifestHandle = await openStableRegularFile(source, undefined, "manifest");
+        let manifest;
+        try {
+            const stat = await manifestHandle.stat();
+            if (stat.size > bounded.max_manifest_bytes)
+                throw new Error("legacy_v1_manifest_too_large");
+            manifest = validateLegacyV1SegmentManifest(JSON.parse(await manifestHandle.readFile("utf8")));
+        }
+        finally {
+            await manifestHandle.close();
+        }
+        const directory = await realpath(dirname(source));
+        containmentRoot = directory;
+        input = resolve(directory, manifest.payload.path);
+        expectedRows = manifest.source.row_count;
+        expectedSourceBytes = manifest.source.bytes;
+        expectedSourceDigest = manifest.source.digest;
+        expectedPayloadBytes = manifest.payload.bytes;
+        expectedPayloadDigest = manifest.payload.digest;
+    }
+    const compressed = source.endsWith(".manifest.json") || source.endsWith(".gz");
+    const kind = source.endsWith(".manifest.json") ? "payload" : "segment";
+    const inputHandle = await openStableRegularFile(input, containmentRoot, kind);
+    try {
+        const inputStat = await inputHandle.stat();
+        if (source.endsWith(".manifest.json")) {
+            if (inputStat.size !== expectedPayloadBytes)
+                throw new Error("legacy_v1_payload_length_mismatch");
+            if (inputStat.size > bounded.max_payload_bytes)
+                throw new Error("legacy_v1_payload_too_large");
+            if ((await hashHandle(input, inputHandle)) !== expectedPayloadDigest) {
+                throw new Error("legacy_v1_payload_digest_mismatch");
+            }
+        }
+        limits.fault?.("after_source_digest", input);
+        const file = createReadStream(input, { fd: inputHandle.fd, autoClose: false, start: 0 });
+        const stream = compressed ? file.pipe(createGunzip()) : file;
+        let pending = Buffer.alloc(0);
+        let rows = 0;
+        let decompressed = 0;
+        const sourceHash = createHash("sha256");
+        for await (const current of stream) {
+            const chunk = current;
+            decompressed += chunk.length;
+            sourceHash.update(chunk);
+            if (decompressed > bounded.max_decompressed_bytes) {
+                throw new Error("legacy_v1_decompression_bound_exceeded");
+            }
+            pending = pending.length === 0 ? chunk : Buffer.concat([pending, chunk]);
+            if (pending.length > bounded.max_row_bytes && !pending.includes(0x0a)) {
+                throw new Error("legacy_v1_row_bound_exceeded");
+            }
+            let newline = pending.indexOf(0x0a);
+            while (newline >= 0) {
+                const row = pending.subarray(0, newline);
+                pending = pending.subarray(newline + 1);
+                if (row.length === 0)
+                    throw new Error("legacy_v1_empty_row");
+                if (row.length > bounded.max_row_bytes)
+                    throw new Error("legacy_v1_row_bound_exceeded");
+                rows += 1;
+                if (rows > bounded.max_rows)
+                    throw new Error("legacy_v1_row_count_bound_exceeded");
+                yield { row_number: rows, bytes: Buffer.from(row) };
+                newline = pending.indexOf(0x0a);
+            }
+        }
+        if (pending.length !== 0)
+            throw new Error("legacy_v1_segment_unterminated_or_truncated");
+        if (expectedRows !== undefined && rows !== expectedRows)
+            throw new Error("legacy_v1_row_count_mismatch");
+        if (expectedSourceBytes !== undefined && decompressed !== expectedSourceBytes) {
+            throw new Error("legacy_v1_source_length_mismatch");
+        }
+        const digest = `sha256:${sourceHash.digest("hex")}`;
+        if (expectedSourceDigest !== undefined && digest !== expectedSourceDigest) {
+            throw new Error("legacy_v1_source_digest_mismatch");
+        }
+    }
+    finally {
+        await inputHandle.close();
+    }
+}
+async function hashHandle(path, handle) {
+    const hash = createHash("sha256");
+    const stream = createReadStream(path, { fd: handle.fd, autoClose: false, start: 0 });
+    for await (const current of stream)
+        hash.update(current);
+    return `sha256:${hash.digest("hex")}`;
+}
+async function openStableRegularFile(path, containmentRoot, kind) {
+    const before = await lstat(path);
+    if (!before.isFile() || before.isSymbolicLink())
+        throw new Error(`legacy_v1_${kind}_not_regular`);
+    const beforeReal = await realpath(path);
+    if (containmentRoot)
+        assertContained(containmentRoot, beforeReal);
+    const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const opened = await handle.stat();
+        const after = await lstat(path);
+        const afterReal = await realpath(path);
+        if (!opened.isFile() ||
+            !after.isFile() ||
+            after.isSymbolicLink() ||
+            opened.dev !== before.dev ||
+            opened.ino !== before.ino ||
+            opened.dev !== after.dev ||
+            opened.ino !== after.ino ||
+            beforeReal !== afterReal)
+            throw new Error(`legacy_v1_${kind}_changed_during_open`);
+        if (containmentRoot)
+            assertContained(containmentRoot, afterReal);
+        return handle;
+    }
+    catch (error) {
+        await handle.close();
+        throw error;
+    }
+}
+function assertContained(root, candidate) {
+    const path = relative(root, candidate);
+    if (path === "" ||
+        (path !== ".." &&
+            !path.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) &&
+            !isAbsolute(path)))
+        return;
+    throw new Error("legacy_v1_payload_escape");
+}

package/dist/core/events/v3/archive-retention.d.ts

@@ -0,0 +1,33 @@
+/** Bounded retention for complete, closed Event Ledger V3 epochs. */
+import { type EventLedgerArchivePolicy } from "../../config.js";
+export type EventV3ArchiveClassification = "retained" | "expired" | "over-budget" | "protected-minimum" | "unmanaged" | "symlink" | "unknown";
+export interface EventV3ArchiveEntry {
+    name: string;
+    path: string;
+    relative_path: string;
+    classification: EventV3ArchiveClassification;
+    reason: string;
+    action: "keep" | "would-delete" | "deleted";
+    bytes: number | null;
+    last_modified_at: string | null;
+}
+export interface EventV3ArchiveAutoCleanResult {
+    ran: boolean;
+    reason: "swept" | "disabled" | "fresh" | "no-root";
+    deleted: number;
+    bytes: number;
+}
+export declare function eventV3ArchivesRoot(repoRoot: string): string;
+export declare function inventoryEventV3Archives(repoRoot: string, opts?: {
+    now?: Date;
+    policy?: EventLedgerArchivePolicy;
+}): EventV3ArchiveEntry[];
+export declare function cleanEventV3Archives(repoRoot: string, opts?: {
+    yes?: boolean;
+    now?: Date;
+    policy?: EventLedgerArchivePolicy;
+}): EventV3ArchiveEntry[];
+export declare function autoCleanEventV3Archives(repoRoot: string, opts?: {
+    now?: Date;
+}): EventV3ArchiveAutoCleanResult;
+//# sourceMappingURL=archive-retention.d.ts.map

package/dist/core/events/v3/archive-retention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-retention.d.ts","sourceRoot":"","sources":["../../../../src/core/events/v3/archive-retention.ts"],"names":[],"mappings":"AAAA,qEAAqE;AAYrE,OAAO,EAEL,KAAK,wBAAwB,EAE9B,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,4BAA4B,GACpC,UAAU,GACV,SAAS,GACT,aAAa,GACb,mBAAmB,GACnB,WAAW,GACX,SAAS,GACT,SAAS,CAAC;AAEd,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,4BAA4B,CAAC;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAC;IAC5C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,6BAA6B;IAC5C,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,SAAS,CAAC;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAKD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,IAAI,CAAC;IAAC,MAAM,CAAC,EAAE,wBAAwB,CAAA;CAAO,GAC3D,mBAAmB,EAAE,CA4CvB;AAED,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,CAAC;IAAC,MAAM,CAAC,EAAE,wBAAwB,CAAA;CAAO,GAC1E,mBAAmB,EAAE,CAqCvB;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,IAAI,CAAA;CAAO,GACxB,6BAA6B,CAgC/B"}