harnery 0.35.0 → 0.36.0

package/dist/core/conversations/query.js

@@ -0,0 +1,280 @@
+import { normalizeConversationRecord } from "./normalize.js";
+export async function queryConversationCatalog(catalog, request) {
+    validateRequest(request);
+    const started = performance.now();
+    const deadline = started + request.budgets.max_wall_ms;
+    const controller = new AbortController();
+    const records = [];
+    const snapshots = [];
+    let decodedBytes = 0;
+    let sourceRecords = 0;
+    let sourceTruncation;
+    const providers = request.provider_id ? [catalog.require(request.provider_id)] : catalog.list();
+    try {
+        providerLoop: for (const provider of providers) {
+            if (!provider.capabilities.can_list || !provider.capabilities.can_stream_source)
+                continue;
+            if (deadlineExpired(deadline)) {
+                sourceTruncation = "wall_budget";
+                break;
+            }
+            let summaries;
+            try {
+                summaries = await beforeDeadline(provider.list(request.project_scope_id, { signal: controller.signal }), deadline, controller);
+            }
+            catch (error) {
+                if (!isWallBudgetError(error))
+                    throw error;
+                sourceTruncation = "wall_budget";
+                break;
+            }
+            for (const summary of summaries) {
+                if (deadlineExpired(deadline)) {
+                    controller.abort();
+                    sourceTruncation = "wall_budget";
+                    break providerLoop;
+                }
+                if (summary.project_scope_id !== request.project_scope_id)
+                    continue;
+                if (request.conversation_id && summary.conversation_id !== request.conversation_id)
+                    continue;
+                let snapshot;
+                try {
+                    snapshot = await beforeDeadline(provider.snapshot(request.project_scope_id, summary.conversation_id, {
+                        signal: controller.signal,
+                    }), deadline, controller);
+                }
+                catch (error) {
+                    if (!isWallBudgetError(error))
+                        throw error;
+                    sourceTruncation = "wall_budget";
+                    break providerLoop;
+                }
+                snapshots.push(snapshot);
+                let sequence = 0;
+                const iterator = provider
+                    .stream(request.project_scope_id, summary.conversation_id, {
+                    signal: controller.signal,
+                })[Symbol.asyncIterator]();
+                let iteratorCompleted = false;
+                try {
+                    while (true) {
+                        if (sourceRecords >= request.budgets.max_source_records) {
+                            sourceTruncation = "record_budget";
+                            break;
+                        }
+                        let next;
+                        try {
+                            next = await beforeDeadline(iterator.next(), deadline, controller);
+                        }
+                        catch (error) {
+                            if (!isWallBudgetError(error))
+                                throw error;
+                            sourceTruncation = "wall_budget";
+                            break;
+                        }
+                        if (next.done) {
+                            iteratorCompleted = true;
+                            break;
+                        }
+                        sourceRecords += 1;
+                        sequence += 1;
+                        const native = next.value;
+                        const rawBytes = typeof native.content === "string" ? Buffer.byteLength(native.content) : 0;
+                        if (decodedBytes + rawBytes > request.budgets.max_decoded_bytes) {
+                            sourceTruncation = "byte_budget";
+                            break;
+                        }
+                        if (deadlineExpired(deadline)) {
+                            controller.abort();
+                            sourceTruncation = "wall_budget";
+                            break;
+                        }
+                        const normalized = normalizeConversationRecord({
+                            capabilities: provider.capabilities,
+                            snapshot,
+                            native,
+                            captured_at: snapshot.observed_at,
+                            sequence,
+                        });
+                        decodedBytes += rawBytes;
+                        if (deadlineExpired(deadline)) {
+                            controller.abort();
+                            sourceTruncation = "wall_budget";
+                            break;
+                        }
+                        if (normalized.record)
+                            records.push(normalized.record);
+                    }
+                }
+                finally {
+                    if (!iteratorCompleted)
+                        requestIteratorReturn(iterator);
+                }
+                if (sourceTruncation)
+                    break providerLoop;
+            }
+        }
+    }
+    finally {
+        if (sourceTruncation)
+            controller.abort();
+    }
+    const result = queryConversationRecords(records, snapshots, request, { started_at: started });
+    if (!sourceTruncation || result.truncated)
+        return result;
+    return { ...result, truncated: true, truncation_reason: sourceTruncation };
+}
+class ConversationWallBudgetError extends Error {
+}
+async function beforeDeadline(operation, deadline, controller) {
+    const remaining = deadline - performance.now();
+    if (remaining <= 0) {
+        controller.abort();
+        throw new ConversationWallBudgetError();
+    }
+    let timer;
+    try {
+        const timeout = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => {
+                controller.abort();
+                reject(new ConversationWallBudgetError());
+            }, remaining);
+        });
+        const result = await Promise.race([operation, timeout]);
+        if (deadlineExpired(deadline)) {
+            controller.abort();
+            throw new ConversationWallBudgetError();
+        }
+        return result;
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+function deadlineExpired(deadline) {
+    return performance.now() >= deadline;
+}
+function isWallBudgetError(error) {
+    return error instanceof ConversationWallBudgetError;
+}
+function requestIteratorReturn(iterator) {
+    try {
+        const returned = iterator.return?.();
+        if (returned)
+            void Promise.resolve(returned).catch(() => undefined);
+    }
+    catch {
+        // A provider cleanup failure cannot widen the query budget or replace its reason code.
+    }
+}
+export function queryConversationRecords(inputRecords, snapshots, request, internal = {}) {
+    validateRequest(request);
+    const started = internal.started_at ?? performance.now();
+    const records = [...inputRecords].sort((left, right) => left.project_scope_id.localeCompare(right.project_scope_id) ||
+        left.provider_id.localeCompare(right.provider_id) ||
+        left.conversation_id.localeCompare(right.conversation_id) ||
+        left.sequence - right.sequence ||
+        left.record_id.localeCompare(right.record_id));
+    const regex = request.regex
+        ? compileRegex(request.regex, request.budgets.max_regex_chars)
+        : undefined;
+    const hits = [];
+    let scannedRecords = 0;
+    let decodedBytes = 0;
+    let truncation;
+    for (let index = 0; index < records.length; index += 1) {
+        const record = records[index];
+        if (!structuredMatch(record, request))
+            continue;
+        if (scannedRecords >= request.budgets.max_source_records) {
+            truncation = "record_budget";
+            break;
+        }
+        if (decodedBytes + record.content_bytes > request.budgets.max_decoded_bytes) {
+            truncation = "byte_budget";
+            break;
+        }
+        if (performance.now() - started > request.budgets.max_wall_ms) {
+            truncation = "wall_budget";
+            break;
+        }
+        scannedRecords += 1;
+        decodedBytes += record.content_bytes;
+        if (request.text && !record.content.includes(request.text))
+            continue;
+        if (regex && !regex.test(record.content))
+            continue;
+        if (hits.length >= Math.min(request.limit, request.budgets.max_matches)) {
+            truncation = "match_budget";
+            break;
+        }
+        hits.push({
+            record,
+            citation: citation(record),
+            neighbors: neighbors(records, index, request.context_before ?? 0, request.context_after ?? 0),
+        });
+    }
+    return {
+        schema: "harnery.conversation-query/v1",
+        request,
+        hits,
+        scanned_records: scannedRecords,
+        decoded_bytes: decodedBytes,
+        truncated: truncation !== undefined,
+        ...(truncation ? { truncation_reason: truncation } : {}),
+        snapshots: [...snapshots].sort((left, right) => left.snapshot_id.localeCompare(right.snapshot_id)),
+    };
+}
+export function citation(record) {
+    return {
+        record_id: record.record_id,
+        provider_id: record.provider_id,
+        conversation_id: record.conversation_id,
+        role: record.role,
+        occurred_at: record.occurred_at,
+        native_conversation_id: record.source.native_conversation_id,
+        ...(record.source.native_record_id ? { native_record_id: record.source.native_record_id } : {}),
+        content_digest: record.content_digest,
+    };
+}
+function structuredMatch(record, request) {
+    return (record.project_scope_id === request.project_scope_id &&
+        (!request.provider_id || record.provider_id === request.provider_id) &&
+        (!request.role || record.role === request.role) &&
+        (!request.session_id || record.session_id === request.session_id) &&
+        (!request.conversation_id || record.conversation_id === request.conversation_id) &&
+        (!request.record_id || record.record_id === request.record_id) &&
+        (!request.since || record.occurred_at >= new Date(request.since).toISOString()) &&
+        (!request.until || record.occurred_at <= new Date(request.until).toISOString()));
+}
+function neighbors(records, index, before, after) {
+    const target = records[index];
+    return records
+        .slice(Math.max(0, index - before), index + after + 1)
+        .filter((record) => record.record_id !== target.record_id &&
+        record.project_scope_id === target.project_scope_id &&
+        record.provider_id === target.provider_id &&
+        record.conversation_id === target.conversation_id);
+}
+function compileRegex(pattern, maxChars) {
+    if (pattern.length === 0 || pattern.length > maxChars)
+        throw new Error("conversation regex limit");
+    if (/\([^)]*[+*][^)]*\)[+*{]/.test(pattern))
+        throw new Error("unsafe nested conversation regex");
+    return new RegExp(pattern, "iu");
+}
+function validateRequest(request) {
+    if (!request.project_scope_id)
+        throw new Error("conversation query requires project_scope_id");
+    for (const [field, value] of Object.entries({ limit: request.limit, ...request.budgets })) {
+        if (!Number.isSafeInteger(value) || value <= 0)
+            throw new Error(`invalid conversation ${field}`);
+    }
+    if (request.role && request.role !== "user" && request.role !== "assistant") {
+        throw new Error("excluded conversation role");
+    }
+    if (request.text && request.regex)
+        throw new Error("conversation query accepts text or regex, not both");
+}

package/dist/core/conversations/search-index.d.ts

@@ -0,0 +1,9 @@
+import type { HarneryConversationRecordV1 } from "./contract.js";
+export interface HarneryConversationSearchIndexV1 {
+    schema: "harnery.conversation-search-index/v1";
+    source_digest: `sha256:${string}`;
+    terms: Readonly<Record<string, readonly string[]>>;
+}
+export declare function buildConversationSearchIndex(records: readonly HarneryConversationRecordV1[]): HarneryConversationSearchIndexV1;
+export declare function verifyIndexedRecords(index: HarneryConversationSearchIndexV1, records: readonly HarneryConversationRecordV1[], term: string): HarneryConversationRecordV1[];
+//# sourceMappingURL=search-index.d.ts.map

package/dist/core/conversations/search-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-index.d.ts","sourceRoot":"","sources":["../../../src/core/conversations/search-index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC;AAGjE,MAAM,WAAW,gCAAgC;IAC/C,MAAM,EAAE,sCAAsC,CAAC;IAC/C,aAAa,EAAE,UAAU,MAAM,EAAE,CAAC;IAClC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;CACpD;AAED,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,SAAS,2BAA2B,EAAE,GAC9C,gCAAgC,CAqBlC;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,gCAAgC,EACvC,OAAO,EAAE,SAAS,2BAA2B,EAAE,EAC/C,IAAI,EAAE,MAAM,GACX,2BAA2B,EAAE,CAS/B"}

package/dist/core/conversations/search-index.js

@@ -0,0 +1,29 @@
+import { digest } from "./normalize.js";
+export function buildConversationSearchIndex(records) {
+    const terms = new Map();
+    const ordered = [...records].sort((left, right) => left.record_id.localeCompare(right.record_id));
+    for (const record of ordered) {
+        for (const term of record.content.toLocaleLowerCase().match(/[\p{L}\p{N}_-]{2,}/gu) ?? []) {
+            const ids = terms.get(term) ?? new Set();
+            ids.add(record.record_id);
+            terms.set(term, ids);
+        }
+    }
+    return {
+        schema: "harnery.conversation-search-index/v1",
+        source_digest: digest(ordered.map((record) => `${record.record_id}:${record.content_digest}`).join("\n")),
+        terms: Object.fromEntries([...terms]
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([term, ids]) => [term, [...ids].sort()])),
+    };
+}
+export function verifyIndexedRecords(index, records, term) {
+    const byId = new Map(records.map((record) => [record.record_id, record]));
+    return (index.terms[term.toLocaleLowerCase()] ?? []).map((id) => {
+        const record = byId.get(id);
+        if (!record?.content.toLocaleLowerCase().includes(term.toLocaleLowerCase())) {
+            throw new Error(`stale conversation index hit: ${id}`);
+        }
+        return record;
+    });
+}

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

@@ -0,0 +1,18 @@
+import { type LegacyV1SegmentManifest } from "./manifest.js";
+export interface LegacyV1CanaryResult {
+    manifest: LegacyV1SegmentManifest;
+    manifest_path: string;
+    payload_path: string;
+    source_unchanged: true;
+    replacement_enabled: false;
+}
+/** Shadow-compress one fenced legacy segment, then prove byte and row parity. */
+export declare function writeLegacyV1Canary(input: {
+    coord_root: string;
+    source_filename: string;
+    output_directory: string;
+    minimum_harnery_version: string;
+    created_at: string;
+}): Promise<LegacyV1CanaryResult>;
+export declare function activateLegacyV1CanaryReplacement(): never;
+//# sourceMappingURL=canary.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"canary.d.ts","sourceRoot":"","sources":["../../../../src/core/events/legacy-storage/canary.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,uBAAuB,EAAmC,MAAM,eAAe,CAAC;AAG9F,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,uBAAuB,CAAC;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,IAAI,CAAC;IACvB,mBAAmB,EAAE,KAAK,CAAC;CAC5B;AAED,iFAAiF;AACjF,wBAAsB,mBAAmB,CAAC,KAAK,EAAE;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,uBAAuB,EAAE,MAAM,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAyFhC;AAED,wBAAgB,iCAAiC,IAAI,KAAK,CAEzD"}

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

@@ -0,0 +1,150 @@
+import { createHash } from "node:crypto";
+import { constants, createReadStream, createWriteStream } from "node:fs";
+import { chmod, lstat, mkdir, open, rename, rm } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { createGzip } from "node:zlib";
+import { canonicalJsonV3 } from "../v3/canonical.js";
+import { verifyLegacyV1HardFence } from "./fence.js";
+import { validateLegacyV1SegmentManifest } from "./manifest.js";
+import { streamLegacyV1Rows } from "./reader.js";
+/** Shadow-compress one fenced legacy segment, then prove byte and row parity. */
+export async function writeLegacyV1Canary(input) {
+    await verifyLegacyV1HardFence(input.coord_root);
+    if (!/^events.+\.ndjson$/.test(input.source_filename) ||
+        input.source_filename.includes("/") ||
+        input.source_filename.includes("\\")) {
+        throw new Error("legacy_v1_canary_source_name_invalid");
+    }
+    const harnery = resolve(input.coord_root, ".harnery");
+    const source = join(harnery, input.source_filename);
+    const sourceStat = await lstat(source);
+    if (!sourceStat.isFile() || sourceStat.isSymbolicLink()) {
+        throw new Error("legacy_v1_canary_source_not_regular");
+    }
+    const sourceDigest = await hashFile(source);
+    const sourceFacts = await inspectRows(source);
+    const segmentId = `v1s_${createHash("sha256")
+        .update(`${input.source_filename}\0${sourceStat.size}\0${sourceDigest}`)
+        .digest("hex")
+        .slice(0, 32)}`;
+    const outputDirectory = resolve(input.output_directory);
+    await mkdir(outputDirectory, { recursive: true, mode: 0o700 });
+    await chmod(outputDirectory, 0o700);
+    const payloadPath = join(outputDirectory, `${segmentId}.ndjson.gz`);
+    const manifestPath = join(outputDirectory, `${segmentId}.manifest.json`);
+    const partialPayload = `${payloadPath}.partial`;
+    const partialManifest = `${manifestPath}.partial`;
+    await rejectExisting([payloadPath, manifestPath, partialPayload, partialManifest]);
+    try {
+        await pipeline(createReadStream(source), createGzip({ level: 9 }), createWriteStream(partialPayload, { flags: "wx", mode: 0o600 }));
+        await rename(partialPayload, payloadPath);
+        const payloadStat = await lstat(payloadPath);
+        const manifest = validateLegacyV1SegmentManifest({
+            format: "harnery-legacy-v1-segment",
+            format_version: 1,
+            segment_id: segmentId,
+            source: {
+                filename: input.source_filename,
+                bytes: sourceStat.size,
+                digest: sourceDigest,
+                row_count: sourceFacts.rows,
+                minimum_recorded_at: sourceFacts.minimum,
+                maximum_recorded_at: sourceFacts.maximum,
+            },
+            payload: {
+                algorithm: "gzip",
+                path: basename(payloadPath),
+                bytes: payloadStat.size,
+                digest: await hashFile(payloadPath),
+            },
+            minimum_harnery_version: input.minimum_harnery_version,
+            created_at: input.created_at,
+        });
+        const handle = await open(partialManifest, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+        try {
+            await handle.writeFile(`${canonicalJsonV3(manifest)}\n`, "utf8");
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(partialManifest, manifestPath);
+        await proveRowParity(source, manifestPath);
+        const after = await lstat(source);
+        if (after.size !== sourceStat.size || (await hashFile(source)) !== sourceDigest) {
+            throw new Error("legacy_v1_canary_source_changed");
+        }
+        return {
+            manifest,
+            manifest_path: manifestPath,
+            payload_path: payloadPath,
+            source_unchanged: true,
+            replacement_enabled: false,
+        };
+    }
+    catch (error) {
+        await rm(partialPayload, { force: true });
+        await rm(partialManifest, { force: true });
+        await rm(payloadPath, { force: true });
+        await rm(manifestPath, { force: true });
+        throw error;
+    }
+}
+export function activateLegacyV1CanaryReplacement() {
+    throw new Error("legacy_v1_replacement_activation_disabled");
+}
+async function inspectRows(path) {
+    let rows = 0;
+    const timestamps = [];
+    for await (const row of streamLegacyV1Rows(path)) {
+        rows += 1;
+        const value = JSON.parse(row.bytes.toString("utf8"));
+        const candidate = typeof value.at === "string"
+            ? value.at
+            : typeof value.timestamp === "string"
+                ? value.timestamp
+                : value.time &&
+                    typeof value.time === "object" &&
+                    typeof value.time.observed_at === "string"
+                    ? value.time.observed_at
+                    : undefined;
+        if (candidate && Number.isFinite(Date.parse(candidate)))
+            timestamps.push(new Date(candidate).toISOString());
+    }
+    timestamps.sort();
+    return { rows, minimum: timestamps[0] ?? null, maximum: timestamps.at(-1) ?? null };
+}
+async function proveRowParity(loose, manifest) {
+    const left = streamLegacyV1Rows(loose)[Symbol.asyncIterator]();
+    const right = streamLegacyV1Rows(manifest)[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_canary_row_count_mismatch");
+            break;
+        }
+        if (!looseRow.value.bytes.equals(packedRow.value.bytes)) {
+            throw new Error(`legacy_v1_canary_row_mismatch:${looseRow.value.row_number}`);
+        }
+    }
+}
+async function hashFile(path) {
+    const hash = createHash("sha256");
+    for await (const current of createReadStream(path))
+        hash.update(current);
+    return `sha256:${hash.digest("hex")}`;
+}
+async function rejectExisting(paths) {
+    for (const path of paths) {
+        try {
+            await lstat(path);
+            throw new Error("legacy_v1_canary_output_exists");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+}

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,6 @@
+export * from "./canary.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,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,5 @@
+export * from "./canary.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"}