@claude-flow/cli 3.32.3 → 3.32.5

package/dist/src/business-pods/bbs-budget-tracker.js

@@ -0,0 +1,358 @@
+/**
+ * BbsRoomBudgetTracker — Atomic reserve / commit / release token-bucket
+ * backed by better-sqlite3 (ADR-164.1 §3-§5).
+ *
+ * Closes the read-then-write race in ADR-164's first-draft tracker by routing
+ * every state transition through a single `BEGIN IMMEDIATE` transaction that
+ * acquires the SQLite write lock atomically with the gate check. The
+ * `_lock_bump` column write is a belt-and-suspenders explicit write inside
+ * the transaction so the lock acquisition is visible to code review and
+ * query-log analysis (§3.2 peer-review clarification).
+ *
+ * Architectural constraints (ADR-164.1):
+ *   - Default OFF: this module is opt-in behind `CLAUDE_FLOW_BBS_ATOMIC_BUDGET=1`.
+ *     The pod-tick.mjs file-based stub remains the default until the flag is
+ *     flipped per ADR-164.1 §12.4.
+ *   - `committed_post_expiry` state machine implemented per §5.3 — late
+ *     commits on expired reservations ARE accepted (the API spend already
+ *     happened), transition to `committed_post_expiry`, charge the budget,
+ *     and return `warned: 'COMMIT_AFTER_EXPIRY'`. This closes the §8.1
+ *     Expired Commit Leak surfaced by peer review on 2026-06-29.
+ *   - `expires_at` is clamped to [5_000, 300_000] ms (§3.2).
+ *   - WAL + synchronous=NORMAL + busy_timeout=500 for write throughput.
+ *
+ * The sweeper interval (`sweepExpired()`) is exposed as a manual method;
+ * callers are expected to drive it on a setInterval — that integration lives
+ * at the call site, not in this file, per ADR-164.1 §7.1.
+ *
+ * @module @claude-flow/cli/business-pods/bbs-budget-tracker
+ */
+import { randomUUID } from 'node:crypto';
+// ---------- expiry-window clamp -------------------------------------------
+export const RESERVATION_EXPIRY_FLOOR_MS = 5_000;
+export const RESERVATION_EXPIRY_CEILING_MS = 300_000;
+export const RESERVATION_EXPIRY_DEFAULT_MS = 60_000;
+export function clampReservationExpiry(raw) {
+    if (raw === undefined || !Number.isFinite(raw)) {
+        const envVal = Number(process.env.CLAUDE_FLOW_BBS_RESERVATION_EXPIRY_MS);
+        if (Number.isFinite(envVal) && envVal > 0) {
+            return Math.max(RESERVATION_EXPIRY_FLOOR_MS, Math.min(RESERVATION_EXPIRY_CEILING_MS, envVal));
+        }
+        return RESERVATION_EXPIRY_DEFAULT_MS;
+    }
+    return Math.max(RESERVATION_EXPIRY_FLOOR_MS, Math.min(RESERVATION_EXPIRY_CEILING_MS, raw));
+}
+// ---------- schema migration ----------------------------------------------
+export const SCHEMA_SQL = `
+PRAGMA journal_mode = WAL;
+PRAGMA synchronous = NORMAL;
+PRAGMA busy_timeout = 500;
+
+CREATE TABLE IF NOT EXISTS bbs_budget_rooms (
+  room_id         TEXT NOT NULL PRIMARY KEY,
+  monthly_cap_usd REAL NOT NULL CHECK (monthly_cap_usd >= 0),
+  billing_month   TEXT NOT NULL,
+  _lock_bump      INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS bbs_budget_reservations (
+  reservation_id    TEXT NOT NULL PRIMARY KEY,
+  room_id           TEXT NOT NULL REFERENCES bbs_budget_rooms(room_id),
+  caller_node_id    TEXT NOT NULL,
+  estimated_usd     REAL NOT NULL CHECK (estimated_usd >= 0),
+  actual_usd        REAL,
+  state             TEXT NOT NULL
+                    CHECK (state IN ('reserved','committed','released','expired','committed_post_expiry')),
+  reserved_at       INTEGER NOT NULL,
+  expires_at        INTEGER NOT NULL,
+  committed_at      INTEGER,
+  audit_envelope_id TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_reservations_room_month
+  ON bbs_budget_reservations (room_id, reserved_at);
+
+CREATE INDEX IF NOT EXISTS idx_reservations_expiry
+  ON bbs_budget_reservations (state, expires_at);
+`;
+// ---------- helpers --------------------------------------------------------
+function currentBillingMonth(now) {
+    const d = new Date(now);
+    return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}`;
+}
+function billingMonthStartMs(billingMonth) {
+    const [y, m] = billingMonth.split('-').map((n) => Number(n));
+    return Date.UTC(y, (m - 1), 1, 0, 0, 0, 0);
+}
+const noopAudit = { emit: () => undefined };
+export class AtomicBbsRoomBudgetTracker {
+    db;
+    defaultExpiryMs;
+    audit;
+    clock;
+    constructor(opts) {
+        this.db = opts.db;
+        this.defaultExpiryMs = clampReservationExpiry(opts.defaultExpiryMs);
+        this.audit = opts.audit ?? noopAudit;
+        this.clock = opts.clock ?? Date.now;
+        // Ensure schema is present. exec() is a no-op for tables that already
+        // exist due to IF NOT EXISTS.
+        this.db.exec(SCHEMA_SQL);
+    }
+    /**
+     * Register (or update) a room and its monthly cap. Idempotent.
+     */
+    registerRoom(roomId, monthlyCapUsd) {
+        const billingMonth = currentBillingMonth(this.clock());
+        this.db
+            .prepare(`INSERT INTO bbs_budget_rooms (room_id, monthly_cap_usd, billing_month, _lock_bump)
+         VALUES (?, ?, ?, 0)
+         ON CONFLICT(room_id) DO UPDATE SET monthly_cap_usd = excluded.monthly_cap_usd`)
+            .run(roomId, monthlyCapUsd, billingMonth);
+    }
+    /**
+     * Atomically check budget and insert a reservation row in a single
+     * BEGIN IMMEDIATE transaction. See ADR-164.1 §5.2.
+     */
+    reserve(roomId, callerId, estimatedUsd, opts) {
+        if (!Number.isFinite(estimatedUsd) || estimatedUsd < 0) {
+            throw new Error('estimatedUsd must be a non-negative finite number');
+        }
+        const auditEnvelopeId = opts?.auditEnvelopeId ?? `audit-${randomUUID()}`;
+        const expiryMs = clampReservationExpiry(opts?.expiryMs ?? this.defaultExpiryMs);
+        const nowMs = this.clock();
+        const billingMonth = currentBillingMonth(nowMs);
+        const billingMonthStart = billingMonthStartMs(billingMonth);
+        const beginStmt = this.db.prepare('BEGIN IMMEDIATE');
+        const commitStmt = this.db.prepare('COMMIT');
+        const rollbackStmt = this.db.prepare('ROLLBACK');
+        beginStmt.run();
+        let transactionOpen = true;
+        try {
+            // Step 1: touch the room header row (the _lock_bump write makes the
+            // lock acquisition visible per §3.2 peer-review note).
+            const bumpRes = this.db
+                .prepare(`UPDATE bbs_budget_rooms
+             SET _lock_bump = _lock_bump + 1,
+                 billing_month = CASE WHEN billing_month = ? THEN billing_month ELSE ? END
+             WHERE room_id = ?`)
+                .run(billingMonth, billingMonth, roomId);
+            if (bumpRes.changes === 0) {
+                rollbackStmt.run();
+                transactionOpen = false;
+                return { ok: false, error: 'ROOM_NOT_FOUND' };
+            }
+            const roomRow = this.db
+                .prepare(`SELECT monthly_cap_usd, billing_month FROM bbs_budget_rooms WHERE room_id = ?`)
+                .get(roomId);
+            if (!roomRow) {
+                rollbackStmt.run();
+                transactionOpen = false;
+                return { ok: false, error: 'ROOM_NOT_FOUND' };
+            }
+            const monthlyCap = roomRow.monthly_cap_usd;
+            // Step 3: compute committed + live-reserved totals within this billing month.
+            const totals = this.db
+                .prepare(`SELECT
+             COALESCE(SUM(CASE WHEN state IN ('committed','committed_post_expiry') THEN actual_usd ELSE 0 END), 0) AS committed_total,
+             COALESCE(SUM(CASE WHEN state = 'reserved' AND expires_at > ? THEN estimated_usd ELSE 0 END), 0) AS reserved_total
+           FROM bbs_budget_reservations
+           WHERE room_id = ? AND reserved_at >= ?`)
+                .get(nowMs, roomId, billingMonthStart);
+            const committedTotal = totals.committed_total ?? 0;
+            const reservedTotal = totals.reserved_total ?? 0;
+            const projected = committedTotal + reservedTotal + estimatedUsd;
+            if (projected > monthlyCap + 1e-9) {
+                rollbackStmt.run();
+                transactionOpen = false;
+                this.audit.emit('reservation.budget_exceeded', {
+                    roomId, callerId, estimatedUsd, committedTotal, reservedTotal, monthlyCap,
+                });
+                return { ok: false, error: 'BUDGET_EXCEEDED' };
+            }
+            // Step 5: insert the reservation.
+            const reservationId = `res-${randomUUID()}`;
+            const expiresAt = nowMs + expiryMs;
+            this.db
+                .prepare(`INSERT INTO bbs_budget_reservations
+             (reservation_id, room_id, caller_node_id, estimated_usd, actual_usd,
+              state, reserved_at, expires_at, committed_at, audit_envelope_id)
+           VALUES (?, ?, ?, ?, NULL, 'reserved', ?, ?, NULL, ?)`)
+                .run(reservationId, roomId, callerId, estimatedUsd, nowMs, expiresAt, auditEnvelopeId);
+            commitStmt.run();
+            transactionOpen = false;
+            const remaining = monthlyCap - (committedTotal + reservedTotal + estimatedUsd);
+            this.audit.emit('reservation.reserved', {
+                reservationId, roomId, callerId, estimatedUsd, expiresAt, remaining,
+            });
+            return { ok: true, reservationId, remainingAfterReserve: remaining };
+        }
+        catch (err) {
+            if (transactionOpen) {
+                try {
+                    rollbackStmt.run();
+                }
+                catch { /* already-rolled */ }
+            }
+            throw err;
+        }
+    }
+    /**
+     * Commit the reservation with the actual cost. Late commits (expired
+     * before commit landed) ARE accepted, transitioned to
+     * 'committed_post_expiry', charged to the budget, and surfaced via
+     * `warned: 'COMMIT_AFTER_EXPIRY'` plus a `reservation.committed_post_expiry`
+     * audit emit. See ADR-164.1 §5.3 + §8.1.
+     */
+    commit(reservationId, actualUsd) {
+        if (!Number.isFinite(actualUsd) || actualUsd < 0) {
+            throw new Error('actualUsd must be a non-negative finite number');
+        }
+        const nowMs = this.clock();
+        const beginStmt = this.db.prepare('BEGIN IMMEDIATE');
+        const commitStmt = this.db.prepare('COMMIT');
+        const rollbackStmt = this.db.prepare('ROLLBACK');
+        beginStmt.run();
+        let transactionOpen = true;
+        try {
+            const row = this.db
+                .prepare(`SELECT state, room_id, estimated_usd, reserved_at, expires_at
+             FROM bbs_budget_reservations
+             WHERE reservation_id = ?`)
+                .get(reservationId);
+            if (!row) {
+                rollbackStmt.run();
+                transactionOpen = false;
+                return { ok: false, error: 'NOT_FOUND' };
+            }
+            if (row.state === 'committed' || row.state === 'committed_post_expiry' ||
+                row.state === 'released' || row.state === 'expired') {
+                rollbackStmt.run();
+                transactionOpen = false;
+                return { ok: false, error: 'ALREADY_FINALIZED' };
+            }
+            // state is 'reserved' here. Decide committed vs committed_post_expiry.
+            const lateCommit = row.expires_at <= nowMs;
+            const newState = lateCommit ? 'committed_post_expiry' : 'committed';
+            this.db
+                .prepare(`UPDATE bbs_budget_reservations
+             SET state = ?, actual_usd = ?, committed_at = ?
+             WHERE reservation_id = ?`)
+                .run(newState, actualUsd, nowMs, reservationId);
+            // Re-compute remaining for the return value.
+            const billingMonth = currentBillingMonth(nowMs);
+            const billingMonthStart = billingMonthStartMs(billingMonth);
+            const totals = this.db
+                .prepare(`SELECT
+             COALESCE(SUM(CASE WHEN state IN ('committed','committed_post_expiry') THEN actual_usd ELSE 0 END), 0) AS committed_total,
+             COALESCE(SUM(CASE WHEN state = 'reserved' AND expires_at > ? THEN estimated_usd ELSE 0 END), 0) AS reserved_total
+           FROM bbs_budget_reservations
+           WHERE room_id = ? AND reserved_at >= ?`)
+                .get(nowMs, row.room_id, billingMonthStart);
+            const roomRow = this.db
+                .prepare(`SELECT monthly_cap_usd FROM bbs_budget_rooms WHERE room_id = ?`)
+                .get(row.room_id);
+            const monthlyCap = roomRow?.monthly_cap_usd ?? 0;
+            const finalRemaining = monthlyCap - ((totals.committed_total ?? 0) + (totals.reserved_total ?? 0));
+            commitStmt.run();
+            transactionOpen = false;
+            if (lateCommit) {
+                // Emit the high-priority audit envelope per §8.1.
+                this.audit.emit('reservation.committed_post_expiry', {
+                    reservationId, roomId: row.room_id, actualUsd, finalRemaining,
+                    reservedAt: row.reserved_at, expiresAt: row.expires_at, committedAt: nowMs,
+                });
+                return { ok: true, warned: 'COMMIT_AFTER_EXPIRY', finalRemaining };
+            }
+            this.audit.emit('reservation.committed', {
+                reservationId, roomId: row.room_id, actualUsd, finalRemaining,
+            });
+            return { ok: true, committed: true, finalRemaining };
+        }
+        catch (err) {
+            if (transactionOpen) {
+                try {
+                    rollbackStmt.run();
+                }
+                catch { /* already-rolled */ }
+            }
+            throw err;
+        }
+    }
+    /**
+     * Release a reservation (caller decided not to proceed). State must be
+     * 'reserved'; any other state is ALREADY_FINALIZED.
+     */
+    release(reservationId) {
+        const beginStmt = this.db.prepare('BEGIN IMMEDIATE');
+        const commitStmt = this.db.prepare('COMMIT');
+        const rollbackStmt = this.db.prepare('ROLLBACK');
+        beginStmt.run();
+        let transactionOpen = true;
+        try {
+            const row = this.db
+                .prepare(`SELECT state, room_id FROM bbs_budget_reservations WHERE reservation_id = ?`)
+                .get(reservationId);
+            if (!row) {
+                rollbackStmt.run();
+                transactionOpen = false;
+                return { ok: false, error: 'NOT_FOUND' };
+            }
+            if (row.state !== 'reserved') {
+                rollbackStmt.run();
+                transactionOpen = false;
+                return { ok: false, error: 'ALREADY_FINALIZED' };
+            }
+            this.db
+                .prepare(`UPDATE bbs_budget_reservations SET state = 'released' WHERE reservation_id = ?`)
+                .run(reservationId);
+            commitStmt.run();
+            transactionOpen = false;
+            this.audit.emit('reservation.released', { reservationId, roomId: row.room_id });
+            return { ok: true, released: true };
+        }
+        catch (err) {
+            if (transactionOpen) {
+                try {
+                    rollbackStmt.run();
+                }
+                catch { /* already-rolled */ }
+            }
+            throw err;
+        }
+    }
+    /**
+     * Sweep expired reservations: transition 'reserved' rows whose expiry has
+     * passed to 'expired'. Callers should drive this on a setInterval per
+     * ADR-164.1 §7.1 (default cadence 5s; this method does NOT install the
+     * timer — that's the integration site's responsibility).
+     * Returns the number of rows updated.
+     */
+    sweepExpired() {
+        const result = this.db
+            .prepare(`UPDATE bbs_budget_reservations
+           SET state = 'expired'
+           WHERE state = 'reserved' AND expires_at < ?`)
+            .run(this.clock());
+        return result.changes;
+    }
+    /**
+     * Diagnostic read: list reservations for a room. Not on the hot path.
+     */
+    listReservations(roomId) {
+        return this.db
+            .prepare(`SELECT * FROM bbs_budget_reservations WHERE room_id = ? ORDER BY reserved_at`)
+            .all(roomId);
+    }
+}
+/**
+ * Feature-flagged factory per ADR-164.1 §12.3. Returns an atomic tracker
+ * when `CLAUDE_FLOW_BBS_ATOMIC_BUDGET=1`, otherwise returns null so the
+ * caller can keep using the file-based stub in pod-tick.mjs.
+ */
+export function createAtomicTrackerIfEnabled(opts) {
+    if (process.env.CLAUDE_FLOW_BBS_ATOMIC_BUDGET !== '1')
+        return null;
+    return new AtomicBbsRoomBudgetTracker(opts);
+}
+//# sourceMappingURL=bbs-budget-tracker.js.map

package/dist/src/business-pods/domain-affinity-policy.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Domain-affinity routing policy — ADR-164 §3.4.
+ *
+ * Surfaces a deterministic routing decision for `@metaharness/router` to use
+ * before its KRR cost-optimal step. The policy is intentionally tiny —
+ * three branches over `preferLocalExecution` and `budgetUsdMonthly` — so the
+ * decision is auditable from the pod template alone, no learned-weight side
+ * effects.
+ *
+ * Rules (per the Phase-3 brief):
+ *   1. `preferLocalExecution === true`                                  → 'local-stdio'
+ *   2. `preferLocalExecution === false` AND `budgetUsdMonthly >= 50`    → 'cloud-managed'
+ *   3. otherwise                                                        → 'remote-peer'
+ *
+ * The boundary `>= 50` matches the Phase-2 sales template (budget 50/month) —
+ * it routes the canonical reference pod to the cloud-managed backend. Pods
+ * below the threshold default to the federation peer-node backend.
+ *
+ * Wire point: `@metaharness/router` reads the result and supplies it as a
+ * routing hint *before* its KRR step. The router is free to override on
+ * latency/cost grounds — domain affinity is a policy floor, not a hard gate.
+ *
+ * @module @claude-flow/cli/business-pods/domain-affinity-policy
+ */
+import type { PodTemplate } from './pod-schema.js';
+/** Three backends @metaharness/router can target for a pod tick. */
+export type AgentBackend = 'local-stdio' | 'remote-peer' | 'cloud-managed';
+/** Threshold for `cloud-managed` routing. Pods at or above this monthly
+ *  spend default to cloud-managed when they are *not* local-pinned. */
+export declare const CLOUD_BUDGET_THRESHOLD_USD = 50;
+/** Structured routing decision. `reason` is rendered into the routing
+ *  rationale via `hooks_explain` so operators can see why each pod was
+ *  routed where it was. */
+export interface BackendDecision {
+    backend: AgentBackend;
+    reason: string;
+}
+/**
+ * Decide which backend `@metaharness/router` should prefer for a pod tick.
+ *
+ * @param pod  A validated PodTemplate. Validation is the caller's
+ *             responsibility; this function will throw on malformed input
+ *             (specifically on missing `preferLocalExecution` or
+ *             `budgetUsdMonthly`).
+ */
+export declare function selectAgentBackend(pod: PodTemplate): BackendDecision;
+//# sourceMappingURL=domain-affinity-policy.d.ts.map

package/dist/src/business-pods/domain-affinity-policy.js

@@ -0,0 +1,65 @@
+/**
+ * Domain-affinity routing policy — ADR-164 §3.4.
+ *
+ * Surfaces a deterministic routing decision for `@metaharness/router` to use
+ * before its KRR cost-optimal step. The policy is intentionally tiny —
+ * three branches over `preferLocalExecution` and `budgetUsdMonthly` — so the
+ * decision is auditable from the pod template alone, no learned-weight side
+ * effects.
+ *
+ * Rules (per the Phase-3 brief):
+ *   1. `preferLocalExecution === true`                                  → 'local-stdio'
+ *   2. `preferLocalExecution === false` AND `budgetUsdMonthly >= 50`    → 'cloud-managed'
+ *   3. otherwise                                                        → 'remote-peer'
+ *
+ * The boundary `>= 50` matches the Phase-2 sales template (budget 50/month) —
+ * it routes the canonical reference pod to the cloud-managed backend. Pods
+ * below the threshold default to the federation peer-node backend.
+ *
+ * Wire point: `@metaharness/router` reads the result and supplies it as a
+ * routing hint *before* its KRR step. The router is free to override on
+ * latency/cost grounds — domain affinity is a policy floor, not a hard gate.
+ *
+ * @module @claude-flow/cli/business-pods/domain-affinity-policy
+ */
+/** Threshold for `cloud-managed` routing. Pods at or above this monthly
+ *  spend default to cloud-managed when they are *not* local-pinned. */
+export const CLOUD_BUDGET_THRESHOLD_USD = 50;
+/**
+ * Decide which backend `@metaharness/router` should prefer for a pod tick.
+ *
+ * @param pod  A validated PodTemplate. Validation is the caller's
+ *             responsibility; this function will throw on malformed input
+ *             (specifically on missing `preferLocalExecution` or
+ *             `budgetUsdMonthly`).
+ */
+export function selectAgentBackend(pod) {
+    if (pod === null || typeof pod !== 'object') {
+        throw new TypeError('selectAgentBackend: pod must be a validated PodTemplate object');
+    }
+    if (typeof pod.preferLocalExecution !== 'boolean') {
+        throw new TypeError('selectAgentBackend: pod.preferLocalExecution must be boolean (validate via pod-schema first)');
+    }
+    if (typeof pod.budgetUsdMonthly !== 'number' || !Number.isFinite(pod.budgetUsdMonthly)) {
+        throw new TypeError('selectAgentBackend: pod.budgetUsdMonthly must be a finite number (validate via pod-schema first)');
+    }
+    if (pod.preferLocalExecution) {
+        return {
+            backend: 'local-stdio',
+            reason: `pod "${pod.name}" preferLocalExecution=true — domain-affinity policy pins to local stdio`,
+        };
+    }
+    if (pod.budgetUsdMonthly >= CLOUD_BUDGET_THRESHOLD_USD) {
+        return {
+            backend: 'cloud-managed',
+            reason: `pod "${pod.name}" preferLocalExecution=false and budgetUsdMonthly=${pod.budgetUsdMonthly} ` +
+                `>= ${CLOUD_BUDGET_THRESHOLD_USD} — routes to cloud Managed Agents`,
+        };
+    }
+    return {
+        backend: 'remote-peer',
+        reason: `pod "${pod.name}" preferLocalExecution=false and budgetUsdMonthly=${pod.budgetUsdMonthly} ` +
+            `< ${CLOUD_BUDGET_THRESHOLD_USD} — routes to federation peer node`,
+    };
+}
+//# sourceMappingURL=domain-affinity-policy.js.map

package/dist/src/business-pods/pod-schema.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Pod template schema validator (ADR-164 §3.3 + ADR-164.1 §3.2).
+ *
+ * Defines the `PodTemplate` type that every business-pod JSON file under
+ * `plugins/ruflo-business-pods/templates/` MUST conform to, and a hand-rolled
+ * validator that throws structured errors on invalid templates. No external
+ * deps (no AJV, no zod) — the schema is small enough to validate by hand and
+ * doing so keeps the cli's optional-dep surface unchanged.
+ *
+ * @module @claude-flow/cli/business-pods/pod-schema
+ */
+export type PiiPolicy = 'soc2' | 'gdpr' | 'hipaa' | 'permissive';
+export interface PodAgent {
+    /** Role label inside the pod, e.g. "lead-gen-agent". */
+    role: string;
+    /** Must resolve to a known ruflo agent type (researcher / coder / ...). */
+    agentType: string;
+    /** Human-readable description of what the agent does in this pod. */
+    description: string;
+    /** Routing hint — true = prefer local stdio execution. */
+    preferLocal: boolean;
+}
+export interface PodBench {
+    /** Bench identifier, e.g. "sales-pipeline-bench". */
+    name: string;
+    /** What the bench measures. */
+    description: string;
+    /** Acceptance criteria — non-empty list of human-readable bullets. */
+    successCriteria: string[];
+    /** Cadence between bench evaluations (hours, ≥1). */
+    scheduleHours: number;
+}
+export interface PodAuditReadView {
+    /** Event types surfaced to the business-owner read view. */
+    includedEventTypes: string[];
+    /** Retention window for the read view (days, ≥1). */
+    retentionDays: number;
+}
+export interface PodTemplate {
+    /** Canonical pod name (matches BBS roomId). */
+    name: string;
+    /** Display name for the cockpit. */
+    displayName: string;
+    /** BBS room this pod serves, e.g. "sales". */
+    roomId: string;
+    /** Ordered list of pod agent compositions. */
+    agents: PodAgent[];
+    /** Allow-list of MCP tools the pod's agents may invoke. */
+    allowedMcpTools: string[];
+    /** Bench definition for periodic Darwin /loop scoring. */
+    bench: PodBench;
+    /** PII compliance mode applied to every envelope in/out of this room. */
+    piiPolicy: PiiPolicy;
+    /** Monthly USD hard cap (0 = unlimited; not recommended). */
+    budgetUsdMonthly: number;
+    /** Estimated USD per pod tick — drives reservation amount. */
+    budgetUsdPerRun: number;
+    /** If true, @metaharness/router routes to local first. */
+    preferLocalExecution: boolean;
+    /** POSIX cron expression for the perpetual /loop scheduler. */
+    cronSchedule: string;
+    /** Compliance audit-log projection. */
+    auditReadView: PodAuditReadView;
+    /**
+     * Reservation expiry for the atomic budget tracker — ADR-164.1 §3.2.
+     * Bounded to [5000, 300000] ms (5 s – 5 min). Default 60_000 if omitted.
+     */
+    reservationExpiryMs?: number;
+}
+/**
+ * Structured validation error — carries the JSON pointer that caused it so
+ * callers can render a precise message.
+ */
+export declare class PodTemplateValidationError extends Error {
+    path: string;
+    constructor(message: string, path: string);
+}
+/**
+ * Validate `json` and return a typed `PodTemplate`. Throws
+ * `PodTemplateValidationError` with a JSON-pointer-style path on failure.
+ *
+ * Used by:
+ *   - `business_pod_validate` MCP tool — returns the error verbatim
+ *   - `pod-tick.mjs` — pre-flight check before any pod execution
+ *   - any external schema-loader that wants typed templates
+ */
+export declare function validatePodTemplate(json: unknown): PodTemplate;
+/**
+ * Known ruflo agent types — kept in sync with src/commands/agent.ts AGENT_TYPES.
+ * The list is duplicated here intentionally so pod-tick.mjs can run without
+ * importing the entire commands module.
+ *
+ * If a new agent type is added to AGENT_TYPES, mirror it here.
+ */
+export declare const KNOWN_AGENT_TYPES: readonly ["coder", "researcher", "tester", "reviewer", "architect", "system-architect", "coordinator", "analyst", "optimizer", "security-architect", "security-auditor", "memory-specialist", "swarm-specialist", "performance-engineer", "core-architect", "test-architect", "planner", "task-orchestrator", "perf-analyzer", "backend-dev", "api-docs", "cicd-engineer", "code-analyzer", "database-specialist", "base-template-generator"];
+//# sourceMappingURL=pod-schema.d.ts.map