harnery 0.35.0 → 0.36.0

package/dist/core/storage/durable-history.js

@@ -0,0 +1,606 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, existsSync, constants as fsConstants, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, realpathSync, renameSync, rmSync, statSync, writeSync, } from "node:fs";
+import { open, rename, rm } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative } from "node:path";
+export const HARNERY_DURABLE_HISTORY_SCHEMA = "harnery.durable-history/v1";
+export function appendDurableHistoryRecord(objectDir, record, options) {
+    validateOptions(options);
+    const line = encodeRecord(record, options.max_record_bytes);
+    ensurePrivateDirectory(objectDir);
+    return withLease(join(objectDir, ".append.lease"), () => {
+        const active = join(objectDir, "active.jsonl");
+        let rotated = false;
+        const activeBytes = regularFileBytes(active);
+        if (activeBytes > 0 && activeBytes + Buffer.byteLength(line) > options.max_segment_bytes) {
+            const segments = join(objectDir, "segments");
+            const segmentDirectory = ensurePrivateDirectory(segments);
+            validateJsonlBeforeSeal(active, options.max_record_bytes);
+            const target = join(segments, nextSegmentName(segments));
+            rejectExistingSymlink(target);
+            renameSync(active, target);
+            assertRegularPath(target, segmentDirectory);
+            syncDirectory(captureDirectoryIdentity(objectDir));
+            syncDirectory(segmentDirectory);
+            options.fault?.("after_segment_rename");
+            rotated = true;
+        }
+        options.fault?.("before_append");
+        appendAndSync(active, line, options.fault, options.write_sync);
+        return {
+            schema: HARNERY_DURABLE_HISTORY_SCHEMA,
+            segment: "active",
+            record_bytes: Buffer.byteLength(line),
+            rotated,
+            synced: true,
+        };
+    });
+}
+export function appendCrashSafeJsonlFile(path, record, maxRecordBytes, fault) {
+    const line = encodeRecord(record, maxRecordBytes);
+    ensurePrivateDirectory(dirname(path));
+    return withLease(`${path}.lease`, () => {
+        fault?.("before_append");
+        appendAndSync(path, line, fault);
+        return Buffer.byteLength(line);
+    });
+}
+export function appendSegmentedJsonlFile(activePath, record, options) {
+    validateOptions(options);
+    const line = encodeRecord(record, options.max_record_bytes);
+    ensurePrivateDirectory(dirname(activePath));
+    return withLease(`${activePath}.segment.lease`, () => {
+        let rotated = false;
+        const activeBytes = regularFileBytes(activePath);
+        if (activeBytes > 0 && activeBytes + Buffer.byteLength(line) > options.max_segment_bytes) {
+            const segments = `${activePath}.segments`;
+            const segmentDirectory = ensurePrivateDirectory(segments);
+            validateJsonlBeforeSeal(activePath, options.max_record_bytes);
+            const target = join(segments, nextSegmentName(segments));
+            rejectExistingSymlink(target);
+            renameSync(activePath, target);
+            assertRegularPath(target, segmentDirectory);
+            syncDirectory(captureDirectoryIdentity(dirname(activePath)));
+            syncDirectory(segmentDirectory);
+            options.fault?.("after_segment_rename");
+            rotated = true;
+        }
+        options.fault?.("before_append");
+        appendAndSync(activePath, line, options.fault, options.write_sync);
+        return {
+            schema: HARNERY_DURABLE_HISTORY_SCHEMA,
+            segment: "active",
+            record_bytes: Buffer.byteLength(line),
+            rotated,
+            synced: true,
+        };
+    });
+}
+export function updateCrashSafeJsonlFile(path, options, update, fault) {
+    ensurePrivateDirectory(dirname(path));
+    return withLease(`${path}.lease`, () => {
+        const records = readCrashSafeJsonlFile(path, options);
+        const decision = update(records);
+        if (decision.append && decision.append.length > 0) {
+            const body = decision.append
+                .map((record) => encodeRecord(record, options.max_record_bytes))
+                .join("");
+            fault?.("before_append");
+            appendAndSync(path, body, fault);
+        }
+        return decision.result;
+    });
+}
+export async function* streamDurableHistory(objectDir, options) {
+    let count = 0;
+    for (const path of durableHistoryPaths(objectDir)) {
+        for await (const line of boundedJsonlLines(path, options.max_record_bytes)) {
+            if (line.length === 0)
+                continue;
+            count += 1;
+            if (options.max_records !== undefined && count > options.max_records) {
+                throw new Error(`durable history exceeds ${options.max_records} records`);
+            }
+            yield parseRecord(line, basename(path), count);
+        }
+    }
+}
+export function readDurableHistorySync(objectDir, options) {
+    const records = [];
+    for (const path of durableHistoryPaths(objectDir)) {
+        const content = completeJsonl(path);
+        for (const line of content.split("\n")) {
+            if (!line)
+                continue;
+            if (Buffer.byteLength(line) + 1 > options.max_record_bytes) {
+                throw new Error(`durable history record exceeds ${options.max_record_bytes} bytes`);
+            }
+            records.push(parseRecord(line, basename(path), records.length + 1));
+            if (options.max_records !== undefined && records.length > options.max_records) {
+                throw new Error(`durable history exceeds ${options.max_records} records`);
+            }
+        }
+    }
+    return records;
+}
+export function readCrashSafeJsonlFile(path, options) {
+    if (!existsSync(path))
+        return [];
+    rejectSymlink(path);
+    const content = completeJsonl(path);
+    const records = [];
+    for (const line of content.split("\n")) {
+        if (!line)
+            continue;
+        if (Buffer.byteLength(line) + 1 > options.max_record_bytes) {
+            throw new Error(`durable history record exceeds ${options.max_record_bytes} bytes`);
+        }
+        records.push(parseRecord(line, basename(path), records.length + 1));
+        if (options.max_records !== undefined && records.length > options.max_records) {
+            throw new Error(`durable history exceeds ${options.max_records} records`);
+        }
+    }
+    return records;
+}
+export function readSegmentedJsonlFileSync(activePath, options) {
+    const records = [];
+    const segments = `${activePath}.segments`;
+    const paths = existsSync(segments)
+        ? readdirSync(segments)
+            .filter((name) => /^\d{8}\.jsonl$/.test(name))
+            .sort()
+            .map((name) => join(segments, name))
+        : [];
+    if (existsSync(activePath))
+        paths.push(activePath);
+    for (const path of paths) {
+        rejectSymlink(path);
+        for (const line of completeJsonl(path).split("\n")) {
+            if (!line)
+                continue;
+            if (Buffer.byteLength(line) + 1 > options.max_record_bytes) {
+                throw new Error(`durable history record exceeds ${options.max_record_bytes} bytes`);
+            }
+            records.push(parseRecord(line, basename(path), records.length + 1));
+            if (options.max_records !== undefined && records.length > options.max_records) {
+                throw new Error(`durable history exceeds ${options.max_records} records`);
+            }
+        }
+    }
+    return records;
+}
+export async function rewriteCrashSafeJsonlFile(path, records, maxRecordBytes, fault) {
+    const body = records.map((record) => encodeRecord(record, maxRecordBytes)).join("");
+    const parent = ensurePrivateDirectory(dirname(path));
+    rejectExistingSymlink(path);
+    const temp = `${path}.rewrite-${process.pid}`;
+    await withLeaseAsync(`${path}.lease`, async () => {
+        const handle = await open(temp, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | noFollowFlag(), 0o600);
+        try {
+            await writeAll(handle, Buffer.from(body, "utf8"));
+            await handle.sync();
+            assertOpenFileIdentity(temp, handle.fd, parent);
+        }
+        finally {
+            await handle.close();
+        }
+        fault?.("after_rewrite_temp_sync");
+        assertDirectoryIdentity(parent);
+        rejectExistingSymlink(path);
+        await rename(temp, path);
+        assertRegularPath(path, parent);
+        syncDirectory(parent);
+        fault?.("after_rewrite_publish");
+    });
+    await rm(temp, { force: true });
+}
+export function durableHistoryPaths(objectDir) {
+    if (!existsSync(objectDir))
+        return [];
+    rejectSymlink(objectDir);
+    const paths = [];
+    const segments = join(objectDir, "segments");
+    if (existsSync(segments)) {
+        captureDirectoryIdentity(segments);
+        rejectSymlink(segments);
+        for (const name of readdirSync(segments).sort()) {
+            if (!/^\d{8}\.jsonl$/.test(name))
+                continue;
+            const path = join(segments, name);
+            rejectSymlink(path);
+            paths.push(path);
+        }
+    }
+    const active = join(objectDir, "active.jsonl");
+    if (existsSync(active)) {
+        rejectSymlink(active);
+        paths.push(active);
+    }
+    return paths;
+}
+function appendAndSync(path, line, fault, writer = nativeWriteSync) {
+    const parent = captureDirectoryIdentity(dirname(path));
+    rejectExistingSymlink(path);
+    const fd = openSync(path, fsConstants.O_RDWR | fsConstants.O_APPEND | fsConstants.O_CREAT | noFollowFlag(), 0o600);
+    try {
+        assertOpenFileIdentity(path, fd, parent);
+        assertCompleteTail(fd, path);
+        writeAllSync(fd, Buffer.from(line, "utf8"), writer);
+        fault?.("after_append_before_sync");
+        fsyncSync(fd);
+        assertOpenFileIdentity(path, fd, parent);
+        syncDirectory(parent);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function ensurePrivateDirectory(path) {
+    mkdirSync(path, { recursive: true, mode: 0o700 });
+    return captureDirectoryIdentity(path);
+}
+function regularFileBytes(path) {
+    if (!existsSync(path))
+        return 0;
+    rejectSymlink(path);
+    const stats = statSync(path);
+    if (!stats.isFile())
+        throw new Error(`durable history path is not a regular file: ${path}`);
+    return stats.size;
+}
+function rejectSymlink(path) {
+    if (lstatSync(path).isSymbolicLink())
+        throw new Error(`durable history rejects symlink: ${path}`);
+}
+function completeJsonl(path) {
+    const parent = captureDirectoryIdentity(dirname(path));
+    rejectExistingSymlink(path);
+    const fd = openSync(path, fsConstants.O_RDONLY | noFollowFlag());
+    let content;
+    try {
+        assertOpenFileIdentity(path, fd, parent);
+        content = readFileSync(fd, "utf8");
+        assertOpenFileIdentity(path, fd, parent);
+    }
+    finally {
+        closeSync(fd);
+    }
+    if (content && !content.endsWith("\n")) {
+        throw new Error(`durable history has a partial record: ${basename(path)}`);
+    }
+    return content;
+}
+function validateJsonlBeforeSeal(path, maximumRecordBytes) {
+    const content = completeJsonl(path);
+    const lines = content.split("\n");
+    lines.pop();
+    for (const [index, line] of lines.entries()) {
+        if (!line)
+            throw new Error(`durable history has malformed JSONL in ${basename(path)}`);
+        if (Buffer.byteLength(line) + 1 > maximumRecordBytes) {
+            throw new Error(`durable history record exceeds ${maximumRecordBytes} bytes`);
+        }
+        parseRecord(line, basename(path), index + 1);
+    }
+}
+async function* boundedJsonlLines(path, maximumRecordBytes) {
+    const parent = captureDirectoryIdentity(dirname(path));
+    rejectExistingSymlink(path);
+    const fd = openSync(path, fsConstants.O_RDONLY | noFollowFlag());
+    let position = 0;
+    let pending = [];
+    let pendingBytes = 0;
+    try {
+        assertOpenFileIdentity(path, fd, parent);
+        while (true) {
+            const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, maximumRecordBytes + 1));
+            const bytesRead = readSync(fd, chunk, 0, chunk.byteLength, position);
+            if (bytesRead === 0)
+                break;
+            const view = chunk.subarray(0, bytesRead);
+            let start = 0;
+            for (let index = 0; index < view.byteLength; index += 1) {
+                if (view[index] !== 10)
+                    continue;
+                const part = view.subarray(start, index);
+                const lineBytes = pendingBytes + part.byteLength + 1;
+                if (lineBytes > maximumRecordBytes) {
+                    throw new Error(`durable history record exceeds ${maximumRecordBytes} bytes`);
+                }
+                if (part.byteLength > 0)
+                    pending.push(part);
+                yield Buffer.concat(pending, pendingBytes + part.byteLength).toString("utf8");
+                pending = [];
+                pendingBytes = 0;
+                start = index + 1;
+            }
+            const tail = view.subarray(start);
+            if (pendingBytes + tail.byteLength >= maximumRecordBytes) {
+                throw new Error(`durable history record exceeds ${maximumRecordBytes} bytes`);
+            }
+            if (tail.byteLength > 0) {
+                pending.push(tail);
+                pendingBytes += tail.byteLength;
+            }
+            position += bytesRead;
+        }
+        if (pendingBytes > 0) {
+            throw new Error(`durable history has a partial record: ${basename(path)}`);
+        }
+        assertOpenFileIdentity(path, fd, parent);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function nextSegmentName(segments) {
+    const last = readdirSync(segments)
+        .filter((name) => /^\d{8}\.jsonl$/.test(name))
+        .sort()
+        .at(-1);
+    const next = last ? Number.parseInt(last.slice(0, 8), 10) + 1 : 1;
+    return `${String(next).padStart(8, "0")}.jsonl`;
+}
+function encodeRecord(record, maxRecordBytes) {
+    if (!Number.isSafeInteger(maxRecordBytes) || maxRecordBytes <= 1) {
+        throw new Error("max_record_bytes must be a positive safe integer");
+    }
+    const line = `${JSON.stringify(record)}\n`;
+    const bytes = Buffer.byteLength(line);
+    if (bytes > maxRecordBytes)
+        throw new Error(`durable history record exceeds ${maxRecordBytes} bytes`);
+    return line;
+}
+function parseRecord(line, file, index) {
+    try {
+        return JSON.parse(line);
+    }
+    catch (error) {
+        throw new Error(`invalid durable history JSON in ${file} record ${index}: ${error.message}`);
+    }
+}
+function validateOptions(options) {
+    if (!Number.isSafeInteger(options.max_record_bytes) ||
+        options.max_record_bytes <= 1 ||
+        !Number.isSafeInteger(options.max_segment_bytes) ||
+        options.max_segment_bytes < options.max_record_bytes) {
+        throw new Error("max_segment_bytes must be a safe integer at least max_record_bytes");
+    }
+}
+function withLease(lease, action) {
+    const owner = acquireLease(lease);
+    try {
+        return action();
+    }
+    finally {
+        releaseOwnedLease(lease, owner);
+    }
+}
+async function withLeaseAsync(lease, action) {
+    const owner = acquireLease(lease);
+    try {
+        return await action();
+    }
+    finally {
+        releaseOwnedLease(lease, owner);
+    }
+}
+const DURABLE_HISTORY_LEASE_STALE_MS = 30_000;
+function acquireLease(lease) {
+    const parent = captureDirectoryIdentity(dirname(lease));
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const owner = {
+            owner_id: randomUUID(),
+            pid: process.pid,
+            acquired_at: new Date().toISOString(),
+        };
+        let claimed;
+        try {
+            mkdirSync(lease, { mode: 0o700 });
+            assertDirectoryWithinParent(lease, parent);
+            claimed = captureDirectoryIdentity(lease);
+            writeOwner(join(lease, "owner.json"), owner);
+            syncDirectory(claimed);
+            return owner;
+        }
+        catch {
+            if (claimed) {
+                try {
+                    assertDirectoryIdentity(claimed);
+                    rmSync(lease, { recursive: true, force: false });
+                }
+                catch {
+                    // Never remove a lease after its directory identity changes.
+                }
+            }
+            if (recoverStaleLease(lease, DURABLE_HISTORY_LEASE_STALE_MS))
+                continue;
+            throw new Error(`durable history lease busy: ${lease}`);
+        }
+    }
+    throw new Error(`durable history lease busy: ${lease}`);
+}
+function writeOwner(path, owner) {
+    const parent = captureDirectoryIdentity(dirname(path));
+    const fd = openSync(path, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | noFollowFlag(), 0o600);
+    try {
+        assertOpenFileIdentity(path, fd, parent);
+        writeAllSync(fd, Buffer.from(`${JSON.stringify(owner)}\n`, "utf8"), nativeWriteSync);
+        fsyncSync(fd);
+        assertOpenFileIdentity(path, fd, parent);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function recoverStaleLease(lease, staleMs) {
+    let leaseIdentity;
+    try {
+        leaseIdentity = captureDirectoryIdentity(lease);
+    }
+    catch {
+        return false;
+    }
+    const ownerPath = join(lease, "owner.json");
+    let raw;
+    try {
+        raw = completeJsonl(ownerPath);
+    }
+    catch {
+        return false;
+    }
+    let owner;
+    try {
+        owner = JSON.parse(raw);
+    }
+    catch {
+        return false;
+    }
+    if (typeof owner.owner_id !== "string" ||
+        owner.owner_id.length === 0 ||
+        !Number.isSafeInteger(owner.pid) ||
+        !Number.isFinite(Date.parse(owner.acquired_at)) ||
+        Date.now() - Date.parse(owner.acquired_at) < staleMs ||
+        processIsAlive(owner.pid)) {
+        return false;
+    }
+    try {
+        assertDirectoryIdentity(leaseIdentity);
+        if (completeJsonl(ownerPath) !== raw)
+            return false;
+        rmSync(lease, { recursive: true, force: false });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function releaseOwnedLease(lease, owner) {
+    try {
+        const current = JSON.parse(completeJsonl(join(lease, "owner.json")));
+        if (current.owner_id !== owner.owner_id)
+            return;
+        rmSync(lease, { recursive: true, force: false });
+    }
+    catch {
+        // A missing or replaced lease does not belong to this operation.
+    }
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}
+function nativeWriteSync(fd, buffer, offset, length) {
+    return writeSync(fd, buffer, offset, length);
+}
+function assertCompleteTail(fd, path) {
+    const stat = fstatSync(fd);
+    if (stat.size === 0)
+        return;
+    const tail = Buffer.allocUnsafe(1);
+    if (readSync(fd, tail, 0, 1, stat.size - 1) !== 1 || tail[0] !== 10) {
+        throw new Error(`durable history has a partial record: ${basename(path)}`);
+    }
+}
+function writeAllSync(fd, buffer, writer) {
+    let offset = 0;
+    while (offset < buffer.byteLength) {
+        const written = writer(fd, buffer, offset, buffer.byteLength - offset);
+        if (!Number.isSafeInteger(written) || written <= 0 || written > buffer.byteLength - offset) {
+            throw new Error("durable history write made no forward progress");
+        }
+        offset += written;
+    }
+}
+async function writeAll(handle, buffer) {
+    let offset = 0;
+    while (offset < buffer.byteLength) {
+        const { bytesWritten } = await handle.write(buffer, offset, buffer.byteLength - offset, null);
+        if (bytesWritten <= 0)
+            throw new Error("durable history write made no forward progress");
+        offset += bytesWritten;
+    }
+}
+function noFollowFlag() {
+    return fsConstants.O_NOFOLLOW ?? 0;
+}
+function rejectExistingSymlink(path) {
+    try {
+        rejectSymlink(path);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+function captureDirectoryIdentity(path) {
+    const stats = lstatSync(path);
+    if (stats.isSymbolicLink())
+        throw new Error(`durable history rejects symlink: ${path}`);
+    if (!stats.isDirectory())
+        throw new Error(`durable history path is not a directory: ${path}`);
+    return { path, real_path: realpathSync(path), dev: stats.dev, ino: stats.ino };
+}
+function assertDirectoryIdentity(identity) {
+    const current = lstatSync(identity.path);
+    if (current.isSymbolicLink() ||
+        !current.isDirectory() ||
+        current.dev !== identity.dev ||
+        current.ino !== identity.ino ||
+        realpathSync(identity.path) !== identity.real_path) {
+        throw new Error(`durable history directory identity changed: ${identity.path}`);
+    }
+}
+function assertDirectoryWithinParent(path, parent) {
+    assertDirectoryIdentity(parent);
+    const child = captureDirectoryIdentity(path);
+    const fromParent = relative(parent.real_path, child.real_path);
+    if (fromParent.startsWith("..") || isAbsolute(fromParent)) {
+        throw new Error(`durable history path escapes parent boundary: ${path}`);
+    }
+}
+function assertRegularPath(path, parent) {
+    const fd = openSync(path, fsConstants.O_RDONLY | noFollowFlag());
+    try {
+        assertOpenFileIdentity(path, fd, parent);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function assertOpenFileIdentity(path, fd, parent) {
+    assertDirectoryIdentity(parent);
+    const opened = fstatSync(fd);
+    const current = lstatSync(path);
+    if (!opened.isFile() ||
+        current.isSymbolicLink() ||
+        !current.isFile() ||
+        opened.dev !== current.dev ||
+        opened.ino !== current.ino) {
+        throw new Error(`durable history path identity changed: ${path}`);
+    }
+    const resolved = realpathSync(path);
+    const fromParent = relative(parent.real_path, resolved);
+    if (fromParent.startsWith("..") || isAbsolute(fromParent)) {
+        throw new Error(`durable history path escapes parent boundary: ${path}`);
+    }
+}
+function syncDirectory(identity) {
+    assertDirectoryIdentity(identity);
+    const fd = openSync(identity.path, fsConstants.O_RDONLY | (fsConstants.O_DIRECTORY ?? 0));
+    try {
+        fsyncSync(fd);
+    }
+    catch (error) {
+        if (!new Set(["EINVAL", "ENOTSUP", "EPERM"]).has(error.code ?? "")) {
+            throw error;
+        }
+    }
+    finally {
+        closeSync(fd);
+    }
+}

package/dist/core/storage/health.d.ts

@@ -0,0 +1,4 @@
+import { type HarneryStorageHealthReport, type HarneryStorageInventoryReport } from "./contract.js";
+/** Project a read-only inventory into reason-coded health without probing bodies. */
+export declare function storageHealth(inventory: HarneryStorageInventoryReport): HarneryStorageHealthReport;
+//# sourceMappingURL=health.d.ts.map

package/dist/core/storage/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../../src/core/storage/health.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,0BAA0B,EAC/B,KAAK,6BAA6B,EACnC,MAAM,eAAe,CAAC;AAWvB,qFAAqF;AACrF,wBAAgB,aAAa,CAC3B,SAAS,EAAE,6BAA6B,GACvC,0BAA0B,CAqB5B"}

package/dist/core/storage/health.js

@@ -0,0 +1,65 @@
+import { HARNERY_STORAGE_HEALTH_SCHEMA, } from "./contract.js";
+const DEGRADED_REASONS = new Set([
+    "hard_link_ambiguous",
+    "overlapping_registration",
+    "special_file_rejected",
+    "symlink_rejected",
+    "unreadable_path",
+    "wrong_root_type",
+]);
+/** Project a read-only inventory into reason-coded health without probing bodies. */
+export function storageHealth(inventory) {
+    const families = inventory.families.map(familyHealth);
+    const issueReasons = inventory.issues.map(({ reason_code }) => reason_code);
+    const reasons = new Set(issueReasons);
+    for (const family of families)
+        for (const reason of family.reason_codes)
+            reasons.add(reason);
+    const status = issueReasons.some((reason) => DEGRADED_REASONS.has(reason)) ||
+        families.some((family) => family.status === "degraded")
+        ? "degraded"
+        : issueReasons.length > 0 || families.some((family) => family.status === "unknown")
+            ? "unknown"
+            : "healthy";
+    return {
+        schema: HARNERY_STORAGE_HEALTH_SCHEMA,
+        captured_at: inventory.captured_at,
+        inventory_schema: inventory.schema,
+        status,
+        reason_codes: [...reasons].sort(),
+        families,
+        issues: inventory.issues,
+    };
+}
+function familyHealth(family) {
+    const reasons = new Set(family.reason_codes);
+    if (family.state === "delegated")
+        reasons.add("delegated_inventory_unavailable");
+    if (family.state === "dormant")
+        reasons.add("root_dormant");
+    for (const reason of family.log_storage?.retention.reason_codes ?? [])
+        reasons.add(reason);
+    const degraded = [...reasons].some((reason) => DEGRADED_REASONS.has(reason));
+    const logDegraded = family.log_storage?.pressure.state === "over_budget" ||
+        family.log_storage?.retention.state === "blocked";
+    const logUnknown = family.log_storage?.pressure.state === "unknown" ||
+        family.log_storage?.retention.state === "unmanaged";
+    return {
+        family_id: family.family_id,
+        policy_version: family.policy_version,
+        status: degraded || logDegraded
+            ? "degraded"
+            : family.state === "dormant" ||
+                family.state === "delegated" ||
+                family.state === "unavailable" ||
+                family.reason_codes.includes("allocated_bytes_unavailable") ||
+                logUnknown
+                ? "unknown"
+                : family.state === "partial"
+                    ? "unknown"
+                    : "healthy",
+        reason_codes: [...reasons].sort(),
+        maintenance: family.maintenance,
+        ...(family.log_storage ? { log_storage: family.log_storage } : {}),
+    };
+}

package/dist/core/storage/index.d.ts

@@ -0,0 +1,16 @@
+export * from "./builtins.js";
+export * from "./catalog.js";
+export * from "./config.js";
+export * from "./contract.js";
+export * from "./durable-history.js";
+export * from "./health.js";
+export * from "./inventory.js";
+export * from "./log-retention.js";
+export * from "./logger.js";
+export * from "./maintenance.js";
+export * from "./maintenance-providers.js";
+export * from "./policy.js";
+export * from "./query.js";
+export * from "./receipts.js";
+export * from "./sink-graph.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/storage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/storage/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC"}