chore(deps): bump vitest from 2.1.9 to 4.1.10

.github/workflows/ci.yml

@@ -1,35 +1,50 @@
 name: CI
 on:
   pull_request:
-    branches: [main]
   push:
-    branches: ['**']
-
+    branches: [main]
 permissions:
   contents: read
-  packages: read
-
-concurrency:
-  group: ci-${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
 jobs:
-  build:
+  node:
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node: ["20.19.0", "22.23.1", "24.18.0"]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: ${{ matrix.node }}
+      - run: npm ci --ignore-scripts
+      - run: npm run build
+      - run: npm run verify:types
+      - run: npm run lint
+      - run: npm run lint:boundary
+      - run: npm test
+      - run: npm audit --audit-level=high --omit=dev
+      - run: npm run verify:package
+      - name: Pack artifact
+        if: matrix.node == '20.19.0'
+        run: |
+          npm pack --ignore-scripts
+          sha256sum quantum-l9-llm-router-*.tgz > package.sha256
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: matrix.node == '20.19.0'
         with:
-          persist-credentials: false
-      - uses: actions/setup-node@v4
+          name: package-contract
+          path: |
+            quantum-l9-llm-router-*.tgz
+            package.sha256
+          if-no-files-found: error
+  artifact-roundtrip:
+    needs: node
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4
         with:
-          node-version: '20'
-          cache: 'npm'
-          registry-url: 'https://npm.pkg.github.com'
-          scope: '@quantum-l9'
-      - run: npm ci
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      - name: Build (tsc -> dist/)
-        run: npm run build
-      - name: Typecheck
-        run: npm run verify:types
+          name: package-contract
+          path: artifacts/downloaded
+      - run: cd artifacts/downloaded && sha256sum -c package.sha256

.github/workflows/l9-analysis.yml

@@ -29,7 +29,7 @@ concurrency:
 
 env:
   # Pin Core to the immutable release commit (or replace with the v2 tag once published).
-  L9_CORE_REF: "54a2f2fc8d060674d544fab14388bb5eff6b8e78"
+  L9_CORE_REF: "f88116503430aa18992b70d8d31063e34ff97ef1"
   # Match the event: pr_fast for pull_request, merge for push, nightly/release/
   # supply_chain as appropriate. Must be allowed_events in execution-profiles.yaml.
   L9_PROFILE: "pr_fast"
@@ -64,7 +64,7 @@ jobs:
 
       - id: gov
         name: Resolve governance (Core)
-        uses: Quantum-L9/l9-ci-core/.github/actions/resolve-governance@54a2f2fc8d060674d544fab14388bb5eff6b8e78
+        uses: Quantum-L9/l9-ci-core/.github/actions/resolve-governance@f88116503430aa18992b70d8d31063e34ff97ef1
         with:
           profile: ${{ env.L9_PROFILE }}
           provider: semgrep
@@ -85,7 +85,7 @@ jobs:
         if: steps.gov.outputs.enabled == 'true'
         run: |
           set -euo pipefail
-          python -m pip install --upgrade pip semgrep
+          python -m pip install 'pip==26.1.2' 'semgrep==1.170.1'
           mkdir -p "artifacts/raw/semgrep/${L9_MATRIX_ID}"
           # Node.js repo ruleset — JS/TS only (no p/python; this repo is TypeScript).
           semgrep scan \
@@ -100,11 +100,11 @@ jobs:
       - id: sdk
         name: Provision immutable SDK
         if: steps.gov.outputs.enabled == 'true'
-        uses: Quantum-L9/l9-ci-core/.github/actions/provision-sdk@54a2f2fc8d060674d544fab14388bb5eff6b8e78
+        uses: Quantum-L9/l9-ci-core/.github/actions/provision-sdk@f88116503430aa18992b70d8d31063e34ff97ef1
 
       - name: Normalize provider report
         if: steps.gov.outputs.enabled == 'true'
-        uses: Quantum-L9/l9-ci-core/.github/actions/invoke-sdk@54a2f2fc8d060674d544fab14388bb5eff6b8e78
+        uses: Quantum-L9/l9-ci-core/.github/actions/invoke-sdk@f88116503430aa18992b70d8d31063e34ff97ef1
         with:
           executable: ${{ steps.sdk.outputs.executable }}
           operation: semgrep-normalize
@@ -119,14 +119,14 @@ jobs:
 
       - name: Validate canonical bundle
         if: steps.gov.outputs.enabled == 'true'
-        uses: Quantum-L9/l9-ci-core/.github/actions/validate-bundle@54a2f2fc8d060674d544fab14388bb5eff6b8e78
+        uses: Quantum-L9/l9-ci-core/.github/actions/validate-bundle@f88116503430aa18992b70d8d31063e34ff97ef1
         with:
           executable: ${{ steps.sdk.outputs.executable }}
           bundle: .l9/runtime/${{ env.L9_MATRIX_ID }}/finding-bundle.json
 
       - name: Project agent-review payload
         if: steps.gov.outputs.enabled == 'true'
-        uses: Quantum-L9/l9-ci-core/.github/actions/invoke-sdk@54a2f2fc8d060674d544fab14388bb5eff6b8e78
+        uses: Quantum-L9/l9-ci-core/.github/actions/invoke-sdk@f88116503430aa18992b70d8d31063e34ff97ef1
         with:
           executable: ${{ steps.sdk.outputs.executable }}
           operation: bundle-project-agent-payload
@@ -137,7 +137,7 @@ jobs:
       - id: route
         name: Route artifacts
         if: steps.gov.outputs.enabled == 'true'
-        uses: Quantum-L9/l9-ci-core/.github/actions/route-artifacts@54a2f2fc8d060674d544fab14388bb5eff6b8e78
+        uses: Quantum-L9/l9-ci-core/.github/actions/route-artifacts@f88116503430aa18992b70d8d31063e34ff97ef1
         with:
           provider: semgrep
           matrix-id: ${{ env.L9_MATRIX_ID }}
@@ -148,7 +148,7 @@ jobs:
 
       - name: Build artifact manifest
         if: steps.gov.outputs.enabled == 'true'
-        uses: Quantum-L9/l9-ci-core/.github/actions/build-artifact-manifest@54a2f2fc8d060674d544fab14388bb5eff6b8e78
+        uses: Quantum-L9/l9-ci-core/.github/actions/build-artifact-manifest@f88116503430aa18992b70d8d31063e34ff97ef1
         with:
           provider: semgrep
           matrix-id: ${{ env.L9_MATRIX_ID }}
@@ -174,7 +174,7 @@ jobs:
     name: Publish analysis (Core)
     needs: analyze
     if: needs.analyze.outputs.enabled == 'true'
-    uses: Quantum-L9/l9-ci-core/.github/workflows/publish-analysis.yml@54a2f2fc8d060674d544fab14388bb5eff6b8e78
+    uses: Quantum-L9/l9-ci-core/.github/workflows/publish-analysis.yml@f88116503430aa18992b70d8d31063e34ff97ef1
     permissions:
       actions: read
       checks: write

.github/workflows/publish.yml

@@ -1,56 +1,21 @@
-name: Publish Package
+name: Publish
 on:
   push:
-    branches: [main]
-    paths: ['package.json']
-  workflow_dispatch:
-
+    tags: ['v*']
 permissions:
   contents: read
   packages: write
-
-concurrency:
-  group: publish-${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: false
-
 jobs:
   publish:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
-          persist-credentials: false
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          cache: 'npm'
-          registry-url: 'https://npm.pkg.github.com'
-          scope: '@quantum-l9'
-      - run: npm ci
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      - run: npm run build
-
-      # Gate publish on a version bump: npm refuses to republish an existing
-      # name@version, so manual dispatch or any non-bump push to package.json
-      # would otherwise fail the job. Skip cleanly when this version already
-      # exists on the registry.
-      - name: Check whether this version is already published
-        id: published
-        run: |
-          VERSION="$(node -p "require('./package.json').version")"
-          if npm view "@quantum-l9/llm-router@${VERSION}" version >/dev/null 2>&1; then
-            echo "exists=true" >> "$GITHUB_OUTPUT"
-            echo "@quantum-l9/llm-router@${VERSION} is already published — skipping publish."
-          else
-            echo "exists=false" >> "$GITHUB_OUTPUT"
-            echo "@quantum-l9/llm-router@${VERSION} not found — will publish."
-          fi
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Publish
-        if: steps.published.outputs.exists == 'false'
-        run: npm publish
+          node-version: 24.18.0
+          registry-url: https://npm.pkg.github.com
+      - run: npm ci --ignore-scripts
+      - run: npm run verify:all
+      - run: npm publish
         env:
           NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/supply-chain.yml

@@ -0,0 +1,25 @@
+name: Supply Chain
+on:
+  pull_request:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+jobs:
+  sbom:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 24.18.0
+      - run: npm ci --ignore-scripts
+      - run: npm sbom --sbom-format cyclonedx > sbom.cdx.json
+      - run: sha256sum sbom.cdx.json > sbom.sha256
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: sbom
+          path: |
+            sbom.cdx.json
+            sbom.sha256
+          if-no-files-found: error

.gitignore

@@ -1,3 +1,6 @@
 node_modules/
 dist/
 *.log
+*.tgz
+artifacts/
+coverage/

ARCHITECTURE.md

@@ -0,0 +1,25 @@
+# Architecture
+
+`@quantum-l9/llm-router` is a reusable TypeScript routing library. The root `L9LLMRouter` is the supported execution surface.
+
+## Runtime flow
+
+```text
+validated TaskDescriptor
+  -> pure route resolution
+  -> atomic process-local budget reservation
+  -> provider-family-safe downgrade
+  -> per-provider circuit permit
+  -> provider dispatch
+  -> cost reconciliation and audit log
+```
+
+Provider clients live under `src/providers/`. Production modules outside `src/index.ts` and `src/providers/` may not import them. Existing provider subpath exports remain available during the 1.x line for compatibility, but direct use is deprecated because it bypasses budget and circuit controls.
+
+## State scope
+
+The built-in budget tracker and circuit breaker are process-local. They prevent concurrent overspend and provider stampedes inside one process. Distributed enforcement requires an external persistence adapter and is intentionally not claimed here.
+
+## Runtime floor
+
+The package runtime floor is Node 20.19.0. Type definitions track the Node 20 line so compilation cannot silently authorize APIs that are unavailable to supported consumers. CI also exercises the current active LTS as a secondary runtime.