harnery 0.34.1 → 0.36.0

package/dist/core/storage/maintenance.js

@@ -0,0 +1,609 @@
+import { createHash, randomUUID } from "node:crypto";
+import { appendFileSync, closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { acquireNoClobberLease } from "../workflow/workspaces/leases.js";
+import { HARNERY_STRUCTURED_LOG_PROVIDER_ID, } from "./contract.js";
+export const HARNERY_MAINTENANCE_TRANSACTION_SCHEMA = "harnery.storage-maintenance-transaction/v1";
+export const HARNERY_MAINTENANCE_RECEIPT_SCHEMA = "harnery.storage-maintenance-receipt/v1";
+export const HARNERY_MAINTENANCE_CURSOR_SCHEMA = "harnery.storage-maintenance-cursor/v1";
+export const HARNERY_MAINTENANCE_PRESSURE_SCHEMA = "harnery.storage-pressure/v1";
+const SAFE_ID = /^[a-z0-9][a-z0-9._-]{0,127}$/;
+const MAX_JSON_BYTES = 4 * 1024 * 1024;
+const DEFAULT_STALE_MS = 10 * 60 * 1_000;
+const DAY_MS = 24 * 60 * 60 * 1_000;
+export const DEFAULT_MAINTENANCE_BUDGET = Object.freeze({
+    max_duration_ms: 1_500,
+    max_files: 250,
+    max_bytes: 64 * 1024 * 1024,
+});
+export async function planStorageMaintenance(catalog, providers, pressure, options = {}) {
+    const now = options.now ?? new Date();
+    assertDate(now);
+    const budget = validateBudget(options.budget ?? DEFAULT_MAINTENANCE_BUDGET);
+    validatePressure(pressure);
+    const providerMap = providerRegistry(catalog, providers);
+    if (options.family_id && !catalog.get(options.family_id)) {
+        throw new HarneryMaintenanceError("unknown_family", `unknown storage family: ${options.family_id}`);
+    }
+    const started = Date.now();
+    const actions = [];
+    const nextCursors = {};
+    const reasons = new Set();
+    for (const row of pressure.families) {
+        if (!row.needs_maintenance || (options.family_id && row.family_id !== options.family_id))
+            continue;
+        const provider = providerMap.get(row.family_id);
+        if (!provider) {
+            reasons.add(`provider_unavailable:${row.family_id}`);
+            continue;
+        }
+        const family = catalog.require(row.family_id);
+        if (family.provider.maintenance !== "storage") {
+            reasons.add(`maintenance_not_storage_owned:${row.family_id}`);
+            continue;
+        }
+        const remaining = remainingBudget(budget, actions, started);
+        if (remaining.max_duration_ms <= 0 || remaining.max_files <= 0 || remaining.max_bytes <= 0) {
+            reasons.add("global_budget_exhausted");
+            break;
+        }
+        const cursor = readFamilyCursor(catalog.context.coord_root, row.family_id);
+        const providerBudget = intersectBudget(remaining, provider.budget);
+        const providerActions = [];
+        const planned = await provider.plan({
+            coord_root: catalog.context.coord_root,
+            pressure: row,
+            cursor,
+            budget: providerBudget,
+            now,
+        });
+        if (planned.next_cursor !== undefined)
+            nextCursors[row.family_id] = boundedCursor(planned.next_cursor);
+        for (const action of planned.actions) {
+            validateAction(action, row.family_id);
+            if (action.destructive &&
+                (!provider.destructive_scope || action.authorization_scope !== provider.destructive_scope)) {
+                throw new HarneryMaintenanceError("destructive_scope_mismatch", `provider ${row.family_id} did not own destructive scope for ${action.action_id}`);
+            }
+            if (action.authorization_scope === "structured-log-retention" &&
+                !isStructuredLogAuthority(family)) {
+                throw new HarneryMaintenanceError("destructive_provider_mismatch", `family ${row.family_id} is not owned by the structured log provider`);
+            }
+            if (!fitsBudget(action, budget, actions, started) ||
+                !fitsBudget(action, providerBudget, providerActions, started)) {
+                reasons.add("global_budget_exhausted");
+                break;
+            }
+            actions.push(structuredClone(action));
+            providerActions.push(action);
+        }
+    }
+    const transaction = {
+        schema: HARNERY_MAINTENANCE_TRANSACTION_SCHEMA,
+        transaction_id: options.transaction_id ?? `maint-${now.toISOString().slice(0, 10)}-${randomUUID()}`,
+        created_at: now.toISOString(),
+        updated_at: now.toISOString(),
+        state: "planned",
+        dry_run: true,
+        catalog_policies: Object.fromEntries([...new Set(actions.map(({ family_id }) => family_id))].map((familyId) => [
+            familyId,
+            catalog.require(familyId).policy.policy_version,
+        ])),
+        effective_policy_fingerprints: transactionFingerprints(actions),
+        budget,
+        actions,
+        next_cursors: nextCursors,
+        reason_codes: [...reasons].sort(),
+    };
+    validateTransaction(transaction);
+    if (options.persist)
+        writeTransaction(catalog.context.coord_root, transaction, false);
+    return transaction;
+}
+export async function executeStorageMaintenance(catalog, providers, transactionId, options) {
+    if (!options.yes) {
+        throw new HarneryMaintenanceError("confirmation_required", "maintenance execution requires the exact transaction id and --yes");
+    }
+    const now = options.now ?? new Date();
+    assertDate(now);
+    const transaction = readMaintenanceTransaction(catalog.context.coord_root, transactionId);
+    if (transaction.transaction_id !== transactionId) {
+        throw new HarneryMaintenanceError("transaction_mismatch", "transaction id does not match its record");
+    }
+    if (transaction.state === "committed")
+        return transaction;
+    for (const [familyId, version] of Object.entries(transaction.catalog_policies)) {
+        if (catalog.require(familyId).policy.policy_version !== version) {
+            throw new HarneryMaintenanceError("policy_changed", `storage policy changed for ${familyId}`);
+        }
+    }
+    for (const [familyId, fingerprint] of Object.entries(transaction.effective_policy_fingerprints)) {
+        const current = catalog.require(familyId).effective_log_retention;
+        if (current?.state !== "valid" || current.effective_policy_fingerprint !== fingerprint) {
+            throw new HarneryMaintenanceError("effective_policy_changed", `effective log retention policy changed for ${familyId}`);
+        }
+    }
+    const providerMap = providerRegistry(catalog, providers);
+    const unauthorized = transaction.actions.find((action) => {
+        if (!action.destructive)
+            return false;
+        const provider = providerMap.get(action.family_id);
+        const family = catalog.require(action.family_id);
+        return (action.authorization_scope !== "structured-log-retention" ||
+            provider?.destructive_scope !== action.authorization_scope ||
+            !isStructuredLogAuthority(family) ||
+            options.authorize_structured_log_deletion !== true);
+    });
+    if (unauthorized) {
+        const refused = updateTransaction(transaction, now, "refused", [
+            ...transaction.reason_codes,
+            "destructive_activation_required",
+        ]);
+        writeTransaction(catalog.context.coord_root, refused, true);
+        throw new HarneryMaintenanceError("destructive_activation_required", "structured-log deletion requires its provider scope, exact transaction, --yes, and explicit authorization");
+    }
+    let current = updateTransaction(transaction, now, "running");
+    writeTransaction(catalog.context.coord_root, current, true);
+    try {
+        for (const action of current.actions) {
+            const existing = readReceipt(catalog.context.coord_root, current.transaction_id, action);
+            if (existing)
+                continue;
+            const provider = providerMap.get(action.family_id);
+            if (!provider)
+                throw new HarneryMaintenanceError("provider_unavailable", action.family_id);
+            const mutation = await provider.apply({
+                coord_root: catalog.context.coord_root,
+                transaction_id: current.transaction_id,
+                action,
+                now,
+            });
+            writeReceipt(catalog.context.coord_root, current.transaction_id, action, mutation, now);
+        }
+        for (const [familyId, cursor] of Object.entries(current.next_cursors)) {
+            writeFamilyCursor(catalog.context.coord_root, familyId, cursor, now);
+        }
+        current = updateTransaction(current, now, "committed");
+        writeTransaction(catalog.context.coord_root, current, true);
+        writeRunOutcome(catalog.context.coord_root, current, now);
+        return current;
+    }
+    catch (error) {
+        current = updateTransaction(current, now, "failed", [
+            ...current.reason_codes,
+            error instanceof HarneryMaintenanceError ? error.code : "provider_failed",
+        ]);
+        writeTransaction(catalog.context.coord_root, current, true);
+        writeRunOutcome(catalog.context.coord_root, current, now);
+        throw error;
+    }
+}
+export async function runAutomaticMaintenanceSlice(catalog, providers, options = {}) {
+    const now = options.now ?? new Date();
+    assertDate(now);
+    const coordRoot = catalog.context.coord_root;
+    if (maintenanceDisabled(coordRoot))
+        return emptyAutomatic("disabled");
+    const pressure = readPressureSummary(coordRoot);
+    if (!pressure?.families.some(({ needs_maintenance }) => needs_maintenance)) {
+        return emptyAutomatic("no-pressure");
+    }
+    const cursor = readDailyCursor(coordRoot);
+    if (cursor?.state === "complete" && now.getTime() - Date.parse(cursor.claimed_at) < DAY_MS) {
+        return emptyAutomatic("fresh");
+    }
+    const leasePath = join(resolve(coordRoot), ".harnery", "maintenance", "cursors", "daily-lease");
+    let lease;
+    try {
+        lease = acquireNoClobberLease({
+            path: leasePath,
+            scope: "storage-maintenance-daily",
+            authoritySha256: sha256(JSON.stringify(pressure)),
+            staleAfterMs: DEFAULT_STALE_MS,
+            now: () => now.getTime(),
+        });
+    }
+    catch {
+        return emptyAutomatic("contended");
+    }
+    try {
+        const refreshed = readDailyCursor(coordRoot);
+        if (refreshed?.state === "complete" &&
+            now.getTime() - Date.parse(refreshed.claimed_at) < DAY_MS) {
+            return emptyAutomatic("fresh");
+        }
+        if (refreshed?.state === "running" && refreshed.transaction_id) {
+            const resumed = options.execute
+                ? await executeStorageMaintenance(catalog, providers, refreshed.transaction_id, {
+                    yes: true,
+                    now,
+                    authorize_structured_log_deletion: false,
+                })
+                : readMaintenanceTransaction(coordRoot, refreshed.transaction_id);
+            if (resumed.state === "committed")
+                writeDailyCursor(coordRoot, now, "complete", resumed.transaction_id);
+            return automaticResult(resumed, resumed.state === "committed" ? "committed" : "planned");
+        }
+        const transactionId = `auto-${now.toISOString().slice(0, 10)}-${randomUUID()}`;
+        writeDailyCursor(coordRoot, now, "running", transactionId);
+        const transaction = await planStorageMaintenance(catalog, providers, pressure, {
+            now,
+            budget: options.budget,
+            persist: true,
+            transaction_id: transactionId,
+        });
+        if (!options.execute || transaction.actions.length === 0) {
+            writeDailyCursor(coordRoot, now, "complete", transaction.transaction_id);
+            return automaticResult(transaction, "planned");
+        }
+        const committed = await executeStorageMaintenance(catalog, providers, transaction.transaction_id, {
+            yes: true,
+            now,
+            authorize_structured_log_deletion: false,
+        });
+        writeDailyCursor(coordRoot, now, "complete", committed.transaction_id);
+        return automaticResult(committed, "committed");
+    }
+    finally {
+        lease.release();
+    }
+}
+export function readMaintenanceTransaction(coordRoot, transactionId) {
+    assertSafeId(transactionId, "transaction id");
+    const path = transactionPath(coordRoot, transactionId);
+    const value = readJsonFile(path);
+    validateTransaction(value);
+    return value;
+}
+export function listMaintenanceTransactions(coordRoot) {
+    const root = transactionsRoot(coordRoot);
+    if (!existsSync(root))
+        return [];
+    return readdirSync(root)
+        .filter((name) => name.endsWith(".json") && SAFE_ID.test(name.slice(0, -5)))
+        .map((name) => readMaintenanceTransaction(coordRoot, name.slice(0, -5)))
+        .sort((left, right) => right.created_at.localeCompare(left.created_at));
+}
+export function writePressureSummary(coordRoot, summary) {
+    validatePressure(summary);
+    atomicJson(pressurePath(coordRoot), summary, true);
+}
+export function readPressureSummary(coordRoot) {
+    const path = pressurePath(coordRoot);
+    if (!existsSync(path))
+        return undefined;
+    const summary = readJsonFile(path);
+    validatePressure(summary);
+    return summary;
+}
+function providerRegistry(catalog, providers) {
+    const result = new Map();
+    for (const provider of providers) {
+        assertSafeId(provider.family_id, "maintenance provider family id");
+        if (!catalog.get(provider.family_id))
+            throw new HarneryMaintenanceError("unknown_family", provider.family_id);
+        if (result.has(provider.family_id))
+            throw new HarneryMaintenanceError("duplicate_provider", provider.family_id);
+        if (provider.budget)
+            intersectBudget(DEFAULT_MAINTENANCE_BUDGET, provider.budget);
+        if (provider.destructive_scope !== undefined) {
+            assertSafeId(provider.destructive_scope, "maintenance provider destructive scope");
+        }
+        result.set(provider.family_id, provider);
+    }
+    return result;
+}
+function isStructuredLogAuthority(family) {
+    return (family.provider.provider_id === HARNERY_STRUCTURED_LOG_PROVIDER_ID &&
+        (family.storage_class === "operational-log" || family.storage_class === "debug-log") &&
+        family.format === "jsonl");
+}
+function validateAction(action, expectedFamily) {
+    assertSafeId(action.action_id, "action id");
+    assertSafeId(action.family_id, "action family id");
+    if (action.family_id !== expectedFamily)
+        throw new HarneryMaintenanceError("action_family_mismatch", action.action_id);
+    if (!SAFE_ID.test(action.kind) ||
+        typeof action.target_ref !== "string" ||
+        action.target_ref.length > 512) {
+        throw new HarneryMaintenanceError("invalid_action", action.action_id);
+    }
+    if (!Number.isSafeInteger(action.files) ||
+        action.files < 0 ||
+        !Number.isSafeInteger(action.bytes) ||
+        action.bytes < 0) {
+        throw new HarneryMaintenanceError("invalid_action_budget", action.action_id);
+    }
+    if (action.expected_sha256 !== undefined && !/^[a-f0-9]{64}$/.test(action.expected_sha256)) {
+        throw new HarneryMaintenanceError("invalid_action_digest", action.action_id);
+    }
+    if (action.authorization_scope !== undefined) {
+        assertSafeId(action.authorization_scope, "action authorization scope");
+    }
+    if (action.effective_policy_fingerprint !== undefined &&
+        !/^[a-f0-9]{64}$/.test(action.effective_policy_fingerprint)) {
+        throw new HarneryMaintenanceError("invalid_action_policy_fingerprint", action.action_id);
+    }
+    if (action.destructive && !action.authorization_scope) {
+        throw new HarneryMaintenanceError("destructive_scope_required", action.action_id);
+    }
+}
+function validateTransaction(value) {
+    if (value?.schema !== HARNERY_MAINTENANCE_TRANSACTION_SCHEMA)
+        throw new HarneryMaintenanceError("invalid_transaction", "schema");
+    assertSafeId(value.transaction_id, "transaction id");
+    assertDate(new Date(value.created_at));
+    assertDate(new Date(value.updated_at));
+    validateBudget(value.budget);
+    if (!Array.isArray(value.actions) ||
+        !Array.isArray(value.reason_codes) ||
+        !value.effective_policy_fingerprints ||
+        typeof value.effective_policy_fingerprints !== "object" ||
+        Array.isArray(value.effective_policy_fingerprints))
+        throw new HarneryMaintenanceError("invalid_transaction", "arrays");
+    for (const action of value.actions)
+        validateAction(action, action.family_id);
+    for (const [familyId, fingerprint] of Object.entries(value.effective_policy_fingerprints)) {
+        assertSafeId(familyId, "effective policy family id");
+        if (!/^[a-f0-9]{64}$/.test(fingerprint)) {
+            throw new HarneryMaintenanceError("invalid_transaction", "effective policy fingerprint");
+        }
+    }
+    if (stableJson(value.effective_policy_fingerprints) !==
+        stableJson(transactionFingerprints(value.actions))) {
+        throw new HarneryMaintenanceError("invalid_transaction", "effective policy fingerprint binding");
+    }
+    if (new Set(value.actions.map(({ action_id }) => action_id)).size !== value.actions.length) {
+        throw new HarneryMaintenanceError("duplicate_action", value.transaction_id);
+    }
+}
+function transactionFingerprints(actions) {
+    const result = {};
+    for (const action of actions) {
+        const fingerprint = action.effective_policy_fingerprint;
+        if (!fingerprint)
+            continue;
+        const current = result[action.family_id];
+        if (current && current !== fingerprint) {
+            throw new HarneryMaintenanceError("mixed_effective_policy", `maintenance actions mix effective policies for ${action.family_id}`);
+        }
+        result[action.family_id] = fingerprint;
+    }
+    return Object.fromEntries(Object.entries(result).sort(([left], [right]) => left.localeCompare(right)));
+}
+function validatePressure(value) {
+    if (value?.schema !== HARNERY_MAINTENANCE_PRESSURE_SCHEMA || !Array.isArray(value.families)) {
+        throw new HarneryMaintenanceError("invalid_pressure_summary", "unsupported pressure summary");
+    }
+    assertDate(new Date(value.captured_at));
+    for (const row of value.families) {
+        assertSafeId(row.family_id, "pressure family id");
+        if (!Number.isSafeInteger(row.logical_bytes) ||
+            row.logical_bytes < 0 ||
+            !Number.isSafeInteger(row.regular_files) ||
+            row.regular_files < 0) {
+            throw new HarneryMaintenanceError("invalid_pressure_summary", row.family_id);
+        }
+        assertDate(new Date(row.observed_at));
+    }
+}
+function readReceipt(coordRoot, transactionId, action) {
+    const path = receiptPath(coordRoot, transactionId, action.action_id);
+    if (!existsSync(path))
+        return undefined;
+    const receipt = readJsonFile(path);
+    if (receipt.schema !== HARNERY_MAINTENANCE_RECEIPT_SCHEMA ||
+        receipt.transaction_id !== transactionId ||
+        receipt.action_id !== action.action_id ||
+        receipt.action_sha256 !== sha256(stableJson(action))) {
+        throw new HarneryMaintenanceError("receipt_mismatch", action.action_id);
+    }
+    return receipt;
+}
+function writeReceipt(coordRoot, transactionId, action, mutation, now) {
+    const receipt = {
+        schema: HARNERY_MAINTENANCE_RECEIPT_SCHEMA,
+        transaction_id: transactionId,
+        action_id: action.action_id,
+        family_id: action.family_id,
+        action_sha256: sha256(stableJson(action)),
+        outcome: mutation.outcome,
+        output_sha256: mutation.output_sha256,
+        detail: mutation.detail,
+        committed_at: now.toISOString(),
+    };
+    const path = receiptPath(coordRoot, transactionId, action.action_id);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeExclusiveDurable(path, `${JSON.stringify(receipt, null, 2)}\n`);
+}
+function writeTransaction(coordRoot, transaction, replace) {
+    validateTransaction(transaction);
+    const path = transactionPath(coordRoot, transaction.transaction_id);
+    if (!replace && existsSync(path))
+        throw new HarneryMaintenanceError("transaction_exists", transaction.transaction_id);
+    atomicJson(path, transaction, true);
+}
+function updateTransaction(transaction, now, state, reasonCodes = transaction.reason_codes) {
+    return {
+        ...transaction,
+        updated_at: now.toISOString(),
+        state,
+        dry_run: state === "planned",
+        reason_codes: [...new Set(reasonCodes)].sort(),
+    };
+}
+function writeRunOutcome(coordRoot, transaction, now) {
+    const root = join(resolve(coordRoot), ".harnery", "logs", "storage-maintenance");
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    const active = join(root, "active.jsonl");
+    if (existsSync(active) && statSync(active).size > 1_048_576) {
+        renameSync(active, join(root, `sealed-${now.toISOString().replaceAll(/[:.]/g, "-")}.jsonl`));
+    }
+    appendFileSync(active, `${JSON.stringify({ ts: now.toISOString(), transaction_id: transaction.transaction_id, state: transaction.state, actions: transaction.actions.length, files: transaction.actions.reduce((n, action) => n + action.files, 0), bytes: transaction.actions.reduce((n, action) => n + action.bytes, 0), reason_codes: transaction.reason_codes })}\n`, { encoding: "utf8", mode: 0o600 });
+}
+function readDailyCursor(coordRoot) {
+    const path = join(resolve(coordRoot), ".harnery", "maintenance", "cursors", "daily.json");
+    if (!existsSync(path))
+        return undefined;
+    const cursor = readJsonFile(path);
+    if (cursor.schema !== HARNERY_MAINTENANCE_CURSOR_SCHEMA || !SAFE_ID.test(cursor.transaction_id)) {
+        throw new HarneryMaintenanceError("invalid_cursor", "daily cursor");
+    }
+    return cursor;
+}
+function writeDailyCursor(coordRoot, now, state, transactionId) {
+    atomicJson(join(resolve(coordRoot), ".harnery", "maintenance", "cursors", "daily.json"), {
+        schema: HARNERY_MAINTENANCE_CURSOR_SCHEMA,
+        state,
+        claimed_at: now.toISOString(),
+        transaction_id: transactionId,
+    }, true);
+}
+function readFamilyCursor(coordRoot, familyId) {
+    const path = join(resolve(coordRoot), ".harnery", "maintenance", "cursors", `${familyId}.json`);
+    if (!existsSync(path))
+        return undefined;
+    const value = readJsonFile(path);
+    return value.schema === HARNERY_MAINTENANCE_CURSOR_SCHEMA && typeof value.cursor === "string"
+        ? boundedCursor(value.cursor)
+        : undefined;
+}
+function writeFamilyCursor(coordRoot, familyId, cursor, now) {
+    atomicJson(join(resolve(coordRoot), ".harnery", "maintenance", "cursors", `${familyId}.json`), {
+        schema: HARNERY_MAINTENANCE_CURSOR_SCHEMA,
+        family_id: familyId,
+        cursor: boundedCursor(cursor),
+        updated_at: now.toISOString(),
+    }, true);
+}
+function maintenanceDisabled(coordRoot) {
+    const env = process.env.HARNERY_STORAGE_MAINTENANCE?.toLowerCase();
+    return (env === "0" ||
+        env === "false" ||
+        existsSync(join(resolve(coordRoot), ".harnery", "maintenance.disabled")));
+}
+function remainingBudget(budget, actions, started) {
+    return {
+        max_duration_ms: Math.max(0, budget.max_duration_ms - (Date.now() - started)),
+        max_files: Math.max(0, budget.max_files - actions.reduce((n, action) => n + action.files, 0)),
+        max_bytes: Math.max(0, budget.max_bytes - actions.reduce((n, action) => n + action.bytes, 0)),
+    };
+}
+function fitsBudget(action, budget, actions, started) {
+    const remaining = remainingBudget(budget, actions, started);
+    return (remaining.max_duration_ms > 0 &&
+        action.files <= remaining.max_files &&
+        action.bytes <= remaining.max_bytes);
+}
+function validateBudget(value) {
+    for (const [key, amount] of Object.entries(value)) {
+        if (!Number.isSafeInteger(amount) || amount <= 0)
+            throw new HarneryMaintenanceError("invalid_budget", key);
+    }
+    return { ...value };
+}
+function intersectBudget(global, provider) {
+    const result = {
+        max_duration_ms: Math.min(global.max_duration_ms, provider?.max_duration_ms ?? global.max_duration_ms),
+        max_files: Math.min(global.max_files, provider?.max_files ?? global.max_files),
+        max_bytes: Math.min(global.max_bytes, provider?.max_bytes ?? global.max_bytes),
+    };
+    return validateBudget(result);
+}
+function boundedCursor(value) {
+    if (value.length === 0 || value.length > 2_048)
+        throw new HarneryMaintenanceError("invalid_cursor", "family cursor");
+    return value;
+}
+function automaticResult(transaction, reason) {
+    return {
+        ran: true,
+        reason,
+        transaction_id: transaction.transaction_id,
+        actions: transaction.actions.length,
+        files: transaction.actions.reduce((n, action) => n + action.files, 0),
+        bytes: transaction.actions.reduce((n, action) => n + action.bytes, 0),
+    };
+}
+function emptyAutomatic(reason) {
+    return { ran: false, reason, actions: 0, files: 0, bytes: 0 };
+}
+function transactionsRoot(coordRoot) {
+    return join(resolve(coordRoot), ".harnery", "maintenance", "transactions");
+}
+function transactionPath(coordRoot, transactionId) {
+    assertSafeId(transactionId, "transaction id");
+    return join(transactionsRoot(coordRoot), `${transactionId}.json`);
+}
+function receiptPath(coordRoot, transactionId, actionId) {
+    assertSafeId(transactionId, "transaction id");
+    assertSafeId(actionId, "action id");
+    return join(resolve(coordRoot), ".harnery", "maintenance", "receipts", transactionId, `${actionId}.json`);
+}
+function pressurePath(coordRoot) {
+    return join(resolve(coordRoot), ".harnery", "maintenance", "pressure.json");
+}
+function readJsonFile(path) {
+    const metadata = lstatSync(path);
+    if (!metadata.isFile() ||
+        metadata.isSymbolicLink() ||
+        metadata.size <= 0 ||
+        metadata.size > MAX_JSON_BYTES) {
+        throw new HarneryMaintenanceError("unsafe_state_file", basename(path));
+    }
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+function atomicJson(path, value, fsync) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
+    const fd = openSync(temporary, "wx", 0o600);
+    try {
+        writeFileSync(fd, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+        if (fsync)
+            fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(temporary, path);
+}
+function writeExclusiveDurable(path, value) {
+    const fd = openSync(path, "wx", 0o600);
+    try {
+        writeFileSync(fd, value, "utf8");
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, child]) => `${JSON.stringify(key)}:${stableJson(child)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function assertSafeId(value, label) {
+    if (typeof value !== "string" || !SAFE_ID.test(value))
+        throw new HarneryMaintenanceError("invalid_id", label);
+}
+function assertDate(value) {
+    if (!Number.isFinite(value.getTime()))
+        throw new HarneryMaintenanceError("invalid_time", "invalid timestamp");
+}
+export class HarneryMaintenanceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "HarneryMaintenanceError";
+    }
+}

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

@@ -0,0 +1,60 @@
+export interface HarneryLogMetricsDelta {
+    accepted?: number;
+    encoded?: number;
+    appended?: number;
+    synced?: number;
+    dropped?: number;
+    coalesced?: number;
+    sampled?: number;
+    bytes_accepted?: number;
+    bytes_appended?: number;
+    bytes_dropped?: number;
+    rotations?: number;
+    failures?: Record<string, number>;
+    append_latency_ms?: number;
+    flush_latency_ms?: number;
+    queue?: {
+        bytes: number;
+        capacity_bytes: number;
+        peak_bytes: number;
+        snapshot_at: string;
+    };
+}
+export interface HarneryLogMetricsV1 {
+    schema: "harnery.log-metrics/v1";
+    generation: string;
+    window_started_at: string;
+    last_merge_at: string;
+    last_successful_sink_at?: string;
+    counters: {
+        accepted: number;
+        encoded: number;
+        appended: number;
+        synced: number;
+        dropped: number;
+        coalesced: number;
+        sampled: number;
+        bytes_accepted: number;
+        bytes_appended: number;
+        bytes_dropped: number;
+        rotations: number;
+    };
+    failures: Record<string, number>;
+    append_latency_histogram: readonly number[];
+    flush_latency_histogram: readonly number[];
+    queue?: HarneryLogMetricsDelta["queue"];
+}
+export declare class LogMetricsAccumulator {
+    #private;
+    increment<K extends keyof HarneryLogMetricsDelta>(key: K, amount?: number): void;
+    failure(reason: string, amount?: number): void;
+    observeQueue(bytes: number, capacityBytes: number, now: Date): void;
+    observeLatency(kind: "append_latency_ms" | "flush_latency_ms", milliseconds: number): void;
+    take(): HarneryLogMetricsDelta;
+}
+export declare function mergeMetricsSidecar(path: string, delta: HarneryLogMetricsDelta, now?: Date): {
+    merged: boolean;
+    generation_reset: boolean;
+};
+export declare function readMetricsSidecar(path: string): HarneryLogMetricsV1 | undefined;
+//# sourceMappingURL=metrics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../../src/core/storage/metrics.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE;QACN,KAAK,EAAE,MAAM,CAAC;QACd,cAAc,EAAE,MAAM,CAAC;QACvB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,wBAAwB,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,EAAE;QACR,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,cAAc,EAAE,MAAM,CAAC;QACvB,cAAc,EAAE,MAAM,CAAC;QACvB,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,wBAAwB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,uBAAuB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,KAAK,CAAC,EAAE,sBAAsB,CAAC,OAAO,CAAC,CAAC;CACzC;AAID,qBAAa,qBAAqB;;IAIhC,SAAS,CAAC,CAAC,SAAS,MAAM,sBAAsB,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,SAAI,GAAG,IAAI;IAO3E,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,SAAI,GAAG,IAAI;IAMzC,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,IAAI;IAUnE,cAAc,CAAC,IAAI,EAAE,mBAAmB,GAAG,kBAAkB,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI;IAI1F,IAAI,IAAI,sBAAsB;CAM/B;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,sBAAsB,EAC7B,GAAG,OAAa,GACf;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,gBAAgB,EAAE,OAAO,CAAA;CAAE,CAqBhD;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAOhF"}