@swfte/nexus-sdk 0.1.0

package/src/core.cjs

@@ -0,0 +1,2411 @@
+'use strict';
+/**
+ * The whole SDK, in CommonJS, on purpose.
+ *
+ * Node has two module systems and a package that supports both has to decide where the *state*
+ * lives. If the ESM entry and the CJS entry each carried their own copy of the client, an app that
+ * `import`ed us in one file and `require`d us in another would get two queues, two session ids and
+ * two flush handlers for one process — the "dual package hazard", and in a governance ledger it
+ * shows up as one service reporting as two.
+ *
+ * CJS is the format both loaders can reach: ESM can `import` a CJS file, and it goes through the
+ * *same* require cache, so `src/index.js` (ESM) and `src/index.cjs` (CJS) observe one instance.
+ * The reverse layout does not hold — `require()` of an ESM file is only supported from Node 22.12,
+ * and even then the ESM graph is evaluated separately. So the core is CJS and the ESM entry is a
+ * facade. `test/dual.test.mjs` asserts the single instance rather than trusting this comment.
+ *
+ * Nothing in this file may throw into the host application. Everything public goes through
+ * `guard()`.
+ */
+
+const fs = require('node:fs');
+const crypto = require('node:crypto');
+const { AsyncLocalStorage } = require('node:async_hooks');
+const provenance = require('./provenance.cjs');
+const redactor = require('./redact.cjs');
+const pricing = require('./pricing.cjs');
+const { HealthRollup } = require('./health.cjs');
+
+const SDK_VERSION = '0.1.0';
+const CONTRACT_VERSION = '1';
+
+/** The attach-point discriminator. Mirrors `nexus/contract.py:PRODUCER`. */
+const PRODUCER = 'sdk';
+
+const EPISTEMIC_BEHAVIOR = 'behavior_trace';
+const EPISTEMIC_RATIONALISATION = 'rationalisation';
+const EPISTEMIC_NARRATIVE = 'interaction_narrative';
+
+// ---------------------------------------------------------------------------------------------
+// counters — the SDK's account of itself (Python `_counters.py`)
+// ---------------------------------------------------------------------------------------------
+
+const counters = Object.create(null);
+
+function incr(name, n) {
+  counters[name] = (counters[name] || 0) + (n === undefined ? 1 : n);
+}
+
+function snapshot() {
+  return Object.assign({}, counters);
+}
+
+// ---------------------------------------------------------------------------------------------
+// safety — Python `_safety.py`
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * Run `fn`, and if it throws, swallow it and return `fallback`.
+ *
+ * The contained error is counted, not logged in a loop: a wrapper that fails once usually fails on
+ * every call, and a per-call `console.error` turns one telemetry bug into a log-volume incident.
+ */
+function guard(name, fn, fallback) {
+  try {
+    return fn();
+  } catch (err) {
+    incr('hook_error');
+    incr('hook_error.' + name);
+    if (process.env.NEXUS_DEBUG === '1') {
+      try { process.stderr.write('[nexus] contained in ' + name + ': ' + err + '\n'); } catch (_) {}
+    }
+    return fallback;
+  }
+}
+
+/** Async twin of `guard`. A rejected promise inside a capture path is still our bug, not theirs. */
+async function guardAsync(name, fn, fallback) {
+  try {
+    return await fn();
+  } catch (err) {
+    incr('hook_error');
+    incr('hook_error.' + name);
+    if (process.env.NEXUS_DEBUG === '1') {
+      try { process.stderr.write('[nexus] contained in ' + name + ': ' + err + '\n'); } catch (_) {}
+    }
+    return fallback;
+  }
+}
+
+/**
+ * What a guarded failure hands back. Absorbs property access, calls, and `for await` so that host
+ * code written against a `Run` keeps running when the `Run` could not be built. Returning
+ * `undefined` instead would put our failure in the customer's stack trace two lines later as
+ * "cannot read property 'outcome' of undefined", which is exactly what `guard` exists to prevent.
+ */
+const INERT = new Proxy(function () {}, {
+  get(_t, prop) {
+    if (prop === Symbol.toPrimitive) return () => '';
+    if (prop === 'then') return undefined; // never look like a thenable to `await`
+    return INERT;
+  },
+  apply() { return INERT; },
+  construct() { return INERT; },
+  has() { return true; },
+});
+
+// ---------------------------------------------------------------------------------------------
+// config
+// ---------------------------------------------------------------------------------------------
+
+// Defined in `redact.cjs` and imported, rather than declared here and duplicated there. The
+// redactor is the thing that acts on a tier, so it owns the vocabulary; two copies of three string
+// literals is exactly the kind of duplication that survives a rename in one file only.
+const { TIER_METADATA_ONLY, TIER_HASHED, TIER_FULL } = redactor;
+
+function envEnabled() {
+  const v = process.env.NEXUS_ENABLED;
+  if (v === undefined) return true;
+  return ['0', 'false', 'no', 'off'].indexOf(String(v).trim().toLowerCase()) === -1;
+}
+
+function envInt(name, fallback, min) {
+  const raw = process.env[name];
+  if (raw === undefined || String(raw).trim() === '') return fallback;
+  const n = Number(String(raw).trim());
+  if (!Number.isFinite(n)) return fallback;
+  return Math.max(min === undefined ? 1 : min, Math.floor(n));
+}
+
+/**
+ * The service name, from the first variable that names one.
+ *
+ * `NEXUS_SERVICE` first, then the names other observability stacks already set. A service running
+ * under OpenTelemetry, Datadog, Cloud Run or Lambda has *already* been told what it is called, and
+ * making the operator repeat it in a fifth variable is how a fleet ends up half-labelled `unknown`
+ * — which is worse than no label, because it aggregates every unlabelled service into one bucket
+ * that looks like a real one.
+ *
+ * The order is Python's, and the order is a precedence claim: a variable set specifically for this
+ * SDK outranks one set for a different tool that we are borrowing.
+ */
+function resolveServiceName() {
+  for (const v of ['NEXUS_SERVICE', 'OTEL_SERVICE_NAME', 'DD_SERVICE', 'K_SERVICE',
+    'AWS_LAMBDA_FUNCTION_NAME']) {
+    const value = (process.env[v] || '').trim();
+    if (value) return value;
+  }
+  // `null`, not `'unknown'`, so the caller can still fall through to the config file. Returning the
+  // default here would make the file rung unreachable for the one field most likely to be in it.
+  return null;
+}
+
+/**
+ * The lowest configuration rung: a JSON file, read only when `NEXUS_CONFIG_FILE` names one.
+ *
+ * There is deliberately no `~/.nexus` and no implicit search path. A telemetry SDK that reads a
+ * file nobody pointed it at is a telemetry SDK whose behaviour depends on a machine's history, and
+ * the first time that matters is when a container behaves differently from a laptop for a reason
+ * neither the code nor the environment explains.
+ *
+ * A failing read is a warning and never an exception: this runs on the application's startup path,
+ * and a malformed JSON file must not stop a process from booting. The counter is what makes the
+ * failure visible without making it fatal.
+ */
+function loadConfigFile() {
+  const path = (process.env.NEXUS_CONFIG_FILE || '').trim();
+  if (!path) return {};
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      incr('config_file_invalid');
+      return {};
+    }
+    return parsed;
+  } catch (_err) {
+    incr('config_file_unreadable');
+    if (process.env.NEXUS_DEBUG === '1') {
+      try { process.stderr.write('[nexus] could not read NEXUS_CONFIG_FILE ' + path + '\n'); } catch (_) {}
+    }
+    return {};
+  }
+}
+
+/**
+ * Which *instance* of the SDK this is — the value that rides as `terminal_id`.
+ *
+ * `hostname-pid` identifies a process, and for a long time that was enough. It is not enough under
+ * `worker_threads`: a `Worker` gets its own module registry and its own heap, so the SDK inside it
+ * is a genuinely separate instance with its own client, queue and session id — but it shares the
+ * process, and therefore shared a `terminal_id` with the main thread and with every sibling worker.
+ * Measured, not assumed: `fixtures/app/worker-app.mjs` produced two sessions whose `terminal_id`
+ * and `pid` were byte-identical, leaving nothing on the wire able to tell them apart.
+ *
+ * The thread id is appended rather than added as a new field. `terminal_id` is declared in
+ * `contract/events.v1.json` and its job is precisely "which emitting instance"; inventing a
+ * `thread_id` beside it would be adding an undeclared field to a type two producers write into,
+ * which is the drift this repository has already fixed once. Changing the *value* of a declared
+ * string field is a different act from growing the schema.
+ *
+ * `threadId` is `0` on the main thread, and that case keeps the old format exactly — so nothing
+ * changes for the overwhelmingly common deployment, and the suffix appears only where it carries
+ * information.
+ */
+function buildInstanceId() {
+  const base = (require('node:os').hostname() || 'host').slice(0, 32) + '-' + process.pid;
+  try {
+    const { threadId } = require('node:worker_threads');
+    return threadId ? base + '-t' + threadId : base;
+  } catch (_err) {
+    // `worker_threads` has been available since Node 12, so this is unreachable on any supported
+    // version. Guarded anyway because this runs in the constructor of the client, and a throw here
+    // would be a telemetry SDK preventing a process from starting.
+    return base;
+  }
+}
+
+/**
+ * Free-form tags, bounded.
+ *
+ * `tags` is a caller-supplied object that `base()` spreads onto **every event this SDK emits**, and
+ * it was previously taken exactly as given: `tags: o.tags || null`. That is the same shape as the
+ * `tool_action.effect` hole — an arbitrary object reaching the wire without passing the treatment
+ * its siblings pass through — and it was found by going looking for the shape rather than for the
+ * bug.
+ *
+ * The failure here is cardinality rather than disclosure, which is why it reads as harmless and is
+ * not. A customer looping a user id or a request id into `tags` multiplies the rollup's key space
+ * on *our* side of the wire, where it is expensive and where nobody can see it happening. Python
+ * bounds it — 32 entries, keys to 64 characters, values to 128, everything coerced to a string —
+ * and Node now bounds it identically, so a tag set does not mean one thing in one language and
+ * something unbounded in the other.
+ *
+ * Values are stringified rather than dropped: a tag whose value is a number is an ordinary thing
+ * for somebody to write, and refusing it would be a surprise where truncating is not. A non-object
+ * yields no tags at all rather than throwing, because this runs inside `init()`.
+ */
+function boundTags(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const out = {};
+  for (const k of Object.keys(raw).slice(0, 32)) {
+    const v = raw[k];
+    if (v === null || v === undefined) continue;
+    out[String(k).slice(0, 64)] = String(v).slice(0, 128);
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+/** The Python SDK's default, and it has to be the same one or one collector needs two configs. */
+const DEFAULT_COLLECTOR_URL = 'http://127.0.0.1:8791';
+
+/**
+ * Where events are POSTed.
+ *
+ * Three layers, in the same order the Python SDK resolves them:
+ *
+ *   1. an explicit `collectorUrl` / `NEXUS_COLLECTOR_URL` — a full URL, wins outright;
+ *   2. **sidecar mode** — `NEXUS_COLLECTOR_HOST` / `_PORT` / `_SCHEME`, composed into a URL. This
+ *      exists because the default is loopback and a Kubernetes sidecar is not: the collector is a
+ *      second container reachable by name, and hardcoding `127.0.0.1` is what makes an otherwise
+ *      correct deployment silently capture nothing;
+ *   3. the loopback default.
+ *
+ * `'none'` is honoured at every layer as an explicit "no collector" — the file sink alone, which
+ * is what the test suite and offline debugging want. It is a sentinel rather than an empty string
+ * because an empty environment variable is far more often an accident than an instruction.
+ *
+ * A bare IPv6 host is bracketed, since `http://::1:8791` is not a parseable URL. Anything that
+ * still fails to parse falls back to the default rather than throwing: this runs inside `init()`,
+ * on the application's startup path, and a malformed variable must not stop a process from booting.
+ */
+function resolveCollectorUrl(o) {
+  const explicit = o.collectorUrl || process.env.NEXUS_COLLECTOR_URL;
+  if (explicit) return String(explicit).trim();
+
+  const host = (process.env.NEXUS_COLLECTOR_HOST || '').trim();
+  if (host) {
+    if (host.toLowerCase() === 'none') return 'none';
+    const scheme = (process.env.NEXUS_COLLECTOR_SCHEME || 'http').trim().toLowerCase();
+    const safeScheme = scheme === 'https' ? 'https' : 'http';
+    const port = envInt('NEXUS_COLLECTOR_PORT', 8791, 1);
+    const bracketed = host.includes(':') && !host.startsWith('[') ? '[' + host + ']' : host;
+    const composed = safeScheme + '://' + bracketed + ':' + port;
+    try {
+      // Round-trip it. A host variable carrying a path, a query or userinfo is a misconfiguration
+      // that would otherwise become a request to somewhere nobody intended.
+      const u = new URL(composed);
+      if (u.pathname === '/' && !u.search && !u.username && !u.password) return composed;
+    } catch (_) { /* fall through to the default */ }
+    incr('collector_host_invalid');
+  }
+
+  return DEFAULT_COLLECTOR_URL;
+}
+
+/**
+ * Resolve the effective configuration.
+ *
+ * Precedence mirrors the Python SDK: explicit argument, then environment, then default — with the
+ * one documented exception that `NEXUS_ENABLED=0` beats everything, including
+ * `init({ enabled: true })`. An operator switching telemetry off from outside the process has to
+ * be able to beat application code that says otherwise, or it is not a kill switch.
+ *
+ * `service` / `env` / `version` fall back to a literal `'unknown'` / `null` because they are
+ * *labels* — an unlabelled service is a real state the ledger has to be able to represent.
+ * `application` / `repo` / `commit` do **not** get that treatment: they are *provenance*, and the
+ * whole point of the operate plane is that a missing link is drawn as a break rather than filled
+ * in. See `provenance.cjs`.
+ */
+function resolveConfig(opts) {
+  const o = opts || {};
+  // The lowest rung, below the environment. Read once per `init()` rather than cached, so a
+  // notebook that edits the file and calls `init()` again sees the change — the same reason
+  // `init()` is idempotent rather than first-call-wins.
+  const fileCfg = loadConfigFile();
+  /** Argument, then environment, then file, then default. */
+  const pick = (argValue, envName, fileKey, fallback) => {
+    if (argValue !== undefined && argValue !== null) return argValue;
+    const env = process.env[envName];
+    if (env !== undefined && String(env).trim() !== '') return String(env).trim();
+    if (fileCfg[fileKey] !== undefined && fileCfg[fileKey] !== null) return fileCfg[fileKey];
+    return fallback;
+  };
+  // The explicit layer, exactly as Python's `config.build` assembles it: the argument, then the
+  // `NEXUS_*` variable, then nothing. Anything that survives this is stamped `explicit`, because an
+  // operator who exported `NEXUS_COMMIT` told us as deliberately as a caller who passed it.
+  // `env` and `version` are handed in the same way rather than being overwritten by a platform
+  // variable afterwards — they have an established config home and a legacy variable each.
+  const prov = provenance.detect({
+    application: o.application || process.env.NEXUS_APPLICATION,
+    repo: o.repo || process.env.NEXUS_REPO,
+    commit: o.commit || process.env.NEXUS_COMMIT,
+    branch: o.branch || process.env.NEXUS_BRANCH,
+    deployment_id: o.deploymentId || process.env.NEXUS_DEPLOYMENT_ID,
+    env: o.env || process.env.NEXUS_ENV,
+    // `NEXUS_VERSION` first, because that is the name the Python SDK reads and the two have to
+    // agree or one estate needs two variables to say one thing. `NEXUS_SERVICE_VERSION` stays an
+    // accepted alias: it is what this package read while it was a spike, and quietly dropping it
+    // would turn a working configuration into an `unknown` label with no error anywhere.
+    version: o.version || process.env.NEXUS_VERSION || process.env.NEXUS_SERVICE_VERSION,
+  });
+
+  return {
+    // ── the three dimensions that ride EVERY event, and were the ones still unbounded ────────
+    //
+    // §7a of PARITY.md claimed this SDK had closed the dimension hole. It had not: `service`,
+    // `env` and `service_version` are on the base envelope of every event, `service` is the field
+    // the dashboard identifies an SDK-instrumented service BY, and all three were unbounded here
+    // while the Python SDK bounded all three (`config.py`: `[:128]`, `[:64]`, `[:64]`). So the
+    // widest-blast-radius dimensions of the whole set were the ones the sweep missed, in the
+    // direction opposite to the one §7a described. Found by the cross-SDK conformance suite
+    // rather than by re-reading either file.
+    //
+    // Bounds are Python's, exactly: a bound that differs by SDK is a cardinality difference a
+    // customer can see, which is the defect this is fixing rather than a smaller version of it.
+    // `'unknown'` is applied AFTER the bound, so a whitespace-only service name still lands on the
+    // sentinel rather than on an empty string.
+    service: label(o.service || resolveServiceName() || fileCfg.service, 128) || 'unknown',
+    env: label(prov.values.env, 64) || 'unknown',
+    version: label(prov.values.version, 64),
+    tier: pick(o.tier, 'NEXUS_TIER', 'tier', TIER_METADATA_ONLY),
+
+    // Egress. `sink` is a file path (the spike's original transport, and still the cheapest way
+    // to assert on a whole event corpus in a test); `collectorUrl` is `POST <url>` with an NDJSON
+    // body. Both may be set at once — someone debugging a silent pipeline wants the file *and*
+    // the collector.
+    sink: pick(o.sink, 'NEXUS_SDK_SINK', 'sink', null),
+    collectorUrl: resolveCollectorUrl(o),
+    apiKey: pick(o.apiKey, 'NEXUS_API_KEY', 'api_key', null),
+
+    // Operate-plane identity. Absent stays absent — never `'unknown'`.
+    //
+    // Bounded here rather than at each builder, because these five ride the *base envelope* and so
+    // appear on every event this SDK emits. That makes them the widest-blast-radius dimensions in
+    // the product: an unbounded `commit` is not one oversized field, it is one oversized field
+    // multiplied by every row. Bounding at the source also means a builder cannot forget.
+    application: label(prov.values.application, 128),
+    repo: label(prov.values.repo, 200),
+    commit: label(prov.values.commit, 128),
+    branch: label(prov.values.branch, 128),
+    deploymentId: label(prov.values.deployment_id, 128),
+    /** Per-field `{ commit: 'env:VERCEL_GIT_COMMIT_SHA', … }`. Never a key without a value. */
+    provenance: Object.keys(prov.sources).length ? prov.sources : null,
+    provenanceSource: provenance.primarySource(prov.sources),
+    provenanceIncomplete: prov.incomplete.length ? prov.incomplete : null,
+
+    tags: boundTags(o.tags || fileCfg.tags),
+    // `NEXUS_ENABLED=0` wins over `init({ enabled: true })`. The reverse would make the
+    // environment variable advisory, which is not what a kill switch is.
+    enabled: envEnabled() && (o.enabled === undefined ? true : !!o.enabled),
+
+    queueCapacity: o.queueCapacity || envInt('NEXUS_QUEUE_CAPACITY', 10000, 1),
+    batchSize: o.batchSize || envInt('NEXUS_BATCH_SIZE', 500, 1),
+    flushIntervalMs: o.flushIntervalMs || envInt('NEXUS_FLUSH_INTERVAL_MS', 2000, 10),
+    flushDeadlineMs: o.flushDeadlineMs || envInt('NEXUS_FLUSH_DEADLINE_MS', 2000, 10),
+    httpTimeoutMs: o.httpTimeoutMs || envInt('NEXUS_HTTP_TIMEOUT_MS', 2000, 10),
+
+    /**
+     * How often the `service_health` window closes. Python's `NEXUS_HEALTH_INTERVAL_S`, in the
+     * milliseconds every other duration in this SDK uses. `0` disables the rollup entirely.
+     */
+    healthIntervalMs: o.healthIntervalMs === undefined
+      ? envInt('NEXUS_HEALTH_INTERVAL_MS', 60000, 0)
+      : o.healthIntervalMs,
+
+    /**
+     * Durable overflow for batches the collector permanently refused. Off by default, and the
+     * default is the interesting part: containers are frequently read-only, and a telemetry SDK
+     * that fails to start because it could not create a directory has inverted its own priorities.
+     * When it is off, an abandoned batch is counted and dropped — which is the honest outcome, and
+     * which `counters()` reports rather than hiding.
+     */
+    spillDir: pick(o.spillDir, 'NEXUS_SPILL_DIR', 'spill_dir', null),
+
+    /**
+     * Vercel's `waitUntil`, if the host handed us one. Without it a serverless function is frozen
+     * the instant it returns, and a background flush does not run late — it does not run at all.
+     * See the `serverless` section.
+     */
+    waitUntil: typeof o.waitUntil === 'function' ? o.waitUntil : null,
+  };
+}
+
+// ---------------------------------------------------------------------------------------------
+// contract — field-for-field with nexus-sdk/src/nexus/contract.py
+// ---------------------------------------------------------------------------------------------
+
+function now() {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+
+function fingerprint(text) {
+  return crypto.createHash('sha256').update(String(text == null ? '' : text), 'utf8')
+    .digest('hex').slice(0, 12);
+}
+
+/** ~4 chars/token. Good enough for rollups; the provider's own count wins when present. */
+function estTokens(text) {
+  return Math.floor(((text || '').length + 3) / 4);
+}
+
+/**
+ * The tier ladder itself, in one place: what content — if any — this tier may carry.
+ *
+ * Returns canonical keys (`text` / `preview` and their flags); the two public wrappers rename them.
+ * **T0 returns an empty object**: not a blank string, not a mask, nothing — so the field is absent
+ * and a reader can tell "no content was captured" from "the content was empty".
+ *
+ * `full` is redacted too. A tier is a decision about *content*; it is never a waiver on
+ * credentials, and a `full` branch that sliced raw text is how `integration_probe.error` ships an
+ * unscrubbed vendor exception to anyone who set `tier: 'full'`.
+ *
+ * Both rungs go through `scanWindow`, so the bound and the unfinished-scan post-condition cannot
+ * hold in one caller and not the other.
+ *
+ * ── What this replaces, and why the old behaviour was worse than it looked ───────────────────
+ *
+ * This SDK used to answer the tier question with three lines: at `full` the text truncated, at
+ * `hashed` the string `sha256:<12 hex>`, at `metadata_only` nothing. Two defects in that, one in
+ * each direction:
+ *
+ * - `full` did not redact. The Python SDK's `full` scrubs credentials and PII on the way out, so
+ *   the same configuration produced scrubbed text there and unscrubbed text here, into the same
+ *   field of the same ledger.
+ * - `hashed` was a digest where Python's is a redacted preview. Stricter, but the same word meaning
+ *   two things is its own defect: a reader joining the two populations gets opaque hashes from half
+ *   their estate and readable text from the other half, under one tier name.
+ */
+function rungs(text, tier, fullLimit, previewLimit) {
+  if (tier === TIER_FULL) {
+    const r = redactor.scanWindow(text, fullLimit);
+    const out = { text: r.unfinished ? redactor.MASK : r.text, text_redacted: r.redacted || r.unfinished };
+    if (fullLimit !== null && fullLimit !== undefined) out.text_truncated = text.length > fullLimit;
+    return out;
+  }
+  if (tier === TIER_HASHED) {
+    const r = redactor.scanWindow(text, previewLimit);
+    return {
+      preview: r.unfinished ? redactor.MASK : r.text,
+      preview_redacted: r.redacted || r.unfinished,
+      preview_truncated: text.length > previewLimit,
+    };
+  }
+  // `metadata_only`, and anything unrecognised. A new tier or a typo degrades to silence rather
+  // than to egress, which is the only failure direction worth having here.
+  return {};
+}
+
+/**
+ * A *named* free-text field, gated by tier, as a fragment to spread into `base()`.
+ *
+ * Shape survives every tier. `<name>_chars` and `<name>_fingerprint` are content-free, so at T0
+ * "the same error as yesterday" stays answerable, deploy actors stay countable and a repeated
+ * target stays groupable, without the text leaving the process. The content key is `<name>` at T2
+ * and `<name>_preview` at T1; at T0 it does not exist.
+ *
+ * Empty in, empty out — an absent field writes nothing, not a zero length.
+ */
+function tieredText(name, text, tier, fullLimit, previewLimit) {
+  const txt = (typeof text === 'string' ? text : (text ? String(text) : '')).trim();
+  if (!txt) return {};
+  const out = {};
+  out[name + '_chars'] = txt.length;
+  out[name + '_fingerprint'] = fingerprint(txt);
+  const r = rungs(txt, tier, fullLimit === undefined ? 512 : fullLimit,
+    previewLimit === undefined ? 280 : previewLimit);
+  for (const k of Object.keys(r)) {
+    // `text` is the field itself; `text_redacted` is a flag *about* the field and reads as
+    // `<name>_redacted`, matching `<name>_preview_redacted` one rung down. Leaving the canonical
+    // name in would spell it `actor_text_redacted`, inventing a second word for one thing.
+    const suffix = k.startsWith('text_') ? k.slice(5) : (k === 'text' ? '' : k);
+    out[suffix ? name + '_' + suffix : name] = r[k];
+  }
+  return out;
+}
+
+/**
+ * Tier-appropriate rendering of a free-text field with *unprefixed* keys, for the model-text events
+ * that carry exactly one such field and rename the fragment on the way in.
+ *
+ * Same ladder as {@link tieredText}, so a tier cannot mean one thing here and another there.
+ */
+function redactPreview(text, tier, limit) {
+  if (!text) return null;
+  const s = String(text);
+  const frag = { chars: s.length, fingerprint: fingerprint(s), tokens_est: estTokens(s) };
+  Object.assign(frag, rungs(s, tier, null, limit === undefined ? 280 : limit));
+  return frag;
+}
+
+/**
+ * The last-resort gate for a caller that only wants a string back.
+ *
+ * Retained because a handful of internal call sites want exactly one value rather than a fragment,
+ * and because removing it would push the tier decision back out to those call sites — which is
+ * precisely how these fields leaked in the wrapper, one path redacted and three not. Prefer
+ * {@link tieredText}: shape at T0 is strictly more useful than nothing.
+ */
+function wireText(text, tier, max) {
+  if (text === null || text === undefined) return null;
+  const s = String(text);
+  if (!s) return s;
+  if (tier !== TIER_FULL && tier !== TIER_HASHED) return null;
+  const r = redactor.scanWindow(s, max || 256);
+  return r.unfinished ? redactor.MASK : r.text;
+}
+
+/**
+ * A **dimension**: a low-cardinality label a consumer groups by. Bounded in length, never redacted.
+ *
+ * These are the fields a rollup does `GROUP BY` on — `goal_class`, `model`, `provider`,
+ * `error_class`, `kind`. They are not content, so the tier ladder is the wrong instrument; what
+ * they need is a bound, and they had none. That is the same class as the `tags` finding: a
+ * cardinality failure rather than a disclosure one, and cardinality failures are invisible in
+ * exactly the way disclosure failures are not — nothing looks wrong, the rollup just quietly
+ * degrades on our side of the wire.
+ *
+ * **What this does and does not fix, stated because the difference matters.** Truncating to a
+ * bound stops a megabyte of prose becoming a group-by key; it does not reduce the *number of
+ * distinct values*, which is the other half of cardinality. Capping distinct values in-process
+ * would mean remembering every value seen, which is itself unbounded memory, so it is not
+ * attempted here and belongs to the collector. Bounding the length is the tractable half and it is
+ * the half that turns a pathological payload into a merely wrong label.
+ *
+ * The Python SDK bounds `agent_run.name`, `tool_action.tool_name`/`action`, `turn_outcome.outcome`
+ * and `verified_by`, and leaves the rest of these unbounded — so this is a gap the two SDKs share
+ * rather than a Node regression, and worth closing on both sides.
+ */
+function label(v, max) {
+  if (v === null || v === undefined) return null;
+  const s = String(v).trim();
+  return s ? s.slice(0, max || 64) : null;
+}
+
+function dropNulls(obj) {
+  const out = {};
+  for (const k of Object.keys(obj)) {
+    if (obj[k] !== null && obj[k] !== undefined) out[k] = obj[k];
+  }
+  return out;
+}
+
+/**
+ * The common envelope. `producer` and `epistemic_class` are written here and nowhere else, so
+ * "never emit an unclassified event" is a property of one function rather than of every call site.
+ */
+function base(type, sessionId, cfg, epistemicClass, extra) {
+  const e = {
+    schema: CONTRACT_VERSION,
+    event_id: crypto.randomUUID().replace(/-/g, ''),
+    type,
+    session_id: sessionId,
+    ts: now(),
+    producer: PRODUCER,
+    epistemic_class: epistemicClass,
+    service: cfg.service,
+    env: cfg.env,
+    service_version: cfg.version,
+    sdk_version: SDK_VERSION,
+
+    // ── operate-plane join keys ──────────────────────────────────────────────────────────────
+    //
+    // On every event rather than on `session` alone, for the same reason `service`/`env` already
+    // are (`contract.py:base`): events from one process outlive the session record that
+    // introduced them, and a consumer that has to look up a session to know which application a
+    // row belongs to will eventually be handed a row whose session it never received.
+    //
+    // These are the fields that turn `repo ──► commit ──► ??? ──► version ──► running service`
+    // into a closed chain. Every one of them may be absent, and `dropNulls` below means absent is
+    // literally absent — the console draws the break, and drawing the break is the product.
+    application: cfg.application,
+    repo: cfg.repo,
+    commit: cfg.commit,
+    /** Which variable the commit was read from, e.g. `env:VERCEL_GIT_COMMIT_SHA`. */
+    provenance_source: cfg.provenanceSource,
+  };
+  Object.assign(e, dropNulls(extra || {}));
+  if (cfg.tags) e.tags = cfg.tags;
+  return dropNulls(e);
+}
+
+const contract = {
+  session(sessionId, cfg, instanceId, runtime) {
+    const e = base('session', sessionId, cfg, EPISTEMIC_BEHAVIOR, {
+      // ── `provenance` is the VALUES, with their sources nested — the Python SDK's shape ───────
+      //
+      // This used to be the per-field *sources* map (`{commit: 'env:VERCEL_GIT_COMMIT_SHA'}`)
+      // while the Python SDK's `provenance` on the same event type is the *values*
+      // (`{commit: '9f2c1ab…'}`) with `source` and `sources` nested inside it. One wire key, two
+      // meanings, split by which SDK the customer happened to install: a reader doing
+      // `session.provenance.commit` got a SHA from one half of the estate and the literal string
+      // `"explicit"` from the other. Exactly the `session.repo` collision below, one level in, and
+      // found the same way — by diffing the two emitted streams rather than by reading either file.
+      //
+      // Python's shape wins because "provenance" naming the values is what every other consumer
+      // already assumes, and because the sources are still there, one level down, losing nothing.
+      provenance: (() => {
+        const v = dropNulls({
+          application: cfg.application, repo: cfg.repo, commit: cfg.commit,
+          branch: cfg.branch, deployment_id: cfg.deploymentId,
+          source: cfg.provenanceSource, sources: cfg.provenance,
+        });
+        return Object.keys(v).length ? v : null;
+      })(),
+      // The counterpart nobody thinks to ship, and Node-only: it names the fields a platform
+      // *nearly* answered. Without it, "Vercel set the repo slug but not the owner, so we
+      // published no repo" is indistinguishable from "no platform variables at all", and the
+      // customer whose ribbon has a break has no way to find out which one they are.
+      provenance_incomplete: cfg.provenanceIncomplete,
+      branch: cfg.branch,
+      platform_deployment_id: cfg.deploymentId,
+      terminal_id: instanceId, tool: 'sdk', privacy_tier: cfg.tier,
+      // ── no `redactor` key, and its removal is the fix rather than a feature being dropped ────
+      //
+      // This event used to carry `redactor: 'none'`, declared so that a collector could tell apart
+      // two populations writing `privacy_tier: "full"` while meaning different things by it — the
+      // Python SDK scrubbing credentials on the way out and this one not. Since PARITY.md §3a that
+      // is no longer true: `src/redact.cjs` is a port of `redact.py`, verified differentially at
+      // 178 cases. So the field was asserting, on every session row in the ledger, something that
+      // had stopped being the case — and it is exactly the field an operator would have trusted to
+      // decide whether text from a Node service was safe.
+      //
+      // It is also a type the contract has no model for: `session` declares no `redactor` in
+      // `contract/events.v1.json`, so nothing could ever have validated it. Undeclared, untrue,
+      // and Python-less: removed rather than corrected, which is the `data_expectation` lesson.
+      runtime, pid: process.pid,
+    });
+
+    // ── a field-name collision between two producers, resolved in our favour by moving ────────
+    //
+    // `base()` puts the provenance repo slug (`github.com/acme/portal`) on every event as a
+    // string. On `session` that lands on top of a key the OTHER producer already owns and means
+    // something else by: `nexus-devtools/events.py:session` takes `repo: Optional[dict]` — a local
+    // repository descriptor keeping an absolute `root` — and `contract/events.v1.json` declares
+    // `session.repo` as `{"type": "object"}` accordingly. Four other event types declare `repo` as
+    // a string; `session` is the only one that does not.
+    //
+    // So a `session` row's `repo` was an object from `wrap` and a string from this SDK. Nothing
+    // rejects it — the collector validates schema major, not per-field types — so the damage would
+    // have been a reader doing `session.repo.root` and getting `undefined` for exactly the rows
+    // that came from production, which is the half of the ledger it most wanted.
+    //
+    // Renamed rather than dropped: the slug is a real operate-plane join key and `session` is
+    // where a reader looks for it. `repo_slug` is additive, unambiguous, and cannot be mistaken
+    // for the other producer's field by a reader or by a schema.
+    if (e.repo !== undefined) {
+      e.repo_slug = e.repo;
+      delete e.repo;
+    }
+    return e;
+  },
+
+  agentRun(sessionId, cfg, o) {
+    return base('agent_run', sessionId, cfg, EPISTEMIC_BEHAVIOR, {
+      run_id: o.runId, name: String(o.name).slice(0, 128), phase: o.phase,
+      goal_class: label(o.goalClass), duration_ms: o.durationMs, actions: o.actions,
+      // The tiered fragment, matching `nexus/contract.py`'s limits field for field. At T0 this
+      // contributes `error_chars` and `error_fingerprint` and no text — which is strictly more
+      // than the old gate gave, because "the same error as yesterday" stays answerable without
+      // the message leaving the process.
+      ...tieredText('error', o.error, cfg.tier, 256, 256),
+      incomplete: o.incomplete || null,
+    });
+  },
+
+  toolAction(sessionId, cfg, o) {
+    return base('tool_action', sessionId, cfg, EPISTEMIC_BEHAVIOR, {
+      tool_name: String(o.toolName).slice(0, 64),
+      action: String(o.action || 'invoke').slice(0, 64),
+      // `target_fingerprint` is spelled by `tieredText` itself now. It used to be computed
+      // separately here, beside a `wireText` call that produced the content — two helpers
+      // deciding one field, which is how the shape drifted from the Python builder's.
+      ...tieredText('target', o.target, cfg.tier, 256, 256),
+      blocked: !!o.blocked,
+      ...tieredText('reason', o.reason, cfg.tier, 256, 256),
+      duration_ms: o.durationMs,
+      caused_by_prompt_id: o.runId,
+      // ── `effect` is customer data, and it used to reach the wire with no gate at all ─────────
+      //
+      // Every other content-bearing field on this event goes through the tier ladder. This one was
+      // spread verbatim: `effect: o.effect || null`. So `act.effect({ headers: { Authorization:
+      // 'Bearer …' } })` — or `{ ssn: 123456789 }`, or a tool's whole response object — shipped
+      // unredacted at `metadata_only`, the tier whose entire promise is that no content leaves the
+      // process.
+      //
+      // It was invisible for the same reason the Python file's own comment gives: a redactor that
+      // only walks free text passes a credential straight through when it arrives as a structured
+      // value. Objects are not strings, so no string gate ever saw them.
+      effect: o.effect ? redactor.scrubMapping(o.effect, cfg.tier) : null,
+      ...tieredText('error', o.error, cfg.tier, 256, 256),
+    });
+  },
+
+  tokenUsage(sessionId, cfg, o) {
+    // ── cost ────────────────────────────────────────────────────────────────────────────────
+    //
+    // A caller-supplied figure wins and is stamped `provider`, because a number the provider
+    // itself reported outranks one we derived. Otherwise it is computed from the token breakdown
+    // and stamped `usage`. Provenance is part of the record: an inference has to be legible as one
+    // beside a reported figure, or a reconciliation against an invoice cannot tell them apart.
+    //
+    // An unpriced model yields `null` for both, and the envelope drops null keys — so a missing
+    // cost is an absent field rather than a zero. A gap somebody can fill; an invented cost is a
+    // gap nobody can see.
+    //
+    // Where this differs from Python: there, `usage()` takes `cost_usd` as a parameter and the
+    // computation lives in the OTel bridge and the streams integration. Node has neither yet, so
+    // computing here is what makes the field reachable at all — same rate card, same function,
+    // called one layer down. Noted in PARITY.md rather than left to be discovered.
+    let costUsd = o.costUsd;
+    let costSource = o.costSource;
+    if (costUsd === undefined || costUsd === null) {
+      costUsd = o.model ? pricing.costFromTokens(o.model, o) : null;
+      costSource = costUsd === null || costUsd === undefined ? null : pricing.SOURCE_USAGE;
+    } else if (!costSource) {
+      costSource = pricing.SOURCE_PROVIDER;
+    }
+
+    return base('token_usage', sessionId, cfg, EPISTEMIC_BEHAVIOR, {
+      model: label(o.model, 128), provider: label(o.provider),
+      input_tokens: o.inputTokens | 0, output_tokens: o.outputTokens | 0,
+      cache_read_tokens: o.cacheReadTokens, cache_write_tokens: o.cacheWriteTokens,
+      cost_usd: costUsd, cost_source: label(costSource, 32),
+      caused_by_prompt_id: o.runId,
+      attempts: o.attempts && o.attempts !== 1 ? o.attempts : null,
+      incomplete: o.incomplete || null,
+      instrumentation: label(o.instrumentation, 32),
+    });
+  },
+
+  turnOutcome(sessionId, cfg, o) {
+    let verified = o.verified;
+    if ((verified === undefined || verified === null) && o.verifiedBy) verified = true;
+    return base('turn_outcome', sessionId, cfg, EPISTEMIC_BEHAVIOR, {
+      prompt_id: o.runId, outcome: String(o.outcome).slice(0, 64),
+      verified: verified === undefined ? null : verified,
+      verified_by: o.verifiedBy ? String(o.verifiedBy).slice(0, 64) : null,
+      actions: o.actions || 0, blocked: o.blocked || 0,
+      partial: o.partial || null,
+    });
+  },
+
+  /**
+   * The SDK's report on itself. Three field-level corrections, all found by the cross-SDK
+   * conformance suite and all of them cross-producer name collisions rather than cosmetics:
+   *
+   * - **`queue_depth`, not `pending`.** `pending` is a declared field on this type and it means
+   *   something else: `nexus_devtools/events.py:pipeline_health` documents it as events sitting
+   *   past the drain watermark — a *ledger backlog* on disk. This SDK has no ledger; it has an
+   *   in-memory queue. Writing an in-memory depth into the backlog column gives one column two
+   *   meanings across two producers, which is the `session.repo` mistake with a different name.
+   *   The Python SDK already spelled it `queue_depth`; this one now agrees.
+   * - **No `nexus_version`.** Same shape. `nexus_version` is the `wrap` CLI's version. This
+   *   SDK's version is `sdk_version`, which `base()` already writes on every event, so the field
+   *   was both wrong and redundant.
+   * - **Counters spread flat, not nested under `counters`.** PARITY.md §5 has claimed since it
+   *   was written that they are spread flat "as in Python". They were not — they were an object,
+   *   so a consumer reading `events_sent` off a Python row read `undefined` off a Node one. A
+   *   documented claim that no test checked, which is the class of defect this suite exists for.
+   */
+  pipelineHealth(sessionId, cfg, o) {
+    return base('pipeline_health', sessionId, cfg, EPISTEMIC_BEHAVIOR, {
+      terminal_id: o.instanceId, checkpoint: o.checkpoint,
+      queue_depth: o.queueDepth, collector_up: !!o.collectorUp,
+      // Restated on every health record, not just at session start: the `session` event is written
+      // before the app's first provider import, so at that point the honest answer is always
+      // "none". The value only becomes true once something has actually been hooked.
+      instrumentation: describeInstrumentation(),
+      runtime: o.runtime || null,
+      ...Object.fromEntries(Object.entries(o.counters || {}).map(([k, v]) => [k, Number(v) | 0])),
+    });
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════════════════════
+  // operate plane — events 28 and 30, plus the declaration that makes 30's alarm honest.
+  //
+  // Shapes are copied field for field from `nexus-web-app/lib/features/operate/types.ts`, which
+  // is the console's read contract. Snake_case on the wire, `detected_by` on every record,
+  // `epistemic_class` from `base()`. These types are not yet in `contract/events.v1.json` — see
+  // ANCHOR-INTEGRATION §5.2 and SCOPE.md §7 D4; `test/contract.test.mjs` pins the drift so that
+  // any *further* undeclared type fails on the day it is introduced.
+  // ═══════════════════════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Event 28 — a version reached an environment, self-reported by the process running it.
+   *
+   * `detected_by: 'self'` is not a formality. The console labels it as the weakest claim on the
+   * plane, because a process asserting its own deployment is exactly the evidence a shadow deploy
+   * would also produce. A CI or cloud connector record beats this one wherever both exist; this
+   * exists so that an estate with no connectors still has *something* to draw, and so that the
+   * something is honestly marked.
+   */
+  deployment(sessionId, cfg, o) {
+    return base('deployment', sessionId, cfg, EPISTEMIC_BEHAVIOR, {
+      deployment_id: o.deploymentId,
+      app_id: label(o.appId, 128),
+      env: label(o.env),
+      version: label(o.version, 128),
+      commit: label(o.commit, 128),
+      repo: label(o.repo, 200),
+      // Free text on an operate event, gated like every other. `nexus-devtools` keeps `actor` at
+      // all three tiers because a deployment ledger that cannot say who did it is not a ledger,
+      // and relies on its redactor to scrub the commit-author email a forge connector usually
+      // supplies. This SDK now has that redactor, so the rule is the same one rather than a
+      // conservative approximation of it: `actor_fingerprint` makes deploy actors countable at
+      // T0, and the name itself appears at T1 and T2 with the email scrubbed out of it.
+      ...tieredText('actor', o.actor, cfg.tier, 128, 128),
+      started_ts: o.startedTs,
+      finished_ts: o.finishedTs,
+      outcome: label(o.outcome, 32),
+      rollback_of: label(o.rollbackOf, 128),
+      detected_by: 'self',
+      // No `provenance` here. It was the per-field *sources* map, `contract/events.v1.json`
+      // declares no such field on `deployment`, and the Python SDK deliberately keeps provenance
+      // on `session` and nowhere else — "emitted once per process identity event" is the whole
+      // argument for nesting it rather than repeating it. A second producer writing an undeclared
+      // field onto a shared operate-plane type is the `data_expectation` shape again.
+    });
+  },
+
+  /**
+   * Event 30 — one observation of an outbound dependency.
+   *
+   * **The two registers must never be merged.** `reachable` says the call completed; `rows` and
+   * `last_data_ts` say what came back. "The call succeeded" and "the call succeeded and returned
+   * zero rows" are different facts, and "the newest row we saw is three days old" is a third.
+   * A single green dot cannot express the PRD's own headline case — API healthy, data stale —
+   * which is why every competitor's integration page cannot express it either.
+   *
+   * Consequently, and this is the part that is easy to undo by accident: a key that was not
+   * supplied is absent, not `false` and not `0`. `rows: 0` means *we counted, and there were
+   * none*; no `rows` key means *we did not count*. `base()` drops nulls, so the only way to
+   * preserve the difference is to never invent a default here.
+   */
+  integrationProbe(sessionId, cfg, o) {
+    const e = base('integration_probe', sessionId, cfg, EPISTEMIC_BEHAVIOR, {
+      integration: String(o.integration).slice(0, 128),
+      app_id: label(o.appId, 128),
+      service: label(o.service, 128),
+      kind: label(o.kind),
+      observed_ts: o.observedTs,
+
+      // ── LIVENESS ────────────────────────────────────────────────────────────────────────────
+      // `integration_up`, not `reachable`, because that is the name the producer contract uses
+      // (`nexus_devtools/events.py:integration_probe`, from which `contract/events.v1.json` is
+      // generated). The console's `lib/features/operate/types.ts` still spells it `reachable`; it
+      // was written before the builders landed. Two names for one register is how the distinction
+      // this event exists to make gets quietly merged, so the producer's name wins here.
+      integration_up: o.integrationUp,
+      auth_ok: o.authOk,
+      latency_ms: o.latencyMs,
+
+      // ── FRESHNESS — a different register, and never derived from the one above ──────────────
+      last_data_ts: o.lastDataTs,
+      rows: o.rows,
+      schema_fingerprint: label(o.schemaFingerprint, 64),
+
+      // Content-free companion to `error`. It survives every tier, which matters because the
+      // alarm branches on it: an alarm that only works at `full` is not an alarm.
+      error_class: label(o.errorClass),
+      detected_by: 'sdk',
+    });
+
+    // Error text on the full ladder, with the limits `nexus/contract.py` uses for this field
+    // (512 / 280 — wider than the others, because a vendor exception is where the diagnosis is).
+    //
+    // The `hashed` rung used to be missing here: shape at every tier, text at `full`, and nothing
+    // in between, "because previewing safely needs a redactor this SDK does not have". It has one
+    // now, so the rung exists and this field stops being the one place the ladder had a step
+    // missing. That gap was also the most consequential place to have it — an integration probe's
+    // error is the single field an operator reads first when something has gone wrong.
+    Object.assign(e, tieredText('error', o.error, cfg.tier, 512, 280));
+    return e;
+  },
+
+  /**
+   * A window of observed service behaviour — a behaviour trace.
+   *
+   * Every quantity is independently optional, and that is the whole design of the event. A producer
+   * that measured latency but not saturation must not be made to look like one that measured
+   * neither, and a zero written where nothing was measured is the specific lie this plane exists to
+   * avoid: a service with `errors` absent is unmeasured, a service with `errors: 0` is healthy, and
+   * one number cannot be allowed to mean both. `base()` drops nulls, so absent stays absent all the
+   * way to the wire.
+   *
+   * The window is two explicit timestamps rather than a duration, because the reader's question is
+   * "over which period" and a bare `"5m"` cannot answer it once the record arrives late.
+   */
+  serviceHealth(sessionId, cfg, o) {
+    return base('service_health', sessionId, cfg, EPISTEMIC_BEHAVIOR, {
+      service: label(o.service, 128), app_id: label(o.appId, 128), env: label(o.env),
+      window_from: o.windowFrom, window_to: o.windowTo,
+      requests: o.requests, errors: o.errors,
+      p50_ms: o.p50Ms, p95_ms: o.p95Ms, p99_ms: o.p99Ms,
+      saturation: o.saturation,
+      detected_by: 'sdk',
+    });
+  },
+
+  // ── There is deliberately no `dataExpectation` builder here ─────────────────────────────────
+  //
+  // One used to sit at this spot and emit a `data_expectation` event. It was removed, and the
+  // removal is the parity fix rather than a feature being dropped.
+  //
+  // That type exists nowhere else in the system: `nexus_devtools/events.py` has no builder for it,
+  // so it is absent from the 51 `$defs` of `contract/events.v1.json`, which is generated from those
+  // builders. The Python SDK reaches the same point and stops — `nexus/api.py` keeps its `DECLARED`
+  // map in-process under a TODO stating that the declaration has no wire representation and that
+  // inventing an event type ahead of the artifact is forbidden.
+  //
+  // This SDK invented it anyway: a second producer writing a type the ledger has no model for,
+  // which is the drift the contract test exists to catch and which it missed because its corpus
+  // omitted the operate app. See `expectsData`, which still records the declaration in-process.
+  //
+  // Whether the event *should* exist is a decision for whoever owns the devtools event builders.
+  // Neither SDK settles it by emitting and letting the schema be regenerated to match.
+};
+
+// ---------------------------------------------------------------------------------------------
+// context — Python `context.py`. `AsyncLocalStorage` is Node's `contextvars`.
+// ---------------------------------------------------------------------------------------------
+
+const als = new AsyncLocalStorage();
+
+/**
+ * Two mechanisms, deliberately.
+ *
+ * `AsyncLocalStorage.run()` is the correct primitive — it propagates across `await`, `Promise.all`
+ * and timers, and it cannot leak one request's run into another's. But it requires the caller to
+ * hand us a callback, and `nexus.agent()` in this API returns a `Run` the caller holds across
+ * arbitrary code, exactly like Python's context manager. There is no `enterWith`-free way to make
+ * the returned-object form propagate, so `_stack` is the fallback for that shape and `runInScope`
+ * is offered for callers who can pass a callback and want real async isolation.
+ *
+ * This asymmetry is a genuine Node-vs-Python cost and it is written up in SCOPE.md §3.
+ */
+const _stack = [];
+
+function currentRun() {
+  const fromAls = als.getStore();
+  if (fromAls) return fromAls;
+  return _stack.length ? _stack[_stack.length - 1] : null;
+}
+
+// ---------------------------------------------------------------------------------------------
+// transport
+//
+// Two rules govern everything below.
+//
+// **The calling thread never performs I/O.** `enqueue` is an array push and a counter increment;
+// nothing else happens on the path a customer's request is on. Draining is a timer's job, and the
+// drain itself is async — `fs.promises.appendFile`, or an HTTP request. The one exception is the
+// `exit` handler, which Node only lets run synchronous work, and which by definition is not on
+// anybody's request path. That exception is why `flushSyncLastResort` exists and why it is named
+// the way it is: so that nobody reaches for it because it looked convenient.
+//
+// **The queue is bounded and drops OLDEST.** A telemetry buffer that grows without limit turns
+// our fault into the host's out-of-memory incident; a bounded one that refuses new events keeps
+// the *least* interesting data, because the newest events are the ones describing the incident
+// that caused the backlog. So the head goes. Every drop is counted, and the count is public —
+// silence about dropped data is a bug, not a tidy default.
+// ---------------------------------------------------------------------------------------------
+
+/** `true` for `http://…` / `https://…`; anything else is treated as a file path. */
+function isHttp(target) {
+  return typeof target === 'string' && /^https?:\/\//i.test(target);
+}
+
+/**
+ * Serialise a batch one event at a time — and that is the point.
+ *
+ * A customer can hand us a circular object in `effect({ … })`, or a getter that throws, or a
+ * `BigInt`. Serialising the batch in one `map` means one poisonous event destroys the other four
+ * hundred beside it, and the loss is silent because the exception surfaces as a failed flush
+ * rather than as a bad payload. Per-event, the poison costs exactly itself; the drop is counted
+ * under its own name so it can be told apart from a transport failure, which has a different fix.
+ *
+ * Returns the per-event strings rather than a finished body, because the two sinks want different
+ * envelopes around the same events — see {@link ndjsonBody} and {@link collectorBody}.
+ *
+ * @returns {string[]} one JSON string per event that could be serialised; may be empty.
+ */
+function serialise(batch) {
+  const lines = [];
+  for (const e of batch) {
+    try {
+      lines.push(JSON.stringify(e));
+    } catch (err) {
+      // Counted once per event, not once per attempt. A process configured with both sinks
+      // serialises the same batch twice, and a poison payload that reported two drops for one lost
+      // event would make the counters — the only place this loss is visible at all — wrong in the
+      // direction that matters, by overstating it.
+      if (!e[UNSERIALISABLE]) {
+        try { Object.defineProperty(e, UNSERIALISABLE, { value: true }); } catch (_) {}
+        incr('build_failed');
+        incr('queue_dropped');
+      }
+    }
+  }
+  return lines;
+}
+
+/**
+ * Per-event bookkeeping that must never reach the wire.
+ *
+ * Symbols rather than properties: `JSON.stringify` ignores symbol keys entirely, so there is no
+ * way for one of these to escape into an event body even if a future refactor stops filtering
+ * them, and no way for either to collide with a field the contract grows later.
+ */
+const WRITTEN_TO_FILE = Symbol('nexus.writtenToFile');
+const UNSERIALISABLE = Symbol('nexus.unserialisable');
+
+/** The file sink's format. NDJSON, because a file is appended to and read back line by line. */
+function ndjsonBody(lines) {
+  return lines.length ? lines.join('\n') + '\n' : null;
+}
+
+/**
+ * The collector's format, and it is NOT NDJSON.
+ *
+ * `POST /v1/events` in `nexus-devtools/collector.py` reads the body with a single `json.loads` and
+ * then looks for an `events` list:
+ *
+ *     data = json.loads(raw) if raw else {}
+ *     if isinstance(data, dict) and "events" in data: events = data.get("events")
+ *     else: events = [data]
+ *
+ * An NDJSON body of two or more events is not valid JSON, so it fails at `json.loads` and comes
+ * back `400 {"error": "invalid json"}`. The spike sent NDJSON to the bare collector URL with no
+ * `/v1/events` path, which means it earned a 404 first and would have earned a 400 after — both
+ * classified as permanent by `postJson` below, both therefore counted and dropped rather than
+ * retried. The customer-visible symptom is an empty dashboard and a healthy application, which is
+ * the precise failure mode this SDK exists to make impossible. `test/transport.test.mjs` runs the
+ * real ingest contract against a real server rather than trusting this comment.
+ *
+ * The array is assembled from pre-serialised strings so that poison isolation above survives: one
+ * unserialisable event is dropped and counted, and the other four hundred still ship.
+ */
+function collectorBody(lines) {
+  return lines.length ? '{"events":[' + lines.join(',') + ']}' : null;
+}
+
+/**
+ * The ingest path, appended to whatever base URL the operator configured.
+ *
+ * Mirrors `Config.events_url` in the Python SDK (`collector_url.rstrip("/") + "/v1/events"`) so
+ * that one `NEXUS_COLLECTOR_URL` value works for both SDKs. Idempotent: a base that already ends
+ * in the path is left alone, because an operator who copied the full endpoint out of the docs
+ * should not silently get `/v1/events/v1/events`.
+ */
+function eventsUrl(base) {
+  const trimmed = String(base).replace(/\/+$/, '');
+  return /\/v1\/events$/.test(trimmed) ? trimmed : trimmed + '/v1/events';
+}
+
+class Sink {
+  constructor(cfg) {
+    this.cfg = cfg;
+    this.queue = [];
+    this.path = cfg.sink && cfg.sink !== 'none' ? cfg.sink : null;
+    this.url = cfg.collectorUrl && cfg.collectorUrl !== 'none' ? cfg.collectorUrl : null;
+    this.lastSendOk = null;
+    this._inflight = null;
+  }
+
+  /**
+   * Accept one event. Synchronous, allocation-only, and never throws.
+   *
+   * @returns {boolean} whether the event was accepted. `false` means the queue was full *and*
+   *   something older was discarded to make room — the event itself is always kept.
+   */
+  enqueue(event) {
+    if (!event) return false;
+    const cap = this.cfg.queueCapacity || 10000;
+    let dropped = 0;
+    while (this.queue.length >= cap) {
+      this.queue.shift();
+      dropped += 1;
+    }
+    if (dropped) {
+      incr('queue_dropped', dropped);
+      // Peak depth is the number that tells a customer whether they are near the edge or over it.
+      if ((counters.queue_depth_peak || 0) < cap) counters.queue_depth_peak = cap;
+    }
+    this.queue.push(event);
+    incr('events_enqueued');
+    if (this.queue.length > (counters.queue_depth_peak || 0)) counters.queue_depth_peak = this.queue.length;
+    return dropped === 0;
+  }
+
+  depth() { return this.queue.length; }
+
+  /** Nothing configured means the events are counted and discarded — a supported test mode. */
+  get inert() { return !this.path && !this.url; }
+
+  _take() {
+    const batch = this.queue;
+    this.queue = [];
+    return batch;
+  }
+
+  _requeueFront(batch) {
+    // Put an undelivered batch back at the *front*, so ordering survives a transient failure, and
+    // let `enqueue`'s cap shed the oldest if the backlog is now over the line. Re-queueing is only
+    // done for errors that plausibly clear (a timeout, a refused connection). A 4xx does not
+    // clear by being retried, and re-queueing it is how a queue becomes a memory leak.
+    this.queue = batch.concat(this.queue);
+    const cap = this.cfg.queueCapacity || 10000;
+    if (this.queue.length > cap) {
+      const over = this.queue.length - cap;
+      this.queue.splice(0, over);
+      incr('queue_dropped', over);
+    }
+  }
+
+  /**
+   * Drain the queue, off the calling thread, within `deadlineMs`.
+   *
+   * Bounded on purpose. An unbounded flush turns container shutdown into a hang: the collector is
+   * exactly the thing most likely to be unhealthy at the moment the fleet is being restarted, and
+   * a telemetry SDK that will not let a pod terminate has become the outage.
+   *
+   * @returns {Promise<boolean>} whether the queue emptied and the write was acknowledged.
+   */
+  async flush(deadlineMs) {
+    if (!this.queue.length) return true;
+    if (this._inflight) {
+      // Concurrent flushes (timer + explicit call) must not interleave two writers on one file.
+      try { await this._inflight; } catch (_) { /* the other caller owns that outcome */ }
+      if (!this.queue.length) return true;
+    }
+    const deadline = deadlineMs === undefined ? (this.cfg.flushDeadlineMs || 2000) : deadlineMs;
+    const batch = this._take();
+    const p = this._send(batch, deadline);
+    this._inflight = p;
+    try {
+      return await p;
+    } finally {
+      if (this._inflight === p) this._inflight = null;
+    }
+  }
+
+  /**
+   * Optional durable overflow for a batch the collector permanently refused. Off unless `spillDir`
+   * is configured.
+   *
+   * Off by default, and the default is the point: containers are frequently read-only, and a
+   * telemetry SDK that fails because it could not create a directory has inverted its own
+   * priorities. When it is off, an abandoned batch is counted and dropped, which `counters()`
+   * reports rather than hides.
+   *
+   * Synchronous, and deliberately so: this runs on the abandon path, which is also reachable from
+   * the exit handler, and an async write there is a write that does not happen. The cost is paid
+   * only when a batch was going to be lost anyway.
+   *
+   * Nothing here can throw. A spill that fails is a spill that did not happen — the batch was
+   * already abandoned, so the only thing a raised error could add is an outage.
+   */
+  _spill(batch) {
+    if (!this.cfg.spillDir) return;
+    try {
+      fs.mkdirSync(this.cfg.spillDir, { recursive: true });
+      // The file name carries a timestamp and the pid, so two processes spilling in the same
+      // second on a shared volume do not silently overwrite one another's evidence.
+      const name = 'nexus-spill-' + Date.now() + '-' + process.pid + '.jsonl';
+      const body = ndjsonBody(serialise(batch));
+      if (body) fs.appendFileSync(require('node:path').join(this.cfg.spillDir, name), body);
+      incr('spilled', batch.length);
+    } catch (_err) {
+      incr('spill_failed');
+    }
+  }
+
+  async _send(batch, deadlineMs) {
+    // Before the inert check, so the rollup works with `NEXUS_COLLECTOR_URL=none` and in tests. It
+    // reads events that are on their way out anyway; the calling path pays a bounded fold over a
+    // batch it is already serialising.
+    if (this.onDrain) this.onDrain(batch);
+    if (this.inert) { this.lastSendOk = true; return true; }
+    let ok = true;
+
+    // ── the file sink, over the events it has not already been given ──────────────────────────
+    //
+    // The filter is load-bearing rather than an optimisation. The two sinks share one queue but
+    // have different retry semantics: an HTTP failure that is retryable puts the whole batch back
+    // on the queue, and without this the next flush would append those same events to the file a
+    // second time. That produces duplicate `event_id`s in the file — the one field the ledger
+    // dedups on — so a single unreachable collector would silently corrupt the local corpus of a
+    // process that was configured with both. Surfaced by `test/contract.test.mjs`'s duplicate-id
+    // assertion the moment the collector default became a real URL rather than `null`.
+    //
+    // Marked with a Symbol so the flag is non-enumerable, never reaches `JSON.stringify`, and
+    // cannot collide with a field the contract might grow later.
+    if (this.path) {
+      const fresh = batch.filter((e) => !e[WRITTEN_TO_FILE]);
+      const lines = serialise(fresh);
+      if (lines.length) {
+        try {
+          await withDeadline(fs.promises.appendFile(this.path, ndjsonBody(lines)), deadlineMs);
+          for (const e of fresh) {
+            try { Object.defineProperty(e, WRITTEN_TO_FILE, { value: true }); } catch (_) {}
+          }
+        } catch (err) {
+          incr('disk_error');
+          incr('queue_dropped', fresh.length);
+          // Deliberately not re-queued: an unwritable path usually stays unwritable, and a queue
+          // that only grows turns a telemetry fault into the host's memory problem.
+          ok = false;
+        }
+      }
+    }
+
+    if (this.url) {
+      const lines = serialise(batch);
+      if (!lines.length) { this.lastSendOk = ok; return ok; }   // every event was unserialisable
+      const res = await postJson(this.url, collectorBody(lines), this.cfg, deadlineMs);
+      if (res.ok) {
+        incr('send_ok');
+        incr('events_sent', batch.length);
+      } else {
+        incr('send_failed');
+        if (res.retryable) {
+          this._requeueFront(batch);
+          incr('requeued', batch.length);
+        } else {
+          // Permanent: a 400 from a body the collector cannot parse, a 404 from a wrong path, a
+          // 401 from a credential it will not accept. Retrying any of those forever is how a
+          // telemetry queue becomes a memory leak, so the batch is abandoned — and abandoned is
+          // counted apart from evicted, because "the collector refused it" and "we ran out of
+          // room" have completely different fixes.
+          this._spill(batch);
+          incr('send_abandoned', batch.length);
+          incr('queue_dropped', batch.length);
+        }
+        ok = false;
+      }
+    }
+
+    this.lastSendOk = ok;
+    return ok;
+  }
+
+  /**
+   * The `exit` handler's only option.
+   *
+   * Node runs `exit` listeners synchronously and does not wait for a promise, so this is the one
+   * place a synchronous write is the honest choice rather than a lazy one. It writes to the file
+   * sink only: there is no synchronous HTTP in Node, and pretending otherwise (a blocking
+   * `execSync('curl')`, say) would be a worse hang than the data loss it prevents. When only a
+   * collector URL is configured, an un-flushed buffer at `exit` is **lost**, it is counted as
+   * lost, and `docs`/README say so rather than implying delivery.
+   */
+  flushSyncLastResort() {
+    if (!this.queue.length) return true;
+    const batch = this._take();
+    if (!this.path) {
+      incr('queue_dropped', batch.length);
+      incr('dropped_at_exit', batch.length);
+      return false;
+    }
+    try {
+      const body = ndjsonBody(serialise(batch.filter((e) => !e[WRITTEN_TO_FILE])));
+      if (body !== null) fs.appendFileSync(this.path, body);
+      return true;
+    } catch (err) {
+      incr('disk_error');
+      incr('queue_dropped', batch.length);
+      return false;
+    }
+  }
+}
+
+/** Reject with a marker error once `ms` has elapsed, without leaving a timer holding the loop. */
+function withDeadline(promise, ms) {
+  return new Promise((resolve, reject) => {
+    const t = setTimeout(() => reject(new Error('nexus: deadline')), ms);
+    if (typeof t.unref === 'function') t.unref();
+    promise.then(
+      (v) => { clearTimeout(t); resolve(v); },
+      (e) => { clearTimeout(t); reject(e); },
+    );
+  });
+}
+
+/**
+ * Whether the bearer credential may travel to this URL.
+ *
+ * Mirrors `HttpSink._auth_allowed` in the Python SDK, and it is a real defence rather than
+ * ceremony. The default collector is loopback, so the ordinary case is safe; the dangerous case is
+ * an operator who points `NEXUS_COLLECTOR_URL` at `http://collector.internal:8791` and does not
+ * think about the fact that the token now crosses a network in cleartext, where anything on the
+ * path can read it and replay it.
+ *
+ * The rule: send it over `https:` anywhere, or over `http:` only to a loopback host. Otherwise
+ * WITHHOLD it — do not refuse to send the events. Withholding produces a 401 from the collector,
+ * which latches and is visible to the operator as a diagnosable auth failure. Refusing the whole
+ * send would produce silence, and silence is indistinguishable from an application that is simply
+ * not busy.
+ *
+ * `0.0.0.0` is deliberately not loopback: it is a bind-any address, not a destination, and
+ * treating it as local is how a token ends up on a wire.
+ */
+function authAllowed(u) {
+  if (u.protocol === 'https:') return true;
+  const host = (u.hostname || '').replace(/^\[|\]$/g, '').toLowerCase();
+  if (host === 'localhost' || host === '::1') return true;
+  // 127.0.0.0/8, and only that. `127.1` is a legal spelling of loopback but not one anybody
+  // configures deliberately, and a narrow test that occasionally withholds is the safe direction.
+  return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host);
+}
+
+/**
+ * `POST` one batch of events as JSON. Zero dependencies, so `node:http`/`node:https` directly.
+ *
+ * Never throws — the caller is a flush that must not become the customer's exception. The return
+ * distinguishes *retryable* (timeout, connection refused, 5xx, 429) from *permanent* (4xx), which
+ * is the difference between a queue that recovers and a queue that leaks.
+ */
+function postJson(url, body, cfg, deadlineMs) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (r) => { if (!settled) { settled = true; resolve(r); } };
+    try {
+      const u = new URL(eventsUrl(url));
+      const mod = u.protocol === 'https:' ? require('node:https') : require('node:http');
+      const headers = {
+        'content-type': 'application/json',
+        'content-length': Buffer.byteLength(body),
+        // The self-exclusion marker, spelled exactly as the Python SDK spells it. A nexus process
+        // observing its own telemetry egress would report itself as a busy outbound integration
+        // and, worse, feed its own health signal back into the ledger it is producing.
+        'x-nexus-sdk-egress': '1',
+        'user-agent': 'nexus-sdk-node/' + SDK_VERSION,
+        'x-nexus-producer': PRODUCER,
+        'x-nexus-sdk-version': SDK_VERSION,
+      };
+      if (cfg.apiKey && authAllowed(u)) headers.authorization = 'Bearer ' + cfg.apiKey;
+      else if (cfg.apiKey) incr('auth_withheld');
+
+      const req = mod.request(u, {
+        method: 'POST',
+        headers,
+        timeout: Math.min(cfg.httpTimeoutMs || 2000, deadlineMs),
+      }, (res) => {
+        // Drain, or the socket is never released back to the agent.
+        res.resume();
+        res.on('end', () => {
+          const code = res.statusCode || 0;
+          // The collector answers 202 with `{"accepted": n}`; 2xx generally means ingested.
+          if (code >= 200 && code < 300) return done({ ok: true, retryable: false, status: code });
+          // 3xx lands here as a permanent failure, and that is the intended behaviour rather than
+          // an oversight. `node:http` does not follow redirects on its own, so unlike `fetch` there
+          // is no risk of replaying the `Authorization` header to a host the operator never
+          // configured — the Python SDK has to install a `_NoRedirect` handler to get the same
+          // property. Treating it as permanent means a misconfigured redirect is loud (counted as
+          // abandoned) instead of an infinite retry loop against a URL that will never accept us.
+          if (code === 401 || code === 403) incr('auth_failed');
+          done({ ok: false, retryable: code === 429 || code >= 500, status: code });
+        });
+      });
+      req.on('timeout', () => { req.destroy(); done({ ok: false, retryable: true, status: 0 }); });
+      req.on('error', () => done({ ok: false, retryable: true, status: 0 }));
+      req.end(body);
+    } catch (err) {
+      // A malformed URL is permanent; retrying it forever would be a busy loop against nothing.
+      incr('disk_error');
+      done({ ok: false, retryable: false, status: 0 });
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------------------------
+// client
+// ---------------------------------------------------------------------------------------------
+
+let _client = null;
+
+class Client {
+  constructor(cfg) {
+    this.cfg = cfg;
+    this.sessionId = crypto.randomUUID().replace(/-/g, '');
+    this.instanceId = buildInstanceId();
+    this.sink = new Sink(cfg);
+    this.started = false;
+    this.health = new HealthRollup(now);
+    // The rollup reads what the sink is already draining, so it has to be handed the batch on the
+    // way past rather than asked for it. A callback rather than a back-reference: the sink has no
+    // other reason to know a client exists, and giving it one would make the drain path depend on
+    // a whole object graph it does not use.
+    this.sink.onDrain = (batch) => { guard('health.observe', () => this.health.observe(batch)); };
+  }
+
+  start() {
+    if (this.started) return;
+    this.started = true;
+    this.emit(contract.session(this.sessionId, this.cfg, this.instanceId, {
+      node: process.version,
+      // Which loader saw us. The single most useful field when a customer reports silence, because
+      // "bundled" is a documented dead end for auto-instrumentation (F3 case 1.18) and this is how
+      // support sees it without asking.
+      instrumentation: describeInstrumentation(),
+    }));
+    this.emitHealth('session_start');
+    this._startTimer();
+
+    // `exit` only permits synchronous work — Node does not await a promise returned from an `exit`
+    // listener — which is why this is the one call site allowed to reach for the synchronous
+    // write, and why that method is named `flushSyncLastResort` rather than something convenient.
+    // A container being torn down does not wait, and an `exit` handler is by definition not on
+    // anybody's request path.
+    this._onExit = () => {
+      guard('client.atexit', () => { this.emitHealth('stop'); this.sink.flushSyncLastResort(); });
+    };
+    // `beforeExit` still has a working event loop, so the real asynchronous flush can run here and
+    // usually does — `exit` then finds an empty queue. This is the ordinary path for a CLI or a
+    // test process; the synchronous one above is the backstop for `process.exit()` and signals.
+    this._onBeforeExit = () => { guard('client.beforeExit', () => { void this.flush(); }); };
+    process.once('exit', this._onExit);
+    process.once('beforeExit', this._onBeforeExit);
+  }
+
+  /**
+   * The background drain.
+   *
+   * `unref()` is the whole point: a telemetry timer that keeps the event loop alive turns a script
+   * that should have exited into one that hangs for the flush interval, and the customer reads
+   * that as our bug because it is. An unref'd timer runs while the process has other work and
+   * stops holding it open the moment it does not.
+   */
+  _startTimer() {
+    if (this.sink.inert) return;              // nothing configured: no timer, nothing to drain to
+    this._timer = setInterval(() => {
+      guard('client.tick', () => {
+        // The health window closes on the flush tick rather than on a timer of its own. One timer
+        // is one thing holding the event loop's attention, and a second interval whose only job is
+        // to check a clock is a second thing a serverless freeze can strand mid-cycle.
+        this.rollHealth(false);
+        void this.flush();
+      });
+    }, this.cfg.flushIntervalMs || 2000);
+    if (typeof this._timer.unref === 'function') this._timer.unref();
+  }
+
+  _stopTimer() {
+    if (this._timer) { clearInterval(this._timer); this._timer = null; }
+  }
+
+  emit(event) {
+    return guard('client.emit', () => this.sink.enqueue(event), false);
+  }
+
+  /**
+   * Close the `service_health` window if it is due, and emit it if there was anything in it.
+   *
+   * @param {boolean} force `heartbeat()`'s path — close the window now, and emit it even when empty.
+   * @returns {boolean} whether an event was emitted.
+   */
+  rollHealth(force) {
+    return guard('client.rollHealth', () => {
+      if (!force && !this.health.due(this.cfg.healthIntervalMs)) return false;
+      const event = this.health.roll(this.sessionId, this.cfg, contract, force);
+      if (!event) return false;
+      this.emit(event);
+      return true;
+    }, false);
+  }
+
+  emitHealth(checkpoint) {
+    guard('client.health', () => {
+      // One and only one closing record per process. `shutdown()` and the `exit` handler both want
+      // to write it, and a duplicated stop makes the queue-depth series look like a restart loop.
+      if (checkpoint === 'stop') {
+        if (this._stopped) return;
+        this._stopped = true;
+      }
+      this.emit(contract.pipelineHealth(this.sessionId, this.cfg, {
+        instanceId: this.instanceId, checkpoint, counters: snapshot(),
+        queueDepth: this.sink.depth(), collectorUp: this.sink.lastSendOk !== false,
+        // Deliberately no `runtime` here, and it is the one pipeline_health field the two SDKs do
+        // not share. Python's is `{transport_mode: thread|sync}` — which fork of its transport is
+        // running — and Node has no transport modes to report, because it has one event loop and
+        // there is no thread-vs-sync choice to make (PARITY.md §2). Emitting an empty object or a
+        // made-up mode to make the shapes match would be inventing a fact to satisfy a diff.
+      }));
+    });
+  }
+
+  /** @returns {Promise<boolean>} whether the queue emptied within the deadline. */
+  flush(deadlineMs) {
+    return guardAsync('client.flush', () => this.sink.flush(deadlineMs), false);
+  }
+
+  /**
+   * Final flush, then stop being a running thing.
+   *
+   * The timer is cleared *first*. A shutdown that leaves an interval armed means the last thing a
+   * terminating process does is schedule work, and the `exit` handler then races a drain it did
+   * not start.
+   */
+  shutdown(deadlineMs) {
+    return guardAsync('client.shutdown', async () => {
+      this._stopTimer();
+      this.emitHealth('stop');
+      return await this.sink.flush(deadlineMs);
+    }, false);
+  }
+}
+
+function getClient() { return _client; }
+
+/**
+ * The client, creating a default one if the application never called `init()`.
+ *
+ * Auto-instrumentation can be armed by a `--import` flag the app author never edited, so "the app
+ * never introduced itself" is a supported state. Capturing under `service: "unknown"` is right;
+ * discarding the data because nobody called `init` is not.
+ */
+function ensureClient() {
+  if (_off) return null;
+  if (_client) return _client;
+  _client = new Client(resolveConfig());
+  _client.start();
+  return _client;
+}
+
+/**
+ * Switched off, at the layer that can actually make it true.
+ *
+ * `src/index.js` and `src/index.cjs` short-circuit before reaching this module, which is what
+ * makes the disabled import cheap. This flag is the *second* line: anything holding a direct
+ * reference to the core — the hooks, a test, a re-export a bundler produced — must find the same
+ * answer, or `NEXUS_ENABLED=0` is only a promise about one entry point. Read once at load, because
+ * a switch that can flip mid-process would mean re-reading the environment on every call *and*
+ * promising the SDK can arm itself later, which "no timers, no sockets, no handlers" cannot honour.
+ */
+let _off = !envEnabled();
+
+function init(opts) {
+  return guard('init', () => {
+    const cfg = resolveConfig(opts);
+    if (!cfg.enabled) { _off = true; return null; }
+    if (!_client) {
+      _client = new Client(cfg);
+      _client.start();
+    } else {
+      // Re-init adopts the new identity and keeps the queue and the session. Tearing them down
+      // would drop whatever is buffered and orphan any in-flight run.
+      _client.cfg = cfg;
+      _client.sink.cfg = cfg;
+      if (cfg.sink && cfg.sink !== 'none') _client.sink.path = cfg.sink;
+    }
+    return _client;
+  }, null);
+}
+
+function resetForTests() {
+  if (_client) {
+    _client._stopTimer();
+    // Detach the lifecycle handlers too. `start()` adds an `exit` and a `beforeExit` listener, and
+    // a suite that calls `init()` a few hundred times would otherwise accumulate them until Node
+    // prints a MaxListenersExceededWarning — which reads like a leak in the SDK, is one in the
+    // test harness, and would eventually make every test run noisy enough that a real warning got
+    // lost in it. `removeListener` on a handler that already fired is a no-op.
+    if (_client._onExit) process.removeListener('exit', _client._onExit);
+    if (_client._onBeforeExit) process.removeListener('beforeExit', _client._onBeforeExit);
+  }
+  _client = null;
+  _off = !envEnabled();
+  _stack.length = 0;
+  _expectations.length = 0;
+  // The declarations map is module-global for the same reason `_expectations` is, and had to be
+  // cleared here for the same reason: without it a test reads the previous test's declaration and
+  // its assertions become statements about whatever ran before it.
+  DECLARED.clear();
+  // Process-global, and therefore leaks between tests unless it is reset here: once any test built
+  // the AI bridge, every later test saw `instrumentation() === 'ai-sdk'` regardless of what it had
+  // done. Resetting to the unarmed value is what makes the assertion "this call is what turned it
+  // on" mean anything.
+  _instrumentationMode = 'none';
+  _gateHook = null;
+  for (const k of Object.keys(counters)) delete counters[k];
+}
+
+// ---------------------------------------------------------------------------------------------
+// explicit API — Python `api.py`
+// ---------------------------------------------------------------------------------------------
+
+class Action {
+  constructor(run, name, target) {
+    this._run = run;
+    this.name = name;
+    this.target = target;
+    this._t0 = Date.now();
+    this._effect = {};
+    this._blocked = false;
+    this._reason = null;
+    this._closed = false;
+  }
+
+  effect(fields) {
+    guard('action.effect', () => { Object.assign(this._effect, fields || {}); });
+    return this;
+  }
+
+  block(reason) {
+    guard('action.block', () => { this._blocked = true; this._reason = reason; });
+    return this;
+  }
+
+  end(error) {
+    guard('action.end', () => {
+      if (this._closed) return;
+      this._closed = true;
+      this._run._actions += 1;
+      if (this._blocked) this._run._blocked += 1;
+      this._run._client.emit(contract.toolAction(this._run.sessionId, this._run._client.cfg, {
+        toolName: this.name, action: 'invoke', target: this.target,
+        blocked: this._blocked, reason: this._reason,
+        durationMs: Date.now() - this._t0,
+        runId: this._run.runId,
+        effect: Object.keys(this._effect).length ? this._effect : null,
+        error: error ? String(error && error.message ? error.message : error) : null,
+      }));
+    });
+    return this;
+  }
+}
+
+class Run {
+  constructor(client, name, goalClass) {
+    this._client = client;
+    this.name = name;
+    this.runId = crypto.randomUUID().replace(/-/g, '');
+    this.sessionId = client.sessionId;
+    this.goalClass = goalClass || null;
+    this._t0 = Date.now();
+    this._actions = 0;
+    this._blocked = 0;
+    this._closed = false;
+    this._outcome = null;
+    this._pushed = false;
+  }
+
+  _start() {
+    guard('run.start', () => {
+      _stack.push(this);
+      this._pushed = true;
+      this._client.emit(contract.agentRun(this.sessionId, this._client.cfg, {
+        runId: this.runId, name: this.name, phase: 'start', goalClass: this.goalClass,
+      }));
+    });
+    return this;
+  }
+
+  /** One effect on the world, bracketed. The enforcement seam lives here (WP-6). */
+  /**
+   * Open an action, **after asking policy whether it may happen.**
+   *
+   * This is the only gated call site in this SDK, and the only one that can be. Enforcement needs a
+   * decision taken *before* the effect, which needs a call site the customer owns — the AI SDK seam
+   * has no return channel to refuse on, and module hooks do not survive bundling. So: here, a
+   * gateway, or nothing.
+   *
+   * **The gate runs outside the `guard`, and that is the whole point.** `guard` exists to stop an
+   * SDK bug reaching the host, and it would happily swallow a `Denied` — turning a refusal into a
+   * silently-permitted call, which is precisely the failure mode the AI seam has and this call site
+   * exists to avoid. `Denied` is the one exception this SDK may raise, and the host opted into it
+   * twice: the rule carried `enforce: true` and the call site did not decline.
+   *
+   * With no policy installed — the default — `_gateHook` is null and this is the same function it
+   * was before. Nothing changes until a signed envelope arrives.
+   */
+  action(name, target) {
+    if (_gateHook !== null) {
+      // Deliberately not inside `guard`. A hook that throws `Denied` must propagate; a hook that
+      // throws anything else is a bug in policy, and `policy.check` already contains those and
+      // degrades to allow, so nothing but a real denial can get out of here.
+      _gateHook({ kind: 'tool_action', tool: name, target: target === undefined ? null : target });
+    }
+    return guard('run.action', () => new Action(this, name, target), INERT);
+  }
+
+  /** One **logical** model call. `attempts` because a vendor client retries internally. */
+  usage(o) {
+    guard('run.usage', () => {
+      this._client.emit(contract.tokenUsage(this.sessionId, this._client.cfg, {
+        model: o.model, provider: o.provider,
+        inputTokens: o.inputTokens, outputTokens: o.outputTokens,
+        cacheReadTokens: o.cacheReadTokens, cacheWriteTokens: o.cacheWriteTokens,
+        costUsd: o.costUsd, costSource: o.costSource,
+        runId: this.runId, attempts: o.attempts, incomplete: o.incomplete,
+        instrumentation: o.instrumentation,
+      }));
+    });
+    return this;
+  }
+
+  /**
+   * What the run achieved. `verifiedBy` is not ceremony: this event is tagged `behavior_trace`,
+   * the class reserved for verifiable fact. With nothing named as the verifier, `verified` stays
+   * absent — *"nothing was verified"* — rather than recording a claim as a fact.
+   */
+  outcome(outcome, opts) {
+    const o = opts || {};
+    guard('run.outcome', () => {
+      this._outcome = outcome;
+      this._client.emit(contract.turnOutcome(this.sessionId, this._client.cfg, {
+        runId: this.runId, outcome, verified: o.verified, verifiedBy: o.verifiedBy,
+        actions: this._actions, blocked: this._blocked,
+      }));
+    });
+    return this;
+  }
+
+  /** Close the run. Idempotent; safe to call from a `finally`. */
+  end(error) {
+    guard('run.end', () => {
+      if (this._closed) return;
+      this._closed = true;
+      if (this._pushed) {
+        const i = _stack.lastIndexOf(this);
+        if (i !== -1) _stack.splice(i, 1);
+        this._pushed = false;
+      }
+      this._client.emit(contract.agentRun(this.sessionId, this._client.cfg, {
+        runId: this.runId, name: this.name, phase: 'end', goalClass: this.goalClass,
+        durationMs: Date.now() - this._t0, actions: this._actions,
+        error: error ? String(error && error.message ? error.message : error) : null,
+      }));
+      if (this._outcome === null && error) {
+        this.outcome('error', { verified: false, verifiedBy: 'exception' });
+      }
+    });
+    return this;
+  }
+}
+
+function agent(name, opts) {
+  return guard('agent', () => {
+    const c = ensureClient();
+    if (!c) return INERT;                    // switched off: no client was ever built
+    return new Run(c, name, opts && opts.goalClass)._start();
+  }, INERT);
+}
+
+/**
+ * Scoped form. `AsyncLocalStorage.run` is the only shape in which the current run survives `await`
+ * correctly under concurrency; the returned-object form from `agent()` cannot, and both are offered
+ * rather than pretending otherwise.
+ */
+function withAgent(name, opts, fn) {
+  if (typeof opts === 'function') { fn = opts; opts = undefined; }
+  const run = agent(name, opts);
+  return als.run(run, async () => {
+    try {
+      const result = await fn(run);
+      run.end();
+      return result;
+    } catch (err) {
+      run.end(err);
+      throw err;                       // never swallow the application's exception
+    }
+  });
+}
+
+function action(name, target) {
+  return guard('action', () => {
+    const run = currentRun();
+    if (run) return run.action(name, target);
+    const c = ensureClient();
+    if (!c) return INERT;
+    // Outside any run: capture under an implicit parent rather than dropping the action.
+    const synthetic = new Run(c, 'unattributed');
+    synthetic._closed = true;
+    return new Action(synthetic, name, target);
+  }, INERT);
+}
+
+/**
+ * Drain the queue within a deadline.
+ *
+ * Asynchronous, and that is not an implementation detail: the calling thread must never perform
+ * I/O, so there is no synchronous form of this to offer. Callers that cannot await — an `exit`
+ * handler — are served by the sink's own last resort, which is deliberately not exported.
+ *
+ * @returns {Promise<boolean>}
+ */
+function flush(deadlineMs) {
+  const c = _client;
+  return c ? c.flush(deadlineMs) : Promise.resolve(true);
+}
+
+/** Final flush, then stop. @returns {Promise<boolean>} */
+function shutdown(deadlineMs) {
+  const c = _client;
+  return c ? c.shutdown(deadlineMs) : Promise.resolve(true);
+}
+
+// ═════════════════════════════════════════════════════════════════════════════════════════════
+// operate plane — the explicit calls (ANCHOR-INTEGRATION §6.2 and §6.4)
+//
+// Level 2 and Level 3 in the Python SDK's ladder: things auto-instrumentation cannot infer,
+// because they are facts about the *deployment* and about *what the data meant*, not about which
+// functions were called. Every one of them is guarded, so a mistake here cannot reach the host.
+// ═════════════════════════════════════════════════════════════════════════════════════════════
+
+/**
+ * §6.4 — self-report a deployment, as a fallback for an estate with no CI or cloud connector.
+ *
+ *     nexus.deployment({ version: '2026.8.1', commit: SHA, env: 'prod' });
+ *
+ * Anything omitted is taken from the resolved config, so on Vercel the whole call is usually
+ * `nexus.deployment()`. **`detected_by` is always `'self'` and is not a parameter.** A process
+ * asserting its own deployment is the weakest evidence on the plane — it is precisely what a
+ * shadow deploy would also produce — and a caller able to claim `'ci'` could erase that
+ * distinction with one argument.
+ *
+ * Emits nothing when neither a version nor a commit is known: a deployment record that identifies
+ * no software is a row that makes the ledger longer without making it truer. The refusal is
+ * counted so it is discoverable rather than mysterious.
+ *
+ * @returns {boolean} whether a record was emitted.
+ */
+function deployment(o) {
+  return guard('deployment', () => {
+    const c = ensureClient();
+    if (!c) return false;
+    const cfg = c.cfg;
+    const opts = o || {};
+
+    const version = opts.version || cfg.version || null;
+    const commit = opts.commit || cfg.commit || null;
+    if (!version && !commit) { incr('deployment_unidentified'); return false; }
+
+    c.emit(contract.deployment(c.sessionId, cfg, {
+      deploymentId: opts.deploymentId || cfg.deploymentId || selfDeploymentId(cfg, version, commit),
+      appId: opts.appId || cfg.application || null,
+      env: opts.env || cfg.env,
+      version,
+      commit,
+      repo: opts.repo || cfg.repo || null,
+      actor: opts.actor || null,
+      // Absent unless the caller supplies them. The process's own start time is not when the
+      // deployment finished, and `outcome: 'succeeded'` because we are running is a claim about a
+      // rollout we can only see one replica of.
+      startedTs: opts.startedTs || null,
+      finishedTs: opts.finishedTs || null,
+      outcome: opts.outcome || null,
+      rollbackOf: opts.rollbackOf || null,
+      provenance: cfg.provenance,
+    }));
+    return true;
+  }, false);
+}
+
+/**
+ * A deployment id for a self-report on a platform that did not supply one.
+ *
+ * Deterministic, and that is the entire requirement: forty replicas of one release must produce
+ * one deployment id, or the drift lanes show a rollout as forty deployments. Derived from the
+ * identity of the software rather than from a clock or a random source for the same reason. The
+ * `self:` prefix says out loud that nothing issued this id — we composed it.
+ */
+function selfDeploymentId(cfg, version, commit) {
+  return 'self:' + fingerprint([cfg.service, cfg.env, version || '', commit || ''].join('|'));
+}
+
+/**
+ * §6.2 — the silent-failure primitive, and the highest-value call on the plane.
+ *
+ *     const io = nexus.integration('salesforce', { kind: 'crm' });
+ *     try {
+ *       const rows = await client.fetchAccounts();
+ *       io.data({ rows: rows.length, watermark: rows[rows.length - 1].updatedAt });
+ *     } catch (err) {
+ *       io.failed(err, { errorClass: 'timeout' });
+ *     } finally {
+ *       io.end();
+ *     }
+ *
+ * or, bracketed for you, {@link withIntegration}.
+ *
+ * **The two registers are separate and must stay separate.** `end()` records *liveness* — the
+ * call completed. `data({ watermark })` records *freshness* — the newest business timestamp we
+ * actually saw. "The call succeeded", "the call succeeded and returned zero rows", and "the
+ * newest row is three days old" are three different facts, and the PRD's headline case (API
+ * healthy, data 72 h stale) is only expressible because no single field can express it. Every
+ * competitor's one green dot is structurally incapable of saying it.
+ *
+ * A handle that is never ended emits nothing. That is correct: we did not observe an outcome, and
+ * an unobserved probe must not become a recorded one.
+ */
+function integration(name, opts) {
+  return guard('integration', () => {
+    const c = ensureClient();
+    if (!c) return INERT;
+    return new Integration(c, name, opts || {});
+  }, INERT);
+}
+
+class Integration {
+  constructor(client, name, opts) {
+    this._client = client;
+    this.name = name;
+    this._opts = opts;
+    this._t0 = Date.now();
+    this._data = null;
+    this._error = null;
+    this._closed = false;
+  }
+
+  /**
+   * Freshness. `watermark` is the newest **business** timestamp observed — the `updated_at` of
+   * the last row, not our own clock, which would make a probe that fetched nothing look fresh.
+   *
+   * `rows: 0` means *we counted, and there were none*. No `rows` key means *we did not count*.
+   * Nothing here invents a default, because `dropNulls` cannot restore a distinction a caller's
+   * `|| 0` already destroyed.
+   */
+  data(fields) {
+    guard('integration.data', () => {
+      const f = fields || {};
+      const d = this._data || (this._data = {});
+      // Only what was SUPPLIED, and that is the fix rather than a style preference. This used to
+      // assign all three unconditionally, so `io.schema(row)` followed by `io.data({rows})` wrote
+      // `schemaFingerprint: undefined` straight over the fingerprint — the call order a caller
+      // naturally writes, silently discarding the field. Absent and supplied-as-undefined have to
+      // stay different here for the same reason `rows: 0` and no `rows` key do.
+      if (f.rows !== undefined) d.rows = f.rows;
+      if (f.schemaFingerprint !== undefined) d.schemaFingerprint = f.schemaFingerprint;
+      // `watermark` is the ergonomic name and the one the Python SDK uses; `last_data_ts` is the
+      // wire name. Both accepted, one meaning.
+      const wm = f.watermark !== undefined ? f.watermark : f.lastDataTs;
+      if (wm !== undefined) d.lastDataTs = isoOrNull(wm);
+    });
+    return this;
+  }
+
+  /**
+   * Say whether the credential was accepted. Only the caller knows; we never guess.
+   *
+   * It was previously reachable only as a constructor option (`integration(name, { authOk })`),
+   * which meant it had to be known before the call was made — and whether a credential was
+   * accepted is precisely the thing you learn afterwards. The Python SDK has had `io.auth(ok)`
+   * since the operate plane landed, so the same instrumentation could report `auth_ok` from a
+   * Python service and not from a Node one.
+   */
+  auth(ok) {
+    guard('integration.auth', () => { this._authOk = !!ok; });
+    return this;
+  }
+
+  /**
+   * Fingerprint the response's **shape**, so a silent schema break is visible before the rows stop
+   * matching. Keys only for an object; never values, at any tier.
+   *
+   * A port of `nexus/api.py:Integration.schema`, and it has to be an exact one: the fingerprint is
+   * a wire value two producers write into one column, so a Node service and a Python service
+   * reading the same API must produce the same digest or "the schema changed" fires on the day a
+   * customer migrated a service between languages. Same key bound (64), same cap (128 keys), same
+   * sort, same `,` join, same `sha256[:12]`.
+   *
+   * **The non-object case cannot agree and does not pretend to.** Python fingerprints
+   * `type(sample).__name__`, and JavaScript has no `list`, no `str`, and one `number` where Python
+   * has `int` and `float`. Mapping `Array`→`list` would be this SDK asserting the sample came from
+   * a Python process. The object case is the one a response sample actually takes; the scalar case
+   * is recorded as a difference in PARITY.md §3b rather than papered over.
+   */
+  schema(sample) {
+    guard('integration.schema', () => {
+      let shape;
+      if (sample && typeof sample === 'object' && !Array.isArray(sample)) {
+        shape = Object.keys(sample).slice(0, 128).map((k) => String(k).slice(0, 64)).sort().join(',');
+      } else if (Array.isArray(sample)) {
+        shape = 'Array';
+      } else {
+        shape = sample === null ? 'null' : typeof sample;
+      }
+      this._data = Object.assign(this._data || {}, { schemaFingerprint: fingerprint(shape) });
+    });
+    return this;
+  }
+
+  /** Liveness, negative. The call did not complete. */
+  failed(error, opts) {
+    guard('integration.failed', () => {
+      this._error = { error, errorClass: (opts && opts.errorClass) || null };
+    });
+    return this;
+  }
+
+  /** Python spells it `fail`. One meaning, two spellings, so neither reads as missing. */
+  fail(error, opts) {
+    return this.failed(error, opts);
+  }
+
+  /** Close the probe and emit exactly one observation. Idempotent. */
+  end(error) {
+    guard('integration.end', () => {
+      if (this._closed) return;
+      this._closed = true;
+      if (error && !this._error) this._error = { error, errorClass: null };
+      const failed = this._error !== null;
+      const d = this._data || {};
+      const cfg = this._client.cfg;
+      this._client.emit(contract.integrationProbe(this._client.sessionId, cfg, {
+        integration: this.name,
+        appId: this._opts.appId || cfg.application || null,
+        service: this._opts.service || cfg.service,
+        kind: this._opts.kind || null,
+        observedTs: now(),
+        // Observed, not assumed: the bracketed call either returned or it did not.
+        integrationUp: !failed,
+        authOk: this._authOk === undefined ? this._opts.authOk : this._authOk,
+        latencyMs: Date.now() - this._t0,
+        lastDataTs: d.lastDataTs,
+        rows: d.rows,
+        schemaFingerprint: d.schemaFingerprint,
+        error: failed ? errText(this._error.error) : null,
+        errorClass: failed ? this._error.errorClass : null,
+      }));
+    });
+    return this;
+  }
+}
+
+/**
+ * The bracketed form of {@link integration}, and the closest Node has to Python's
+ * `with nexus.integration(...) as io:`. The probe is closed on the way out including on throw, and
+ * the application's exception is re-thrown unchanged.
+ */
+function withIntegration(name, opts, fn) {
+  if (typeof opts === 'function') { fn = opts; opts = undefined; }
+  const io = integration(name, opts);
+  return (async () => {
+    try {
+      const result = await fn(io);
+      io.end();
+      return result;
+    } catch (err) {
+      io.failed(err);
+      io.end();
+      throw err;
+    }
+  })();
+}
+
+/**
+ * Declared expectations, so the alarm has something to be silent *against*.
+ *
+ * Deduplicated per process: a declaration made inside a scheduled function would otherwise be
+ * re-emitted on every tick, and ten thousand identical declarations is noise that makes the one
+ * that changed invisible.
+ */
+const _expectations = [];
+
+/** @see the comment at the `key` below. */
+const KEY_SEP = String.fromCharCode(0);
+
+/**
+ * §6.2 — declare that data is expected within a window.
+ *
+ *     nexus.expectsData('crm_sync', { within: '24h' });
+ *
+ * An expectation with no matching `integration_probe` inside its window is the silent-failure
+ * alarm. Note the asymmetry that keeps it honest: the alarm fires on **absence of evidence
+ * against a declared expectation**, never on absence alone — absence alone is indistinguishable
+ * from "nobody ever declared this", and an alarm that fires on that means nothing within a week.
+ *
+ * ── The declaration stays in this process, and does not become an event ──────────────────────
+ *
+ * This function used to emit a `data_expectation` event. It does not any more, and the removal is
+ * a parity fix rather than a feature being dropped.
+ *
+ * `data_expectation` exists nowhere else in the system. `nexus_devtools/events.py` has no builder
+ * for it, and it is therefore absent from the 51 `$defs` of `contract/events.v1.json`, which is
+ * generated from those builders. The Python SDK reaches exactly this point and stops —
+ * `nexus/api.py` holds its `DECLARED` map in-process under a TODO that says the declaration has no
+ * wire representation and that inventing an event type ahead of the artifact is forbidden. Until
+ * that event exists, Python delivers the *probe* half automatically and the alarm cannot fire from
+ * code alone.
+ *
+ * This SDK invented the type anyway, which is the same rule broken from the other side: a second
+ * producer writing a type the ledger has no model for. It was very likely dead on the wire in any
+ * case — a collector validating against the schema has nothing to validate it against.
+ *
+ * Whether that event *should* exist is a contract decision for the humans who own
+ * `nexus_devtools/events.py`. It is not something either SDK settles by emitting it and letting the
+ * schema be regenerated to match, because that ratifies the invention instead of deciding it. When
+ * a builder lands there, this is the place that changes — and `test/contract.test.mjs` fails the
+ * day the two lists diverge again, in either direction.
+ *
+ * The declaration is still recorded here, so an in-process reader (and a future exporter) can see
+ * it, and so the duplicate-suppression below still means something.
+ *
+ * @returns {boolean} whether this was a new declaration (`false` on a repeat).
+ */
+/**
+ * Close the current `service_health` window now and emit it, even if nothing was measured.
+ *
+ * The honest form of "this process is alive". A window with a timestamp and **no quantities** — no
+ * `requests`, no `errors`, no percentiles — because a process with no request loop still has
+ * something true to say and `requests: 0` is not it. Zero observed spans far more often means "this
+ * service never calls `run.action`" than it means an outage, and a fabricated zero reads on a
+ * console exactly like a measured one.
+ *
+ * Call it from a cron, a liveness probe, or a worker that processes a queue slowly.
+ *
+ * @returns {boolean} whether an event was emitted.
+ */
+function heartbeat() {
+  return guard('heartbeat', () => {
+    const c = ensureClient();
+    if (!c) return false;
+    return c.rollHealth(true);
+  }, false);
+}
+
+function expectsData(name, opts) {
+  return guard('expectsData', () => {
+    const c = ensureClient();
+    if (!c) return false;
+    const o = opts || {};
+    const within = String(o.within || '').trim();
+    if (!within) { incr('expectation_without_window'); return false; }
+
+    // A NUL separator, deliberately: it cannot occur in an integration name or in a window
+    // spelling, so the composite key cannot collide the way a space could. Built with
+    // `fromCharCode` so that no escape sequence ever appears in this source file.
+    const key = name + KEY_SEP + within;
+    if (_expectations.indexOf(key) !== -1) return false;
+    _expectations.push(key);
+
+    DECLARED.set(key, {
+      integration: name,
+      appId: o.appId || c.cfg.application || null,
+      within,
+      // Absent when the spelling could not be parsed. A wrong `withinMs` silently retimes
+      // somebody's alarm; an absent one makes a reader fall back to `within` verbatim.
+      withinMs: parseWithin(within),
+      declaredBy: o.declaredBy || null,
+      declaredTs: o.declaredTs || now(),
+    });
+    incr('expectation_declared');
+    return true;
+  }, false);
+}
+
+/**
+ * The in-process declarations, mirroring Python's `api.DECLARED`.
+ *
+ * Exposed so that the half of the feature that works is inspectable, and so that the day event 34
+ * exists there is one place holding everything an exporter would need. Read-only by convention;
+ * `declarations()` hands back a copy.
+ */
+const DECLARED = new Map();
+
+/** A snapshot of what this process has declared. Empty unless `expectsData` was called. */
+function declarations() {
+  return guard('declarations', () => Array.from(DECLARED.values()).map((d) => ({ ...d })), []);
+}
+
+/** `24h` · `30m` · `90s` · `7d` · `PT24H`. Anything else is `null` — never a guess. */
+function parseWithin(text) {
+  const s = String(text).trim();
+  const plain = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d|w)$/i.exec(s);
+  const UNIT = { ms: 1, s: 1000, m: 60000, h: 3600000, d: 86400000, w: 604800000 };
+  if (plain) return Math.round(parseFloat(plain[1]) * UNIT[plain[2].toLowerCase()]);
+  const iso = /^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$/i.exec(s);
+  if (iso && s.length > 1 && /\d/.test(s)) {
+    const d = Number(iso[1] || 0), h = Number(iso[2] || 0), m = Number(iso[3] || 0);
+    const sec = Number(iso[4] || 0);
+    return Math.round(((d * 24 + h) * 60 + m) * 60000 + sec * 1000);
+  }
+  return null;
+}
+
+/**
+ * A business timestamp, normalised the way `nexus/api.py:_watermark` normalises one.
+ *
+ * The string branch is the one that changed, and it changed to STOP reinterpreting. This used to
+ * parse a string and re-serialise it, so a caller's `"2026-08-30T12:00:00Z"` — read straight off
+ * their own record — came back as `"2026-08-30T12:00:00.000Z"`, and the same column held two
+ * timestamp formats depending on which SDK wrote the row. Worse, a timestamp `Date` could not
+ * parse was silently dropped to `null`, which the console draws as *no freshness data at all*:
+ * the exact signal the silent-failure alarm exists to raise, deleted on the way to it.
+ *
+ * Python's rule, and now this one: a string is used as the caller gave it, bounded. A caller read
+ * it off their own record; we are not in the business of reinterpreting somebody's format.
+ *
+ * **One unit difference remains, and it is deliberate.** A bare number here is epoch
+ * milliseconds, because that is what `Date.now()` returns and what a JavaScript caller will pass;
+ * Python reads epoch *seconds*, because that is what `time.time()` returns. Each is its own
+ * language's convention, and picking one would make the other SDK's idiomatic call wrong.
+ * PARITY.md §3b records it.
+ */
+function isoOrNull(v) {
+  if (v === null || v === undefined || v === '') return null;
+  if (v instanceof Date) return Number.isNaN(v.getTime()) ? null : v.toISOString();
+  if (typeof v === 'number' && Number.isFinite(v)) {
+    return v <= 0 ? null : new Date(v).toISOString();
+  }
+  const text = String(v).trim();
+  return text ? text.slice(0, 64) : null;
+}
+
+function errText(err) {
+  if (err === null || err === undefined) return null;
+  return String(err && err.message ? err.message : err);
+}
+
+// ---------------------------------------------------------------------------------------------
+// serverless — the lifecycle Node cannot infer
+//
+// A serverless platform freezes the sandbox the instant the handler returns. A background flusher
+// does not run late there; it does not run at all. Python solves this with an explicit
+// `instrument_lambda_handler`, and the same thing has to be explicit here, because there is no
+// signal a library can read that says "you are about to be frozen".
+//
+// This is stated rather than papered over: **without one of the two mechanisms below, the last
+// buffered events of every serverless invocation are lost.** Not delayed — lost. An SDK that let a
+// customer believe otherwise would be reporting a coverage number it knows is wrong.
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * Hand the host a promise it will keep the sandbox alive for.
+ *
+ * On Vercel this is `waitUntil` from `@vercel/functions`; it can also be given to `init()`. With
+ * it, a flush outlives the response without delaying it. Without it, {@link instrumentHandler}
+ * awaits the flush instead, which is correct but does add its duration to the invocation.
+ */
+function setWaitUntil(fn) {
+  guard('setWaitUntil', () => {
+    const c = ensureClient();
+    if (c) c.cfg.waitUntil = typeof fn === 'function' ? fn : null;
+  });
+}
+
+/**
+ * Wrap a serverless handler so the queue is drained before the sandbox freezes.
+ *
+ *     export const handler = nexus.instrumentHandler(async (event) => { … });
+ *
+ * The application's return value and its exceptions pass through untouched — the flush happens in
+ * a `finally`, so a handler that threw is still accounted for, which is exactly the invocation
+ * whose telemetry matters most.
+ */
+function instrumentHandler(handler, opts) {
+  if (typeof handler !== 'function') return handler;
+  const budgetMs = (opts && opts.budgetMs) || 1000;
+  return async function nexusInstrumentedHandler(...args) {
+    try {
+      return await handler.apply(this, args);
+    } finally {
+      await guardAsync('instrumentHandler.flush', async () => {
+        const c = _client;
+        if (!c) return;
+        const w = c.cfg.waitUntil;
+        // With `waitUntil` the platform owns the wait, so the response is not held for us.
+        if (w) { w(c.flush(budgetMs)); return; }
+        await c.flush(budgetMs);
+      });
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------------------------
+// instrumentation registry — shared by the ESM hook thread's shim output and the CJS hook
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * The policy gate, installed by `src/policy/index.cjs` when a customer imports it.
+ *
+ * A registration hook rather than a `require`, because `policy` requires `core` and the reverse
+ * would be a cycle. It also keeps the core honest: with nothing registered there is no policy code
+ * on the request path at all, which is what makes "adding the import changes no behaviour until an
+ * envelope arrives" literally true rather than approximately so.
+ */
+let _gateHook = null;
+
+/** Install the policy gate. Passing `null` removes it. */
+function setGateHook(fn) {
+  _gateHook = typeof fn === 'function' ? fn : null;
+}
+
+const INSTRUMENTED = Symbol.for('nexus.instrumented');
+let _instrumentationMode = 'none';
+
+function describeInstrumentation() { return _instrumentationMode; }
+function noteInstrumentation(mode) { _instrumentationMode = mode; }
+
+/**
+ * Adapters, keyed by package name.
+ *
+ * `mutate` patches objects reachable from the namespace in place — this works identically in both
+ * module systems, because an ESM namespace is a frozen record of *bindings*, and the objects those
+ * bindings point at are ordinary mutable objects.
+ *
+ * `rebind` lists exports that must be replaced *as bindings*. Those cannot be patched in place in
+ * ESM at all: `export function createClient` is an immutable binding in the importer. The only way
+ * to intercept one is to rewrite the module's source so a different value is exported — which is
+ * why the ESM hook generates a shim rather than just importing and mutating. This distinction is
+ * the single largest cost difference between the CJS and ESM paths; see SCOPE.md §2.
+ */
+/**
+ * **Empty in the published package, and that is the shipped state rather than a stub.**
+ *
+ * Module-hook auto-instrumentation is not part of this release (README, "What this does not do";
+ * SCOPE.md §3 and §7/D5 for the measurements behind that). The registry itself stays, because the
+ * AI SDK bridge and any future adapter need somewhere to record that a package was instrumented,
+ * and because an empty table is what makes `instrumentation()` able to answer `"none"` honestly.
+ *
+ * The one adapter that used to live here wrapped the stand-in provider package the spike's hook
+ * tests import. It now lives in `src/hooks/adapters-dev.cjs`, which the publish allowlist excludes
+ * — a test double compiled into a customer's production dependency is a supply-chain smell even
+ * when it is inert. `scripts/npm-guard.cjs` greps every shipped file for that package's name, so
+ * this cannot quietly come back; that check is also why this comment does not spell it out.
+ */
+const ADAPTERS = Object.create(null);
+
+/** Every capture path from a hook is guarded: a bad adapter must not break the customer's import. */
+function recordModelCall(provider, params, res, durationMs, err) {
+  guard('instrument.record', () => {
+    const client = ensureClient();
+    const run = currentRun();
+    const usage = (res && res.usage) || {};
+    client.emit(contract.tokenUsage(client.sessionId, client.cfg, {
+      model: (res && res.model) || (params && params.model) || 'unknown',
+      provider,
+      inputTokens: usage.input_tokens || 0,
+      outputTokens: usage.output_tokens || 0,
+      runId: run ? run.runId : undefined,
+      instrumentation: describeInstrumentation(),
+      incomplete: err ? true : undefined,
+    }));
+  });
+}
+
+function adapterFor(name) { return ADAPTERS[name] || null; }
+
+/** Called from the injected ESM shim and from the CJS `Module._load` patch alike. */
+function instrumentNamespace(pkg, ns) {
+  return guard('instrument.' + pkg, () => {
+    const adapter = adapterFor(pkg);
+    if (!adapter) return ns;
+    adapter.mutate(ns);
+    incr('instrumented.' + pkg);
+    return ns;
+  }, ns);
+}
+
+module.exports = {
+  SDK_VERSION, CONTRACT_VERSION, PRODUCER,
+  EPISTEMIC_BEHAVIOR, EPISTEMIC_RATIONALISATION, EPISTEMIC_NARRATIVE,
+  TIER_METADATA_ONLY, TIER_HASHED, TIER_FULL,
+  contract, base, fingerprint, now, wireText, tieredText, redactPreview, rungs, estTokens,
+  redact: redactor, pricing,
+  guard, guardAsync, INERT,
+  init, agent, withAgent, action, flush, shutdown,
+  deployment, integration, withIntegration, expectsData, declarations, DECLARED, heartbeat,
+  setWaitUntil, instrumentHandler,
+  parseWithin, isoOrNull, selfDeploymentId, provenance,
+  currentRun, counters: snapshot, incr, resetForTests, setGateHook,
+  getClient, ensureClient, Run, Action, Client, Integration, Sink,
+  ADAPTERS, adapterFor, instrumentNamespace, INSTRUMENTED, recordModelCall,
+  // Exported for tests. `authAllowed` is a pure predicate and the security property it encodes —
+  // a bearer token never rides plain HTTP off the machine — deserves a truth table asserted
+  // directly rather than inferred from whether some request happened to carry a header.
+  authAllowed, eventsUrl, resolveCollectorUrl,
+  describeInstrumentation, noteInstrumentation,
+  enabled: envEnabled,
+};