Phase 6: v1 → v2 SDK migration (uxf-v2 fork review artifact)

.env.example

@@ -0,0 +1,11 @@
+# sphere-sdk e2e / soak configuration — copy to `.env` (gitignored).
+
+# Unicity testnet2 v2 gateway (state-transition aggregator).
+TESTNET2_GATEWAY=https://gateway.testnet2.unicity.network
+
+# testnet2 gateway API key — NOT a secret: testnet2 keys are safe to
+# commit here and in docs.
+TESTNET2_API_KEY=sk_ddc3cfcc001e4a28ac3fad7407f99590
+
+# Root trust base JSON URL (testnet2 = networkId 4).
+TESTNET2_TRUSTBASE_URL=https://raw.githubusercontent.com/unicitynetwork/unicity-ids/main/bft-trustbase.testnet2.json

.github/workflows/ci.yml

@@ -2,9 +2,9 @@ name: CI
 
 on:
   push:
-    branches: [main]
+    branches: [main, '@vrogojin/uxf-v2']
   pull_request:
-    branches: [main]
+    branches: [main, '@vrogojin/uxf-v2']
 
 jobs:
   build:
@@ -33,3 +33,27 @@ jobs:
 
       - name: Test
         run: npm run test:run
+
+  conformance-report:
+    runs-on: ubuntu-latest
+    # Report-only: never blocks the build. Diffs the exported API surface against a
+    # frozen upstream main v0.11.4 snapshot as a burn-down metric for the uxf-v2 refactor.
+    # See docs/uxf/uxfv2-phase-1-report.md.
+    continue-on-error: true
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js 22
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: |
+          npm install --include=optional --ignore-scripts
+          npm rebuild
+
+      - name: API-conformance drift report
+        run: bash tests/harness/run-conformance.sh

.github/workflows/external-acks-gate.yml

@@ -0,0 +1,99 @@
+# External Acks Gate (T.8.D production cutover)
+#
+# Why this exists (W6 / W2 plan rationale):
+#   The UXF Inter-Wallet Transfer Protocol v1 widens the `onIntent` callback
+#   shape across consumers. Three downstream repositories must update their
+#   integrations BEFORE we cut over production (T.8.D), or live wallets will
+#   silently drop incoming intents. We cannot land the cutover PR until each
+#   maintainer has signed off in their own repo.
+#
+# How acks are recorded:
+#   Each downstream repo opens a tracking issue with the label
+#   `uxf-transfer-v1-ack`. The maintainer closes the issue once their repo
+#   has shipped the widened callback. This workflow asserts all 3 are closed.
+#
+# Tracking issues (corrected from plan after repo audit at PR-prep time —
+# `agentsphere` doesn't yet exist as a real GitHub repo so it's not in the
+# active gate; if/when it lands, follow the "Adding a 4th external repo"
+# instructions below):
+#   - unicity-sphere/sphere            (label: uxf-transfer-v1-ack) — issue #302
+#   - unicitynetwork/openclaw-unicity  (label: uxf-transfer-v1-ack) — issue #8
+#
+# Triggering model (label-gated):
+#   The job runs only when the PR carries the `t8d-cutover` label. This keeps
+#   the gate scoped to the cutover PR; ordinary PRs are unaffected. We
+#   re-evaluate on label add/remove and on every push to the PR head, so the
+#   check stays green/red in lockstep with the upstream issue state.
+#
+# Required secret:
+#   EXTERNAL_ACKS_TOKEN — a fine-grained PAT (or GitHub App token) with
+#   `Issues: Read` scope on the upstream repos listed above. The default
+#   `GITHUB_TOKEN` is scoped to THIS repo only and cannot read issues in other
+#   repos; passing it would surface as a 404, not an auth error, which is hard
+#   to debug. Configure under: Settings → Secrets and variables → Actions.
+#
+# Adding another external repo:
+#   1. Add the new tracking issue (label `uxf-transfer-v1-ack`) in that repo.
+#   2. Append `<owner>/<repo>` to the `REPOS` list in the gate step.
+#   3. Ensure EXTERNAL_ACKS_TOKEN has `Issues: Read` on the new repo.
+#   4. Update the T.8.D PR description to reference the new tracking issue.
+
+name: External Acks Gate
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+
+jobs:
+  external-acks-gate:
+    name: Verify external maintainer acks (T.8.D)
+    # Only run on the cutover PR — gated by the `t8d-cutover` label.
+    if: contains(github.event.pull_request.labels.*.name, 't8d-cutover')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    steps:
+      - name: Verify EXTERNAL_ACKS_TOKEN is configured
+        env:
+          EXTERNAL_ACKS_TOKEN: ${{ secrets.EXTERNAL_ACKS_TOKEN }}
+        run: |
+          if [ -z "${EXTERNAL_ACKS_TOKEN:-}" ]; then
+            echo "::error::EXTERNAL_ACKS_TOKEN secret is not set."
+            echo "::error::This gate queries closed issues in the configured external repos."
+            echo "::error::Configure a fine-grained PAT with 'Issues: Read' on those repos."
+            echo "::error::Settings → Secrets and variables → Actions → New repository secret"
+            exit 1
+          fi
+
+      - name: Check external repos have a closed uxf-transfer-v1-ack issue
+        env:
+          GH_TOKEN: ${{ secrets.EXTERNAL_ACKS_TOKEN }}
+        run: |
+          set -euo pipefail
+          REPOS=(
+            "unicity-sphere/sphere"
+            "unicitynetwork/openclaw-unicity"
+          )
+          missing=()
+          for repo in "${REPOS[@]}"; do
+            # `gh issue list` honours --label and --state; --json id keeps output stable.
+            count=$(gh issue list \
+              --repo "$repo" \
+              --state closed \
+              --label uxf-transfer-v1-ack \
+              --json id \
+              --jq 'length')
+            if [ "$count" -lt 1 ]; then
+              echo "❌ $repo has no closed issue with label uxf-transfer-v1-ack — maintainer ack required before T.8.D merges"
+              missing+=("$repo")
+            else
+              echo "✅ $repo: $count closed uxf-transfer-v1-ack issue(s) found"
+            fi
+          done
+          if [ ${#missing[@]} -gt 0 ]; then
+            echo "::error::T.8.D cutover blocked — ${#missing[@]} external repo(s) missing acks: ${missing[*]}"
+            exit 1
+          fi
+          echo "All ${#REPOS[@]} external repos have signed off — T.8.D cutover gate passed."

.github/workflows/pointer-sdk-canary.yml

@@ -0,0 +1,175 @@
+name: Pointer SDK Canary
+
+# Triggers only when pointer-layer surface changes. The goal of this
+# workflow is to catch silent drift in:
+#   (1) the KAT test vectors (SPEC §14)
+#   (2) the pinned @unicitylabs/state-transition-sdk version range
+#   (3) the package-major / pointer-layer-major alignment
+#
+# It does NOT replace the main `CI` workflow; it runs in parallel on
+# pointer-touching PRs and fails closed if any of the invariants drift.
+#
+# See docs/uxf/PROFILE-AGGREGATOR-POINTER-TEST-SPEC.md §4 (W8 "SDK
+# version pinning + CI canary") for the normative requirement.
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - 'profile/aggregator-pointer/**'
+      - 'profile/pointer-wiring.ts'
+      - 'profile/profile-token-storage-provider.ts'
+      - 'tests/fixtures/pointer-kat-vectors.json'
+      - 'tests/fixtures/pointer-kat-vectors.sha256'
+      - 'tests/conformance/pointer/**'
+      - 'docs/uxf/PROFILE-AGGREGATOR-POINTER-TEST-SPEC.md'
+      - 'docs/uxf/PROFILE-AGGREGATOR-POINTER-SPEC.md'
+      - '.github/workflows/pointer-sdk-canary.yml'
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  canary:
+    name: pointer-layer canary
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: npm
+
+      - name: Install dependencies
+        run: |
+          npm install --include=optional --ignore-scripts
+          npm rebuild
+
+      # ---- Invariant 1: KAT vectors checksum has not drifted --------
+      # The `.sha256` file is the checked-in source of truth. If a dev
+      # changes the KAT vectors intentionally (e.g. after a SPEC bump),
+      # they MUST regenerate the checksum and commit both files in the
+      # same PR. Silent drift is caught here.
+      - name: Verify KAT vectors checksum
+        run: |
+          set -euo pipefail
+          VECTORS="tests/fixtures/pointer-kat-vectors.json"
+          CHECKSUM="tests/fixtures/pointer-kat-vectors.sha256"
+          if [ ! -f "$VECTORS" ]; then
+            echo "ERROR: $VECTORS not found"
+            exit 1
+          fi
+          if [ ! -f "$CHECKSUM" ]; then
+            echo "ERROR: $CHECKSUM not found — regenerate via:"
+            echo "  sha256sum $VECTORS | awk '{print \$1}' > $CHECKSUM"
+            exit 1
+          fi
+          EXPECTED=$(awk 'NR==1 {print $1}' "$CHECKSUM")
+          ACTUAL=$(sha256sum "$VECTORS" | awk '{print $1}')
+          if [ "$EXPECTED" != "$ACTUAL" ]; then
+            echo "ERROR: KAT vectors drift detected!"
+            echo "  file:     $VECTORS"
+            echo "  expected: $EXPECTED"
+            echo "  actual:   $ACTUAL"
+            echo ""
+            echo "If this change is intentional (SPEC bump), regenerate:"
+            echo "  sha256sum $VECTORS | awk '{print \$1}' > $CHECKSUM"
+            echo "and commit both files in the same PR."
+            exit 1
+          fi
+          echo "OK: KAT vectors checksum matches ($EXPECTED)"
+
+      # ---- Invariant 2: state-transition-sdk version is strictly pinned
+      # The pointer layer depends on AggregatorClient / RootTrustBase /
+      # InclusionProof types from @unicitylabs/state-transition-sdk.
+      # A floating range (^, ~, *) would allow silent ABI shifts under
+      # us. Enforce an exact pin (no range operator).
+      - name: Verify state-transition-sdk version is pinned exactly
+        run: |
+          set -euo pipefail
+          RAW=$(node -p "require('./package.json').dependencies['@unicitylabs/state-transition-sdk'] || ''")
+          echo "state-transition-sdk pin: '$RAW'"
+          if [ -z "$RAW" ]; then
+            echo "ERROR: @unicitylabs/state-transition-sdk missing from dependencies"
+            exit 1
+          fi
+          case "$RAW" in
+            ^*|~*|*x*|*\**|\>*|\<*)
+              echo "ERROR: @unicitylabs/state-transition-sdk version '$RAW' is a range."
+              echo "Pointer layer requires an exact pin (e.g. '1.6.1-rc.f37cb85')."
+              exit 1
+              ;;
+          esac
+          echo "OK: state-transition-sdk is exact-pinned"
+
+      # ---- Invariant 3: package-major ↔ pointer-layer-major alignment
+      # The pointer layer's HKDF info string embeds "v1" and the SPEC
+      # contract promises backwards-compat within a single major.
+      # If `package.json` version major bumps (0.x → 1.x etc.) without
+      # a corresponding pointer-layer-major bump (HKDF info rename +
+      # SPEC version), downstream wallets will silently re-derive
+      # different keys. Guard against that.
+      - name: Verify package-major aligns with pointer-layer-major
+        run: |
+          set -euo pipefail
+          PKG_VERSION=$(node -p "require('./package.json').version")
+          PKG_MAJOR=$(echo "$PKG_VERSION" | cut -d. -f1)
+          echo "package.json version: $PKG_VERSION (major=$PKG_MAJOR)"
+
+          # Expected pointer-layer major encoded in HKDF info constant.
+          # Parse profile/aggregator-pointer/constants.ts for the
+          # PROFILE_POINTER_HKDF_INFO literal and extract the trailing
+          # vN segment.
+          INFO_LINE=$(grep -E "PROFILE_POINTER_HKDF_INFO\s*=\s*utf8ToBytes\(" profile/aggregator-pointer/constants.ts | head -n1)
+          if [ -z "$INFO_LINE" ]; then
+            echo "ERROR: could not locate PROFILE_POINTER_HKDF_INFO in constants.ts"
+            exit 1
+          fi
+          POINTER_MAJOR=$(echo "$INFO_LINE" | sed -n 's/.*-v\([0-9][0-9]*\).*/\1/p')
+          if [ -z "$POINTER_MAJOR" ]; then
+            echo "ERROR: could not parse pointer-layer major from HKDF info"
+            echo "  line: $INFO_LINE"
+            exit 1
+          fi
+          echo "pointer-layer major (from HKDF info): v$POINTER_MAJOR"
+
+          # Alignment rule (v1 phase): while package.json is on 0.x,
+          # the pointer layer is v1. When package.json bumps to 1.x,
+          # pointer-layer v1 must still be the live protocol until a
+          # SPEC v4.x bump ships v2. This guard fires if someone
+          # publishes a package with major >= 2 while the HKDF info
+          # still says v1 — a strong signal of silent skew.
+          if [ "$PKG_MAJOR" -ge 2 ] && [ "$POINTER_MAJOR" = "1" ]; then
+            echo "ERROR: package major=$PKG_MAJOR but pointer-layer is still v1."
+            echo "Either bump pointer-layer to v2 (rename HKDF info + SPEC §14) or"
+            echo "downgrade package major."
+            exit 1
+          fi
+          echo "OK: package-major=$PKG_MAJOR aligns with pointer-layer-v$POINTER_MAJOR"
+
+      # ---- Invariant 4: TEST-SPEC §4 coverage matrix audit ----------
+      # Fails CI if any H/W finding lacks PRIMARY or SECONDARY coverage.
+      # The parser + assertions live in the test file; this step is a
+      # thin shim that invokes them.
+      - name: Coverage matrix audit
+        run: npx vitest run tests/conformance/pointer/
+
+      # ---- Invariant 5: typecheck + lint of the pointer layer -------
+      - name: Typecheck
+        run: npm run typecheck
+
+      # Scope: only lint the conformance audit files — the pointer
+      # layer itself is linted by the main `CI` workflow. Keeping
+      # this scope tight avoids double-reporting pre-existing
+      # warnings in pointer-layer source.
+      - name: Lint coverage-audit scaffold
+        run: npx eslint tests/conformance/pointer/
+
+      # ---- Invariant 6: pointer-layer unit tests still pass ---------
+      - name: Run pointer-layer unit tests
+        run: npx vitest run tests/unit/profile/pointer/