harnery 0.35.0 → 0.36.0

package/src/core/storage/inventory.ts

@@ -0,0 +1,859 @@
+import type { Dir, Stats } from "node:fs";
+import {
+  lstat as defaultLstat,
+  opendir as defaultOpendir,
+  realpath as defaultRealpath,
+} from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import type { HarneryStorageCatalog } from "./catalog.ts";
+import {
+  HARNERY_STORAGE_INVENTORY_SCHEMA,
+  type HarneryRegisteredStorageFamily,
+  type HarneryStorageClass,
+  type HarneryStorageFamilyInventory,
+  type HarneryStorageInventoryReport,
+  type HarneryStorageInventoryTotals,
+  type HarneryStorageIssueSummary,
+  type HarneryStorageMeasurement,
+  type HarneryStorageReasonCode,
+  type HarneryStorageRoot,
+  type HarneryStorageRootInventory,
+} from "./contract.ts";
+import { inspectStructuredLogRetention } from "./log-retention.ts";
+
+const MAX_CONCURRENCY = 16;
+
+export interface HarneryStorageInventoryOptions {
+  now?: () => Date;
+  allocatedBytes?: (stats: Stats) => number | undefined;
+  fs?: Partial<HarneryStorageInventoryFs>;
+}
+
+export interface HarneryStorageInventoryFs {
+  lstat(path: string): Promise<Stats>;
+  opendir(path: string): Promise<Dir>;
+  realpath(path: string): Promise<string>;
+}
+
+export interface HarneryStorageInventoryFilter {
+  family_id?: string;
+  storage_class?: HarneryStorageClass;
+}
+
+interface MutableTotals {
+  regular_files: number;
+  logical_bytes: number;
+  allocated_bytes: number;
+  allocated_available: boolean;
+  allocated_identities: Set<string>;
+}
+
+interface RootAccumulator {
+  root: HarneryStorageRoot;
+  index: number;
+  base_present: boolean;
+  matched: boolean;
+  totals: MutableTotals;
+  reasons: Set<HarneryStorageReasonCode>;
+}
+
+interface FamilyAccumulator {
+  family: HarneryRegisteredStorageFamily;
+  roots: RootAccumulator[];
+  totals: MutableTotals;
+  reasons: Set<HarneryStorageReasonCode>;
+}
+
+interface ScanState {
+  catalog: HarneryStorageCatalog;
+  coordStorageRoot: string;
+  families: Map<string, FamilyAccumulator>;
+  totals: MutableTotals;
+  coordinationRootTotals: MutableTotals;
+  externalRootTotals: MutableTotals;
+  issues: Map<HarneryStorageReasonCode, number>;
+  allocatedBytes: (stats: Stats) => number | undefined;
+  fs: HarneryStorageInventoryFs;
+}
+
+interface ScanPath {
+  physical: string;
+  logical: string;
+  expectedIdentity?: FileIdentity;
+}
+
+interface FileIdentity {
+  dev: number;
+  ino: number;
+}
+
+/**
+ * Inventory registered storage with metadata-only, depth-first traversal.
+ * The complete `.harnery` root is scanned once; outside it, only explicit
+ * registered filesystem roots are visited.
+ */
+export async function inventoryStorage(
+  catalog: HarneryStorageCatalog,
+  options: HarneryStorageInventoryOptions = {},
+): Promise<HarneryStorageInventoryReport> {
+  const coordStorageRoot = resolve(catalog.context.coord_root, ".harnery");
+  const capturedAt = (options.now ?? (() => new Date()))();
+  const state: ScanState = {
+    catalog,
+    coordStorageRoot,
+    families: new Map(
+      catalog.families.map((family) => [
+        family.id,
+        {
+          family,
+          roots: family.resolved_roots.map((root, index) => ({
+            root,
+            index,
+            base_present: false,
+            matched: false,
+            totals: emptyTotals(),
+            reasons: new Set(),
+          })),
+          totals: emptyTotals(),
+          reasons: new Set(),
+        },
+      ]),
+    ),
+    totals: emptyTotals(),
+    coordinationRootTotals: emptyTotals(),
+    externalRootTotals: emptyTotals(),
+    issues: new Map(),
+    allocatedBytes: options.allocatedBytes ?? allocatedBytes,
+    fs: {
+      lstat: options.fs?.lstat ?? defaultLstat,
+      opendir: options.fs?.opendir ?? defaultOpendir,
+      realpath: options.fs?.realpath ?? defaultRealpath,
+    },
+  };
+
+  await inspectRegisteredRoots(state);
+  await scanBoundary(state, coordStorageRoot, true);
+  for (const boundary of externalBoundaries(state)) {
+    await scanBoundary(state, boundary, false);
+  }
+
+  return {
+    schema: HARNERY_STORAGE_INVENTORY_SCHEMA,
+    captured_at: capturedAt.toISOString(),
+    privacy: { content_read: false, path_mode: "aggregate-labels" },
+    scan: {
+      mode: "streaming-lstat",
+      max_concurrency: MAX_CONCURRENCY,
+      project_filesystem_scope: ".harnery-and-registered-external-roots",
+    },
+    filter: {},
+    filesystem_totals: observedTotals(state.totals),
+    scope_totals: {
+      coordination_root: observedTotals(state.coordinationRootTotals),
+      registered_external_roots: observedTotals(state.externalRootTotals),
+    },
+    families: [...state.families.values()]
+      .map((family) => familyInventory(catalog, family, capturedAt))
+      .sort((left, right) => left.family_id.localeCompare(right.family_id)),
+    issues: issueRows(state.issues),
+  };
+}
+
+export function filterStorageInventory(
+  report: HarneryStorageInventoryReport,
+  filter: HarneryStorageInventoryFilter,
+): HarneryStorageInventoryReport {
+  return {
+    ...report,
+    filter: {
+      ...(filter.family_id ? { family_id: filter.family_id } : {}),
+      ...(filter.storage_class ? { storage_class: filter.storage_class } : {}),
+    },
+    families: report.families.filter(
+      (family) =>
+        (!filter.family_id || family.family_id === filter.family_id) &&
+        (!filter.storage_class || family.storage_class === filter.storage_class),
+    ),
+  };
+}
+
+function emptyTotals(): MutableTotals {
+  return {
+    regular_files: 0,
+    logical_bytes: 0,
+    allocated_bytes: 0,
+    allocated_available: true,
+    allocated_identities: new Set(),
+  };
+}
+
+async function inspectRegisteredRoots(state: ScanState): Promise<void> {
+  for (const family of state.families.values()) {
+    if (family.family.provider.inventory === "delegated") {
+      family.reasons.add("delegated_inventory_unavailable");
+      for (const root of family.roots) root.reasons.add("delegated_inventory_unavailable");
+      continue;
+    }
+    for (const root of family.roots) {
+      let metadata: Stats;
+      try {
+        metadata = await state.fs.lstat(root.root.path);
+      } catch (error) {
+        if (isMissing(error)) root.reasons.add("root_dormant");
+        else root.reasons.add("unreadable_path");
+        continue;
+      }
+      if (metadata.isSymbolicLink()) {
+        root.reasons.add("symlink_rejected");
+        continue;
+      }
+      const expectedDirectory = root.root.kind === "directory";
+      if (
+        (expectedDirectory && !metadata.isDirectory()) ||
+        (!expectedDirectory && !metadata.isFile())
+      ) {
+        root.reasons.add("wrong_root_type");
+        continue;
+      }
+      root.base_present = true;
+    }
+  }
+}
+
+function externalBoundaries(state: ScanState): string[] {
+  const boundaries = new Set<string>();
+  for (const family of state.families.values()) {
+    if (family.family.provider.inventory !== "filesystem") continue;
+    for (const { root } of family.roots) {
+      if (!within(state.coordStorageRoot, root.path)) boundaries.add(resolve(root.path));
+    }
+  }
+  const ordered = [...boundaries].sort(
+    (left, right) => left.length - right.length || left.localeCompare(right),
+  );
+  const collapsed: string[] = [];
+  for (const boundary of ordered) {
+    if (!collapsed.some((parent) => within(parent, boundary))) collapsed.push(boundary);
+  }
+  return collapsed;
+}
+
+async function scanBoundary(
+  state: ScanState,
+  boundary: string,
+  completeCoordinationRoot: boolean,
+): Promise<void> {
+  let metadata: Stats;
+  try {
+    metadata = await state.fs.lstat(boundary);
+  } catch (error) {
+    if (!isMissing(error)) recordIssue(state, "unreadable_path");
+    return;
+  }
+  if (metadata.isSymbolicLink()) {
+    recordBoundaryIssue(state, boundary, "symlink_rejected", completeCoordinationRoot);
+    return;
+  }
+  if (!metadata.isFile() && !metadata.isDirectory()) {
+    recordBoundaryIssue(state, boundary, "special_file_rejected", completeCoordinationRoot);
+    return;
+  }
+  let safeRoot: string;
+  try {
+    safeRoot = await state.fs.realpath(boundary);
+  } catch {
+    recordBoundaryIssue(state, boundary, "unreadable_path", completeCoordinationRoot);
+    return;
+  }
+  let targetMetadata: Stats;
+  try {
+    targetMetadata = await state.fs.lstat(safeRoot);
+  } catch {
+    recordBoundaryIssue(state, boundary, "unreadable_path", completeCoordinationRoot);
+    return;
+  }
+  if (
+    !sameIdentity(metadata, targetMetadata) ||
+    metadata.isDirectory() !== targetMetadata.isDirectory() ||
+    metadata.isFile() !== targetMetadata.isFile()
+  ) {
+    recordBoundaryIssue(state, boundary, "symlink_rejected", completeCoordinationRoot);
+    return;
+  }
+  if (metadata.isFile()) {
+    await recordRegularFile(
+      state,
+      safeRoot,
+      boundary,
+      metadata,
+      completeCoordinationRoot,
+      safeRoot,
+    );
+    return;
+  }
+  await scanDirectoryTree(state, safeRoot, boundary, metadata, completeCoordinationRoot);
+}
+
+async function scanDirectoryTree(
+  state: ScanState,
+  safeRoot: string,
+  logicalRoot: string,
+  rootMetadata: Stats,
+  completeCoordinationRoot: boolean,
+): Promise<void> {
+  const queue: ScanPath[] = [
+    {
+      physical: safeRoot,
+      logical: logicalRoot,
+      expectedIdentity: fileIdentity(rootMetadata),
+    },
+  ];
+  for (let index = 0; index < queue.length; index += 1) {
+    const current = queue[index]!;
+    const children = await scanDirectory(
+      state,
+      current.physical,
+      current.logical,
+      current.expectedIdentity,
+      safeRoot,
+      completeCoordinationRoot,
+    );
+    queue.push(...children);
+  }
+}
+
+async function scanDirectory(
+  state: ScanState,
+  directoryPath: string,
+  logicalDirectoryPath: string,
+  expectedIdentity: FileIdentity | undefined,
+  safeRoot: string,
+  completeCoordinationRoot: boolean,
+): Promise<ScanPath[]> {
+  let metadata: Stats;
+  try {
+    metadata = await state.fs.lstat(directoryPath);
+  } catch {
+    recordPathIssue(state, logicalDirectoryPath, "unreadable_path", completeCoordinationRoot);
+    return [];
+  }
+  if (metadata.isSymbolicLink()) {
+    recordPathIssue(state, logicalDirectoryPath, "symlink_rejected", completeCoordinationRoot);
+    return [];
+  }
+  if (expectedIdentity && !matchesIdentity(metadata, expectedIdentity)) {
+    recordPathIssue(state, logicalDirectoryPath, "symlink_rejected", completeCoordinationRoot);
+    return [];
+  }
+  if (!metadata.isDirectory()) {
+    recordPathIssue(state, logicalDirectoryPath, "wrong_root_type", completeCoordinationRoot);
+    return [];
+  }
+  let canonical: string;
+  try {
+    canonical = await state.fs.realpath(directoryPath);
+  } catch {
+    recordPathIssue(state, logicalDirectoryPath, "unreadable_path", completeCoordinationRoot);
+    return [];
+  }
+  if (!within(safeRoot, canonical)) {
+    recordPathIssue(state, logicalDirectoryPath, "symlink_rejected", completeCoordinationRoot);
+    return [];
+  }
+  let canonicalMetadata: Stats;
+  try {
+    canonicalMetadata = await state.fs.lstat(canonical);
+  } catch {
+    recordPathIssue(state, logicalDirectoryPath, "unreadable_path", completeCoordinationRoot);
+    return [];
+  }
+  if (!canonicalMetadata.isDirectory() || !sameIdentity(metadata, canonicalMetadata)) {
+    recordPathIssue(state, logicalDirectoryPath, "symlink_rejected", completeCoordinationRoot);
+    return [];
+  }
+  let directory: Dir;
+  try {
+    directory = await state.fs.opendir(canonical);
+  } catch {
+    recordPathIssue(state, logicalDirectoryPath, "unreadable_path", completeCoordinationRoot);
+    return [];
+  }
+  try {
+    const [revalidatedPath, revalidatedCanonical] = await Promise.all([
+      state.fs.lstat(directoryPath),
+      state.fs.lstat(canonical),
+    ]);
+    if (
+      revalidatedPath.isSymbolicLink() ||
+      !sameIdentity(metadata, revalidatedPath) ||
+      !sameIdentity(metadata, revalidatedCanonical)
+    ) {
+      await closeRejectedDirectory(directory);
+      recordPathIssue(state, logicalDirectoryPath, "symlink_rejected", completeCoordinationRoot);
+      return [];
+    }
+  } catch {
+    await closeRejectedDirectory(directory);
+    recordPathIssue(state, logicalDirectoryPath, "unreadable_path", completeCoordinationRoot);
+    return [];
+  }
+  const childDirectories: ScanPath[] = [];
+  let batch: ScanPath[] = [];
+  for await (const entry of directory) {
+    batch.push({
+      physical: join(canonical, entry.name),
+      logical: join(logicalDirectoryPath, entry.name),
+    });
+    if (batch.length === MAX_CONCURRENCY) {
+      childDirectories.push(
+        ...(await scanEntryBatch(state, batch, safeRoot, completeCoordinationRoot)),
+      );
+      batch = [];
+    }
+  }
+  if (batch.length > 0) {
+    childDirectories.push(
+      ...(await scanEntryBatch(state, batch, safeRoot, completeCoordinationRoot)),
+    );
+  }
+  return childDirectories;
+}
+
+async function scanEntryBatch(
+  state: ScanState,
+  paths: readonly ScanPath[],
+  safeRoot: string,
+  completeCoordinationRoot: boolean,
+): Promise<ScanPath[]> {
+  const children = await Promise.all(
+    paths.map((path) => scanEntry(state, path, safeRoot, completeCoordinationRoot)),
+  );
+  return children.filter((path): path is ScanPath => path !== undefined);
+}
+
+async function scanEntry(
+  state: ScanState,
+  path: ScanPath,
+  safeRoot: string,
+  completeCoordinationRoot: boolean,
+): Promise<ScanPath | undefined> {
+  let child: Stats;
+  try {
+    child = await state.fs.lstat(path.physical);
+  } catch {
+    recordPathIssue(state, path.logical, "unreadable_path", completeCoordinationRoot);
+    return undefined;
+  }
+  if (child.isSymbolicLink()) {
+    if (!allowsSymbolicLinkSkip(state, path.logical)) {
+      recordPathIssue(state, path.logical, "symlink_rejected", completeCoordinationRoot);
+    }
+  } else if (child.isDirectory()) {
+    return { ...path, expectedIdentity: fileIdentity(child) };
+  } else if (child.isFile()) {
+    await recordRegularFile(
+      state,
+      path.physical,
+      path.logical,
+      child,
+      completeCoordinationRoot,
+      safeRoot,
+    );
+  } else {
+    recordPathIssue(state, path.logical, "special_file_rejected", completeCoordinationRoot);
+  }
+  return undefined;
+}
+
+async function closeRejectedDirectory(directory: Dir): Promise<void> {
+  try {
+    await directory.close();
+  } catch {
+    // Rejection remains fail-closed even when the platform already closed it.
+  }
+}
+
+function sameIdentity(left: Stats, right: Stats): boolean {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+function fileIdentity(stats: Stats): FileIdentity {
+  return { dev: stats.dev, ino: stats.ino };
+}
+
+function matchesIdentity(stats: Stats, identity: FileIdentity): boolean {
+  return stats.dev === identity.dev && stats.ino === identity.ino;
+}
+
+async function recordRegularFile(
+  state: ScanState,
+  physicalPath: string,
+  logicalPath: string,
+  metadata: Stats,
+  completeCoordinationRoot: boolean,
+  safeRoot: string,
+): Promise<void> {
+  let canonical: string;
+  let canonicalMetadata: Stats;
+  try {
+    canonical = await state.fs.realpath(physicalPath);
+    canonicalMetadata = await state.fs.lstat(canonical);
+  } catch {
+    recordPathIssue(state, logicalPath, "unreadable_path", completeCoordinationRoot);
+    return;
+  }
+  if (!within(safeRoot, canonical) || !sameIdentity(metadata, canonicalMetadata)) {
+    recordPathIssue(state, logicalPath, "symlink_rejected", completeCoordinationRoot);
+    return;
+  }
+  const matches = filesystemMatches(state, logicalPath);
+  if (!completeCoordinationRoot && matches.length === 0) return;
+  const hardLinkAmbiguous = metadata.nlink > 1 && !allowsHardLink(state, logicalPath);
+  if (hardLinkAmbiguous) recordIssue(state, "hard_link_ambiguous");
+  const allocatedCandidate = state.allocatedBytes(metadata);
+  const allocated =
+    allocatedCandidate !== undefined &&
+    Number.isSafeInteger(allocatedCandidate) &&
+    allocatedCandidate >= 0
+      ? allocatedCandidate
+      : undefined;
+  const allocationIdentity = metadata.nlink > 1 ? fileIdentity(metadata) : undefined;
+  addFile(state.totals, metadata.size, allocated, allocationIdentity);
+  addFile(
+    completeCoordinationRoot ? state.coordinationRootTotals : state.externalRootTotals,
+    metadata.size,
+    allocated,
+    allocationIdentity,
+  );
+  if (allocated === undefined) recordIssue(state, "allocated_bytes_unavailable");
+  if (matches.length === 0) {
+    const exclusion = state.catalog.exclusions.some(({ root }) => rootMatches(root, logicalPath));
+    recordIssue(state, exclusion ? "host_exclusion" : "unregistered_path");
+    return;
+  }
+  if (matches.length > 1) {
+    recordIssue(state, "overlapping_registration");
+    for (const match of matches) match.reasons.add("overlapping_registration");
+    return;
+  }
+  const family = matches[0]!;
+  const roots = family.roots.filter(({ root }) => rootMatches(root, logicalPath));
+  if (roots.length !== 1) {
+    recordIssue(state, "overlapping_registration");
+    family.reasons.add("overlapping_registration");
+    return;
+  }
+  addFile(family.totals, metadata.size, allocated, allocationIdentity);
+  family.roots[roots[0]!.index]!.matched = true;
+  addFile(family.roots[roots[0]!.index]!.totals, metadata.size, allocated, allocationIdentity);
+  if (hardLinkAmbiguous) {
+    family.reasons.add("hard_link_ambiguous");
+    family.roots[roots[0]!.index]!.reasons.add("hard_link_ambiguous");
+  }
+  if (allocated === undefined) {
+    family.reasons.add("allocated_bytes_unavailable");
+    family.roots[roots[0]!.index]!.reasons.add("allocated_bytes_unavailable");
+  }
+}
+
+function recordPathIssue(
+  state: ScanState,
+  path: string,
+  reason: HarneryStorageReasonCode,
+  completeCoordinationRoot: boolean,
+): void {
+  const matches = filesystemMatches(state, path);
+  if (!completeCoordinationRoot && matches.length === 0) return;
+  recordIssue(state, reason);
+  if (matches.length === 0 && completeCoordinationRoot) recordIssue(state, "unregistered_path");
+  for (const family of matches) {
+    family.reasons.add(reason);
+    for (const root of family.roots.filter(({ root }) => rootMatches(root, path))) {
+      root.reasons.add(reason);
+    }
+  }
+}
+
+function recordBoundaryIssue(
+  state: ScanState,
+  path: string,
+  reason: HarneryStorageReasonCode,
+  completeCoordinationRoot: boolean,
+): void {
+  const resolved = resolve(path);
+  const matches = [...state.families.values()].filter(
+    (family) =>
+      family.family.provider.inventory === "filesystem" &&
+      family.roots.some(({ root }) => resolve(root.path) === resolved),
+  );
+  recordIssue(state, reason);
+  if (matches.length === 0 && completeCoordinationRoot) recordIssue(state, "unregistered_path");
+  for (const family of matches) {
+    family.reasons.add(reason);
+    for (const root of family.roots.filter(({ root }) => resolve(root.path) === resolved)) {
+      root.reasons.add(reason);
+    }
+  }
+}
+
+function filesystemMatches(state: ScanState, path: string): FamilyAccumulator[] {
+  return state.catalog
+    .familiesForPath(path)
+    .filter((family) => family.provider.inventory === "filesystem")
+    .map((family) => state.families.get(family.id)!);
+}
+
+function addFile(
+  totals: MutableTotals,
+  logicalBytes: number,
+  allocated: number | undefined,
+  allocationIdentity: FileIdentity | undefined,
+): void {
+  totals.regular_files += 1;
+  totals.logical_bytes += logicalBytes;
+  if (allocated === undefined || !Number.isSafeInteger(allocated) || allocated < 0) {
+    totals.allocated_available = false;
+  } else {
+    const key = allocationIdentity
+      ? `${allocationIdentity.dev}:${allocationIdentity.ino}`
+      : undefined;
+    if (key === undefined || !totals.allocated_identities.has(key)) {
+      if (key !== undefined) totals.allocated_identities.add(key);
+      totals.allocated_bytes += allocated;
+    }
+  }
+}
+
+function allowsSymbolicLinkSkip(state: ScanState, path: string): boolean {
+  return matchingRoot(state, path)?.root.link_handling?.symbolic_links === "skip";
+}
+
+function allowsHardLink(state: ScanState, path: string): boolean {
+  return matchingRoot(state, path)?.root.link_handling?.hard_links === "allow";
+}
+
+function matchingRoot(state: ScanState, path: string): RootAccumulator | undefined {
+  const families = filesystemMatches(state, path);
+  if (families.length !== 1) return undefined;
+  const roots = families[0]!.roots.filter(({ root }) => rootMatches(root, path));
+  if (roots.length !== 1) return undefined;
+  return roots[0]!;
+}
+
+function allocatedBytes(stats: Stats): number | undefined {
+  if (typeof stats.blocks !== "number" || !Number.isSafeInteger(stats.blocks)) return undefined;
+  const bytes = stats.blocks * 512;
+  return Number.isSafeInteger(bytes) ? bytes : undefined;
+}
+
+function recordIssue(state: ScanState, reason: HarneryStorageReasonCode): void {
+  state.issues.set(reason, (state.issues.get(reason) ?? 0) + 1);
+}
+
+function familyInventory(
+  catalog: HarneryStorageCatalog,
+  accumulator: FamilyAccumulator,
+  capturedAt: Date,
+): HarneryStorageFamilyInventory {
+  const delegated = accumulator.family.provider.inventory === "delegated";
+  const roots = accumulator.roots.map((root) => rootInventory(catalog, accumulator, root));
+  const rootStates = new Set(roots.map(({ state }) => state));
+  const reasons = new Set(accumulator.reasons);
+  for (const root of roots) for (const reason of root.reason_codes) reasons.add(reason);
+  let state: HarneryStorageFamilyInventory["state"];
+  if (delegated) state = "delegated";
+  else if (rootStates.has("unavailable") && rootStates.size === 1) state = "unavailable";
+  else if (rootStates.has("unavailable") || rootStates.has("partial")) state = "partial";
+  else if (rootStates.has("present") && rootStates.has("dormant")) state = "partial";
+  else if (rootStates.has("present")) state = "present";
+  else state = "dormant";
+  if (state === "dormant" || rootStates.has("dormant")) reasons.add("root_dormant");
+  return {
+    family_id: accumulator.family.id,
+    source: accumulator.family.source,
+    storage_class: accumulator.family.storage_class,
+    policy_version: accumulator.family.policy.policy_version,
+    provider_id: accumulator.family.provider.provider_id,
+    inventory: accumulator.family.provider.inventory,
+    maintenance: maintenance(accumulator.family, state, reasons),
+    state,
+    reason_codes: [...reasons].sort(),
+    totals: delegated
+      ? unavailableTotals("delegated_inventory_unavailable")
+      : observedTotals(accumulator.totals),
+    roots,
+    ...(isLogFamily(accumulator.family)
+      ? { log_storage: logStorageStatus(accumulator.family, capturedAt) }
+      : {}),
+  };
+}
+
+function logStorageStatus(family: HarneryRegisteredStorageFamily, now: Date) {
+  const inspection = inspectStructuredLogRetention(family, now);
+  const effective = family.effective_log_retention;
+  return {
+    effective_policy: effective
+      ? {
+          state: effective.state,
+          max_bytes: effective.max_bytes,
+          max_age_days: effective.max_age_days,
+          max_age_ms: effective.max_age_ms,
+          fingerprint: effective.effective_policy_fingerprint,
+          provenance: effective.provenance,
+          diagnostics: effective.diagnostics,
+        }
+      : null,
+    usage: inspection.usage,
+    pressure: inspection.pressure,
+    retention: inspection.retention,
+  };
+}
+
+function isLogFamily(family: HarneryRegisteredStorageFamily): boolean {
+  return family.storage_class === "operational-log" || family.storage_class === "debug-log";
+}
+
+function rootInventory(
+  catalog: HarneryStorageCatalog,
+  family: FamilyAccumulator,
+  root: RootAccumulator,
+): HarneryStorageRootInventory {
+  const delegated = family.family.provider.inventory === "delegated";
+  const reasons = new Set(root.reasons);
+  let state: HarneryStorageRootInventory["state"];
+  if (delegated) state = "delegated";
+  else if (reasons.has("unreadable_path") || reasons.has("wrong_root_type")) state = "unavailable";
+  else if (reasons.has("symlink_rejected")) state = "unavailable";
+  else if (root.matched || (root.base_present && root.root.match === "subtree")) state = "present";
+  else if (root.base_present && root.root.match === "exact" && root.root.kind === "directory") {
+    state = "present";
+  } else {
+    state = "dormant";
+    reasons.add("root_dormant");
+  }
+  return {
+    root_index: root.index,
+    root_label: rootLabel(catalog, family.family.id, root),
+    ownership: root.root.ownership ?? "harnery",
+    state,
+    reason_codes: [...reasons].sort(),
+    totals: delegated
+      ? unavailableTotals("delegated_inventory_unavailable")
+      : observedTotals(root.totals),
+  };
+}
+
+function rootLabel(
+  catalog: HarneryStorageCatalog,
+  familyId: string,
+  root: RootAccumulator,
+): string {
+  const rel = relative(catalog.context.coord_root, root.root.path);
+  if (rel === "") return ".";
+  if (!rel.startsWith("..") && !isAbsolute(rel)) return rel.split(sep).join("/");
+  return `<external:${familyId}:${root.index + 1}>`;
+}
+
+function maintenance(
+  family: HarneryRegisteredStorageFamily,
+  state: HarneryStorageFamilyInventory["state"],
+  reasons: Set<HarneryStorageReasonCode>,
+): HarneryStorageFamilyInventory["maintenance"] {
+  if (family.provider.maintenance === "delegated") {
+    return { state: "delegated", reason_code: "maintenance_delegated" };
+  }
+  if (family.provider.maintenance === "none") {
+    return { state: "ineligible", reason_code: "maintenance_not_registered" };
+  }
+  if (family.policy.retention.status !== "active") {
+    return { state: "ineligible", reason_code: "maintenance_policy_inactive" };
+  }
+  if (state !== "present" || reasons.has("allocated_bytes_unavailable")) {
+    return { state: "ineligible", reason_code: "provider_unavailable" };
+  }
+  if (
+    [...reasons].some((reason) =>
+      [
+        "host_exclusion",
+        "hard_link_ambiguous",
+        "overlapping_registration",
+        "special_file_rejected",
+        "symlink_rejected",
+        "unreadable_path",
+        "unregistered_path",
+        "wrong_root_type",
+      ].includes(reason),
+    )
+  ) {
+    return { state: "ineligible", reason_code: "provider_unavailable" };
+  }
+  return { state: "eligible" };
+}
+
+function observedTotals(totals: MutableTotals): HarneryStorageInventoryTotals {
+  return {
+    regular_files: observed("files", totals.regular_files),
+    logical_bytes: observed("bytes", totals.logical_bytes),
+    allocated_bytes: totals.allocated_available
+      ? observed("bytes", totals.allocated_bytes)
+      : unavailable("bytes", "allocated_bytes_unavailable"),
+  };
+}
+
+function unavailableTotals(reason: HarneryStorageReasonCode): HarneryStorageInventoryTotals {
+  return {
+    regular_files: unavailable("files", reason),
+    logical_bytes: unavailable("bytes", reason),
+    allocated_bytes: unavailable("bytes", reason),
+  };
+}
+
+function observed(unit: "files" | "bytes", value: number): HarneryStorageMeasurement {
+  return { state: "observed", unit, value };
+}
+
+function unavailable(
+  unit: "files" | "bytes",
+  reason_code: HarneryStorageReasonCode,
+): HarneryStorageMeasurement {
+  return { state: "unavailable", unit, reason_code };
+}
+
+function issueRows(issues: Map<HarneryStorageReasonCode, number>): HarneryStorageIssueSummary[] {
+  return [...issues.entries()]
+    .map(([reason_code, count]) => ({ reason_code, count, maintenance_eligible: false as const }))
+    .sort((left, right) => left.reason_code.localeCompare(right.reason_code));
+}
+
+function rootMatches(root: HarneryStorageRoot, candidate: string): boolean {
+  const path = resolve(candidate);
+  if (root.match === "exact") return resolve(root.path) === path;
+  const remainder = relative(root.path, path).split(sep).join("/");
+  if (remainder === "" || remainder.startsWith("..") || isAbsolute(remainder)) return false;
+  if (root.match === "subtree") return true;
+  return root.include!.some((pattern) => globRegex(pattern).test(remainder));
+}
+
+function globRegex(pattern: string): RegExp {
+  let source = "^";
+  for (let index = 0; index < pattern.length; index += 1) {
+    const character = pattern[index]!;
+    if (character === "*") {
+      if (pattern[index + 1] === "*") {
+        source += ".*";
+        index += 1;
+      } else source += "[^/]*";
+    } else if (character === "?") source += "[^/]";
+    else source += character.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+  }
+  return new RegExp(`${source}$`);
+}
+
+function within(root: string, candidate: string): boolean {
+  const remainder = relative(resolve(root), resolve(candidate));
+  return remainder === "" || (!remainder.startsWith("..") && !isAbsolute(remainder));
+}
+
+function isMissing(error: unknown): boolean {
+  return (error as NodeJS.ErrnoException)?.code === "ENOENT";
+}