@bounded-sh/observe 0.1.0

package/dist/pipeline.d.ts

@@ -0,0 +1,18 @@
+import type { RawCapture } from "./types";
+import type { Reporter } from "./reporter";
+export declare class Pipeline {
+    private reporter;
+    private rawQueue;
+    private counters;
+    private shapes;
+    constructor(reporter: Reporter, promoteThreshold: number, shapesPerMinute: number);
+    get rawQueueDepth(): number;
+    /** HOT PATH: O(1) push; drop + count on overflow. Never throws. */
+    enqueueRaw(raw: RawCapture): void;
+    /** Tick work: classify pending raws, roll counter windows. Never throws.
+     * Returns a promise ONLY when identity hashing is in flight (wanted-identity
+     * routes) so flush()/tests can await full delivery; the common path stays
+     * fully synchronous. */
+    process(now: number, force?: boolean): void | Promise<void>;
+    private classify;
+}

package/dist/pipeline.js

@@ -0,0 +1,212 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// pipeline.ts -- raw capture -> event classes (SPEC §3.2).
+//
+// The interceptors' hot path only does enqueueRaw() (bounded array push).
+// Everything heavy — templating, recognition, body parsing, shape dedupe,
+// counter aggregation, wire-event construction — happens here, on the shared
+// tick, off the request path.
+//
+// Event classes:
+//   recognized + 2xx        -> action (rec{rail, action, registryVersion})
+//   recognized + non-2xx/0  -> error  (rec present)
+//   manifest counter match
+//     or promoted route     -> exact per-minute counter aggregation
+//   unrecognized            -> shape sample (deduped, rate-capped, names/types
+//                              only) + provisional counter tally for GETs
+//                              (promotes at >threshold calls/min)
+//   manifest mute match     -> nothing
+//
+// Wire events are constructed as EXACT envelope-v2 objects (whitelist by
+// construction): org/sensor omitted (server-stamped), `scrubbed` never sent,
+// no unknown TOP-LEVEL fields. Recognized safe-field values ride the envelope
+// under `rec.fields` (v2) AND stay on InternalEvent.fields for the debug hook.
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Pipeline = void 0;
+const envelope_1 = require("./envelope");
+const template_1 = require("./template");
+const recognize_1 = require("./recognize");
+const counters_1 = require("./counters");
+const shapes_1 = require("./shapes");
+const state_1 = require("./state");
+const MAX_RAW_QUEUE = 10_000;
+function actorOf(raw) {
+    if (!raw.actor)
+        return undefined;
+    return { id: raw.actor.id, kind: raw.actor.kind, grade: "asserted" };
+}
+class Pipeline {
+    reporter;
+    rawQueue = [];
+    counters;
+    shapes;
+    constructor(reporter, promoteThreshold, shapesPerMinute) {
+        this.reporter = reporter;
+        this.counters = new counters_1.CounterAggregator(promoteThreshold);
+        this.shapes = new shapes_1.ShapeDeduper(shapesPerMinute);
+    }
+    get rawQueueDepth() {
+        return this.rawQueue.length;
+    }
+    /** HOT PATH: O(1) push; drop + count on overflow. Never throws. */
+    enqueueRaw(raw) {
+        if (this.rawQueue.length >= MAX_RAW_QUEUE) {
+            this.reporter.countDrop(1);
+            return;
+        }
+        state_1.state.stats.captured++;
+        this.rawQueue.push(raw);
+    }
+    /** Tick work: classify pending raws, roll counter windows. Never throws.
+     * Returns a promise ONLY when identity hashing is in flight (wanted-identity
+     * routes) so flush()/tests can await full delivery; the common path stays
+     * fully synchronous. */
+    process(now, force = false) {
+        try {
+            const pending = this.rawQueue;
+            let hashing;
+            if (pending.length > 0) {
+                this.rawQueue = [];
+                for (const raw of pending) {
+                    try {
+                        const p = this.classify(raw);
+                        if (p)
+                            (hashing ??= []).push(p.catch((err) => (0, state_1.noteInternalError)("pipeline.classify", err)));
+                    }
+                    catch (err) {
+                        (0, state_1.noteInternalError)("pipeline.classify", err);
+                    }
+                }
+            }
+            for (const c of this.counters.flush(now, force)) {
+                this.reporter.push({ wire: counterEvent(c) });
+            }
+            if (hashing)
+                return Promise.all(hashing).then(() => undefined);
+        }
+        catch (err) {
+            (0, state_1.noteInternalError)("pipeline.process", err);
+        }
+    }
+    classify(raw) {
+        const manifest = state_1.state.manifest;
+        const pathTemplate = (0, template_1.templatePath)(raw.path);
+        const { host, method } = raw;
+        if (manifest.isMuted(host, method, pathTemplate))
+            return;
+        const route = { host, method, pathTemplate };
+        // Explicit counter policy (manifest) or an already-promoted hot route.
+        if (manifest.isCounterRoute(host, method, pathTemplate) || this.counters.isPromoted(route)) {
+            this.counters.add(route, raw.ts, raw.status, raw.durMs, raw.bytesIn, raw.bytesOut, false);
+            return;
+        }
+        // Parse the request body at most once, reused across JSON-RPC method
+        // matching, safe-field extraction, and shape sampling (the shim already
+        // retained the body; this is the same parse it does today — nothing extra
+        // on the request hot path, this runs on the shared tick).
+        let reqBody;
+        let reqParsed = false;
+        const reqBodyOnce = () => {
+            if (!reqParsed) {
+                reqBody = (0, recognize_1.parseBody)(raw.reqBodyText, raw.reqContentType);
+                reqParsed = true;
+            }
+            return reqBody;
+        };
+        let rec = manifest.recognize(host, method, pathTemplate);
+        // Crypto JSON-RPC: the operation is in the body's `method`, not the path
+        // (every RPC call POSTs to "/"). When no exact route matched and the host
+        // carries rpc recognizers, match on the parsed JSON-RPC method instead.
+        if (!rec && method === "POST" && manifest.hasRpcHost(host)) {
+            const rpcMethod = (0, recognize_1.jsonRpcMethod)(reqBodyOnce());
+            if (rpcMethod)
+                rec = manifest.recognizeRpc(host, rpcMethod);
+        }
+        if (rec) {
+            const body = reqBodyOnce();
+            const fields = (0, recognize_1.extractRecognizedFields)(rec, body, raw.respJson);
+            const cls = raw.status >= 200 && raw.status < 300 ? "action" : "error";
+            const wire = {
+                v: envelope_1.EVENT_SCHEMA_VERSION,
+                ts: raw.ts,
+                class: cls,
+                dest: { host, pathTemplate, method },
+                status: raw.status,
+                dur_ms: round1(raw.durMs),
+                bytes: { i: raw.bytesIn, o: raw.bytesOut },
+                rec: { rail: rec.rail, action: rec.action, registryVersion: manifest.version },
+            };
+            const actor = actorOf(raw);
+            if (actor)
+                wire.actor = actor;
+            if (raw.actor?.onBehalfOf)
+                wire.onBehalfOf = raw.actor.onBehalfOf;
+            const policyVersion = manifest.manifest.policyVersion;
+            if (policyVersion)
+                wire.policyVersion = policyVersion;
+            // v2: carry recognizer-extracted SAFE values on the wire (rec.fields).
+            // Already L1/L2-filtered + primitive-capped at extraction; ingest
+            // re-checks the KEYS (L2) and scrubs the VALUES (L4) server-side.
+            if (fields && wire.rec)
+                wire.rec.fields = fields;
+            // Wanted identity → the ATTRIBUTION channel: the manifest routed a
+            // request field into onBehalfOf (route config wins over the ALS
+            // context). Hashed IN-PROCESS by default — the raw value never leaves;
+            // raw rides ONLY on the owner's explicit hash:false opt-in. Never in
+            // rec.fields (extraction skips the source; validateManifest rejects
+            // entries that list it for capture).
+            const identity = rec.identityField;
+            const idValue = identity ? (0, recognize_1.extractIdentityValue)(identity, body) : undefined;
+            if (idValue !== undefined && identity.hash !== false) {
+                return (0, recognize_1.hashIdentityValue)(idValue).then((principal) => {
+                    wire.onBehalfOf = principal;
+                    this.reporter.push({ wire, fields });
+                });
+            }
+            if (idValue !== undefined)
+                wire.onBehalfOf = idValue;
+            this.reporter.push({ wire, fields });
+            return;
+        }
+        // Unrecognized: heuristic counter tally for GETs (exact from call #1).
+        if (method === "GET") {
+            this.counters.add(route, raw.ts, raw.status, raw.durMs, raw.bytesIn, raw.bytesOut, true);
+        }
+        // Shape sample: once per route, rate-capped, names/types only (L5).
+        if (this.shapes.shouldEmit(host, method, pathTemplate, raw.ts)) {
+            const fields = (0, recognize_1.extractShapeFields)(reqBodyOnce(), raw.queryNames);
+            const wire = {
+                v: envelope_1.EVENT_SCHEMA_VERSION,
+                ts: raw.ts,
+                class: "shape",
+                dest: { host, pathTemplate, method },
+                status: raw.status,
+                dur_ms: round1(raw.durMs),
+                bytes: { i: raw.bytesIn, o: raw.bytesOut },
+                shape: { fields },
+            };
+            const actor = actorOf(raw);
+            if (actor)
+                wire.actor = actor;
+            this.reporter.push({ wire });
+        }
+    }
+}
+exports.Pipeline = Pipeline;
+function round1(n) {
+    return n < 0 ? 0 : Math.round(n * 10) / 10;
+}
+function counterEvent(c) {
+    return {
+        v: envelope_1.EVENT_SCHEMA_VERSION,
+        ts: c.ts,
+        class: "counter",
+        dest: { host: c.host, pathTemplate: c.pathTemplate, method: c.method },
+        status: c.status,
+        dur_ms: round1(c.durMsSum),
+        bytes: { i: c.bytesInSum, o: c.bytesOutSum },
+        count: c.count,
+        window: { start: c.windowStart, seconds: c.windowSeconds },
+    };
+}

package/dist/recognize.d.ts

@@ -0,0 +1,38 @@
+import type { RecFields, ShapeField } from "./envelope";
+import type { IdentityFieldConfig, RecognizerEntry } from "./manifest";
+/** Parse a request body by content type. Returns undefined on any failure. */
+export declare function parseBody(text: string | undefined, contentType: string | undefined): Record<string, unknown> | undefined;
+/**
+ * Read the JSON-RPC operation name from an ALREADY-PARSED request body (crypto
+ * rails, SPEC §3.2). A JSON-RPC 2.0 request is {jsonrpc:"2.0", method, params};
+ * we return `method` for rpcMethod matching. The `params` VALUES (raw signed
+ * transactions, calldata, signatures) are NEVER read here — only the operation
+ * name. Returns undefined for anything that is not a single JSON-RPC call
+ * (batch arrays parse to non-objects and never reach here).
+ */
+export declare function jsonRpcMethod(body: Record<string, unknown> | undefined): string | undefined;
+/**
+ * Extract the recognizer's SAFE fields from parsed request/response bodies.
+ * Returns undefined when nothing was extracted. Response fields are prefixed
+ * "resp." when the same name exists on the request side.
+ */
+export declare function extractRecognizedFields(entry: RecognizerEntry, reqBody: Record<string, unknown> | undefined, respBody: unknown): RecFields | undefined;
+/**
+ * Extract the wanted-identity source value for the ATTRIBUTION channel
+ * (event.onBehalfOf) — never rec.fields. Primitives only; capped at the
+ * envelope's onBehalfOf bound. Returns undefined when absent/non-primitive.
+ */
+export declare function extractIdentityValue(cfg: IdentityFieldConfig, reqBody: Record<string, unknown> | undefined): string | undefined;
+/**
+ * Hash an identity value IN-PROCESS (webcrypto sha256) into the deterministic
+ * attribution principal "sha256:<hex>". The raw value never leaves the shim
+ * on this path.
+ */
+export declare function hashIdentityValue(value: string): Promise<string>;
+/**
+ * Shape sampling (L5): field NAMES + JSON types only, from the request body's
+ * top level plus query parameter names. Values never leave this function.
+ * Even the NAMES of PII-denied fields are dropped (nothing PII-shaped rides
+ * shape samples either).
+ */
+export declare function extractShapeFields(reqBody: Record<string, unknown> | undefined, queryNames: string[] | undefined): ShapeField[];

package/dist/recognize.js

@@ -0,0 +1,185 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// recognize.ts -- safe-field extraction for recognized routes (SPEC §3.2/§3.3)
+// and name/type extraction for shape samples (§3.2, L5).
+//
+// L1: only manifest-listed fields are ever extracted. L2: the hard PII
+// denylist is applied AGAIN here (defense in depth — even if a bad manifest
+// slipped past validateManifest, PII-named fields never leave this function).
+// Values captured are primitives only: numbers (amounts in cents, token
+// counts), booleans (delivery acks, flags) and short strings (opaque ids,
+// model names, enum-ish statuses).
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseBody = parseBody;
+exports.jsonRpcMethod = jsonRpcMethod;
+exports.extractRecognizedFields = extractRecognizedFields;
+exports.extractIdentityValue = extractIdentityValue;
+exports.hashIdentityValue = hashIdentityValue;
+exports.extractShapeFields = extractShapeFields;
+const node_crypto_1 = require("node:crypto");
+const denylist_1 = require("./denylist");
+const MAX_STRING_FIELD = 128;
+/** onBehalfOf is capped at 256 by the ingest envelope (and context.ts). */
+const MAX_IDENTITY_VALUE = 256;
+/** Parse a request body by content type. Returns undefined on any failure. */
+function parseBody(text, contentType) {
+    if (!text)
+        return undefined;
+    const ct = (contentType ?? "").toLowerCase();
+    try {
+        if (ct.includes("application/x-www-form-urlencoded")) {
+            const params = new URLSearchParams(text);
+            const out = {};
+            for (const [k, v] of params) {
+                // Numeric form values (Stripe amounts) become numbers.
+                out[k] = v !== "" && /^\d+$/.test(v) ? Number(v) : v;
+            }
+            return out;
+        }
+        // Default to JSON (covers application/json and JSON without a header).
+        const parsed = JSON.parse(text);
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read the JSON-RPC operation name from an ALREADY-PARSED request body (crypto
+ * rails, SPEC §3.2). A JSON-RPC 2.0 request is {jsonrpc:"2.0", method, params};
+ * we return `method` for rpcMethod matching. The `params` VALUES (raw signed
+ * transactions, calldata, signatures) are NEVER read here — only the operation
+ * name. Returns undefined for anything that is not a single JSON-RPC call
+ * (batch arrays parse to non-objects and never reach here).
+ */
+function jsonRpcMethod(body) {
+    if (!body)
+        return undefined;
+    if (typeof body.jsonrpc !== "string")
+        return undefined; // JSON-RPC 2.0 marker required
+    const method = body.method;
+    if (typeof method !== "string" || method.length === 0 || method.length > 128)
+        return undefined;
+    return method;
+}
+function getPath(obj, dotPath) {
+    let cur = obj;
+    for (const seg of dotPath.split(".")) {
+        if (typeof cur !== "object" || cur === null)
+            return undefined;
+        cur = cur[seg];
+    }
+    return cur;
+}
+/**
+ * Extract the recognizer's SAFE fields from parsed request/response bodies.
+ * Returns undefined when nothing was extracted. Response fields are prefixed
+ * "resp." when the same name exists on the request side.
+ */
+function extractRecognizedFields(entry, reqBody, respBody) {
+    const out = {};
+    let any = false;
+    const identitySource = entry.identityField?.source;
+    const take = (source, paths, prefixOnClash) => {
+        if (!source || !paths)
+            return;
+        for (const p of paths) {
+            if ((0, denylist_1.isDeniedFieldPath)(p))
+                continue; // L2 hard deny, re-checked
+            if (p === identitySource)
+                continue; // wanted identity NEVER rides capture
+            const v = getPath(source, p);
+            let val;
+            if (typeof v === "number" && Number.isFinite(v))
+                val = v;
+            else if (typeof v === "boolean")
+                val = v;
+            else if (typeof v === "string" && v.length > 0)
+                val = v.slice(0, MAX_STRING_FIELD);
+            if (val === undefined)
+                continue;
+            let key = p;
+            if (prefixOnClash && key in out)
+                key = `resp.${p}`;
+            out[key] = val;
+            any = true;
+        }
+    };
+    take(reqBody, entry.requestFields, false);
+    take(respBody, entry.responseFields, true);
+    return any ? out : undefined;
+}
+/**
+ * Extract the wanted-identity source value for the ATTRIBUTION channel
+ * (event.onBehalfOf) — never rec.fields. Primitives only; capped at the
+ * envelope's onBehalfOf bound. Returns undefined when absent/non-primitive.
+ */
+function extractIdentityValue(cfg, reqBody) {
+    if (!reqBody)
+        return undefined;
+    const v = getPath(reqBody, cfg.source);
+    if (typeof v === "string" && v.length > 0)
+        return v.slice(0, MAX_IDENTITY_VALUE);
+    if (typeof v === "number" && Number.isFinite(v))
+        return String(v);
+    return undefined;
+}
+/**
+ * Hash an identity value IN-PROCESS (webcrypto sha256) into the deterministic
+ * attribution principal "sha256:<hex>". The raw value never leaves the shim
+ * on this path.
+ */
+async function hashIdentityValue(value) {
+    const digest = await node_crypto_1.webcrypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+    let hex = "";
+    for (const b of new Uint8Array(digest))
+        hex += b.toString(16).padStart(2, "0");
+    return `sha256:${hex}`;
+}
+/**
+ * Shape sampling (L5): field NAMES + JSON types only, from the request body's
+ * top level plus query parameter names. Values never leave this function.
+ * Even the NAMES of PII-denied fields are dropped (nothing PII-shaped rides
+ * shape samples either).
+ */
+function extractShapeFields(reqBody, queryNames) {
+    const fields = [];
+    const seen = new Set();
+    const push = (name, type) => {
+        if (fields.length >= 64)
+            return;
+        if (name.length === 0 || name.length > 128)
+            return;
+        if (seen.has(name))
+            return;
+        if ((0, denylist_1.isDeniedSegment)(name))
+            return;
+        seen.add(name);
+        fields.push({ name, type: type });
+    };
+    if (reqBody) {
+        for (const [k, v] of Object.entries(reqBody)) {
+            const t = v === null
+                ? "null"
+                : Array.isArray(v)
+                    ? "array"
+                    : typeof v === "object"
+                        ? "object"
+                        : typeof v === "number"
+                            ? "number"
+                            : typeof v === "boolean"
+                                ? "boolean"
+                                : "string";
+            push(k, t);
+        }
+    }
+    if (queryNames) {
+        for (const q of queryNames)
+            push(q, "string");
+    }
+    return fields;
+}

package/dist/register.d.ts

@@ -0,0 +1,9 @@
+import type { ObserveHandle } from "./index";
+export { escortedManifest } from "./manifest";
+type Env = Record<string, string | undefined>;
+/** Install undici's env-proxy dispatcher so global fetch honors HTTPS_PROXY.
+ *  No-op when no proxy is configured or undici is not resolvable (fail-open). */
+export declare function installProxyDispatcher(env?: Env): void;
+/** Arm the shim from BOUNDED_* env. Returns the ObserveHandle from init(), or
+ *  undefined if @bounded-sh/observe could not initialize (never throws). */
+export declare function bootstrapFromEnv(env?: Env): ObserveHandle | undefined;

package/dist/register.js

@@ -0,0 +1,138 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// register.ts -- the env-driven --require/--import PRELOAD entrypoint for the
+// Bounded escort (SPEC §3.1e, T9). Arms the shim from BOUNDED_* env with ZERO
+// changes to the customer app:
+//
+//   node --require @bounded-sh/observe/register app.js      (CJS)
+//   node --import  @bounded-sh/observe/register app.js      (ESM interop)
+//
+// This is a SIDE-EFFECT module: importing/requiring it runs bootstrapFromEnv()
+// once (unless BOUNDED_REGISTER_AUTOSTART=0, which the unit tests set so they can
+// drive bootstrapFromEnv explicitly). It does two things, in order:
+//
+//   1. PROXY-AWARENESS. Node's global fetch (undici) does NOT honor HTTPS_PROXY
+//      by default. Behind an egress sidecar we install undici's
+//      EnvHttpProxyAgent so every fetch (the app's rail calls AND the shim's
+//      verdict/settle/ingest calls) tunnels through the sidecar (CONNECT, no
+//      MITM). The escort still fires the call from THIS process (T9).
+//   2. ESCORT ARMING. init() with an env-derived escort PIN (escortPin) for
+//      the built-in Stripe-refund recognizer (mirrors the reference mapping).
+//      The pin is applied over the built-in manifest at init AND re-applied
+//      over every fetched manifest swap (60s poll stays LIVE), so a served
+//      manifest can never silently drop enforcement; a fetched escort block
+//      on the pinned route wins over the pin. Without BOUNDED_VERDICT_URL we
+//      init OBSERVE-only (report egress, escort nothing).
+//
+// The shim NEVER breaks the app: every failure here is logged and swallowed.
+// This is the canonical source; packages/observe-container/bootstrap/register.cjs
+// is a thin delegator that just requires @bounded-sh/observe/register.
+//
+// Env (all optional except a sensor token to authenticate):
+//   BOUNDED_VERDICT_URL        https://<org>.bounded.sh/api/verdict (arms escort)
+//   BOUNDED_SENSOR_TOKEN       obs1.<keyId>.<sig> (verdict auth + report auth)
+//   BOUNDED_ORG                org slug (manifest polling only)
+//   BOUNDED_INGEST_BASE        default prod observe-ingest
+//   BOUNDED_COLLECTION         escort collection (default stripeRefunds)
+//   BOUNDED_FAIL_MODE          closed|open (default closed; SPEC U18)  [alias BOUNDED_FAILMODE]
+//   BOUNDED_FLUSH_MS           report flush cadence, ms (default 2000)
+//   BOUNDED_VERDICT_TIMEOUT_MS verdict round-trip timeout, ms (capped 30000)
+//   BOUNDED_DEBUG=1            shim debug logging
+//   BOUNDED_OBSERVE_DISABLED=1 kill switch (shim honors it directly)
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escortedManifest = void 0;
+exports.installProxyDispatcher = installProxyDispatcher;
+exports.bootstrapFromEnv = bootstrapFromEnv;
+const index_1 = require("./index");
+// Re-exported for compatibility: the pin transformation lives in manifest.ts
+// so the shim core can re-apply it over fetched manifests without importing
+// this side-effect module.
+var manifest_1 = require("./manifest");
+Object.defineProperty(exports, "escortedManifest", { enumerable: true, get: function () { return manifest_1.escortedManifest; } });
+const TAG = "[bounded-observe]";
+function log(msg) {
+    try {
+        process.stderr.write(`${TAG} ${msg}\n`);
+    }
+    catch {
+        /* ignore */
+    }
+}
+const DEFAULT_INGEST = "https://observe-ingest.buildwithtarobase.workers.dev";
+function redactProxy(p) {
+    // Proxy URLs rarely hold secrets, but strip any userinfo defensively.
+    try {
+        const u = new URL(p);
+        u.username = "";
+        u.password = "";
+        return u.toString();
+    }
+    catch {
+        return "set";
+    }
+}
+/** Install undici's env-proxy dispatcher so global fetch honors HTTPS_PROXY.
+ *  No-op when no proxy is configured or undici is not resolvable (fail-open). */
+function installProxyDispatcher(env = process.env) {
+    const proxy = env.HTTPS_PROXY || env.https_proxy || env.HTTP_PROXY || env.http_proxy;
+    if (!proxy)
+        return;
+    try {
+        // Dynamic require: undici is a Node runtime module, not a package dependency.
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const undici = require("undici");
+        undici.setGlobalDispatcher(new undici.EnvHttpProxyAgent());
+        log(`proxy dispatcher enabled (fetch honors HTTPS_PROXY=${redactProxy(proxy)})`);
+    }
+    catch (err) {
+        // Non-fatal: without a dispatcher, fetch ignores the proxy and (behind a
+        // default-deny egress network) simply fails closed — never a silent bypass.
+        log(`WARN could not enable proxy dispatcher: ${err?.message}`);
+    }
+}
+/** Arm the shim from BOUNDED_* env. Returns the ObserveHandle from init(), or
+ *  undefined if @bounded-sh/observe could not initialize (never throws). */
+function bootstrapFromEnv(env = process.env) {
+    try {
+        installProxyDispatcher(env);
+        const verdictUrl = env.BOUNDED_VERDICT_URL || "";
+        const collection = env.BOUNDED_COLLECTION || "stripeRefunds";
+        const failMode = String(env.BOUNDED_FAIL_MODE || env.BOUNDED_FAILMODE || "closed").toLowerCase() === "open"
+            ? "open"
+            : "closed";
+        const flushMsRaw = Number(env.BOUNDED_FLUSH_MS);
+        const flushIntervalMs = Number.isFinite(flushMsRaw) && flushMsRaw > 0 ? flushMsRaw : undefined;
+        const timeoutRaw = Number(env.BOUNDED_VERDICT_TIMEOUT_MS);
+        const timeoutMs = Number.isFinite(timeoutRaw) && timeoutRaw > 0 ? Math.min(timeoutRaw, 30_000) : undefined;
+        const cfg = {
+            ingestBase: env.BOUNDED_INGEST_BASE || DEFAULT_INGEST,
+            token: env.BOUNDED_SENSOR_TOKEN || "obs1.unset.unset",
+            org: env.BOUNDED_ORG || undefined,
+            debug: env.BOUNDED_DEBUG === "1",
+            ...(flushIntervalMs ? { flushIntervalMs } : {}),
+        };
+        if (verdictUrl) {
+            // Escort PIN (not a manifest override): applied over the built-in at
+            // init and re-applied over every fetched swap, with the 60s manifest
+            // poll left LIVE so broader/multi-rail escort (incl. llm-gateway) can
+            // still arrive server-side via the promoted manifest.
+            cfg.escortPin = { verdictUrl, collection, failMode, ...(timeoutMs ? { timeoutMs } : {}) };
+        }
+        const handle = (0, index_1.init)(cfg);
+        log(verdictUrl
+            ? `escort ARMED -> collection=${collection} failMode=${failMode} verdict=${verdictUrl}`
+            : "observe-only (no BOUNDED_VERDICT_URL) — reporting egress, escorting nothing");
+        return handle;
+    }
+    catch (err) {
+        log(`WARN observe init failed (app continues): ${err?.message}`);
+        return undefined;
+    }
+}
+// Auto-arm on load (the --require/--import entrypoint). Guarded so unit tests can
+// import the exported helpers WITHOUT the global-patch side effect
+// (BOUNDED_REGISTER_AUTOSTART=0). Real preloads never set that flag.
+if (process.env.BOUNDED_REGISTER_AUTOSTART !== "0") {
+    bootstrapFromEnv();
+}

package/dist/reporter.d.ts

@@ -0,0 +1,27 @@
+import type { InternalEvent } from "./types";
+export declare class Reporter {
+    private readonly maxQueue;
+    private readonly sendTimeoutMs;
+    private queue;
+    private retry;
+    /** In-flight send (single-flight). drain() AWAITS it — never abandons it. */
+    private inFlight;
+    private immediateScheduled;
+    /** Drops awaiting report on the next batch's first event. */
+    pendingDrops: number;
+    totalDropped: number;
+    sentEvents: number;
+    sentBatches: number;
+    sendFailures: number;
+    constructor(maxQueue: number, sendTimeoutMs: number);
+    get queueDepth(): number;
+    countDrop(n?: number): void;
+    push(ev: InternalEvent): void;
+    /** Send at most one batch. Single-flight; never throws. */
+    flushOnce(): Promise<void>;
+    /** Drain everything (graceful shutdown / tests). WAITS for any in-flight
+     * send first — a shutdown never abandons a batch mid-air. Never throws. */
+    drain(): Promise<void>;
+    private takeBatch;
+    private sendNext;
+}