cadet-agent 0.20.2 → 0.24.0

package/src/harness/ledger.mjs

@@ -0,0 +1,309 @@
+/**
+ * Cadet-Agent execution ledger.
+ *
+ * Creates and persists sanitized run records: spans, evidence, decisions,
+ * budget accounting, and capability labels. All structured values pass through
+ * redaction before persistence, and output beyond the inline limit is written to
+ * a bounded artifact with a diagnostic preview.
+ *
+ * Contract: docs/core/HarnessContract.md §4 (accounting), §8 (privacy), §9 (retention).
+ */
+
+import {
+  mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, unlinkSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { newId, timestamp, sha256Bytes } from './util.mjs';
+import { redact, redactString, REDACTED } from './redaction.mjs';
+import { BudgetTracker, normalizeUsage, estimateCost, budgetReport } from './budget.mjs';
+import { writeJsonAtomic } from './state.mjs';
+
+export const RUN_SCHEMA_VERSION = 2;
+
+class LedgerError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'LedgerError';
+  }
+}
+
+export function runsDir(targetDir) {
+  return join(targetDir, '.cadet', 'runs');
+}
+
+/** A single run: created empty, appended to, then finalized. */
+export class RunLedger {
+  constructor({ targetDir = process.cwd(), policy, runId = null, workItemId = null, phase = null, budgets = null, capabilities = null } = {}) {
+    if (!policy) throw new LedgerError('RunLedger requires a resolved policy');
+    this.targetDir = targetDir;
+    this.policy = policy;
+    this.runId = runId || newId();
+    this.workItemId = workItemId;
+    this.phase = phase;
+    this.tracker = budgets || new BudgetTracker(policy);
+    this.capabilities = capabilities;
+    this.startedAt = timestamp();
+    this.finishedAt = null;
+    this.spans = [];
+    this.evidence = [];
+    this.decisions = [];
+    this.usage = null;
+    this.status = 'running';
+    this.retention = {
+      rawPromptRetained: false,
+      keepOnFailure: policy.retention?.keepOnFailure ?? true,
+    };
+  }
+
+  /** Append a sanitized span. Never stores secrets. */
+  addSpan(span) {
+    const safe = redact({ ...span, runId: this.runId, spanId: span.spanId || newId() });
+    this.spans.push(safe);
+    return safe;
+  }
+
+  /** Append an evidence record (already structured; redacted defensively). */
+  addEvidence(evidence) {
+    const safe = redact(evidence);
+    this.evidence.push(safe);
+    return safe;
+  }
+
+  /** Append a decision (transition, escalation, budget override, stop). */
+  addDecision(decision) {
+    const safe = redact({ decisionId: decision.decisionId || newId(), runId: this.runId, createdAt: decision.createdAt || timestamp(), ...decision });
+    this.decisions.push(safe);
+    return safe;
+  }
+
+  /** Record provider or estimated usage and update the cost budget. */
+  recordUsage(usage) {
+    const normalized = normalizeUsage(usage, this.policy);
+    const cost = estimateCost(normalized.inputTokens ?? 0, normalized.outputTokens ?? 0, this.policy);
+    this.usage = {
+      ...normalized,
+      usd: cost.known ? cost.usd : null,
+      model: cost.model,
+      rateCardId: cost.known ? cost.rateCardId : null,
+      effectiveDate: cost.known ? cost.effectiveDate : null,
+    };
+    if (cost.known) {
+      this.tracker.set('estimatedCostUsd', cost.usd);
+    } else {
+      // Unknown cost must not silently satisfy the cost envelope: mark the
+      // counter unmeasurable so a configured cost budget cannot be confirmed.
+      this.tracker.markUnknown('estimatedCostUsd', 'no provider rate card available');
+      this.usage.costUnknown = true;
+    }
+    return this.usage;
+  }
+
+  /**
+   * Record bounded tool output. Output over `maxInlineBytes` is written to a
+   * redacted artifact; only path, hash, byte count, and a redacted preview are
+   * stored inline. Redaction is mandatory and runs before anything reaches disk.
+   */
+  recordOutput({ name = 'output', output, status = 'ok', tool = null, args = {}, durationMs = null, exitCode = null, retryNumber = 0 } = {}) {
+    const rawText = typeof output === 'string' ? output : JSON.stringify(output ?? '');
+    // Redaction is mandatory: never add an option to bypass it.
+    const text = redactString(rawText);
+    const bytes = Buffer.byteLength(text, 'utf-8');
+    const maxInline = this.policy.output?.maxInlineBytes ?? 64 * 1024;
+    const previewBytes = this.policy.output?.previewBytes ?? 4 * 1024;
+    // Estimated output tokens (contract §4) so output volume is bounded too.
+    const per = this.policy.estimation?.bytesPerToken || 3;
+    this.tracker.add('outputTokens', Math.ceil(bytes / per));
+
+    let artifactPath = null;
+    let artifactHash = null;
+    if (bytes > maxInline) {
+      const dir = join(runsDir(this.targetDir), 'artifacts');
+      mkdirSync(dir, { recursive: true });
+      const full = join(dir, `${this.runId}-${name}-${newId().slice(0, 8)}.log`);
+      writeFileSync(full, text, 'utf-8');
+      artifactPath = full;
+      // Hash covers the exact persisted (redacted) bytes.
+      artifactHash = sha256Bytes(Buffer.from(text, 'utf-8'));
+    }
+
+    return this.addSpan({
+      kind: 'tool-output',
+      name,
+      tool,
+      args: redact(args),
+      result: status,
+      exitCode,
+      durationMs,
+      outputBytes: bytes,
+      artifactPath,
+      artifactHash,
+      preview: artifactPath ? text.slice(0, previewBytes) : null,
+      retryNumber,
+      status,
+    });
+  }
+
+  finalize({ status = null } = {}) {
+    this.finishedAt = timestamp();
+    const result = this.tracker.result();
+    // The budget result is authoritative for failure states: a caller may not
+    // label an exhausted, blocked, or unmeasurable-cost run as success.
+    let effective = status || (result.exhausted ? 'exhausted' : result.ok ? 'ok' : 'warning');
+    const unsafeToClaimSuccess = result.exhausted || result.costUnmeasurable === true;
+    if (unsafeToClaimSuccess && (effective === 'ok' || effective === 'warning' || effective === 'running')) {
+      effective = result.exhausted ? 'exhausted' : 'blocked';
+    }
+    this.status = effective;
+    return this.toRecord();
+  }
+
+  toRecord() {
+    return {
+      runId: this.runId,
+      schemaVersion: RUN_SCHEMA_VERSION,
+      workItemId: this.workItemId,
+      phase: this.phase,
+      startedAt: this.startedAt,
+      finishedAt: this.finishedAt,
+      status: this.status,
+      spans: this.spans,
+      evidence: this.evidence,
+      decisions: this.decisions,
+      budget: this.tracker.result(),
+      usage: this.usage,
+      capabilities: this.capabilities,
+      retention: this.retention,
+    };
+  }
+
+  /** Persist the ledger to `.cadet/runs/<runId>.json` (atomically). */
+  persist() {
+    const dir = runsDir(this.targetDir);
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, `${this.runId}.json`);
+    // Atomic write: a process interruption cannot truncate a run record.
+    writeJsonAtomic(path, this.toRecord());
+    return path;
+  }
+}
+
+/** Load a run record by id. */
+export function loadRun(targetDir, runId) {
+  const path = join(runsDir(targetDir), `${runId}.json`);
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, 'utf-8'));
+}
+
+/** List run records (id + status + timestamps), newest first. */
+export function listRuns(targetDir) {
+  const dir = runsDir(targetDir);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => {
+      try {
+        const rec = JSON.parse(readFileSync(join(dir, f), 'utf-8'));
+        return { runId: rec.runId, status: rec.status, startedAt: rec.startedAt, finishedAt: rec.finishedAt, file: f };
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .sort((a, b) => (a.startedAt < b.startedAt ? 1 : -1));
+}
+
+/**
+ * Apply the retention policy: delete successful run records unless
+ * `retainRunRecords` is set; keep failed runs when `keepOnFailure`. Never deletes
+ * unrelated files.
+ */
+export function cleanupRuns(targetDir, policy, { olderThanMs = null, now = new Date() } = {}) {
+  const runs = listRuns(targetDir);
+  const retainAll = policy?.retention?.retainRunRecords === true;
+  const keepOnFailure = policy?.retention?.keepOnFailure !== false;
+  const deleted = [];
+  const kept = [];
+
+  for (const run of runs) {
+    const age = now.getTime() - new Date(run.startedAt).getTime();
+    const oldEnough = olderThanMs === null || age >= olderThanMs;
+    const failed = ['failed', 'blocked', 'exhausted'].includes(run.status);
+    if (retainAll) { kept.push(run.runId); continue; }
+    if (failed && keepOnFailure) { kept.push(run.runId); continue; }
+    if (!oldEnough) { kept.push(run.runId); continue; }
+    try {
+      unlinkSync(join(runsDir(targetDir), run.file));
+      deleted.push(run.runId);
+    } catch {
+      kept.push(run.runId);
+    }
+  }
+  return { deleted, kept };
+}
+
+/**
+ * Build a secret-free run report: budget consumption and failures.
+ * Unknown telemetry is labeled, never replaced with invented values.
+ */
+export function buildReport(run) {
+  const checks = run.budget?.checks || [];
+  return {
+    runId: run.runId,
+    status: run.status,
+    workItemId: run.workItemId,
+    phase: run.phase,
+    startedAt: run.startedAt,
+    finishedAt: run.finishedAt,
+    budgets: checks.map((c) => ({
+      budget: c.budget,
+      used: c.used,
+      hard: c.hard,
+      remaining: c.remaining,
+      overage: c.hard !== null && c.used > c.hard,
+      status: c.status,
+    })),
+    toolCalls: checks.find((c) => c.counter === 'toolCalls')?.used ?? null,
+    retries: checks.find((c) => c.counter === 'retries')?.used ?? null,
+    usage: run.usage
+      ? {
+        source: run.usage.source,
+        inputTokens: run.usage.inputTokens,
+        outputTokens: run.usage.outputTokens,
+        usd: run.usage.usd,
+        model: run.usage.model,
+        costUnknown: run.usage.costUnknown === true || run.usage.usd === null,
+      }
+      : { source: 'unknown', costUnknown: true },
+    telemetry: {
+      tokenTelemetry: run.capabilities?.tokenTelemetry?.provider ? 'provider' : 'unavailable-estimated-or-unknown',
+      costTelemetry: run.usage?.usd != null ? 'estimated' : 'unavailable',
+      mcp: run.capabilities?.mcp?.available ? 'available' : 'unavailable',
+    },
+    failures: (run.spans || []).filter((s) => ['failed', 'blocked', 'exhausted', 'timed-out'].includes(s.status || s.result)),
+    spanCount: (run.spans || []).length,
+    evidenceCount: (run.evidence || []).length,
+    decisionCount: (run.decisions || []).length,
+  };
+}
+
+/** Machine-readable, secret-free report summary for display. */
+export function formatReport(run) {
+  const r = buildReport(run);
+  const lines = [];
+  lines.push(`Run ${r.runId} — ${r.status}`);
+  lines.push(`  Work item: ${r.workItemId || 'unscoped'}  Phase: ${r.phase || 'unknown'}`);
+  lines.push('  Budgets:');
+  for (const b of r.budgets) {
+    const cap = b.hard === null ? 'unbounded' : String(b.hard);
+    lines.push(`    ${b.budget.padEnd(22)} used ${String(b.used).padStart(8)} / ${cap.padStart(8)} (${b.status})${b.overage ? ' OVER' : ''}`);
+  }
+  lines.push(`  Usage: tokens=${r.usage.source}; usd=${r.usage.usd ?? 'unknown'}`);
+  lines.push(`  Telemetry: ${r.telemetry.tokenTelemetry}; cost=${r.telemetry.costTelemetry}; mcp=${r.telemetry.mcp}`);
+  if (r.failures.length) {
+    lines.push(`  Failures (${r.failures.length}):`);
+    for (const f of r.failures.slice(0, 20)) lines.push(`    ${f.kind || 'span'} ${f.name || f.tool || ''} ${f.result || f.status}`);
+  }
+  return lines.join('\n');
+}
+
+export { LedgerError, REDACTED, budgetReport };

package/src/harness/policy.mjs

@@ -0,0 +1,359 @@
+/**
+ * Cadet-Agent harness policy.
+ *
+ * Loads hard-coded conservative defaults, optionally overlays a repository-local
+ * `.cadet/harness.json`, validates the merged result, and exposes the resolved
+ * budget/limit policy used by every other harness module.
+ *
+ * Contract: docs/core/HarnessContract.md §3. Phase names and gate names are frozen
+ * compatibility invariants — this module may validate them but must not rename them.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Frozen phase names (compatibility invariant C1). */
+export const PHASES = Object.freeze([
+  'context-resolution',
+  'requirements',
+  'requirementsComplete',
+  'architecture',
+  'architectureComplete',
+  'spikes',
+  'story-breakdown',
+  'implementation',
+  'review',
+  'validation',
+  'closed',
+]);
+
+/** Frozen gate names (compatibility invariant C3). */
+export const GATES = Object.freeze([
+  'codeReviewCompleted',
+  'testsPassed',
+  'storyTrackingUpdated',
+  'compileCheckConfirmed',
+  'unityAnalyzerClean',
+  'acceptanceCriteriaValidated',
+  'securityReviewPassed',
+  'designArtifactSyncConfirmed',
+]);
+
+/** Legal phase transitions (compatibility invariant C4). */
+export const TRANSITIONS = Object.freeze({
+  implementation: { to: 'review', gates: ['testsPassed', 'compileCheckConfirmed', 'unityAnalyzerClean', 'storyTrackingUpdated'] },
+  review: { to: 'validation', gates: ['codeReviewCompleted', 'securityReviewPassed', 'acceptanceCriteriaValidated'] },
+  validation: { to: 'closed', gates: ['designArtifactSyncConfirmed'] },
+});
+
+/** Evidence statuses. */
+export const EVIDENCE_STATUSES = Object.freeze(['passed', 'failed', 'blocked', 'manual-confirmation', 'superseded']);
+
+/** Retry classes. */
+export const RETRY_CLASSES = Object.freeze(['deterministic', 'transient', 'repair', 'unknown']);
+
+/** Context tiers. */
+export const CONTEXT_TIERS = Object.freeze(['tier0', 'tier1', 'tier2', 'tier3']);
+
+const MIB = 1024 * 1024;
+
+/**
+ * Conservative default budgets. Every value is validated at load time.
+ * `hard` is the hard-stop threshold; `warn` is the soft-warning threshold (fraction 0..1).
+ */
+export const DEFAULT_BUDGETS = Object.freeze({
+  maxContextTokens:       { hard: 64000,    warn: 0.80, unit: 'tokens' },
+  maxOutputTokens:        { hard: 8000,     warn: 0.80, unit: 'tokens' },
+  maxToolCalls:           { hard: 80,       warn: 0.75, unit: 'calls' },
+  maxRetriesPerStep:      { hard: 2,        warn: null, unit: 'retries' },
+  maxTotalRetries:        { hard: 8,        warn: 0.75, unit: 'retries' },
+  maxWallClockMs:         { hard: 30 * 60 * 1000, warn: 0.80, unit: 'ms' },
+  maxEstimatedCostUsd:    { hard: 2.00,     warn: 0.80, unit: 'usd' },
+  maxDownloadedBytes:     { hard: 25 * MIB, warn: 0.80, unit: 'bytes' },
+  maxDecompressedBytes:   { hard: 100 * MIB, warn: 0.80, unit: 'bytes' },
+  maxArchiveFiles:        { hard: 2000,     warn: 0.80, unit: 'files' },
+});
+
+/**
+ * Hard safety ceilings. A repository override may raise a hard limit only when an
+ * explicit compatibility flag is set; it may never lower one below the default
+ * without the same explicit flag (contract §3, plan §5.3).
+ */
+export const HARD_CEILINGS = Object.freeze({
+  maxDownloadedBytes: 100 * MIB,
+  maxDecompressedBytes: 500 * MIB,
+  maxArchiveFiles: 10000,
+  maxWallClockMs: 4 * 60 * 60 * 1000,
+});
+
+/** Default archive-safety limits (Phase 6 consumes these). */
+export const DEFAULT_ARCHIVE_LIMITS = Object.freeze({
+  maxCompressedBytes: 25 * MIB,
+  maxDecompressedBytes: 100 * MIB,
+  maxFiles: 2000,
+  maxFilenameBytes: 240,
+  maxCompressionRatio: 100,
+});
+
+/** Default tool-output and retention policy. */
+export const DEFAULT_OUTPUT_POLICY = Object.freeze({
+  maxInlineBytes: 64 * 1024,
+  previewBytes: 4 * 1024,
+});
+
+export const DEFAULT_RETENTION = Object.freeze({
+  keepOnFailure: true,
+  retainRunRecords: false,
+  retainRawPrompt: false,
+});
+
+/** Default token/cost estimation policy. */
+export const DEFAULT_ESTIMATION = Object.freeze({
+  bytesPerToken: 3,
+  // Known rate cards keyed by model id. Absence of a card => no USD is reported.
+  rateCards: Object.freeze({}),
+});
+
+/** Git-guard hook behavior. */
+export const DEFAULT_HOOK_POLICY = Object.freeze({
+  mode: 'ask-on-recognized-write', // or 'fail-open' (opt-in, visible)
+});
+
+const BUDGET_KEYS = Object.keys(DEFAULT_BUDGETS);
+
+class PolicyError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'PolicyError';
+  }
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function isFiniteNumber(v) {
+  return typeof v === 'number' && Number.isFinite(v);
+}
+
+function isNonNegativeInt(v) {
+  return Number.isInteger(v) && v >= 0;
+}
+
+/**
+ * Validate a single budget override. Returns the normalized entry or throws PolicyError.
+ */
+function validateBudgetOverride(key, value, defaults) {
+  const def = defaults[key];
+  if (!def) {
+    throw new PolicyError(`Unknown budget key "${key}".`);
+  }
+  if (isPlainObject(value)) {
+    const out = { ...def };
+    for (const field of Object.keys(value)) {
+      if (field !== 'hard' && field !== 'warn') {
+        throw new PolicyError(`Budget "${key}" has unknown field "${field}".`);
+      }
+      const fv = value[field];
+      if (field === 'hard') {
+        if (!isFiniteNumber(fv) || fv < 0) {
+          throw new PolicyError(`Budget "${key}.hard" must be a non-negative finite number.`);
+        }
+        out.hard = fv;
+      } else {
+        if (fv !== null && (!isFiniteNumber(fv) || fv < 0 || fv > 1)) {
+          throw new PolicyError(`Budget "${key}.warn" must be null or a fraction between 0 and 1.`);
+        }
+        out.warn = fv;
+      }
+    }
+    return out;
+  }
+  if (!isFiniteNumber(value) || value < 0) {
+    throw new PolicyError(`Budget "${key}" must be a non-negative finite number or an object.`);
+  }
+  return { ...def, hard: value };
+}
+
+/**
+ * A project may never lower a hard safety ceiling, and may only exceed it with an
+ * explicit compatibility flag.
+ */
+function enforceCeilings(resolved, { allowCeilingOverride = false } = {}) {
+  for (const [key, ceiling] of Object.entries(HARD_CEILINGS)) {
+    const value = resolved.budgets[key]?.hard;
+    if (value === undefined) continue;
+    if (value > ceiling && !allowCeilingOverride) {
+      throw new PolicyError(
+        `Budget "${key}" (${value}) exceeds the hard safety ceiling (${ceiling}). ` +
+        `Set allowBudgetCeilingOverride in .cadet/harness.json to opt in explicitly.`
+      );
+    }
+  }
+}
+
+/**
+ * Parse and validate a repository harness policy document.
+ * Unknown top-level keys are rejected so misconfiguration fails loudly.
+ */
+export function validatePolicy(raw, defaults = DEFAULT_BUDGETS) {
+  if (!isPlainObject(raw)) {
+    throw new PolicyError('Harness policy must be a JSON object.');
+  }
+  const allowed = new Set([
+    '$schema',
+    'budgets', 'archive', 'output', 'retention', 'estimation', 'hook',
+    'allowBudgetCeilingOverride', 'scopes', 'model', 'analyzerCommand',
+    'compileCommand', 'testCommand', 'allowEmptyFreshness',
+  ]);
+  for (const key of Object.keys(raw)) {
+    if (!allowed.has(key)) {
+      throw new PolicyError(`Unknown harness policy key "${key}".`);
+    }
+  }
+
+  const budgets = {};
+  for (const [key, def] of Object.entries(defaults)) {
+    budgets[key] = { ...def };
+  }
+  if (raw.budgets !== undefined) {
+    if (!isPlainObject(raw.budgets)) {
+      throw new PolicyError('"budgets" must be an object.');
+    }
+    for (const [key, value] of Object.entries(raw.budgets)) {
+      budgets[key] = validateBudgetOverride(key, value, defaults);
+    }
+  }
+
+  const archive = { ...DEFAULT_ARCHIVE_LIMITS, ...(raw.archive || {}) };
+  for (const [key, value] of Object.entries(raw.archive || {})) {
+    if (!(key in DEFAULT_ARCHIVE_LIMITS)) {
+      throw new PolicyError(`Unknown archive limit "${key}".`);
+    }
+    if (!isNonNegativeInt(value)) {
+      throw new PolicyError(`Archive limit "${key}" must be a non-negative integer.`);
+    }
+  }
+
+  const output = { ...DEFAULT_OUTPUT_POLICY, ...(raw.output || {}) };
+  for (const [key, value] of Object.entries(raw.output || {})) {
+    if (!(key in DEFAULT_OUTPUT_POLICY)) {
+      throw new PolicyError(`Unknown output policy key "${key}".`);
+    }
+    if (!isNonNegativeInt(value)) {
+      throw new PolicyError(`Output policy "${key}" must be a non-negative integer.`);
+    }
+  }
+
+  const retention = { ...DEFAULT_RETENTION, ...(raw.retention || {}) };
+  for (const [key, value] of Object.entries(raw.retention || {})) {
+    if (!(key in DEFAULT_RETENTION)) {
+      throw new PolicyError(`Unknown retention key "${key}".`);
+    }
+    if (typeof value !== 'boolean') {
+      throw new PolicyError(`Retention "${key}" must be a boolean.`);
+    }
+  }
+
+  const estimation = {
+    ...DEFAULT_ESTIMATION,
+    ...(raw.estimation || {}),
+    rateCards: { ...(raw.estimation?.rateCards || {}) },
+  };
+  if (!isNonNegativeInt(estimation.bytesPerToken) || estimation.bytesPerToken < 1) {
+    throw new PolicyError('"estimation.bytesPerToken" must be a positive integer.');
+  }
+
+  const hook = { ...DEFAULT_HOOK_POLICY, ...(raw.hook || {}) };
+  if (!['ask-on-recognized-write', 'fail-open'].includes(hook.mode)) {
+    throw new PolicyError('"hook.mode" must be "ask-on-recognized-write" or "fail-open".');
+  }
+
+  const allowCeilingOverride = raw.allowBudgetCeilingOverride === true;
+
+  const resolved = {
+    budgets,
+    archive,
+    output,
+    retention,
+    estimation,
+    hook,
+    allowBudgetCeilingOverride: allowCeilingOverride,
+    allowEmptyFreshness: raw.allowEmptyFreshness === true,
+    scopes: raw.scopes || { perRun: {}, perStory: {} },
+    model: raw.model || null,
+    analyzerCommand: raw.analyzerCommand || null,
+    compileCommand: raw.compileCommand || null,
+    testCommand: raw.testCommand || null,
+  };
+
+  if (raw.scopes !== undefined) {
+    if (!isPlainObject(raw.scopes)) throw new PolicyError('"scopes" must be an object.');
+    for (const scope of ['perRun', 'perStory']) {
+      const s = raw.scopes[scope];
+      if (s === undefined) continue;
+      if (!isPlainObject(s)) throw new PolicyError(`"scopes.${scope}" must be an object.`);
+      for (const [key, value] of Object.entries(s)) {
+        const v = validateBudgetOverride(key, isPlainObject(value) ? value.hard ?? value : value, defaults);
+        if (value !== null && isPlainObject(value) && value.warn !== undefined) {
+          if (value.warn !== null && (!isFiniteNumber(value.warn) || value.warn < 0 || value.warn > 1)) {
+            throw new PolicyError(`"scopes.${scope}.${key}.warn" must be null or a fraction between 0 and 1.`);
+          }
+        }
+        s[key] = v.hard;
+      }
+    }
+  }
+
+  enforceCeilings(resolved, { allowCeilingOverride });
+
+  return resolved;
+}
+
+/** Returns the built-in default policy, fully validated. */
+export function defaultPolicy() {
+  return validatePolicy({});
+}
+
+export function policyPath(targetDir) {
+  return join(targetDir, '.cadet', 'harness.json');
+}
+
+/**
+ * Load the resolved policy for a repository. Missing file => defaults.
+ * Malformed/unknown-typed policy throws PolicyError rather than silently degrading.
+ */
+export function loadPolicy(targetDir, { defaults = DEFAULT_BUDGETS } = {}) {
+  const path = policyPath(targetDir);
+  if (!existsSync(path)) {
+    return { ...validatePolicy({}, defaults), sourcePath: null };
+  }
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(path, 'utf-8'));
+  } catch (err) {
+    throw new PolicyError(`Failed to parse ${path}: ${err.message}`);
+  }
+  return { ...validatePolicy(raw, defaults), sourcePath: path };
+}
+
+/** Resolve the effective budget for a scope, applying per-run/per-story overrides. */
+export function budgetForScope(policy, scope = 'perRun') {
+  const budgets = {};
+  for (const [key, def] of Object.entries(policy.budgets)) {
+    budgets[key] = { ...def };
+  }
+  const overrides = policy.scopes?.[scope] || {};
+  for (const [key, value] of Object.entries(overrides)) {
+    if (budgets[key]) budgets[key] = { ...budgets[key], hard: value };
+  }
+  return budgets;
+}
+
+/** Warning threshold for a budget, or null when the budget has no warning. */
+export function warnThreshold(def) {
+  if (def.warn === null || def.warn === undefined) return null;
+  return def.hard * def.warn;
+}
+
+export { PolicyError, BUDGET_KEYS, MIB };