harnery 0.35.0 → 0.36.0

package/src/core/storage/maintenance.ts

@@ -0,0 +1,929 @@
+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.ts";
+import type { HarneryStorageCatalog } from "./catalog.ts";
+import {
+  HARNERY_STRUCTURED_LOG_PROVIDER_ID,
+  type HarneryRegisteredStorageFamily,
+} from "./contract.ts";
+
+export const HARNERY_MAINTENANCE_TRANSACTION_SCHEMA =
+  "harnery.storage-maintenance-transaction/v1" as const;
+export const HARNERY_MAINTENANCE_RECEIPT_SCHEMA = "harnery.storage-maintenance-receipt/v1" as const;
+export const HARNERY_MAINTENANCE_CURSOR_SCHEMA = "harnery.storage-maintenance-cursor/v1" as const;
+export const HARNERY_MAINTENANCE_PRESSURE_SCHEMA = "harnery.storage-pressure/v1" as const;
+
+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 interface HarneryMaintenanceBudget {
+  max_duration_ms: number;
+  max_files: number;
+  max_bytes: number;
+}
+
+export interface HarneryStoragePressureFamily {
+  family_id: string;
+  logical_bytes: number;
+  regular_files: number;
+  needs_maintenance: boolean;
+  observed_at: string;
+}
+
+export interface HarneryStoragePressureSummary {
+  schema: typeof HARNERY_MAINTENANCE_PRESSURE_SCHEMA;
+  captured_at: string;
+  families: readonly HarneryStoragePressureFamily[];
+}
+
+export interface HarneryMaintenanceAction {
+  action_id: string;
+  family_id: string;
+  kind: string;
+  target_ref: string;
+  files: number;
+  bytes: number;
+  destructive: boolean;
+  /** Exact provider-owned destructive scope; generic destructive actions are never authorized. */
+  authorization_scope?: string;
+  /** Effective user/source retention policy frozen into the plan. */
+  effective_policy_fingerprint?: string;
+  expected_sha256?: string;
+  metadata?: Readonly<Record<string, string | number | boolean>>;
+}
+
+export interface HarneryMaintenanceProviderPlan {
+  actions: readonly HarneryMaintenanceAction[];
+  next_cursor?: string;
+}
+
+export interface HarneryMaintenanceProvider {
+  family_id: string;
+  /** The sole destructive scope this provider may plan and apply. */
+  destructive_scope?: string;
+  budget?: Partial<HarneryMaintenanceBudget>;
+  plan(input: {
+    coord_root: string;
+    pressure: HarneryStoragePressureFamily;
+    cursor?: string;
+    budget: HarneryMaintenanceBudget;
+    now: Date;
+  }): HarneryMaintenanceProviderPlan | Promise<HarneryMaintenanceProviderPlan>;
+  apply(input: {
+    coord_root: string;
+    transaction_id: string;
+    action: HarneryMaintenanceAction;
+    now: Date;
+  }): HarneryMaintenanceMutation | Promise<HarneryMaintenanceMutation>;
+}
+
+export interface HarneryMaintenanceMutation {
+  outcome: "applied" | "already_applied" | "refused";
+  output_sha256?: string;
+  detail?: string;
+}
+
+export interface HarneryMaintenanceTransaction {
+  schema: typeof HARNERY_MAINTENANCE_TRANSACTION_SCHEMA;
+  transaction_id: string;
+  created_at: string;
+  updated_at: string;
+  state: "planned" | "running" | "committed" | "refused" | "failed";
+  dry_run: boolean;
+  catalog_policies: Readonly<Record<string, string>>;
+  effective_policy_fingerprints: Readonly<Record<string, string>>;
+  budget: HarneryMaintenanceBudget;
+  actions: readonly HarneryMaintenanceAction[];
+  next_cursors: Readonly<Record<string, string>>;
+  reason_codes: readonly string[];
+}
+
+export interface HarneryMaintenanceReceipt {
+  schema: typeof HARNERY_MAINTENANCE_RECEIPT_SCHEMA;
+  transaction_id: string;
+  action_id: string;
+  family_id: string;
+  action_sha256: string;
+  outcome: HarneryMaintenanceMutation["outcome"];
+  output_sha256?: string;
+  detail?: string;
+  committed_at: string;
+}
+
+export interface HarneryAutomaticMaintenanceResult {
+  ran: boolean;
+  reason: "disabled" | "no-pressure" | "fresh" | "contended" | "planned" | "committed";
+  transaction_id?: string;
+  actions: number;
+  files: number;
+  bytes: number;
+}
+
+export const DEFAULT_MAINTENANCE_BUDGET: HarneryMaintenanceBudget = Object.freeze({
+  max_duration_ms: 1_500,
+  max_files: 250,
+  max_bytes: 64 * 1024 * 1024,
+});
+
+export async function planStorageMaintenance(
+  catalog: HarneryStorageCatalog,
+  providers: readonly HarneryMaintenanceProvider[],
+  pressure: HarneryStoragePressureSummary,
+  options: {
+    now?: Date;
+    budget?: HarneryMaintenanceBudget;
+    family_id?: string;
+    persist?: boolean;
+    transaction_id?: string;
+  } = {},
+): Promise<HarneryMaintenanceTransaction> {
+  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: HarneryMaintenanceAction[] = [];
+  const nextCursors: Record<string, string> = {};
+  const reasons = new Set<string>();
+  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: HarneryMaintenanceAction[] = [];
+    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: HarneryMaintenanceTransaction = {
+    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: HarneryStorageCatalog,
+  providers: readonly HarneryMaintenanceProvider[],
+  transactionId: string,
+  options: { yes: boolean; now?: Date; authorize_structured_log_deletion?: boolean },
+): Promise<HarneryMaintenanceTransaction> {
+  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: HarneryStorageCatalog,
+  providers: readonly HarneryMaintenanceProvider[],
+  options: { now?: Date; budget?: HarneryMaintenanceBudget; execute?: boolean } = {},
+): Promise<HarneryAutomaticMaintenanceResult> {
+  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: ReturnType<typeof acquireNoClobberLease>;
+  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: string,
+  transactionId: string,
+): HarneryMaintenanceTransaction {
+  assertSafeId(transactionId, "transaction id");
+  const path = transactionPath(coordRoot, transactionId);
+  const value = readJsonFile(path) as HarneryMaintenanceTransaction;
+  validateTransaction(value);
+  return value;
+}
+
+export function listMaintenanceTransactions(coordRoot: string): HarneryMaintenanceTransaction[] {
+  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: string,
+  summary: HarneryStoragePressureSummary,
+): void {
+  validatePressure(summary);
+  atomicJson(pressurePath(coordRoot), summary, true);
+}
+
+export function readPressureSummary(coordRoot: string): HarneryStoragePressureSummary | undefined {
+  const path = pressurePath(coordRoot);
+  if (!existsSync(path)) return undefined;
+  const summary = readJsonFile(path) as HarneryStoragePressureSummary;
+  validatePressure(summary);
+  return summary;
+}
+
+function providerRegistry(
+  catalog: HarneryStorageCatalog,
+  providers: readonly HarneryMaintenanceProvider[],
+): Map<string, HarneryMaintenanceProvider> {
+  const result = new Map<string, HarneryMaintenanceProvider>();
+  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: HarneryRegisteredStorageFamily): boolean {
+  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: HarneryMaintenanceAction, expectedFamily: string): void {
+  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: HarneryMaintenanceTransaction): void {
+  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: readonly HarneryMaintenanceAction[],
+): Readonly<Record<string, string>> {
+  const result: Record<string, string> = {};
+  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: HarneryStoragePressureSummary): void {
+  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: string,
+  transactionId: string,
+  action: HarneryMaintenanceAction,
+): HarneryMaintenanceReceipt | undefined {
+  const path = receiptPath(coordRoot, transactionId, action.action_id);
+  if (!existsSync(path)) return undefined;
+  const receipt = readJsonFile(path) as HarneryMaintenanceReceipt;
+  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: string,
+  transactionId: string,
+  action: HarneryMaintenanceAction,
+  mutation: HarneryMaintenanceMutation,
+  now: Date,
+): void {
+  const receipt: HarneryMaintenanceReceipt = {
+    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: string,
+  transaction: HarneryMaintenanceTransaction,
+  replace: boolean,
+): void {
+  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: HarneryMaintenanceTransaction,
+  now: Date,
+  state: HarneryMaintenanceTransaction["state"],
+  reasonCodes = transaction.reason_codes,
+): HarneryMaintenanceTransaction {
+  return {
+    ...transaction,
+    updated_at: now.toISOString(),
+    state,
+    dry_run: state === "planned",
+    reason_codes: [...new Set(reasonCodes)].sort(),
+  };
+}
+
+function writeRunOutcome(
+  coordRoot: string,
+  transaction: HarneryMaintenanceTransaction,
+  now: Date,
+): void {
+  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 },
+  );
+}
+
+interface DailyCursor {
+  schema: typeof HARNERY_MAINTENANCE_CURSOR_SCHEMA;
+  state: "running" | "complete";
+  claimed_at: string;
+  transaction_id: string;
+}
+
+function readDailyCursor(coordRoot: string): DailyCursor | undefined {
+  const path = join(resolve(coordRoot), ".harnery", "maintenance", "cursors", "daily.json");
+  if (!existsSync(path)) return undefined;
+  const cursor = readJsonFile(path) as DailyCursor;
+  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: string,
+  now: Date,
+  state: DailyCursor["state"],
+  transactionId: string,
+): void {
+  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: string, familyId: string): string | undefined {
+  const path = join(resolve(coordRoot), ".harnery", "maintenance", "cursors", `${familyId}.json`);
+  if (!existsSync(path)) return undefined;
+  const value = readJsonFile(path) as { schema?: string; cursor?: string };
+  return value.schema === HARNERY_MAINTENANCE_CURSOR_SCHEMA && typeof value.cursor === "string"
+    ? boundedCursor(value.cursor)
+    : undefined;
+}
+
+function writeFamilyCursor(coordRoot: string, familyId: string, cursor: string, now: Date): void {
+  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: string): boolean {
+  const env = process.env.HARNERY_STORAGE_MAINTENANCE?.toLowerCase();
+  return (
+    env === "0" ||
+    env === "false" ||
+    existsSync(join(resolve(coordRoot), ".harnery", "maintenance.disabled"))
+  );
+}
+
+function remainingBudget(
+  budget: HarneryMaintenanceBudget,
+  actions: readonly HarneryMaintenanceAction[],
+  started: number,
+): HarneryMaintenanceBudget {
+  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: HarneryMaintenanceAction,
+  budget: HarneryMaintenanceBudget,
+  actions: readonly HarneryMaintenanceAction[],
+  started: number,
+): boolean {
+  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: HarneryMaintenanceBudget): HarneryMaintenanceBudget {
+  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: HarneryMaintenanceBudget,
+  provider: Partial<HarneryMaintenanceBudget> | undefined,
+): HarneryMaintenanceBudget {
+  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: string): string {
+  if (value.length === 0 || value.length > 2_048)
+    throw new HarneryMaintenanceError("invalid_cursor", "family cursor");
+  return value;
+}
+
+function automaticResult(
+  transaction: HarneryMaintenanceTransaction,
+  reason: "planned" | "committed",
+): HarneryAutomaticMaintenanceResult {
+  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: HarneryAutomaticMaintenanceResult["reason"],
+): HarneryAutomaticMaintenanceResult {
+  return { ran: false, reason, actions: 0, files: 0, bytes: 0 };
+}
+
+function transactionsRoot(coordRoot: string): string {
+  return join(resolve(coordRoot), ".harnery", "maintenance", "transactions");
+}
+
+function transactionPath(coordRoot: string, transactionId: string): string {
+  assertSafeId(transactionId, "transaction id");
+  return join(transactionsRoot(coordRoot), `${transactionId}.json`);
+}
+
+function receiptPath(coordRoot: string, transactionId: string, actionId: string): string {
+  assertSafeId(transactionId, "transaction id");
+  assertSafeId(actionId, "action id");
+  return join(
+    resolve(coordRoot),
+    ".harnery",
+    "maintenance",
+    "receipts",
+    transactionId,
+    `${actionId}.json`,
+  );
+}
+
+function pressurePath(coordRoot: string): string {
+  return join(resolve(coordRoot), ".harnery", "maintenance", "pressure.json");
+}
+
+function readJsonFile(path: string): unknown {
+  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: string, value: unknown, fsync: boolean): void {
+  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: string, value: string): void {
+  const fd = openSync(path, "wx", 0o600);
+  try {
+    writeFileSync(fd, value, "utf8");
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value as Record<string, unknown>)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, child]) => `${JSON.stringify(key)}:${stableJson(child)}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function sha256(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function assertSafeId(value: string, label: string): void {
+  if (typeof value !== "string" || !SAFE_ID.test(value))
+    throw new HarneryMaintenanceError("invalid_id", label);
+}
+
+function assertDate(value: Date): void {
+  if (!Number.isFinite(value.getTime()))
+    throw new HarneryMaintenanceError("invalid_time", "invalid timestamp");
+}
+
+export class HarneryMaintenanceError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = "HarneryMaintenanceError";
+  }
+}