@occasiolabs/occasio 0.8.1

package/src/boundary.js

@@ -0,0 +1,238 @@
+'use strict';
+
+/**
+ * boundary.js — per-request "what crossed the boundary" view.
+ *
+ * Reads existing per-request JSONL entries from ~/.occasio/logs/ and
+ * projects each request into a three-column accounting:
+ *
+ *   produced  — raw bytes/tokens each tool emitted
+ *   re-entered — bytes/tokens that actually re-entered the model's next request
+ *   prevented  — bytes/tokens kept out, classified by reason
+ *
+ * The data primitives (`bytes`, `kept_bytes`, `prevention_reason`) are
+ * recorded per tool call in `interceptor.js`. Older log entries that predate
+ * the new fields are handled by falling back to `bytes` (treated as "kept
+ * fully"). No new audit-chain fields are introduced.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+const LOG_DIR = path.join(os.homedir(), '.occasio', 'logs');
+
+// Char-per-token ratio used by the analyzer. Approximate; every token
+// figure surfaced by this module is prefixed with '~' in the renderer.
+const CHARS_PER_TOKEN = 4;
+
+function estTokens(bytes) {
+  return Math.ceil((bytes || 0) / CHARS_PER_TOKEN);
+}
+
+const PREVENTION_LABELS = {
+  distill_clip:    'distilled',
+  redact_secrets:  'redacted',
+  block:           'blocked',
+  context_budget:  'budget-clipped',
+};
+
+/**
+ * Build a per-request boundary view from a single JSONL log entry.
+ *
+ * @param  {object} entry  parsed JSONL log entry
+ * @returns {object|null}  { iso, model, event_type, tools: [...], totals: {...} }
+ */
+function buildBoundaryView(entry) {
+  if (!entry || typeof entry !== 'object') return null;
+  const toolRuns = Array.isArray(entry.tools) ? entry.tools : [];
+
+  const tools = toolRuns.map((t) => {
+    const raw  = typeof t.bytes      === 'number' ? t.bytes      : 0;
+    // Backward compat: log entries written before kept_bytes treat the entire
+    // raw output as kept (no shaping was recorded).
+    const kept = typeof t.kept_bytes === 'number' ? t.kept_bytes : raw;
+    const prevented = Math.max(0, raw - kept);
+    const reason =
+      t.prevention_reason ||
+      (t.distilled        ? 'distill_clip'   :
+       t.secretsRedacted  ? 'redact_secrets' :
+       t.blocked          ? 'block'          : null);
+
+    return {
+      tool:         t.tool || '(unknown)',
+      tool_use_id:  t.tool_use_id || null,
+      cmd:          t.cmd  || '',
+      raw_bytes:        raw,
+      kept_bytes:       kept,
+      prevented_bytes:  prevented,
+      raw_tokens:       estTokens(raw),
+      kept_tokens:      estTokens(kept),
+      prevented_tokens: estTokens(prevented),
+      prevention_reason: reason,
+      prevention_label:  reason ? (PREVENTION_LABELS[reason] || reason) : null,
+      native:           !!t.native,
+    };
+  });
+
+  const totalRaw       = tools.reduce((s, t) => s + t.raw_bytes,       0);
+  const totalKept      = tools.reduce((s, t) => s + t.kept_bytes,      0);
+  const totalPrevented = Math.max(0, totalRaw - totalKept);
+
+  return {
+    iso:        entry.iso,
+    model:      entry.model || '',
+    event_type: entry.event_type || '',
+    run_id:     entry.run_id || null,
+    tools,
+    totals: {
+      raw_bytes:        totalRaw,
+      kept_bytes:       totalKept,
+      prevented_bytes:  totalPrevented,
+      raw_tokens:       estTokens(totalRaw),
+      kept_tokens:      estTokens(totalKept),
+      prevented_tokens: estTokens(totalPrevented),
+    },
+  };
+}
+
+// ── Renderer ──────────────────────────────────────────────────────────────────
+
+const C = (() => {
+  const noColor = process.env.NO_COLOR || !process.stdout.isTTY;
+  if (noColor) return new Proxy({}, { get: () => (s) => s });
+  return {
+    b: (s) => `\x1b[1m${s}\x1b[0m`,
+    d: (s) => `\x1b[2m${s}\x1b[0m`,
+    g: (s) => `\x1b[32m${s}\x1b[0m`,
+    y: (s) => `\x1b[33m${s}\x1b[0m`,
+    c: (s) => `\x1b[36m${s}\x1b[0m`,
+    r: (s) => `\x1b[31m${s}\x1b[0m`,
+  };
+})();
+
+function fmtBytes(b) {
+  if (b < 1024) return `${b} B`;
+  return `${(b / 1024).toFixed(1)} KB`;
+}
+
+function renderBoundaryView(view, opts = {}) {
+  if (!view) return '';
+  const lines = [];
+  const tag = view.event_type ? `[${view.event_type}]` : '';
+  lines.push('');
+  lines.push(`${C.b('Request')}  ${C.d(view.iso || '')}  ${C.d(view.model)}  ${C.d(tag)}`);
+  lines.push('');
+
+  if (view.tools.length === 0) {
+    lines.push(C.d('  (no tool calls in this request)'));
+    return lines.join('\n');
+  }
+
+  lines.push(`  ${C.b('Tool'.padEnd(12))} ${C.b('Target'.padEnd(34))} ${C.b('Produced'.padEnd(16))} ${C.b('Re-entered'.padEnd(16))} ${C.b('Prevented')}`);
+  lines.push(`  ${C.d('─'.repeat(12))} ${C.d('─'.repeat(34))} ${C.d('─'.repeat(16))} ${C.d('─'.repeat(16))} ${C.d('─'.repeat(20))}`);
+
+  for (const t of view.tools) {
+    const target = (t.cmd || '').slice(0, 32).padEnd(34);
+    const produced = `${fmtBytes(t.raw_bytes)} ~${t.raw_tokens}t`.padEnd(16);
+    const kept = (t.kept_bytes === t.raw_bytes ? C.g(`${fmtBytes(t.kept_bytes)} ~${t.kept_tokens}t`) : C.y(`${fmtBytes(t.kept_bytes)} ~${t.kept_tokens}t`)).padEnd(t.kept_bytes === t.raw_bytes ? 21 : 21);
+    const prevented = t.prevented_bytes === 0
+      ? C.d('—')
+      : `${C.r('~' + t.prevented_tokens + 't')} ${C.d('(' + t.prevention_label + ')')}`;
+    lines.push(`  ${t.tool.padEnd(12)} ${target} ${produced} ${kept} ${prevented}`);
+  }
+
+  lines.push('');
+  lines.push(`  ${C.b('Totals:')}`);
+  lines.push(`    produced       ${fmtBytes(view.totals.raw_bytes)}  ~${view.totals.raw_tokens}t`);
+  lines.push(`    re-entered     ${C.g(fmtBytes(view.totals.kept_bytes) + '  ~' + view.totals.kept_tokens + 't')}`);
+  lines.push(`    prevented      ${view.totals.prevented_bytes === 0
+    ? C.d('0 B  ~0t')
+    : C.r(fmtBytes(view.totals.prevented_bytes) + '  ~' + view.totals.prevented_tokens + 't')}`);
+  lines.push('');
+  lines.push(C.d('  Token figures are approximate (chars/4). Audit chain at') + ' ' + C.d('~/.occasio/pipeline-events.jsonl'));
+  return lines.join('\n');
+}
+
+// ── Log reader ────────────────────────────────────────────────────────────────
+
+function readEntries({ scope = 'today' } = {}) {
+  const today = (() => {
+    const d = new Date();
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+  })();
+
+  let files = [];
+  try {
+    files = fs.readdirSync(LOG_DIR).filter(f => f.endsWith('.jsonl'));
+  } catch { /* logs dir absent */ }
+  if (scope === 'today') files = files.filter(f => f === `${today}.jsonl`);
+  files.sort();
+
+  const entries = [];
+  for (const f of files) {
+    let text;
+    try { text = fs.readFileSync(path.join(LOG_DIR, f), 'utf8'); } catch { continue; }
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue;
+      try { entries.push(JSON.parse(line)); } catch { /* skip malformed */ }
+    }
+  }
+  return entries;
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────────
+
+function runBoundaryCli(args = []) {
+  const lastIdx  = args.indexOf('--last');
+  const entryIdx = args.indexOf('--entry');
+  const runIdx   = args.indexOf('--run');
+  const json     = args.includes('--json');
+  const scopeIdx = args.indexOf('--scope');
+
+  const scope = scopeIdx >= 0 ? (args[scopeIdx + 1] || 'today') : 'today';
+  const all = readEntries({ scope });
+  if (all.length === 0) {
+    process.stdout.write('\n  ' + C.d('No requests in scope. Run a session first.') + '\n');
+    return { ok: true, count: 0 };
+  }
+
+  // Selection: --entry N (1-indexed), --run <prefix>, --last N, default last 1
+  let selected;
+  if (entryIdx >= 0) {
+    const n = parseInt(args[entryIdx + 1], 10);
+    selected = isFinite(n) && n >= 1 && n <= all.length ? [all[n - 1]] : [];
+  } else if (runIdx >= 0) {
+    const prefix = (args[runIdx + 1] || '');
+    selected = all.filter(e => (e.run_id || '').startsWith(prefix));
+  } else {
+    const n = lastIdx >= 0 ? Math.max(1, parseInt(args[lastIdx + 1], 10) || 1) : 1;
+    selected = all.slice(-n);
+  }
+
+  if (selected.length === 0) {
+    process.stdout.write('\n  ' + C.d('No matching requests.') + '\n');
+    return { ok: false, count: 0 };
+  }
+
+  if (json) {
+    const views = selected.map(buildBoundaryView).filter(Boolean);
+    process.stdout.write(JSON.stringify(views, null, 2) + '\n');
+    return { ok: true, count: views.length };
+  }
+
+  process.stdout.write('\n' + C.b('Occasio Boundary') + '   ' +
+    C.d(`scope: ${scope}  ·  ${all.length} entries  ·  showing ${selected.length}`) + '\n');
+  for (const e of selected) {
+    const view = buildBoundaryView(e);
+    process.stdout.write(renderBoundaryView(view) + '\n');
+  }
+  return { ok: true, count: selected.length };
+}
+
+module.exports = {
+  buildBoundaryView,
+  renderBoundaryView,
+  runBoundaryCli,
+  readEntries,
+};

package/src/budget.js

@@ -0,0 +1,42 @@
+'use strict';
+
+/**
+ * budget.js — Pure budget-enforcement helpers.
+ * No I/O.  Import in index.js and test-interceptor.js.
+ */
+
+const WARN_THRESHOLD = 0.80;   // emit warning once at 80 % of budget
+const BUDGET_EXCEEDED_EVENT = 'budget_exceeded';
+
+/**
+ * Given current session spend and the configured budget limit, return the
+ * enforcement state that the caller should act on.
+ *
+ * @param {number}       spent   Accumulated session cost so far (before this request)
+ * @param {number|null}  budget  Dollar limit (null = no budget)
+ * @returns {{ exceeded: boolean, warnNow: boolean, pct: number|null }}
+ *   exceeded  – true if spend >= budget (block the request)
+ *   warnNow   – true if spend crossed the warning threshold (fire at most once)
+ *   pct       – spend / budget ratio (null when no budget)
+ */
+function budgetStatus(spent, budget) {
+  if (budget == null || budget <= 0) return { exceeded: false, warnNow: false, pct: null };
+  const pct = spent / budget;
+  return {
+    exceeded: pct >= 1.0,
+    warnNow:  pct >= WARN_THRESHOLD,
+    pct,
+  };
+}
+
+/**
+ * Format a spend-vs-budget string for display.
+ * e.g. "$0.85 / $1.0000 (85%)"
+ */
+function fmtBudget(spent, budget) {
+  if (budget == null) return '';
+  const pct = Math.min(999, Math.round(spent / budget * 100));
+  return `$${spent.toFixed(4)} / $${budget.toFixed(4)} (${pct}%)`;
+}
+
+module.exports = { budgetStatus, fmtBudget, WARN_THRESHOLD, BUDGET_EXCEEDED_EVENT };

package/src/classifier.js

@@ -0,0 +1,115 @@
+'use strict';
+
+/**
+ * classifier.js — Semantic routing for Bash tool_use calls.
+ *
+ * Replaces the simple LOCAL_BASH_CMDS whitelist with structured class data
+ * from embeddings.json. Key improvements over the whitelist:
+ *
+ *   1. Git subcommand awareness — "git push" is rejected, "git log" is accepted.
+ *   2. Dangerous flag detection — "--force", "--hard" block interception.
+ *   3. Extensible via embeddings.json without code changes.
+ *   4. Routing feedback log for future ML training.
+ *
+ * routeLocally() is the public interface.
+ * isInterceptable() in interceptor.js delegates here.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+const DATA         = require('./embeddings.json');
+const ALWAYS_LOCAL = new Set(DATA.always_local);
+const NEVER_LOCAL  = new Set(DATA.never_local);
+const GIT_SAFE     = new Set(DATA.git_safe_subcommands);
+const GIT_UNSAFE   = new Set(DATA.git_unsafe_subcommands);
+const DANGER_FLAGS = new Set(DATA.dangerous_flags);
+const SHELL_META   = /[;&|`$<>\\]/;
+
+const FEEDBACK_LOG = path.join(os.homedir(), '.occasio', 'routing-feedback.jsonl');
+
+/**
+ * Decide whether a tool call should be executed locally.
+ *
+ * @param {string} toolName   e.g. "Bash"
+ * @param {string} command    the command string
+ * @param {string} [context]  reserved for future ML use
+ * @returns {{ local: boolean, confidence: number, reason: string }}
+ */
+function routeLocally(toolName, command, context = '') {
+  if (toolName !== 'Bash') {
+    return { local: false, confidence: 1.0, reason: 'non-bash tool' };
+  }
+
+  const cmd = (command || '').trim();
+  if (!cmd) {
+    return { local: false, confidence: 1.0, reason: 'empty command' };
+  }
+  if (SHELL_META.test(cmd)) {
+    return { local: false, confidence: 1.0, reason: 'shell metacharacter' };
+  }
+
+  const parts     = cmd.split(/\s+/);
+  const firstWord = parts[0].toLowerCase();
+
+  // Dangerous flags anywhere in the command override everything.
+  // Check exact case (git -D is uppercase, distinct from -d) then also lowercase
+  // so --Force and similar variants are still caught.
+  const hasDangerFlag = parts.slice(1).some(p => DANGER_FLAGS.has(p) || DANGER_FLAGS.has(p.toLowerCase()));
+  if (hasDangerFlag) {
+    return { local: false, confidence: 0.95, reason: 'dangerous flag' };
+  }
+
+  // Hard block
+  if (NEVER_LOCAL.has(firstWord)) {
+    return { local: false, confidence: 0.95, reason: `${firstWord}: write/execute command` };
+  }
+
+  // Git requires subcommand-level inspection
+  if (firstWord === 'git') {
+    const sub = (parts[1] || '').toLowerCase();
+    if (GIT_SAFE.has(sub)) {
+      return { local: true, confidence: 0.95, reason: `git ${sub}: read-only` };
+    }
+    if (GIT_UNSAFE.has(sub) || sub === '') {
+      return { local: false, confidence: 0.92, reason: `git ${sub || '(bare)'}: write/network operation` };
+    }
+    // Unknown git subcommand — conservative
+    return { local: false, confidence: 0.65, reason: `git ${sub}: unknown subcommand` };
+  }
+
+  // Safe read commands
+  if (ALWAYS_LOCAL.has(firstWord)) {
+    return { local: true, confidence: 0.95, reason: `${firstWord}: safe read command` };
+  }
+
+  // Unknown — default to cloud
+  return { local: false, confidence: 0.6, reason: `${firstWord}: unknown command` };
+}
+
+/**
+ * Append a routing decision to the feedback log for future training.
+ *
+ * @param {string} command
+ * @param {{ local: boolean, confidence: number, reason: string }} decision
+ * @param {number} latency_ms
+ * @param {'success'|'error'|'timeout'} outcome
+ */
+function logRoutingDecision(command, decision, latency_ms, outcome) {
+  try {
+    const entry = JSON.stringify({
+      ts:         new Date().toISOString(),
+      command:    (command || '').slice(0, 200),
+      local:      decision.local,
+      confidence: decision.confidence,
+      reason:     decision.reason,
+      latency_ms,
+      outcome,
+    }) + '\n';
+    fs.mkdirSync(path.dirname(FEEDBACK_LOG), { recursive: true });
+    fs.appendFileSync(FEEDBACK_LOG, entry);
+  } catch { /* feedback is best-effort */ }
+}
+
+module.exports = { routeLocally, logRoutingDecision };

package/src/context-budget.js

@@ -0,0 +1,77 @@
+'use strict';
+
+/**
+ * context-budget.js — per-tool context budget enforcement.
+ *
+ * Pure function. Given a string output and a token cap (positive integer),
+ * returns either the input untouched or a clipped version with a one-line
+ * marker that mirrors distill()'s convention. Token estimate is the same
+ * char/4 rule used throughout the project (see boundary.js, analyzer.js).
+ *
+ * Returns:
+ *   { content: string, clipped: boolean,
+ *     raw_tokens: number, kept_tokens: number, prevented_tokens: number }
+ *
+ * The caller (interceptor.runOneRound) applies this AFTER any existing
+ * transform/distill so context-budget is the final clip before the tool
+ * result re-enters the model's next request.
+ */
+
+const CHARS_PER_TOKEN = 4;
+
+function estTokens(s) {
+  if (typeof s !== 'string' || !s) return 0;
+  return Math.ceil(Buffer.byteLength(s, 'utf8') / CHARS_PER_TOKEN);
+}
+
+function enforceContextBudget(output, maxTokens) {
+  if (typeof output !== 'string' || !output) {
+    return {
+      content: output || '',
+      clipped: false,
+      raw_tokens: 0,
+      kept_tokens: 0,
+      prevented_tokens: 0,
+    };
+  }
+  // No cap or invalid cap → pass through. Caller is responsible for validating
+  // the policy value, but be defensive: never fall closed on a bad config.
+  if (typeof maxTokens !== 'number' || !Number.isFinite(maxTokens) || maxTokens <= 0) {
+    const tok = estTokens(output);
+    return {
+      content: output, clipped: false,
+      raw_tokens: tok, kept_tokens: tok, prevented_tokens: 0,
+    };
+  }
+  const rawTokens = estTokens(output);
+  if (rawTokens <= maxTokens) {
+    return {
+      content: output, clipped: false,
+      raw_tokens: rawTokens, kept_tokens: rawTokens, prevented_tokens: 0,
+    };
+  }
+  // Cut by chars (≈ tokens × 4), preserving valid UTF-8 by using slice on the
+  // string (JS strings are UTF-16, but the char/4 estimate is an estimate —
+  // we don't claim exactness, only approximation marked with '~').
+  const charBudget = maxTokens * CHARS_PER_TOKEN;
+  const cut = output.slice(0, charBudget);
+  const cutTokens = estTokens(cut);
+  // "Prevented" is the count of ORIGINAL tool-output tokens that did not
+  // make it into the model's next request. The informational marker added
+  // below counts toward kept_tokens (it is in the prompt) but must not
+  // shrink prevented_tokens — the bytes that came from the tool itself are
+  // gone whether the marker is appended or not.
+  const preventedTokens = Math.max(0, rawTokens - cutTokens);
+  const clipped = cut +
+    `\n\n[Occasio: ~${preventedTokens}t cut by context_budget (max ${maxTokens}t). Full output not re-sent to model.]`;
+  const keptTokens = estTokens(clipped);
+  return {
+    content: clipped,
+    clipped: true,
+    raw_tokens: rawTokens,
+    kept_tokens: keptTokens,
+    prevented_tokens: preventedTokens,
+  };
+}
+
+module.exports = { enforceContextBudget, estTokens };

package/src/core/boundary-event.js

@@ -0,0 +1,75 @@
+'use strict';
+
+/**
+ * BoundaryEvent — the canonical record of one cross-boundary interaction
+ * between an AI agent and the user's machine.
+ *
+ * Every cross-boundary event in the system flows through this shape.
+ * Adapters produce them; policy evaluates them; executors act on them;
+ * auditors record them; observability reads them.
+ *
+ * Stage 1: the shape is minimal. Speculative fields are deliberately omitted.
+ * Add fields only when there is live evidence that a downstream layer needs them.
+ *
+ * Hard rule for the `raw` field: only the adapter touches it. The pipeline
+ * never introspects it. If a downstream layer needs a value out of `raw`,
+ * the adapter must promote it to a normalized field first.
+ */
+
+const { randomUUID } = require('crypto');
+
+/**
+ * Build a BoundaryEvent. All optional fields default to undefined.
+ *
+ * @param {object} input
+ * @param {'outbound'|'inbound'} input.direction
+ * @param {'request'|'tool_call'|'tool_result'|'response'} input.kind
+ * @param {string} input.agent           Stable agent identity, e.g. 'claude-code'
+ * @param {string} input.protocol        Stable protocol identity, e.g. 'anthropic-http'
+ * @param {string} [input.sessionId]
+ * @param {string} [input.runId]
+ * @param {string} [input.toolName]      Canonical tool name (mapped by adapter)
+ * @param {object} [input.toolInput]     Canonical input shape
+ * @param {object|string} [input.toolResult]
+ * @param {object|string} [input.payload]
+ * @param {unknown}  [input.raw]         Adapter-private; opaque to other layers
+ */
+function makeBoundaryEvent({
+  direction,
+  kind,
+  agent,
+  protocol,
+  sessionId,
+  runId,
+  toolName,
+  toolInput,
+  toolResult,
+  payload,
+  raw,
+}) {
+  if (!direction) throw new Error('BoundaryEvent.direction is required');
+  if (!kind)      throw new Error('BoundaryEvent.kind is required');
+  if (!agent)     throw new Error('BoundaryEvent.agent is required');
+  if (!protocol)  throw new Error('BoundaryEvent.protocol is required');
+
+  return {
+    id:        randomUUID(),
+    timestamp: new Date().toISOString(),
+    sessionId,
+    runId,
+    agent,
+    protocol,
+    direction,
+    kind,
+    toolName,
+    toolInput,
+    toolResult,
+    payload,
+    raw,
+  };
+}
+
+const KINDS      = ['request', 'tool_call', 'tool_result', 'response'];
+const DIRECTIONS = ['outbound', 'inbound'];
+
+module.exports = { makeBoundaryEvent, KINDS, DIRECTIONS };

package/src/core/decision.js

@@ -0,0 +1,61 @@
+'use strict';
+
+/**
+ * Decision — the result of evaluating policy against a BoundaryEvent.
+ *
+ * The policy engine produces a Decision; the dispatcher acts on it.
+ * Decisions are pure data: no functions, no closures. They can be logged
+ * and replayed.
+ *
+ * Stage 1: minimal shape. `policySource` is always 'default' until Stage 2
+ * introduces user-authored YAML rules.
+ */
+
+const ACTIONS = ['PASS', 'LOCAL', 'TRANSFORM', 'BLOCK'];
+
+/**
+ * Build a Decision.
+ *
+ * @param {object} input
+ * @param {'PASS'|'LOCAL'|'TRANSFORM'|'BLOCK'} input.action
+ * @param {string} input.reason          Stable code, e.g. 'native-handleable'
+ * @param {string} [input.policySource]  'default' in Stage 1
+ * @param {string} [input.executor]      Required when action === 'LOCAL'
+ * @param {string} [input.transform]     Required when action === 'TRANSFORM'
+ * @param {object} [input.syntheticResponse]  Required when action === 'BLOCK'
+ */
+function makeDecision({ action, reason, policySource = 'default', executor, transform, syntheticResponse }) {
+  if (!ACTIONS.includes(action)) {
+    throw new Error(`Decision.action must be one of ${ACTIONS.join('/')} — got ${action}`);
+  }
+  if (!reason) throw new Error('Decision.reason is required');
+  if (action === 'LOCAL'     && !executor)          throw new Error('Decision.executor is required for LOCAL');
+  if (action === 'TRANSFORM' && !transform)         throw new Error('Decision.transform is required for TRANSFORM');
+  if (action === 'BLOCK'     && !syntheticResponse) throw new Error('Decision.syntheticResponse is required for BLOCK');
+  return { action, reason, policySource, executor, transform, syntheticResponse };
+}
+
+// Convenience constructors for the common cases.
+const PASS      = (reason, policySource)              => makeDecision({ action: 'PASS',      reason, policySource });
+const LOCAL     = (executor, reason, policySource)    => makeDecision({ action: 'LOCAL',     reason, policySource, executor });
+const TRANSFORM = (transform, reason, policySource)   => makeDecision({ action: 'TRANSFORM', reason, policySource, transform });
+const BLOCK     = (syntheticResponse, reason, policySource) =>
+  makeDecision({ action: 'BLOCK', reason, policySource, syntheticResponse });
+
+/**
+ * Build a chained TRANSFORM decision that applies multiple named transforms
+ * in sequence. `transforms` must be an ordered array of ≥ 2 names.
+ *
+ * The `transform` field on the decision is set to `transforms.join('+')` so
+ * audit consumers that only read the scalar field see a stable, readable name.
+ * The dispatcher reads `decision.transforms` (array) to execute the chain.
+ */
+const TRANSFORM_CHAIN = (transforms, reason, policySource) => {
+  if (!Array.isArray(transforms) || transforms.length < 2) {
+    throw new Error('TRANSFORM_CHAIN requires an array of at least 2 transforms');
+  }
+  const d = makeDecision({ action: 'TRANSFORM', reason: reason || 'chain', policySource, transform: transforms.join('+') });
+  return Object.freeze({ ...d, transforms });
+};
+
+module.exports = { makeDecision, PASS, LOCAL, TRANSFORM, TRANSFORM_CHAIN, BLOCK, ACTIONS };

package/src/core/pipeline.js

@@ -0,0 +1,66 @@
+'use strict';
+
+/**
+ * Pipeline — the canonical orchestration for a single boundary event.
+ *
+ *     adapter (in caller)  →  policy.evaluate  →  dispatcher.dispatch  →  auditor.record
+ *
+ * The pipeline does not own state. It is a pure orchestration function:
+ * given an event, the layers, and any per-call context, it returns a Result.
+ *
+ * Stage 1: this function exists and has clean contracts, but the index.js
+ * request handler does not yet call it. Stage 2 migrates the request path
+ * onto the pipeline; for now it is exercised by tests and `processToolEvent`
+ * provides a wired end-to-end demonstration with the default layers.
+ */
+
+/**
+ * Run one BoundaryEvent through the pipeline with caller-provided layers.
+ *
+ * @param {object} args
+ * @param {object} args.event       BoundaryEvent
+ * @param {object} args.policy      { evaluate(event) → Decision }
+ * @param {object} args.dispatcher  { dispatch(event, decision, ctx) → Result }
+ * @param {object} [args.auditor]   { record(event, decision, result) }
+ * @param {object} [args.ctx]       Per-call context forwarded to dispatcher
+ * @returns {object} { event, decision, result }
+ */
+async function process({ event, policy, dispatcher, auditor, ctx }) {
+  const decision = policy.evaluate(event);
+  const result   = await dispatcher.dispatch(event, decision, ctx);
+  if (auditor && typeof auditor.record === 'function') {
+    // v0.6.4: auditor.record now returns { ok, error, droppedRow }. A failed
+    // append is session-fatal — propagate as AuditWriteError so the proxy
+    // can abort before the cloud call completes. A missing audit row must
+    // not coexist with a successful tool dispatch.
+    const status = auditor.record(event, decision, result);
+    if (status && status.ok === false) {
+      const { AuditWriteError } = require('../audit/errors');
+      throw new AuditWriteError(status.error, status.droppedRow);
+    }
+  }
+  return { event, decision, result };
+}
+
+/**
+ * Convenience: run one BoundaryEvent through the default Stage 1 layers
+ * (policy.engine, executor.dispatcher, optional auditor). This is the wired
+ * demonstration of the architecture; index.js does not yet call it for the
+ * proxy's request flow — Stage 2 owns that migration.
+ *
+ * @param {object} event   BoundaryEvent
+ * @param {object} [opts]  { auditor, ctx }
+ */
+async function processToolEvent(event, opts = {}) {
+  const policy     = require('../policy/engine');
+  const dispatcher = require('../executor/dispatcher');
+  return process({
+    event,
+    policy,
+    dispatcher,
+    auditor: opts.auditor,
+    ctx:     opts.ctx,
+  });
+}
+
+module.exports = { process, processToolEvent };