@bounded-sh/observe 0.1.0

package/dist/escort.d.ts

@@ -0,0 +1,92 @@
+import type { CompiledEscort } from "./manifest";
+import type { ActorContext } from "./types";
+export type EscortVerdict = "allowed" | "pending_approval" | "declined";
+export interface VerdictResult {
+    verdict: EscortVerdict;
+    intentId: string;
+    invariant?: string;
+    reason?: string;
+    approveUrl?: string;
+}
+export interface SettleOutcome {
+    outcome: "fired" | "failed" | "fail_open";
+    status?: number;
+    resultId?: string;
+    failOpen?: boolean;
+    /** llm-gateway rail ONLY (§4.3): the ACTUAL usage-cost in integer cents,
+     * computed from the fired call's response usage. The enforcement worker forwards
+     * this as a DECREASE of the estCents reservation (releasing rolling-window
+     * headroom). Absent for every other rail. */
+    actualCents?: number;
+}
+/** Verdict endpoint unreachable / non-decisive (network, timeout, 5xx, auth).
+ * Distinct from a decisive `declined` verdict — the caller applies failMode. */
+export declare class EscortUnreachable extends Error {
+    readonly detail: string;
+    constructor(detail: string);
+}
+/**
+ * A local enforcement error thrown to the app when a call is NOT allowed to
+ * fire. Shaped to resemble a Stripe API error (`type`/`code`/`raw.error`) so it
+ * flows through rail SDK error handling; also carries Bounded-specific fields.
+ * The outbound request never fired.
+ */
+export declare class BoundedEnforcementError extends Error {
+    readonly boundedVerdict: "declined" | "pending_approval" | "fail_closed";
+    readonly rail: string;
+    /** Stripe-compatible error type. */
+    readonly type = "invalid_request_error";
+    readonly code: string;
+    readonly intentId?: string;
+    readonly invariant?: string;
+    readonly reason?: string;
+    readonly approveUrl?: string;
+    /** Response-shaped payload mirroring a rail API error body. */
+    readonly raw: {
+        error: {
+            type: string;
+            code: string;
+            message: string;
+        };
+    };
+    constructor(opts: {
+        boundedVerdict: "declined" | "pending_approval" | "fail_closed";
+        rail: string;
+        code: string;
+        message: string;
+        intentId?: string;
+        invariant?: string;
+        reason?: string;
+        approveUrl?: string;
+    });
+}
+/** Build the rail-shaped local error for a non-fire verdict. */
+export declare function buildRailError(cfg: CompiledEscort, opts: {
+    kind: "declined" | "pending_approval" | "fail_closed";
+    intentId?: string;
+    invariant?: string;
+    reason?: string;
+    approveUrl?: string;
+}): BoundedEnforcementError;
+/**
+ * Extract candidate intent fields from the request body the app already built,
+ * via the route's fieldMap (rail field -> intent field). Numbers stay numbers
+ * (Stripe amounts in cents); strings are length-capped. PII-shaped mappings are
+ * dropped (defense in depth on top of validateManifest).
+ *
+ * The `llm-gateway` rail (SPEC §4.3) is the ONE COMPUTED case: fieldMap alone
+ * cannot express estCents, so instead of copying request-body fields verbatim
+ * the shim computes {model, maxTokensReq, estCents} from the model + output cap
+ * via the static price table (llm-prices.ts). estCents is an UPPER BOUND at
+ * verdict time; the generic verbatim-copy path is UNTOUCHED for every other
+ * rail (stripe, etc.).
+ */
+export declare function buildIntentFields(reqBodyText: string | undefined, contentType: string | undefined, cfg: CompiledEscort): Record<string, string | number>;
+/**
+ * ONE verdict round-trip to the org's verdict endpoint (sensor-key authed,
+ * tight client timeout). Returns a decisive verdict, or throws EscortUnreachable
+ * (network/timeout/5xx/auth) so the caller can apply failMode locally.
+ */
+export declare function requestVerdict(cfg: CompiledEscort, intentId: string, intent: Record<string, string | number>, actor: ActorContext | undefined): Promise<VerdictResult>;
+/** Fire-and-forget settle report to the org's settle endpoint. Never throws. */
+export declare function settleAsync(cfg: CompiledEscort, intentId: string, outcome: SettleOutcome): void;

package/dist/escort.js

@@ -0,0 +1,269 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// escort.ts -- Mode A escort (enforce) round-trip (SPEC §4.2, T9, U16, U18).
+//
+// When an outbound request matches an escorted route, the interceptor:
+//   1. extracts candidate intent fields from the request the app ALREADY built
+//      (never mutates it) via the route's fieldMap,
+//   2. mints an intentId (crypto.randomUUID) and makes ONE verdict round-trip
+//      to the org's verdict endpoint (sensor-key authed, tight timeout),
+//   3. on `allowed` lets the call FIRE FROM THE APP'S OWN PROCESS with an
+//      Idempotency-Key = intentId, then fire-and-forget settle-reports the
+//      outcome; on `declined`/`pending_approval` throws a rail-shaped local
+//      error (the call never fires); on verdict-endpoint unreachability applies
+//      the route's failMode LOCALLY (closed = clean local error, open =
+//      proceed + flag).
+//
+// The payload never transits Bounded (only the mapped intent fields do). This
+// module is deterministic — no LLM anywhere (T3). All network here uses the
+// pre-patch original fetch, so it is never itself captured or escorted.
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BoundedEnforcementError = exports.EscortUnreachable = void 0;
+exports.buildRailError = buildRailError;
+exports.buildIntentFields = buildIntentFields;
+exports.requestVerdict = requestVerdict;
+exports.settleAsync = settleAsync;
+const denylist_1 = require("./denylist");
+const llm_prices_1 = require("./llm-prices");
+const recognize_1 = require("./recognize");
+const state_1 = require("./state");
+const DEFAULT_VERDICT_TIMEOUT_MS = 3_000;
+/** Verdict endpoint unreachable / non-decisive (network, timeout, 5xx, auth).
+ * Distinct from a decisive `declined` verdict — the caller applies failMode. */
+class EscortUnreachable extends Error {
+    detail;
+    constructor(detail) {
+        super(`verdict endpoint unreachable: ${detail}`);
+        this.detail = detail;
+        this.name = "EscortUnreachable";
+    }
+}
+exports.EscortUnreachable = EscortUnreachable;
+/**
+ * A local enforcement error thrown to the app when a call is NOT allowed to
+ * fire. Shaped to resemble a Stripe API error (`type`/`code`/`raw.error`) so it
+ * flows through rail SDK error handling; also carries Bounded-specific fields.
+ * The outbound request never fired.
+ */
+class BoundedEnforcementError extends Error {
+    boundedVerdict;
+    rail;
+    /** Stripe-compatible error type. */
+    type = "invalid_request_error";
+    code;
+    intentId;
+    invariant;
+    reason;
+    approveUrl;
+    /** Response-shaped payload mirroring a rail API error body. */
+    raw;
+    constructor(opts) {
+        super(opts.message);
+        this.name = "BoundedEnforcementError";
+        this.boundedVerdict = opts.boundedVerdict;
+        this.rail = opts.rail;
+        this.code = opts.code;
+        this.intentId = opts.intentId;
+        this.invariant = opts.invariant;
+        this.reason = opts.reason;
+        this.approveUrl = opts.approveUrl;
+        this.raw = { error: { type: this.type, code: opts.code, message: opts.message } };
+    }
+}
+exports.BoundedEnforcementError = BoundedEnforcementError;
+/** Build the rail-shaped local error for a non-fire verdict. */
+function buildRailError(cfg, opts) {
+    let code;
+    let message;
+    if (opts.kind === "declined") {
+        code = "bounded_declined";
+        message = opts.invariant
+            ? `Declined by Bounded: invariant "${opts.invariant}" would be violated.`
+            : `Declined by Bounded${opts.reason ? ` (${opts.reason})` : ""}.`;
+    }
+    else if (opts.kind === "pending_approval") {
+        code = "bounded_pending_approval";
+        message = `Pending approval${opts.approveUrl ? `; approve at ${opts.approveUrl}` : ""}.`;
+    }
+    else {
+        code = "bounded_fail_closed";
+        message = "Blocked: Bounded verdict endpoint unreachable and failMode=closed.";
+    }
+    return new BoundedEnforcementError({
+        boundedVerdict: opts.kind,
+        rail: cfg.rail,
+        code,
+        message,
+        intentId: opts.intentId,
+        invariant: opts.invariant,
+        reason: opts.reason,
+        approveUrl: opts.approveUrl,
+    });
+}
+/**
+ * Extract candidate intent fields from the request body the app already built,
+ * via the route's fieldMap (rail field -> intent field). Numbers stay numbers
+ * (Stripe amounts in cents); strings are length-capped. PII-shaped mappings are
+ * dropped (defense in depth on top of validateManifest).
+ *
+ * The `llm-gateway` rail (SPEC §4.3) is the ONE COMPUTED case: fieldMap alone
+ * cannot express estCents, so instead of copying request-body fields verbatim
+ * the shim computes {model, maxTokensReq, estCents} from the model + output cap
+ * via the static price table (llm-prices.ts). estCents is an UPPER BOUND at
+ * verdict time; the generic verbatim-copy path is UNTOUCHED for every other
+ * rail (stripe, etc.).
+ */
+function buildIntentFields(reqBodyText, contentType, cfg) {
+    const out = {};
+    const body = (0, recognize_1.parseBody)(reqBodyText, contentType);
+    if (!body)
+        return out;
+    if (cfg.rail === "llm-gateway") {
+        const llm = (0, llm_prices_1.buildLlmIntentFields)(body, cfg.action, reqBodyText);
+        if (!llm)
+            return out;
+        // Only emit intent fields the route's fieldMap targets (server projectFields
+        // drops the rest anyway); default carries model + estCents when the promoted
+        // fieldMap maps them. maxTokensReq is informational for the reservation.
+        for (const [, intentField] of Object.entries(cfg.fieldMap)) {
+            if ((0, denylist_1.isDeniedFieldPath)(intentField))
+                continue;
+            if (intentField === "model")
+                out.model = llm.model;
+            else if (intentField === "estCents")
+                out.estCents = llm.estCents;
+            else if (intentField === "maxTokensReq")
+                out.maxTokensReq = llm.maxTokensReq;
+        }
+        // If the fieldMap did not name model/estCents (e.g. a minimal manifest),
+        // still carry the invariant field so the reservation is never $0-silent.
+        if (out.estCents === undefined)
+            out.estCents = llm.estCents;
+        if (out.model === undefined)
+            out.model = llm.model;
+        return out;
+    }
+    for (const [railField, intentField] of Object.entries(cfg.fieldMap)) {
+        if ((0, denylist_1.isDeniedFieldPath)(railField) || (0, denylist_1.isDeniedFieldPath)(intentField))
+            continue;
+        const v = body[railField];
+        if (typeof v === "number" && Number.isFinite(v))
+            out[intentField] = v;
+        else if (typeof v === "string" && v.length > 0)
+            out[intentField] = v.slice(0, 256);
+    }
+    return out;
+}
+/**
+ * ONE verdict round-trip to the org's verdict endpoint (sensor-key authed,
+ * tight client timeout). Returns a decisive verdict, or throws EscortUnreachable
+ * (network/timeout/5xx/auth) so the caller can apply failMode locally.
+ */
+async function requestVerdict(cfg, intentId, intent, actor) {
+    const doFetch = state_1.state.originalFetch;
+    const token = state_1.state.config?.token;
+    if (!doFetch || !token)
+        throw new EscortUnreachable("shim-not-ready");
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), cfg.timeoutMs ?? DEFAULT_VERDICT_TIMEOUT_MS);
+    timer.unref?.();
+    let res;
+    try {
+        res = await doFetch(cfg.verdictUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+            body: JSON.stringify({
+                intentId,
+                collection: cfg.collection,
+                rail: cfg.rail,
+                action: cfg.action,
+                fields: intent,
+                actor: actor?.id ?? "unattributed",
+                actorKind: actor?.kind,
+                onBehalfOf: actor?.onBehalfOf,
+            }),
+            signal: ac.signal,
+        });
+    }
+    catch {
+        throw new EscortUnreachable("network"); // timeout / abort / connection error
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const status = res.status;
+    let body = {};
+    try {
+        body = (await res.json());
+    }
+    catch {
+        body = {};
+    }
+    if (status >= 200 && status < 300) {
+        const vb = typeof body.verdict === "string" ? body.verdict : "";
+        const approval = body.approval;
+        const approveUrl = typeof body.approveUrl === "string" ? body.approveUrl
+            : approval && typeof approval.approveUrl === "string" ? approval.approveUrl
+                : undefined;
+        if (vb === "pending_approval")
+            return { verdict: "pending_approval", intentId, approveUrl };
+        // A 2xx that is explicitly a decline (defense in depth: the server SHOULD
+        // send 403/409, but never FIRE on a body that says "declined").
+        if (vb === "declined") {
+            return {
+                verdict: "declined",
+                intentId,
+                invariant: typeof body.invariant === "string" ? body.invariant : undefined,
+                reason: typeof body.reason === "string" ? body.reason : "rule",
+            };
+        }
+        // Fire ONLY on an explicit allow. An empty/unknown 2xx verdict is NOT a fire
+        // signal — treat it as non-decisive and apply failMode (never fail-open).
+        if (vb === "allowed" || vb === "settled")
+            return { verdict: "allowed", intentId, approveUrl };
+        throw new EscortUnreachable(`ambiguous-verdict-${vb || "empty"}`);
+    }
+    // Decisive declines: 403 = rule, 409 = invariant (or duplicate intent).
+    if (status === 403 || status === 409) {
+        return {
+            verdict: "declined",
+            intentId,
+            invariant: typeof body.invariant === "string" ? body.invariant : undefined,
+            reason: typeof body.reason === "string" ? body.reason : status === 403 ? "rule" : "invariant",
+        };
+    }
+    // 401 / 5xx / anything else: not a decisive verdict -> apply failMode.
+    throw new EscortUnreachable(`status-${status}`);
+}
+/** Fire-and-forget settle report to the org's settle endpoint. Never throws. */
+function settleAsync(cfg, intentId, outcome) {
+    const doFetch = state_1.state.originalFetch;
+    const token = state_1.state.config?.token;
+    if (!doFetch || !token)
+        return;
+    try {
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), cfg.timeoutMs ?? DEFAULT_VERDICT_TIMEOUT_MS);
+        timer.unref?.();
+        void doFetch(cfg.settleUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+            body: JSON.stringify({ intentId, collection: cfg.collection, ...outcome }),
+            signal: ac.signal,
+        })
+            .then((r) => {
+            try {
+                return r.text();
+            }
+            catch {
+                return undefined;
+            }
+        })
+            .catch(() => undefined)
+            .finally(() => clearTimeout(timer));
+    }
+    catch (err) {
+        (0, state_1.noteInternalError)("escort.settle", err);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { middleware, runAs, currentActor } from "./context";
+import { BUILTIN_MANIFEST, escortedManifest } from "./manifest";
+import type { Diagnostics, ObserveConfig } from "./types";
+export type { ObserveConfig, ActorInput, ActorContext, SessionMapper, WireEvent, Diagnostics, } from "./types";
+export type { ObserveManifest, RecognizerEntry, IdentityFieldConfig, RouteMatcher, EscortConfig, CompiledEscort, EscortPin, } from "./manifest";
+export { escortedManifest };
+export { BoundedEnforcementError } from "./escort";
+export { estimateUpperBoundCents, actualCentsFromUsage, usageFromResponse, buildLlmIntentFields, resolveModelPrice, MODEL_PRICES, PRICE_TABLE_VERSION, } from "./llm-prices";
+export type { ModelPrice, UpperBoundResult, ActualResult, LlmIntentFields } from "./llm-prices";
+export { runAs, middleware, currentActor };
+export { BUILTIN_MANIFEST };
+export interface ObserveHandle {
+    runAs: typeof runAs;
+    middleware: typeof middleware;
+    /** Force-process + report everything pending (partial counter windows included). */
+    flush: () => Promise<void>;
+    /** Graceful shutdown: final flush, stop timers. Patches stay (inert). */
+    shutdown: () => Promise<void>;
+    diagnostics: () => Diagnostics;
+}
+/**
+ * Initialize the shim. Idempotent: a second call updates config only.
+ * With BOUNDED_OBSERVE_DISABLED=1 at startup, nothing is patched and the
+ * returned handle is inert (runAs/middleware still work as passthroughs).
+ */
+export declare function init(config: ObserveConfig): ObserveHandle;
+/** Process + report everything pending (forces partial counter windows). */
+export declare function flush(): Promise<void>;
+/** Final flush + stop timers. Patches remain installed but keep working;
+ * call this on graceful shutdown so the tail of the queue is reported. */
+export declare function shutdown(): Promise<void>;
+export declare function diagnostics(): Diagnostics;
+/** TEST ONLY: unpatch globals and reset all singleton state. */
+export declare function __resetForTests(): void;
+/** TEST ONLY: run one pipeline/report tick synchronously-ish. */
+export declare function __tickForTests(now?: number): Promise<void>;
+declare const _default: {
+    init: typeof init;
+    runAs: typeof runAs;
+    middleware: typeof middleware;
+    currentActor: typeof currentActor;
+    flush: typeof flush;
+    shutdown: typeof shutdown;
+    diagnostics: typeof diagnostics;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,274 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// @bounded-sh/observe -- Node observe shim (SPEC-OBSERVE-ENFORCE-CUSTODY.md
+// §3.1a). Interception: globalThis.fetch (undici) + http/https.request.
+// Actor context: runAs() / middleware() via AsyncLocalStorage.
+// Reporting: async batches (<=500 / 2s) to the observe ingest, fire-and-
+// forget, bounded memory, honest drop counting. Metadata-only by default;
+// capture is manifest-driven (built-in manifest + 60s poll stub).
+//
+// Kill switch: BOUNDED_OBSERVE_DISABLED=1 (checked at init AND re-checked on
+// every tick — flipping it at runtime stops interception within a tick).
+// The shim NEVER breaks the app: every code path is wrapped; original
+// behavior is always preserved; observe is always fail-open.
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILTIN_MANIFEST = exports.currentActor = exports.middleware = exports.runAs = exports.PRICE_TABLE_VERSION = exports.MODEL_PRICES = exports.resolveModelPrice = exports.buildLlmIntentFields = exports.usageFromResponse = exports.actualCentsFromUsage = exports.estimateUpperBoundCents = exports.BoundedEnforcementError = exports.escortedManifest = void 0;
+exports.init = init;
+exports.flush = flush;
+exports.shutdown = shutdown;
+exports.diagnostics = diagnostics;
+exports.__resetForTests = __resetForTests;
+exports.__tickForTests = __tickForTests;
+const context_1 = require("./context");
+Object.defineProperty(exports, "middleware", { enumerable: true, get: function () { return context_1.middleware; } });
+Object.defineProperty(exports, "runAs", { enumerable: true, get: function () { return context_1.runAs; } });
+Object.defineProperty(exports, "currentActor", { enumerable: true, get: function () { return context_1.currentActor; } });
+const fetch_1 = require("./intercept/fetch");
+const http_1 = require("./intercept/http");
+const manifest_1 = require("./manifest");
+Object.defineProperty(exports, "BUILTIN_MANIFEST", { enumerable: true, get: function () { return manifest_1.BUILTIN_MANIFEST; } });
+Object.defineProperty(exports, "escortedManifest", { enumerable: true, get: function () { return manifest_1.escortedManifest; } });
+const pipeline_1 = require("./pipeline");
+const reporter_1 = require("./reporter");
+const state_1 = require("./state");
+var escort_1 = require("./escort");
+Object.defineProperty(exports, "BoundedEnforcementError", { enumerable: true, get: function () { return escort_1.BoundedEnforcementError; } });
+var llm_prices_1 = require("./llm-prices");
+Object.defineProperty(exports, "estimateUpperBoundCents", { enumerable: true, get: function () { return llm_prices_1.estimateUpperBoundCents; } });
+Object.defineProperty(exports, "actualCentsFromUsage", { enumerable: true, get: function () { return llm_prices_1.actualCentsFromUsage; } });
+Object.defineProperty(exports, "usageFromResponse", { enumerable: true, get: function () { return llm_prices_1.usageFromResponse; } });
+Object.defineProperty(exports, "buildLlmIntentFields", { enumerable: true, get: function () { return llm_prices_1.buildLlmIntentFields; } });
+Object.defineProperty(exports, "resolveModelPrice", { enumerable: true, get: function () { return llm_prices_1.resolveModelPrice; } });
+Object.defineProperty(exports, "MODEL_PRICES", { enumerable: true, get: function () { return llm_prices_1.MODEL_PRICES; } });
+Object.defineProperty(exports, "PRICE_TABLE_VERSION", { enumerable: true, get: function () { return llm_prices_1.PRICE_TABLE_VERSION; } });
+const DEFAULT_FLUSH_MS = 2_000;
+const DEFAULT_SEND_TIMEOUT_MS = 5_000;
+const DEFAULT_MAX_QUEUE = 5_000;
+const DEFAULT_PROMOTE_THRESHOLD = 60;
+const DEFAULT_SHAPES_PER_MIN = 30;
+const DEFAULT_MANIFEST_POLL_MS = 60_000;
+function tick() {
+    try {
+        // Runtime kill switch: honor env flips without a restart.
+        if ((0, state_1.killSwitchActive)()) {
+            if (state_1.state.enabled)
+                (0, state_1.debugLog)(`${state_1.KILL_SWITCH_ENV} set — observation stopped`);
+            state_1.state.enabled = false;
+            return;
+        }
+        if (state_1.state.initialized && !state_1.state.enabled) {
+            // Env was cleared again: resume (patches are still in place).
+            state_1.state.enabled = true;
+            (0, state_1.debugLog)("kill switch cleared — observation resumed");
+        }
+        const processed = state_1.state.pipeline?.process(Date.now(), false);
+        if (processed) {
+            // Identity hashing in flight — flush after it settles (fire-and-forget).
+            void processed.then(() => state_1.state.reporter?.flushOnce());
+        }
+        else {
+            void state_1.state.reporter?.flushOnce();
+        }
+    }
+    catch (err) {
+        (0, state_1.noteInternalError)("tick", err);
+    }
+}
+async function pollManifest() {
+    const cfg = state_1.state.config;
+    const doFetch = state_1.state.originalFetch;
+    if (!cfg || !doFetch || !state_1.state.enabled)
+        return;
+    try {
+        const org = cfg.org ? `?org=${encodeURIComponent(cfg.org)}` : "";
+        const ac = new AbortController();
+        const t = setTimeout(() => ac.abort(), 5_000);
+        t.unref?.();
+        let res;
+        try {
+            res = await doFetch(`${cfg.ingestBase.replace(/\/$/, "")}/v1/manifest${org}`, {
+                signal: ac.signal,
+                // Sensor-token authed (same token as /v1/events; the served manifest is
+                // org-scoped to the token). No token => 401 => builtin retained.
+                headers: cfg.token ? { Authorization: `Bearer ${cfg.token}` } : undefined,
+            });
+        }
+        finally {
+            clearTimeout(t);
+        }
+        if (!res.ok) {
+            // Endpoint doesn't exist yet (404) or is unhappy: keep what we have.
+            try {
+                await res.text();
+            }
+            catch {
+                /* ignore */
+            }
+            (0, state_1.debugLog)(`manifest poll: ${res.status} — keeping ${state_1.state.manifest.source} manifest`);
+            return;
+        }
+        const body = await res.json();
+        // TODO(signed manifests, SPEC §3.1a): verify `signature` before accepting.
+        const validated = (0, manifest_1.validateManifest)(body);
+        if (!validated) {
+            (0, state_1.debugLog)("manifest poll: invalid manifest — keeping current (fail-safe)");
+            return;
+        }
+        // Escort blocks + field lists INSIDE the fetched manifest already passed
+        // cleanEscort / the L2 denylist in validateManifest above. The env-derived
+        // escort pin is re-applied over the validated result so a served manifest
+        // can never silently drop enforcement (a fetched escort block on the
+        // pinned route wins; see escortedManifest).
+        const next = (0, manifest_1.withEscortPin)(validated, cfg.escortPin);
+        state_1.state.manifest = new manifest_1.CompiledManifest(next, "fetched");
+        (0, state_1.debugLog)(`manifest updated to ${next.version}`);
+    }
+    catch (err) {
+        (0, state_1.debugLog)("manifest poll failed — keeping current manifest", err);
+    }
+}
+/**
+ * Initialize the shim. Idempotent: a second call updates config only.
+ * With BOUNDED_OBSERVE_DISABLED=1 at startup, nothing is patched and the
+ * returned handle is inert (runAs/middleware still work as passthroughs).
+ */
+function init(config) {
+    try {
+        if (!state_1.state.initialized) {
+            state_1.state.config = config;
+            try {
+                state_1.state.ingestHost = new URL(config.ingestBase).host;
+            }
+            catch {
+                state_1.state.ingestHost = undefined;
+            }
+            const reporter = new reporter_1.Reporter(config.maxQueueEvents ?? DEFAULT_MAX_QUEUE, config.sendTimeoutMs ?? DEFAULT_SEND_TIMEOUT_MS);
+            state_1.state.reporter = reporter;
+            state_1.state.pipeline = new pipeline_1.Pipeline(reporter, config.counterPromoteThreshold ?? DEFAULT_PROMOTE_THRESHOLD, config.shapesPerMinute ?? DEFAULT_SHAPES_PER_MIN);
+            // Manifest: override (tests/dev) > built-in; fetched may replace later.
+            // The env-derived escort pin (register preload) is applied over the
+            // initial manifest here AND over every fetched swap (pollManifest) — a
+            // served manifest can never silently drop pinned enforcement.
+            if (config.manifest !== undefined) {
+                const validated = (0, manifest_1.validateManifest)(config.manifest);
+                state_1.state.manifest = validated
+                    ? new manifest_1.CompiledManifest((0, manifest_1.withEscortPin)(validated, config.escortPin), "override")
+                    : new manifest_1.CompiledManifest((0, manifest_1.withEscortPin)(manifest_1.BUILTIN_MANIFEST, config.escortPin), "builtin"); // fail-safe
+                if (!validated)
+                    (0, state_1.debugLog)("init: invalid manifest override — using built-in (fail-safe)");
+            }
+            else {
+                state_1.state.manifest = new manifest_1.CompiledManifest((0, manifest_1.withEscortPin)(manifest_1.BUILTIN_MANIFEST, config.escortPin), "builtin");
+            }
+            state_1.state.initialized = true;
+            if ((0, state_1.killSwitchActive)()) {
+                state_1.state.enabled = false;
+                (0, state_1.debugLog)(`${state_1.KILL_SWITCH_ENV} set — shim inert (nothing patched)`);
+            }
+            else {
+                state_1.state.enabled = true;
+                (0, fetch_1.patchFetch)();
+                (0, http_1.patchHttp)();
+                state_1.state.patched = true;
+                const flushMs = config.flushIntervalMs ?? DEFAULT_FLUSH_MS;
+                state_1.state.tickTimer = setInterval(tick, flushMs);
+                state_1.state.tickTimer.unref?.();
+                if (!config.disableManifestPoll && config.manifest === undefined) {
+                    state_1.state.manifestTimer = setInterval(() => void pollManifest(), config.manifestPollMs ?? DEFAULT_MANIFEST_POLL_MS);
+                    state_1.state.manifestTimer.unref?.();
+                }
+                (0, state_1.debugLog)("initialized (fetch + http/https patched)");
+            }
+        }
+        else {
+            state_1.state.config = { ...state_1.state.config, ...config };
+            (0, state_1.debugLog)("re-init: config updated");
+        }
+    }
+    catch (err) {
+        // Init must never take the app down.
+        (0, state_1.noteInternalError)("init", err);
+    }
+    return { runAs: context_1.runAs, middleware: context_1.middleware, flush, shutdown, diagnostics };
+}
+/** Process + report everything pending (forces partial counter windows). */
+async function flush() {
+    try {
+        await state_1.state.pipeline?.process(Date.now(), true);
+        await state_1.state.reporter?.drain();
+    }
+    catch (err) {
+        (0, state_1.noteInternalError)("flush", err);
+    }
+}
+/** Final flush + stop timers. Patches remain installed but keep working;
+ * call this on graceful shutdown so the tail of the queue is reported. */
+async function shutdown() {
+    try {
+        if (state_1.state.tickTimer)
+            clearInterval(state_1.state.tickTimer);
+        if (state_1.state.manifestTimer)
+            clearInterval(state_1.state.manifestTimer);
+        state_1.state.tickTimer = undefined;
+        state_1.state.manifestTimer = undefined;
+        await flush();
+    }
+    catch (err) {
+        (0, state_1.noteInternalError)("shutdown", err);
+    }
+}
+function diagnostics() {
+    return {
+        enabled: state_1.state.enabled,
+        patched: state_1.state.patched,
+        queueDepth: state_1.state.reporter?.queueDepth ?? 0,
+        rawQueueDepth: state_1.state.pipeline?.rawQueueDepth ?? 0,
+        pendingDrops: state_1.state.reporter?.pendingDrops ?? 0,
+        totalDropped: state_1.state.reporter?.totalDropped ?? 0,
+        captured: state_1.state.stats.captured,
+        sentEvents: state_1.state.reporter?.sentEvents ?? 0,
+        sentBatches: state_1.state.reporter?.sentBatches ?? 0,
+        sendFailures: state_1.state.reporter?.sendFailures ?? 0,
+        internalErrors: state_1.state.stats.internalErrors,
+        manifestVersion: state_1.state.manifest.version,
+        manifestSource: state_1.state.manifest.source,
+    };
+}
+/** TEST ONLY: unpatch globals and reset all singleton state. */
+function __resetForTests() {
+    if (state_1.state.tickTimer)
+        clearInterval(state_1.state.tickTimer);
+    if (state_1.state.manifestTimer)
+        clearInterval(state_1.state.manifestTimer);
+    (0, fetch_1.unpatchFetch)();
+    (0, http_1.unpatchHttp)();
+    state_1.state.initialized = false;
+    state_1.state.enabled = false;
+    state_1.state.patched = false;
+    state_1.state.config = undefined;
+    state_1.state.ingestHost = undefined;
+    state_1.state.originalFetch = undefined;
+    state_1.state.pipeline = undefined;
+    state_1.state.reporter = undefined;
+    state_1.state.tickTimer = undefined;
+    state_1.state.manifestTimer = undefined;
+    state_1.state.manifest = new manifest_1.CompiledManifest(manifest_1.BUILTIN_MANIFEST, "builtin");
+    state_1.state.stats = { captured: 0, internalErrors: 0 };
+}
+/** TEST ONLY: run one pipeline/report tick synchronously-ish. */
+async function __tickForTests(now) {
+    await state_1.state.pipeline?.process(now ?? Date.now(), false);
+    await state_1.state.reporter?.flushOnce();
+}
+// Default export mirrors the named surface for CJS ergonomics:
+//   const bounded = require("@bounded-sh/observe"); bounded.init({...})
+exports.default = {
+    init,
+    runAs: context_1.runAs,
+    middleware: context_1.middleware,
+    currentActor: context_1.currentActor,
+    flush,
+    shutdown,
+    diagnostics,
+};