@geraldmaron/construct 1.4.2 → 1.5.0

package/lib/packs/manifest-schema.mjs

@@ -0,0 +1,58 @@
+/**
+ * lib/packs/manifest-schema.mjs — canonical pack manifest schema descriptor.
+ *
+ * Defines the vocabulary for pack manifests as per ADR-0055 (A5 pack schema).
+ * A plain JS descriptor, not JSON Schema — the validator in validate.mjs
+ * consumes it directly. The schema is intentionally additive: new optional
+ * fields may be added in a minor version bump; new required fields are
+ * breaking and require a PACK_COMPAT_VERSION increment.
+ *
+ * `embedBindings` (LMCP-E4) is one such additive field: per-specialist
+ * provider read/search grants and external-write proposal grants, closing
+ * the excessive-agency gap where an embedded specialist could read any
+ * provider and propose any write with no declared authorization.
+ */
+
+export const PACK_REQUIRED_FIELDS = ['id', 'version', 'compatVersion'];
+
+export const PACK_OPTIONAL_FIELDS = [
+  'teams', 'specialists', 'prompts', 'frameworks', 'perspectives',
+  'modelTierHints', 'toolGrantsRequested', 'workflowContributions',
+  'handoffContracts', 'outputContracts', 'gates', 'tests', 'docs',
+  'installConditions', 'enableConditions', 'deprecation', 'embedBindings',
+];
+
+export const PACK_COMPAT_VERSION = 1;
+export const PACK_ID_RE = /^[a-z0-9\-./@]+$/;
+export const PACK_SOURCE_TIERS = ['builtin', 'user', 'project'];
+
+/**
+ * embedBindings shape (LMCP-E4) — per-specialist read/propose grant.
+ *
+ * `embedBindings` is a pack-level map keyed by specialist id:
+ *
+ *   {
+ *     "<specialistId>": {
+ *       "providers": [
+ *         { "id": "<extension-manifest-id>", "capabilities": ["read"], "filters": { ... ADR-0060 filter block ... } }
+ *       ],
+ *       "proposals": ["jira.createIssue"]
+ *     }
+ *   }
+ *
+ * `providers[].capabilities` values must be drawn from EMBED_BINDING_CAPABILITIES
+ * and must each be declared by the referenced extension manifest's own
+ * `capabilities` array — the binding cannot grant a capability the provider
+ * itself never advertises. `providers[].filters` reuses the ADR-0060 provider
+ * filter block verbatim (scope/predicates/nativeQuery); it is optional and,
+ * when present, validated with the same rules poll-time filters use.
+ * `proposals` is a flat list of `<providerId>.<writeKind>` tokens the
+ * specialist may propose (never execute autonomously — see authority-guard.mjs).
+ */
+export const EMBED_BINDING_CAPABILITIES = ['read', 'search'];
+
+export const EMBED_BINDING_FIELDS = ['providers', 'proposals'];
+
+export const EMBED_BINDING_PROVIDER_FIELDS = ['id', 'capabilities', 'filters'];
+
+export const EMBED_BINDING_PROPOSAL_RE = /^[a-z0-9-]+\.[a-zA-Z0-9]+$/;

package/lib/packs/prompts.mjs

@@ -0,0 +1,120 @@
+/**
+ * lib/packs/prompts.mjs — pack prompt-file validation and registry resolution.
+ *
+ * A pack manifest's `prompts` map declares `{ specialistId: relativePath }`,
+ * relative to that pack's own directory (`_packDir`, set by
+ * lib/packs/loader.mjs for every manifest-loaded pack) — a project pack's
+ * prompt paths are relative to the project, not to the Construct install.
+ * The core pack (lib/packs/core-pack.mjs) has no `_packDir`; its prompts map
+ * uses paths relative to `packageRoot` (the Construct install), the fallback
+ * root used whenever a pack carries no `_packDir` of its own.
+ *
+ * validatePackPrompts() confirms every declared file exists AND carries
+ * parseable YAML frontmatter with a `role` field — the two things worker.mjs
+ * needs before it can trust a persona prompt. In team/enterprise deployment
+ * mode a miss is a hard load-time error (the pack is rejected, naming the
+ * missing file) per LMCP-E2: a governed pack must never let a specialist run
+ * under the wrong persona.
+ *
+ * resolvePersonaPrompt() is the ONLY path worker.mjs uses to read a persona
+ * body: a walk of the pack list in the order given (the caller sorts by tier
+ * precedence — project before user before builtin, per ADR-0055), returning
+ * the first pack that declares the role, or `{ found: false }` when no pack
+ * in the registry declares it. No fallback to reading specialists/prompts/
+ * directly exists — that would defeat the pack boundary the registry is
+ * meant to enforce.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import yaml from 'js-yaml';
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
+
+function parseFrontmatter(content) {
+  const match = content.match(FRONTMATTER_RE);
+  if (!match) return null;
+  try {
+    return yaml.load(match[1]) || {};
+  } catch {
+    return null;
+  }
+}
+
+function packPromptRoot(pack, fallbackRoot) {
+  return pack?._packDir || fallbackRoot;
+}
+
+/**
+ * Validate every prompt file a pack declares.
+ *
+ * @param {object} pack        a manifest object carrying `prompts: {id: relPath}`
+ * @param {object} opts
+ * @param {string} opts.packageRoot   fallback root for packs with no `_packDir` (e.g. the core pack)
+ * @returns {{valid: boolean, errors: string[]}}
+ */
+export function validatePackPrompts(pack, { packageRoot } = {}) {
+  const errors = [];
+  const prompts = pack?.prompts || {};
+  const root = packPromptRoot(pack, packageRoot);
+
+  for (const [specId, relPath] of Object.entries(prompts)) {
+    if (typeof relPath !== 'string' || !relPath) {
+      errors.push(`pack '${pack.id}': prompt entry for '${specId}' has no file path`);
+      continue;
+    }
+    const absPath = join(root, relPath);
+    if (!existsSync(absPath)) {
+      errors.push(`pack '${pack.id}': declared prompt file missing for '${specId}': ${relPath}`);
+      continue;
+    }
+    let raw;
+    try {
+      raw = readFileSync(absPath, 'utf8');
+    } catch (err) {
+      errors.push(`pack '${pack.id}': declared prompt file unreadable for '${specId}': ${relPath} (${err.message})`);
+      continue;
+    }
+    const fm = parseFrontmatter(raw);
+    if (!fm) {
+      errors.push(`pack '${pack.id}': prompt file missing or invalid frontmatter for '${specId}': ${relPath}`);
+      continue;
+    }
+    if (!fm.role || typeof fm.role !== 'string') {
+      errors.push(`pack '${pack.id}': prompt frontmatter missing 'role' for '${specId}': ${relPath}`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Resolve one specialist's persona prompt through the pack registry only.
+ *
+ * Packs are tried in the order given (the caller sorts by tier precedence;
+ * see the module header) — the first pack declaring the role wins.
+ *
+ * @param {string} role         specialist id, e.g. 'cx-engineer' (accepts 'engineer' too)
+ * @param {object} opts
+ * @param {object[]} opts.packs      pack list, tier-precedence ordered (see loadAllPacks)
+ * @param {string} opts.packageRoot  fallback root for packs with no `_packDir` (e.g. the core pack)
+ * @returns {{found: true, content: string, packId: string} | {found: false}}
+ */
+export function resolvePersonaPrompt(role, { packs, packageRoot }) {
+  const slug = String(role || '').replace(/^cx-/, '');
+  const specId = `cx-${slug}`;
+
+  for (const pack of packs || []) {
+    const relPath = pack?.prompts?.[specId];
+    if (!relPath) continue;
+    const absPath = join(packPromptRoot(pack, packageRoot), relPath);
+    if (!existsSync(absPath)) continue;
+    try {
+      return { found: true, content: readFileSync(absPath, 'utf8'), packId: pack.id };
+    } catch {
+      continue;
+    }
+  }
+
+  return { found: false };
+}

package/lib/packs/validate.mjs

@@ -0,0 +1,208 @@
+/**
+ * lib/packs/validate.mjs — pack manifest validator.
+ *
+ * Validates a plain-JS pack manifest object against the canonical schema
+ * defined in manifest-schema.mjs. All errors are returned in a structured
+ * result; this function never throws. Error messages are single-line,
+ * actionable, and prefixed with the filePath (when provided).
+ *
+ * `embedBindings` validation (LMCP-E4) additionally cross-checks each bound
+ * provider id and capability against `knownProviders` — a map of provider id
+ * to its loaded extension manifest (lib/extensions/loader.mjs). A binding
+ * naming a provider id absent from that map, or granting a capability the
+ * provider's own manifest does not declare, fails validation with a path.
+ */
+
+import {
+  PACK_REQUIRED_FIELDS, PACK_OPTIONAL_FIELDS, PACK_COMPAT_VERSION,
+  EMBED_BINDING_CAPABILITIES, EMBED_BINDING_FIELDS, EMBED_BINDING_PROVIDER_FIELDS,
+  EMBED_BINDING_PROPOSAL_RE,
+} from './manifest-schema.mjs';
+import { validateFilterConfig } from '../providers/contract.mjs';
+
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:[-+].+)?$/;
+
+const PACK_ID_RE = /^[a-z0-9\-./@]+$/;
+
+/**
+ * Validate the `embedBindings` block (LMCP-E4) against known extension
+ * manifests. `knownProviders` is a map of providerId → manifest (as loaded
+ * by lib/extensions/loader.mjs); each bound provider must exist in that map
+ * and must itself declare every capability the binding grants — a pack
+ * cannot hand a specialist a read/search grant the provider never advertises.
+ * Every error names the JSON path of the offending field.
+ */
+function validateEmbedBindings(embedBindings, { prefix, knownProviders = {} }) {
+  const errors = [];
+
+  if (typeof embedBindings !== 'object' || embedBindings === null || Array.isArray(embedBindings)) {
+    return [`${prefix}embedBindings must be an object keyed by specialist id`];
+  }
+
+  for (const [specialistId, binding] of Object.entries(embedBindings)) {
+    const bindingPath = `embedBindings.${specialistId}`;
+
+    if (typeof binding !== 'object' || binding === null || Array.isArray(binding)) {
+      errors.push(`${prefix}${bindingPath} must be an object`);
+      continue;
+    }
+
+    for (const key of Object.keys(binding)) {
+      if (!EMBED_BINDING_FIELDS.includes(key)) {
+        errors.push(`${prefix}${bindingPath}.${key} is not a recognized embedBindings field (allowed: ${EMBED_BINDING_FIELDS.join(', ')})`);
+      }
+    }
+
+    const providers = binding.providers;
+    if (providers !== undefined) {
+      if (!Array.isArray(providers)) {
+        errors.push(`${prefix}${bindingPath}.providers must be an array`);
+      } else {
+        providers.forEach((entry, idx) => {
+          const entryPath = `${bindingPath}.providers[${idx}]`;
+
+          if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+            errors.push(`${prefix}${entryPath} must be an object`);
+            return;
+          }
+
+          for (const key of Object.keys(entry)) {
+            if (!EMBED_BINDING_PROVIDER_FIELDS.includes(key)) {
+              errors.push(`${prefix}${entryPath}.${key} is not a recognized provider binding field (allowed: ${EMBED_BINDING_PROVIDER_FIELDS.join(', ')})`);
+            }
+          }
+
+          const providerId = entry.id;
+          if (typeof providerId !== 'string' || providerId.length === 0) {
+            errors.push(`${prefix}${entryPath}.id must be a non-empty string`);
+            return;
+          }
+
+          const providerManifest = knownProviders[providerId];
+          if (!providerManifest) {
+            errors.push(`${prefix}${entryPath}.id references unknown provider "${providerId}" (no extension manifest declares this id)`);
+            return;
+          }
+
+          const declaredCapabilities = new Set(providerManifest.capabilities || []);
+
+          if (!Array.isArray(entry.capabilities) || entry.capabilities.length === 0) {
+            errors.push(`${prefix}${entryPath}.capabilities must be a non-empty array`);
+          } else {
+            entry.capabilities.forEach((cap, capIdx) => {
+              const capPath = `${entryPath}.capabilities[${capIdx}]`;
+              if (!EMBED_BINDING_CAPABILITIES.includes(cap)) {
+                errors.push(`${prefix}${capPath} "${cap}" is not a recognized embed capability (allowed: ${EMBED_BINDING_CAPABILITIES.join(', ')})`);
+              } else if (!declaredCapabilities.has(cap)) {
+                errors.push(`${prefix}${capPath} "${cap}" is not declared by provider "${providerId}"'s manifest capabilities (${[...declaredCapabilities].join(', ') || '(none)'})`);
+              }
+            });
+          }
+
+          if (entry.filters !== undefined) {
+            try {
+              validateFilterConfig(providerId, entry.filters);
+            } catch (err) {
+              errors.push(`${prefix}${entryPath}.filters: ${err.message}`);
+            }
+          }
+        });
+      }
+    }
+
+    const proposals = binding.proposals;
+    if (proposals !== undefined) {
+      if (!Array.isArray(proposals)) {
+        errors.push(`${prefix}${bindingPath}.proposals must be an array`);
+      } else {
+        const boundProviderIds = new Set((Array.isArray(providers) ? providers : []).map((p) => p?.id).filter(Boolean));
+        proposals.forEach((token, idx) => {
+          const tokenPath = `${bindingPath}.proposals[${idx}]`;
+          if (typeof token !== 'string' || !EMBED_BINDING_PROPOSAL_RE.test(token)) {
+            errors.push(`${prefix}${tokenPath} "${token}" must be a "<providerId>.<writeKind>" token (e.g. "jira.createIssue")`);
+            return;
+          }
+          const [providerId] = token.split('.');
+          if (!knownProviders[providerId]) {
+            errors.push(`${prefix}${tokenPath} "${token}" references unknown provider "${providerId}" (no extension manifest declares this id)`);
+          } else if (boundProviderIds.size > 0 && !boundProviderIds.has(providerId)) {
+            errors.push(`${prefix}${tokenPath} "${token}" proposes against provider "${providerId}" which is not in this specialist's providers[] grant`);
+          }
+        });
+      }
+    }
+  }
+
+  return errors;
+}
+
+export function validatePackManifest(manifest, { filePath, strict = false, knownProviders = {} } = {}) {
+  const prefix = filePath ? `${filePath}: ` : '';
+  const errors = [];
+
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    return { valid: false, errors: [`${prefix}manifest must be a JSON object`] };
+  }
+
+  for (const field of PACK_REQUIRED_FIELDS) {
+    if (!(field in manifest) || manifest[field] === undefined || manifest[field] === null) {
+      errors.push(`${prefix}missing required field: ${field}`);
+    }
+  }
+
+  if ('id' in manifest && manifest.id !== undefined && manifest.id !== null) {
+    if (typeof manifest.id !== 'string' || manifest.id.length === 0) {
+      errors.push(`${prefix}id must be a non-empty string`);
+    } else if (!PACK_ID_RE.test(manifest.id)) {
+      errors.push(`${prefix}id must match [a-z0-9-./@]+ (got '${manifest.id}')`);
+    }
+  }
+
+  if ('version' in manifest && manifest.version !== undefined && manifest.version !== null) {
+    if (typeof manifest.version !== 'string' || !SEMVER_RE.test(manifest.version)) {
+      errors.push(`${prefix}version must be a semver string`);
+    }
+  }
+
+  if (manifest.compatVersion !== undefined && manifest.compatVersion !== null) {
+    if (typeof manifest.compatVersion !== 'number' || !Number.isInteger(manifest.compatVersion)) {
+      errors.push(`${prefix}compatVersion must be an integer`);
+    } else if (manifest.compatVersion > PACK_COMPAT_VERSION) {
+      errors.push(
+        `${prefix}compatVersion ${manifest.compatVersion} exceeds supported version ${PACK_COMPAT_VERSION}; upgrade Construct to use this pack`
+      );
+    }
+  }
+
+  if (manifest.deprecation !== undefined && manifest.deprecation !== null) {
+    if (typeof manifest.deprecation !== 'object' || Array.isArray(manifest.deprecation)) {
+      errors.push(`${prefix}deprecation must be an object`);
+    } else {
+      if (!('since' in manifest.deprecation)) {
+        errors.push(`${prefix}deprecation must include 'since' field`);
+      }
+      if (!('message' in manifest.deprecation)) {
+        errors.push(`${prefix}deprecation must include 'message' field`);
+      }
+    }
+  }
+
+  if (manifest.embedBindings !== undefined && manifest.embedBindings !== null) {
+    errors.push(...validateEmbedBindings(manifest.embedBindings, { prefix, knownProviders }));
+  }
+
+  if (strict) {
+    const knownFields = new Set([...PACK_REQUIRED_FIELDS, ...PACK_OPTIONAL_FIELDS]);
+    for (const key of Object.keys(manifest)) {
+      if (key.startsWith('_')) continue;
+      if (!knownFields.has(key)) {
+        errors.push(`${prefix}unknown field '${key}' in strict mode`);
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    return { valid: false, errors };
+  }
+  return { valid: true };
+}

package/lib/plugin-registry.mjs

@@ -6,11 +6,10 @@
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, extname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { extname, join, resolve } from "node:path";
 import { configDir } from "./config/xdg.mjs";
+import { packageRoot } from "./roots.mjs";
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
 export const MANIFEST_VERSION = 1;
 
 function readJson(filePath) {
@@ -97,7 +96,7 @@ export function validatePluginManifest(manifest, { manifestPath = "<memory>" } =
 
 function loadBuiltinPlugin(rootDir) {
   const rootCatalogPath = join(rootDir, "lib", "mcp-catalog.json");
-  const catalogPath = existsSync(rootCatalogPath) ? rootCatalogPath : join(__dirname, "mcp-catalog.json");
+  const catalogPath = existsSync(rootCatalogPath) ? rootCatalogPath : join(packageRoot, "lib", "mcp-catalog.json");
   const catalog = readJson(catalogPath);
   const plugin = {
     id: "construct-builtins",
@@ -142,7 +141,7 @@ function findManifestFiles(pluginDirs) {
   return files.sort();
 }
 
-export function loadPluginRegistry({ cwd = process.cwd(), homeDir = homedir(), rootDir = resolve(__dirname, ".."), env = process.env } = {}) {
+export function loadPluginRegistry({ cwd = process.cwd(), homeDir = homedir(), rootDir = packageRoot, env = process.env } = {}) {
   const errors = [];
   const plugins = [loadBuiltinPlugin(rootDir)];
   const pluginDirs = resolvePluginDirs({ cwd, homeDir, env });

package/lib/policy/audit-gate.mjs

@@ -0,0 +1,42 @@
+/**
+ * lib/policy/audit-gate.mjs — mandatory-audit enforcement for enterprise mode (LMCP-H5).
+ *
+ * ADR-0057 (A7): enterprise mode promises every mutating action is audited.
+ * A broker/policy/write path that silently swallows an audit-sink failure
+ * (as lib/mcp/broker.mjs's best-effort catch does today) makes that promise
+ * false under exactly the condition it exists to cover. enforceMandatoryAudit
+ * is a policy-decision precondition: in enterprise mode, when the audit sink
+ * (lib/audit-trail.mjs#checkAuditSinkAvailable) is down, every action is
+ * denied before any role/manifest logic runs — fail closed, no
+ * CONSTRUCT_SKIP_* escape hatch. Solo and team modes never call the sink
+ * check and are unaffected.
+ */
+
+import { checkAuditSinkAvailable } from '../audit-trail.mjs';
+
+export const AUDIT_GATE_SOURCE = 'mandatory-audit-gate';
+
+/**
+ * Enterprise-only precondition: deny everything if the audit sink is down.
+ * Returns null (no opinion) for solo/team or when the sink is healthy, so
+ * callers can compose this before their own decision logic without changing
+ * behavior outside enterprise mode.
+ *
+ * @param {object} input
+ * @param {'solo'|'team'|'enterprise'} input.deploymentMode
+ * @param {function} [input.checkSink] - injectable for tests; defaults to the real fs probe
+ * @returns {{allowed: boolean, reason: string, approvalRequired: boolean, source: string}|null}
+ */
+export function enforceMandatoryAudit({ deploymentMode, checkSink = checkAuditSinkAvailable } = {}) {
+  if (deploymentMode !== 'enterprise') return null;
+
+  const sink = checkSink();
+  if (sink.available) return null;
+
+  return {
+    allowed: false,
+    reason: `enterprise mode requires a healthy audit sink; audit sink unavailable (${sink.reason || 'unknown-error'}) — action refused fail-closed`,
+    approvalRequired: false,
+    source: AUDIT_GATE_SOURCE,
+  };
+}

package/lib/policy/consumption-budget.mjs

@@ -0,0 +1,149 @@
+/**
+ * lib/policy/consumption-budget.mjs — durable per-actor/run consumption budgets (LMCP-N5).
+ *
+ * Nothing durably bounded token/tool-call/external-write/queue-submission
+ * consumption per actor or run before this: lib/mcp/broker.mjs's BrokerStore
+ * (LMCP-I1) covers only a fixed-window tool-call rate per actor+tool, reset
+ * on every window rather than accumulating for the life of a run. This store
+ * persists cumulative consumption per actor+run to
+ * `<rootDir>/.cx/consumption-budgets.json`, survives process restarts the
+ * same way BrokerStore does, and is consulted pre-execution so an exhausted
+ * run halts with a clear, durable budget-denied record instead of a
+ * surprise bill.
+ *
+ * Budgets default per deployment mode (lib/deployment-mode.mjs): solo is
+ * `null` (unbounded) — a single local operator should never hit a wall a
+ * team/enterprise multi-actor deployment needs; team/enterprise apply real
+ * per-kind caps. An explicit `budget` object always overrides the mode
+ * default.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { getDeploymentMode } from '../deployment-mode.mjs';
+
+const BUDGET_STORE_SUBPATH = path.join('.cx', 'consumption-budgets.json');
+
+export const CONSUMPTION_KINDS = ['tokens', 'toolCalls', 'externalWrites', 'queueSubmissions'];
+
+export const DEFAULT_BUDGETS_BY_MODE = Object.freeze({
+  solo: null,
+  team: Object.freeze({ tokens: 2_000_000, toolCalls: 2000, externalWrites: 200, queueSubmissions: 500 }),
+  enterprise: Object.freeze({ tokens: 5_000_000, toolCalls: 5000, externalWrites: 500, queueSubmissions: 1000 }),
+});
+
+export function resolveDefaultBudget(mode) {
+  // `??` treats solo's deliberate `null` (unbounded) as absent and would fall
+  // through to the team default, defeating the solo-is-unbounded default —
+  // an explicit `in` check is required so null is a real, honored value.
+  return mode in DEFAULT_BUDGETS_BY_MODE ? DEFAULT_BUDGETS_BY_MODE[mode] : DEFAULT_BUDGETS_BY_MODE.team;
+}
+
+export function budgetStorePath(rootDir) {
+  return path.join(rootDir, BUDGET_STORE_SUBPATH);
+}
+
+function emptyConsumption() {
+  return { tokens: 0, toolCalls: 0, externalWrites: 0, queueSubmissions: 0 };
+}
+
+function readStoreFile(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+export class BudgetExceeded extends Error {
+  constructor({ actor, runId, kind, cap, projected }) {
+    super(`consumption budget exceeded: actor '${actor}' run '${runId}' would reach ${projected} ${kind} against a budget of ${cap}`);
+    this.name = 'BudgetExceeded';
+    this.actor = actor;
+    this.runId = runId;
+    this.kind = kind;
+    this.cap = cap;
+    this.projected = projected;
+  }
+}
+
+/**
+ * ConsumptionBudgetStore — file-backed durable per-actor/run consumption.
+ *
+ * Read/write mirrors lib/mcp/broker.mjs's BrokerStore: in-memory `_data` is
+ * the write buffer, `save()` persists the whole map, and every disk
+ * operation is best-effort so a disk failure never breaks the caller.
+ */
+export class ConsumptionBudgetStore {
+  constructor({ rootDir, file, env = process.env } = {}) {
+    if (!rootDir && !file) throw new Error('ConsumptionBudgetStore: rootDir or file is required');
+    this.rootDir = rootDir ?? null;
+    this.env = env;
+    this._storePath = file || budgetStorePath(rootDir);
+    this._data = readStoreFile(this._storePath);
+  }
+
+  _key(actor, runId) {
+    return `${actor}::${runId}`;
+  }
+
+  _save() {
+    try {
+      fs.mkdirSync(path.dirname(this._storePath), { recursive: true });
+      fs.writeFileSync(this._storePath, JSON.stringify(this._data), 'utf8');
+    } catch { /* best-effort, mirrors BrokerStore.save */ }
+  }
+
+  /** Resolves the effective budget: an explicit override, else the deployment-mode default. */
+  resolveBudget(budgetOverride) {
+    if (budgetOverride !== undefined) return budgetOverride;
+    const mode = getDeploymentMode(this.env, { cwd: this.rootDir ?? process.cwd() });
+    return resolveDefaultBudget(mode);
+  }
+
+  /** Cumulative consumption recorded so far for actor+run, zeroed if none. */
+  consumptionFor(actor, runId) {
+    return { ...emptyConsumption(), ...(this._data[this._key(actor, runId)] || {}) };
+  }
+
+  /**
+   * check(actor, runId, kind, amount, { budget }) — would recording `amount`
+   * more of `kind` exceed the budget? Read-only, no state mutated.
+   */
+  check(actor, runId, kind, amount = 1, { budget } = {}) {
+    const resolved = this.resolveBudget(budget);
+    const consumption = this.consumptionFor(actor, runId);
+    if (!resolved) return { allowed: true, cap: null, projected: consumption[kind] + amount, consumption };
+    const cap = resolved[kind];
+    if (!Number.isFinite(cap)) return { allowed: true, cap: null, projected: consumption[kind] + amount, consumption };
+    const projected = consumption[kind] + amount;
+    return { allowed: projected <= cap, cap, projected, consumption };
+  }
+
+  /** Durably record `amount` more of `kind` for actor+run. Returns the updated row. */
+  record(actor, runId, kind, amount = 1) {
+    const key = this._key(actor, runId);
+    const current = { ...emptyConsumption(), ...(this._data[key] || {}) };
+    current[kind] = (current[kind] || 0) + amount;
+    this._data[key] = current;
+    this._save();
+    return current;
+  }
+
+  /** Every actor+run row with its resolved budget, for status surfacing. */
+  allEntries() {
+    return Object.entries(this._data).map(([key, consumption]) => {
+      const sep = key.indexOf('::');
+      const actor = sep === -1 ? key : key.slice(0, sep);
+      const runId = sep === -1 ? null : key.slice(sep + 2);
+      return {
+        actor,
+        runId,
+        consumption: { ...emptyConsumption(), ...consumption },
+        budget: this.resolveBudget(undefined),
+      };
+    });
+  }
+}