chore: upgrade yarn to v4 (berry) and add node 22 ci tests

.github/dependabot.yml

@@ -7,10 +7,15 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
+    cooldown:
+      default-days: 7
     groups:
       npm-minor-patch:
         patterns: ["*"]
         update-types: ["minor", "patch"]
+    ignore:
+      - dependency-name: "@types/node"
+        update-types: ["version-update:semver-major"]
 
   - package-ecosystem: "github-actions"
     directory: "/"

.github/workflows/ci.yml

@@ -14,55 +14,72 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
+      - run: corepack enable
       - uses: actions/setup-node@v6
         with:
           node-version-file: .node-version
           cache: yarn
-      - run: yarn install --frozen-lockfile
+      - run: yarn install
       - run: yarn format:check
 
   lint:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
+      - run: corepack enable
       - uses: actions/setup-node@v6
         with:
           node-version-file: .node-version
           cache: yarn
-      - run: yarn install --frozen-lockfile
+      - run: yarn install
       - run: yarn lint:check
 
   typecheck:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
+      - run: corepack enable
       - uses: actions/setup-node@v6
         with:
           node-version-file: .node-version
           cache: yarn
-      - run: yarn install --frozen-lockfile
+      - run: yarn install
       - run: yarn typecheck
 
-  test:
+  test-matrix:
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [22, 24]
     steps:
       - uses: actions/checkout@v7
+      - run: corepack enable
       - uses: actions/setup-node@v6
         with:
-          node-version-file: .node-version
+          node-version: ${{ matrix.node-version }}
           cache: yarn
-      - run: yarn install --frozen-lockfile
+      - run: yarn install
       - run: yarn test
 
+  test:
+    needs: test-matrix
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - if: needs.test-matrix.result != 'success'
+        run: exit 1
+
   build:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
+      - run: corepack enable
       - uses: actions/setup-node@v6
         with:
           node-version-file: .node-version
           cache: yarn
-      - run: yarn install --frozen-lockfile
+      - run: yarn install
       - run: yarn build
       - uses: actions/upload-artifact@v7
         with:
@@ -75,11 +92,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
+      - run: corepack enable
       - uses: actions/setup-node@v6
         with:
           node-version-file: .node-version
           cache: yarn
-      - run: yarn install --frozen-lockfile
+      - run: yarn install
       # publint resolves the package `exports` against the packed tarball, which
       # references ./dist/*. Reuse the build job's output instead of rebuilding.
       - uses: actions/download-artifact@v8

.github/workflows/publish.yml

@@ -15,12 +15,13 @@ jobs:
       contents: read
     steps:
       - uses: actions/checkout@v7
+      - run: corepack enable
       - uses: actions/setup-node@v6
         with:
           node-version-file: .node-version
           registry-url: https://registry.npmjs.org
           cache: yarn
-      - run: yarn install --frozen-lockfile
+      - run: yarn install
       - run: yarn lint:check
       - run: yarn typecheck
       - run: yarn test

.gitignore

@@ -1,2 +1,17 @@
-dist
-node_modules
+# Build artifacts
+dist/
+
+# Dependency artifacts
+node_modules/
+
+# IDE artifacts
+.idea/
+
+# Yarn
+# https://yarnpkg.com/getting-started/qa#which-files-should-be-gitignored
+.yarn/*
+!.yarn/releases
+!.yarn/patches
+!.yarn/plugins
+!.yarn/sdks
+!.yarn/versions

.prettierignore

@@ -1,4 +1,2 @@
-dist
-spec/spec.md
-spec/fixtures/
-spec/normative-ledger.json
+.yarn/
+spec/

.yarnrc.yml

@@ -0,0 +1,11 @@
+enableGlobalCache: true
+
+enableImmutableInstalls: true
+
+enableScripts: false
+
+nodeLinker: node-modules
+
+npmMinimalAgeGate: 1w
+
+yarnPath: .yarn/releases/yarn-4.17.0.cjs

CLAUDE.md

@@ -31,7 +31,12 @@ repeatable spec-upgrade loop and `spec/conformance.md` for the requirement→cod
    publish workflow without explicit confirmation. Publishes are permanent.
 5. **Run `yarn check-all` and `yarn test` before any commit or push.**
 6. **Keep `yarn publint` on `--pack npm`.**
-7. **Don't lower `engines.node` below `>=22.0.0`.**
+7. **Keep `engines.node` at `>=22.0.0` and keep the CI `test-matrix` covering it.** This is the
+   consumer runtime floor; consumers run the compiled `dist`, which uses only long-stable globals
+   (`URL`/`URLSearchParams`) and runs on any maintained LTS. Dev and CI use Node 24 (`.node-version`,
+   active LTS). The `test-matrix` job runs `yarn test` on Node 22 and 24; the 22 leg resolves to the
+   latest 22.x because the native `.ts` test runner needs default type stripping (Node >=22.18), so
+   never pin the matrix low leg below that. Don't raise the consumer floor to match the dev pin.
 8. **Never use `eslint-disable`, `@ts-ignore`, or `@ts-expect-error` as a workaround.** Fix the
    underlying code or surface the rule to the user for a config decision.
 
@@ -57,6 +62,12 @@ repeatable spec-upgrade loop and `spec/conformance.md` for the requirement→cod
 | `yarn format`    | `prettier --write`                                 |
 | `yarn publint`   | `publint --pack npm` (keep the flag)               |
 
+## Tooling (Yarn 4)
+
+- Yarn is pinned via `packageManager: [email protected]` (`.yarn/releases/yarn-4.17.0.cjs`). Run `corepack enable` so the project yarn is used; CI does the same.
+- `.yarnrc.yml` config: `nodeLinker: node-modules`, immutable installs (`enableImmutableInstalls: true` - no `--frozen-lockfile` needed), `enableScripts: false` (no postinstall scripts - a dep needing a build step at install won't run it), `npmMinimalAgeGate: 1w` (deps published <1 week ago won't install; matches the dependabot 7-day cooldown).
+- `yarn.lock` is the only lockfile.
+
 ## Source Map
 
 - `src/constants.ts` — scheme/version (`0.2.0`), `DC_API_PROTOCOL` (signed/unsigned), header names, schema URL, token-exchange URNs.
@@ -105,5 +116,4 @@ Never `git push --follow-tags` to `main`: the commit is rejected but the tag sti
 
 ## Notes
 
-- `yarn.lock` is the only lockfile (no `package-lock.json`).
 - Scope is `@proof.com` (with the dot), not `@proof`.

CONTRIBUTING.md

@@ -2,8 +2,8 @@
 
 ## Requirements
 
-- `node` >= 22.0.0 (the repo targets the version in [.node-version](.node-version))
-- `yarn`
+- `node` >= 22.0.0 (published floor, `engines.node`). Develop on Node 24 (active LTS), pinned in [.node-version](.node-version).
+- `yarn` 4 - run `corepack enable`; the version is pinned via `packageManager` in `package.json`.
 
 ## Design Principles
 
@@ -35,6 +35,8 @@ To submit a pull request:
 - Include a clear title and description explaining what changed and why.
 - Keep changes focused, try to limit one issue or feature per PR.
 
+CI runs `test` on a matrix of Node 22 (the `engines.node` floor) and Node 24 (active LTS). The other jobs run on Node 24 from `.node-version`.
+
 ## Code of conduct
 
 This project follows the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). By participating, you are expected to uphold this standard.

package.json

@@ -48,17 +48,18 @@
     "@owf/identity-common": "^0.3.0"
   },
   "devDependencies": {
-    "@types/node": "^25.9.1",
+    "@types/node": "^24.13.2",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
-    "eslint": "^10.4.0",
+    "eslint": "^10.5.0",
     "eslint-plugin-unused-imports": "^4.4.1",
     "prettier": "^3.8.4",
     "prettier-plugin-packagejson": "^3.0.2",
     "publint": "^0.3.21",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.61.0"
+    "typescript-eslint": "^8.62.0"
   },
+  "packageManager": "[email protected]",
   "engines": {
     "node": ">=22.0.0"
   },