@planu/cli 4.13.0 → 4.14.1

package/dist/engine/test-generators/contract-test-generator.js

@@ -1,6 +1,4 @@
-// engine/test-generators/contract-test-generator.ts
-// SPEC-018: Contract test generation (OpenAPI, Pact, GraphQL, tRPC)
-import { getStandardVersion } from '../../config/version-defaults.js';
+import { technologyValue } from '../technology-registry.js';
 // === Contract format detection ===
 /**
  * Detect the contract format from project stack.
@@ -11,10 +9,13 @@ export function detectContractFormat(knowledge) {
     if (stack.some((s) => s.includes('pact'))) {
         return 'pact';
     }
-    if (stack.some((s) => s.includes('graphql') || s.includes('@apollo') || s.includes('yoga') || s === 'gql')) {
+    if (stack.some((s) => s.includes(technologyValue('technology-graphql-aed31c')) ||
+        s.includes('@apollo') ||
+        s.includes('yoga') ||
+        s === 'gql')) {
         return 'graphql-schema';
     }
-    if (stack.some((s) => s.includes('trpc'))) {
+    if (stack.some((s) => s.includes(technologyValue('technology-trpc-7a75ed')))) {
         return 'trpc-router';
     }
     return 'openapi';
@@ -27,209 +28,15 @@ export function detectContractFormat(knowledge) {
 export function buildSampleEndpoints(_specTitle) {
     return [];
 }
-// === OpenAPI contract generation ===
-function buildOpenApiYaml(specTitle, endpoints) {
-    const resource = specTitle
-        .toLowerCase()
-        .replace(/[^a-z0-9]/g, '-')
-        .replace(/-+/g, '-');
-    const openapiVersion = getStandardVersion('openapi') || '3.0.3';
-    const lines = [
-        `openapi: "${openapiVersion}"`,
-        'info:',
-        `  title: "${specTitle} API Contract"`,
-        '  version: "1.0.0"',
-        '  description: "Auto-generated contract from Planu SPEC-018"',
-        'paths:',
-    ];
-    const grouped = new Map();
-    for (const ep of endpoints) {
-        const existing = grouped.get(ep.path) ?? [];
-        existing.push(ep);
-        grouped.set(ep.path, existing);
-    }
-    for (const [path, eps] of grouped) {
-        lines.push(`  "${path}":`);
-        for (const ep of eps) {
-            const method = ep.method.toLowerCase();
-            lines.push(`    ${method}:`);
-            lines.push(`      operationId: "${method}${resource.replace(/-/g, '')}${ep.path.includes('{id}') ? 'ById' : ''}"`);
-            lines.push('      tags:');
-            lines.push(`        - "${resource}"`);
-            lines.push('      responses:');
-            for (const code of ep.statusCodes) {
-                lines.push(`        "${code}":`);
-                lines.push(`          description: "HTTP ${code}"`);
-                if (code < 400) {
-                    lines.push('          content:');
-                    lines.push('            application/json:');
-                    lines.push('              schema:');
-                    lines.push('                type: object');
-                }
-            }
-        }
-    }
-    return lines.join('\n');
-}
-// === Pact contract generation ===
-function buildPactContract(specTitle, endpoints) {
-    const consumer = specTitle.toLowerCase().replace(/[^a-z0-9]/g, '-');
-    const provider = `${consumer}-provider`;
-    const interactions = endpoints
-        .map((ep, i) => {
-        const description = `${ep.method} ${ep.path} — scenario ${i + 1}`;
-        return `    {
-      "description": "${description}",
-      "providerState": "${specTitle} is initialized",
-      "request": {
-        "method": "${ep.method}",
-        "path": "${ep.path.replace('{id}', '550e8400-e29b-41d4-a716-446655440000')}"
-      },
-      "response": {
-        "status": ${ep.statusCodes[0] ?? 200},
-        "headers": { "Content-Type": "application/json" },
-        "body": {}
-      }
-    }`;
-    })
-        .join(',\n');
-    return `{
-  "consumer": { "name": "${consumer}-consumer" },
-  "provider": { "name": "${provider}" },
-  "interactions": [
-${interactions}
-  ],
-  "metadata": {
-    "pactSpecification": { "version": "2.0.0" },
-    "planu": { "spec": "${specTitle}", "generated": true }
-  }
-}`;
-}
-// === GraphQL schema contract generation ===
-function buildGraphQlSchema(specTitle) {
-    const typeName = specTitle.replace(/[^a-zA-Z0-9]/g, '').replace(/^\d+/, '');
-    return `# GraphQL schema contract — ${specTitle}
-# Auto-generated by Planu SPEC-018
-
-type ${typeName} {
-  id: ID!
-  name: String!
-  createdAt: String!
-  updatedAt: String!
-}
-
-input Create${typeName}Input {
-  name: String!
-}
-
-input Update${typeName}Input {
-  name: String
-}
-
-type Query {
-  list${typeName}s: [${typeName}!]!
-  get${typeName}(id: ID!): ${typeName}
-}
-
-type Mutation {
-  create${typeName}(input: Create${typeName}Input!): ${typeName}!
-  update${typeName}(id: ID!, input: Update${typeName}Input!): ${typeName}!
-  delete${typeName}(id: ID!): Boolean!
-}
-`;
-}
-// === tRPC router contract generation ===
-function buildTrpcRouter(specTitle) {
-    const name = specTitle
-        .toLowerCase()
-        .replace(/[^a-z0-9\s]/g, '')
-        .split(/\s+/)
-        .map((w, i) => (i === 0 ? w : w.charAt(0).toUpperCase() + w.slice(1)))
-        .join('');
-    return `// tRPC router contract — ${specTitle}
-// Auto-generated by Planu SPEC-018
-// Install: @trpc/server, zod
-
-import { z } from 'zod';
-import { router, publicProcedure, protectedProcedure } from '../trpc';
-
-const ${name}Schema = z.object({
-  id: z.string().uuid(),
-  name: z.string().min(1).max(255),
-  createdAt: z.iso.datetime(),
-});
-
-const create${name.charAt(0).toUpperCase() + name.slice(1)}Schema = z.object({
-  name: z.string().min(1).max(255),
-});
-
-export const ${name}Router = router({
-  list: publicProcedure
-    .output(z.array(${name}Schema))
-    .query(async () => {
-      // TODO: Implement list
-      return [];
-    }),
-
-  getById: publicProcedure
-    .input(z.object({ id: z.string().uuid() }))
-    .output(${name}Schema.nullable())
-    .query(async ({ input }) => {
-      // TODO: Implement getById
-      void input;
-      return null;
-    }),
-
-  create: protectedProcedure
-    .input(create${name.charAt(0).toUpperCase() + name.slice(1)}Schema)
-    .output(${name}Schema)
-    .mutation(async ({ input }) => {
-      // TODO: Implement create
-      throw new Error(\`Not implemented: \${input.name}\`);
-    }),
-
-  delete: protectedProcedure
-    .input(z.object({ id: z.string().uuid() }))
-    .output(z.boolean())
-    .mutation(async ({ input }) => {
-      // TODO: Implement delete
-      void input;
-      return false;
-    }),
-});
-`;
-}
 // === Main export ===
 /**
  * Generate a contract spec for the given spec title and knowledge.
  * Format is auto-detected from project stack.
  */
-export function generateContractSpec(specTitle, knowledge) {
+export function generateContractSpec(_specTitle, knowledge) {
     const format = detectContractFormat(knowledge);
     const endpoints = [];
-    if (endpoints.length === 0) {
-        return { format, content: '', endpoints };
-    }
-    let content;
-    switch (format) {
-        case 'pact':
-            content = buildPactContract(specTitle, endpoints);
-            break;
-        case 'graphql-schema':
-            content = buildGraphQlSchema(specTitle);
-            break;
-        case 'trpc-router':
-            content = buildTrpcRouter(specTitle);
-            break;
-        case 'openapi':
-            content = buildOpenApiYaml(specTitle, endpoints);
-            break;
-        /* v8 ignore next 3 */
-        default:
-            content = buildOpenApiYaml(specTitle, endpoints);
-            break;
-    }
-    return { format, content, endpoints };
+    return { format, content: '', endpoints };
 }
 /**
  * Get the file extension for a given contract format.
@@ -238,7 +45,7 @@ export function getContractFileExtension(format) {
     const extMap = {
         openapi: 'yaml',
         pact: 'json',
-        'graphql-schema': 'graphql',
+        'graphql-schema': technologyValue('technology-graphql-aed31c'),
         'trpc-router': 'ts',
     };
     return extMap[format];

package/dist/engine/test-generators/platform-test-templates-b.js

@@ -1,5 +1,4 @@
-// engine/test-generators/platform-test-templates-b.ts
-// SPEC-015b: Advanced test scaffold generators — Anchor (Solana) and ML robustness
+import { technologyValue } from '../technology-registry.js';
 // === Anchor (Solana) test scaffold ===
 function buildAnchorTestContent(specTitle) {
     return [
@@ -180,7 +179,7 @@ function buildMLRobustnessContent(specTitle) {
 export function buildMLRobustnessTestFile(title, slug, testDir, autoGenerate) {
     return {
         path: `${testDir}/ml/test_${slug}_robustness.py`,
-        framework: 'pytest',
+        framework: technologyValue('technology-pytest-2b0121'),
         content: buildMLRobustnessContent(title),
         ready: autoGenerate,
     };

package/dist/engine/test-generators/platform-test-templates.js

@@ -1,7 +1,4 @@
-// engine/test-generators/platform-test-templates.ts
-// SPEC-015a: Test scaffold generators for Smart Contracts and ML projects
-// Criteria 12: Smart contract tests (Hardhat/Foundry, fuzzing, invariant)
-// Criteria 13: ML tests (data validation, accuracy thresholds, drift detection)
+import { technologyValue } from '../technology-registry.js';
 import { buildAnchorTestFile, buildMLRobustnessTestFile } from './platform-test-templates-b.js';
 import { buildMLTestContent } from './platform-test-templates-ml.js';
 // === Smart contract detection ===
@@ -252,7 +249,7 @@ export function buildMLTestFiles(title, slug, testDir, autoGenerate) {
     return [
         {
             path: `${testDir}/ml/test_${slug}.py`,
-            framework: 'pytest',
+            framework: technologyValue('technology-pytest-2b0121'),
             content: buildMLTestContent(title),
             ready: autoGenerate,
         },

package/dist/engine/test-mocks-generator.js

@@ -1,11 +1,12 @@
+import { technologyValue } from './technology-registry.js';
 // engine/test-mocks-generator.ts — SPEC-018 multi-language mock code generator
 // Orchestrator: routes to the correct template based on testing framework.
 import { MOCK_TEMPLATES } from './test-mocks-generator/mock-templates.js';
 // Frameworks supported by the mock generator (superset of TestingFramework)
 const SUPPORTED_FRAMEWORKS = new Set([
-    'vitest',
-    'jest',
-    'pytest',
+    technologyValue('technology-vitest-a9127f'),
+    technologyValue('technology-jest-35e99f'),
+    technologyValue('technology-pytest-2b0121'),
     'go-test',
     'junit',
     'testng',

package/dist/engine/test-plan-generator.js

@@ -1,3 +1,4 @@
+import { technologyValue } from './technology-registry.js';
 // Hours estimate per layer type
 const LAYER_HOURS = {
     unit: 2,
@@ -38,15 +39,30 @@ function isMicroservices(knowledge) {
         knowledge.apps.filter((a) => a.type === 'backend' || a.type === 'worker').length > 1);
 }
 function hasAuth(knowledge) {
-    const authTerms = ['auth', 'jwt', 'oauth', 'passport', 'keycloak', 'auth0', 'clerk', 'supabase'];
+    const authTerms = [
+        'auth',
+        'jwt',
+        'oauth',
+        'passport',
+        'keycloak',
+        'auth0',
+        'clerk',
+        technologyValue('technology-supabase-4d7594'),
+    ];
     return authTerms.some((term) => knowledge.stack.some((s) => s.toLowerCase().includes(term)));
 }
 function detectFrameworksForLayer(layerType, knowledge) {
     const lang = knowledge.language;
     const unitFrameworks = {
-        typescript: ['vitest', 'jest'],
-        javascript: ['vitest', 'jest'],
-        python: ['pytest'],
+        typescript: [
+            technologyValue('technology-vitest-a9127f'),
+            technologyValue('technology-jest-35e99f'),
+        ],
+        javascript: [
+            technologyValue('technology-vitest-a9127f'),
+            technologyValue('technology-jest-35e99f'),
+        ],
+        python: [technologyValue('technology-pytest-2b0121')],
         go: ['go test'],
         rust: ['cargo test'],
         java: ['JUnit 5'],
@@ -57,20 +73,20 @@ function detectFrameworksForLayer(layerType, knowledge) {
         php: ['PHPUnit'],
         ruby: ['RSpec'],
     };
-    const e2eFrameworks = knowledge.stack.includes('playwright')
-        ? ['Playwright']
+    const e2eFrameworks = knowledge.stack.includes(technologyValue('technology-playwright-7827e8'))
+        ? [technologyValue('technology-playwright-9b7555')]
         : knowledge.stack.includes('cypress')
             ? ['Cypress']
-            : ['Playwright'];
+            : [technologyValue('technology-playwright-9b7555')];
     const frameworkMap = {
-        unit: unitFrameworks[lang] ?? ['vitest'],
-        integration: unitFrameworks[lang] ?? ['vitest'],
+        unit: unitFrameworks[lang] ?? [technologyValue('technology-vitest-a9127f')],
+        integration: unitFrameworks[lang] ?? [technologyValue('technology-vitest-a9127f')],
         e2e: e2eFrameworks,
         contract: ['Pact', 'Schemathesis'],
-        visual: ['Playwright', 'Percy', 'Chromatic'],
+        visual: [technologyValue('technology-playwright-9b7555'), 'Percy', 'Chromatic'],
         load: ['k6', 'Locust', 'Gatling'],
         security: ['OWASP ZAP', 'Trivy', 'Snyk'],
-        a11y: ['axe-core', 'Playwright', 'pa11y'],
+        a11y: ['axe-core', technologyValue('technology-playwright-9b7555'), 'pa11y'],
     };
     return frameworkMap[layerType] ?? [];
 }
@@ -78,7 +94,9 @@ function detectToolsForLayer(layerType, knowledge) {
     const toolMap = {
         unit: ['Coverage reporter', 'Test runner'],
         integration: ['Supertest', 'Testcontainers', 'Docker Compose'],
-        e2e: knowledge.stack.includes('playwright') ? ['Playwright', 'playwright MCP'] : ['Playwright'],
+        e2e: knowledge.stack.includes(technologyValue('technology-playwright-7827e8'))
+            ? [technologyValue('technology-playwright-9b7555'), 'playwright MCP']
+            : [technologyValue('technology-playwright-9b7555')],
         contract: ['Pact Broker', 'Swagger Validator'],
         visual: ['Percy', 'Chromatic', 'BackstopJS'],
         load: ['k6', 'Artillery', 'autocannon'],

package/dist/engine/test-scaffold-generator/advanced-scaffold.js

@@ -1,5 +1,4 @@
-// engine/test-scaffold-generator/advanced-scaffold.ts — E2E, BDD, property-based, and load test scaffolds
-// SPEC-018
+import { technologyValue } from '../technology-registry.js';
 import { toSnake } from './helpers.js';
 // === E2E test scaffold ===
 /**
@@ -127,7 +126,7 @@ export function generatePropertyTestScaffold(specTitle, framework) {
     };
 }
 function buildPropertyContent(title, framework) {
-    if (framework === 'pytest') {
+    if (framework === technologyValue('technology-pytest-2b0121')) {
         return buildHypothesisContent(title);
     }
     return buildFastCheckContent(title, framework);
@@ -156,7 +155,7 @@ function buildHypothesisContent(title) {
     ].join('\n');
 }
 function buildFastCheckContent(title, framework) {
-    const importLine = framework === 'vitest'
+    const importLine = framework === technologyValue('technology-vitest-a9127f')
         ? "import { describe, it, expect } from 'vitest';\nimport * as fc from 'fast-check';"
         : "import { describe, it, expect } from '@jest/globals';\nimport * as fc from 'fast-check';";
     return [
@@ -192,7 +191,7 @@ export function generateLoadTestScaffold(specTitle, endpoint) {
     return {
         filepath: `tests/load/${toSnake(specTitle)}.k6.js`,
         content: buildK6SmokeTest(specTitle, endpoint),
-        framework: 'vitest', // placeholder — load tests run via k6, not vitest
+        framework: technologyValue('technology-vitest-a9127f'), // placeholder — load tests run via k6, not vitest
         testType: 'load',
         runCommand: `k6 run tests/load/${toSnake(specTitle)}.k6.js`,
     };

package/dist/engine/test-scaffold-generator/unit-scaffold.js

@@ -1,5 +1,4 @@
-// engine/test-scaffold-generator/unit-scaffold.ts — Unit test scaffold generators
-// SPEC-018
+import { technologyValue } from '../technology-registry.js';
 import { generateMockCode, criteriaContainsMockKeyword } from '../test-mocks-generator.js';
 import { toPascal, toSnake, getFrameworkExt, getFrameworkRunCommand } from './helpers.js';
 // === Unit test scaffold ===
@@ -27,7 +26,7 @@ function buildUnitContent(title, criteria, framework) {
     return `${base}\n// === Mock example for this spec ===\n${mockExample}`;
 }
 function buildBaseUnitContent(title, criteria, framework) {
-    if (framework === 'pytest') {
+    if (framework === technologyValue('technology-pytest-2b0121')) {
         return buildPytestUnit(title, criteria);
     }
     if (framework === 'junit') {
@@ -36,7 +35,7 @@ function buildBaseUnitContent(title, criteria, framework) {
     return buildJsUnit(title, criteria, framework);
 }
 function buildJsUnit(title, criteria, framework) {
-    const importLine = framework === 'vitest'
+    const importLine = framework === technologyValue('technology-vitest-a9127f')
         ? "import { describe, it } from 'vitest';"
         : "import { describe, it } from '@jest/globals';";
     const tests = criteria
@@ -75,11 +74,11 @@ export function generateIntegrationTestScaffold(specTitle, framework) {
     };
 }
 function buildIntegrationContent(title, framework) {
-    if (framework === 'pytest') {
+    if (framework === technologyValue('technology-pytest-2b0121')) {
         const cls = toPascal(title);
         return `import pytest\n\n\nclass Test${cls}Integration:\n    """Integration tests for ${title}."""\n\n    @pytest.mark.skip(reason="Bind integration boundaries before enabling.")\n    def test_declared_integration_boundary(self):\n        raise AssertionError("Bind integration boundaries before enabling.")\n`;
     }
-    const importLine = framework === 'vitest'
+    const importLine = framework === technologyValue('technology-vitest-a9127f')
         ? "import { describe, it } from 'vitest';"
         : "import { describe, it } from '@jest/globals';";
     return `${importLine}\n\ndescribe('${title} — Integration', () => {\n  it.skip('declared integration boundary is verified', async () => {\n    throw new Error('Bind integration boundaries before enabling.');\n  });\n});\n`;

package/dist/engine/timing/budget.d.ts

@@ -1,25 +1,14 @@
 import type { BudgetResult, BudgetExceeded, BudgetOk } from '../../types/timing.js';
 export type { BudgetResult, BudgetExceeded, BudgetOk };
 /**
- * Run `fn` within a time budget of `budgetMs` milliseconds.
- *
- * - If `fn` resolves in time → returns {exceeded: false, value, elapsedMs}
- * - If the budget fires first → returns {exceeded: true, step, budgetMs, elapsedMs, warning}
- *   and the underlying promise is left to settle on its own (fire-and-forget).
- *
- * Never throws — all errors from `fn` are caught and treated as budget exceeded.
- */
-export declare function withBudget<T>(step: string, budgetMs: number, fn: () => Promise<T>): Promise<BudgetResult<T>>;
-/**
- * Extract the value from a BudgetResult, or return `fallback` when exceeded.
- * Optionally collect warnings into a mutable array.
+ * Runs a step under a child deadline. The supplied signal is aborted when the
+ * local budget or any parent request deadline expires. Abandoned work is
+ * observed but is never awaited on the response path.
  */
+export declare function withBudget<T>(step: string, budgetMs: number, fn: (signal: AbortSignal) => Promise<T>): Promise<BudgetResult<T>>;
 export declare function unwrapBudget<T>(result: BudgetResult<T>, fallback: T, warnings?: string[]): T;
-/**
- * Total budget enforcer — wraps an entire operation in a hard ceiling.
- * Returns {timedOut: true, warning} if the ceiling fires, or {timedOut: false, value} otherwise.
- */
-export declare function withTotalBudget<T>(operationName: string, ceilingMs: number, fn: () => Promise<T>): Promise<{
+/** Applies the same cancellation tree to a complete operation ceiling. */
+export declare function withTotalBudget<T>(operationName: string, ceilingMs: number, fn: (signal: AbortSignal) => Promise<T>): Promise<{
     timedOut: false;
     value: T;
 } | {

package/dist/engine/timing/budget.js

@@ -1,56 +1,80 @@
-// engine/timing/budget.ts — Per-step budget wrapper (SPEC-713)
-// withBudget(stepName, ms, fn) aborts fn after `ms` milliseconds and returns
-// a PartialResult with a warning string instead of throwing.
+// engine/timing/budget.ts — Cancellation-aware per-step budgets.
+import { createChildCancellationScope } from '../execution/context.js';
+function elapsedSince(start) {
+    return Math.round(performance.now() - start);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function executeWithinBudget(requestedMs, fn) {
+    const scope = createChildCancellationScope(requestedMs);
+    let task;
+    try {
+        task = fn(scope.signal);
+    }
+    catch (error) {
+        task = Promise.reject(error instanceof Error ? error : new Error(String(error)));
+    }
+    void task.catch(() => undefined);
+    const result = new Promise((resolve) => {
+        let settled = false;
+        const settle = (value) => {
+            if (!settled) {
+                settled = true;
+                scope.signal.removeEventListener('abort', onAbort);
+                resolve(value);
+            }
+        };
+        const onAbort = () => {
+            settle({ ok: false, error: new Error(errorMessage(scope.signal.reason)) });
+        };
+        scope.signal.addEventListener('abort', onAbort, { once: true });
+        task.then((value) => {
+            settle({ ok: true, value });
+        }, (error) => {
+            settle({ ok: false, error: error instanceof Error ? error : new Error(String(error)) });
+        });
+        if (scope.signal.aborted) {
+            onAbort();
+        }
+    });
+    return {
+        result,
+        timeoutMs: scope.timeoutMs,
+        dispose: () => {
+            scope.dispose();
+        },
+    };
+}
 /**
- * Run `fn` within a time budget of `budgetMs` milliseconds.
- *
- * - If `fn` resolves in time → returns {exceeded: false, value, elapsedMs}
- * - If the budget fires first → returns {exceeded: true, step, budgetMs, elapsedMs, warning}
- *   and the underlying promise is left to settle on its own (fire-and-forget).
- *
- * Never throws — all errors from `fn` are caught and treated as budget exceeded.
+ * Runs a step under a child deadline. The supplied signal is aborted when the
+ * local budget or any parent request deadline expires. Abandoned work is
+ * observed but is never awaited on the response path.
  */
 export async function withBudget(step, budgetMs, fn) {
     const start = performance.now();
-    const timeoutPromise = new Promise((resolve) => {
-        setTimeout(() => {
-            const elapsed = Math.round(performance.now() - start);
-            resolve({
-                exceeded: true,
-                step,
-                budgetMs,
-                elapsedMs: elapsed,
-                warning: `[SPEC-713] Step "${step}" exceeded ${String(budgetMs)}ms budget (actual: ${String(elapsed)}ms)`,
-            });
-        }, budgetMs);
-    });
+    const execution = executeWithinBudget(budgetMs, fn);
     try {
-        const result = await Promise.race([
-            fn().then((value) => ({
-                exceeded: false,
-                value,
-                elapsedMs: Math.round(performance.now() - start),
-            })),
-            timeoutPromise,
-        ]);
-        return result;
-    }
-    catch (err) {
-        const elapsed = Math.round(performance.now() - start);
-        const message = err instanceof Error ? err.message : String(err);
+        const outcome = await execution.result;
+        const elapsedMs = elapsedSince(start);
+        if (outcome.ok) {
+            return { exceeded: false, value: outcome.value, elapsedMs };
+        }
+        const thrownBeforeDeadline = elapsedMs < execution.timeoutMs;
         return {
             exceeded: true,
             step,
-            budgetMs,
-            elapsedMs: elapsed,
-            warning: `[SPEC-713] Step "${step}" threw after ${String(elapsed)}ms: ${message}`,
+            budgetMs: execution.timeoutMs,
+            elapsedMs,
+            warning: thrownBeforeDeadline
+                ? `[SPEC-713] Step "${step}" threw after ${String(elapsedMs)}ms: ${errorMessage(outcome.error)}`
+                : `[SPEC-713] Step "${step}" exceeded ${String(execution.timeoutMs)}ms budget (actual: ${String(elapsedMs)}ms)`,
         };
     }
+    finally {
+        execution.dispose();
+    }
 }
-/**
- * Extract the value from a BudgetResult, or return `fallback` when exceeded.
- * Optionally collect warnings into a mutable array.
- */
 export function unwrapBudget(result, fallback, warnings) {
     if (result.exceeded) {
         warnings?.push(result.warning);
@@ -58,34 +82,26 @@ export function unwrapBudget(result, fallback, warnings) {
     }
     return result.value;
 }
-/**
- * Total budget enforcer — wraps an entire operation in a hard ceiling.
- * Returns {timedOut: true, warning} if the ceiling fires, or {timedOut: false, value} otherwise.
- */
+/** Applies the same cancellation tree to a complete operation ceiling. */
 export async function withTotalBudget(operationName, ceilingMs, fn) {
     const start = performance.now();
-    const ceilingPromise = new Promise((resolve) => {
-        setTimeout(() => {
-            const elapsed = Math.round(performance.now() - start);
-            resolve({
-                timedOut: true,
-                warning: `[SPEC-713] Operation "${operationName}" exceeded ${String(ceilingMs)}ms ceiling (actual: ${String(elapsed)}ms) — aborting cleanly`,
-            });
-        }, ceilingMs);
-    });
+    const execution = executeWithinBudget(ceilingMs, fn);
     try {
-        return await Promise.race([
-            fn().then((value) => ({ timedOut: false, value })),
-            ceilingPromise,
-        ]);
-    }
-    catch (err) {
-        const elapsed = Math.round(performance.now() - start);
-        const message = err instanceof Error ? err.message : String(err);
+        const outcome = await execution.result;
+        if (outcome.ok) {
+            return { timedOut: false, value: outcome.value };
+        }
+        const elapsedMs = elapsedSince(start);
+        const thrownBeforeDeadline = elapsedMs < execution.timeoutMs;
         return {
             timedOut: true,
-            warning: `[SPEC-713] Operation "${operationName}" threw after ${String(elapsed)}ms: ${message}`,
+            warning: thrownBeforeDeadline
+                ? `[SPEC-713] Operation "${operationName}" threw after ${String(elapsedMs)}ms: ${errorMessage(outcome.error)}`
+                : `[SPEC-713] Operation "${operationName}" exceeded ${String(execution.timeoutMs)}ms ceiling (actual: ${String(elapsedMs)}ms) — aborted cleanly`,
         };
     }
+    finally {
+        execution.dispose();
+    }
 }
 //# sourceMappingURL=budget.js.map