@bounded-sh/observe 0.1.0 → 0.1.2

package/README.md

@@ -116,9 +116,38 @@ microseconds (measured in `test/perf.test.ts`; U2 target <1ms p99).
 - **Node 18 / 20 / 22 server apps** (fetch + http/https interception).
 - **Vercel / Next.js Node runtime**: supported (call `init()` in
   `instrumentation.ts` or the server entry).
-- **Edge runtimes** (Vercel Edge, Workers): **fetch-wrap only** — `http/https`
-  and `AsyncLocalStorage`-based middleware depend on Node APIs; use `runAs`
-  with the fetch path only. (Documented limitation, SPEC §3.1a.)
+- **Edge runtimes** (Cloudflare Workers, Vercel Edge, Deno Deploy): the root
+  entry cannot load there (it needs `node:async_hooks`, `node:crypto`, and
+  http/https patching) — use the **`@bounded-sh/observe/edge`** subpath
+  instead (below).
+
+## Edge emitter (`@bounded-sh/observe/edge`)
+
+For code that already sits at a chokepoint (a Worker proxy, an API gateway)
+and wants to REPORT events rather than intercept egress. No queue, no timers,
+no patching — one fire-and-forget envelope-v2 POST per call:
+
+```ts
+import { emitEvent } from "@bounded-sh/observe/edge";
+
+emitEvent(
+  { ingestUrl: env.BOUNDED_INGEST_URL, sensorToken: env.BOUNDED_SENSOR_TOKEN },
+  {
+    class: "action",
+    actor: { id: tenantId, kind: "service", grade: "attested" },
+    dest: { host: "api.anthropic.com", pathTemplate: "/v1/messages", method: "POST" },
+    status: 200, dur_ms: 0, bytes: { i: 0, o: 0 },
+    rec: { rail: "llm-gateway", action: "acme.tenant.aiRun", registryVersion: "acme-proxy",
+           fields: { actualCents, "usage.input_tokens": inTok, "usage.output_tokens": outTok } },
+  },
+  ctx, // optional Workers ExecutionContext — the POST rides ctx.waitUntil
+);
+```
+
+Posture: NO-OP unless both `ingestUrl` and `sensorToken` are present (delete
+the secret = kill switch); `postEvent` never rejects; the POST is bounded by
+`timeoutMs` (default 2000 ms); `org`/`sensor` are never sent — the ingest
+stamps both server-authoritatively from the sensor key.
 
 Notes: `http/https` path records duration to response *headers* and takes
 `bytes.o` from `Content-Length` (0 when chunked); response-field recognition

package/dist/edge.d.ts

@@ -0,0 +1,44 @@
+import { EVENT_SCHEMA_VERSION, MAX_BATCH_EVENTS, type ObserveEventV1 } from "./envelope";
+export { EVENT_SCHEMA_VERSION, MAX_BATCH_EVENTS };
+export type { ObserveEventV1, EventClass, EventActor, EventDest, EventBytes, EventRec, RecFields, RecFieldValue, } from "./envelope";
+/** Everything the emitter needs; a missing url/token makes it a NO-OP. */
+export interface EdgeEmitterConfig {
+    /** Observe-ingest base URL (POST <ingestUrl>/v1/events). */
+    ingestUrl?: string | null;
+    /** Org sensor bearer token (obs1.<keyId>.<sig>). */
+    sensorToken?: string | null;
+    /** Upper bound on one emission POST (default EDGE_EMIT_TIMEOUT_MS). Short
+     *  by design: a slow ingest must never pin a waitUntil task for long. */
+    timeoutMs?: number;
+    /** Custom fetch (tests, service bindings). Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+/** Default upper bound on one emission POST. */
+export declare const EDGE_EMIT_TIMEOUT_MS = 2000;
+/** What callers build: the frozen v2 envelope minus the pieces this module
+ *  stamps (`v`, `ts` defaulted) or that MUST stay absent (`org`/`sensor` —
+ *  server-authoritative from the key; `scrubbed` — server-set). */
+export type EdgeObserveEvent = Omit<ObserveEventV1, "v" | "org" | "sensor" | "ts" | "scrubbed"> & {
+    ts?: number;
+};
+/** The bytes that go on the wire: `v` stamped, `ts` defaulted, org/sensor absent. */
+export type WireObserveEvent = Omit<ObserveEventV1, "org" | "sensor" | "scrubbed">;
+/** True iff the config is complete (the emitter will actually fire). */
+export declare function edgeEmitConfigured(cfg: EdgeEmitterConfig | null | undefined): boolean;
+/** Stamp `v` and default `ts` on a caller-built event. Pure. */
+export declare function buildEvent(event: EdgeObserveEvent): WireObserveEvent;
+/**
+ * POST one event (or a small batch, capped at MAX_BATCH_EVENTS) to
+ * `<ingestUrl>/v1/events`. Resolves `true` iff ingest 2xx'd; NEVER rejects.
+ * Await it inside your own `ctx.waitUntil` task when composing (e.g.
+ * lookup-then-emit); use `emitEvent` for the common one-shot case.
+ */
+export declare function postEvent(cfg: EdgeEmitterConfig | null | undefined, event: EdgeObserveEvent | EdgeObserveEvent[]): Promise<boolean>;
+/**
+ * Fire ONE event (or batch), fully detached: no-op on missing config, rides
+ * `ctx.waitUntil` when a Workers execution context is given (floated
+ * otherwise), and guaranteed to never throw into the request path.
+ */
+export declare function emitEvent(cfg: EdgeEmitterConfig | null | undefined, event: EdgeObserveEvent | EdgeObserveEvent[], ctx?: {
+    waitUntil(p: Promise<unknown>): void;
+}): void;

package/dist/edge.js

@@ -0,0 +1,107 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// edge.ts -- Worker/edge-native emitter ("@bounded-sh/observe/edge").
+//
+// The package root is a LONG-LIVED-PROCESS shim: it patches fetch/http, runs
+// a batch queue and flush timers, and hard-depends on Node builtins
+// (node:async_hooks, node:crypto). Edge runtimes (Cloudflare Workers, Deno
+// Deploy, Vercel Edge) cannot import it. This entry is the opposite posture:
+// ONE fire-and-forget envelope-v2 event per call, no queue, no timers, no
+// interception, no imports beyond the frozen ./envelope mirror — safe to
+// bundle anywhere `fetch` and `AbortSignal.timeout` exist.
+//
+// Contract (same fail-open posture as the platform emitter in
+// observe-shared/src/emitter.ts and the shim reporter):
+//   * NO-OP unless both {ingestUrl, sensorToken} are present — a consumer
+//     without config costs nothing and emits nothing. Deleting the sensor
+//     token secret is the kill switch.
+//   * `org` and `sensor` are NEVER sent: the ingest stamps both
+//     server-authoritatively from the sensor key (a mismatched body `org`
+//     would be rejected; omitting it is the one-correct-way).
+//   * postEvent NEVER rejects; every failure (missing config, network error,
+//     timeout, non-2xx) resolves `false`. Observing is reporting, not
+//     protection — an ingest outage must cost the caller nothing beyond
+//     `timeoutMs`.
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EDGE_EMIT_TIMEOUT_MS = exports.MAX_BATCH_EVENTS = exports.EVENT_SCHEMA_VERSION = void 0;
+exports.edgeEmitConfigured = edgeEmitConfigured;
+exports.buildEvent = buildEvent;
+exports.postEvent = postEvent;
+exports.emitEvent = emitEvent;
+const envelope_1 = require("./envelope");
+Object.defineProperty(exports, "EVENT_SCHEMA_VERSION", { enumerable: true, get: function () { return envelope_1.EVENT_SCHEMA_VERSION; } });
+Object.defineProperty(exports, "MAX_BATCH_EVENTS", { enumerable: true, get: function () { return envelope_1.MAX_BATCH_EVENTS; } });
+/** Default upper bound on one emission POST. */
+exports.EDGE_EMIT_TIMEOUT_MS = 2_000;
+/** True iff the config is complete (the emitter will actually fire). */
+function edgeEmitConfigured(cfg) {
+    return !!(cfg && cfg.ingestUrl && cfg.sensorToken);
+}
+/** Stamp `v` and default `ts` on a caller-built event. Pure. */
+function buildEvent(event) {
+    const { ts, ...rest } = event;
+    return {
+        v: envelope_1.EVENT_SCHEMA_VERSION,
+        ts: typeof ts === "number" ? ts : Date.now(),
+        ...rest,
+    };
+}
+/**
+ * POST one event (or a small batch, capped at MAX_BATCH_EVENTS) to
+ * `<ingestUrl>/v1/events`. Resolves `true` iff ingest 2xx'd; NEVER rejects.
+ * Await it inside your own `ctx.waitUntil` task when composing (e.g.
+ * lookup-then-emit); use `emitEvent` for the common one-shot case.
+ */
+async function postEvent(cfg, event) {
+    try {
+        if (!edgeEmitConfigured(cfg))
+            return false; // NO-OP (inert-by-flag)
+        const list = Array.isArray(event) ? event.slice(0, envelope_1.MAX_BATCH_EVENTS) : [event];
+        if (list.length === 0)
+            return false;
+        const events = list.map(buildEvent);
+        const url = String(cfg.ingestUrl).replace(/\/$/, "") + "/v1/events";
+        const doFetch = cfg.fetchImpl ?? fetch;
+        const timeoutMs = typeof cfg.timeoutMs === "number" && cfg.timeoutMs > 0 ? cfg.timeoutMs : exports.EDGE_EMIT_TIMEOUT_MS;
+        const res = await doFetch(url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${cfg.sensorToken}`,
+            },
+            body: JSON.stringify({ events }),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        return res.ok;
+    }
+    catch {
+        return false; // fire-and-forget: an emit failure is invisible to the caller
+    }
+}
+/**
+ * Fire ONE event (or batch), fully detached: no-op on missing config, rides
+ * `ctx.waitUntil` when a Workers execution context is given (floated
+ * otherwise), and guaranteed to never throw into the request path.
+ */
+function emitEvent(cfg, event, ctx) {
+    try {
+        if (!edgeEmitConfigured(cfg))
+            return; // NO-OP (inert-by-flag)
+        const task = postEvent(cfg, event);
+        if (ctx && typeof ctx.waitUntil === "function") {
+            try {
+                ctx.waitUntil(task);
+            }
+            catch {
+                void task;
+            }
+        }
+        else {
+            void task;
+        }
+    }
+    catch {
+        /* can never throw into the hot path */
+    }
+}

package/dist/manifest.js

@@ -95,10 +95,43 @@ const CRYPTO_RECOGNIZERS = [
     ...rpcRecognizers("solana", SOLANA_RPC_HOSTS, SOLANA_RPC_METHODS),
     ...rpcRecognizers("evm", EVM_RPC_HOSTS, EVM_RPC_METHODS),
 ];
+// ---------------------------------------------------------------------------
+// Wallet-watch recognizers (rails: solana, evm) — the "Crypto wallets" data
+// source. These match a SYNTHETIC destination host "wallet-watch.bounded.sh"
+// that no real egress can ever reach (the same pattern the data plane uses for
+// data.bounded.sh): events are minted SERVER-SIDE by org-host's wallet-watch
+// poller (bounded-org-host/src/wallet-watch.ts) from public onchain history,
+// with `rec` PRE-STAMPED to these action/rail pairs. The shim never emits these
+// (the host is not a real API), so listing them here only makes ingest's
+// server-side re-recognition table AGREE with the poller's stamp (no
+// serverMismatch). observe-only, like the rest of the crypto rails.
+//
+// The `responseFields` document the SAFE scalars the poller carries in
+// rec.fields (all public onchain data). NOTE: the tracked address rides
+// rec.fields.wallet (NOT `address` — the L2 key denylist hard-denies /address/)
+// and, raw, on the envelope's onBehalfOf attribution slot.
+const WALLET_WATCH_RECOGNIZERS = [
+    {
+        host: "wallet-watch.bounded.sh",
+        method: "POST",
+        path: "/solana/tx",
+        rail: "solana",
+        action: "solana.wallet.tx",
+        responseFields: ["wallet", "chain", "direction", "amountLamports", "txSig", "counterparty"],
+    },
+    {
+        host: "wallet-watch.bounded.sh",
+        method: "POST",
+        path: "/evm/tx",
+        rail: "evm",
+        action: "evm.wallet.tx",
+        responseFields: ["wallet", "chain", "direction", "valueWei", "txHash", "counterparty"],
+    },
+];
 /** Built-in default manifest: metadata-only + curated safe-field recognizers.
  * SAFE fields only: amounts (cents), opaque IDs, model names, token counts. */
 exports.BUILTIN_MANIFEST = {
-    version: "builtin-0.3.0",
+    version: "builtin-0.4.0",
     recognizers: [
         // --- Stripe (rail: stripe). Amounts are already in cents. -------------
         {
@@ -590,6 +623,8 @@ exports.BUILTIN_MANIFEST = {
         },
         // --- Crypto RPC (rails: solana, evm) — rpcMethod-matched, observe-only. --
         ...CRYPTO_RECOGNIZERS,
+        // --- Wallet-watch (rails: solana, evm) — synthetic dest, server-emitted. -
+        ...WALLET_WATCH_RECOGNIZERS,
     ],
     counters: [],
     mutes: [],

package/dist/pipeline.js

@@ -169,6 +169,13 @@ class Pipeline {
             this.reporter.push({ wire, fields });
             return;
         }
+        // Bounded-only capture (the app-dev / skill default, "bounded stuff only"):
+        // send ONLY recognized-by-fixtures events + explicit counter routes. Drop
+        // every UNrecognized route here — no shape sample, no heuristic counter — so
+        // nothing about traffic Bounded doesn't already recognize ever leaves the
+        // process. BOUNDED_CAPTURE_SCOPE=all re-enables discovery (shapes/counters).
+        if (state_1.state.config?.captureScope === "recognized")
+            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);

package/dist/register.js

@@ -32,6 +32,9 @@
 //   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_CAPTURE_SCOPE      bounded|recognized => send only recognized events
+//                              + counters (app-dev default); all => full capture
+//                              incl. unknown-route shape discovery (unset => all)
 //   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]
@@ -105,11 +108,18 @@ function bootstrapFromEnv(env = process.env) {
         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;
+        // Capture scope: "bounded"/"recognized" => send only recognized-by-fixtures
+        // events + counter routes (the app-dev / skill default). Anything else (or
+        // unset) => "all" (full capture incl. unknown-route shape discovery).
+        const scopeRaw = String(env.BOUNDED_CAPTURE_SCOPE || "").toLowerCase();
+        const captureScope = scopeRaw === "recognized" || scopeRaw === "bounded" ? "recognized"
+            : scopeRaw === "all" ? "all" : 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",
+            ...(captureScope ? { captureScope } : {}),
             ...(flushIntervalMs ? { flushIntervalMs } : {}),
         };
         if (verdictUrl) {

package/dist/types.d.ts

@@ -83,6 +83,16 @@ export interface ObserveConfig {
     counterPromoteThreshold?: number;
     /** Max new shape samples emitted per minute (default 30). */
     shapesPerMinute?: number;
+    /**
+     * What to send. "all" (default): recognized events + counters + UNrecognized
+     * shape samples (needed for the classification loop). "recognized" (the
+     * app-dev / skill default, "bounded stuff only"): recognized-by-fixtures
+     * events + explicit counter routes ONLY — unknown external routes are neither
+     * sampled nor counted, so nothing about traffic Bounded doesn't already
+     * recognize ever leaves the process. Turn on full capture with
+     * BOUNDED_CAPTURE_SCOPE=all when you want to discover/classify new routes.
+     */
+    captureScope?: "recognized" | "all";
     /** Manifest override (tests/dev). Skips the built-in + polling when set. */
     manifest?: unknown;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bounded-sh/observe",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Bounded observe shim for Node: intercepts fetch + http/https egress, attributes actors, reports metadata-only events to the Bounded observe ingest. Never breaks the app.",
   "license": "MIT",
   "private": false,
@@ -19,6 +19,11 @@
       "types": "./dist/register.d.ts",
       "require": "./dist/register.js",
       "import": "./dist/register.js"
+    },
+    "./edge": {
+      "types": "./dist/edge.d.ts",
+      "require": "./dist/edge.js",
+      "import": "./dist/edge.js"
     }
   },
   "files": [