wip v28

Author: geraldarthurdavis

BITCODE_SPEC_V28_NOTES.md

@@ -269,6 +269,8 @@ They are V28 inputs because V27 closed the protocol law and minimum crypto-comme
 | V26 proof generator and older promotion scripts still contain version-specific historical logic | V27 accepted generated-equivalent proof artifacts rather than fully modernizing promotion automation | Decide whether V28 should update proof generation for V28+ families or leave older promotion scripts as historical tooling |
 | Some formal protocol package internals are freshly ported from the standalone demonstration | V28 now owns commercializing the Protocol implementation enough that commercial code must not depend on demonstration runtime code | Keep commercial UAPI imports on formal packages such as `@bitcode/protocol`, keep `protocol-demonstration` out of the workspace build graph, move required demonstration-derived behavior into packages/UAPI, and use the demonstration only as reference/proof witness |
 | BNB Chain, opBNB, Binance Web3 Wallet, BEP-20, and BitVM bridge research are relevant but not current chain-of-record facts | V28 must avoid implying a public BTD deployment or native BNB Taproot/BitVM compatibility | Treat Bitcoin Taproot/PSBT/testnet as V28's practical crypto lane; record BSC/opBNB/Binance and BitVM bridge pilots as future bridge/distribution work unless a proof-bound testnet artifact exists |
+| Top chrome can briefly show `Connect Wallet` while wallet/user data is still loading | V28 wallet identity is the origin point for Supabase synchronization and Terminal readiness | Treat top chrome wallet state as tri-state: reading, connected, disconnected. The disconnected CTA may render only after auxillary user data has settled. While unresolved, render an integrated loading indicator and emit QA telemetry so manual passes can distinguish slow readiness from missing identity. |
+| Manual QA needs database-level evidence, not only screenshots | V28 is proving ledger/database synchronization posture before deeper deployment versions | Each wallet/GitHub/Terminal pass must collect client logs, server logs, network failures, and Supabase SQL query results for `auth.users`, `auth.identities`, `user_profiles`, `user_connections`, and repository inventory tables. Missing tables or permission errors are valid evidence and must be recorded, not hidden. |
 
 ## V28 Gate Sketch
 
@@ -282,6 +284,9 @@ The minimum useful V28 gate plan is Protocol/Terminal-MVP-first:
 
 2. **Gate 2: Protocol/Terminal MVP QA Baseline**
    - QA primary active routes and navigation.
+   - Prove top chrome wallet readiness as a tri-state loading/connected/disconnected surface so the wallet CTA does not appear before connection status is known.
+   - Add client and server QA telemetry around wallet OAuth, wallet proof persistence, auxillary data reads, GitHub setup callbacks, and user-data cache revalidation.
+   - Add Supabase SQL verification to manual QA steps so profile, wallet identity, provider connection, and GitHub installation synchronization are checked at the database layer.
    - Remove Auxillaries old orbital shell conflicts from active contained tabs-left paths.
    - Disable or hide Exchange and website Conversations from V28 QA.
    - Separate commercial runtime imports from the standalone protocol demonstration and remove the demonstration from the workspace build graph.

BITCODE_V28_QA.md

@@ -85,6 +85,7 @@ Each pass should be small enough to produce actionable screenshots, console obse
 | Pass | Track | Scope | Stop condition |
 | --- | --- | --- | --- |
 | 3A | Natural progression 1A | Wallet, GitHub, profile, notifications, nav balance, Auxillaries Connects/Profile/BTD readiness. | Mock passes deterministic readiness; testnet-readiness either works live or records precise blocked provider/credential states; no console errors. |
+| 3A-prereq | Natural progression 1A | Sign-up/sign-in, signed Bitcoin wallet authentication, BTC/BTD chrome, GitHub App installation, and prerequisite clarity before Give/Need. | Mock proves the intended prerequisite model; testnet proves or precisely blocks Supabase custom Bitcoin OAuth, wallet proof capture, profile persistence, sign-out clearing, and GitHub installation visibility. |
 | 3B | Natural progression 1B | Simplest Need path: select/express Need, run or inspect fastest Fit path, read settlement/delivery/result state. | User can explain what happened, where it landed in Exchange, what is mocked, and what remains staged in testnet-readiness. |
 | 3C | Natural progression 1C | Simplest Give path: attach or select source, run/inspect Give flow, read earning/settlement state. | User can explain what source was contributed, how it was measured, and whether earning/BTD posture is live, mocked, or blocked. |
 | 4A | Docs sequence 00 | Docs overview and Source Shares against nav, Terminal, BTD widget, MCP/ChatGPT readiness. | Contradictions between docs and product are logged in both lanes. |
@@ -208,6 +209,32 @@ Manual evidence requested for this pass:
 - console errors and network errors after each lane;
 - answer whether any wallet-extension permission prompt appeared, which wallet extension/provider it was, which network/account was selected, and whether the app changed state after approval/cancel/failure.
 
+### 2026-05-12 Pass 3A-prereq: Sign-up, Sign-in, Wallet, And GitHub Prerequisites
+
+This pass focuses only on prerequisite reality before Terminal Give/Need QA continues.
+It validates the V28 rule that signed Bitcoin wallet authentication is the origin point for Supabase user data synchronization, and that GitHub App installation is the next required prerequisite for Giving and Needing.
+
+Run the same checklist first in mock, then in testnet-readiness.
+Mock establishes the intended product language and visual state.
+Testnet-readiness establishes whether the live custom OAuth provider, browser wallet, Supabase session, local/server wallet persistence, BTC/BTD chrome, sign-out clearing, and GitHub App install flow are usable or precisely blocked.
+
+Prerequisite pass stop conditions:
+
+| Lane | Stop condition |
+| --- | --- |
+| Mock | Profile shows wallet-first identity, Connects shows GitHub as the second prerequisite, BTD/top chrome show deterministic wallet facts, sign-out clears the signed-in mock posture, and no console errors appear. |
+| Testnet-readiness | A Bitcoin wallet proof either creates a Supabase session and persists through `/api/wallet/authenticate`, or fails at a named boundary: wallet provider unavailable, OAuth provider URL not reachable by Supabase, database schema missing, or GitHub App install/session missing. |
+
+V28 prerequisite report fields:
+
+1. Current URLs for both lanes and whether each route loaded at the top of `/terminal`.
+2. Mock Profile result: wallet-first copy, provider buttons, optional email position, BTC/BTD chrome, sign-out behavior, and console result.
+3. Testnet wallet result: provider clicked, wallet prompt seen, network/account selected, signed message approved/cancelled, final URL after Supabase callback, and whether Profile/top chrome show connected wallet.
+4. Testnet network/API result: any failed request URL/status/body for `/tps/wallet/authorize`, `/api/wallet/oauth/authorization-code`, Supabase `/auth/v1/token`, `/api/wallet/oauth/token`, `/api/wallet/oauth/userinfo`, `/api/wallet/authenticate`, `/api/auxillaries/data`, and GitHub callback/setup routes.
+5. Testnet sign-out result: whether Supabase session, local wallet identity, top chrome, Profile, BTD pane, and Connects prerequisite state all return to unauthenticated/unconnected.
+6. GitHub result: whether the install link opens `https://github.com/apps/bitcode-github-app-auxillary`, whether installation callback returns to Connects, and whether connected account/repository scope appears.
+7. Screenshots of any blocked/failing state and all console errors/warnings except expected extension-injection noise.
+
 Manual findings from 2026-05-09:
 
 | Lane | Check | Result | V28 disposition |
@@ -477,3 +504,119 @@ V28 blocker / V28 polish / V29+ deferred
 
 ### Notes
 ```
+
+## Required QA Telemetry And Database Evidence
+
+Every V28 manual pass from this point forward must capture three evidence layers.
+
+1. Browser console with `NEXT_PUBLIC_BITCODE_QA_VERBOSE=true`.
+   Capture `[Bitcode QA]` lines after each interaction group, plus warnings/errors from wallet extensions, Supabase, GitHub, and route fetches.
+
+2. Dev server console with `BITCODE_QA_VERBOSE=true`.
+   Capture `[Bitcode QA Server]` lines for wallet OAuth, token/userinfo, wallet persistence, auxillary data reads, and GitHub callback/setup routes.
+
+3. Supabase SQL results.
+   Run the relevant SQL queries below after sign-in, sign-out, GitHub install, and any Terminal write that claims to sync identity/source state.
+   Paste both successful rows and SQL/table/permission errors into the QA notes.
+
+Wallet-authentication baseline:
+
+```sql
+select
+  id,
+  email,
+  raw_app_meta_data,
+  raw_user_meta_data,
+  created_at,
+  last_sign_in_at
+from auth.users
+order by created_at desc
+limit 5;
+```
+
+```sql
+select
+  user_id,
+  provider,
+  identity_data,
+  created_at,
+  updated_at
+from auth.identities
+where provider = 'custom:bitcode-bitcoin'
+order by updated_at desc
+limit 10;
+```
+
+Bitcode profile and wallet binding:
+
+```sql
+select
+  id,
+  username,
+  wallet_address,
+  wallet_provider,
+  wallet_binding_status,
+  settings->'bitcodeProfile'->'walletBinding' as wallet_binding,
+  updated_at
+from public.user_profiles
+order by updated_at desc
+limit 10;
+```
+
+Wallet and GitHub provider connections:
+
+```sql
+select
+  user_id,
+  provider,
+  is_active,
+  connection_data->>'address' as wallet_address,
+  connection_data->>'network' as wallet_network,
+  connection_data->>'verification_state' as verification_state,
+  connection_data->>'auth_source' as auth_source,
+  connection_data->>'account_login' as github_account,
+  updated_at
+from public.user_connections
+where provider in ('xverse', 'leather', 'unisat', 'okx-bitcoin', 'github')
+order by updated_at desc
+limit 20;
+```
+
+GitHub repository inventory:
+
+```sql
+select
+  user_id,
+  provider,
+  repo_full_name,
+  repo_default_branch,
+  updated_at
+from public.vcs_repositories
+order by updated_at desc
+limit 20;
+```
+
+If `vcs_repositories` is not present in the current schema, run:
+
+```sql
+select
+  user_id,
+  provider,
+  connection_data->'repositories' as installation_repositories,
+  updated_at
+from public.user_connections
+where provider = 'github'
+order by updated_at desc
+limit 10;
+```
+
+### Top Chrome Wallet Readiness
+
+Expected V28 behavior:
+
+- first page load renders an integrated `Reading wallet` indicator while `/api/auxillaries/data` and local wallet identity state are unresolved;
+- `Connect Wallet` renders only after the data read has settled with no wallet identity;
+- the BTC/BTD widget renders only after a stored or locally staged wallet identity is known;
+- a later background revalidation may make the BTC/BTD widget show its own loading posture, but it must not regress to the disconnected CTA while a known wallet exists;
+- client telemetry must include `nav:chrome-identity`, `user-data:fetch-start`, `user-data:read` or `user-data:anonymous-read`, and any fetch failure;
+- server telemetry must include `auxillaries-data:read-start` and `auxillaries-data:read-finish` or `auxillaries-data:read-failed`.

uapi/README.md

@@ -5,6 +5,9 @@ It carries the `/terminal` operator surface, `/exchange` activity master-detail,
 
 Active canon follows the top-level `BITCODE_SPEC.txt` pointer while the current draft hardens the commercial MVP experience.
 
+V28 QA scope is intentionally narrower than the full route inventory: Terminal, Auxillaries readiness, wallet-backed identity, GitHub source prerequisites, `$BTD` posture, MCP/API, and ChatGPT App MVP remain active; Exchange and website Conversations are deferred beyond V35 unless retained code contaminates the active V28 surfaces.
+Wallet state in top chrome is tri-state during QA: loading while shared auxillary data is unresolved, connected when a wallet binding or local staged wallet exists, and disconnected only after the read settles without a wallet.
+
 ## Primary routes
 
 - `/`

uapi/app/api/auxillaries/data/route.ts

@@ -1,5 +1,6 @@
 import { buildGetAuxillaryDataRoute } from '@bitcode/api/src/routes/auxillaries';
 import { buildMockAuxillariesData, isAuxillariesMockMode } from '@/lib/mock-review-mode';
+import { bitcodeServerTelemetry } from '@/lib/bitcode-server-telemetry';
 import { readBitcodeWalletConnectionStatus } from '@/app/api/wallet/_shared';
 import {
   buildDisconnectedConnectionStatus,
@@ -11,7 +12,7 @@ import {
 
 export const runtime = 'nodejs';
 
-export const GET = buildGetAuxillaryDataRoute({
+const getAuxillaryData = buildGetAuxillaryDataRoute({
   isMockMode: isAuxillariesMockMode,
   mockAuxillaryData: buildMockAuxillariesData,
   resolveWalletConnectionStatus: async ({ supabase, userId, profile }) => {
@@ -48,3 +49,24 @@ export const GET = buildGetAuxillaryDataRoute({
     };
   },
 });
+
+export async function GET(request: Request) {
+  bitcodeServerTelemetry('info', 'auxillaries-data', 'read-start', {
+    mockMode: isAuxillariesMockMode(),
+  });
+
+  try {
+    const response = await getAuxillaryData(request);
+    bitcodeServerTelemetry('info', 'auxillaries-data', 'read-finish', {
+      status: response.status,
+      mockMode: isAuxillariesMockMode(),
+    });
+    return response;
+  } catch (error) {
+    bitcodeServerTelemetry('error', 'auxillaries-data', 'read-failed', {
+      message: error instanceof Error ? error.message : String(error),
+      mockMode: isAuxillariesMockMode(),
+    });
+    throw error;
+  }
+}

uapi/app/api/wallet/authenticate/route.ts

@@ -6,6 +6,10 @@ import {
 } from '@bitcode/orm';
 import { supabaseAdmin } from '@bitcode/supabase';
 import { createClient } from '@bitcode/supabase/ssr/server';
+import {
+  bitcodeServerTelemetry,
+  compactBitcodeServerId,
+} from '@/lib/bitcode-server-telemetry';
 
 export const runtime = 'nodejs';
 
@@ -80,6 +84,9 @@ export async function POST(request: Request) {
   } = await supabase.auth.getUser();
 
   if (!user || userError) {
+    bitcodeServerTelemetry('warn', 'wallet-authenticate', 'session-required', {
+      userError: userError?.message ?? null,
+    });
     return NextResponse.json(
       {
         error:
@@ -94,6 +101,7 @@ export async function POST(request: Request) {
   try {
     body = (await request.json()) as WalletAuthPayload;
   } catch {
+    bitcodeServerTelemetry('warn', 'wallet-authenticate', 'invalid-json');
     return NextResponse.json({ error: 'Invalid JSON body' }, { status: 400 });
   }
 
@@ -110,10 +118,19 @@ export async function POST(request: Request) {
   const connectedAt = readNonEmptyString(body.connectedAt) ?? issuedAt;
 
   if (!address || !isPlausibleBitcoinAddress(address)) {
+    bitcodeServerTelemetry('warn', 'wallet-authenticate', 'invalid-address', {
+      address: compactBitcodeServerId(address),
+      provider,
+      network,
+    });
     return NextResponse.json({ error: 'A valid Bitcoin wallet address is required.' }, { status: 400 });
   }
 
   if (!provider) {
+    bitcodeServerTelemetry('warn', 'wallet-authenticate', 'invalid-provider', {
+      provider: readNonEmptyString(body.provider),
+      address: compactBitcodeServerId(address),
+    });
     return NextResponse.json(
       {
         error:
@@ -124,17 +141,29 @@ export async function POST(request: Request) {
   }
 
   if (!proofKind) {
+    bitcodeServerTelemetry('warn', 'wallet-authenticate', 'missing-proof-kind', {
+      provider,
+      address: compactBitcodeServerId(address),
+    });
     return NextResponse.json({ error: 'Bitcoin wallet proof kind is required.' }, { status: 400 });
   }
 
   if (proofKind === 'bitcoin_message_signature') {
     if (!message || !signature) {
+      bitcodeServerTelemetry('warn', 'wallet-authenticate', 'missing-signature', {
+        provider,
+        address: compactBitcodeServerId(address),
+      });
       return NextResponse.json(
         { error: 'Bitcoin wallet message-signature proof requires both message and signature.' },
         { status: 400 },
       );
     }
     if (!isBitcodeBitcoinWalletMessage(message, address)) {
+      bitcodeServerTelemetry('warn', 'wallet-authenticate', 'message-mismatch', {
+        provider,
+        address: compactBitcodeServerId(address),
+      });
       return NextResponse.json(
         { error: 'Bitcoin wallet message does not match the Bitcode authentication challenge.' },
         { status: 400 },
@@ -144,13 +173,26 @@ export async function POST(request: Request) {
 
   const persistedAt = new Date().toISOString();
   const bindingStatus = proofKind === 'bitcoin_message_signature' ? 'pending' : 'pending';
+  bitcodeServerTelemetry('info', 'wallet-authenticate', 'persist-start', {
+    userId: compactBitcodeServerId(user.id),
+    provider,
+    address: compactBitcodeServerId(address),
+    network,
+    proofKind,
+    paymentAddress: compactBitcodeServerId(paymentAddress),
+    authAddress: compactBitcodeServerId(authAddress),
+  });
   const { data: existingProfile, error: profileReadError } = await supabaseAdmin
     .from('user_profiles')
     .select('*')
     .eq('id', user.id)
     .maybeSingle();
 
   if (profileReadError) {
+    bitcodeServerTelemetry('error', 'wallet-authenticate', 'profile-read-failed', {
+      userId: compactBitcodeServerId(user.id),
+      message: profileReadError.message,
+    });
     return NextResponse.json({ error: profileReadError.message }, { status: 500 });
   }
 
@@ -190,6 +232,10 @@ export async function POST(request: Request) {
   );
 
   if (profileWriteError) {
+    bitcodeServerTelemetry('error', 'wallet-authenticate', 'profile-write-failed', {
+      userId: compactBitcodeServerId(user.id),
+      message: profileWriteError.message,
+    });
     return NextResponse.json({ error: profileWriteError.message }, { status: 500 });
   }
 
@@ -223,6 +269,12 @@ export async function POST(request: Request) {
   );
 
   if (connectionWriteError) {
+    bitcodeServerTelemetry('error', 'wallet-authenticate', 'connection-write-failed', {
+      userId: compactBitcodeServerId(user.id),
+      provider,
+      address: compactBitcodeServerId(address),
+      message: connectionWriteError.message,
+    });
     return NextResponse.json(
       {
         error: connectionWriteError.message,
@@ -234,6 +286,14 @@ export async function POST(request: Request) {
     );
   }
 
+  bitcodeServerTelemetry('info', 'wallet-authenticate', 'persist-success', {
+    userId: compactBitcodeServerId(user.id),
+    provider,
+    address: compactBitcodeServerId(address),
+    network,
+    verificationState: bindingStatus,
+  });
+
   return NextResponse.json(
     {
       success: true,