@swfte/nexus-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Swfte AI
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,38 @@
+@swfte/nexus-sdk  (Node)
+Copyright 2026 Swfte AI
+
+This product includes software developed at Swfte AI (https://swfte.com/).
+
+================================================================================
+Third-party components redistributed inside this package
+================================================================================
+
+None.
+
+That is not an oversight and it is not a placeholder. The published tarball
+contains no vendored code, no bundled dependency, and no `dependencies` entry —
+`npm ls --omit=dev --all` on an install of this package resolves to nothing but
+this package. `test/packaging.test.mjs` asserts it, so the claim cannot regress
+into a stale sentence in a NOTICE file that nobody re-reads.
+
+The Python sibling (`swfte-nexus-sdk`) *does* vendor two trees — `wrapt` and
+dd-trace-py's import machinery — because CPython's import-hook story has no
+usable stdlib equivalent. Node's does: `AsyncLocalStorage`, `node:http` and
+`crypto.randomUUID` are all builtins, and the one thing that would have required
+a third-party dependency in Node — `import-in-the-middle`, for module-hook
+auto-instrumentation — is deliberately not shipped (see README, "What this does
+not do"). The empty section below is a direct consequence of that decision
+rather than a coincidence, and if module hooks are ever shipped this file gains
+an entry in the same commit.
+
+================================================================================
+Development-only material, not distributed
+================================================================================
+
+`fixtures/vercel/` and `fixtures/oss/` install third-party packages (`ai`,
+`zod`, `@anthropic-ai/sdk`, OpenTelemetry and Traceloop instrumentation) in
+their own `node_modules` trees in order to measure how those libraries behave.
+None of it is a dependency of the SDK, none of it is imported by anything under
+`src/`, and none of it is present in the published tarball — the `files`
+allowlist in package.json and `scripts/npm-guard.js` both exclude the fixture
+trees, and the guard fails the publish if that ever stops being true.

package/README.md

@@ -0,0 +1,414 @@
+# @swfte/nexus-sdk
+
+**Agent observability and enforcement for Node services you run yourself.**
+
+[![npm](https://img.shields.io/npm/v/@swfte/nexus-sdk.svg)](https://www.npmjs.com/package/@swfte/nexus-sdk)
+[![Node](https://img.shields.io/node/v/@swfte/nexus-sdk.svg)](https://www.npmjs.com/package/@swfte/nexus-sdk)
+[![Licence](https://img.shields.io/badge/licence-Apache--2.0-blue.svg)](LICENSE)
+[![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](#why-no-dependencies)
+
+`nexus wrap` captures what an agent does inside a developer's terminal. This package captures the
+same thing inside your own Node application — a third attach point on one event ledger, stamped
+`producer="sdk"` so a run in production and a run on a laptop are the same shape in the same
+tables.
+
+```
+npm install @swfte/nexus-sdk
+```
+
+Node 18+. **Zero dependencies** — see [Why no dependencies](#why-no-dependencies). ESM and CommonJS
+both supported, from one instance.
+
+Part of **[Nexus by Swfte](https://www.swfte.com)** — savings, governance and a real audit trail
+for AI agents. This is the Node sibling of
+**[`swfte-nexus-sdk`](https://github.com/SwfteAI/nexus-sdk)** for Python: same concepts, same event
+shapes, same collector. See also the
+**[terminal wrapper](https://www.npmjs.com/package/@swfte/nexus)** (`npm i -g @swfte/nexus`).
+
+---
+
+## Contents
+
+| Section | |
+|---|---|
+| [Start here, if you are bundling](#start-here-if-you-are-bundling) | read this before anything else if you deploy a bundle |
+| [Three levels, pick one](#three-levels-pick-one) | the whole API, in increasing detail |
+| [Guarantees](#guarantees) | what this SDK promises never to do to your process |
+| [Configuration](#configuration) | every variable and the precedence rule |
+| [Privacy tiers](#privacy-tiers) | what actually goes on the wire, with a worked example |
+| [OpenTelemetry](#opentelemetry) | the OTLP bridge, and why it is a bridge |
+| [Enforcement](#enforcement) | the part that can say *no* |
+| [What this does not do](#what-this-does-not-do) | honestly, and with reasons |
+| [Why no dependencies](#why-no-dependencies) | and what that costs us instead |
+| [Development](#development) | running the suite, the layout |
+
+**Reference documentation**
+
+| Document | For |
+|---|---|
+| [`docs/API.md`](docs/API.md) | every export, its signature, and what it returns |
+| [`PARITY.md`](PARITY.md) | line-by-line account of what matches the Python SDK, what deliberately does not, and why |
+| [`SCOPE.md`](SCOPE.md) | the original feasibility spike — historical, kept for the record |
+| [`AGENTS.md`](AGENTS.md) | orientation for coding agents working in this repository |
+| [`CONTRIBUTING.md`](CONTRIBUTING.md) | how to run the suite and what review will ask |
+| [`SECURITY.md`](SECURITY.md) | reporting a vulnerability |
+| [`CHANGELOG.md`](CHANGELOG.md) | what changed, and why |
+
+---
+
+## Start here, if you are bundling
+
+Most Node advice about telemetry assumes it can patch your imports at startup. **In a bundled
+application that does not work, and it fails silently**, so it is worth knowing before you choose
+anything:
+
+| | ESM app | CJS app | bundled (esbuild / webpack / ncc / Next.js) |
+|---|---|---|---|
+| Module hooks (`--import`, `--require`) | works | works | **silently captures nothing** |
+| The Vercel AI SDK seam | works | works | **works** |
+| The explicit API | works | works | **works** |
+
+A bundler inlines your dependencies into your own file, so there is no `import '@anthropic-ai/sdk'`
+left for a hook to intercept — the module boundary the technique needs no longer exists in the
+artifact that runs. It is not degraded, it is absent, and worse: a bundled app carries its own
+inlined copy of the SDK, so events would belong to a different session from the app's own runs.
+
+Next.js bundles server code by default. That makes the deployment shape most likely to be running
+an agent in Node exactly the shape module hooks cannot serve.
+
+So this SDK is built on the two columns that survive. It ships no module hooks, and it does not
+offer zero-code capture in Node. When nothing is capturing, it says so — `instrumentation()`
+returns `"none"` and every `pipeline_health` record carries it. An empty dashboard that looks
+plausible is worse than an error.
+
+The measurements behind all of this are in [`SCOPE.md`](./SCOPE.md), and reproducible.
+
+---
+
+## Three levels, pick one
+
+**Level 1 — declare who you are.** One call, at startup:
+
+```js
+import * as nexus from '@swfte/nexus-sdk';
+
+nexus.init({ service: 'checkout', env: 'prod', version: '2026.8.1' });
+```
+
+Datadog's unified tagging. `service` / `env` / `version` land on every event as join keys. There is
+no user identity anywhere in this SDK: a service does not need one, and inventing one is how a
+telemetry pipeline becomes a compliance problem.
+
+**Level 2 — capture your model calls.** If you use the Vercel AI SDK, one more call:
+
+```js
+import { registerTelemetry } from 'ai';
+import { telemetry } from '@swfte/nexus-sdk/ai';
+
+registerTelemetry(telemetry());
+```
+
+Token counts with the cache-read/cache-write split, model and provider ids, tool names and
+durations, and exact cost from the cache split — with no changes at your call sites, and it survives
+bundling. Note the direction: you
+import `ai`, not us. This package has no dependency on it and no version range to conflict with
+yours.
+
+**Level 3 — say what the agent did.**
+
+```js
+await nexus.withAgent('refund-request', { goalClass: 'transaction' }, async (run) => {
+  const act = run.action('db.write', 'refunds');
+  act.effect({ rows: 1, amountCents: 4200 }).end();
+
+  run.usage({ model: 'claude-opus-4', inputTokens: 1800, outputTokens: 240 });
+  run.outcome('success', { verified: true, verifiedBy: 'ledger_balance' });
+});
+```
+
+A **run** is a unit of agent work with an outcome. An **action** is something with an effect on the
+world — the thing enforcement gates. The distinction is not stylistic: what an agent *did*
+(`behavior_trace`) and what a model *said it did* (`rationalisation`) are different epistemic
+classes, stamped as such, and only one is admissible as evidence.
+
+Prefer `withAgent` to `agent()` in async code. The current run propagates across `await` correctly
+there and only there (`AsyncLocalStorage`); the object returned by `agent()` cannot do that, and
+`action()` several frames down will not find it.
+
+All three levels compose.
+
+---
+
+## Guarantees
+
+**A telemetry SDK must never be the reason a request fails.** Concretely, each of these is a test:
+
+- Every public entry point is wrapped in a guard that contains exceptions and returns a safe
+  default. A guarded failure hands back an inert proxy rather than `undefined`, so host code
+  written against a `Run` keeps running instead of failing two lines later on
+  `cannot read property 'outcome' of undefined`.
+- The calling thread never performs I/O. `flush()` is asynchronous because there is no honest
+  synchronous form to offer.
+- The queue is bounded and drops **oldest**, because the newest events describe the incident. Every
+  drop is counted and reported in `counters()`. Silence about dropped data is a bug.
+- Shutdown flushes to a **deadline**. A hung collector must not hang your container — asserted by a
+  test with a server that accepts the request and never answers.
+- `SIGKILL` loses the in-flight buffer. That is not fixable and we do not pretend otherwise.
+
+### The kill switch is real
+
+```
+NEXUS_ENABLED=0
+```
+
+No timers, no sink opened, no exit handler, no socket. `NEXUS_ENABLED=0` beats
+`init({ enabled: true })` — an operator disabling telemetry from outside the process has to beat
+what the application says, or it is not a kill switch.
+
+---
+
+## Configuration
+
+Explicit arguments win over environment variables, which win over defaults. The one exception is
+`NEXUS_ENABLED=0`, which wins over everything.
+
+| Variable | Default | |
+|---|---|---|
+| `NEXUS_ENABLED` | `1` | `0` disables entirely |
+| `NEXUS_SERVICE` / `NEXUS_ENV` / `NEXUS_VERSION` | `unknown` | unified tagging; the service name also falls back to `OTEL_SERVICE_NAME` / `DD_SERVICE` / `K_SERVICE` / `AWS_LAMBDA_FUNCTION_NAME` |
+| `NEXUS_COLLECTOR_URL` | `http://127.0.0.1:8791` | full URL; `none` for no collector |
+| `NEXUS_COLLECTOR_HOST` / `_PORT` / `_SCHEME` | — | **sidecar mode**: not hardcoded loopback, IPv6 hosts bracketed |
+| `NEXUS_API_KEY` | — | bearer token; see below |
+| `NEXUS_TIER` | `metadata_only` | `metadata_only` / `hashed` / `full` |
+| `NEXUS_CONFIG_FILE` | — | JSON file, read only when named; no implicit search path |
+| `NEXUS_HEALTH_INTERVAL_MS` | `60000` | `service_health` window; `0` disables |
+| `NEXUS_SPILL_DIR` | — | durable overflow for batches the collector permanently refused |
+| `NEXUS_QUEUE_CAPACITY` | `10000` | events, then drop-oldest |
+| `NEXUS_BATCH_SIZE` | `500` | |
+| `NEXUS_FLUSH_INTERVAL_MS` / `NEXUS_FLUSH_DEADLINE_MS` | `2000` / `2000` | |
+| `NEXUS_HTTP_TIMEOUT_MS` | `2000` | |
+| `NEXUS_SDK_SINK` | — | append events to a file as NDJSON, for debugging |
+| `NEXUS_APPLICATION` / `NEXUS_REPO` / `NEXUS_COMMIT` / `NEXUS_BRANCH` / `NEXUS_DEPLOYMENT_ID` | auto | provenance; auto-detected from Vercel and GitHub Actions |
+| `NEXUS_DEBUG` | — | `1` writes contained errors to stderr |
+
+Events are `POST`ed to `{collector}/v1/events` as `{"events": [...]}`.
+
+**The bearer token is withheld from plain HTTP to a non-loopback host.** `https:` anywhere is fine,
+and `http:` to loopback is fine; anything else and the token is left off the request rather than
+sent in cleartext across a network. The request still goes, so you get a diagnosable 401 instead of
+silence.
+
+---
+
+## Privacy tiers
+
+Every free-text field carries its shape at every tier — `<name>_chars` and `<name>_fingerprint` are
+content-free, so "the same error as yesterday" stays answerable and a repeated target stays
+groupable without the text leaving the process. What changes per tier is the content beside it.
+
+| Tier | On the wire |
+|---|---|
+| `metadata_only` (default) | Shape only. The content key is absent — not blank, not masked. |
+| `hashed` | plus `<name>_preview`: redacted text, truncated. |
+| `full` | plus `<name>`: redacted text, at the field's full limit. |
+
+**A tier is a decision about content, never a waiver on credentials.** `full` is not "unscrubbed",
+it is "scrubbed, at greater length": bearer tokens, API keys in nineteen vendor shapes, PEM blocks,
+Luhn-valid card numbers, mod-97-valid IBANs, national IDs, phone numbers and email addresses go
+regardless of tier. Structured values are scrubbed too, which is the case a free-text redactor
+misses — `effect({ headers: { Authorization: 'Bearer …' } })` is masked by key name, and a number
+under a key that is not a recognised measurement is masked below `full`.
+
+The redactor is a port of the Python SDK's, and the two are checked against each other over a
+shared corpus (`node scripts/redact-parity.mjs`, 178 cases). One tier setting means the same thing
+in a Node service and a Python one.
+
+It is not magic, and the limits are worth knowing. It is a bounded set of anchored patterns plus
+key-name matching, not an entropy scan, because it runs on your request path. `Jane Doe` is not
+recognisable by any regular expression, so a field naming a person still contains their name at
+`full`. The default tier is the primary control; redaction is the second line.
+
+**The AI SDK bridge emits tool inputs and outputs on this ladder, and no model text.** Tool payloads
+are structured, which is exactly what the scrubber is for. Model text reaches the ledger through
+[`@swfte/nexus-sdk/otel`](#opentelemetry) instead, as `model_response` and `model_thinking`, where
+it is re-gated by your tier on ingest because upstream redaction is not trusted. The prompt itself
+is emitted by neither path: there is no `prompt` event in the contract for a second producer to
+write against.
+
+---
+
+## OpenTelemetry
+
+If you already run GenAI instrumentation — OpenInference, OpenLLMetry/OpenLIT, or anything emitting
+the OTel GenAI semantic conventions — the bridge turns its spans into nexus events:
+
+```js
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { spanProcessor } from '@swfte/nexus-sdk/otel';
+
+new NodeTracerProvider({ spanProcessors: [spanProcessor()] }).register();
+```
+
+Same direction as the AI SDK bridge: **you import OpenTelemetry, not us.** `spanProcessor()` returns
+a plain object with the four methods the interface requires, so this package still has no
+dependency and no version range to conflict with yours.
+
+Three things it does deliberately:
+
+- **An unclassified span is dropped, not guessed at.** A GenAI span whose kind is not modelled is
+  counted under `bridge_unclassified` and emitted nowhere — never defaulted into `behavior_trace`,
+  which is the class the ledger treats as evidence. A bridge that guesses produces confidently wrong
+  events, which is worse than none. `stats().unclassified` is the number to alert on.
+- **Model text is re-gated by your tier on ingest.** Every instrumentation in this space has its own
+  content-capture switch and its own idea of what a secret looks like; some have none. Whether text
+  leaves your process is your decision, not theirs.
+- **A tool call's arguments contribute a shape, not their values.** `{amount: 4200, note: '…'}`
+  becomes field names and types with no value at any depth, because `tool_action.target` is an
+  identifier field and a payload must not be standing in front of a gate that assumes one.
+
+---
+
+## Enforcement
+
+Every agent-observability tool observes. This one can also refuse:
+
+```js
+import * as policy from '@swfte/nexus-sdk/policy';
+
+policy.install(signedEnvelope);        // Ed25519, verified before a rule is read
+
+run.action('db.write', 'prod-orders'); // throws Denied if a rule says no
+```
+
+Importing that module gates `run.action(...)`. **It is the only gated call site**, and it is the
+only one that can be: enforcement needs a decision taken before the effect, which needs a call site
+you own. Tool calls made through the AI SDK seam cannot be gated in-process — see below.
+
+A policy is a signed envelope from your control plane. A rule refuses for real only if it carries
+`"enforce": true`; everything else evaluates, records, and lets the call through, so a shadow
+deployment tells you what *would* have been blocked without blocking it.
+
+The failure semantics are the part worth reading twice, because they decide what happens on your
+worst day:
+
+| Situation | What happens |
+|---|---|
+| No policy installed, or one that will not verify | **Allow**, and raise an integrity alert |
+| Policy verified but stale | `enforce`-marked rules **keep enforcing**; unmarked ones become advice |
+| Evaluation exceeds its latency budget | **Allow**, and record the overrun |
+| A bug inside policy evaluation | **Allow**, and raise an integrity alert |
+| A rule needs a human, and there is no approver | The rule's own `on_timeout`: **deny** if enforce-marked, **allow** if not |
+
+**Denying because we could not reach something is never a default.** `failClosed` is the single
+opt-in exception, and it says so in the reason string on every decision it produces — a service
+that starts refusing should be able to tell you why without a support ticket.
+
+`Denied` is the only exception this SDK will ever put in your stack trace, and you opted into it
+twice: the rule carried `enforce: true` and the call site did not decline. **With no policy
+installed — the default — nothing here can throw.**
+
+---
+
+## What this does not do
+
+Named, because a gap that is named is fine and a gap that is silent is not.
+[`PARITY.md`](./PARITY.md) has the full list against the Python SDK.
+
+- **No module-hook auto-instrumentation.** No `--import @swfte/nexus-sdk/register`. It cannot serve
+  bundled applications, and shipping a half-working version of it produces exactly the empty
+  dashboard this SDK is supposed to make impossible. The spike's implementation is still in the
+  repository under `src/hooks/`, excluded from the published package.
+- **No provider adapters.** No direct instrumentation of `@anthropic-ai/sdk` or `openai`. If you
+  call those libraries directly rather than through the AI SDK, use `run.usage(...)`.
+- **No enforcement through the AI SDK.** The seam is observe-only *by its type signature* — the
+  callback returns `void`, there is no channel to refuse on, and a throw from
+  `onToolExecutionStart` neither stops the tool nor reaches your code. Measured, not assumed. In
+  Node, enforcement means the explicit API, where you own the call site.
+- **Enforcement reaches exactly one call site.** `@swfte/nexus-sdk/policy` gates
+  `run.action(...)`, and nothing else. **An application using the AI SDK seam cannot be gated
+  in-process at all**, now or later: that seam's callbacks return `void`, so there is no channel to
+  refuse on, and a throw from `onToolExecutionStart` neither stops the tool nor reaches your code.
+  Enforcement in Node means the explicit API where you own the call site, a gateway in front of your
+  provider, or nothing. Worth knowing before you design around it.
+- **No human-approval channel.** A `require_approval` rule resolves to its own `on_timeout` — deny
+  if the rule is enforce-marked, allow if not — rather than waiting for a person. Node cannot park
+  its event loop, and a synchronous wait would freeze the process.
+- **The OTel bridge does not deduplicate retries.** `@swfte/nexus-sdk/otel` reads spans from
+  whatever GenAI instrumentation you run and emits `token_usage`, `tool_action`,
+  `model_response` and `model_thinking`. What it does not port is Python's multi-span logical-call
+  join, so against an instrumentation that emits one span per HTTP attempt, token counts sum across
+  retries instead of being deduplicated.
+- **No `nexus-run` launcher.** There is no Node equivalent of `PYTHONPATH`-based bootstrapping that
+  survives bundling.
+
+---
+
+## Why no dependencies
+
+The core declares nothing. Not an HTTP client, not a UUID library.
+
+This is a product decision, not asceticism. An observability SDK is installed into a dependency
+graph somebody else has already resolved, and every requirement we add is a version range that can
+conflict with theirs — a conflict at install time is where the adoption conversation ends, before
+any of this code runs. `scripts/npm-guard.cjs` and a test both fail the build if `dependencies`,
+`peerDependencies` or `optionalDependencies` stops being empty.
+
+The `/ai` entry point is the shape this forces and it is a better shape anyway: we never import
+`ai`, you hand us `registerTelemetry`.
+
+---
+
+## Development
+
+```
+npm test          # 339 tests, node --test, no third-party framework
+npm run typecheck # tsc --strict against the public declarations
+npm run guard     # what `npm publish` would ship, checked against an allowlist
+```
+
+Two checks need a network and are not part of `npm test`:
+
+```
+npm run probe:ai                # the bridge against the real `ai` package, end to end
+npm run parity                  # redactor, rate card and policy envelope, diffed against Python
+bash scripts/consumer-check.sh  # install the tarball; run strict tsc against it as a consumer
+```
+
+`test/contract.test.mjs` validates every emitted event against `contract/events.v1.json` from
+`nexus-devtools`. It looks for it at `../nexus-devtools/contract/events.v1.json`, overridable with
+`NEXUS_CONTRACT`, and skips loudly rather than silently when it is absent.
+
+### Layout
+
+```
+src/core.cjs        the SDK: config, context, queue, transport, run/action, contract
+src/index.js  .cjs  ESM and CJS entries over the one core (dual-package hazard)
+src/ai.cjs    .js   the Vercel AI SDK bridge
+src/provenance.cjs  where a commit and a repo came from, and how confident we are
+src/hooks/          the spike's module hooks — NOT shipped, kept for the record
+fixtures/           stand-in provider, probe applications, the real-library probes
+bundle/             esbuild build + the start-up measurement harness
+```
+
+---
+
+## Nexus, beyond this package
+
+This SDK is one attach point of three. All three write the same events to the same ledger, so a run
+in production and a run on a laptop are the same shape in the same tables.
+
+| | Install | What it attaches to |
+|---|---|---|
+| **Terminal wrapper** | `npm i -g @swfte/nexus` · `pip install swfte-nexus` | coding agents in a developer's terminal — Claude Code, Codex |
+| **Node SDK** — this package | `npm i @swfte/nexus-sdk` | your own Node services |
+| **[Python SDK](https://github.com/SwfteAI/nexus-sdk)** | `pip install swfte-nexus-sdk` | your own Python services |
+
+- **Product, pricing and docs:** [www.swfte.com](https://www.swfte.com)
+- **Self-hosting, procurement, security review, pilots:** [sales@swfte.com](mailto:sales@swfte.com)
+- **Report a vulnerability:** [`SECURITY.md`](./SECURITY.md)
+
+## Licence
+
+Apache-2.0. See [`LICENSE`](./LICENSE) and [`NOTICE`](./NOTICE).
+
+Built by **[Swfte AI](https://www.swfte.com)**.