feat: error reference, device matrix, soak tests and a release pipeline

Four things, all of which exist to make the project's claims checkable
rather than asserted.

**The error reference** documents every one of the thirty `NfcErrorCode`
values with a cause and a remedy, and a test compares it against
`NFC_ERROR_CODES` in both directions. A code with no row is the worst
omission an error reference can have -- the reader concludes the error is
undocumented and guesses -- and a row for a code that no longer exists
sends them looking for something they will never see. Rows with empty
cells fail too, since a code that has been listed rather than explained is
not documented.

**The soak test** is the automatable half of "it works the first five
times". Thirty iterations of every entry point, then an assertion that the
library is back where it started: no active session, no native listener,
every handle released. Including the interleaved case, because a leak that
only appears when one entry point follows another is exactly what a
per-entry-point test misses. Writing it turned up nothing, which is the
result worth having.

**The device matrix** is 45 rows covering every claim the library makes,
each with the setup that tests it and what passed means -- and every row is
marked not run, on the first line, because it has not been. Row 21 is
called out as the one place the library makes an inference it could not
check: the Android 17 `DISPATCH_NFC_MESSAGE` behaviour.

**The release pipeline** uses npm trusted publishing, so there is no token
in the repository and none should ever be added. The requirements were read
from npm's documentation rather than recalled, which corrected two things:
Node 22.14 is the floor, not just npm 11.5.1, and the workflow filename is
part of the trust configuration -- renaming it breaks publishing with an
error that looks like authentication. Every gate runs again inside the
release job, because a release is the one place where "it passed earlier"
is not good enough.

The version becomes 0.9.0. `RELEASING.md` says what a 1.0.0 needs first,
and it is not code: the matrix, row 21 settled on hardware, and weeks of
real use. A 1.0.0 that has not survived somebody else's tags is a version
number rather than a promise.

Maestro flows are deliberately not here. They would test the example app's
UI, not the library -- whose error paths are already at 100% -- and would
need a runtime mock switch inside the example, which means a test seam in
shipping code. The reason is recorded rather than the work half-done.

1342 tests.

Author: visibait

.changeset/README.md

@@ -0,0 +1,18 @@
+# Changesets
+
+A changeset is a note about a change, written when the change is made rather than
+reconstructed at release time. Run `npx changeset` and answer two questions: how big
+the change is, and what to say about it.
+
+Which bump to pick, for this library specifically:
+
+- **patch** — a fix that changes no API and needs no rebuild.
+- **minor** — a new capability, a new `NfcErrorCode`, or anything that bumps
+  `CONTRACT_VERSION`. A contract bump means consumers must rebuild their development
+  build, so the changeset should say so in as many words.
+- **major** — changing the `code` of an existing error, removing an export, or
+  changing what an existing call does. Renaming a technology counts.
+
+The changelog is generated from these, which is the point: the library this replaces
+has a `CHANGELOG.md` frozen at 3.0.2 from February 2021, with four years of releases
+missing from it.

.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.github/workflows/release.yml

@@ -0,0 +1,78 @@
+# Publishing to npm.
+#
+# There is no NPM_TOKEN here, deliberately. This uses npm's trusted publishing:
+# GitHub Actions mints a short-lived OIDC token, npm accepts it because the package
+# names this workflow as a trusted publisher, and provenance attestations are
+# generated automatically. Classic npm tokens were deprecated on 2025-12-09, and
+# automation tokens lose direct publish in January 2027, so a token-based release
+# would be a pipeline with a known end date.
+#
+# **The workflow filename is part of the trust configuration.** npm matches on the
+# owner, the repository and this file's name, so renaming this file breaks publishing
+# until the trusted publisher is updated on npmjs.com. See RELEASING.md.
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: Version or publish
+    runs-on: ubuntu-latest
+
+    permissions:
+      # Mints the OIDC token npm exchanges for publish rights. Without it the
+      # publish falls back to looking for a token and fails.
+      id-token: write
+      # The changesets action opens and updates the version pull request, and tags
+      # the release commit.
+      contents: write
+      pull-requests: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Changesets compares against the base branch to decide what to bump.
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          # Trusted publishing needs Node 22.14 or later and npm 11.5.1 or later.
+          # Pinned rather than left to the runner's default so a runner image
+          # change cannot silently drop below the floor.
+          node-version: 22.14.0
+          registry-url: https://registry.npmjs.org
+          cache: npm
+
+      - name: Use an npm that can publish this way
+        run: npm install --global npm@latest
+
+      - run: npm ci --ignore-scripts
+
+      # The gates run again here rather than being trusted from the push that
+      # triggered this. A release is the one place where "it passed earlier" is not
+      # good enough: the tree being published is this one.
+      - name: Verify
+        run: |
+          npm run lint
+          npm run format:check
+          npm run typecheck
+          npm run test:coverage
+          npm run verify:package
+
+      - name: Version or publish
+        uses: changesets/action@v1
+        with:
+          # With changesets pending, this opens or updates a pull request that
+          # applies them. With none, and a version not yet on npm, it publishes.
+          version: npm run release:version
+          publish: npm publish
+          commit: 'chore: release'
+          title: 'chore: release'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+Generated from changesets from `0.9.1` onwards. This first entry is written by hand,
+because everything below it predates the changeset workflow.
+
+## 0.9.0
+
+The first version worth installing. Every layer is present and tested; what is
+missing is hardware validation, which is why this is not a `1.0.0` — see
+[docs/device-matrix.md](docs/device-matrix.md), where not one row has been run yet.
+
+### Reading and writing
+
+- `nfc.withTag`, which closes the session on every path, including a throw, an abort,
+  a timeout, and the platform ending the session underneath.
+- `nfc.openSession` for reading several tags with your own UI in between, as an
+  `AsyncDisposable` so `await using` works — with a fallback for engines that lack
+  `Symbol.asyncDispose`, which includes Hermes.
+- `nfc.onTag` for continuous reading, tied to subscriber count so reader mode is only
+  active while something is listening.
+- Tags as a discriminated union: `tag.is('ndef')` is what makes `readNdef` exist, in
+  the type system and at runtime. On iOS `tag.is('mifareClassic')` is always `false`.
+- Every rejection is an `NfcError` with a `code`, a `platform`, the original
+  `nativeCode`, and whether retrying is worth it. See
+  [docs/errors.md](docs/errors.md).
+
+### Layers that need no device
+
+- `react-native-nfc-kit/ndef` — the NDEF codec, at 100% branch coverage: chunked
+  records, UTF-16 text, the 36-entry URI prefix table both ways, Smart Posters, Type 2
+  TLV, and the Type 4 capability container.
+- `react-native-nfc-kit/protocols` — ISO 7816 with command chaining and `61xx`/`6Cxx`
+  handling, ISO 15693, FeliCa, NTAG/Ultralight, all over one native primitive.
+
+### Platform surfaces
+
+- Android reports tag removal (`tag.onLost`), by polling below API 37 and from the
+  platform above it, deduplicated so it can only fire once.
+- Background tags: `nfc.withLaunchTag` and `nfc.onBackgroundTag`, with the launch
+  intent consumed so a screen rotation cannot replay a tap.
+- `react-native-nfc-kit/hce` — card emulation on Android, including an emulated Type 4
+  tag written in TypeScript, observe mode, and polling loop frames.
+- `react-native-nfc-kit/vas` — reading an Apple Wallet pass. Needs an entitlement
+  Apple grants case by case.
+- `react-native-nfc-kit/react` — hooks, on a subpath so the core never imports React.
+- Web NFC: the same API in a browser, implemented over the same native contract.
+
+### Tooling
+
+- A config plugin that writes exactly what each option requires and removes it again
+  when the option goes away, with `dispatchNfcMessagePermission` refusing to guess.
+- Setup documentation generated from the plugin itself, so the Expo and bare routes
+  cannot drift.
+- `CONTRACT_VERSION`, so a bundle newer than the installed binary says "rebuild the
+  development build" rather than failing on an undefined method.

README.md

@@ -195,6 +195,18 @@ npx pod-install
 There is no `prebuild` in a bare project, so entitlements and the Android manifest are
 edited by hand. See [docs/setup/bare-react-native.md](docs/setup/bare-react-native.md).
 
+## What has not been validated on hardware
+
+Nothing, yet — and that is stated here rather than left to be discovered.
+[docs/device-matrix.md](docs/device-matrix.md) is the checklist: 45 rows covering
+every claim this library makes, each with the setup that tests it and what "passed"
+means. Not one has been run.
+
+The automated suite proves the bookkeeping — including a soak test that runs thirty
+iterations of every entry point and asserts nothing is left held. Only a tag proves
+the radio, which is why the version is `0.9.0` and why
+[RELEASING.md](RELEASING.md) lists what a `1.0.0` needs first.
+
 ## Documentation
 
 The full documentation lives under [docs/](docs/) and is built as a Mintlify site
@@ -244,6 +256,7 @@ Nothing here is claimed to work because it looks right.
 | Wallet passes         | Validation and decoding tested against the fake native module; the read itself needs an entitlement Apple grants case by case          |
 | Card emulation        | The emulated Type 4 tag is driven through a whole reader conversation, using the same functions an app uses to talk to a real card     |
 | Config plugin         | 104 tests through Expo's own introspection compiler, so the assertions are about what `expo prebuild` produces                         |
+| Leaks                 | 30 iterations of every entry point, asserting no session, no native listener and no handle is left behind                              |
 | The documentation     | Every import in a code block is checked against the barrels that define it, and the site's navigation against the files on disk        |
 | The published package | `publint` and `arethetypeswrong` against a packed tarball, so a broken `exports` map fails before a user finds it                      |
 
@@ -253,19 +266,19 @@ release requirement, not an afterthought.
 
 ## Roadmap
 
-| Phase | Contents                                                              | Status |
-| ----- | --------------------------------------------------------------------- | ------ |
-| M0    | Repository scaffold, tooling, CI                                      | done   |
-| M1    | NDEF codec (pure TypeScript, no native)                               | done   |
-| M2    | Android core: reader mode, tech adapters, errors, sessions, tags      | done   |
-| M3    | iOS core: session actor, one-shot continuations, tag handles          | done   |
-| M4    | Protocol layers: ISO 7816, ISO 15693, FeliCa, NTAG/Ultralight         | done   |
-| M5    | Config plugin, bare React Native, React hooks                         | done   |
-| M6    | Continuous reading, `onTagLost`, observe mode, background tag reading | next   |
-| M7    | Host card emulation (Android)                                         | done   |
-| M8    | Observe mode, polling loop frames                                     | done   |
-| M9    | Web NFC shim, documentation site, migration guide                     | done   |
-| M10   | Error reference, device matrix pass, soak tests, `1.0.0`              | next   |
+| Phase | Contents                                                              | Status      |
+| ----- | --------------------------------------------------------------------- | ----------- |
+| M0    | Repository scaffold, tooling, CI                                      | done        |
+| M1    | NDEF codec (pure TypeScript, no native)                               | done        |
+| M2    | Android core: reader mode, tech adapters, errors, sessions, tags      | done        |
+| M3    | iOS core: session actor, one-shot continuations, tag handles          | done        |
+| M4    | Protocol layers: ISO 7816, ISO 15693, FeliCa, NTAG/Ultralight         | done        |
+| M5    | Config plugin, bare React Native, React hooks                         | done        |
+| M6    | Continuous reading, `onTagLost`, observe mode, background tag reading | next        |
+| M7    | Host card emulation (Android)                                         | done        |
+| M8    | Observe mode, polling loop frames                                     | done        |
+| M9    | Web NFC shim, documentation site, migration guide                     | done        |
+| M10   | Error reference, device matrix, soak tests, release pipeline          | in progress |
 
 Out of scope, deliberately: Apple's NFC & SE Platform (`CredentialSession`). It requires
 an agreement with Apple, ABR onboarding, and an accredited-lab applet security review —

RELEASING.md

@@ -0,0 +1,84 @@
+# Releasing
+
+There are no npm tokens in this repository, and there should never be. Publishing
+goes through npm's trusted publishing: GitHub Actions mints a short-lived OIDC
+token, npm accepts it because the package names the release workflow as a trusted
+publisher, and provenance attestations are generated without asking.
+
+Classic npm tokens were deprecated on 2025-12-09 and automation tokens lose direct
+publish in January 2027, so a token-based pipeline would be one with a known expiry
+date.
+
+## One-time setup on npmjs.com
+
+Before the first publish, on the package's settings page under **Trusted
+publishers**, add a GitHub Actions publisher with:
+
+| Field                | Value                  |
+| -------------------- | ---------------------- |
+| Organization or user | `visibait`             |
+| Repository           | `react-native-nfc-kit` |
+| Workflow filename    | `release.yml`          |
+
+**The workflow filename is part of the trust configuration.** Renaming
+`.github/workflows/release.yml` breaks publishing until this is updated, and the
+failure looks like an authentication error rather than a configuration one.
+
+The package must exist on npm first. For the very first publish, either create it
+with a manual `npm publish` from a machine that is logged in, or reserve the name
+and then let the workflow take over.
+
+## The everyday flow
+
+1. **Write a changeset with the change**, not afterwards:
+
+   ```bash
+   npx changeset
+   ```
+
+   Two questions: how big the change is, and what to say about it. `.changeset/README.md`
+   explains which bump to pick — the one to get right is that anything bumping
+   `CONTRACT_VERSION` is a **minor** and the note must say that consumers need to
+   rebuild their development build, because that is the support question that
+   otherwise arrives instead.
+
+2. **Merge to `main`.** The release workflow opens or updates a pull request titled
+   `chore: release` that applies every pending changeset: versions bumped,
+   `CHANGELOG.md` written, changesets consumed.
+
+3. **Merge that pull request.** The workflow runs again, finds no pending changesets
+   and a version not yet on npm, and publishes.
+
+Every gate runs again inside the release job rather than being trusted from the push
+that triggered it. A release is the one place where "it passed earlier" is not good
+enough: the tree being published is this one.
+
+## Before a 1.0.0
+
+The version is `0.9.0`, and that is deliberate. What is missing is not code:
+
+- **[The device matrix](docs/device-matrix.md) has not been run.** Not one row. A
+  `1.0.0` that has not been through it would be a claim this project has not earned,
+  and the matrix says as much on its own first line.
+- **Row 21 is an unverified inference.** The Android 17 `DISPATCH_NFC_MESSAGE`
+  behaviour follows from Google's documentation and has not been checked on an API 37
+  device. The default is the conservative one and the docs call it provisional, but
+  it should be settled before a stable release.
+- **Weeks of real use.** A 1.0.0 that has not survived somebody else's tags is a
+  version number, not a promise. The plan for this library said so from the start,
+  and it is worth repeating here where the release happens.
+
+Publishing `0.x` releases in the meantime is the point of the version scheme: each
+one is usable, and none of them claims more than has been checked.
+
+## Semantic versioning, as applied here
+
+- Adding an `NfcErrorCode` is a **minor**. Nothing that existed changed meaning.
+- Changing the `code` an existing failure produces is a **major**, because callers
+  branch on codes and a changed code silently takes a branch away.
+- Bumping `CONTRACT_VERSION` is a **minor** that requires a rebuild. The runtime says
+  so itself — a bundle newer than the installed binary fails with `contractMismatch`
+  and a message naming the remedy — but the changelog should not make anyone
+  discover it that way.
+- Renaming a technology is a **major**. `tag.is('...')` and the config plugin's tech
+  lists both take those names.