forgeos 0.1.0-alpha.2 → 0.1.0-alpha.21

package/src/forge/delta/classifier.ts

@@ -0,0 +1,52 @@
+import { extname } from "node:path";
+import { normalizePath } from "../compiler/primitives/paths.ts";
+
+export interface DeltaSemanticHint {
+  kind: string;
+  confidence: "high" | "medium" | "low";
+}
+
+export function classifyDeltaPath(path: string): DeltaSemanticHint[] {
+  const normalized = normalizePath(path);
+  const hints: DeltaSemanticHint[] = [];
+
+  if (normalized.startsWith("src/forge/_generated/")) {
+    hints.push({ kind: "artifact.generated", confidence: "high" });
+  } else if (normalized === "src/policies.ts" || normalized.includes("/policies/")) {
+    hints.push({ kind: "policy.change", confidence: "high" });
+  } else if (normalized.startsWith("src/commands/")) {
+    hints.push({ kind: "command.change", confidence: "high" });
+  } else if (normalized.startsWith("src/queries/")) {
+    hints.push({ kind: "query.change", confidence: "high" });
+  } else if (normalized.startsWith("src/actions/")) {
+    hints.push({ kind: "action.change", confidence: "high" });
+  } else if (normalized.startsWith("src/workflows/")) {
+    hints.push({ kind: "workflow.change", confidence: "high" });
+  } else if (normalized === "src/forge/schema.ts") {
+    hints.push({ kind: "schema.change", confidence: "high" });
+  } else if (normalized.endsWith(".manifest.json") || normalized === "forge.manifest.json") {
+    hints.push({ kind: "manifest.change", confidence: "high" });
+  } else if (normalized === "package.json" || normalized.endsWith("/package.json")) {
+    hints.push({ kind: "dependency.change", confidence: "medium" });
+  }
+
+  if (hints.length === 0) {
+    hints.push({ kind: `file.${extname(normalized).slice(1) || "unknown"}`, confidence: "low" });
+  }
+  return hints;
+}
+
+export function classifyArtifactKind(path: string): string {
+  const normalized = normalizePath(path);
+  if (normalized.startsWith("src/forge/_generated/")) {
+    return "generated-contract";
+  }
+  if (normalized.includes("security") || normalized.includes("proof")) {
+    return "evidence";
+  }
+  if (normalized.startsWith(".forge/")) {
+    return "local-state";
+  }
+  return "source";
+}
+

package/src/forge/delta/explain.ts

@@ -0,0 +1,126 @@
+import { DeltaStore } from "./store.ts";
+
+export interface DeltaExplainResult {
+  ok: true;
+  thing: string;
+  explanation: Record<string, unknown>;
+  exitCode: 0;
+}
+
+export async function runDeltaExplain(input: {
+  workspaceRoot: string;
+  thing: string;
+}): Promise<DeltaExplainResult> {
+  const store = await DeltaStore.open(input.workspaceRoot, { access: "read" });
+  try {
+    return {
+      ok: true,
+      thing: input.thing,
+      explanation: await store.explain(input.thing),
+      exitCode: 0,
+    };
+  } finally {
+    await store.close();
+  }
+}
+
+export function formatDeltaExplainHuman(result: DeltaExplainResult): string {
+  const explanation = result.explanation;
+  if (explanation.type === "work-session") {
+    const session = explanation.session as Record<string, unknown> | null | undefined;
+    const lines = [result.thing, ""];
+    if (!session) {
+      lines.push("work session not found");
+      return `${lines.join("\n")}\n`;
+    }
+    lines.push("Work session:");
+    lines.push(`  ${String(session.id)}`);
+    lines.push(`  title: ${String(session.title ?? "Work session")}`);
+    lines.push(`  status: ${String(session.status ?? "unknown")}`);
+    lines.push(`  confidence: ${Number(session.confidence ?? 0).toFixed(2)}`);
+    if (session.summary) {
+      lines.push(`  summary: ${String(session.summary)}`);
+    }
+    const operations = Array.isArray(session.operations) ? session.operations as Array<Record<string, unknown>> : [];
+    lines.push("");
+    lines.push("Operations:");
+    for (const operation of operations.slice(-12)) {
+      const timestamp = typeof operation.timestamp === "string" ? operation.timestamp.slice(11, 16) : "??:??";
+      lines.push(`  ${timestamp} ${String(operation.kind)}${operation.summary ? ` ${String(operation.summary)}` : ""}`);
+    }
+    return `${lines.join("\n")}\n`;
+  }
+  const runtime = explanation.runtime as Record<string, unknown> | null | undefined;
+  const semanticTimeline = explanation.semanticTimeline as Record<string, unknown> | null | undefined;
+  const semanticEvents = semanticTimeline && Array.isArray(semanticTimeline.events)
+    ? semanticTimeline.events as Array<Record<string, unknown>>
+    : [];
+  const currentState = semanticTimeline && semanticTimeline.currentState && typeof semanticTimeline.currentState === "object"
+    ? semanticTimeline.currentState as Record<string, unknown>
+    : {};
+  const proofs = Array.isArray(explanation.proofs) ? explanation.proofs as Array<Record<string, unknown>> : [];
+  const workSessions = Array.isArray(explanation.workSessions) ? explanation.workSessions as Array<Record<string, unknown>> : [];
+  const lines = [result.thing, ""];
+  lines.push("Type:");
+  lines.push(`  ${String(explanation.type ?? "unknown")}`);
+  lines.push("");
+  if (runtime) {
+    lines.push("Runtime:");
+    lines.push(`  kind: ${String(runtime.entry_kind ?? "unknown")}`);
+    lines.push(`  result: ${String(runtime.result ?? "unknown")}`);
+    if (runtime.diagnostic_code) {
+      lines.push(`  diagnostic: ${String(runtime.diagnostic_code)}`);
+    }
+    if (runtime.trace_id) {
+      lines.push(`  trace: ${String(runtime.trace_id)}`);
+    }
+    lines.push("");
+  }
+  lines.push("Semantic timeline:");
+  if (semanticEvents.length === 0) {
+    lines.push("  no matching operations");
+  } else {
+    for (const item of semanticEvents.slice(-12)) {
+      const timestamp = typeof item.timestamp === "string" ? item.timestamp.slice(11, 16) : "??:??";
+      lines.push(`  ${timestamp} ${String(item.kind)} ${String(item.title ?? item.summary ?? "")}`.trimEnd());
+    }
+  }
+  if (Object.keys(currentState).length > 0) {
+    lines.push("");
+    lines.push("Current state:");
+    for (const [key, value] of Object.entries(currentState)) {
+      if (value !== undefined) {
+        lines.push(`  ${key}: ${Array.isArray(value) ? value.join(", ") : String(value)}`);
+      }
+    }
+  }
+  lines.push("");
+  lines.push("Introduced in:");
+  if (workSessions.length === 0) {
+    lines.push("  no inferred work session linked");
+  } else {
+    const session = workSessions[0]!;
+    lines.push(`  ${String(session.id)} - ${String(session.title ?? "Work session")}`);
+    lines.push(`  confidence: ${Number(session.confidence ?? 0).toFixed(2)}`);
+    if (session.summary) {
+      lines.push(`  ${String(session.summary)}`);
+    }
+  }
+  lines.push("");
+  lines.push("Proofs:");
+  if (proofs.length === 0) {
+    lines.push("  none recorded");
+  } else {
+    for (const proof of proofs.slice(-6)) {
+      lines.push(`  ${String(proof.proof_kind)} -> ${String(proof.result)}`);
+    }
+  }
+  lines.push("");
+  lines.push("Git:");
+  lines.push(explanation.git ? "  linked metadata recorded" : "  no linked commit yet");
+  return `${lines.join("\n")}\n`;
+}
+
+export function formatDeltaExplainJson(result: DeltaExplainResult): string {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}

package/src/forge/delta/git-observer.ts

@@ -0,0 +1,43 @@
+import { execFileSync } from "node:child_process";
+
+function git(workspaceRoot: string, args: string[]): string | null {
+  try {
+    return execFileSync("git", args, {
+      cwd: workspaceRoot,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export interface DeltaGitSnapshot {
+  branch?: string;
+  head?: string;
+  dirty?: boolean;
+  changedPaths?: string[];
+  changedPathCount?: number;
+  changedPathsTruncated?: boolean;
+}
+
+export function readDeltaGitSnapshot(workspaceRoot: string): DeltaGitSnapshot {
+  const branch = git(workspaceRoot, ["branch", "--show-current"]) ?? undefined;
+  const head = git(workspaceRoot, ["rev-parse", "--short=12", "HEAD"]) ?? undefined;
+  const status = git(workspaceRoot, ["status", "--porcelain"]);
+  const allChangedPaths = status
+    ? status
+        .split(/\r?\n/)
+        .map((line) => line.slice(3).trim())
+        .filter(Boolean)
+    : [];
+  const changedPaths = allChangedPaths.slice(0, 50);
+  return {
+    branch,
+    head,
+    dirty: allChangedPaths.length > 0,
+    changedPaths,
+    changedPathCount: allChangedPaths.length,
+    changedPathsTruncated: allChangedPaths.length > changedPaths.length,
+  };
+}

package/src/forge/delta/ids.ts

@@ -0,0 +1,44 @@
+import { randomBytes } from "node:crypto";
+
+export type DeltaIdPrefix =
+  | "actor"
+  | "sess"
+  | "op"
+  | "txn"
+  | "filechg"
+  | "cmdrun"
+  | "proof"
+  | "rtcall"
+  | "artifact"
+  | "gitmap"
+  | "aevt"
+  | "amem"
+  | "worksess"
+  | "wssig"
+  | "wssum";
+
+const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+
+function encodeTime(time: number): string {
+  let value = BigInt(time);
+  let output = "";
+  for (let index = 0; index < 10; index++) {
+    output = CROCKFORD[Number(value % 32n)] + output;
+    value = value / 32n;
+  }
+  return output;
+}
+
+function encodeRandom(bytes: Uint8Array): string {
+  let value = BigInt(`0x${Buffer.from(bytes).toString("hex")}`);
+  let output = "";
+  for (let index = 0; index < 16; index++) {
+    output = CROCKFORD[Number(value % 32n)] + output;
+    value = value / 32n;
+  }
+  return output;
+}
+
+export function createDeltaId(prefix: DeltaIdPrefix): string {
+  return `${prefix}_${encodeTime(Date.now())}${encodeRandom(randomBytes(10))}`;
+}

package/src/forge/delta/index.ts

@@ -0,0 +1,13 @@
+export {
+  runDeltaStatus,
+  runDeltaRepair,
+  formatDeltaStatusHuman,
+  formatDeltaStatusJson,
+  formatDeltaRepairHuman,
+  formatDeltaRepairJson,
+} from "./status.ts";
+export { runDeltaTimeline, formatDeltaTimelineHuman, formatDeltaTimelineJson } from "./timeline.ts";
+export { runDeltaExplain, formatDeltaExplainHuman, formatDeltaExplainJson } from "./explain.ts";
+export { runDeltaSessionCommand, formatDeltaSessionHuman, formatDeltaSessionJson } from "./session.ts";
+export { createAmbientDeltaRecorder, recordParsedCliCommand, isDeltaDisabled } from "./recorder.ts";
+export { DeltaStore, getDeltaStorePath } from "./store.ts";

package/src/forge/delta/recorder.ts

@@ -0,0 +1,402 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { join, relative } from "node:path";
+import type { ForgeCommand } from "../cli/parse.ts";
+import { GENERATED_DIR } from "../compiler/emitter/constants.ts";
+import { normalizePath } from "../compiler/primitives/paths.ts";
+import { hashUtf8Bytes } from "../compiler/primitives/hash.ts";
+import { DeltaStore, type DeltaRuntimeCallInput } from "./store.ts";
+import { classifyArtifactKind } from "./classifier.ts";
+import { readDeltaGitSnapshot } from "./git-observer.ts";
+
+export interface AmbientDeltaRecorder {
+  sessionId?: string;
+  recordRuntimeCall(input: DeltaRuntimeCallInput & { diagnostics?: unknown[] }): Promise<void>;
+  recordAgentTool(input: { toolName: string; risk?: string; status: "completed" | "failed"; traceId?: string; durationMs?: number }): Promise<void>;
+  recordFileChanged(path: string, changeType?: "created" | "modified" | "deleted" | "renamed" | "generated"): Promise<void>;
+  close(summary?: string): Promise<void>;
+}
+
+export function isDeltaDisabled(argv: string[] = process.argv.slice(2)): boolean {
+  return argv.includes("--no-delta") || process.env.FORGE_DELTA === "0";
+}
+
+export async function createAmbientDeltaRecorder(
+  workspaceRoot: string,
+  source: "forge-dev" | "forge-command" | "auto",
+  summary?: string,
+): Promise<AmbientDeltaRecorder> {
+  if (isDeltaDisabled()) {
+    return noopRecorder;
+  }
+  try {
+    const store = await DeltaStore.open(workspaceRoot);
+    const actorId = await store.ensureActor("forge", "forge-cli", { pid: process.pid });
+    const sessionId = await store.createSession({
+      source,
+      summary,
+      metadata: { actorId },
+      git: readDeltaGitSnapshot(workspaceRoot),
+    });
+    return {
+      sessionId,
+      async recordRuntimeCall(input) {
+        await safeDelta(async () => {
+          const failedCode = input.diagnosticCode ?? diagnosticCode(input.diagnostics);
+          await store.appendOperation({
+            sessionId,
+            actorId,
+            kind: input.result === "denied"
+              ? "runtime.entry.denied"
+              : input.result === "failed"
+                ? "runtime.entry.failed"
+                : "runtime.entry.executed",
+            summary: `${input.entryName} ${input.result ?? "executed"}`,
+            data: {
+              entryName: input.entryName,
+              entryKind: input.entryKind,
+              result: input.result,
+              traceId: input.traceId,
+              diagnosticCode: failedCode,
+            },
+            runtimeCall: { ...input, diagnosticCode: failedCode },
+          });
+        });
+      },
+      async recordAgentTool(input) {
+        await safeDelta(async () => {
+          await store.appendOperation({
+            sessionId,
+            actorId,
+            kind: "agent.tool.called",
+            summary: `${input.toolName} ${input.status}`,
+            data: {
+              toolName: input.toolName,
+              risk: input.risk,
+              status: input.status,
+              traceId: input.traceId,
+              durationMs: input.durationMs,
+            },
+          });
+        });
+      },
+      async recordFileChanged(path, changeType = "modified") {
+        await safeDelta(() => store.recordFilePath(sessionId, path, changeType));
+      },
+      async close(closeSummary) {
+        await safeDelta(async () => {
+          await store.endSession(sessionId, closeSummary);
+          await store.close();
+        });
+      },
+    };
+  } catch {
+    return noopRecorder;
+  }
+}
+
+export async function recordParsedCliCommand(input: {
+  command: ForgeCommand;
+  argv: string[];
+  exitCode: number;
+  durationMs: number;
+}): Promise<void> {
+  if (
+    isDeltaDisabled(input.argv) ||
+    input.command.kind === "delta" ||
+    input.command.kind === "session" ||
+    input.command.kind === "timeline" ||
+    input.command.kind === "explain"
+  ) {
+    return;
+  }
+  await safeDelta(async () => {
+    const workspaceRoot = commandWorkspaceRoot(input.command);
+    const store = await DeltaStore.open(workspaceRoot);
+    const actorId = await store.ensureActor("forge", "forge-cli", { pid: process.pid });
+    const sessionId = await store.createSession({
+      source: "forge-command",
+      summary: `forge ${input.command.kind}`,
+      metadata: { argv: input.argv },
+      git: readDeltaGitSnapshot(workspaceRoot),
+    });
+    const commandName = commandDisplayName(input.command);
+    const exitKind = input.exitCode === 0 ? "forge.command.completed" : "forge.command.failed";
+    const data = {
+      command: commandName,
+      exitCode: input.exitCode,
+      durationMs: input.durationMs,
+      git: readDeltaGitSnapshot(workspaceRoot),
+    };
+    await store.appendOperation({
+      sessionId,
+      actorId,
+      kind: exitKind,
+      summary: `${commandName} ${input.exitCode === 0 ? "completed" : "failed"}`,
+      data,
+      commandRun: {
+        commandName,
+        argv: input.argv,
+        exitCode: input.exitCode,
+        durationMs: input.durationMs,
+      },
+    });
+
+    await recordSpecializedCommand(store, sessionId, actorId, input.command, input.exitCode, commandName);
+    await store.endSession(sessionId, `forge ${input.command.kind} exited ${input.exitCode}`);
+    await store.close();
+  });
+}
+
+async function recordSpecializedCommand(
+  store: DeltaStore,
+  sessionId: string,
+  actorId: string,
+  command: ForgeCommand,
+  exitCode: number,
+  commandName: string,
+): Promise<void> {
+  const workspaceRoot = commandWorkspaceRoot(command);
+  if (command.kind === "generate" && exitCode === 0) {
+    const artifacts = listGeneratedArtifacts(workspaceRoot).map((path) => ({
+      path,
+      artifactKind: classifyArtifactKind(path),
+      generated: true,
+      hash: hashFileIfPresent(workspaceRoot, path),
+    }));
+    await store.appendOperation({
+      sessionId,
+      actorId,
+      kind: "artifact.generated",
+      summary: `Generated ${artifacts.length} Forge artifacts`,
+      data: { count: artifacts.length, generator: "forge generate" },
+      artifacts,
+    });
+    return;
+  }
+
+  if (command.kind === "manifest") {
+    await store.appendOperation({
+      sessionId,
+      actorId,
+      kind: command.subcommand === "import" ? "manifest.imported" : "manifest.validated",
+      summary: `${command.subcommand} ${command.path}`,
+      data: { path: command.path, subcommand: command.subcommand, exitCode },
+      artifacts: command.subcommand === "import"
+        ? ["externalServices.json", "agentContract.json", "api.json"].map((name) => ({
+            path: `${GENERATED_DIR}/${name}`,
+            generated: true,
+          }))
+        : undefined,
+    });
+    return;
+  }
+
+  if (command.kind === "run" && command.name) {
+    const queryMode = command.queryMode === true;
+    const runtimeMetadata = externalRuntimeMetadata(workspaceRoot, command.name, queryMode ? "query" : "command");
+    await store.appendOperation({
+      sessionId,
+      actorId,
+      kind: exitCode === 0 ? "runtime.entry.executed" : "runtime.entry.failed",
+      summary: `${command.name} ${exitCode === 0 ? "success" : "failed"}`,
+      data: { entryName: command.name, entryKind: queryMode ? "query" : "command", exitCode, ...runtimeMetadata },
+      runtimeCall: {
+        entryName: command.name,
+        entryKind: queryMode ? "query" : "command",
+        result: exitCode === 0 ? "success" : "failed",
+        ...runtimeMetadata,
+      },
+    });
+    return;
+  }
+
+  if (command.kind === "query" && command.subcommand === "run" && command.name) {
+    const runtimeMetadata = externalRuntimeMetadata(workspaceRoot, command.name, "query");
+    await store.appendOperation({
+      sessionId,
+      actorId,
+      kind: exitCode === 0 ? "runtime.entry.executed" : "runtime.entry.failed",
+      summary: `${command.name} ${exitCode === 0 ? "success" : "failed"}`,
+      data: { entryName: command.name, entryKind: "query", exitCode, ...runtimeMetadata },
+      runtimeCall: {
+        entryName: command.name,
+        entryKind: "query",
+        result: exitCode === 0 ? "success" : "failed",
+        ...runtimeMetadata,
+      },
+    });
+    return;
+  }
+
+  if (command.kind === "security" && command.subcommand === "prove") {
+    await store.appendOperation({
+      sessionId,
+      actorId,
+      kind: "proof.run",
+      summary: `security prove ${exitCode === 0 ? "passed" : "failed"}`,
+      data: { command: commandName, exitCode },
+      proof: {
+        proofKind: "security-prove",
+        command: commandName,
+        result: exitCode === 0 ? "passed" : "failed",
+      },
+    });
+    return;
+  }
+
+  if (command.kind === "ai" && command.subcommand === "redteam") {
+    await store.appendOperation({
+      sessionId,
+      actorId,
+      kind: "proof.run",
+      summary: `ai redteam ${exitCode === 0 ? "passed" : "failed"}`,
+      data: { command: commandName, exitCode },
+      proof: {
+        proofKind: "ai-redteam",
+        command: commandName,
+        result: exitCode === 0 ? "passed" : "failed",
+      },
+    });
+    return;
+  }
+
+  if (command.kind === "check" || command.kind === "verify") {
+    await store.appendOperation({
+      sessionId,
+      actorId,
+      kind: "proof.run",
+      summary: `${commandName} ${exitCode === 0 ? "passed" : "failed"}`,
+      data: { command: commandName, exitCode },
+      proof: {
+        proofKind: command.kind === "check" ? "forge-check" : "forge-verify",
+        command: commandName,
+        result: exitCode === 0 ? "passed" : "failed",
+      },
+    });
+  }
+}
+
+const noopRecorder: AmbientDeltaRecorder = {
+  async recordRuntimeCall() {},
+  async recordAgentTool() {},
+  async recordFileChanged() {},
+  async close() {},
+};
+
+async function safeDelta(fn: () => Promise<void>): Promise<void> {
+  try {
+    await fn();
+  } catch {
+    // Delta recording is ambient. It must never change primary command behavior.
+  }
+}
+
+function diagnosticCode(diagnostics: unknown[] | undefined): string | undefined {
+  const first = diagnostics?.find((diagnostic) =>
+    diagnostic && typeof diagnostic === "object" && "code" in diagnostic,
+  ) as { code?: unknown } | undefined;
+  return typeof first?.code === "string" ? first.code : undefined;
+}
+
+interface ExternalServicesFile {
+  services?: Array<{
+    name?: unknown;
+    language?: unknown;
+    entries?: Array<{
+      name?: unknown;
+      kind?: unknown;
+      risk?: unknown;
+      policy?: unknown;
+      tenantScoped?: unknown;
+      needsApproval?: unknown;
+    }>;
+  }>;
+}
+
+function externalRuntimeMetadata(
+  workspaceRoot: string,
+  qualifiedName: string,
+  kind: "command" | "query",
+): Partial<DeltaRuntimeCallInput> {
+  const [serviceName, ...entryParts] = qualifiedName.split(".");
+  const entryName = entryParts.join(".");
+  if (!serviceName || !entryName) {
+    return {};
+  }
+  try {
+    const graph = JSON.parse(
+      readFileSync(join(workspaceRoot, GENERATED_DIR, "externalServices.json"), "utf8"),
+    ) as ExternalServicesFile;
+    const service = graph.services?.find((candidate) => candidate.name === serviceName);
+    const entry = service?.entries?.find((candidate) => candidate.name === entryName && candidate.kind === kind);
+    if (!service || !entry) {
+      return {};
+    }
+    return {
+      service: typeof service.name === "string" ? service.name : undefined,
+      language: typeof service.language === "string" ? service.language : undefined,
+      risk: typeof entry.risk === "string" ? entry.risk : undefined,
+      policy: typeof entry.policy === "string" ? entry.policy : undefined,
+      tenantScoped: typeof entry.tenantScoped === "boolean" ? entry.tenantScoped : undefined,
+      needsApproval: typeof entry.needsApproval === "boolean" ? entry.needsApproval : undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+function commandWorkspaceRoot(command: ForgeCommand): string {
+  if ("workspaceRoot" in command && typeof command.workspaceRoot === "string") {
+    return command.workspaceRoot;
+  }
+  if ("options" in command && command.options && typeof command.options === "object" && "workspaceRoot" in command.options) {
+    const root = (command.options as { workspaceRoot?: unknown }).workspaceRoot;
+    if (typeof root === "string") {
+      return root;
+    }
+  }
+  return process.cwd().replace(/\\/g, "/");
+}
+
+function commandDisplayName(command: ForgeCommand): string {
+  if ("subcommand" in command && typeof command.subcommand === "string") {
+    return `forge ${command.kind} ${command.subcommand}`;
+  }
+  if ("options" in command && command.options && typeof command.options === "object" && "subcommand" in command.options) {
+    const subcommand = (command.options as { subcommand?: unknown }).subcommand;
+    if (typeof subcommand === "string") {
+      return `forge ${command.kind} ${subcommand}`;
+    }
+  }
+  return `forge ${command.kind}`;
+}
+
+function listGeneratedArtifacts(workspaceRoot: string): string[] {
+  const root = join(workspaceRoot, GENERATED_DIR);
+  try {
+    return walk(root).map((path) => normalizePath(relative(workspaceRoot, path)));
+  } catch {
+    return [];
+  }
+}
+
+function walk(root: string): string[] {
+  const entries: string[] = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) {
+      entries.push(...walk(path));
+    } else if (entry.isFile()) {
+      entries.push(path);
+    }
+  }
+  return entries;
+}
+
+function hashFileIfPresent(workspaceRoot: string, path: string): string | undefined {
+  try {
+    return hashUtf8Bytes(readFileSync(join(workspaceRoot, path)));
+  } catch {
+    return undefined;
+  }
+}