Merge pull request #46 from engineeredsoftware/v31/gate-3-profile-account-state

V31 Gate 3: Profile Account State

Author: geraldarthurdavis

.github/workflows/bitcode-gate-quality.yml

@@ -97,6 +97,7 @@ jobs:
             node scripts/check-v30-gate10-promotion-readiness.mjs --promotion-mode --skip-branch-check
             node scripts/check-v31-gate1-spec-roadmap-opening.mjs --skip-branch-check
             node scripts/check-v31-gate2-auxillaries-package-route-contracts.mjs --skip-branch-check
+            node scripts/check-v31-gate3-profile-account-state.mjs --skip-branch-check
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
             exit 1
@@ -137,6 +138,7 @@ jobs:
         run: |
           pnpm --dir uapi exec jest --runTestsByPath \
             tests/userDataRoute.test.ts \
+            tests/profileStep.test.tsx \
             tests/api/readReviewRoute.test.ts \
             tests/api/pipelineHarnessRoute.test.ts \
             tests/terminalPipelineHarnessClient.test.ts \

BITCODE_SPEC_V31.md

@@ -231,7 +231,11 @@ Gate 2 contract precision:
 Gate 3 profile/account precision:
 
 - Profile state binds user id, display identity, account readiness, wallet binding, model preference, template preference, notification posture, data-sharing posture, and completeness root.
-- Incomplete profile state must name blockers and repair routes rather than rendering as generic missing data.
+- Account identity is a typed support object containing user id, handle, display name, email, email verification, company, and role; it is not inferred again in UI surfaces.
+- Incomplete profile state must name completeness issues, blocking issue ids, repair routes, repair panes, and retry posture rather than rendering as generic missing data.
+- Model and template preferences are support readiness posture, with deterministic preference roots and repair actions when missing.
+- Notification posture names contact readiness, unread count, latest notification time, and source-safety class without exposing message bodies in the profile readiness summary.
+- Data-sharing posture names repository counts and enabled/disabled repository counts without exposing protected source.
 - Wallet binding is a capability/readiness field, not a private-key or custody claim.
 
 Gate 4 Connects precision:

BITCODE_SPEC_V31_DELTA.md

@@ -110,6 +110,13 @@ Closure acceptance:
 - incomplete profile/account state names blockers and recovery routes;
 - focused package, route, and pane tests prove persistence, hydration, projection, and source-safety.
 
+Gate 3 implementation centers:
+
+- `AuxillariesProfileState` carries `accountIdentity`, `profileCompleteness.issues`, `profileCompleteness.repairRoutes`, `walletBinding`, `preferences`, `notificationPosture`, and `dataSharingPosture` as package-owned source-safe state.
+- `/api/auxillaries/data` hydrates profile, GitHub connection, wallet status, BTD holdings, model preferences, template preferences, recent notifications, and repository inventory before delegating the read model to `buildAuxillaryDataPayload`.
+- The Profile pane consumes `profileState` instead of locally deriving readiness, rendering account readiness, wallet, notification, data-sharing, and repair actions from the package contract.
+- Focused tests prove account hydration, route projection, unread-notification posture, template preference posture, repair routes, and JSON-safe contract roots.
+
 ### Gate 4: Connects Provider Readiness And Recovery
 
 Gate 4 deepens provider connection readiness.

BITCODE_SPEC_V31_NOTES.md

@@ -80,3 +80,10 @@ Gate 1 is closed only when the V31 draft family validates over V30, the roadmap
 Gate 2 is closed only when Auxillaries support-state contracts are package-owned and JSON-safe.
 Routes may still authenticate, read/write explicit storage rows, and return framework responses, but readiness and policy objects for Profile, Connects, Interfaces, Wallet, BTD, organization, diagnostics, and recovery must be built through `packages/api/src/routes/auxillaries-contract.ts`.
 The route payload can preserve existing UI fields for compatibility, but provider tokens, wallet secrets, service keys, database credentials, private prompts, and protected source must be redacted before any UI, telemetry, or proof-hook consumption.
+
+## Gate 3 closure note
+
+Gate 3 is closed only when Profile/account state is not just a form payload.
+It must be a package-owned support state that binds account identity, profile completeness issues, repair routes, wallet binding posture, model/template preference posture, notification posture, data-sharing posture, and proof roots.
+The Profile pane may present and link repairs, but it must consume the package contract and must not locally rederive account readiness or completeness law.
+Route hydration must include template preference and notification readback where available, while missing storage rows degrade into explicit repair posture rather than generic missing data.

BITCODE_SPEC_V31_PARITY_MATRIX.md

@@ -57,8 +57,8 @@ No `_legacy/` source is active source truth.
 | --- | --- | --- | --- | --- |
 | Draft family and branch posture | Gate 1 | `BITCODE_SPEC_V31.md`, DELTA, NOTES, PARITY, `BITCODE_SPEC.txt`, branch `v31/gate-1-spec-roadmap-opening` | drafted | V31 family validates in draft mode over active V30 and `check:v31-gate1` passes. |
 | Roadmap truth | Gate 1 | `SPECIFICATIONS_ROADMAP.md`, README, PR template, workflow posture | drafted | Roadmap states V30 active, V31 draft, and coherent V32-V37 responsibilities. |
-| Auxillaries package and route contracts | Gate 2 | `packages/api`, `packages/orm`, `packages/btd`, `uapi/app/auxillaries`, route tests | pending | Shared Profile, Connects, Interfaces, Wallet, BTD, organization, readiness, and recovery objects are package-owned and JSON-safe. |
-| Profile and account state | Gate 3 | Profile/account packages, routes, Auxillaries pane tests | pending | Profile, account identity, wallet binding, preferences, notification posture, and completeness blockers are typed and recoverable. |
+| Auxillaries package and route contracts | Gate 2 | `packages/api/src/routes/auxillaries-contract.ts`, `packages/api/src/routes/auxillaries.ts`, package docs, route tests | drafted | Shared Profile, Connects, Interfaces, Wallet, BTD, organization, readiness, and recovery objects are package-owned and JSON-safe. |
+| Profile and account state | Gate 3 | `packages/api/src/routes/auxillaries-contract.ts`, `packages/api/src/routes/auxillaries.ts`, `uapi/app/auxillaries/components/AuxillariesProfilePane.tsx`, route/pane tests | drafted | Profile, account identity, wallet binding, preferences, notification posture, and completeness blockers are typed and recoverable. |
 | Connects provider readiness and recovery | Gate 4 | Provider packages, connection routes, readiness/recovery tests | pending | Provider readiness names credential posture without secrets, scopes class, readback status, blocker, repair action, and before/after roots. |
 | Wallet and BTD pane readiness | Gate 5 | `packages/btd`, Wallet/BTD panes, settlement/read-right tests | pending | Wallet and BTD panes consume V30 no-custody, signer, read-right, treasury, and settlement-readiness primitives. |
 | Organization team role policy authority | Gate 6 | Organization packages/routes, policy authority tests, Terminal/Auxillaries projections | pending | Organization, team, role, grants, multi-sig readiness, policy decisions, denials, and recovery routes are typed and fail closed. |
@@ -105,9 +105,9 @@ No `_legacy/` source is active source truth.
 
 | Requirement | Source evidence | Current V31 judgment |
 | --- | --- | --- |
-| Profile/account state is typed | Profile/account package objects and tests | pending |
-| Wallet binding and preferences are recoverable support state | profile/account routes and Auxillaries pane readback | pending |
-| Incomplete state names blockers and repair routes | component tests and route tests | pending |
+| Profile/account state is typed | `AuxillariesAccountIdentity`, `AuxillariesProfileCompletenessIssue`, `AuxillariesPreferencePosture`, `AuxillariesNotificationPosture`, and `AuxillariesDataSharingPosture` in `packages/api/src/routes/auxillaries-contract.ts` | drafted |
+| Wallet binding and preferences are recoverable support state | `buildAuxillariesProfileState` emits wallet, model, and template repair issues; `/api/auxillaries/data` hydrates model and template preferences before `buildAuxillaryDataPayload` | drafted |
+| Incomplete state names blockers and repair routes | `packages/api/src/routes/__tests__/auxillaries-contract.test.ts`, `uapi/tests/userDataRoute.test.ts`, and `uapi/tests/profileStep.test.tsx` cover issues, blockers, repair routes, and Profile pane projection | drafted |
 
 ## Gate 4 Parity
 

SPECIFICATIONS_ROADMAP.md

@@ -5,7 +5,7 @@
 - Current active canonical pointer: `BITCODE_SPEC.txt` -> `V30`
 - Current active canon: `BITCODE_SPEC_V30.md`
 - Current draft target: `BITCODE_SPEC_V31.md`
-- Current working gate: V31 Gate 2 Auxillaries package and route contracts, which makes Profile, Connects, Interfaces, Wallet, BTD, organization, readiness, and recovery support-state objects package-owned, JSON-safe, and route-consumable over the V30 Protocol/BTD substrate.
+- Current working gate: V31 Gate 3 Profile and account state, which deepens the package-owned Auxillaries Profile contract with account identity, wallet binding posture, model/template preferences, notifications, data-sharing posture, explicit blockers, and repair routes over the V30 Protocol/BTD substrate.
 - Purpose: concise running index of Bitcode/ENGI specification history, current work, and planned work.
 
 This roadmap is not an active system specification.

package.json

@@ -66,6 +66,7 @@
     "check:v30-gate10": "node scripts/check-v30-gate10-promotion-readiness.mjs",
     "check:v31-gate1": "node scripts/check-v31-gate1-spec-roadmap-opening.mjs",
     "check:v31-gate2": "node scripts/check-v31-gate2-auxillaries-package-route-contracts.mjs",
+    "check:v31-gate3": "node scripts/check-v31-gate3-profile-account-state.mjs",
     "check:spec-quality": "node scripts/run-bitcode-spec-quality.mjs --mode basic",
     "check:spec-quality:title": "node scripts/run-bitcode-spec-quality.mjs --mode strict-from-title",
     "check:spec-quality:v24": "node scripts/run-bitcode-spec-quality.mjs --mode strict-version --version V24",

packages/api/README.md

@@ -27,6 +27,13 @@ objects must be built through `buildAuxillariesContractSnapshot` and
 secrets, private prompts, protected source, service keys, and database
 credentials before UI, telemetry, or proof-hook consumption.
 
+Profile/account state is also package-owned. `AuxillariesProfileState` binds
+the support identity, completeness issues, repair routes, wallet binding,
+model/template preferences, notification posture, data-sharing posture, and
+proof roots. Profile UI and routes can display or persist explicit fields, but
+they should not recalculate readiness locally; missing profile/account facts
+must degrade into named blockers or repairable issues.
+
 In V26 fourth-gate this package is where merged-world Bitcode becomes concrete:
 - `/conversations` continuity
 - `/executions` compatibility and pipeline-run APIs

packages/api/src/routes/__tests__/auxillaries-contract.test.ts

@@ -16,6 +16,8 @@ describe('Auxillaries package route contracts', () => {
         id: 'user-1',
         username: 'operator',
         display_name: 'Operator',
+        email: 'operator@bitcode.exchange',
+        is_verified: true,
         company_name: 'Bitcode',
         role: 'admin',
         wallet_binding: {
@@ -78,14 +80,55 @@ describe('Auxillaries package route contracts', () => {
       ],
       modelPreferences: {
         preferred_model: 'gpt-4.1',
+        preferred_provider: 'openai',
       },
+      templatePreferences: {
+        shippable_templates: {
+          asset_pack_pr: { label: 'AssetPack PR' },
+        },
+        evidence_document_templates: {
+          witness_summary: { label: 'Witness summary' },
+        },
+        auto_save_templates: true,
+      },
+      notificationRows: [
+        {
+          id: 'notification-1',
+          is_read: false,
+          created_at: '2026-05-21T01:00:00.000Z',
+        },
+      ],
       onboardedSteps: ['btd', 'connects', 'profile', 'interfaces'],
     });
 
     expect(payload.isOnboardingComplete).toBe(true);
     expect(payload.onboardedPanes).toEqual(['wallet', 'externals', 'profile', 'interfaces']);
     expect(payload.organizations).toEqual(['bitcode']);
     expect(payload.profileState.kind).toBe('AuxillariesProfileState');
+    expect(payload.profileState.accountIdentity).toMatchObject({
+      userId: 'user-1',
+      emailVerified: true,
+    });
+    expect(payload.profileState.preferences.model).toMatchObject({
+      configured: true,
+      provider: 'openai',
+      model: 'gpt-4.1',
+    });
+    expect(payload.profileState.preferences.templates).toMatchObject({
+      configured: true,
+      shippableTemplateCount: 1,
+      evidenceDocumentTemplateCount: 1,
+      autoSaveTemplates: true,
+    });
+    expect(payload.profileState.notificationPosture).toMatchObject({
+      state: 'attention_needed',
+      unreadCount: 1,
+    });
+    expect(payload.profileState.dataSharingPosture).toMatchObject({
+      state: 'configured',
+      repositoryCount: 1,
+      enabledRepositoryCount: 1,
+    });
     expect(payload.connectionReadiness[0]).toMatchObject({
       provider: 'github',
       connected: true,
@@ -124,6 +167,8 @@ describe('Auxillaries package route contracts', () => {
       btcFeeBalance: null,
       recentBtdAssetPacks: [],
       modelPreferences: null,
+      templatePreferences: null,
+      notificationRows: [],
       onboardedSteps: [],
     });
 
@@ -134,6 +179,8 @@ describe('Auxillaries package route contracts', () => {
     expect(blockerIds).toEqual(expect.arrayContaining([
       'profile.missing',
       'profile.identity_missing',
+      'preferences.model_missing',
+      'preferences.templates_missing',
       'connects.github.connect_provider',
       'wallet.binding_missing',
     ]));