@crewhaus/ir-passes 0.1.4 → 0.1.5

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 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]` but only ever references some of
+ *    them — e.g. an `alwaysDeny` rule naming `Write` actually counts as a
+ *    reference and KEEPS `Write` in the list; only a tool that no rule and
+ *    no sub-agent mentions at all (say `Bash` here) gets dropped.
+ *  - `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.
+ *  - `transactionPolicyEnforcement` — §47 validating pass: checks the
+ *    blockchain blocks (wallets/contracts/chains/transaction_policy) for
+ *    referential integrity and throws `IrPassError` on a mismatch.
+ *  - `wellFormednessCheck` — Track F validating pass: checks typed
+ *    multi-agent graphs/crews (edges connect declared nodes, reachability
+ *    from entry, schema/role references resolve) and throws on a violation.
+ *  - `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 → transactionPolicyEnforcement →
+ *   wellFormednessCheck → promptCachePrefixSort
+ */
+import { CrewhausError } from "@crewhaus/errors";
+import type { IrNode } from "@crewhaus/ir";
+export declare class IrPassError extends CrewhausError {
+    readonly name = "IrPassError";
+    constructor(message: string, cause?: unknown);
+}
+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 declare function applyPasses(ir: IrNode, opts?: ApplyPassesOptions): IrNode;
+/**
+ * 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 declare function deadToolElimination(ir: IrNode): IrNode;
+/**
+ * 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 declare function redundantMcpServerCollapse(ir: IrNode): IrNode;
+/**
+ * Pass 3 — sort + dedup permission rules. Within each precedence tier
+ * (alwaysDeny > alwaysAsk > alwaysAllow), rules are sorted alphabetically
+ * by pattern and exact duplicates dropped.
+ */
+export declare function permissionRuleCanonicalize(ir: IrNode): 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 declare function promptCachePrefixSort(ir: IrNode): IrNode;
+export declare function transactionPolicyEnforcement(ir: IrNode): IrNode;
+/**
+ * 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 declare function wellFormednessCheck(ir: IrNode): IrNode;
+export declare const DEFAULT_PIPELINE: ReadonlyArray<IrPass>;

package/dist/index.js

@@ -0,0 +1,375 @@
+/**
+ * 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]` but only ever references some of
+ *    them — e.g. an `alwaysDeny` rule naming `Write` actually counts as a
+ *    reference and KEEPS `Write` in the list; only a tool that no rule and
+ *    no sub-agent mentions at all (say `Bash` here) gets dropped.
+ *  - `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.
+ *  - `transactionPolicyEnforcement` — §47 validating pass: checks the
+ *    blockchain blocks (wallets/contracts/chains/transaction_policy) for
+ *    referential integrity and throws `IrPassError` on a mismatch.
+ *  - `wellFormednessCheck` — Track F validating pass: checks typed
+ *    multi-agent graphs/crews (edges connect declared nodes, reachability
+ *    from entry, schema/role references resolve) and throws on a violation.
+ *  - `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 → transactionPolicyEnforcement →
+ *   wellFormednessCheck → promptCachePrefixSort
+ */
+import { CrewhausError } from "@crewhaus/errors";
+export class IrPassError extends CrewhausError {
+    name = "IrPassError";
+    constructor(message, cause) {
+        super("compiler", message, cause);
+    }
+}
+/** Apply every pass in order; returns the final IR. */
+export function applyPasses(ir, opts = {}) {
+    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) {
+    if (ir.target !== "cli")
+        return ir;
+    const cli = ir;
+    const tools = cli.tools ?? [];
+    if (tools.length === 0)
+        return ir;
+    // Track which tool names have any reachable use site.
+    const used = new Set();
+    // 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) };
+}
+function extractToolFromPattern(pattern) {
+    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) {
+    // mcp_servers lives on cli, channel, managed
+    const carriesMcp = (n) => n.target === "cli" || n.target === "channel" || n.target === "managed";
+    if (!carriesMcp(ir))
+        return ir;
+    const ms = ir.mcp_servers;
+    if (!ms || Object.keys(ms).length < 2)
+        return ir;
+    const sigToFirstKey = new Map();
+    const keptOrdered = [];
+    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 = {};
+    for (const [k, v] of keptOrdered)
+        next[k] = v;
+    return { ...ir, mcp_servers: Object.freeze(next) };
+}
+function mcpSignature(c) {
+    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) {
+    const carriesPerms = (n) => n.target === "cli" || n.target === "channel" || n.target === "managed";
+    if (!carriesPerms(ir))
+        return ir;
+    const perms = ir.permissions;
+    if (!perms)
+        return ir;
+    const tier = (t) => t === "alwaysDeny" ? 0 : t === "alwaysAsk" ? 1 : 2;
+    const seen = new Set();
+    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 = {
+        ...perms,
+        rules: Object.freeze(sorted),
+    };
+    return { ...ir, permissions: newPerms };
+}
+/**
+ * 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) {
+    return ir;
+}
+function carriesChainSubsystem(ir) {
+    const t = ir.target;
+    return (t === "cli" ||
+        t === "workflow" ||
+        t === "channel" ||
+        t === "graph" ||
+        t === "crew" ||
+        t === "research" ||
+        t === "batch");
+}
+export function transactionPolicyEnforcement(ir) {
+    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((chains ?? []).map((c) => c.id));
+    const contractIds = new Set((contracts ?? []).map((c) => c.id));
+    // chains[] uniqueness
+    if (chains !== undefined) {
+        const seen = new Set();
+        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();
+        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();
+        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) {
+    if (ir.target === "graph") {
+        const g = ir;
+        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([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;
+        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 = Object.freeze([
+    deadToolElimination,
+    redundantMcpServerCollapse,
+    permissionRuleCanonicalize,
+    transactionPolicyEnforcement,
+    wellFormednessCheck,
+    promptCachePrefixSort,
+]);

package/package.json

@@ -1,19 +1,22 @@
 {
   "name": "@crewhaus/ir-passes",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "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",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.4",
-    "@crewhaus/ir": "0.1.4"
+    "@crewhaus/errors": "0.1.5",
+    "@crewhaus/ir": "0.1.5"
   },
   "license": "Apache-2.0",
   "author": {
@@ -33,5 +36,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }