@bounded-sh/observe 0.1.0

package/README.md

@@ -0,0 +1,167 @@
+# @bounded-sh/observe — Bounded observe shim for Node
+
+CP1 origin for the observe/enforce project (`SPEC-OBSERVE-ENFORCE-CUSTODY.md`
+§3.1a). Intercepts your service's **egress** — `globalThis.fetch` (undici) and
+`http`/`https.request` — and reports metadata-only event batches to the
+Bounded observe ingest. Dependency-free at runtime. **Never breaks the app**:
+every shim code path is wrapped; original behavior is always preserved;
+observe is always fail-open (Bounded down ⇒ nothing changes for your app, T9).
+
+## Install
+
+```bash
+npm install @bounded-sh/observe
+```
+
+```js
+const { init, middleware, runAs } = require("@bounded-sh/observe");
+
+init({
+  ingestBase: "https://observe-ingest.buildwithtarobase.workers.dev",
+  token: process.env.BOUNDED_SENSOR_TOKEN, // obs1.<keyId>.<sig>
+  org: "your-org",
+});
+```
+
+That's the whole install: call `init()` once, as early as possible (before
+other modules grab references to `fetch`). ESM: `import { init } from
+"@bounded-sh/observe"`.
+
+## Actor context — who did it
+
+Attribution rides the **report only**; nothing is ever added to your outbound
+requests (any `X-Bounded-*` header is actively **stripped from egress** and
+used purely as attribution fallback).
+
+```js
+// Per-request (Express or Hono): maps your session to an actor for the whole
+// request's async chain.
+app.use(middleware());                       // default: req.session.user / req.user
+app.use(middleware((req) => ({ actor: req.session.user.id, kind: "human" })));
+
+// Explicit scope (bots, jobs, agents):
+await runAs({ actor: "agent:support-1", kind: "agent", onBehalfOf: customerId }, async () => {
+  await stripe.refunds.create({ charge, amount }); // reported as agent:support-1
+});
+```
+
+Actor ids should be **opaque internal ids, never emails** (L9 — the ingest
+scrubber redacts email-shaped values as suspected PII). Unattributed calls are
+still captured (they roll up under the `unattributed` pseudo-actor).
+
+## What's captured vs. NOT (PII posture)
+
+Captured (metadata only, per event): destination host, **templated** path
+(UUIDs / numeric ids / hashes / vendor ids become `{id}` before anything
+leaves your process), method, status, duration, byte counts, actor context.
+
+Manifest-recognized routes (built-in v0 registry: Stripe
+refunds/charges/payment_intents; OpenAI + Anthropic spend) additionally
+recognize **safe fields only**: amounts in cents, opaque ids (`ch_…`,
+`cus_…`), model names, token counts. As of **envelope v2** these ride the wire
+under `rec.fields` (a bounded, one-level object of primitive SAFE values) —
+`rec{rail, action, registryVersion, fields}` — and drive deterministic action
+stories on the dashboard. They also remain available locally via the `onEvent`
+hook. Server-side, ingest re-checks `rec.fields` KEYS against the L2 denylist
+and scrubs the VALUES (L4), so a leaked email/PAN never lands raw.
+
+NOT captured, ever:
+- request/response **bodies** (unrecognized routes: top-level field
+  **names/types only**, on the first sighting of a shape);
+- query-string **values** (names only, on shape samples);
+- headers (only scanned to strip `X-Bounded-*`);
+- prompts/completions/messages of LLM calls (not in any safe-field list);
+- **PII-named fields — hard denylist (L2)**: `email`, `card*`, `*_name`,
+  `password`, `*token` (auth-shaped; token *counts* are fine), `address`,
+  `ssn`, `dob`, … are compiled into the shim and re-checked at extraction
+  time. Even a malicious/buggy manifest listing `customer_email` cannot
+  capture it, and even the *names* of PII-shaped fields are dropped from
+  shape samples.
+
+Fail-safe: no/invalid manifest ⇒ metadata-only mode. Server side, ingest
+re-filters (L3) and value-scrubs (L4) independently — the shim never sends
+`org`/`sensor` (server-stamped from your sensor key), `scrubbed`, or any
+unknown field.
+
+Honest counts: if the shim ever drops events (bounded memory, backpressure),
+the drop count is reported on the next successful event (`dropped`) and
+surfaces downstream as completeness flags.
+
+## Event classes (SPEC §3.2)
+
+| class   | when                                     | notes |
+|---------|------------------------------------------|-------|
+| action  | recognized route, 2xx                    | `rec{rail, action, registryVersion, fields}` (v2 `rec.fields` = SAFE values) |
+| error   | recognized route, non-2xx / network fail | `rec{…, fields}`; status 0 = never completed |
+| shape   | unrecognized route, first sighting       | deduped in-memory, rate-capped, names/types only |
+| counter | manifest `counters` matchers + hot unrecognized GETs (> 60 calls/min, exact from call #1) | one event per (route, minute): exact count, summed dur/bytes, class-representative status |
+
+## Kill switch
+
+`BOUNDED_OBSERVE_DISABLED=1`
+- at process start: nothing is patched at all;
+- at runtime: observation stops within one flush tick (≤2s). Clearing the env
+  resumes it.
+
+## Reporting behavior
+
+Async batches (≤500 events or 2s), fire-and-forget with a 5s send timeout,
+single in-flight send, one retry for transient failures, bounded queue
+(default 5000 events) with drop-and-count on overflow. `shutdown()` performs
+a final drain (call it on SIGTERM to flush the tail). Hot-path overhead is
+microseconds (measured in `test/perf.test.ts`; U2 target <1ms p99).
+
+## Supported environments
+
+- **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.)
+
+Notes: `http/https` path records duration to response *headers* and takes
+`bytes.o` from `Content-Length` (0 when chunked); response-field recognition
+(LLM token counts) is fetch-path only.
+
+## Config quick reference
+
+```ts
+init({
+  ingestBase, token,            // required
+  org,                          // manifest polling scope
+  sessionMapper,                // default mapper for middleware()
+  aliasHosts,                   // {"127.0.0.1:4242": "api.stripe.com"} — dev/demo
+  flushIntervalMs: 2000, sendTimeoutMs: 5000, maxQueueEvents: 5000,
+  counterPromoteThreshold: 60,  // unrecognized-GET calls/min -> counter class
+  shapesPerMinute: 30,          // new-shape rate cap
+  manifest,                     // override (tests); invalid -> built-in (fail-safe)
+  disableManifestPoll, manifestPollMs,
+  debug, onEvent,               // debug hook: (wireEvent, recognizedFields)
+});
+```
+
+## Manifest (living capture policy, §3.1g)
+
+The shim polls `<ingestBase>/v1/manifest?org=…` every 60s (T1: capture policy
+changes reach every interceptor without re-install). The endpoint doesn't
+exist yet — 404/invalid keeps the built-in manifest. Signed-manifest
+verification is a marked TODO in `src/manifest.ts`; until it lands, the
+built-in registry is the trust anchor.
+
+## Development
+
+- `npm run build` · `npm test` (76 tests: interception, templating,
+  recognizers, counters, ALS context, header stripping, kill switch, L1/L2
+  PII behavior, envelope contract vs the real `observe-shared` validator,
+  perf, and an integration run of the sample app in
+  `~/bounded/observe-sample-app`).
+- `npm run test:live` — LIVE prod verification: mints a dev sensor key
+  (needs `/tmp/observe-admin-secret.txt` or `$OBSERVE_ADMIN_SECRET`), runs
+  the sample app against prod ingest, asserts exact rollup deltas via the
+  consumer's `/internal/rollup/acme-demo`.
+- Wire contract: `src/envelope.ts` mirrors the versioned envelope (v2) from
+  `packages/cdk/cloudflare/observe-shared`; `test/envelope-contract.test.ts`
+  fails on any drift (types + constants + runtime validation), including that
+  every emitted v2 event (with `rec.fields`) passes the real ingest validator
+  with ZERO stripped fields.

package/dist/context.d.ts

@@ -0,0 +1,18 @@
+import type { ActorContext, ActorInput, SessionMapper } from "./types";
+/** Current actor context, if any (interceptors read this at call time). */
+export declare function currentActor(): ActorContext | undefined;
+/**
+ * Run `fn` attributed to an actor. The context follows the async chain, so
+ * every intercepted egress inside (awaited or fire-and-forget started within
+ * `fn`) reports this actor. Returns fn's return value; errors propagate
+ * unchanged (app semantics are never altered).
+ */
+export declare function runAs<T>(input: ActorInput, fn: () => T): T;
+/**
+ * Request middleware establishing actor context for the whole request.
+ * Express: app.use(bounded.middleware()) — (req, res, next).
+ * Hono:    app.use(bounded.middleware(mapper)) — (c, next), promise returned.
+ * The mapper receives the framework-native request object (Express `req` /
+ * Hono `Context`); Hono users should pass an explicit mapper.
+ */
+export declare function middleware(mapper?: SessionMapper): (a: unknown, b: unknown, c?: unknown) => unknown;

package/dist/context.js

@@ -0,0 +1,105 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// context.ts -- actor attribution context (SPEC §3.1f, the "who" pillar).
+//
+// AsyncLocalStorage carries {actor, onBehalfOf, kind} across the async chain.
+// The context rides the REPORT only — it is never added to third-party egress
+// (interceptors additionally STRIP any X-Bounded-* header from real egress).
+//
+// runAs() and middleware() must NEVER break the app: mapper/normalization
+// errors fall back to running the wrapped function without context.
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.currentActor = currentActor;
+exports.runAs = runAs;
+exports.middleware = middleware;
+const node_async_hooks_1 = require("node:async_hooks");
+const state_1 = require("./state");
+const als = new node_async_hooks_1.AsyncLocalStorage();
+const KINDS = ["human", "agent", "service", "unknown"];
+function normalize(input, defaultKind) {
+    if (!input || typeof input.actor !== "string" || input.actor.length === 0)
+        return undefined;
+    const kind = typeof input.kind === "string" && KINDS.includes(input.kind) ? input.kind : defaultKind;
+    const ctx = { id: input.actor.slice(0, 256), kind };
+    if (typeof input.onBehalfOf === "string" && input.onBehalfOf.length > 0) {
+        ctx.onBehalfOf = input.onBehalfOf.slice(0, 256);
+    }
+    return ctx;
+}
+/** Current actor context, if any (interceptors read this at call time). */
+function currentActor() {
+    try {
+        return als.getStore();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Run `fn` attributed to an actor. The context follows the async chain, so
+ * every intercepted egress inside (awaited or fire-and-forget started within
+ * `fn`) reports this actor. Returns fn's return value; errors propagate
+ * unchanged (app semantics are never altered).
+ */
+function runAs(input, fn) {
+    let ctx;
+    try {
+        ctx = normalize(input, "unknown");
+    }
+    catch {
+        ctx = undefined;
+    }
+    return ctx ? als.run(ctx, fn) : fn();
+}
+/** Default session -> actor mapper: duck-types common Express shapes. */
+function defaultMapper(req) {
+    const r = req;
+    if (!r || typeof r !== "object")
+        return null;
+    // Explicit escape hatch: req.boundedActor = {actor, kind?, onBehalfOf?} | string
+    const explicit = r.boundedActor;
+    if (typeof explicit === "string")
+        return { actor: explicit };
+    if (explicit && typeof explicit.actor === "string")
+        return explicit;
+    const sessionUser = r.session?.user;
+    const user = sessionUser ?? r.user;
+    if (user) {
+        const id = user.id ?? user.userId ?? user.email;
+        if (typeof id === "string" && id.length > 0)
+            return { actor: id, kind: "human" };
+    }
+    return null;
+}
+/**
+ * Request middleware establishing actor context for the whole request.
+ * Express: app.use(bounded.middleware()) — (req, res, next).
+ * Hono:    app.use(bounded.middleware(mapper)) — (c, next), promise returned.
+ * The mapper receives the framework-native request object (Express `req` /
+ * Hono `Context`); Hono users should pass an explicit mapper.
+ */
+function middleware(mapper) {
+    return function boundedObserveMiddleware(a, b, c) {
+        const isExpress = typeof c === "function";
+        const next = isExpress
+            ? c
+            : typeof b === "function"
+                ? b
+                : undefined;
+        if (!next)
+            return undefined; // unrecognized signature: do nothing, never throw
+        let ctx;
+        try {
+            const m = mapper ?? state_1.state.config?.sessionMapper ?? defaultMapper;
+            ctx = normalize(m(a) ?? undefined, "human");
+        }
+        catch (err) {
+            (0, state_1.debugLog)("middleware mapper failed", err);
+            ctx = undefined;
+        }
+        // next() runs INSIDE the ALS scope so the entire downstream async chain
+        // (route handlers, their egress) carries the actor.
+        return ctx ? als.run(ctx, () => next()) : next();
+    };
+}

package/dist/counters.d.ts

@@ -0,0 +1,34 @@
+export interface CounterKeyParts {
+    host: string;
+    method: string;
+    pathTemplate: string;
+}
+export interface CounterEmit extends CounterKeyParts {
+    windowStart: number;
+    windowSeconds: number;
+    /** Event ts = window end (or `now` for forced partial flush). */
+    ts: number;
+    count: number;
+    durMsSum: number;
+    bytesInSum: number;
+    bytesOutSum: number;
+    /** Class-representative status: 200 | 400 | 500 | 0. */
+    status: number;
+}
+export declare class CounterAggregator {
+    private promoteThreshold;
+    private entries;
+    private promoted;
+    constructor(promoteThreshold: number);
+    private routeKey;
+    isPromoted(p: CounterKeyParts): boolean;
+    /** Aggregate one call. `provisional` = heuristic tally (unrecognized GET). */
+    add(p: CounterKeyParts, ts: number, status: number, durMs: number, bytesIn: number, bytesOut: number, provisional: boolean): void;
+    /**
+     * Emit closed windows (or everything when `force`, e.g. shutdown).
+     * Provisional tallies below the promote threshold are discarded.
+     */
+    flush(now: number, force?: boolean): CounterEmit[];
+    /** Test/diagnostic helper. */
+    size(): number;
+}

package/dist/counters.js

@@ -0,0 +1,141 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// counters.ts -- exact per-minute counter aggregation (SPEC §3.2).
+//
+// One counter event per (route, minute-window): exact count + SUMMED
+// dur_ms/bytes + class-representative status. Two entry modes:
+//   * forced   — manifest `counters` matchers: always aggregate, always emit.
+//   * provisional — the unrecognized-GET heuristic: every unrecognized GET is
+//     tallied from call #1; at window close, tallies >= threshold emit (exact
+//     — nothing was lost) and the route is promoted (sticky) to forced
+//     counter mode; tallies below threshold are discarded (those calls are
+//     represented by their deduped shape sample only).
+//
+// Windows emit after (window end + grace) so late-processed raw records from
+// the pipeline's tick cadence still land in their window — guaranteeing the
+// one-event-per-(route,window) contract.
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CounterAggregator = void 0;
+const WINDOW_MS = 60_000;
+/** Late-record grace before a closed window emits (2x max tick cadence). */
+const FLUSH_GRACE_MS = 5_000;
+const MAX_ENTRIES = 2_000;
+const MAX_PROMOTED_ROUTES = 512;
+function statusClassCounts(entry, status) {
+    if (status === 0)
+        entry.s0++;
+    else if (status >= 500)
+        entry.s5xx++;
+    else if (status >= 400)
+        entry.s4xx++;
+    else
+        entry.s2xx++;
+}
+/** Majority status class; ties break toward the more severe class. */
+function representativeStatus(e) {
+    const ranked = [
+        [500, e.s5xx],
+        [400, e.s4xx],
+        [0, e.s0],
+        [200, e.s2xx],
+    ];
+    let best = ranked[0];
+    for (const r of ranked) {
+        if (r[1] > best[1])
+            best = r;
+    }
+    return best[1] === 0 ? 200 : best[0];
+}
+class CounterAggregator {
+    promoteThreshold;
+    entries = new Map();
+    promoted = new Set();
+    constructor(promoteThreshold) {
+        this.promoteThreshold = promoteThreshold;
+    }
+    routeKey(p) {
+        return `${p.host}|${p.method}|${p.pathTemplate}`;
+    }
+    isPromoted(p) {
+        return this.promoted.has(this.routeKey(p));
+    }
+    /** Aggregate one call. `provisional` = heuristic tally (unrecognized GET). */
+    add(p, ts, status, durMs, bytesIn, bytesOut, provisional) {
+        const windowStart = Math.floor(ts / WINDOW_MS) * WINDOW_MS;
+        const key = `${this.routeKey(p)}|${windowStart}`;
+        let e = this.entries.get(key);
+        if (!e) {
+            if (this.entries.size >= MAX_ENTRIES)
+                return; // cardinality guard
+            e = {
+                host: p.host,
+                method: p.method,
+                pathTemplate: p.pathTemplate,
+                windowStart,
+                count: 0,
+                durMsSum: 0,
+                bytesInSum: 0,
+                bytesOutSum: 0,
+                s2xx: 0,
+                s4xx: 0,
+                s5xx: 0,
+                s0: 0,
+                provisional,
+            };
+            this.entries.set(key, e);
+        }
+        // A forced add upgrades a provisional entry (manifest matcher wins).
+        if (!provisional)
+            e.provisional = false;
+        e.count++;
+        e.durMsSum += durMs;
+        e.bytesInSum += bytesIn;
+        e.bytesOutSum += bytesOut;
+        statusClassCounts(e, status);
+    }
+    /**
+     * Emit closed windows (or everything when `force`, e.g. shutdown).
+     * Provisional tallies below the promote threshold are discarded.
+     */
+    flush(now, force = false) {
+        const out = [];
+        for (const [key, e] of this.entries) {
+            const closed = e.windowStart + WINDOW_MS + FLUSH_GRACE_MS <= now;
+            if (!closed && !force)
+                continue;
+            this.entries.delete(key);
+            if (e.provisional) {
+                if (e.count < this.promoteThreshold)
+                    continue; // discard quiet tallies
+                // Promote: subsequent windows aggregate from call #1 as forced.
+                if (this.promoted.size < MAX_PROMOTED_ROUTES) {
+                    this.promoted.add(this.routeKey(e));
+                }
+            }
+            const partial = !closed; // force-flushed mid-window
+            const windowSeconds = partial
+                ? Math.min(60, Math.max(1, Math.ceil((now - e.windowStart) / 1000)))
+                : 60;
+            out.push({
+                host: e.host,
+                method: e.method,
+                pathTemplate: e.pathTemplate,
+                windowStart: e.windowStart,
+                windowSeconds,
+                ts: partial ? now : e.windowStart + WINDOW_MS,
+                count: e.count,
+                durMsSum: e.durMsSum,
+                bytesInSum: e.bytesInSum,
+                bytesOutSum: e.bytesOutSum,
+                status: representativeStatus(e),
+            });
+        }
+        return out;
+    }
+    /** Test/diagnostic helper. */
+    size() {
+        return this.entries.size;
+    }
+}
+exports.CounterAggregator = CounterAggregator;

package/dist/denylist.d.ts

@@ -0,0 +1,7 @@
+/** True if a single field-name segment is PII-shaped (hard-denied). */
+export declare function isDeniedSegment(segment: string): boolean;
+/**
+ * True if ANY segment of a dot-path field reference is PII-shaped.
+ * "usage.total_tokens" -> false; "customer.email" -> true; "card.last4" -> true.
+ */
+export declare function isDeniedFieldPath(path: string): boolean;

package/dist/denylist.js

@@ -0,0 +1,81 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// denylist.ts -- L2 HARD PII denylist (SPEC §3.7 L2).
+//
+// PII-shaped field names can NEVER enter capture, even if a (bad or
+// malicious) manifest lists them in requestFields/responseFields. This list
+// is compiled into the shim and is not configurable at runtime — the manifest
+// linter (registry CI) is the other half of L2; this is the fail-safe half.
+//
+// Matching is applied to EVERY segment of a field dot-path (e.g.
+// "customer.email" is blocked because the segment "email" matches).
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDeniedSegment = isDeniedSegment;
+exports.isDeniedFieldPath = isDeniedFieldPath;
+const DENY_PATTERNS = [
+    /e[-_]?mail/i, // email, e_mail, customerEmail
+    /phone/i,
+    /mobile/i,
+    /ssn/i,
+    /social[-_]?security/i,
+    /passport/i,
+    /driver[-_]?licen[cs]e/i,
+    /tax[-_]?id/i,
+    /(?:^|_)(?:vat)(?:_|$)/i,
+    /passw(?:or)?d/i,
+    /(?:^|_)pwd(?:_|$)/i,
+    /secret/i,
+    /credential/i,
+    /private[-_]?key/i,
+    /api[-_]?key/i,
+    /(?:^|_)key$/i, // api_key, session_key — but NOT "monkey" etc. (segment-suffix)
+    /token$/i, // access_token, id_token — NOT prompt_tokens / total_tokens
+    /authorization/i,
+    /(?:^|_)auth(?:_|$)/i,
+    /bearer/i,
+    /(?:^|_)jwt(?:_|$)/i,
+    /cookie/i,
+    /session[-_]?id/i,
+    /card/i, // card, card_number, cardNumber, card_country (safe-side)
+    /cvv|cvc|cvn/i,
+    /(?:^|_)pan(?:_|$)/i,
+    /pin[-_]?code|(?:^|_)pin(?:_|$)/i,
+    /account[-_]?number/i,
+    /iban/i,
+    /(?:^|_)bic(?:_|$)/i,
+    /swift/i,
+    /routing/i,
+    /(?:^|_)dob(?:_|$)/i,
+    /birth/i,
+    /address/i, // street/billing/ip_address — safe-side
+    /street/i,
+    /(?:^|_)zip(?:_|$)|postal/i,
+    /(?:first|last|full|middle|maiden|user|customer|holder|given|family)[-_]?name/i,
+    /(?:^|_)name$/i, // bare "name" — could be a person (safe-side); "model" etc. unaffected
+    /gender/i,
+    /nationality/i,
+    /biometric/i,
+    /fingerprint/i,
+    /(?:^|_)ip(?:_|$)/i,
+    /latitude|longitude|geo[-_]?loc/i,
+];
+/** True if a single field-name segment is PII-shaped (hard-denied). */
+function isDeniedSegment(segment) {
+    for (const re of DENY_PATTERNS) {
+        if (re.test(segment))
+            return true;
+    }
+    return false;
+}
+/**
+ * True if ANY segment of a dot-path field reference is PII-shaped.
+ * "usage.total_tokens" -> false; "customer.email" -> true; "card.last4" -> true.
+ */
+function isDeniedFieldPath(path) {
+    for (const seg of path.split(".")) {
+        if (isDeniedSegment(seg))
+            return true;
+    }
+    return false;
+}

package/dist/envelope.d.ts

@@ -0,0 +1,71 @@
+/** Current envelope version (== observe-shared EVENT_SCHEMA_VERSION). */
+export declare const EVENT_SCHEMA_VERSION: 2;
+/** Versions the ingest still accepts (== observe-shared SUPPORTED_SCHEMA_VERSIONS). */
+export type EventSchemaVersion = 1 | 2;
+/** Max events per POST /v1/events batch (== observe-shared MAX_BATCH_EVENTS). */
+export declare const MAX_BATCH_EVENTS = 500;
+export type EventClass = "action" | "counter" | "shape" | "error";
+export type ActorKind = "human" | "agent" | "service" | "unknown";
+export type ActorGrade = "asserted" | "attested";
+export interface EventActor {
+    id: string;
+    kind: ActorKind;
+    grade: ActorGrade;
+}
+export interface EventDest {
+    host: string;
+    /** IDs stripped to templates SHIM-SIDE, e.g. "/v1/charges/{id}/refunds". */
+    pathTemplate: string;
+    method: string;
+}
+export interface EventBytes {
+    i: number;
+    o: number;
+}
+/** v2 rec.fields value: primitive leaves only (one level, no nesting). */
+export type RecFieldValue = string | number | boolean;
+export type RecFields = Record<string, RecFieldValue>;
+export interface EventRec {
+    rail: string;
+    action: string;
+    registryVersion: string;
+    /** v2: recognizer-extracted SAFE values (amounts in cents, ids, models,
+     * token counts). One level, primitives only. Denylist-filtered at extraction
+     * (L1/L2); ingest re-checks KEYS (L2) and scrubs VALUES (L4). */
+    fields?: RecFields;
+}
+export interface EventWindow {
+    start: number;
+    seconds: number;
+}
+export interface ShapeField {
+    name: string;
+    type: string;
+}
+export interface EventShape {
+    fields: ShapeField[];
+}
+/** The v1 observe event envelope (FROZEN — see header). */
+export interface ObserveEventV1 {
+    v: EventSchemaVersion;
+    ts: number;
+    /** SERVER-AUTHORITATIVE (stamped from the sensor key); shims omit it. */
+    org: string;
+    /** SERVER-AUTHORITATIVE (stamped from the sensor key); shims omit it. */
+    sensor: string;
+    class: EventClass;
+    actor?: EventActor;
+    onBehalfOf?: string;
+    dest: EventDest;
+    status: number;
+    dur_ms: number;
+    bytes: EventBytes;
+    rec?: EventRec;
+    policyVersion?: string;
+    dropped?: number;
+    count?: number;
+    window?: EventWindow;
+    shape?: EventShape;
+    /** SERVER-SET by the ingest L4 scrubber; shims NEVER send it. */
+    scrubbed?: boolean;
+}

package/dist/envelope.js

@@ -0,0 +1,20 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// envelope.ts -- FROZEN observe event envelope v1, mirrored.
+//
+// SOURCE OF TRUTH: packages/cdk/cloudflare/observe-shared/src/index.ts
+// (EVENT_SCHEMA_VERSION = 1). Mirrored here so the shim builds hermetically
+// (dependency-free dist, no cross-package rootDir coupling). Any drift fails
+// CI: test/envelope-contract.test.ts asserts bidirectional type-assignability
+// against the real @bounded-sh/observe-shared source AND validates every
+// pipeline-emitted event with the shared validateAndFilterEvent().
+//
+// If observe-shared bumps EVENT_SCHEMA_VERSION, update this file with it and
+// follow the CHANGELOG discipline in the observe-shared README.
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_BATCH_EVENTS = exports.EVENT_SCHEMA_VERSION = void 0;
+/** Current envelope version (== observe-shared EVENT_SCHEMA_VERSION). */
+exports.EVENT_SCHEMA_VERSION = 2;
+/** Max events per POST /v1/events batch (== observe-shared MAX_BATCH_EVENTS). */
+exports.MAX_BATCH_EVENTS = 500;