@vauban-org/agent-sdk 0.16.0

package/dist/testing/brain-conformance.d.ts

@@ -0,0 +1,45 @@
+/**
+ * BrainPort conformance suite.
+ *
+ * Asserts a concrete BrainPort impl honours the contract:
+ *   - archiveKnowledge returns an entry-like object or null; never throws
+ *     on server validation failure (throws only for network/auth errors).
+ *   - queryKnowledge (when present) returns an array; empty array for no
+ *     matches, never null.
+ *   - Multiple archiveKnowledge calls with the same content are accepted;
+ *     the impl may de-dupe but must not reject on repeat.
+ */
+import type { BrainPort } from "../ports/brain.js";
+import type { ConformanceRunner } from "./runner.js";
+export interface BrainConformanceConfig {
+    describe: ConformanceRunner["describe"];
+    it: ConformanceRunner["it"];
+    expect: (actual: unknown) => {
+        toBeDefined(): void;
+        toBeNull(): void;
+        toBeTruthy(): void;
+        toBe(expected: unknown): void;
+        toEqual(expected: unknown): void;
+        toBeInstanceOf(cls: unknown): void;
+        toHaveProperty(key: string): void;
+        toBeGreaterThanOrEqual(n: number): void;
+        not: {
+            toBe(expected: unknown): void;
+            toBeNull(): void;
+            toThrow(): void;
+        };
+        [key: string]: any;
+    };
+    /**
+     * Async factory returning a fresh BrainPort for each test case.
+     * Use this to isolate state between tests.
+     */
+    factory: () => Promise<BrainPort> | BrainPort;
+    /**
+     * Optional tag applied to all archived entries (so the host can clean
+     * up after the suite runs). Defaults to "conformance-test".
+     */
+    testTag?: string;
+}
+export declare function brainPortConformance(config: BrainConformanceConfig): void;
+//# sourceMappingURL=brain-conformance.d.ts.map

package/dist/testing/brain-conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-conformance.d.ts","sourceRoot":"","sources":["../../src/testing/brain-conformance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC;IACxC,EAAE,EAAE,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK;QAC3B,WAAW,IAAI,IAAI,CAAC;QACpB,QAAQ,IAAI,IAAI,CAAC;QACjB,UAAU,IAAI,IAAI,CAAC;QACnB,IAAI,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;QAC9B,OAAO,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;QACjC,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;QACnC,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAClC,sBAAsB,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACxC,GAAG,EAAE;YACH,IAAI,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;YAC9B,QAAQ,IAAI,IAAI,CAAC;YACjB,OAAO,IAAI,IAAI,CAAC;SACjB,CAAC;QAEF,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;KACpB,CAAC;IACF;;;OAGG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,GAAG,SAAS,CAAC;IAC9C;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAyDzE"}

package/dist/testing/brain-conformance.js

@@ -0,0 +1,68 @@
+/**
+ * BrainPort conformance suite.
+ *
+ * Asserts a concrete BrainPort impl honours the contract:
+ *   - archiveKnowledge returns an entry-like object or null; never throws
+ *     on server validation failure (throws only for network/auth errors).
+ *   - queryKnowledge (when present) returns an array; empty array for no
+ *     matches, never null.
+ *   - Multiple archiveKnowledge calls with the same content are accepted;
+ *     the impl may de-dupe but must not reject on repeat.
+ */
+export function brainPortConformance(config) {
+    const { describe, it, expect, factory } = config;
+    const tag = config.testTag ?? "conformance-test";
+    describe("BrainPort conformance", () => {
+        it("archiveKnowledge returns an entry with an id on success", async () => {
+            const brain = await factory();
+            const result = await brain.archiveKnowledge({
+                content: "conformance — archive smoke",
+                category: "pattern",
+                tags: [tag],
+            });
+            if (result !== null) {
+                expect(result).toHaveProperty("id");
+                expect(typeof result.id).toBe("string");
+            }
+        });
+        it("archiveKnowledge returns null (not throws) on validation failure", async () => {
+            const brain = await factory();
+            // Empty content should either succeed or return null — never throw.
+            let threw = false;
+            try {
+                const result = await brain.archiveKnowledge({ content: "" });
+                // Acceptable outcomes: entry with id, or null.
+                if (result !== null) {
+                    expect(result).toHaveProperty("id");
+                }
+            }
+            catch {
+                threw = true;
+            }
+            expect(threw).toBe(false);
+        });
+        it("archiveKnowledge accepts repeated identical entries", async () => {
+            const brain = await factory();
+            const entry = {
+                content: `conformance-repeat-${Date.now()}`,
+                category: "pattern",
+                tags: [tag],
+            };
+            const r1 = await brain.archiveKnowledge(entry);
+            const r2 = await brain.archiveKnowledge(entry);
+            // Both calls must resolve without rejecting.
+            expect(r1 === null || typeof r1.id === "string").toBe(true);
+            expect(r2 === null || typeof r2.id === "string").toBe(true);
+        });
+        it("queryKnowledge (when present) returns an array", async () => {
+            const brain = await factory();
+            if (!brain.queryKnowledge)
+                return; // optional port method
+            const results = await brain.queryKnowledge("conformance test query", {
+                limit: 5,
+            });
+            expect(Array.isArray(results)).toBe(true);
+        });
+    });
+}
+//# sourceMappingURL=brain-conformance.js.map

package/dist/testing/brain-conformance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-conformance.js","sourceRoot":"","sources":["../../src/testing/brain-conformance.ts"],"names":[],"mappings":"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"}

package/dist/testing/chaos.d.ts

@@ -0,0 +1,126 @@
+/**
+ * @vauban-org/agent-sdk/testing/chaos — chaos harness (Sprint-475 / Sprint-477).
+ *
+ * Inject realistic failure patterns into a port impl to validate that
+ * agents + resilience primitives (circuit breaker, idempotent, bulkhead)
+ * behave correctly under adverse conditions. Not to be used in production.
+ *
+ * Public API (Sprint-477):
+ *   injectBrainFailure<P>(port, { failureRate, type? }) — BrainPort-aware wrapper
+ *   networkJitter<P>(port, { p99Ms, p50Ms? })           — latency injection
+ *   wholeCircuit<P>(port)                               — trips every call (half-open testing)
+ *   exhaustResources<P>(port, { maxCalls })             — throws after N calls
+ *
+ * Legacy API (Sprint-475 — kept for backward compat):
+ *   injectFailure<T>(impl, opts)  — generic failure injection
+ *   fullOutage<T>(impl, opts)     — rate=1 shorthand
+ *
+ * Usage (vitest):
+ *   import { injectBrainFailure, networkJitter } from "@vauban-org/agent-sdk/testing/chaos";
+ *   const flaky = injectBrainFailure(brain, { failureRate: 0.3, type: "rate-limit" });
+ *   const slow  = networkJitter(brain, { p99Ms: 500, p50Ms: 50 });
+ */
+import type { BrainPort } from "../ports/index.js";
+export type FailureType = "rate-limit" | "timeout" | "network" | "random" | "unavailable" | "error";
+export interface InjectFailureOptions {
+    /** 0..1 probability that a call fails instead of delegating. */
+    rate: number;
+    /**
+     * Optional factory that produces the Error to throw. Defaults based
+     * on `type` (rate-limit -> BrainRateLimit, else BrainUnavailable).
+     */
+    err?: () => Error;
+    /** Shortcut for common error types. */
+    type?: FailureType;
+    /** Optional PRNG (defaults to Math.random). Inject for deterministic tests. */
+    random?: () => number;
+}
+/**
+ * Wrap every function-valued method of `impl` so `rate` fraction of
+ * calls throw. Non-function properties pass through unchanged.
+ */
+export declare function injectFailure<T extends object>(impl: T, options: InjectFailureOptions): T;
+export interface NetworkJitterOptions {
+    /** Minimum delay per call, in ms. Default 0. */
+    minMs?: number;
+    /** Maximum delay per call, in ms. Default 100. */
+    maxMs?: number;
+    /**
+     * p99 latency in ms (Sprint-477 API). When set, models a log-normal
+     * distribution where ~99% of calls complete within p99Ms.
+     * If both legacy (minMs/maxMs) and new (p99Ms) options are provided,
+     * p99Ms takes precedence.
+     */
+    p99Ms?: number;
+    /**
+     * p50 (median) latency in ms. Only meaningful when p99Ms is set.
+     * Defaults to p99Ms / 10 (rough estimate for a log-normal dist).
+     */
+    p50Ms?: number;
+    /** Optional uniform PRNG for test determinism. */
+    random?: () => number;
+}
+/**
+ * Wrap every method so async calls settle after a random delay.
+ *
+ * Two usage modes:
+ *   networkJitter(port, { minMs: 10, maxMs: 100 })          — uniform [min,max]
+ *   networkJitter(port, { p99Ms: 500, p50Ms: 50 })          — log-normal percentile model
+ *
+ * Combined with bulkhead, proves queue stays bounded under slow backends.
+ */
+export declare function networkJitter<T extends object>(impl: T, options?: NetworkJitterOptions): T;
+export interface OutageOptions {
+    /** Error factory for every call. */
+    err?: () => Error;
+}
+/**
+ * Every call throws. Useful to probe "brain down" degradation paths —
+ * pairs with circuitBreaker to assert the breaker trips promptly.
+ */
+export declare function fullOutage<T extends object>(impl: T, options?: OutageOptions): T;
+export interface InjectBrainFailureOptions {
+    /** 0..1 probability that any call fails. */
+    failureRate: number;
+    /** Error type to inject. Default "rate-limit". */
+    type?: "rate-limit" | "timeout" | "network" | "random";
+    /** Optional PRNG for deterministic tests. */
+    random?: () => number;
+}
+/**
+ * BrainPort-specific chaos wrapper. Semantically equivalent to
+ * injectFailure but typed against BrainPort and uses BrainPort-aware
+ * defaults (rate-limit → BrainRateLimit instead of generic error).
+ *
+ * Usage:
+ *   const flaky = injectBrainFailure(brain, { failureRate: 0.3, type: "rate-limit" });
+ *   // Use in narrator tests to assert Brain-dependent steps are skipped.
+ */
+export declare function injectBrainFailure<P extends BrainPort>(port: P, opts: InjectBrainFailureOptions): P;
+/**
+ * Trips every call immediately (rate=1, BrainUnavailable). Designed for
+ * half-open testing: wrap the port BEFORE passing it to circuitBreaker,
+ * then advance the clock past resetAfterMs to trigger the HALF-OPEN probe.
+ *
+ *   const cb = circuitBreaker(wholeCircuit(brain).archiveKnowledge.bind(...), {
+ *     failureThreshold: 1,
+ *     resetAfterMs: 1_000,
+ *     now: () => clock,
+ *   });
+ */
+export declare function wholeCircuit<P extends object>(port: P): P;
+export interface ExhaustResourcesOptions {
+    /** Number of successful calls before throwing. */
+    maxCalls: number;
+    /** Error factory for calls past the limit. Default: BrainUnavailable. */
+    err?: () => Error;
+}
+/**
+ * Allow the first `maxCalls` invocations to succeed, then throw on
+ * every subsequent call. Simulates quota exhaustion or memory pressure.
+ *
+ * Counter is shared across all methods — useful to cap total call volume
+ * in property tests regardless of which method is invoked.
+ */
+export declare function exhaustResources<P extends object>(port: P, opts: ExhaustResourcesOptions): P;
+//# sourceMappingURL=chaos.d.ts.map

package/dist/testing/chaos.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chaos.d.ts","sourceRoot":"","sources":["../../src/testing/chaos.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,aAAa,GAAG,OAAO,CAAC;AAEpG,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,KAAK,CAAC;IAClB,uCAAuC;IACvC,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAC5C,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,oBAAoB,GAC5B,CAAC,CAiBH;AAwBD,MAAM,WAAW,oBAAoB;IACnC,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAC5C,IAAI,EAAE,CAAC,EACP,OAAO,GAAE,oBAAyB,GACjC,CAAC,CAkCH;AAID,MAAM,WAAW,aAAa;IAC5B,oCAAoC;IACpC,GAAG,CAAC,EAAE,MAAM,KAAK,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACzC,IAAI,EAAE,CAAC,EACP,OAAO,GAAE,aAAkB,GAC1B,CAAC,CAMH;AAID,MAAM,WAAW,yBAAyB;IACxC,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,IAAI,CAAC,EAAE,YAAY,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;IACvD,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,SAAS,EACpD,IAAI,EAAE,CAAC,EACP,IAAI,EAAE,yBAAyB,GAC9B,CAAC,CAMH;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAEzD;AAID,MAAM,WAAW,uBAAuB;IACtC,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,KAAK,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAC/C,IAAI,EAAE,CAAC,EACP,IAAI,EAAE,uBAAuB,GAC5B,CAAC,CAiBH"}

package/dist/testing/chaos.js

@@ -0,0 +1,176 @@
+/**
+ * @vauban-org/agent-sdk/testing/chaos — chaos harness (Sprint-475 / Sprint-477).
+ *
+ * Inject realistic failure patterns into a port impl to validate that
+ * agents + resilience primitives (circuit breaker, idempotent, bulkhead)
+ * behave correctly under adverse conditions. Not to be used in production.
+ *
+ * Public API (Sprint-477):
+ *   injectBrainFailure<P>(port, { failureRate, type? }) — BrainPort-aware wrapper
+ *   networkJitter<P>(port, { p99Ms, p50Ms? })           — latency injection
+ *   wholeCircuit<P>(port)                               — trips every call (half-open testing)
+ *   exhaustResources<P>(port, { maxCalls })             — throws after N calls
+ *
+ * Legacy API (Sprint-475 — kept for backward compat):
+ *   injectFailure<T>(impl, opts)  — generic failure injection
+ *   fullOutage<T>(impl, opts)     — rate=1 shorthand
+ *
+ * Usage (vitest):
+ *   import { injectBrainFailure, networkJitter } from "@vauban-org/agent-sdk/testing/chaos";
+ *   const flaky = injectBrainFailure(brain, { failureRate: 0.3, type: "rate-limit" });
+ *   const slow  = networkJitter(brain, { p99Ms: 500, p50Ms: 50 });
+ */
+import { BrainRateLimit, BrainUnavailable } from "../errors.js";
+/**
+ * Wrap every function-valued method of `impl` so `rate` fraction of
+ * calls throw. Non-function properties pass through unchanged.
+ */
+export function injectFailure(impl, options) {
+    const rand = options.random ?? Math.random;
+    const makeErr = options.err ?? defaultErrorFor(options.type ?? "error");
+    return new Proxy(impl, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof value !== "function")
+                return value;
+            return function (...args) {
+                if (rand() < options.rate) {
+                    const err = makeErr();
+                    return Promise.reject(err);
+                }
+                return value.apply(target, args);
+            };
+        },
+    });
+}
+function defaultErrorFor(type) {
+    if (type === "rate-limit")
+        return () => new BrainRateLimit({ retryAfterMs: 500 });
+    if (type === "unavailable")
+        return () => new BrainUnavailable();
+    if (type === "timeout")
+        return () => Object.assign(new Error("chaos: timeout"), { code: "ETIMEDOUT" });
+    if (type === "network")
+        return () => Object.assign(new Error("chaos: network error"), { code: "ECONNRESET" });
+    if (type === "random") {
+        const types = [
+            "rate-limit",
+            "unavailable",
+            "timeout",
+            "network",
+        ];
+        return () => defaultErrorFor(types[Math.floor(Math.random() * types.length)])();
+    }
+    return () => new Error("chaos: injected failure");
+}
+/**
+ * Wrap every method so async calls settle after a random delay.
+ *
+ * Two usage modes:
+ *   networkJitter(port, { minMs: 10, maxMs: 100 })          — uniform [min,max]
+ *   networkJitter(port, { p99Ms: 500, p50Ms: 50 })          — log-normal percentile model
+ *
+ * Combined with bulkhead, proves queue stays bounded under slow backends.
+ */
+export function networkJitter(impl, options = {}) {
+    const rand = options.random ?? Math.random;
+    function sampleDelayMs() {
+        if (options.p99Ms !== undefined) {
+            // Model via log-normal: solve for μ and σ so that
+            //   P50 = exp(μ) and P99 ≈ exp(μ + 2.326σ)
+            const p50 = options.p50Ms ?? options.p99Ms / 10;
+            const p99 = options.p99Ms;
+            // μ = ln(p50); σ = (ln(p99) - ln(p50)) / 2.326
+            const mu = Math.log(Math.max(p50, 1));
+            const sigma = (Math.log(Math.max(p99, p50 + 1)) - mu) / 2.326;
+            // Box-Muller transform for normal sample
+            const u1 = Math.max(rand(), 1e-10);
+            const u2 = rand();
+            const z = Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+            return Math.exp(mu + sigma * z);
+        }
+        const minMs = options.minMs ?? 0;
+        const maxMs = options.maxMs ?? 100;
+        return minMs + rand() * (maxMs - minMs);
+    }
+    return new Proxy(impl, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof value !== "function")
+                return value;
+            return async function (...args) {
+                const delay = sampleDelayMs();
+                await new Promise((r) => setTimeout(r, delay));
+                return value.apply(target, args);
+            };
+        },
+    });
+}
+/**
+ * Every call throws. Useful to probe "brain down" degradation paths —
+ * pairs with circuitBreaker to assert the breaker trips promptly.
+ */
+export function fullOutage(impl, options = {}) {
+    const makeErr = options.err ?? (() => new BrainUnavailable());
+    return injectFailure(impl, {
+        rate: 1,
+        err: makeErr,
+    });
+}
+/**
+ * BrainPort-specific chaos wrapper. Semantically equivalent to
+ * injectFailure but typed against BrainPort and uses BrainPort-aware
+ * defaults (rate-limit → BrainRateLimit instead of generic error).
+ *
+ * Usage:
+ *   const flaky = injectBrainFailure(brain, { failureRate: 0.3, type: "rate-limit" });
+ *   // Use in narrator tests to assert Brain-dependent steps are skipped.
+ */
+export function injectBrainFailure(port, opts) {
+    return injectFailure(port, {
+        rate: opts.failureRate,
+        type: opts.type ?? "rate-limit",
+        random: opts.random,
+    });
+}
+// ─── wholeCircuit ─────────────────────────────────────────────────────────
+/**
+ * Trips every call immediately (rate=1, BrainUnavailable). Designed for
+ * half-open testing: wrap the port BEFORE passing it to circuitBreaker,
+ * then advance the clock past resetAfterMs to trigger the HALF-OPEN probe.
+ *
+ *   const cb = circuitBreaker(wholeCircuit(brain).archiveKnowledge.bind(...), {
+ *     failureThreshold: 1,
+ *     resetAfterMs: 1_000,
+ *     now: () => clock,
+ *   });
+ */
+export function wholeCircuit(port) {
+    return fullOutage(port);
+}
+/**
+ * Allow the first `maxCalls` invocations to succeed, then throw on
+ * every subsequent call. Simulates quota exhaustion or memory pressure.
+ *
+ * Counter is shared across all methods — useful to cap total call volume
+ * in property tests regardless of which method is invoked.
+ */
+export function exhaustResources(port, opts) {
+    const makeErr = opts.err ?? (() => new BrainUnavailable());
+    let callCount = 0;
+    return new Proxy(port, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof value !== "function")
+                return value;
+            return function (...args) {
+                callCount += 1;
+                if (callCount > opts.maxCalls) {
+                    return Promise.reject(makeErr());
+                }
+                return value.apply(target, args);
+            };
+        },
+    });
+}
+//# sourceMappingURL=chaos.js.map

package/dist/testing/chaos.js.map

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

package/dist/testing/contracts/brain-port.contract.d.ts

@@ -0,0 +1,23 @@
+/**
+ * BrainPort contract test suite.
+ *
+ * Forge adapters (PostgresBrainAdapter) run this suite to validate
+ * semantic correctness, not just type conformance.
+ *
+ * Usage in Forge:
+ * ```typescript
+ * import { brainPortContract } from "@vauban-org/agent-sdk/testing/contracts";
+ * brainPortContract(async () => {
+ *   const port = new PostgresBrainAdapter(testPool);
+ *   return { port, cleanup: () => testPool.end() };
+ * });
+ * ```
+ *
+ * @public
+ */
+import type { BrainPort } from "../../ports/brain.js";
+export declare function brainPortContract(factory: () => Promise<{
+    port: BrainPort;
+    cleanup(): Promise<void>;
+}>): void;
+//# sourceMappingURL=brain-port.contract.d.ts.map

package/dist/testing/contracts/brain-port.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-port.contract.d.ts","sourceRoot":"","sources":["../../../src/testing/contracts/brain-port.contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,OAAO,CAAC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,GACpE,IAAI,CAmEN"}

package/dist/testing/contracts/brain-port.contract.js

@@ -0,0 +1,79 @@
+/**
+ * BrainPort contract test suite.
+ *
+ * Forge adapters (PostgresBrainAdapter) run this suite to validate
+ * semantic correctness, not just type conformance.
+ *
+ * Usage in Forge:
+ * ```typescript
+ * import { brainPortContract } from "@vauban-org/agent-sdk/testing/contracts";
+ * brainPortContract(async () => {
+ *   const port = new PostgresBrainAdapter(testPool);
+ *   return { port, cleanup: () => testPool.end() };
+ * });
+ * ```
+ *
+ * @public
+ */
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+export function brainPortContract(factory) {
+    let port;
+    let cleanup;
+    beforeAll(async () => {
+        const result = await factory();
+        port = result.port;
+        cleanup = result.cleanup;
+    });
+    afterAll(async () => {
+        await cleanup();
+    });
+    describe("BrainPort contract", () => {
+        it("archives and retrieves knowledge", async () => {
+            const entry = await port.archiveKnowledge({
+                content: "Test knowledge entry for contract validation",
+                category: "forge_test",
+                tags: ["test", "contract"],
+                confidence: 0.9,
+            });
+            expect(entry).not.toBeNull();
+            expect(entry.id).toBeDefined();
+            expect(entry.content).toContain("contract validation");
+        });
+        it("queries by category", async () => {
+            if (!port.queryKnowledge)
+                return; // optional
+            await port.archiveKnowledge({
+                content: "Category-specific entry",
+                category: "forge_test_category",
+                tags: ["test"],
+            });
+            const results = await port.queryKnowledge("Category", {
+                category: "forge_test_category",
+                limit: 5,
+            });
+            expect(results.length).toBeGreaterThan(0);
+            expect(results[0].category).toBe("forge_test_category");
+        });
+        it("returns null for non-existent queries", async () => {
+            if (!port.queryKnowledge)
+                return;
+            const results = await port.queryKnowledge("nonexistent_xyz_123", { limit: 1 });
+            expect(results.length).toBe(0);
+        });
+        it("supports working memory tier", async () => {
+            if (!port.working)
+                return;
+            await port.working.set("test-run", "key1", { value: 42 });
+            const result = await port.working.get("test-run", "key1");
+            expect(result).toEqual({ value: 42 });
+        });
+        it("supports episodic memory tier", async () => {
+            if (!port.episodic)
+                return;
+            await port.episodic.record("test-agent", "run-1", "cycle_completed", { cycles: 5 });
+            const events = await port.episodic.since("test-agent", Date.now() - 60_000);
+            expect(events.length).toBeGreaterThan(0);
+        });
+    });
+}
+//# sourceMappingURL=brain-port.contract.js.map

package/dist/testing/contracts/brain-port.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-port.contract.js","sourceRoot":"","sources":["../../../src/testing/contracts/brain-port.contract.ts"],"names":[],"mappings":"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"}

package/dist/testing/contracts/economic-observer.contract.d.ts

@@ -0,0 +1,23 @@
+/**
+ * EconomicObserver contract test suite.
+ *
+ * Forge adapters (PostgresEconomicObserver) run this suite to validate:
+ *   1. shouldThrottle returns true after 20+ cycles with cost > value * 0.5
+ *   2. shouldThrottle returns false under 20 cycles regardless of ROI
+ *   3. 7-day window: stale cycles expire, un-throttling the agent
+ *   4. getStats returns correct cost7d, value7d, roi, cycles
+ *
+ * clock injection via factory parameter — PostgresEconomicObserver accepts
+ * clock for test determinism without waiting 7 real days.
+ *
+ * @public
+ */
+import type { EconomicObserver } from "../../orchestration/ooda/economic-observer.js";
+export declare function economicObserverContract(factory: () => Promise<{
+    obs: EconomicObserver;
+    clock?: {
+        now(): Date;
+    };
+    cleanup(): Promise<void>;
+}>): void;
+//# sourceMappingURL=economic-observer.contract.d.ts.map

package/dist/testing/contracts/economic-observer.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"economic-observer.contract.d.ts","sourceRoot":"","sources":["../../../src/testing/contracts/economic-observer.contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+CAA+C,CAAC;AAEtF,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,OAAO,CAAC;IACrB,GAAG,EAAE,gBAAgB,CAAC;IACtB,KAAK,CAAC,EAAE;QAAE,GAAG,IAAI,IAAI,CAAA;KAAE,CAAC;IACxB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B,CAAC,GACD,IAAI,CA8DN"}

package/dist/testing/contracts/economic-observer.contract.js

@@ -0,0 +1,71 @@
+/**
+ * EconomicObserver contract test suite.
+ *
+ * Forge adapters (PostgresEconomicObserver) run this suite to validate:
+ *   1. shouldThrottle returns true after 20+ cycles with cost > value * 0.5
+ *   2. shouldThrottle returns false under 20 cycles regardless of ROI
+ *   3. 7-day window: stale cycles expire, un-throttling the agent
+ *   4. getStats returns correct cost7d, value7d, roi, cycles
+ *
+ * clock injection via factory parameter — PostgresEconomicObserver accepts
+ * clock for test determinism without waiting 7 real days.
+ *
+ * @public
+ */
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+export function economicObserverContract(factory) {
+    let obs;
+    let cleanup;
+    beforeAll(async () => {
+        const result = await factory();
+        obs = result.obs;
+        cleanup = result.cleanup;
+    });
+    afterAll(async () => {
+        await cleanup();
+    });
+    describe("EconomicObserver contract", () => {
+        const agentId = "test-agent-contract";
+        it("shouldThrottle returns false under 20 cycles regardless of ROI", async () => {
+            // Record 5 cycles with terrible ROI
+            for (let i = 0; i < 5; i++) {
+                await obs.recordCycle(agentId, 10.0, 1, 1.0); // $10 cost, $0.01 value
+            }
+            const throttled = await obs.shouldThrottle(agentId);
+            expect(throttled).toBe(false);
+        });
+        it("shouldThrottle returns true after 20+ cycles with cost > value * 0.5", async () => {
+            // Record 25 cycles with negative ROI
+            for (let i = 0; i < 25; i++) {
+                await obs.recordCycle(agentId, 5.0, 1, 1.0); // $5 cost, $0.01 value
+            }
+            const throttled = await obs.shouldThrottle(agentId);
+            expect(throttled).toBe(true);
+        });
+        it("shouldThrottle returns false after 20+ cycles with positive ROI", async () => {
+            const profitableAgent = "test-agent-profitable";
+            for (let i = 0; i < 25; i++) {
+                await obs.recordCycle(profitableAgent, 0.01, 100, 1.0); // $0.01 cost, $1.00 value
+            }
+            const throttled = await obs.shouldThrottle(profitableAgent);
+            expect(throttled).toBe(false);
+        });
+        it("getStats returns correct cost7d, value7d, roi, cycles", async () => {
+            const stats = await obs.getStats(agentId);
+            expect(typeof stats.cost7d).toBe("number");
+            expect(typeof stats.value7d).toBe("number");
+            expect(typeof stats.roi).toBe("number");
+            expect(typeof stats.cycles).toBe("number");
+            expect(stats.cycles).toBeGreaterThan(0);
+        });
+        it("confidence weights outcome value", async () => {
+            const confAgent = "test-agent-confidence";
+            // Record with low confidence — effective value is discounted
+            await obs.recordCycle(confAgent, 1.0, 100, 0.5); // $1 cost, $1 value * 0.5 = $0.50
+            const stats = await obs.getStats(confAgent);
+            // Value should reflect confidence weighting
+            expect(stats.value7d).toBeGreaterThan(0);
+        });
+    });
+}
+//# sourceMappingURL=economic-observer.contract.js.map