@runuai/host 0.9.14 → 0.9.42

package/lib/task-inventory.ts

@@ -0,0 +1,585 @@
+/**
+ * ADR-100 L2 authenticated task inventory.
+ *
+ * This is deliberately positive evidence: an unavailable Docker query can
+ * omit resources, but can never turn that omission into permission to delete.
+ * One immutable, sorted snapshot is retained for the active scan so duplicate
+ * cursor requests are idempotent while cleanup mutates the underlying host.
+ */
+
+import { lstatSync, opendirSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { sql } from "drizzle-orm";
+
+import { dockerCli, type DockerResult } from "./docker-exec";
+import { containerRuntimeProblem } from "./container-runtime";
+import { env } from "./env";
+import { getDb, schema } from "./db";
+import {
+  MAX_HOST_TASK_INVENTORY_PAGE_SIZE,
+  MAX_HOST_TASK_INVENTORY_SCAN_ID_CHARS,
+  MAX_HOST_TASK_INVENTORY_TASK_ID_CHARS,
+  type HostTaskInventoryEntry,
+  type HostTaskInventorySource,
+} from "../src/protocol";
+import {
+  assertSafeHostTaskId,
+  isSafeHostTaskId,
+} from "./task-identity";
+import {
+  taskContainerBackend,
+  taskContainerCli,
+} from "./task-container-cli";
+import { appleTaskContainerName } from "./task-environment/apple-container";
+
+export {
+  assertSafeHostTaskId,
+  isSafeHostTaskId,
+  SAFE_HOST_TASK_ID,
+} from "./task-identity";
+
+const SOURCE_ORDER: readonly HostTaskInventorySource[] = [
+  "db",
+  "session",
+  "event",
+  "workspace",
+  "compose",
+  "network",
+  "volume",
+  "preview",
+];
+
+const COMPOSE_PROJECT_LABEL = "com.docker.compose.project";
+const PREVIEW_TASK_LABEL = "com.runuai.preview-sidecar.task";
+export const MAX_HOST_TASK_INVENTORY_SNAPSHOT_ENTRIES = 10_000;
+const MAX_HOST_TASK_INVENTORY_DOCKER_OUTPUT_BYTES = 2 * 1024 * 1024;
+
+export function isSafeInventoryScanId(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    value.length <= MAX_HOST_TASK_INVENTORY_SCAN_ID_CHARS &&
+    // Scan ids are correlation values only, but controls/whitespace make logs
+    // and duplicate-page diagnosis ambiguous. Keep the wire boundary exact.
+    /^[A-Za-z0-9_-]+$/.test(value)
+  );
+}
+
+interface InventorySnapshot {
+  entries: HostTaskInventoryEntry[];
+  runtimeEnumerated: boolean;
+}
+
+export interface HostTaskInventoryPage {
+  entries: HostTaskInventoryEntry[];
+  nextCursor: string | null;
+  runtimeEnumerated: boolean;
+}
+
+export interface HostTaskInventoryDeps {
+  hostTaskIds(): string[];
+  sessionTaskIds(): string[];
+  eventTaskIds(): string[];
+  workspaceTaskIds(): string[];
+  runtimeReady(): boolean;
+  docker(args: string[]): Promise<DockerResult>;
+  /** Whether the pinned backend is apple-container (round 4: inventory and
+   * the orphan proof were Docker-only, so apple orphans were invisible and
+   * apple GC could never prune local state). */
+  appleBackend(): boolean;
+  /** Apple container inventory: `list --all --format json`. */
+  appleList(): Promise<DockerResult>;
+  /** Apple exact-name/image probes through the bundled CLI. */
+  appleCli(args: string[]): Promise<DockerResult>;
+}
+
+function databaseTaskIds(
+  table:
+    | typeof schema.hostTasks
+    | typeof schema.hostAgentSessions
+    | typeof schema.hostEvents,
+): string[] {
+  const rows = getDb()
+    .selectDistinct({ taskId: table.taskId })
+    .from(table)
+    .where(
+      sql`length(${table.taskId}) between 1 and ${MAX_HOST_TASK_INVENTORY_TASK_ID_CHARS}`,
+    )
+    .limit(MAX_HOST_TASK_INVENTORY_SNAPSHOT_ENTRIES + 1)
+    .all();
+  if (rows.length > MAX_HOST_TASK_INVENTORY_SNAPSHOT_ENTRIES) {
+    throw new Error("host inventory DB source exceeds snapshot limit");
+  }
+  return rows.map((row) => row.taskId);
+}
+
+function workspaceTaskIds(): string[] {
+  const root = resolve(env.workspaceRoot, "tasks");
+  let directory: ReturnType<typeof opendirSync>;
+  try {
+    directory = opendirSync(root);
+  } catch {
+    return [];
+  }
+  const taskIds: string[] = [];
+  try {
+    for (;;) {
+      const entry = directory.readSync();
+      if (!entry) break;
+      const taskId = entry.name;
+      if (!isSafeHostTaskId(taskId)) continue;
+      let realDirectory = false;
+      try {
+        const stat = lstatSync(resolve(root, taskId));
+        realDirectory = stat.isDirectory() && !stat.isSymbolicLink();
+      } catch {
+        // A concurrent taskDown removed it. Positive omission is safe.
+      }
+      if (!realDirectory) continue;
+      taskIds.push(taskId);
+      if (taskIds.length > MAX_HOST_TASK_INVENTORY_SNAPSHOT_ENTRIES) {
+        throw new Error("host inventory workspace exceeds snapshot limit");
+      }
+    }
+  } finally {
+    directory.closeSync();
+  }
+  return taskIds;
+}
+
+const defaultDeps: HostTaskInventoryDeps = {
+  hostTaskIds: () => databaseTaskIds(schema.hostTasks),
+  sessionTaskIds: () => databaseTaskIds(schema.hostAgentSessions),
+  eventTaskIds: () => databaseTaskIds(schema.hostEvents),
+  workspaceTaskIds,
+  runtimeReady: () => containerRuntimeProblem() === null,
+  docker: (args) =>
+    dockerCli(args, {
+      timeoutMs: 30_000,
+      maxOutputBytes: MAX_HOST_TASK_INVENTORY_DOCKER_OUTPUT_BYTES,
+    }),
+  appleBackend: () => taskContainerBackend().apple,
+  appleList: () =>
+    taskContainerCli(["list", "--all", "--format", "json"], {
+      timeoutMs: 30_000,
+      maxOutputBytes: MAX_HOST_TASK_INVENTORY_DOCKER_OUTPUT_BYTES,
+    }),
+  appleCli: (args) =>
+    taskContainerCli(args, {
+      timeoutMs: 30_000,
+      maxOutputBytes: MAX_HOST_TASK_INVENTORY_DOCKER_OUTPUT_BYTES,
+    }),
+};
+
+function addEvidence(
+  evidence: Map<string, Set<HostTaskInventorySource>>,
+  taskId: string,
+  source: HostTaskInventorySource,
+): void {
+  if (!isSafeHostTaskId(taskId)) return;
+  let sources = evidence.get(taskId);
+  if (!sources) {
+    if (evidence.size >= MAX_HOST_TASK_INVENTORY_SNAPSHOT_ENTRIES) {
+      throw new Error("host inventory snapshot exceeds task limit");
+    }
+    sources = new Set();
+    evidence.set(taskId, sources);
+  }
+  sources.add(source);
+}
+
+type AppleInventoryRow = { id: string; taskLabel: string | null };
+
+/** Strict apple inventory shape (rounds 5+6). Every row must be structurally
+ * valid — an object whose configuration.id is a non-empty string and whose
+ * com.uai.task label, when present, is a string. Anything else invalidates
+ * the WHOLE inventory (returns null): a [null] entry or a malformed label
+ * could be hiding exactly the labeled container a caller needs to see, so a
+ * partially-readable answer is no answer. */
+function parseAppleInventoryRows(stdout: string): AppleInventoryRow[] | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(parsed)) return null;
+  const rows: AppleInventoryRow[] = [];
+  for (const row of parsed) {
+    if (typeof row !== "object" || row === null) return null;
+    const configuration = (row as { configuration?: unknown }).configuration;
+    if (typeof configuration !== "object" || configuration === null) {
+      return null;
+    }
+    const id = (configuration as { id?: unknown }).id;
+    if (typeof id !== "string" || id === "") return null;
+    const labels = (configuration as { labels?: unknown }).labels;
+    if (labels === undefined || labels === null) {
+      rows.push({ id, taskLabel: null });
+      continue;
+    }
+    if (typeof labels !== "object" || Array.isArray(labels)) return null;
+    const label = (labels as Record<string, unknown>)["com.uai.task"];
+    if (label === undefined) {
+      rows.push({ id, taskLabel: null });
+      continue;
+    }
+    if (typeof label !== "string") return null;
+    rows.push({ id, taskLabel: label });
+  }
+  return rows;
+}
+
+function composeTaskId(project: string): string | null {
+  if (!project.startsWith("task-")) return null;
+  const taskId = project.slice("task-".length);
+  return isSafeHostTaskId(taskId) ? taskId : null;
+}
+
+function outputLines(result: DockerResult): string[] {
+  return result.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+async function buildSnapshot(
+  deps: HostTaskInventoryDeps,
+): Promise<InventorySnapshot> {
+  const evidence = new Map<string, Set<HostTaskInventorySource>>();
+  for (const taskId of deps.hostTaskIds()) addEvidence(evidence, taskId, "db");
+  for (const taskId of deps.sessionTaskIds()) {
+    addEvidence(evidence, taskId, "session");
+  }
+  for (const taskId of deps.eventTaskIds()) {
+    addEvidence(evidence, taskId, "event");
+  }
+  for (const taskId of deps.workspaceTaskIds()) {
+    addEvidence(evidence, taskId, "workspace");
+  }
+
+  // The container-runtime module owns the authoritative readiness verdict.
+  // When it is already degraded, four potentially expensive CLI timeouts
+  // cannot add trustworthy negative evidence, so return local positives now.
+  if (!deps.runtimeReady()) {
+    return {
+      entries: inventoryEntries(evidence),
+      runtimeEnumerated: false,
+    };
+  }
+
+  if (deps.appleBackend()) {
+    // One inventory call covers containers; apple tasks have no compose
+    // networks/volumes or preview sidecars. One ownership rule everywhere
+    // (round 5): a task-shaped NAME is evidence only when the com.uai.task
+    // label derives it — a foreign container occupying the reserved shape
+    // must not feed the GC that deletes by that name. The label alone is
+    // evidence regardless of the name (a renamed container still carries
+    // it). Round 6: a structurally invalid inventory (any malformed row)
+    // is no inventory — it could be hiding a labeled container.
+    const listed = await deps.appleList();
+    let runtimeEnumerated = false;
+    if (listed.status === 0) {
+      const rows = parseAppleInventoryRows(listed.stdout);
+      if (rows !== null) {
+        runtimeEnumerated = true;
+        for (const row of rows) {
+          if (row.taskLabel !== null) {
+            addEvidence(evidence, row.taskLabel, "compose");
+          }
+        }
+      }
+    }
+    return {
+      entries: inventoryEntries(evidence),
+      runtimeEnumerated,
+    };
+  }
+
+  const [compose, networks, volumes, previews] = await Promise.all([
+    deps.docker([
+      "ps",
+      "-a",
+      "--filter",
+      `label=${COMPOSE_PROJECT_LABEL}`,
+      "--format",
+      `{{.Label \"${COMPOSE_PROJECT_LABEL}\"}}`,
+    ]),
+    deps.docker([
+      "network",
+      "ls",
+      "--filter",
+      `label=${COMPOSE_PROJECT_LABEL}`,
+      "--format",
+      `{{.Label \"${COMPOSE_PROJECT_LABEL}\"}}`,
+    ]),
+    deps.docker([
+      "volume",
+      "ls",
+      "--filter",
+      `label=${COMPOSE_PROJECT_LABEL}`,
+      "--format",
+      `{{.Label \"${COMPOSE_PROJECT_LABEL}\"}}`,
+    ]),
+    deps.docker([
+      "ps",
+      "-a",
+      "--filter",
+      `label=${PREVIEW_TASK_LABEL}`,
+      "--format",
+      `{{.Label \"${PREVIEW_TASK_LABEL}\"}}`,
+    ]),
+  ]);
+
+  for (const project of outputLines(compose)) {
+    const taskId = composeTaskId(project);
+    if (taskId) addEvidence(evidence, taskId, "compose");
+  }
+  for (const project of outputLines(networks)) {
+    const taskId = composeTaskId(project);
+    if (taskId) addEvidence(evidence, taskId, "network");
+  }
+  for (const project of outputLines(volumes)) {
+    const taskId = composeTaskId(project);
+    if (taskId) addEvidence(evidence, taskId, "volume");
+  }
+  for (const taskId of outputLines(previews)) {
+    addEvidence(evidence, taskId, "preview");
+  }
+
+  return {
+    entries: inventoryEntries(evidence),
+    runtimeEnumerated: [compose, networks, volumes, previews].every(
+      (result) => result.status === 0,
+    ),
+  };
+}
+
+function inventoryEntries(
+  evidence: Map<string, Set<HostTaskInventorySource>>,
+): HostTaskInventoryEntry[] {
+  return [...evidence.entries()]
+    .map(([taskId, sources]) => ({
+      taskId,
+      sources: SOURCE_ORDER.filter((source) => sources.has(source)),
+    }))
+    .sort((left, right) =>
+      left.taskId < right.taskId ? -1 : left.taskId > right.taskId ? 1 : 0,
+    );
+}
+
+/** One-active-scan snapshot cache. A new scan supersedes the old connection's
+ * state; duplicate requests for the same scan share the same build promise. */
+export class HostTaskInventorySnapshots {
+  private scanId: string | null = null;
+  private snapshot: Promise<InventorySnapshot> | null = null;
+
+  constructor(private readonly deps: HostTaskInventoryDeps = defaultDeps) {}
+
+  clear(): void {
+    this.scanId = null;
+    this.snapshot = null;
+  }
+
+  async page(request: {
+    scanId: string;
+    cursor: string | null;
+    limit: number;
+  }): Promise<HostTaskInventoryPage> {
+    if (!isSafeInventoryScanId(request.scanId)) {
+      throw new Error("invalid host inventory scan id");
+    }
+    if (
+      !Number.isSafeInteger(request.limit) ||
+      request.limit < 1 ||
+      request.limit > MAX_HOST_TASK_INVENTORY_PAGE_SIZE
+    ) {
+      throw new Error("invalid host inventory page limit");
+    }
+    if (request.cursor !== null && !isSafeHostTaskId(request.cursor)) {
+      throw new Error("invalid host inventory cursor");
+    }
+
+    if (request.cursor === null) {
+      if (this.scanId !== request.scanId || !this.snapshot) {
+        this.scanId = request.scanId;
+        this.snapshot = buildSnapshot(this.deps);
+      }
+    } else if (this.scanId !== request.scanId || !this.snapshot) {
+      throw new Error("unknown host inventory scan");
+    }
+
+    const snapshot = await this.snapshot;
+    let start = 0;
+    if (request.cursor !== null) {
+      const cursorIndex = snapshot.entries.findIndex(
+        (entry) => entry.taskId === request.cursor,
+      );
+      if (cursorIndex < 0) throw new Error("unknown host inventory cursor");
+      start = cursorIndex + 1;
+    }
+    const entries = snapshot.entries.slice(start, start + request.limit);
+    const hasMore = start + entries.length < snapshot.entries.length;
+    return {
+      entries,
+      nextCursor: hasMore ? (entries.at(-1)?.taskId ?? null) : null,
+      runtimeEnumerated: snapshot.runtimeEnumerated,
+    };
+  }
+}
+
+export const hostTaskInventorySnapshots = new HostTaskInventorySnapshots();
+
+/** Final orphan-GC proof. Never interpret a failed Docker query as absence. */
+export async function proveOrphanTaskResourcesAbsent(
+  taskId: string,
+  docker: HostTaskInventoryDeps["docker"] = defaultDeps.docker,
+  appleDeps: Pick<HostTaskInventoryDeps, "appleBackend" | "appleCli"> = defaultDeps,
+): Promise<void> {
+  assertSafeHostTaskId(taskId);
+  if (appleDeps.appleBackend()) {
+    // Apple task resources: the fixed-name container and the derived image.
+    // No compose networks/volumes exist there. Absence is proven only by the
+    // exact not-found grammars (a failed query is never absence).
+    // Derive the apple name from the branch's own backend decision, not the
+    // global pin — this proof runs exactly when appleBackend() says apple.
+    const containerName = appleTaskContainerName(taskId);
+    const inspectedContainer = await appleDeps.appleCli([
+      "inspect",
+      containerName,
+    ]);
+    if (inspectedContainer.status === 0) {
+      throw new Error(`orphan proof: container ${containerName} still exists`);
+    }
+    // Round 6: absence needs a SETTLED nonzero exit (a killed probe with a
+    // stale stderr line proves nothing) plus empty stdout and the exact
+    // whole-line grammar.
+    const containerAbsent =
+      typeof inspectedContainer.status === "number" &&
+      inspectedContainer.stdout.trim() === "" &&
+      inspectedContainer.stderr
+        .split("\n")
+        .some(
+          (line) =>
+            line.trim() === `Error: container not found: ${containerName}`,
+        );
+    if (!containerAbsent) {
+      throw new Error(
+        `orphan proof: container ${containerName} could not be proven absent (exit ${inspectedContainer.status ?? "killed"})`,
+      );
+    }
+    const imageRef = `uai-task-${taskId.toLowerCase()}`;
+    const inspected = await appleDeps.appleCli(["image", "inspect", imageRef]);
+    const imageAbsent =
+      typeof inspected.status === "number" &&
+      inspected.status !== 0 &&
+      inspected.stdout.trim() === "" &&
+      inspected.stderr
+        .split("\n")
+        .some((line) => line.trim() === `Error: image not found: ${imageRef}`);
+    if (!imageAbsent) {
+      throw new Error(
+        inspected.status === 0
+          ? `orphan proof: derived image ${imageRef} still exists`
+          : `orphan proof: derived image ${imageRef} could not be proven absent (exit ${inspected.status ?? "killed"})`,
+      );
+    }
+    // The same ownership set the enumeration uses (round 5): a RENAMED
+    // container still carrying this task's label is this task's resource,
+    // and the exact-name check above cannot see it. An unreadable inventory
+    // proves nothing.
+    const listed = await appleDeps.appleCli(["list", "--all", "--format", "json"]);
+    if (listed.status !== 0) {
+      throw new Error(
+        `orphan proof: container inventory failed (exit ${listed.status ?? "killed"})`,
+      );
+    }
+    const rows = parseAppleInventoryRows(listed.stdout);
+    if (rows === null) {
+      // Round 6: [null] entries or malformed labels invalidate the whole
+      // answer — a partially-readable inventory could be hiding exactly the
+      // labeled container this proof exists to find.
+      throw new Error("orphan proof: container inventory was unparseable");
+    }
+    for (const row of rows) {
+      if (row.taskLabel === taskId) {
+        throw new Error(
+          `orphan proof: container ${row.id} still carries this task's ownership label`,
+        );
+      }
+    }
+    // Workspace absence, exactly like the Docker proof below.
+    const appleTaskDir = resolve(env.workspaceRoot, "tasks", taskId);
+    try {
+      lstatSync(appleTaskDir);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+      throw error;
+    }
+    throw new Error("task workspace remains after task teardown");
+  }
+  const composeProject = `task-${taskId}`;
+  const checks: Array<{ label: string; args: string[] }> = [
+    {
+      label: "compose containers",
+      args: [
+        "ps",
+        "-aq",
+        "--filter",
+        `label=${COMPOSE_PROJECT_LABEL}=${composeProject}`,
+      ],
+    },
+    {
+      label: "compose networks",
+      args: [
+        "network",
+        "ls",
+        "-q",
+        "--filter",
+        `label=${COMPOSE_PROJECT_LABEL}=${composeProject}`,
+      ],
+    },
+    {
+      label: "compose volumes",
+      args: [
+        "volume",
+        "ls",
+        "-q",
+        "--filter",
+        `label=${COMPOSE_PROJECT_LABEL}=${composeProject}`,
+      ],
+    },
+    {
+      label: "preview sidecars",
+      args: [
+        "ps",
+        "-aq",
+        "--filter",
+        `label=${PREVIEW_TASK_LABEL}=${taskId}`,
+      ],
+    },
+  ];
+  const results = await Promise.all(checks.map((check) => docker(check.args)));
+  for (let index = 0; index < checks.length; index++) {
+    const check = checks[index]!;
+    const result = results[index]!;
+    if (result.status !== 0) {
+      throw new Error(
+        `could not prove ${check.label} absent: ${result.stderr.trim().slice(0, 200) || "docker did not answer"}`,
+      );
+    }
+    if (outputLines(result).length > 0) {
+      throw new Error(`${check.label} remain after task teardown`);
+    }
+  }
+
+  const taskDir = resolve(env.workspaceRoot, "tasks", taskId);
+  try {
+    lstatSync(taskDir);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw error;
+  }
+  throw new Error("task workspace remains after task teardown");
+}