@methodts/runtime 0.1.0

package/dist/cost-governor/backpressure-queue.test.js

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: Apache-2.0
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { BackpressureQueue } from './backpressure-queue.js';
+test('enqueue + dequeue resolves in FIFO order', async () => {
+    const queue = new BackpressureQueue();
+    const order = [];
+    const p1 = queue.enqueue(5000).then(() => order.push(1));
+    const p2 = queue.enqueue(5000).then(() => order.push(2));
+    assert.equal(queue.size, 2);
+    queue.dequeue();
+    await p1;
+    queue.dequeue();
+    await p2;
+    assert.deepEqual(order, [1, 2]);
+});
+test('dequeue returns false when empty', () => {
+    const queue = new BackpressureQueue();
+    assert.equal(queue.dequeue(), false);
+});
+test('timeout rejects after timeoutMs', async () => {
+    const queue = new BackpressureQueue();
+    await assert.rejects(queue.enqueue(10), (err) => err.message.includes('exceeded'));
+});
+test('abort signal rejects', async () => {
+    const queue = new BackpressureQueue();
+    const ac = new AbortController();
+    const p = queue.enqueue(5000, ac.signal);
+    ac.abort();
+    await assert.rejects(p, (err) => err.message.includes('Aborted'));
+    assert.equal(queue.size, 0);
+});
+test('already-aborted signal rejects synchronously', async () => {
+    const queue = new BackpressureQueue();
+    const ac = new AbortController();
+    ac.abort();
+    await assert.rejects(queue.enqueue(5000, ac.signal), (err) => err.message.includes('Aborted'));
+});
+test('clear rejects all entries', async () => {
+    const queue = new BackpressureQueue();
+    const p1 = queue.enqueue(5000);
+    const p2 = queue.enqueue(5000);
+    queue.clear();
+    await assert.rejects(p1);
+    await assert.rejects(p2);
+    assert.equal(queue.size, 0);
+});
+//# sourceMappingURL=backpressure-queue.test.js.map

package/dist/cost-governor/backpressure-queue.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backpressure-queue.test.js","sourceRoot":"","sources":["../../src/cost-governor/backpressure-queue.test.ts"],"names":[],"mappings":"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"}

package/dist/cost-governor/cost-events.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Cost telemetry event types + emit helpers.
+ *
+ * All cost events carry domain='cost' on the Universal Event Bus.
+ * The accountId field is included for forward-compatibility with
+ * multi-account routing — currently always 'default'.
+ *
+ * PRD-057 / S2 §8: Each emitter accepts an optional `appId` field. When
+ * present (agent-runtime / Cortex case), the emitted RuntimeEvent carries
+ * `payload.appId`. When absent (bridge case), behavior is bit-identical
+ * to pre-PRD-057.
+ */
+import type { EventBus } from '../ports/event-bus.js';
+import type { InvocationSignature, AccountId, ProviderClass } from '@methodts/types';
+import type { AppId } from './rate-governor-impl.js';
+export type CostEventType = 'cost.observation_recorded' | 'cost.rate_limited' | 'cost.estimate_emitted' | 'cost.prediction_diverged' | 'cost.slot_leaked' | 'cost.integrity_violation' | 'cost.observations_corrupted' | 'cost.clock_discontinuity' | 'cost.account_saturated' | 'cost.observation_parse_error';
+export declare function emitObservationRecorded(bus: EventBus, payload: {
+    signature: InvocationSignature;
+    costUsd: number;
+    durationMs: number;
+    accountId: AccountId;
+    appId?: AppId;
+    correlationId?: string;
+}): void;
+export declare function emitRateLimited(bus: EventBus, payload: {
+    accountId: AccountId;
+    providerClass: ProviderClass;
+    appId?: AppId;
+    retryAfterMs?: number;
+    correlationId?: string;
+}): void;
+export declare function emitEstimateEmitted(bus: EventBus, payload: {
+    strategyId: string;
+    totalCostP50Usd: number;
+    totalCostP90Usd: number;
+    durationMsP50: number;
+    confidence: 'low' | 'medium' | 'high';
+    appId?: AppId;
+    correlationId?: string;
+}): void;
+export declare function emitSlotLeaked(bus: EventBus, payload: {
+    slotId: string;
+    accountId: AccountId;
+    ageMs: number;
+    appId?: AppId;
+}): void;
+export declare function emitAccountSaturated(bus: EventBus, payload: {
+    accountId: AccountId;
+    providerClass: ProviderClass;
+    window: 'burst' | 'weekly';
+    usedPct: number;
+    appId?: AppId;
+}): void;
+export declare function emitIntegrityViolation(bus: EventBus, payload: {
+    lineNumber: number;
+    reason: string;
+    appId?: AppId;
+}): void;
+export declare function emitObservationsCorrupted(bus: EventBus, payload: {
+    renamedTo: string;
+    recordsLoaded: number;
+    recordsSkipped: number;
+    appId?: AppId;
+}): void;
+//# sourceMappingURL=cost-events.d.ts.map

package/dist/cost-governor/cost-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-events.d.ts","sourceRoot":"","sources":["../../src/cost-governor/cost-events.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAqB,MAAM,uBAAuB,CAAC;AACzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAIrD,MAAM,MAAM,aAAa,GACrB,2BAA2B,GAC3B,mBAAmB,GACnB,uBAAuB,GACvB,0BAA0B,GAC1B,kBAAkB,GAClB,0BAA0B,GAC1B,6BAA6B,GAC7B,0BAA0B,GAC1B,wBAAwB,GACxB,8BAA8B,CAAC;AAEnC,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE;IACP,SAAS,EAAE,mBAAmB,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,SAAS,CAAC;IACrB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GACA,IAAI,CAEN;AAED,wBAAgB,eAAe,CAC7B,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE;IACP,SAAS,EAAE,SAAS,CAAC;IACrB,aAAa,EAAE,aAAa,CAAC;IAC7B,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GACA,IAAI,CAEN;AAED,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE;IACP,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACtC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GACA,IAAI,CAEN;AAED,wBAAgB,cAAc,CAC5B,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,GAC9E,IAAI,CAEN;AAED,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE;IACP,SAAS,EAAE,SAAS,CAAC;IACrB,aAAa,EAAE,aAAa,CAAC;IAC7B,MAAM,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf,GACA,IAAI,CAEN;AAED,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,GAC7D,IAAI,CAEN;AAED,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE;IACP,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf,GACA,IAAI,CAEN"}

package/dist/cost-governor/cost-events.js

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Cost telemetry event types + emit helpers.
+ *
+ * All cost events carry domain='cost' on the Universal Event Bus.
+ * The accountId field is included for forward-compatibility with
+ * multi-account routing — currently always 'default'.
+ *
+ * PRD-057 / S2 §8: Each emitter accepts an optional `appId` field. When
+ * present (agent-runtime / Cortex case), the emitted RuntimeEvent carries
+ * `payload.appId`. When absent (bridge case), behavior is bit-identical
+ * to pre-PRD-057.
+ */
+const SOURCE = 'runtime/cost-governor';
+export function emitObservationRecorded(bus, payload) {
+    emit(bus, 'cost.observation_recorded', 'info', payload, payload.correlationId);
+}
+export function emitRateLimited(bus, payload) {
+    emit(bus, 'cost.rate_limited', 'warning', payload, payload.correlationId);
+}
+export function emitEstimateEmitted(bus, payload) {
+    emit(bus, 'cost.estimate_emitted', 'info', payload, payload.correlationId);
+}
+export function emitSlotLeaked(bus, payload) {
+    emit(bus, 'cost.slot_leaked', 'error', payload);
+}
+export function emitAccountSaturated(bus, payload) {
+    emit(bus, 'cost.account_saturated', 'warning', payload);
+}
+export function emitIntegrityViolation(bus, payload) {
+    emit(bus, 'cost.integrity_violation', 'error', payload);
+}
+export function emitObservationsCorrupted(bus, payload) {
+    emit(bus, 'cost.observations_corrupted', 'error', payload);
+}
+// ── Internal emit helper ────────────────────────────────────────
+function emit(bus, type, severity, payload, correlationId) {
+    bus.emit({
+        version: 1,
+        domain: 'cost',
+        type,
+        severity,
+        payload,
+        source: SOURCE,
+        correlationId,
+    });
+}
+//# sourceMappingURL=cost-events.js.map

package/dist/cost-governor/cost-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-events.js","sourceRoot":"","sources":["../../src/cost-governor/cost-events.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC;;;;;;;;;;;GAWG;AAMH,MAAM,MAAM,GAAG,uBAAuB,CAAC;AAcvC,MAAM,UAAU,uBAAuB,CACrC,GAAa,EACb,OAOC;IAED,IAAI,CAAC,GAAG,EAAE,2BAA2B,EAAE,MAAM,EAAE,OAAkC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;AAC5G,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,GAAa,EACb,OAMC;IAED,IAAI,CAAC,GAAG,EAAE,mBAAmB,EAAE,SAAS,EAAE,OAAkC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;AACvG,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,GAAa,EACb,OAQC;IAED,IAAI,CAAC,GAAG,EAAE,uBAAuB,EAAE,MAAM,EAAE,OAAkC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;AACxG,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,GAAa,EACb,OAA+E;IAE/E,IAAI,CAAC,GAAG,EAAE,kBAAkB,EAAE,OAAO,EAAE,OAAkC,CAAC,CAAC;AAC7E,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,GAAa,EACb,OAMC;IAED,IAAI,CAAC,GAAG,EAAE,wBAAwB,EAAE,SAAS,EAAE,OAAkC,CAAC,CAAC;AACrF,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,GAAa,EACb,OAA8D;IAE9D,IAAI,CAAC,GAAG,EAAE,0BAA0B,EAAE,OAAO,EAAE,OAAkC,CAAC,CAAC;AACrF,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,GAAa,EACb,OAKC;IAED,IAAI,CAAC,GAAG,EAAE,6BAA6B,EAAE,OAAO,EAAE,OAAkC,CAAC,CAAC;AACxF,CAAC;AAED,mEAAmE;AAEnE,SAAS,IAAI,CACX,GAAa,EACb,IAAmB,EACnB,QAAuC,EACvC,OAAgC,EAChC,aAAsB;IAEtB,GAAG,CAAC,IAAI,CAAC;QACP,OAAO,EAAE,CAAC;QACV,MAAM,EAAE,MAAM;QACd,IAAI;QACJ,QAAQ;QACR,OAAO;QACP,MAAM,EAAE,MAAM;QACd,aAAa;KACd,CAAC,CAAC;AACL,CAAC"}

package/dist/cost-governor/cost-governor-app-id.test.d.ts

@@ -0,0 +1,19 @@
+/**
+ * PRD-057 / S2 §8 / G-COSTGOV-APP-ID gate test.
+ *
+ * Verifies that:
+ *
+ *   1. `createCostGovernor` accepts an optional `appId` option.
+ *   2. Emitted `cost.*` events carry `payload.appId` when set, and
+ *      omit it when not set.
+ *   3. `rateGovernor.utilization()` supports the scope-filter form
+ *      `utilization(providerClass, appId)`.
+ *   4. The `appId`-absent path behaves bit-identically to before:
+ *      no surprise payload keys, no slot-routing changes.
+ *
+ * These are *additive* assertions — they do NOT replace or mutate the
+ * existing observations-store.test.ts / rate-governor-impl.test.ts
+ * coverage (which is intentionally unchanged per PRD §9.4).
+ */
+export {};
+//# sourceMappingURL=cost-governor-app-id.test.d.ts.map

package/dist/cost-governor/cost-governor-app-id.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-governor-app-id.test.d.ts","sourceRoot":"","sources":["../../src/cost-governor/cost-governor-app-id.test.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;GAgBG"}

package/dist/cost-governor/cost-governor-app-id.test.js

@@ -0,0 +1,201 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * PRD-057 / S2 §8 / G-COSTGOV-APP-ID gate test.
+ *
+ * Verifies that:
+ *
+ *   1. `createCostGovernor` accepts an optional `appId` option.
+ *   2. Emitted `cost.*` events carry `payload.appId` when set, and
+ *      omit it when not set.
+ *   3. `rateGovernor.utilization()` supports the scope-filter form
+ *      `utilization(providerClass, appId)`.
+ *   4. The `appId`-absent path behaves bit-identically to before:
+ *      no surprise payload keys, no slot-routing changes.
+ *
+ * These are *additive* assertions — they do NOT replace or mutate the
+ * existing observations-store.test.ts / rate-governor-impl.test.ts
+ * coverage (which is intentionally unchanged per PRD §9.4).
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createCostGovernor } from './index.js';
+// ── In-memory event bus that records emitted events ─────────────
+function createRecordingBus() {
+    const events = [];
+    let seq = 0;
+    const sinks = [];
+    const bus = {
+        emit(input) {
+            const event = {
+                ...input,
+                id: `ev-${++seq}`,
+                timestamp: new Date().toISOString(),
+                sequence: seq,
+            };
+            events.push(event);
+            for (const sink of sinks)
+                sink.onEvent(event);
+            return event;
+        },
+        importEvent(event) {
+            events.push(event);
+        },
+        subscribe() {
+            return { unsubscribe() { } };
+        },
+        query() {
+            return [...events];
+        },
+        registerSink(sink) {
+            sinks.push(sink);
+        },
+    };
+    return { bus, events };
+}
+// ── Minimal in-memory FileSystemProvider (matches MemFs in other tests) ──
+class MemFs {
+    files = new Map();
+    dirs = new Set();
+    readFileSync(path) {
+        const content = this.files.get(path);
+        if (content === undefined)
+            throw new Error(`ENOENT: ${path}`);
+        return content;
+    }
+    writeFileSync(path, content) {
+        this.files.set(path, content);
+    }
+    existsSync(path) {
+        return this.files.has(path) || this.dirs.has(path);
+    }
+    readdirSync(_path, options) {
+        return options?.withFileTypes ? [] : [];
+    }
+    statSync(_path) {
+        throw new Error('not implemented');
+    }
+    unlinkSync(path) {
+        this.files.delete(path);
+    }
+    mkdirSync(path) {
+        this.dirs.add(path);
+    }
+    renameSync(oldPath, newPath) {
+        const content = this.files.get(oldPath);
+        if (content !== undefined) {
+            this.files.set(newPath, content);
+            this.files.delete(oldPath);
+        }
+    }
+    realpathSync(path) { return path; }
+    async readFile(path) { return this.readFileSync(path); }
+    async writeFile(path, content) { this.writeFileSync(path, content); }
+    async appendFile(path, content) {
+        const existing = this.files.get(path) ?? '';
+        this.files.set(path, existing + content);
+    }
+    async readdir(_path) { return []; }
+    async stat(_path) { throw new Error('not implemented'); }
+    async access(_path) { }
+    async mkdir(path) { this.dirs.add(path); }
+}
+// ── Tests ───────────────────────────────────────────────────────
+describe('createCostGovernor — per-AppId hook (PRD-057 / S2 §8)', () => {
+    it('no appId: governor exposes appId=undefined and emits events without payload.appId', () => {
+        const { bus } = createRecordingBus();
+        const fs = new MemFs();
+        const governor = createCostGovernor({
+            eventBus: bus,
+            fileSystem: fs,
+            config: { dataDir: '/data', hmacSecret: 'test' },
+        });
+        assert.equal(governor.appId, undefined);
+        assert.equal(governor.rateGovernor.getAppId(), undefined);
+        assert.equal(governor.sweepLeakedSlots(), 0);
+        // Utilization without filter — single entry.
+        const util = governor.rateGovernor.utilization('claude-cli');
+        assert.equal(util.length, 1);
+        // Utilization with filter: any appId filter on a no-scope governor
+        // returns empty (scope miss).
+        const filtered = governor.rateGovernor.utilization('claude-cli', 'app-x');
+        assert.equal(filtered.length, 0);
+    });
+    it('with appId: governor exposes appId and scoped utilization matches', () => {
+        const { bus } = createRecordingBus();
+        const fs = new MemFs();
+        const appId = 'tenant-42';
+        const governor = createCostGovernor({
+            eventBus: bus,
+            fileSystem: fs,
+            config: { dataDir: '/data', hmacSecret: 'test' },
+            appId,
+        });
+        assert.equal(governor.appId, appId);
+        assert.equal(governor.rateGovernor.getAppId(), appId);
+        // Matching filter — returns the account row.
+        const matching = governor.rateGovernor.utilization('claude-cli', appId);
+        assert.equal(matching.length, 1);
+        // Non-matching filter — empty.
+        const nonMatching = governor.rateGovernor.utilization('claude-cli', 'other-tenant');
+        assert.equal(nonMatching.length, 0);
+        // Unfiltered — still returns the account row.
+        const unfiltered = governor.rateGovernor.utilization('claude-cli');
+        assert.equal(unfiltered.length, 1);
+    });
+    it('with appId: sweepLeakedSlots emits cost.slot_leaked with payload.appId', () => {
+        const { bus, events } = createRecordingBus();
+        const fs = new MemFs();
+        const appId = 'tenant-77';
+        const governor = createCostGovernor({
+            eventBus: bus,
+            fileSystem: fs,
+            config: { dataDir: '/data', hmacSecret: 'test' },
+            appId,
+        });
+        // Manually inject a stale slot so sweep has something to emit.
+        // We bypass the normal acquire path to avoid needing a full signature
+        // fixture — the assertion target is the emitted payload.
+        const rg = governor.rateGovernor;
+        rg.active.set('stale', {
+            slot: {
+                slotId: 'stale',
+                providerClass: 'claude-cli',
+                accountId: 'default',
+                acquiredAt: Date.now() - 120_000,
+                estimatedCostUsd: 0,
+                maxLifetimeMs: 60_000,
+            },
+        });
+        const leaked = governor.sweepLeakedSlots();
+        assert.equal(leaked, 1);
+        const slotLeakedEvents = events.filter(e => e.type === 'cost.slot_leaked');
+        assert.equal(slotLeakedEvents.length, 1);
+        assert.equal(slotLeakedEvents[0].payload.appId, appId);
+        assert.equal(slotLeakedEvents[0].source, 'runtime/cost-governor');
+    });
+    it('no appId: cost.slot_leaked events omit payload.appId', () => {
+        const { bus, events } = createRecordingBus();
+        const fs = new MemFs();
+        const governor = createCostGovernor({
+            eventBus: bus,
+            fileSystem: fs,
+            config: { dataDir: '/data', hmacSecret: 'test' },
+        });
+        const rg = governor.rateGovernor;
+        rg.active.set('stale', {
+            slot: {
+                slotId: 'stale',
+                providerClass: 'claude-cli',
+                accountId: 'default',
+                acquiredAt: Date.now() - 120_000,
+                estimatedCostUsd: 0,
+                maxLifetimeMs: 60_000,
+            },
+        });
+        governor.sweepLeakedSlots();
+        const slotLeakedEvents = events.filter(e => e.type === 'cost.slot_leaked');
+        assert.equal(slotLeakedEvents.length, 1);
+        assert.ok(!('appId' in slotLeakedEvents[0].payload), 'no-appId governor must not emit payload.appId');
+    });
+});
+//# sourceMappingURL=cost-governor-app-id.test.js.map

package/dist/cost-governor/cost-governor-app-id.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-governor-app-id.test.js","sourceRoot":"","sources":["../../src/cost-governor/cost-governor-app-id.test.ts"],"names":[],"mappings":"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"}

package/dist/cost-governor/cost-oracle-impl.d.ts

@@ -0,0 +1,19 @@
+/**
+ * CostOracle implementation backed by HistoricalObservations.
+ *
+ * Computes p50/p90 bands per-signature from observation history.
+ * Delegates DAG walking to estimator.ts.
+ */
+import type { InvocationSignature } from '@methodts/types';
+import type { CostOracle, StrategyEstimate } from '../ports/cost-oracle.js';
+import type { HistoricalObservations } from '../ports/historical-observations.js';
+export declare class HistogramCostOracle implements CostOracle {
+    private readonly history;
+    private readonly onRecord?;
+    constructor(history: HistoricalObservations, onRecord?: ((sig: InvocationSignature, costUsd: number, durationMs: number, accountId: string) => void) | undefined);
+    estimateStrategy(nodeSignatures: ReadonlyMap<string, InvocationSignature>, dagEdges: ReadonlyMap<string, readonly string[]>): StrategyEstimate;
+    /** Internal: look up p50/p90 for a single signature. */
+    private estimateSignature;
+    record(sig: InvocationSignature, actualCostUsd: number, actualDurationMs: number, accountId: string): void;
+}
+//# sourceMappingURL=cost-oracle-impl.d.ts.map

package/dist/cost-governor/cost-oracle-impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-oracle-impl.d.ts","sourceRoot":"","sources":["../../src/cost-governor/cost-oracle-impl.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAY,MAAM,iBAAiB,CAAC;AACrE,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAIlF,qBAAa,mBAAoB,YAAW,UAAU;IAElD,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBADT,OAAO,EAAE,sBAAsB,EAC/B,QAAQ,CAAC,GAAE,CAC1B,GAAG,EAAE,mBAAmB,EACxB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,KACd,IAAI,aAAA;IAGX,gBAAgB,CACd,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACxD,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,GAC/C,gBAAgB;IAMnB,wDAAwD;IACxD,OAAO,CAAC,iBAAiB;IA+BzB,MAAM,CACJ,GAAG,EAAE,mBAAmB,EACxB,aAAa,EAAE,MAAM,EACrB,gBAAgB,EAAE,MAAM,EACxB,SAAS,EAAE,MAAM,GAChB,IAAI;CAMR"}

package/dist/cost-governor/cost-oracle-impl.js

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CostOracle implementation backed by HistoricalObservations.
+ *
+ * Computes p50/p90 bands per-signature from observation history.
+ * Delegates DAG walking to estimator.ts.
+ */
+import { computeBands } from './percentile.js';
+import { estimateStrategy as walkDag } from './estimator.js';
+export class HistogramCostOracle {
+    history;
+    onRecord;
+    constructor(history, onRecord) {
+        this.history = history;
+        this.onRecord = onRecord;
+    }
+    estimateStrategy(nodeSignatures, dagEdges) {
+        return walkDag(nodeSignatures, dagEdges, (sig) => this.estimateSignature(sig));
+    }
+    /** Internal: look up p50/p90 for a single signature. */
+    estimateSignature(sig) {
+        const obs = this.history.query(sig);
+        if (obs.length === 0)
+            return null;
+        const costs = obs.map((o) => o.costUsd);
+        const durations = obs.map((o) => o.durationMs);
+        const costBands = computeBands(costs);
+        const durationBands = computeBands(durations);
+        const confidence = obs.length >= 20 ? 'high' : obs.length >= 5 ? 'medium' : 'low';
+        return {
+            cost: {
+                p50Usd: costBands.p50,
+                p90Usd: costBands.p90,
+                sampleCount: obs.length,
+                confidence,
+            },
+            durationMs: {
+                p50Usd: durationBands.p50,
+                p90Usd: durationBands.p90,
+                sampleCount: obs.length,
+                confidence,
+            },
+        };
+    }
+    record(sig, actualCostUsd, actualDurationMs, accountId) {
+        // The actual observation storage happens via HistoricalObservations.append()
+        // (called by the RateGovernor releaseSlot flow with AppendToken).
+        // This method is a side-channel hook for CostOracle consumers.
+        this.onRecord?.(sig, actualCostUsd, actualDurationMs, accountId);
+    }
+}
+//# sourceMappingURL=cost-oracle-impl.js.map

package/dist/cost-governor/cost-oracle-impl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-oracle-impl.js","sourceRoot":"","sources":["../../src/cost-governor/cost-oracle-impl.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC;;;;;GAKG;AAKH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,gBAAgB,IAAI,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAE7D,MAAM,OAAO,mBAAmB;IAEX;IACA;IAFnB,YACmB,OAA+B,EAC/B,QAKR;QANQ,YAAO,GAAP,OAAO,CAAwB;QAC/B,aAAQ,GAAR,QAAQ,CAKhB;IACR,CAAC;IAEJ,gBAAgB,CACd,cAAwD,EACxD,QAAgD;QAEhD,OAAO,OAAO,CAAC,cAAc,EAAE,QAAQ,EAAE,CAAC,GAAG,EAAE,EAAE,CAC/C,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAC5B,CAAC;IACJ,CAAC;IAED,wDAAwD;IAChD,iBAAiB,CACvB,GAAwB;QAExB,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAElC,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QACxC,MAAM,SAAS,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QAE/C,MAAM,SAAS,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;QACtC,MAAM,aAAa,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;QAE9C,MAAM,UAAU,GACd,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC;QAEjE,OAAO;YACL,IAAI,EAAE;gBACJ,MAAM,EAAE,SAAS,CAAC,GAAG;gBACrB,MAAM,EAAE,SAAS,CAAC,GAAG;gBACrB,WAAW,EAAE,GAAG,CAAC,MAAM;gBACvB,UAAU;aACX;YACD,UAAU,EAAE;gBACV,MAAM,EAAE,aAAa,CAAC,GAAG;gBACzB,MAAM,EAAE,aAAa,CAAC,GAAG;gBACzB,WAAW,EAAE,GAAG,CAAC,MAAM;gBACvB,UAAU;aACX;SACF,CAAC;IACJ,CAAC;IAED,MAAM,CACJ,GAAwB,EACxB,aAAqB,EACrB,gBAAwB,EACxB,SAAiB;QAEjB,6EAA6E;QAC7E,kEAAkE;QAClE,+DAA+D;QAC/D,IAAI,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,aAAa,EAAE,gBAAgB,EAAE,SAAS,CAAC,CAAC;IACnE,CAAC;CACF"}

package/dist/cost-governor/estimator.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Critical-Path DAG Estimator — computes total cost/duration
+ * via the longest path through a DAG with parallelism discount.
+ */
+import type { InvocationSignature, CostBand } from '@methodts/types';
+import type { StrategyEstimate } from '../ports/cost-oracle.js';
+export interface SignatureEstimator {
+    (sig: InvocationSignature): {
+        cost: CostBand;
+        durationMs: CostBand;
+    } | null;
+}
+export declare function heuristicEstimate(sig: InvocationSignature): CostBand;
+/**
+ * Estimate a full strategy DAG.
+ *
+ * @param nodeSignatures - Map of nodeId -> InvocationSignature
+ * @param dagEdges - Map of nodeId -> list of dependency nodeIds
+ * @param estimateSignature - Lookup function for historical data
+ */
+export declare function estimateStrategy(nodeSignatures: ReadonlyMap<string, InvocationSignature>, dagEdges: ReadonlyMap<string, readonly string[]>, estimateSignature: SignatureEstimator): StrategyEstimate;
+//# sourceMappingURL=estimator.d.ts.map

package/dist/cost-governor/estimator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"estimator.d.ts","sourceRoot":"","sources":["../../src/cost-governor/estimator.ts"],"names":[],"mappings":"AACA;;;GAGG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,KAAK,EAAgB,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE9E,MAAM,WAAW,kBAAkB;IACjC,CAAC,GAAG,EAAE,mBAAmB,GAAG;QAAE,IAAI,EAAE,QAAQ,CAAC;QAAC,UAAU,EAAE,QAAQ,CAAA;KAAE,GAAG,IAAI,CAAC;CAC7E;AAWD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,mBAAmB,GAAG,QAAQ,CASpE;AAaD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACxD,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,EAChD,iBAAiB,EAAE,kBAAkB,GACpC,gBAAgB,CA0FlB"}

package/dist/cost-governor/estimator.js

@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Critical-Path DAG Estimator — computes total cost/duration
+ * via the longest path through a DAG with parallelism discount.
+ */
+/** Minimum cost floor — prevents zero-cost bypass. */
+const COST_FLOOR_USD = 0.02;
+const DURATION_FLOOR_MS = 5_000;
+/** Empty-history heuristic: $0.05 default, scaled by size bucket. */
+const SIZE_MULTIPLIERS = {
+    xs: 0.5, s: 1.0, m: 2.0, l: 5.0, xl: 10.0,
+};
+export function heuristicEstimate(sig) {
+    const mult = SIZE_MULTIPLIERS[sig.inputSizeBucket] ?? 1.0;
+    const base = 0.05 * mult;
+    return {
+        p50Usd: Math.max(base, COST_FLOOR_USD),
+        p90Usd: Math.max(base * 2, COST_FLOOR_USD),
+        sampleCount: 0,
+        confidence: 'low',
+    };
+}
+function heuristicDuration(sig) {
+    const mult = SIZE_MULTIPLIERS[sig.inputSizeBucket] ?? 1.0;
+    const base = 30_000 * mult;
+    return {
+        p50Usd: Math.max(base, DURATION_FLOOR_MS), // reusing CostBand shape for duration
+        p90Usd: Math.max(base * 2, DURATION_FLOOR_MS),
+        sampleCount: 0,
+        confidence: 'low',
+    };
+}
+/**
+ * Estimate a full strategy DAG.
+ *
+ * @param nodeSignatures - Map of nodeId -> InvocationSignature
+ * @param dagEdges - Map of nodeId -> list of dependency nodeIds
+ * @param estimateSignature - Lookup function for historical data
+ */
+export function estimateStrategy(nodeSignatures, dagEdges, estimateSignature) {
+    const nodes = [];
+    const unknownNodes = [];
+    // Estimate each node
+    const nodeEstimates = new Map();
+    for (const [nodeId, sig] of nodeSignatures) {
+        const est = estimateSignature(sig);
+        const cost = est?.cost ?? heuristicEstimate(sig);
+        const durationMs = est?.durationMs ?? heuristicDuration(sig);
+        if (!est)
+            unknownNodes.push(nodeId);
+        // Enforce floor
+        const flooredCost = {
+            ...cost,
+            p50Usd: Math.max(cost.p50Usd, COST_FLOOR_USD),
+            p90Usd: Math.max(cost.p90Usd, COST_FLOOR_USD),
+        };
+        const ne = { nodeId, signature: sig, cost: flooredCost, durationMs };
+        nodes.push(ne);
+        nodeEstimates.set(nodeId, ne);
+    }
+    // Critical-path computation: longest duration path through DAG
+    // Total cost = sum of all nodes (all must execute)
+    // Total duration = critical path (longest chain accounting for parallelism)
+    const memo = new Map();
+    function longestPath(nodeId) {
+        if (memo.has(nodeId))
+            return memo.get(nodeId);
+        const est = nodeEstimates.get(nodeId);
+        const selfDuration = est ? est.durationMs.p50Usd : DURATION_FLOOR_MS;
+        const deps = dagEdges.get(nodeId) ?? [];
+        let maxDepDuration = 0;
+        for (const dep of deps) {
+            maxDepDuration = Math.max(maxDepDuration, longestPath(dep));
+        }
+        const total = selfDuration + maxDepDuration;
+        memo.set(nodeId, total);
+        return total;
+    }
+    // Find all leaf nodes (nodes that no other node depends on)
+    const allDeps = new Set();
+    for (const deps of dagEdges.values()) {
+        for (const d of deps)
+            allDeps.add(d);
+    }
+    const leafNodes = [...nodeSignatures.keys()].filter(n => !allDeps.has(n));
+    // If no leaves found (possible with empty DAG), use all nodes
+    const roots = leafNodes.length > 0 ? leafNodes : [...nodeSignatures.keys()];
+    let criticalPathMs = 0;
+    for (const root of roots) {
+        criticalPathMs = Math.max(criticalPathMs, longestPath(root));
+    }
+    // Sum total cost across all nodes
+    let totalP50 = 0;
+    let totalP90 = 0;
+    for (const ne of nodes) {
+        totalP50 += ne.cost.p50Usd;
+        totalP90 += ne.cost.p90Usd;
+    }
+    // Determine overall confidence
+    const minSamples = Math.min(...nodes.map(n => n.cost.sampleCount));
+    const confidence = minSamples >= 20 ? 'high' : minSamples >= 5 ? 'medium' : 'low';
+    return {
+        nodes,
+        totalCost: {
+            p50Usd: totalP50,
+            p90Usd: totalP90,
+            sampleCount: minSamples,
+            confidence,
+        },
+        totalDurationMs: {
+            p50Usd: criticalPathMs,
+            p90Usd: criticalPathMs * 1.5, // rough p90 estimate
+            sampleCount: minSamples,
+            confidence,
+        },
+        unknownNodes,
+    };
+}
+//# sourceMappingURL=estimator.js.map