@aigne/ash 0.0.1

package/src/ai-dev-loop/e2e.test.ts

@@ -0,0 +1,324 @@
+/**
+ * End-to-End Tests for ASH AI Dev Loop.
+ *
+ * These tests use REAL ASH compilation, validation, and execution.
+ * Only ctx.think() is faked (no real LLM calls).
+ *
+ * Verifies the full chain: think → validate → compile → execute → observe.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { runDevLoop } from "./dev-loop.js";
+import { runStructured } from "./structured-runner.js";
+import { ashValidate } from "./ash-validate.js";
+import type { WorldInterface, JobLogger, JobContext } from "../compiler.js";
+import { isAshTypedError } from "./ash-typed-error.js";
+
+// ── Real World + Context ─────────────────────────────────
+
+function makeWorld(data: Record<string, unknown[]> = {}): WorldInterface & {
+  written: Record<string, unknown[]>;
+  published: Record<string, unknown[]>;
+} {
+  const written: Record<string, unknown[]> = {};
+  const published: Record<string, unknown[]> = {};
+  return {
+    read(path: string) { return data[path] ?? []; },
+    write(path: string, records: unknown[]) { written[path] = records; },
+    publish(topic: string, records: unknown[]) { published[topic] = records; },
+    written,
+    published,
+  };
+}
+
+function makeCtx(data: Record<string, unknown[]> = {}) {
+  const world = makeWorld(data);
+  return {
+    ctx: {
+      world,
+      caps: new Set(["*"]),
+      logger: { log() {} } as JobLogger,
+    } as JobContext,
+    world,
+  };
+}
+
+// ── Fake Think Helper ────────────────────────────────────
+
+function thinkReturning(scripts: string[]) {
+  let i = 0;
+  return vi.fn(async () => ({
+    kind: "completed" as const,
+    response: {
+      content: "",
+      tool_calls: [{
+        id: `tc-${i}`,
+        name: "ash_run",
+        arguments: JSON.stringify({ script: scripts[i++] ?? "" }),
+      }],
+    },
+    toolResults: [],
+  }));
+}
+
+// ── Real runner + validate wrappers ──────────────────────
+
+function realRunner(ctx: JobContext, mode: "dry-run" | "live" = "dry-run") {
+  return async (source: string) => runStructured(source, ctx, { mode });
+}
+
+function realValidate() {
+  return async (source: string) => ashValidate(source);
+}
+
+// ── E2E Tests ────────────────────────────────────────────
+
+describe("E2E: Full AI Dev Loop with Real ASH", () => {
+  it("valid script → real compile + execute → success on first try", async () => {
+    const { ctx } = makeCtx({ "/users": [{ id: 1, name: "Alice" }] });
+    const think = thinkReturning(['job "e2e" { find /users }']);
+    const observe = vi.fn(async () => {});
+
+    const result = await runDevLoop({
+      intent: "find all users",
+      max_iterations: 3,
+      think,
+      runner: realRunner(ctx),
+      validate: realValidate(),
+      observe,
+    });
+
+    expect(result.status).toBe("ok");
+    expect(result.iterations).toBe(1);
+    expect(result.finalResult).toBeDefined();
+    expect(result.finalResult!.status).toBe("ok");
+    expect(observe).toHaveBeenCalledTimes(1);
+  });
+
+  it("invalid syntax → validate catches it → correction → second script succeeds", async () => {
+    const { ctx } = makeCtx({ "/users": [{ id: 1 }] });
+    const think = thinkReturning([
+      'job "broken" { foobar }',        // invalid command → validate catches
+      'job "fixed" { find /users }',     // valid
+    ]);
+    const observe = vi.fn(async () => {});
+
+    const result = await runDevLoop({
+      intent: "find users",
+      max_iterations: 3,
+      think,
+      runner: realRunner(ctx),
+      validate: realValidate(),
+      observe,
+    });
+
+    expect(result.status).toBe("ok");
+    expect(result.iterations).toBe(2);
+    // First iteration: validate error, no runner call
+    // Second iteration: validate ok, runner ok
+    expect(observe).toHaveBeenCalledTimes(2);
+    // First observation should have validation_errors
+    const firstObs = (observe.mock.calls as any)[0][0];
+    expect(firstObs!.validation_errors).toBeDefined();
+    expect(firstObs!.validation_errors.length).toBeGreaterThan(0);
+  });
+
+  it("dry-run mode: world is NOT written to", async () => {
+    const { ctx, world } = makeCtx({ "/users": [{ id: 1, name: "Alice" }] });
+    const think = thinkReturning([
+      'job "write-test" { find /users | save /output }',
+    ]);
+
+    const result = await runDevLoop({
+      intent: "copy users to output",
+      max_iterations: 1,
+      think,
+      runner: realRunner(ctx, "dry-run"),
+      validate: realValidate(),
+      observe: vi.fn(async () => {}),
+    });
+
+    expect(result.status).toBe("ok");
+    expect(result.mode).toBe("dry-run");
+    // World should NOT have been written to
+    expect(world.written["/output"]).toBeUndefined();
+    expect(Object.keys(world.written)).toHaveLength(0);
+  });
+
+  it("live mode: world IS written to", async () => {
+    const { ctx, world } = makeCtx({ "/users": [{ id: 1, name: "Alice" }] });
+    const think = thinkReturning([
+      'job "write-test" { find /users | save /output }',
+    ]);
+
+    const result = await runDevLoop({
+      intent: "copy users to output",
+      max_iterations: 1,
+      mode: "live",
+      think,
+      runner: realRunner(ctx, "live"),
+      validate: realValidate(),
+      observe: vi.fn(async () => {}),
+    });
+
+    expect(result.status).toBe("ok");
+    expect(result.mode).toBe("live");
+    // World SHOULD have been written to
+    expect(world.written["/output"]).toBeDefined();
+  });
+
+  it("all iterations fail with bad syntax → returns error with all observations", async () => {
+    const { ctx } = makeCtx();
+    const think = thinkReturning([
+      'job "bad1" { foobar }',
+      'job "bad2" { bazqux }',
+      'job "bad3" { nope }',
+    ]);
+    const observe = vi.fn(async () => {});
+
+    const result = await runDevLoop({
+      intent: "do something",
+      max_iterations: 3,
+      think,
+      runner: realRunner(ctx),
+      validate: realValidate(),
+      observe,
+    });
+
+    expect(result.status).toBe("error");
+    expect(result.iterations).toBe(3);
+    expect(result.observations).toHaveLength(3);
+    // Every observation should have validation errors
+    for (const obs of result.observations) {
+      expect(obs.validation_errors).toBeDefined();
+    }
+  });
+
+  it("correction prompt includes error details from real validation failure", async () => {
+    const { ctx } = makeCtx({ "/users": [{ id: 1 }] });
+    let correctionMessage: string | undefined;
+    let callCount = 0;
+
+    const think = vi.fn(async (req: any) => {
+      callCount++;
+      if (callCount === 2) {
+        // Capture the correction prompt on second call
+        correctionMessage = req.messages?.[0]?.content;
+      }
+      const scripts = [
+        'job "broken" { foobar }',
+        'job "fixed" { find /users }',
+      ];
+      return {
+        kind: "completed" as const,
+        response: {
+          content: "",
+          tool_calls: [{
+            id: `tc-${callCount}`,
+            name: "ash_run",
+            arguments: JSON.stringify({ script: scripts[callCount - 1] }),
+          }],
+        },
+        toolResults: [],
+      };
+    });
+
+    const result = await runDevLoop({
+      intent: "find users",
+      max_iterations: 3,
+      think,
+      runner: realRunner(ctx),
+      validate: realValidate(),
+      observe: vi.fn(async () => {}),
+    });
+
+    expect(result.status).toBe("ok");
+    expect(correctionMessage).toBeDefined();
+    expect(correctionMessage).toContain("previous ASH script failed");
+    expect(correctionMessage).toContain("ParseError");
+    expect(correctionMessage).toContain("foobar");
+  });
+
+  it("observations contain real AshRunResult from execution", async () => {
+    const { ctx } = makeCtx({ "/users": [{ id: 1 }, { id: 2 }] });
+    const think = thinkReturning(['job "real" { find /users }']);
+    const observe = vi.fn(async () => {});
+
+    await runDevLoop({
+      intent: "find users",
+      max_iterations: 1,
+      think,
+      runner: realRunner(ctx),
+      validate: realValidate(),
+      observe,
+    });
+
+    const obs = (observe.mock.calls as any)[0][0];
+    expect(obs!.result).toBeDefined();
+    expect(obs!.result.status).toBe("ok");
+    expect(obs!.result.duration_ms).toBeGreaterThanOrEqual(0);
+    expect(Array.isArray(obs!.result.steps)).toBe(true);
+  });
+
+  it("runtime error in ASH execution → loop attempts correction", async () => {
+    // Use a script that compiles but fails at runtime (e.g., read from non-existent path)
+    const { ctx } = makeCtx({}); // empty world
+    const think = thinkReturning([
+      'job "fetch" { find /nonexistent }',  // compiles, runs, returns empty
+      'job "fetch2" { find /users }',
+    ]);
+
+    const result = await runDevLoop({
+      intent: "find data",
+      max_iterations: 2,
+      think,
+      runner: realRunner(ctx),
+      validate: realValidate(),
+      observe: vi.fn(async () => {}),
+    });
+
+    // Both scripts compile and run — find with no data is still "ok" (empty result)
+    expect(result.status).toBe("ok");
+    expect(result.iterations).toBe(1); // first one already succeeds (empty find is ok)
+  });
+
+  it("e2e with real validate catching error → real run on corrected script → world unchanged (dry-run)", async () => {
+    const { ctx, world } = makeCtx({ "/data": [{ x: 1 }] });
+    const think = thinkReturning([
+      'job "bad" { unknowncmd }',               // validation error
+      'job "good" { find /data | save /out }',   // valid, will run in dry-run
+    ]);
+
+    const result = await runDevLoop({
+      intent: "process data",
+      max_iterations: 3,
+      think,
+      runner: realRunner(ctx, "dry-run"),
+      validate: realValidate(),
+      observe: vi.fn(async () => {}),
+    });
+
+    expect(result.status).toBe("ok");
+    expect(result.iterations).toBe(2);
+    // INV-1: dry-run → world unchanged
+    expect(Object.keys(world.written)).toHaveLength(0);
+    expect(Object.keys(world.published)).toHaveLength(0);
+  });
+
+  it("max_iterations=1 with valid script → single pass e2e", async () => {
+    const { ctx } = makeCtx({ "/items": [{ a: 1 }] });
+    const think = thinkReturning(['job "single" { find /items }']);
+
+    const result = await runDevLoop({
+      intent: "get items",
+      max_iterations: 1,
+      think,
+      runner: realRunner(ctx),
+      validate: realValidate(),
+      observe: vi.fn(async () => {}),
+    });
+
+    expect(result.status).toBe("ok");
+    expect(result.iterations).toBe(1);
+  });
+});

package/src/ai-dev-loop/index.ts

@@ -0,0 +1,15 @@
+/**
+ * AI Dev Loop — bounded generate → validate → run → observe → correct loop.
+ */
+export { runDevLoop } from "./dev-loop.js";
+export type { DevLoopConfig, DevLoopResult } from "./dev-loop.js";
+export { runStructured } from "./structured-runner.js";
+export { ashValidate } from "./ash-validate.js";
+export { isAshRunSuccess, isAshRunFailure } from "./ash-run-result.js";
+export type { AshRunResult, AshRunFailure, AshRunSuccess, AshStepResult } from "./ash-run-result.js";
+export { isAshTypedError, fromJobError } from "./ash-typed-error.js";
+export type { AshTypedError } from "./ash-typed-error.js";
+export { checkLivePermission } from "./live-mode.js";
+export type { LiveModePolicy } from "./live-mode.js";
+export { buildSystemPrompt, buildCorrectionPrompt } from "./system-prompt.js";
+export { ashRunToolDef, ashValidateToolDef, ashExplainErrorToolDef, META_TOOL_DEFS, executeMetaTool } from "./meta-tools.js";

package/src/ai-dev-loop/invariants.test.ts

@@ -0,0 +1,253 @@
+import { describe, it, expect, vi } from "vitest";
+import { runDevLoop } from "./dev-loop.js";
+import type { AshRunResult, AshRunFailure } from "./ash-run-result.js";
+import { isAshTypedError } from "./ash-typed-error.js";
+
+// ── Helpers ──────────────────────────────────────────────
+
+function fakeThink(scripts: string[]) {
+  let i = 0;
+  return vi.fn(async () => ({
+    kind: "completed" as const,
+    response: {
+      content: "",
+      tool_calls: [{ id: `tc-${i}`, name: "ash_run", arguments: JSON.stringify({ script: scripts[i++] ?? "" }) }],
+    },
+    toolResults: [],
+  }));
+}
+
+function fakeRunner(results: Map<string, AshRunResult>) {
+  return vi.fn(async (source: string): Promise<AshRunResult> =>
+    results.get(source) ?? { status: "ok", steps: [], output: [], duration_ms: 0 },
+  );
+}
+
+// ── INV-1: Default Dry-Run ───────────────────────────────
+
+describe("INV-1: Default execution is dry-run", () => {
+  it("default mode is dry-run", async () => {
+    const result = await runDevLoop({
+      intent: "test",
+      max_iterations: 1,
+      think: fakeThink(["script"]),
+      runner: vi.fn(async () => ({ status: "ok" as const, steps: [], output: [], duration_ms: 0 })),
+      validate: vi.fn(async () => []),
+      observe: vi.fn(async () => {}),
+    });
+    expect(result.mode).toBe("dry-run");
+  });
+
+  it("explicit live mode is live", async () => {
+    const result = await runDevLoop({
+      intent: "test",
+      max_iterations: 1,
+      mode: "live",
+      think: fakeThink(["script"]),
+      runner: vi.fn(async () => ({ status: "ok" as const, steps: [], output: [], duration_ms: 0 })),
+      validate: vi.fn(async () => []),
+      observe: vi.fn(async () => {}),
+    });
+    expect(result.mode).toBe("live");
+  });
+});
+
+// ── INV-2: Structured Typed Errors ───────────────────────
+
+describe("INV-2: Every error is AshTypedError", () => {
+  it("AshRunFailure.failedAt is always AshTypedError", async () => {
+    const failure: AshRunFailure = {
+      status: "error",
+      steps: [],
+      failedAt: { kind: "RuntimeError", message: "boom" },
+      duration_ms: 0,
+    };
+    expect(isAshTypedError(failure.failedAt)).toBe(true);
+  });
+
+  it("IntentDenied includes invariant + suggestion", () => {
+    const err = { kind: "IntentDenied" as const, invariant: "INV-1", message: "denied", suggestion: "use dry-run" };
+    expect(isAshTypedError(err)).toBe(true);
+    expect(err.invariant).toBeDefined();
+    expect(err.suggestion).toBeDefined();
+  });
+
+  it("ToolNotFound includes available[] list", () => {
+    const err = { kind: "ToolNotFound" as const, name: "foo", available: ["bar", "baz"], message: "not found" };
+    expect(isAshTypedError(err)).toBe(true);
+    expect(err.available).toEqual(["bar", "baz"]);
+  });
+
+  it("each error kind has enough info for AI self-repair", () => {
+    const errors = [
+      { kind: "IntentDenied", invariant: "INV-1", message: "denied" },
+      { kind: "CapabilityMissing", capability: "net", message: "missing" },
+      { kind: "ToolNotFound", name: "x", available: [], message: "not found" },
+      { kind: "ValidationFailed", field: "f", expected: "string", got: "number", message: "mismatch" },
+      { kind: "BudgetExceeded", device: "llm", limit: 100, used: 101, message: "over" },
+      { kind: "Timeout", step: "find", limit_ms: 1000, message: "slow" },
+      { kind: "ParseError", message: "syntax", line: 1 },
+      { kind: "RuntimeError", message: "crash" },
+    ];
+    for (const err of errors) {
+      expect(isAshTypedError(err)).toBe(true);
+      expect(err.message).toBeDefined();
+    }
+  });
+});
+
+// ── INV-3: Observe Only, Never Commit ────────────────────
+
+describe("INV-3: Observe only, never commit", () => {
+  it("every iteration calls observe", async () => {
+    const observe = vi.fn(async () => {});
+    await runDevLoop({
+      intent: "test",
+      max_iterations: 3,
+      think: fakeThink(["bad", "bad", "good"]),
+      runner: fakeRunner(new Map([
+        ["bad", { status: "error", steps: [], failedAt: { kind: "RuntimeError", message: "x" }, duration_ms: 0 } as AshRunResult],
+        ["good", { status: "ok", steps: [], output: [], duration_ms: 0 }],
+      ])),
+      validate: vi.fn(async () => []),
+      observe,
+    });
+    expect(observe).toHaveBeenCalledTimes(3);
+  });
+
+  it("no commit function is called (observe-only API)", async () => {
+    // The DevLoopConfig has observe but no commit — enforced by type system
+    const observe = vi.fn(async () => {});
+    await runDevLoop({
+      intent: "test",
+      max_iterations: 1,
+      think: fakeThink(["script"]),
+      runner: vi.fn(async () => ({ status: "ok" as const, steps: [], output: [], duration_ms: 0 })),
+      validate: vi.fn(async () => []),
+      observe,
+    });
+    // If we got here with no commit call, INV-3 holds (type system prevents commit)
+    expect(observe).toHaveBeenCalledTimes(1);
+  });
+
+  it("failed iterations are observed", async () => {
+    const observe = vi.fn(async () => {});
+    await runDevLoop({
+      intent: "test",
+      max_iterations: 2,
+      think: fakeThink(["fail1", "fail2"]),
+      runner: fakeRunner(new Map([
+        ["fail1", { status: "error", steps: [], failedAt: { kind: "RuntimeError", message: "x" }, duration_ms: 0 } as AshRunResult],
+        ["fail2", { status: "error", steps: [], failedAt: { kind: "RuntimeError", message: "y" }, duration_ms: 0 } as AshRunResult],
+      ])),
+      validate: vi.fn(async () => []),
+      observe,
+    });
+    expect(observe).toHaveBeenCalledTimes(2);
+  });
+});
+
+// ── INV-4: Bounded Iterations ────────────────────────────
+
+describe("INV-4: Bounded loop", () => {
+  it("max_iterations=5 → loop runs at most 5 times", async () => {
+    const think = fakeThink(["f1", "f2", "f3", "f4", "f5", "f6"]);
+    const runner = vi.fn(async (): Promise<AshRunResult> => ({
+      status: "error", steps: [], failedAt: { kind: "RuntimeError", message: "fail" }, duration_ms: 0,
+    }));
+
+    const result = await runDevLoop({
+      intent: "test",
+      max_iterations: 5,
+      think,
+      runner,
+      validate: vi.fn(async () => []),
+      observe: vi.fn(async () => {}),
+    });
+
+    expect(result.iterations).toBe(5);
+    expect(think).toHaveBeenCalledTimes(5);
+  });
+
+  it("max_iterations=1 → loop runs exactly 1 time", async () => {
+    const think = fakeThink(["script"]);
+    const result = await runDevLoop({
+      intent: "test",
+      max_iterations: 1,
+      think,
+      runner: vi.fn(async () => ({ status: "ok" as const, steps: [], output: [], duration_ms: 0 })),
+      validate: vi.fn(async () => []),
+      observe: vi.fn(async () => {}),
+    });
+    expect(result.iterations).toBe(1);
+    expect(think).toHaveBeenCalledTimes(1);
+  });
+
+  it("exceeding max returns last state + all observations", async () => {
+    const result = await runDevLoop({
+      intent: "test",
+      max_iterations: 3,
+      think: fakeThink(["a", "b", "c"]),
+      runner: vi.fn(async (): Promise<AshRunResult> => ({
+        status: "error", steps: [], failedAt: { kind: "RuntimeError", message: "fail" }, duration_ms: 0,
+      })),
+      validate: vi.fn(async () => []),
+      observe: vi.fn(async () => {}),
+    });
+    expect(result.status).toBe("error");
+    expect(result.observations).toHaveLength(3);
+    expect(result.finalResult).toBeDefined();
+  });
+
+  it("no infinite retry possible", async () => {
+    // Even with a runner that always fails, the loop terminates
+    const think = fakeThink(Array.from({ length: 100 }, (_, i) => `script${i}`));
+    const result = await runDevLoop({
+      intent: "test",
+      max_iterations: 10,
+      think,
+      runner: vi.fn(async (): Promise<AshRunResult> => ({
+        status: "error", steps: [], failedAt: { kind: "RuntimeError", message: "always fail" }, duration_ms: 0,
+      })),
+      validate: vi.fn(async () => []),
+      observe: vi.fn(async () => {}),
+    });
+    expect(result.iterations).toBe(10);
+    expect(think).toHaveBeenCalledTimes(10);
+  });
+});
+
+// ── INV-5: ASH is Ephemeral ─────────────────────────────
+
+describe("INV-5: ASH scripts are ephemeral", () => {
+  it("scripts are not persisted — only in observations (transient)", async () => {
+    const observe = vi.fn(async () => {});
+    const result = await runDevLoop({
+      intent: "test",
+      max_iterations: 1,
+      think: fakeThink(["ephemeral script"]),
+      runner: vi.fn(async () => ({ status: "ok" as const, steps: [], output: [], duration_ms: 0 })),
+      validate: vi.fn(async () => []),
+      observe,
+    });
+    // Script appears in observations (transient) but DevLoopResult has no persisted script field
+    expect(result.observations[0].script).toBe("ephemeral script");
+    expect((result as any).script).toBeUndefined();
+  });
+
+  it("scripts are not committed to memory — observe only", async () => {
+    // Same as INV-3: observe callback gets data, no commit API exists
+    const observe = vi.fn(async () => {});
+    await runDevLoop({
+      intent: "test",
+      max_iterations: 1,
+      think: fakeThink(["temp script"]),
+      runner: vi.fn(async () => ({ status: "ok" as const, steps: [], output: [], duration_ms: 0 })),
+      validate: vi.fn(async () => []),
+      observe,
+    });
+    const observed = (observe.mock.calls as any)[0][0];
+    expect(observed!.script).toBe("temp script");
+    // No commit was called — type system prevents it
+  });
+});

package/src/ai-dev-loop/live-mode.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect, vi } from "vitest";
+import { checkLivePermission, type LiveModePolicy } from "./live-mode.js";
+
+describe("Live Mode Permission Check", () => {
+  // ── Happy Path ─────────────────────────────────────────
+
+  it("proc with ash.live capability → allowed", async () => {
+    const policy: LiveModePolicy = { capabilities: new Set(["ash.live"]) };
+    expect(await checkLivePermission(policy)).toBe(true);
+  });
+
+  it("user confirmation returns true → allowed", async () => {
+    const policy: LiveModePolicy = {
+      capabilities: new Set(),
+      confirm: async () => true,
+    };
+    expect(await checkLivePermission(policy)).toBe(true);
+  });
+
+  it("debug profile + restricted scope → allowed", async () => {
+    const policy: LiveModePolicy = {
+      capabilities: new Set(),
+      debug: true,
+    };
+    expect(await checkLivePermission(policy)).toBe(true);
+  });
+
+  // ── Bad Path ───────────────────────────────────────────
+
+  it("no capability + no confirmation → rejected", async () => {
+    const policy: LiveModePolicy = { capabilities: new Set() };
+    expect(await checkLivePermission(policy)).toBe(false);
+  });
+
+  it("user confirmation returns false → rejected", async () => {
+    const policy: LiveModePolicy = {
+      capabilities: new Set(),
+      confirm: async () => false,
+    };
+    expect(await checkLivePermission(policy)).toBe(false);
+  });
+
+  it("non-debug profile without capability → rejected", async () => {
+    const policy: LiveModePolicy = {
+      capabilities: new Set(),
+      debug: false,
+    };
+    expect(await checkLivePermission(policy)).toBe(false);
+  });
+
+  // ── Edge Cases ─────────────────────────────────────────
+
+  it("capability + confirmation both present → capability takes priority", async () => {
+    const confirm = vi.fn(async () => false);
+    const policy: LiveModePolicy = {
+      capabilities: new Set(["ash.live"]),
+      confirm,
+    };
+    expect(await checkLivePermission(policy)).toBe(true);
+    // confirm should not be called since capability was sufficient
+    expect(confirm).not.toHaveBeenCalled();
+  });
+});

package/src/ai-dev-loop/live-mode.ts

@@ -0,0 +1,33 @@
+/**
+ * Live Mode Permission — gates upgrade from dry-run to live execution.
+ *
+ * Per INTENT §6.1, live mode requires one of:
+ * a) ash.live capability in proc caps
+ * b) User confirmation callback
+ * c) Debug profile flag
+ */
+
+export interface LiveModePolicy {
+  capabilities: Set<string>;
+  confirm?: () => Promise<boolean>;
+  debug?: boolean;
+}
+
+/**
+ * Check if live mode is permitted. Checks in priority order:
+ * 1. Capability (ash.live)
+ * 2. Debug flag
+ * 3. User confirmation
+ */
+export async function checkLivePermission(policy: LiveModePolicy): Promise<boolean> {
+  // 1. Capability takes priority
+  if (policy.capabilities.has("ash.live")) return true;
+
+  // 2. Debug profile
+  if (policy.debug) return true;
+
+  // 3. User confirmation
+  if (policy.confirm) return policy.confirm();
+
+  return false;
+}