@crewhaus/ir-passes 0.1.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@crewhaus/ir-passes",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Idempotent IR optimization passes (dead-tool-elimination, prompt-cache-prefix-sort, redundant-mcp-server-collapse, permission-rule-canonicalize)",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.0.0",
+    "@crewhaus/ir": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/ir-passes"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/ir-passes#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,380 @@
+/**
+ * Section 28 — `ir-passes` tests:
+ *  - T1 per built-in pass
+ *  - T9 idempotence (apply(apply(x)) === apply(x))
+ *  - T4 fixture replay
+ */
+import { describe, expect, test } from "bun:test";
+import type { IrNode, IrV0 } from "@crewhaus/ir";
+import {
+  DEFAULT_PIPELINE,
+  IrPassError,
+  applyPasses,
+  deadToolElimination,
+  permissionRuleCanonicalize,
+  promptCachePrefixSort,
+  redundantMcpServerCollapse,
+  transactionPolicyEnforcement,
+} from "./index";
+
+function makeCli(overrides: Partial<IrV0> = {}): IrV0 {
+  return {
+    version: 0,
+    name: "test",
+    target: "cli",
+    agent: { model: "claude-opus-4-7", instructions: "be helpful" },
+    tools: [],
+    toolConfigs: {},
+    mcp_servers: {},
+    permissions: { rules: [] },
+    subAgents: [],
+    compaction: {},
+    ...overrides,
+  };
+}
+
+describe("ir-passes — deadToolElimination (T1)", () => {
+  test("no rules + no sub-agents → returns input unchanged (no inference)", () => {
+    const ir = makeCli({ tools: ["Read", "Write", "Bash"] });
+    const out = deadToolElimination(ir) as IrV0;
+    expect(out.tools).toEqual(ir.tools);
+  });
+
+  test("with rules referring only to Read+Bash → drops Write", () => {
+    const ir = makeCli({
+      tools: ["Read", "Write", "Bash"],
+      permissions: {
+        rules: [
+          { type: "alwaysAllow", pattern: "Read" },
+          { type: "alwaysAllow", pattern: "Bash(*)" },
+        ],
+      },
+    });
+    const out = deadToolElimination(ir) as IrV0;
+    expect([...out.tools].sort()).toEqual(["Bash", "Read"]);
+  });
+
+  test("sub-agent that uses Write keeps Write in the parent's tool list", () => {
+    const ir = makeCli({
+      tools: ["Read", "Write"],
+      permissions: { rules: [{ type: "alwaysAllow", pattern: "Read" }] },
+      subAgents: [
+        {
+          name: "writer",
+          description: "writes files",
+          instructions: "x",
+          tools: ["Write"],
+          permissions: "inherit",
+          inheritBypass: false,
+        },
+      ],
+    });
+    const out = deadToolElimination(ir) as IrV0;
+    expect([...out.tools].sort()).toEqual(["Read", "Write"]);
+  });
+
+  test("non-cli targets pass through unchanged", () => {
+    // Use a fixture-shaped non-cli IR
+    const ir: IrNode = {
+      version: 0,
+      name: "wf",
+      target: "workflow",
+      steps: [],
+    } as unknown as IrNode;
+    expect(deadToolElimination(ir)).toBe(ir);
+  });
+});
+
+describe("ir-passes — redundantMcpServerCollapse (T1)", () => {
+  test("dedup stdio servers by (command, args)", () => {
+    const ir = makeCli({
+      mcp_servers: {
+        a: { transport: "stdio", command: "npx", args: ["@x"] },
+        b: { transport: "stdio", command: "npx", args: ["@x"] },
+        c: { transport: "stdio", command: "npx", args: ["@y"] },
+      },
+    });
+    const out = redundantMcpServerCollapse(ir) as IrV0;
+    expect(Object.keys(out.mcp_servers).sort()).toEqual(["a", "c"]);
+  });
+
+  test("dedup sse servers by url", () => {
+    const ir = makeCli({
+      mcp_servers: {
+        a: { transport: "sse", url: "http://x" },
+        b: { transport: "sse", url: "http://x" },
+        c: { transport: "sse", url: "http://y" },
+      },
+    });
+    const out = redundantMcpServerCollapse(ir) as IrV0;
+    expect(Object.keys(out.mcp_servers).sort()).toEqual(["a", "c"]);
+  });
+
+  test("returns input unchanged when no duplicates", () => {
+    const ir = makeCli({
+      mcp_servers: {
+        a: { transport: "stdio", command: "x", args: [] },
+      },
+    });
+    expect(redundantMcpServerCollapse(ir)).toBe(ir);
+  });
+});
+
+describe("ir-passes — permissionRuleCanonicalize (T1)", () => {
+  test("sorts by tier (deny > ask > allow) then alpha within tier", () => {
+    const ir = makeCli({
+      permissions: {
+        rules: [
+          { type: "alwaysAllow", pattern: "Read" },
+          { type: "alwaysDeny", pattern: "Bash(rm *)" },
+          { type: "alwaysAsk", pattern: "Edit" },
+          { type: "alwaysAllow", pattern: "Bash" },
+          { type: "alwaysDeny", pattern: "Write" },
+        ],
+      },
+    });
+    const out = permissionRuleCanonicalize(ir) as IrV0;
+    expect(out.permissions.rules.map((r) => `${r.type}:${r.pattern}`)).toEqual([
+      "alwaysDeny:Bash(rm *)",
+      "alwaysDeny:Write",
+      "alwaysAsk:Edit",
+      "alwaysAllow:Bash",
+      "alwaysAllow:Read",
+    ]);
+  });
+
+  test("dedups exact duplicates", () => {
+    const ir = makeCli({
+      permissions: {
+        rules: [
+          { type: "alwaysAllow", pattern: "Read" },
+          { type: "alwaysAllow", pattern: "Read" },
+          { type: "alwaysAllow", pattern: "Bash" },
+        ],
+      },
+    });
+    const out = permissionRuleCanonicalize(ir) as IrV0;
+    expect(out.permissions.rules.length).toBe(2);
+  });
+
+  test("returns input unchanged when already canonical", () => {
+    const ir = makeCli({
+      permissions: {
+        rules: [
+          { type: "alwaysDeny", pattern: "Bash(rm *)" },
+          { type: "alwaysAllow", pattern: "Read" },
+        ],
+      },
+    });
+    const out = permissionRuleCanonicalize(ir);
+    expect(out).toBe(ir);
+  });
+});
+
+describe("ir-passes — promptCachePrefixSort (T1 stub)", () => {
+  test("v0 stub returns input unchanged", () => {
+    const ir = makeCli();
+    expect(promptCachePrefixSort(ir)).toBe(ir);
+  });
+});
+
+describe("ir-passes — applyPasses + idempotence (T9)", () => {
+  test("applyPasses runs the default pipeline", () => {
+    const ir = makeCli({
+      tools: ["Read", "Write", "Bash"],
+      permissions: {
+        rules: [
+          { type: "alwaysAllow", pattern: "Read" },
+          { type: "alwaysAllow", pattern: "Read" },
+        ],
+      },
+      mcp_servers: {
+        a: { transport: "stdio", command: "x", args: [] },
+        b: { transport: "stdio", command: "x", args: [] },
+      },
+    });
+    const once = applyPasses(ir) as IrV0;
+    expect([...once.tools].sort()).toEqual(["Read"]);
+    expect(once.permissions.rules.length).toBe(1);
+    expect(Object.keys(once.mcp_servers).length).toBe(1);
+  });
+
+  test("idempotence: applyPasses(applyPasses(x)) === applyPasses(x)", () => {
+    const ir = makeCli({
+      tools: ["Read", "Write", "Bash"],
+      permissions: {
+        rules: [
+          { type: "alwaysAllow", pattern: "Read" },
+          { type: "alwaysDeny", pattern: "Bash" },
+        ],
+      },
+      mcp_servers: {
+        a: { transport: "stdio", command: "x", args: ["y"] },
+        b: { transport: "stdio", command: "x", args: ["y"] },
+      },
+    });
+    const a = applyPasses(ir);
+    const b = applyPasses(a);
+    expect(JSON.stringify(b)).toBe(JSON.stringify(a));
+  });
+
+  test("custom pipeline applied in order", () => {
+    const calls: string[] = [];
+    const passes = [
+      (n: IrNode) => {
+        calls.push("a");
+        return n;
+      },
+      (n: IrNode) => {
+        calls.push("b");
+        return n;
+      },
+    ];
+    applyPasses(makeCli(), { passes });
+    expect(calls).toEqual(["a", "b"]);
+  });
+
+  test("DEFAULT_PIPELINE has 6 passes (+ wellFormednessCheck from Track F §57)", () => {
+    expect(DEFAULT_PIPELINE.length).toBe(6);
+  });
+});
+
+describe("ir-passes — transactionPolicyEnforcement (T1, T8)", () => {
+  const baseChain = {
+    id: "base-mainnet",
+    kind: "evm" as const,
+    rpcUrls: [{ kind: "literal" as const, value: "https://rpc.test" }],
+    rpcPolicy: "single" as const,
+    finality: { kind: "finalized" as const },
+    reorgTolerant: true,
+  };
+  const treasuryWallet = {
+    id: "treasury",
+    chainId: "base-mainnet",
+    custody: "user-controlled" as const,
+    signingPolicy: "explicit-user-approval" as const,
+  };
+  const usdcContract = {
+    id: "usdc",
+    chainId: "base-mainnet",
+    address: "0xusdc",
+    abiRef: "abi://erc20",
+  };
+
+  test("empty subsystem is a no-op (existing specs untouched)", () => {
+    const ir = makeCli();
+    expect(transactionPolicyEnforcement(ir)).toBe(ir);
+  });
+
+  test("valid subsystem passes through unchanged", () => {
+    const ir = makeCli({
+      chains: [baseChain],
+      wallets: [treasuryWallet],
+      contracts: [usdcContract],
+      transactionPolicy: {
+        defaultWriteApproval: "required",
+        allowedContracts: ["usdc"],
+        simulationRequired: true,
+      },
+    });
+    expect(transactionPolicyEnforcement(ir)).toBe(ir);
+  });
+
+  test("rejects wallets[].chainId not declared in chains[]", () => {
+    const ir = makeCli({
+      chains: [baseChain],
+      wallets: [{ ...treasuryWallet, chainId: "polygon-mainnet" }],
+    });
+    expect(() => transactionPolicyEnforcement(ir)).toThrow(IrPassError);
+  });
+
+  test("rejects contracts[].chainId not declared in chains[]", () => {
+    const ir = makeCli({
+      chains: [baseChain],
+      contracts: [{ ...usdcContract, chainId: "polygon-mainnet" }],
+    });
+    expect(() => transactionPolicyEnforcement(ir)).toThrow(/not declared in chains\[\]/);
+  });
+
+  test("rejects allowedContracts entry not in contracts[].id", () => {
+    const ir = makeCli({
+      chains: [baseChain],
+      contracts: [usdcContract],
+      transactionPolicy: {
+        defaultWriteApproval: "required",
+        allowedContracts: ["unknown-token"],
+        simulationRequired: true,
+      },
+    });
+    expect(() => transactionPolicyEnforcement(ir)).toThrow(/unknown-token/);
+  });
+
+  test("rejects approval=none with non-automated wallet", () => {
+    const ir = makeCli({
+      chains: [baseChain],
+      wallets: [treasuryWallet],
+      contracts: [usdcContract],
+      transactionPolicy: {
+        defaultWriteApproval: "none",
+        allowedContracts: ["usdc"],
+        simulationRequired: false,
+      },
+    });
+    expect(() => transactionPolicyEnforcement(ir)).toThrow(/automated/);
+  });
+
+  test("accepts approval=none when every wallet is automated", () => {
+    const ir = makeCli({
+      chains: [baseChain],
+      wallets: [
+        {
+          ...treasuryWallet,
+          custody: "kms",
+          signingPolicy: "automated",
+          keyRef: { kind: "env", name: "KMS_KEY" },
+        },
+      ],
+      contracts: [usdcContract],
+      transactionPolicy: {
+        defaultWriteApproval: "none",
+        allowedContracts: ["usdc"],
+        simulationRequired: false,
+      },
+    });
+    expect(transactionPolicyEnforcement(ir)).toBe(ir);
+  });
+
+  test("rejects kms wallet without keyRef", () => {
+    const ir = makeCli({
+      chains: [baseChain],
+      wallets: [{ ...treasuryWallet, custody: "kms" }],
+    });
+    expect(() => transactionPolicyEnforcement(ir)).toThrow(/keyRef/);
+  });
+
+  test("rejects duplicate chains[].id", () => {
+    const ir = makeCli({ chains: [baseChain, baseChain] });
+    expect(() => transactionPolicyEnforcement(ir)).toThrow(/duplicate chains/);
+  });
+
+  test("rejects duplicate wallets[].id", () => {
+    const ir = makeCli({
+      chains: [baseChain],
+      wallets: [treasuryWallet, treasuryWallet],
+    });
+    expect(() => transactionPolicyEnforcement(ir)).toThrow(/duplicate wallets/);
+  });
+
+  test("non-blockchain shapes (managed, voice, browser, eval) pass through unchanged", () => {
+    const ir: IrNode = {
+      version: 0,
+      name: "test-mgd",
+      target: "managed",
+      agent: { model: "claude-opus-4-7", instructions: "hi" },
+      tenants: [{ id: "t1", budget: { maxInputTokens: 1, maxOutputTokens: 1 } }],
+      permissions: { rules: [] },
+      compaction: {},
+    };
+    expect(transactionPolicyEnforcement(ir)).toBe(ir);
+  });
+});

package/src/index.ts

@@ -0,0 +1,441 @@
+/**
+ * Section 28 — `ir-passes`. Idempotent IR optimization passes; each pass
+ * is a pure `(IrNode) → IrNode` function. The pipeline is composable and
+ * deterministic: same input → same output regardless of pass order
+ * (within the published "safe order" — see `applyPasses`).
+ *
+ * Built-in passes:
+ *  - `deadToolElimination` — drop entries from `tools` that no sub-agent
+ *    or permission rule references. Catches the common case where a spec
+ *    declares `tools: [Read, Write, Bash]` then locks Write down with an
+ *    `alwaysDeny` rule and never uses it elsewhere.
+ *  - `redundantMcpServerCollapse` — dedup `mcp_servers` map entries by
+ *    `(transport, command, args)` signature so two specs that import the
+ *    same server under different keys collapse into one boot per process.
+ *  - `permissionRuleCanonicalize` — sort + dedup `permissions.rules` by
+ *    canonical (type, pattern) tuples; preserves source priority order
+ *    (alwaysDeny > alwaysAsk > alwaysAllow) but de-dupes identical entries.
+ *  - `promptCachePrefixSort` — TODO: re-orders system-block segments so
+ *    the cache prefix is maximised. v0 stub returns IR unchanged so the
+ *    pipeline contract holds; v1 follow-up wires this once we land
+ *    multi-block system prompts in IR.
+ *
+ * Pipeline order in `applyPasses` (the safe default):
+ *   deadToolElimination → redundantMcpServerCollapse →
+ *   permissionRuleCanonicalize → promptCachePrefixSort
+ */
+import { CrewhausError } from "@crewhaus/errors";
+import type {
+  IrChainBinding,
+  IrChannelV0,
+  IrContractBinding,
+  IrCrewV0,
+  IrGraphV0,
+  IrManagedV0,
+  IrMcpServerConfig,
+  IrMcpServers,
+  IrNode,
+  IrPermissionRule,
+  IrPermissions,
+  IrTransactionPolicy,
+  IrV0,
+  IrWalletBinding,
+} from "@crewhaus/ir";
+
+export class IrPassError extends CrewhausError {
+  override readonly name = "IrPassError";
+  constructor(message: string, cause?: unknown) {
+    super("compiler", message, cause);
+  }
+}
+
+export type IrPass = (ir: IrNode) => IrNode;
+
+export type ApplyPassesOptions = {
+  /** Override the pass order. Default: safe order. */
+  readonly passes?: ReadonlyArray<IrPass>;
+};
+
+/** Apply every pass in order; returns the final IR. */
+export function applyPasses(ir: IrNode, opts: ApplyPassesOptions = {}): IrNode {
+  const pipeline = opts.passes ?? DEFAULT_PIPELINE;
+  let current = ir;
+  for (const pass of pipeline) {
+    current = pass(current);
+  }
+  return current;
+}
+
+/**
+ * Pass 1 — drop tools that no permission rule and no sub-agent references.
+ * v0 only inspects `IrV0` (the cli target) since that's where tools[] +
+ * sub_agents + permissions live in the same shape. Other targets either
+ * don't carry `tools[]` (workflow uses per-step tools) or aren't v0-IR
+ * subjects of dead-tool elimination yet (graph nodes carry their own
+ * tool sets — handled by a follow-up pass).
+ */
+export function deadToolElimination(ir: IrNode): IrNode {
+  if (ir.target !== "cli") return ir;
+  const cli = ir as IrV0;
+  const tools = cli.tools ?? [];
+  if (tools.length === 0) return ir;
+  // Track which tool names have any reachable use site.
+  const used = new Set<string>();
+  // Permission rules can reference a specific tool name (e.g. "Bash" or
+  // "Bash(rm *)"). The matcher's compilePattern parses this as the tool
+  // followed by an optional invocation pattern in parens. We look at the
+  // characters before the first `(` or `:` to extract the tool name.
+  const ruleNames = (cli.permissions?.rules ?? []).map((r) => extractToolFromPattern(r.pattern));
+  for (const n of ruleNames) if (n) used.add(n);
+  // Sub-agents inherit a subset of the parent's tools — surface them.
+  const subAgentRefs = cli.subAgents ?? [];
+  for (const sa of subAgentRefs) {
+    for (const t of sa.tools) used.add(t);
+  }
+  // Always-allow defaults: if any rule references a tool by exact name we
+  // count it; otherwise the original tool list serves as the
+  // "implicitly used" baseline. We use case-insensitive comparison since
+  // tool registration uses the lowercase variant.
+  const filtered = tools.filter(
+    (t) =>
+      used.has(t) ||
+      used.has(t.toLowerCase()) ||
+      [...used].some((u) => u.toLowerCase() === t.toLowerCase()),
+  );
+  // If no reference exists at all (rules + sub-agents both empty), return
+  // input unchanged — eliminating every tool would be wrong.
+  if (used.size === 0) return ir;
+  if (filtered.length === tools.length) return ir;
+  return { ...cli, tools: Object.freeze(filtered) } as IrNode;
+}
+
+function extractToolFromPattern(pattern: string): string | undefined {
+  if (!pattern) return undefined;
+  // Strip a `(...)` invocation suffix: "Bash(rm *)" → "Bash".
+  const parenIdx = pattern.indexOf("(");
+  const head = (parenIdx === -1 ? pattern : pattern.slice(0, parenIdx)).trim();
+  if (!head) return undefined;
+  return head;
+}
+
+/**
+ * Pass 2 — collapse `mcp_servers` entries that share `(transport, command,
+ * args)` (stdio) or `(transport, url)` (sse). The first key wins on
+ * collision; later duplicates are dropped. Order is preserved for entries
+ * that survive.
+ */
+export function redundantMcpServerCollapse(ir: IrNode): IrNode {
+  // mcp_servers lives on cli, channel, managed
+  const carriesMcp = (n: IrNode): n is IrV0 | IrChannelV0 | IrManagedV0 =>
+    n.target === "cli" || n.target === "channel" || n.target === "managed";
+  if (!carriesMcp(ir)) return ir;
+  const ms = (ir as { mcp_servers?: IrMcpServers }).mcp_servers;
+  if (!ms || Object.keys(ms).length < 2) return ir;
+  const sigToFirstKey = new Map<string, string>();
+  const keptOrdered: Array<[string, IrMcpServerConfig]> = [];
+  for (const [k, v] of Object.entries(ms)) {
+    const sig = mcpSignature(v);
+    if (sigToFirstKey.has(sig)) continue;
+    sigToFirstKey.set(sig, k);
+    keptOrdered.push([k, v]);
+  }
+  if (keptOrdered.length === Object.keys(ms).length) return ir;
+  const next: Record<string, IrMcpServerConfig> = {};
+  for (const [k, v] of keptOrdered) next[k] = v;
+  return { ...ir, mcp_servers: Object.freeze(next) } as IrNode;
+}
+
+function mcpSignature(c: IrMcpServerConfig): string {
+  if (c.transport === "stdio") {
+    return `stdio|${c.command}|${(c.args ?? []).join(" ")}`;
+  }
+  return `sse|${c.url}`;
+}
+
+/**
+ * Pass 3 — sort + dedup permission rules. Within each precedence tier
+ * (alwaysDeny > alwaysAsk > alwaysAllow), rules are sorted alphabetically
+ * by pattern and exact duplicates dropped.
+ */
+export function permissionRuleCanonicalize(ir: IrNode): IrNode {
+  const carriesPerms = (n: IrNode): n is IrV0 | IrChannelV0 | IrManagedV0 =>
+    n.target === "cli" || n.target === "channel" || n.target === "managed";
+  if (!carriesPerms(ir)) return ir;
+  const perms = (ir as { permissions?: IrPermissions }).permissions;
+  if (!perms) return ir;
+  const tier = (t: IrPermissionRule["type"]): number =>
+    t === "alwaysDeny" ? 0 : t === "alwaysAsk" ? 1 : 2;
+  const seen = new Set<string>();
+  const sorted = [...perms.rules]
+    .map((r) => ({ r, key: `${r.type}:${r.pattern}` }))
+    .filter(({ key }) => {
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    })
+    .sort((a, b) => {
+      const ta = tier(a.r.type);
+      const tb = tier(b.r.type);
+      if (ta !== tb) return ta - tb;
+      return a.r.pattern.localeCompare(b.r.pattern);
+    })
+    .map(({ r }) => r);
+  if (sorted.length === perms.rules.length) {
+    let identical = true;
+    for (let i = 0; i < sorted.length; i++) {
+      if (sorted[i] !== perms.rules[i]) {
+        identical = false;
+        break;
+      }
+    }
+    if (identical) return ir;
+  }
+  const newPerms: IrPermissions = {
+    ...perms,
+    rules: Object.freeze(sorted),
+  };
+  return { ...ir, permissions: newPerms } as IrNode;
+}
+
+/**
+ * Pass 4 — re-order system-block segments to maximise the prompt-cache
+ * prefix. v0 stub: IR carries the system prompt as a single string, so
+ * there's no segmentation to reorder yet. Returns input unchanged.
+ * The placeholder keeps the pipeline contract stable; once IR carries
+ * multi-block system prompts (Section 31's Studio v1 paths), the real
+ * impl lands here.
+ */
+export function promptCachePrefixSort(ir: IrNode): IrNode {
+  return ir;
+}
+
+/**
+ * Pass 5 — §47 transaction-policy enforcement. Validates the
+ * cross-cutting blockchain blocks at compile time so the runtime
+ * can rely on referential integrity:
+ *
+ *   - every `wallets[].chainId` references a declared `chains[].id`
+ *   - every `contracts[].chainId` references a declared `chains[].id`
+ *   - every `transaction_policy.allowed_contracts` entry references
+ *     a declared `contracts[].id`
+ *   - `transaction_policy.defaultWriteApproval = "none"` is only
+ *     permitted when every wallet is `automated` custody
+ *   - declared wallets without a key reference are user-controlled
+ *     (kms / hsm / local custody require `keyRef`)
+ *
+ * Mismatches throw `IrPassError` so compilation halts before any
+ * bundle is emitted. The wallet-engine also re-checks these at
+ * runtime (defense in depth); this pass catches mistakes at the
+ * earliest possible point.
+ */
+type CarriesChainSubsystem = {
+  readonly chains?: ReadonlyArray<IrChainBinding>;
+  readonly wallets?: ReadonlyArray<IrWalletBinding>;
+  readonly contracts?: ReadonlyArray<IrContractBinding>;
+  readonly transactionPolicy?: IrTransactionPolicy;
+};
+
+function carriesChainSubsystem(ir: IrNode): ir is IrNode & CarriesChainSubsystem {
+  const t = ir.target;
+  return (
+    t === "cli" ||
+    t === "workflow" ||
+    t === "channel" ||
+    t === "graph" ||
+    t === "crew" ||
+    t === "research" ||
+    t === "batch"
+  );
+}
+
+export function transactionPolicyEnforcement(ir: IrNode): IrNode {
+  if (!carriesChainSubsystem(ir)) return ir;
+  const chains = ir.chains;
+  const wallets = ir.wallets;
+  const contracts = ir.contracts;
+  const policy = ir.transactionPolicy;
+
+  // Empty subsystem is a no-op (existing specs untouched).
+  if (
+    (chains === undefined || chains.length === 0) &&
+    (wallets === undefined || wallets.length === 0) &&
+    (contracts === undefined || contracts.length === 0) &&
+    policy === undefined
+  ) {
+    return ir;
+  }
+
+  const chainIds = new Set<string>((chains ?? []).map((c) => c.id));
+  const contractIds = new Set<string>((contracts ?? []).map((c) => c.id));
+
+  // chains[] uniqueness
+  if (chains !== undefined) {
+    const seen = new Set<string>();
+    for (const c of chains) {
+      if (seen.has(c.id)) {
+        throw new IrPassError(`duplicate chains[].id "${c.id}"`);
+      }
+      seen.add(c.id);
+    }
+  }
+
+  // wallets[*].chainId ⊆ chains[].id; keyRef required for non-user-controlled
+  if (wallets !== undefined) {
+    const seen = new Set<string>();
+    for (const w of wallets) {
+      if (seen.has(w.id)) {
+        throw new IrPassError(`duplicate wallets[].id "${w.id}"`);
+      }
+      seen.add(w.id);
+      if (!chainIds.has(w.chainId)) {
+        throw new IrPassError(
+          `wallets[].id "${w.id}" references chainId "${w.chainId}" which is not declared in chains[]`,
+        );
+      }
+      if (w.custody !== "user-controlled" && w.keyRef === undefined) {
+        throw new IrPassError(
+          `wallets[].id "${w.id}" has custody="${w.custody}" but no keyRef; kms/hsm/local custody requires keyRef`,
+        );
+      }
+    }
+  }
+
+  // contracts[*].chainId ⊆ chains[].id
+  if (contracts !== undefined) {
+    const seen = new Set<string>();
+    for (const c of contracts) {
+      if (seen.has(c.id)) {
+        throw new IrPassError(`duplicate contracts[].id "${c.id}"`);
+      }
+      seen.add(c.id);
+      if (!chainIds.has(c.chainId)) {
+        throw new IrPassError(
+          `contracts[].id "${c.id}" references chainId "${c.chainId}" which is not declared in chains[]`,
+        );
+      }
+    }
+  }
+
+  // transaction_policy.allowed_contracts ⊆ contracts[].id
+  if (policy !== undefined) {
+    for (const cid of policy.allowedContracts) {
+      if (!contractIds.has(cid)) {
+        throw new IrPassError(
+          `transaction_policy.allowedContracts entry "${cid}" is not a declared contracts[].id`,
+        );
+      }
+    }
+    if (policy.defaultWriteApproval === "none") {
+      const allAutomated = (wallets ?? []).every((w) => w.signingPolicy === "automated");
+      if (!allAutomated) {
+        throw new IrPassError(
+          'transaction_policy.defaultWriteApproval="none" requires every wallet to have signingPolicy="automated"',
+        );
+      }
+    }
+  }
+
+  // No structural rewrite — the pass validates and passes through.
+  return ir;
+}
+
+/**
+ * Track F (Section 57) — well-formedness check for typed multi-agent
+ * graphs. Source: AgentFlow (arxiv 2604.20801). Before any candidate
+ * harness is sent for expensive LLM evaluation, this pass:
+ *
+ *   1. Verifies every graph edge connects declared nodes.
+ *   2. Verifies the graph is connected (every node reachable from entry).
+ *   3. Verifies every edge's `schema` either is `untyped` or resolves
+ *      to a declared `messageSchemas` entry.
+ *   4. For crews: verifies routing.match targets all reference declared
+ *      roles (a subset of what `parseSpec` does; we re-check here so
+ *      `applyPasses(ir)` is safe to call standalone).
+ *
+ * Failing this check is fast and cheap, which means the search budget
+ * for upstream optimizers (Tracks D, E) goes to well-formed harnesses
+ * only. Cited paper: AgentFlow (arxiv 2604.20801).
+ */
+export function wellFormednessCheck(ir: IrNode): IrNode {
+  if (ir.target === "graph") {
+    const g = ir as IrGraphV0;
+    const nodeNames = new Set(g.nodes.map((n) => n.name));
+    if (!nodeNames.has(g.entry)) {
+      throw new IrPassError(
+        `graph entry "${g.entry}" is not a declared node (nodes: ${[...nodeNames].join(", ")})`,
+      );
+    }
+    const schemaNames = new Set((g.messageSchemas ?? []).map((s) => s.name));
+    for (const e of g.edges) {
+      if (!nodeNames.has(e.from)) {
+        throw new IrPassError(`graph edge from "${e.from}" references an undeclared node`);
+      }
+      if (!nodeNames.has(e.to)) {
+        throw new IrPassError(`graph edge to "${e.to}" references an undeclared node`);
+      }
+      if (e.schema !== undefined && e.schema.kind === "named") {
+        if (!schemaNames.has(e.schema.name)) {
+          throw new IrPassError(
+            `graph edge ${e.from}→${e.to} references undeclared message schema "${e.schema.name}"`,
+          );
+        }
+      }
+    }
+    // Reachability from entry.
+    const reachable = new Set<string>([g.entry]);
+    let added = true;
+    while (added) {
+      added = false;
+      for (const e of g.edges) {
+        if (reachable.has(e.from) && !reachable.has(e.to)) {
+          reachable.add(e.to);
+          added = true;
+        }
+      }
+    }
+    for (const n of g.nodes) {
+      if (!reachable.has(n.name)) {
+        throw new IrPassError(`graph node "${n.name}" is unreachable from entry "${g.entry}"`);
+      }
+    }
+  } else if (ir.target === "crew") {
+    const c = ir as IrCrewV0;
+    const roleNames = new Set(c.roles.map((r) => r.name));
+    if (!roleNames.has(c.entry)) {
+      throw new IrPassError(
+        `crew entry "${c.entry}" is not a declared role (roles: ${[...roleNames].join(", ")})`,
+      );
+    }
+    const schemaNames = new Set((c.messageSchemas ?? []).map((s) => s.name));
+    if (c.routing?.kind === "match" && c.routing.match !== undefined) {
+      for (const [from, rules] of Object.entries(c.routing.match)) {
+        if (!roleNames.has(from)) {
+          throw new IrPassError(`crew routing.match["${from}"]: source role not declared`);
+        }
+        for (const rule of rules) {
+          if (!roleNames.has(rule.to)) {
+            throw new IrPassError(
+              `crew routing.match["${from}"].to "${rule.to}": target role not declared`,
+            );
+          }
+        }
+      }
+    }
+    // Schema declarations exist (they're optional but if present they must
+    // be uniquely named). This catches the easy authoring bug of declaring
+    // two schemas with the same name.
+    if (schemaNames.size !== (c.messageSchemas ?? []).length) {
+      throw new IrPassError("crew messageSchemas contains duplicate names");
+    }
+  }
+  return ir;
+}
+
+export const DEFAULT_PIPELINE: ReadonlyArray<IrPass> = Object.freeze([
+  deadToolElimination,
+  redundantMcpServerCollapse,
+  permissionRuleCanonicalize,
+  transactionPolicyEnforcement,
+  wellFormednessCheck,
+  promptCachePrefixSort,
+]);

package/src/wellformedness.test.ts

@@ -0,0 +1,118 @@
+/**
+ * Track F (§57) — wellformedness check tests. Source: AgentFlow
+ * (arxiv 2604.20801).
+ */
+import { describe, expect, test } from "bun:test";
+import type { IrCrewV0, IrGraphV0 } from "@crewhaus/ir";
+import { IrPassError, wellFormednessCheck } from "./index";
+
+const baseGraph: IrGraphV0 = {
+  version: 0,
+  name: "test-graph",
+  target: "graph",
+  entry: "a",
+  nodes: [
+    { name: "a", instructions: "node a", model: "m", tools: [], toolConfigs: {} },
+    { name: "b", instructions: "node b", model: "m", tools: [], toolConfigs: {} },
+  ],
+  edges: [{ from: "a", to: "b" }],
+  permissions: { rules: [] },
+  compaction: {},
+};
+
+describe("Track F — wellFormednessCheck (graph)", () => {
+  test("accepts a well-formed graph", () => {
+    expect(() => wellFormednessCheck(baseGraph)).not.toThrow();
+  });
+
+  test("rejects edge referencing undeclared node", () => {
+    const bad: IrGraphV0 = {
+      ...baseGraph,
+      edges: [{ from: "a", to: "ghost" }],
+    };
+    expect(() => wellFormednessCheck(bad)).toThrow(IrPassError);
+  });
+
+  test("rejects unreachable node", () => {
+    const bad: IrGraphV0 = {
+      ...baseGraph,
+      nodes: [
+        ...baseGraph.nodes,
+        { name: "orphan", instructions: "x", model: "m", tools: [], toolConfigs: {} },
+      ],
+    };
+    expect(() => wellFormednessCheck(bad)).toThrow(IrPassError);
+  });
+
+  test("rejects entry that's not a declared node", () => {
+    const bad: IrGraphV0 = { ...baseGraph, entry: "missing" };
+    expect(() => wellFormednessCheck(bad)).toThrow(IrPassError);
+  });
+
+  test("rejects edge schema that references undeclared schema", () => {
+    const bad: IrGraphV0 = {
+      ...baseGraph,
+      edges: [{ from: "a", to: "b", schema: { kind: "named", name: "ghost-schema" } }],
+    };
+    expect(() => wellFormednessCheck(bad)).toThrow(IrPassError);
+  });
+
+  test("accepts edge with untyped schema", () => {
+    const g: IrGraphV0 = {
+      ...baseGraph,
+      edges: [{ from: "a", to: "b", schema: { kind: "untyped" } }],
+    };
+    expect(() => wellFormednessCheck(g)).not.toThrow();
+  });
+
+  test("accepts edge with declared named schema", () => {
+    const g: IrGraphV0 = {
+      ...baseGraph,
+      messageSchemas: [{ name: "decision", schema: { type: "object" } }],
+      edges: [{ from: "a", to: "b", schema: { kind: "named", name: "decision" } }],
+    };
+    expect(() => wellFormednessCheck(g)).not.toThrow();
+  });
+});
+
+const baseCrew: IrCrewV0 = {
+  version: 0,
+  name: "test-crew",
+  target: "crew",
+  entry: "alpha",
+  roles: [
+    { name: "alpha", model: "m", instructions: "a", tools: [], toolConfigs: {}, subAgents: [] },
+    { name: "beta", model: "m", instructions: "b", tools: [], toolConfigs: {}, subAgents: [] },
+  ],
+  mcp_servers: {},
+  permissions: { rules: [] },
+  compaction: {},
+};
+
+describe("Track F — wellFormednessCheck (crew)", () => {
+  test("accepts a well-formed crew", () => {
+    expect(() => wellFormednessCheck(baseCrew)).not.toThrow();
+  });
+
+  test("rejects routing.match to undeclared role", () => {
+    const bad: IrCrewV0 = {
+      ...baseCrew,
+      routing: {
+        kind: "match",
+        match: { alpha: [{ contains: "x", to: "ghost" }] },
+      },
+    };
+    expect(() => wellFormednessCheck(bad)).toThrow(IrPassError);
+  });
+
+  test("rejects duplicate messageSchemas", () => {
+    const bad: IrCrewV0 = {
+      ...baseCrew,
+      messageSchemas: [
+        { name: "dup", schema: { type: "object" } },
+        { name: "dup", schema: { type: "object" } },
+      ],
+    };
+    expect(() => wellFormednessCheck(bad)).toThrow(IrPassError);
+  });
+});