harnery 0.35.0 → 0.36.0

package/dist/core/events/v3/support-storage/classify.js

@@ -0,0 +1,149 @@
+export const EVENT_V3_SUPPORT_CLASSIFICATION_REASONS = [
+    "active_committed_receipt_deferred",
+    "active_epoch_family_not_enabled",
+    "archive_has_ready_authority_transaction",
+    "authority_lease_live",
+    "authority_ready_active",
+    "command_state_lease_live",
+    "command_state_open",
+    "command_state_pending",
+    "committed_receipt_grace_not_elapsed",
+    "committed_receipt_reconciled",
+    "diagnostic_consumer_window_elapsed",
+    "diagnostic_timestamp_mismatch",
+    "diagnostic_within_loose_window",
+    "epoch_not_enabled_for_maintenance_slice",
+    "event_reference_cross_epoch",
+    "event_reference_unresolved",
+    "file_contract_invalid",
+    "file_not_owner_only",
+    "file_not_regular",
+    "finalization_not_complete",
+    "maintenance_transaction_owns_path",
+    "producer_pending_reference",
+    "recovery_bound_archive_not_enabled",
+    "receipt_digest_mismatch",
+    "receipt_has_ready_sibling",
+    "sealed_terminal_state",
+    "stale_writer_grace_not_elapsed",
+    "transaction_digest_mismatch",
+    "turn_not_sealed",
+    "unknown_support_family",
+];
+export const EVENT_V3_DIAGNOSTIC_CONSUMER_WINDOW_MS = 48 * 60 * 60 * 1000;
+export const EVENT_V3_DIAGNOSTIC_FIXED_GRACE_MS = 24 * 60 * 60 * 1000;
+/** The only disposition decision point for V3 support files. */
+export function classifyEventV3Support(evidence) {
+    if (!evidence.family)
+        return result("unsupported", ["unknown_support_family"]);
+    if (evidence.file_regular === false)
+        return result("quarantine", ["file_not_regular"]);
+    if (evidence.file_owner_only === false)
+        return result("quarantine", ["file_not_owner_only"]);
+    if (evidence.contract_valid === false)
+        return result("quarantine", ["file_contract_invalid"]);
+    if (evidence.maintenance_owned) {
+        return result("live-required", ["maintenance_transaction_owns_path"]);
+    }
+    if (evidence.archive_has_ready_transaction) {
+        return result("quarantine", ["archive_has_ready_authority_transaction"]);
+    }
+    if (evidence.recovery_bound && !evidence.recovery_packing_enabled) {
+        return result("recovery-required", ["recovery_bound_archive_not_enabled"]);
+    }
+    if (!evidence.epoch_maintenance_enabled) {
+        return result("live-required", ["epoch_not_enabled_for_maintenance_slice"]);
+    }
+    switch (evidence.family) {
+        case "diagnostic":
+            return classifyDiagnostic(evidence);
+        case "session-tee":
+            return classifyCommandState(evidence);
+        case "authority-ready":
+            return evidence.authority_state === "active"
+                ? result("recovery-required", ["authority_ready_active"])
+                : result("quarantine", ["archive_has_ready_authority_transaction"]);
+        case "authority-committed":
+            return classifyCommittedReceipt(evidence);
+        case "authority-residue":
+            return result("quarantine", ["file_contract_invalid"]);
+    }
+}
+function classifyDiagnostic(evidence) {
+    if (!evidence.recorded_at || !evidence.filename_recorded_at) {
+        return result("quarantine", ["file_contract_invalid"]);
+    }
+    const recorded = Date.parse(evidence.recorded_at);
+    const filename = Date.parse(evidence.filename_recorded_at);
+    const now = Date.parse(evidence.now);
+    if (![recorded, filename, now].every(Number.isFinite)) {
+        return result("quarantine", ["file_contract_invalid"]);
+    }
+    const tolerance = evidence.writer_tolerance_ms ?? 1000;
+    if (Math.abs(recorded - filename) > tolerance) {
+        return result("quarantine", ["diagnostic_timestamp_mismatch"]);
+    }
+    const consumer = evidence.maximum_loose_consumer_window_ms ?? EVENT_V3_DIAGNOSTIC_CONSUMER_WINDOW_MS;
+    const grace = evidence.fixed_consumer_grace_ms ?? EVENT_V3_DIAGNOSTIC_FIXED_GRACE_MS;
+    if (now - recorded < consumer + grace) {
+        return result("live-required", ["diagnostic_within_loose_window"]);
+    }
+    return result("pack-eligible", ["diagnostic_consumer_window_elapsed"]);
+}
+function classifyCommandState(evidence) {
+    if (evidence.authority_state === "active" && !evidence.active_session_tee_enabled) {
+        return result("live-required", ["active_epoch_family_not_enabled"]);
+    }
+    if (!evidence.terminal)
+        return result("recovery-required", ["command_state_open"]);
+    if (evidence.pending)
+        return result("recovery-required", ["command_state_pending"]);
+    if (!evidence.turn_sealed)
+        return result("recovery-required", ["turn_not_sealed"]);
+    if (!evidence.finalization_complete) {
+        return result("recovery-required", ["finalization_not_complete"]);
+    }
+    if (!evidence.event_references_resolved) {
+        return result("quarantine", ["event_reference_unresolved"]);
+    }
+    if (!evidence.event_references_same_epoch) {
+        return result("quarantine", ["event_reference_cross_epoch"]);
+    }
+    if (evidence.lease_live)
+        return result("recovery-required", ["command_state_lease_live"]);
+    if (!evidence.stale_writer_grace_elapsed) {
+        return result("live-required", ["stale_writer_grace_not_elapsed"]);
+    }
+    return result("pack-eligible", ["sealed_terminal_state"]);
+}
+function classifyCommittedReceipt(evidence) {
+    if (evidence.authority_state === "active" && !evidence.active_committed_receipt_enabled) {
+        return result("live-required", ["active_committed_receipt_deferred"]);
+    }
+    if (evidence.ready_sibling)
+        return result("recovery-required", ["receipt_has_ready_sibling"]);
+    if (evidence.producer_pending_reference) {
+        return result("recovery-required", ["producer_pending_reference"]);
+    }
+    if (!evidence.event_references_resolved) {
+        return result("quarantine", ["event_reference_unresolved"]);
+    }
+    if (!evidence.event_references_same_epoch) {
+        return result("quarantine", ["event_reference_cross_epoch"]);
+    }
+    if (!evidence.event_row_digest_matches) {
+        return result("quarantine", ["receipt_digest_mismatch"]);
+    }
+    if (!evidence.transaction_digest_matches) {
+        return result("quarantine", ["transaction_digest_mismatch"]);
+    }
+    if (evidence.lease_live)
+        return result("recovery-required", ["authority_lease_live"]);
+    if (!evidence.receipt_grace_elapsed) {
+        return result("live-required", ["committed_receipt_grace_not_elapsed"]);
+    }
+    return result("pack-eligible", ["committed_receipt_reconciled"]);
+}
+function result(disposition, reasons) {
+    return { disposition, reasons: [...new Set(reasons)].sort() };
+}

package/dist/core/events/v3/support-storage/eligibility.d.ts

@@ -0,0 +1,29 @@
+import type { EventV3SupportInventoryEntry } from "./inventory.js";
+export interface EventV3AuthorityPackingCandidate {
+    authority_root: string;
+    state: "active" | "archived";
+    genesis_id: string;
+    recovery_receipt_id?: string;
+    has_ready_transaction: boolean;
+    has_pending_producer_state: boolean;
+    has_maintenance_transaction: boolean;
+    regular_file_count: number;
+    entries: EventV3SupportInventoryEntry[];
+}
+export interface EventV3AuthorityPackingGate {
+    eligible: boolean;
+    reasons: string[];
+}
+export declare function assessEventV3AuthorityPackingGate(candidate: EventV3AuthorityPackingCandidate, options?: {
+    allow_active?: boolean;
+    allow_recovery_bound?: boolean;
+}): EventV3AuthorityPackingGate;
+/** Choose one deterministic smallest unbound archive canary; never mutate it. */
+export declare function planEventV3ArchiveCanary(candidates: EventV3AuthorityPackingCandidate[]): {
+    candidate?: EventV3AuthorityPackingCandidate;
+    rejected: Array<{
+        authority_root: string;
+        reasons: string[];
+    }>;
+};
+//# sourceMappingURL=eligibility.d.ts.map

package/dist/core/events/v3/support-storage/eligibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eligibility.d.ts","sourceRoot":"","sources":["../../../../../src/core/events/v3/support-storage/eligibility.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAC;AAEnE,MAAM,WAAW,gCAAgC;IAC/C,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,0BAA0B,EAAE,OAAO,CAAC;IACpC,2BAA2B,EAAE,OAAO,CAAC;IACrC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,4BAA4B,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,wBAAgB,iCAAiC,CAC/C,SAAS,EAAE,gCAAgC,EAC3C,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAC;IAAC,oBAAoB,CAAC,EAAE,OAAO,CAAA;CAAO,GACvE,2BAA2B,CAe7B;AAED,iFAAiF;AACjF,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,gCAAgC,EAAE,GAAG;IACxF,SAAS,CAAC,EAAE,gCAAgC,CAAC;IAC7C,QAAQ,EAAE,KAAK,CAAC;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;CAChE,CAcA"}

package/dist/core/events/v3/support-storage/eligibility.js

@@ -0,0 +1,35 @@
+export function assessEventV3AuthorityPackingGate(candidate, options = {}) {
+    const reasons = [];
+    if (candidate.state === "active" && !options.allow_active)
+        reasons.push("active_epoch_not_enabled");
+    if (candidate.recovery_receipt_id && !options.allow_recovery_bound) {
+        reasons.push("recovery_bound_archive_not_enabled");
+    }
+    if (candidate.has_ready_transaction)
+        reasons.push("ready_authority_transaction_present");
+    if (candidate.has_pending_producer_state)
+        reasons.push("pending_producer_state_present");
+    if (candidate.has_maintenance_transaction)
+        reasons.push("maintenance_transaction_present");
+    if (candidate.entries.length === 0)
+        reasons.push("no_support_files");
+    if (candidate.entries.some((entry) => entry.disposition !== "pack-eligible")) {
+        reasons.push("support_entry_not_pack_eligible");
+    }
+    return { eligible: reasons.length === 0, reasons: reasons.sort() };
+}
+/** Choose one deterministic smallest unbound archive canary; never mutate it. */
+export function planEventV3ArchiveCanary(candidates) {
+    const rejected = [];
+    const eligible = [];
+    for (const candidate of candidates) {
+        const gate = assessEventV3AuthorityPackingGate(candidate);
+        if (gate.eligible)
+            eligible.push(candidate);
+        else
+            rejected.push({ authority_root: candidate.authority_root, reasons: gate.reasons });
+    }
+    eligible.sort((left, right) => left.regular_file_count - right.regular_file_count ||
+        left.authority_root.localeCompare(right.authority_root));
+    return { candidate: eligible[0], rejected };
+}

package/dist/core/events/v3/support-storage/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./classify.js";
+export * from "./eligibility.js";
+export * from "./inventory.js";
+export * from "./logical-authority.js";
+export * from "./maintenance.js";
+export * from "./pack-contract.js";
+export * from "./pack-reader.js";
+export * from "./pack-writer.js";
+export * from "./recovery.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/core/events/v3/support-storage/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC"}

package/dist/core/events/v3/support-storage/index.js

@@ -0,0 +1,9 @@
+export * from "./classify.js";
+export * from "./eligibility.js";
+export * from "./inventory.js";
+export * from "./logical-authority.js";
+export * from "./maintenance.js";
+export * from "./pack-contract.js";
+export * from "./pack-reader.js";
+export * from "./pack-writer.js";
+export * from "./recovery.js";

package/dist/core/events/v3/support-storage/inventory.d.ts

@@ -0,0 +1,30 @@
+import { type EventV3SupportClassificationEvidence, type EventV3SupportDisposition } from "./classify.js";
+import type { EventV3SupportFamily } from "./pack-contract.js";
+export interface EventV3SupportAuthorityIdentity {
+    state: "active" | "archived";
+    epoch_directory?: string;
+    genesis_id?: string;
+    recovery_receipt_id?: string;
+}
+export interface EventV3SupportInventoryEntry {
+    authority: EventV3SupportAuthorityIdentity;
+    family: EventV3SupportFamily;
+    relative_path: string;
+    bytes: number;
+    digest: `sha256:${string}`;
+    disposition: EventV3SupportDisposition;
+    reasons: string[];
+    observed: {
+        recorded_at?: string;
+        modified_at: string;
+    };
+}
+export interface InventoryEventV3SupportInput {
+    authority_root: string;
+    authority: EventV3SupportAuthorityIdentity;
+    now: string;
+    evidence?: Record<string, Omit<EventV3SupportClassificationEvidence, "family" | "authority_state" | "now">>;
+}
+/** Enumerate only V3 support roots, never canonical streams and never symlink targets. */
+export declare function inventoryEventV3Support(input: InventoryEventV3SupportInput): Promise<EventV3SupportInventoryEntry[]>;
+//# sourceMappingURL=inventory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"inventory.d.ts","sourceRoot":"","sources":["../../../../../src/core/events/v3/support-storage/inventory.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,KAAK,oCAAoC,EACzC,KAAK,yBAAyB,EAC/B,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE/D,MAAM,WAAW,+BAA+B;IAC9C,KAAK,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,4BAA4B;IAC3C,SAAS,EAAE,+BAA+B,CAAC;IAC3C,MAAM,EAAE,oBAAoB,CAAC;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,UAAU,MAAM,EAAE,CAAC;IAC3B,WAAW,EAAE,yBAAyB,CAAC;IACvC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE;QACR,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,4BAA4B;IAC3C,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,+BAA+B,CAAC;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CACf,MAAM,EACN,IAAI,CAAC,oCAAoC,EAAE,QAAQ,GAAG,iBAAiB,GAAG,KAAK,CAAC,CACjF,CAAC;CACH;AAQD,0FAA0F;AAC1F,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,4BAA4B,GAClC,OAAO,CAAC,4BAA4B,EAAE,CAAC,CAqEzC"}

package/dist/core/events/v3/support-storage/inventory.js

@@ -0,0 +1,94 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, readdir, realpath } from "node:fs/promises";
+import { basename, join, relative, resolve } from "node:path";
+import { classifyEventV3Support, } from "./classify.js";
+const SUPPORT_ROOTS = [
+    { prefix: "diagnostics", family: "diagnostic" },
+    { prefix: "private-producers/session-tee", family: "session-tee" },
+    { prefix: "authority-outbox", family: "authority-residue" },
+];
+/** Enumerate only V3 support roots, never canonical streams and never symlink targets. */
+export async function inventoryEventV3Support(input) {
+    const root = resolve(input.authority_root);
+    const rootStat = await lstat(root);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+        throw new Error("event_v3_support_inventory_authority_invalid");
+    }
+    const rootReal = await realpath(root);
+    const results = [];
+    for (const support of SUPPORT_ROOTS) {
+        const directory = join(root, ...support.prefix.split("/"));
+        try {
+            const stat = await lstat(directory);
+            if (!stat.isDirectory() || stat.isSymbolicLink()) {
+                throw new Error(`event_v3_support_inventory_root_invalid:${support.prefix}`);
+            }
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue;
+            throw error;
+        }
+        const directoryReal = await realpath(directory);
+        if (relative(rootReal, directoryReal).startsWith("..")) {
+            throw new Error("event_v3_support_inventory_root_escape");
+        }
+        await visit(directory, support.prefix, support.family);
+    }
+    return results.sort((left, right) => left.relative_path.localeCompare(right.relative_path));
+    async function visit(directory, prefix, defaultFamily) {
+        for (const entry of (await readdir(directory, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name))) {
+            const path = join(directory, entry.name);
+            const relativePath = `${prefix}/${entry.name}`;
+            const fileStat = await lstat(path);
+            if (fileStat.isSymbolicLink())
+                throw new Error("event_v3_support_inventory_symlink");
+            if (fileStat.isDirectory()) {
+                await visit(path, relativePath, defaultFamily);
+                continue;
+            }
+            if (!fileStat.isFile())
+                throw new Error("event_v3_support_inventory_special_file");
+            const family = familyFor(relativePath, defaultFamily);
+            const supplied = input.evidence?.[relativePath] ?? {};
+            const classification = classifyEventV3Support({
+                ...supplied,
+                family,
+                authority_state: input.authority.state,
+                now: input.now,
+                file_regular: true,
+                file_owner_only: (fileStat.mode & 0o077) === 0,
+            });
+            results.push({
+                authority: input.authority,
+                family,
+                relative_path: relativePath,
+                bytes: fileStat.size,
+                digest: await hashFile(path),
+                disposition: classification.disposition,
+                reasons: classification.reasons,
+                observed: {
+                    ...(supplied.recorded_at ? { recorded_at: supplied.recorded_at } : {}),
+                    modified_at: fileStat.mtime.toISOString(),
+                },
+            });
+        }
+    }
+}
+function familyFor(path, fallback) {
+    if (fallback !== "authority-residue")
+        return fallback;
+    const name = basename(path);
+    if (name.endsWith(".ready.json"))
+        return "authority-ready";
+    if (name.endsWith(".committed.json"))
+        return "authority-committed";
+    return fallback;
+}
+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/v3/support-storage/logical-authority.d.ts

@@ -0,0 +1,14 @@
+import type { EventV3LogicalAuthorityEntry } from "./pack-contract.js";
+export interface EventV3LogicalAuthorityView {
+    entries: EventV3LogicalAuthorityEntry[];
+    quarantined_packs: Array<{
+        manifest_path: string;
+        reason: string;
+    }>;
+    physical_files: number;
+    packed_entries: number;
+}
+/** Build a pack-aware authority view without following symlinks or granting pack precedence. */
+export declare function iterateEventV3LogicalAuthority(authorityRoot: string): Promise<EventV3LogicalAuthorityView>;
+export declare function digestEventV3LogicalAuthority(authorityRoot: string): Promise<`sha256:${string}`>;
+//# sourceMappingURL=logical-authority.d.ts.map

package/dist/core/events/v3/support-storage/logical-authority.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logical-authority.d.ts","sourceRoot":"","sources":["../../../../../src/core/events/v3/support-storage/logical-authority.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AAGvE,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,4BAA4B,EAAE,CAAC;IACxC,iBAAiB,EAAE,KAAK,CAAC;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpE,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,gGAAgG;AAChG,wBAAsB,8BAA8B,CAClD,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,2BAA2B,CAAC,CAkFtC;AAED,wBAAsB,6BAA6B,CACjD,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,UAAU,MAAM,EAAE,CAAC,CAM7B"}

package/dist/core/events/v3/support-storage/logical-authority.js

@@ -0,0 +1,104 @@
+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";
+import { canonicalJsonV3 } from "../canonical.js";
+import { readEventV3SupportPackManifest, streamEventV3SupportPackRecords } from "./pack-reader.js";
+/** Build a pack-aware authority view without following symlinks or granting pack precedence. */
+export async function iterateEventV3LogicalAuthority(authorityRoot) {
+    const root = resolve(authorityRoot);
+    const rootStat = await lstat(root);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+        throw new Error("event_v3_logical_authority_root_invalid");
+    }
+    const rootReal = await realpath(root);
+    const physical = new Map();
+    const manifests = [];
+    let physicalFiles = 0;
+    const visit = async (directory, prefix) => {
+        const directoryStat = await lstat(directory);
+        if (!directoryStat.isDirectory() || directoryStat.isSymbolicLink()) {
+            throw new Error("event_v3_logical_authority_directory_invalid");
+        }
+        const directoryReal = await realpath(directory);
+        if (relative(rootReal, directoryReal).startsWith("..")) {
+            throw new Error("event_v3_logical_authority_directory_escape");
+        }
+        for (const entry of (await readdir(directory, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name))) {
+            const path = join(directory, entry.name);
+            const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+            const stat = await lstat(path);
+            if (stat.isSymbolicLink())
+                throw new Error("event_v3_logical_authority_symlink");
+            if (stat.isDirectory()) {
+                if (prefix === "" && entry.name === "support-packs") {
+                    for (const candidate of await readdir(path)) {
+                        if (candidate.endsWith(".manifest.json"))
+                            manifests.push(join(path, candidate));
+                    }
+                }
+                else {
+                    await visit(path, relativePath);
+                }
+                continue;
+            }
+            if (!stat.isFile())
+                throw new Error("event_v3_logical_authority_special_file");
+            const digest = await hashFile(path);
+            physical.set(relativePath, { path: relativePath, bytes: stat.size, digest });
+            physicalFiles += 1;
+        }
+    };
+    await visit(root, "");
+    const packedByPath = new Map();
+    const quarantined = [];
+    let packedEntries = 0;
+    for (const manifestPath of manifests.sort()) {
+        await readEventV3SupportPackManifest(manifestPath);
+        const candidate = [];
+        for await (const record of streamEventV3SupportPackRecords(manifestPath)) {
+            const priorPack = packedByPath.get(record.path);
+            if (priorPack)
+                throw new Error(`event_v3_logical_authority_cross_pack_duplicate:${record.path}`);
+            candidate.push({ path: record.path, bytes: record.bytes, digest: record.digest });
+        }
+        const conflict = candidate.find((entry) => {
+            const loose = physical.get(entry.path);
+            return loose && (loose.bytes !== entry.bytes || loose.digest !== entry.digest);
+        });
+        if (conflict) {
+            quarantined.push({
+                manifest_path: manifestPath,
+                reason: `loose_pack_digest_conflict:${conflict.path}`,
+            });
+            continue;
+        }
+        for (const entry of candidate)
+            packedByPath.set(entry.path, { entry, manifest: manifestPath });
+        packedEntries += candidate.length;
+    }
+    const combined = new Map(physical);
+    for (const { entry } of packedByPath.values()) {
+        if (!combined.has(entry.path))
+            combined.set(entry.path, entry);
+    }
+    return {
+        entries: [...combined.values()].sort((left, right) => left.path.localeCompare(right.path)),
+        quarantined_packs: quarantined,
+        physical_files: physicalFiles,
+        packed_entries: packedEntries,
+    };
+}
+export async function digestEventV3LogicalAuthority(authorityRoot) {
+    const view = await iterateEventV3LogicalAuthority(authorityRoot);
+    if (view.quarantined_packs.length > 0) {
+        throw new Error("event_v3_logical_authority_has_quarantined_pack");
+    }
+    return `sha256:${createHash("sha256").update(canonicalJsonV3(view.entries)).digest("hex")}`;
+}
+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/v3/support-storage/maintenance.d.ts

@@ -0,0 +1,98 @@
+import type { EventV3SupportInventoryEntry } from "./inventory.js";
+import type { EventV3SupportFamily, EventV3SupportVerificationMode } from "./pack-contract.js";
+export type EventV3SupportTransactionState = "planned" | "shadow-written" | "shadow-verified" | "replacement-ready" | "replacement-active" | "committed";
+export interface EventV3SupportTransactionSource {
+    relative_path: string;
+    bytes: number;
+    digest: `sha256:${string}`;
+    family: EventV3SupportFamily;
+    recorded_at?: string;
+    diagnostic_category?: string;
+    diagnostic_reason?: string;
+}
+export interface EventV3SupportMaintenanceTransaction {
+    format: "harnery-event-v3-support-maintenance";
+    format_version: 1;
+    transaction_id: `vst_${string}`;
+    sequence: number;
+    state: EventV3SupportTransactionState;
+    created_at: string;
+    updated_at: string;
+    catalog_version: string;
+    policy_version: string;
+    authority: {
+        root: string;
+        root_id: string;
+        genesis_id: string;
+        state: "active" | "archived";
+        verification_mode: EventV3SupportVerificationMode;
+        source_authority_digest?: `sha256:${string}`;
+    };
+    sources: EventV3SupportTransactionSource[];
+    shadow?: {
+        manifest_path: string;
+        payload_path: string;
+        pack_id: `vsp_${string}`;
+    };
+    authorization?: {
+        exact_transaction_id: `vst_${string}`;
+        authorized_at: string;
+    };
+}
+export interface PlanEventV3SupportTransactionInput {
+    transaction_root: string;
+    authority_root: string;
+    root_id: string;
+    genesis_id: string;
+    authority_state: "active" | "archived";
+    source_authority_digest?: `sha256:${string}`;
+    entries: EventV3SupportInventoryEntry[];
+    catalog_version: string;
+    policy_version: string;
+    now: string;
+}
+/** Freeze a content-free exact source set. No pack is written and no source is changed. */
+export declare function planEventV3SupportTransaction(input: PlanEventV3SupportTransactionInput): Promise<EventV3SupportMaintenanceTransaction>;
+export declare function writeEventV3SupportTransactionShadow(input: {
+    transaction_root: string;
+    transaction_id: string;
+    minimum_harnery_version: string;
+    now: string;
+}): Promise<EventV3SupportMaintenanceTransaction>;
+export declare function verifyEventV3SupportTransactionShadow(input: {
+    transaction_root: string;
+    transaction_id: string;
+    expected_current_genesis_id: string;
+    now: string;
+}): Promise<EventV3SupportMaintenanceTransaction>;
+/** Record exact authorization only. Publication and source removal remain disabled. */
+export declare function authorizeEventV3SupportReplacement(input: {
+    transaction_root: string;
+    transaction_id: string;
+    exact_transaction_id: string;
+    yes: boolean;
+    now: string;
+}): Promise<EventV3SupportMaintenanceTransaction>;
+export interface EventV3SupportReplacementPlan {
+    transaction_id: `vst_${string}`;
+    enabled: false;
+    final_manifest_path: string;
+    final_payload_path: string;
+    frozen_source_paths: string[];
+    reason: "event_v3_support_replacement_activation_disabled";
+}
+/** Produce the canary replacement plan without publishing a pack or deleting a source. */
+export declare function planEventV3SupportReplacement(input: {
+    transaction_root: string;
+    transaction_id: string;
+}): Promise<EventV3SupportReplacementPlan>;
+export declare function activateEventV3SupportReplacement(): never;
+export declare function recoverEventV3SupportTransaction(input: {
+    transaction_root: string;
+    transaction_id: string;
+    expected_current_genesis_id: string;
+}): Promise<{
+    action: "write-shadow" | "verify-shadow" | "await-authorization" | "activation-disabled";
+}>;
+export declare function readEventV3SupportTransaction(transactionRoot: string, transactionId: string): Promise<EventV3SupportMaintenanceTransaction>;
+//# sourceMappingURL=maintenance.d.ts.map

package/dist/core/events/v3/support-storage/maintenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance.d.ts","sourceRoot":"","sources":["../../../../../src/core/events/v3/support-storage/maintenance.ts"],"names":[],"mappings":"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"}