PayCargo · AI-Sandbox · Process

6.bWebSocket pattern — server push for vibe apps

Specced doctrine for real-time bidirectional channels. Captured before the first consumer demands the capability; built only when one does. Defines the SDK surface, contracts, audit + cost model, and the substrate primitives so the design is ready when the use case shows up.

Block: 6.b (Console doctrine extension) · State: Specced, no code · First consumer: TBD (live system alerts; multi-user collaboration; long-running agent progress)

1. When WebSockets are the right tool

Need	WebSocket?	Alternative
Streaming AI response (chatbot)	No	Lambda Function URL Response Streaming (already in Step 6.a)
Cron / scheduled updates (every minute or slower)	No	Client polling with cache headers
Server → browser push of system alerts (sub-second)	Yes	—
Multi-user collaboration (shared cursors, presence)	Yes	—
Long-running agent progress (per-step status pushes)	Yes	—
Live dashboards with high-frequency tile updates	Maybe	SSE over Lambda Function URL streaming (simpler, one-way)

2. The substrate primitive

Shared platform resource (one per AWS region):

API Gateway WebSocket API at wss://realtime.<platform-domain>
$connect route: authorizer Lambda validates the JWT (X-Auth-Token, intra-platform SSO from §13); stores connection metadata in DDB
$disconnect route: removes the connection metadata
$default route: dispatches by message envelope's app + action fields to the right vibe-app Lambda
Connections table ai-sandbox-ws-connections: connectionId (PK), userId, cognitoGroups, connectedAt, lastSeen, appsActive (list of vibe apps subscribed to)

Per-app: a Lambda function that handles the vibe-app's WebSocket actions (similar shape to the HTTP route handler).

3. SDK surface — vibe-scripter facing

Browser side

// vibecode/sdk/v1/spa/socket.js
import { connect } from '/sdk/v1/spa/socket.js';

const socket = connect();
socket.on('alert', (event) => { /* render alert */ });
socket.on('thread.updated', (event) => { /* refresh thread */ });
socket.emit('chat.typing', { threadId });
// Auto-reconnect, exponential backoff, ping/pong heartbeat all internal.

Server side

// vibecode/sdk/v1/lambda/socket.ts
import { broadcast } from 'vibecode-sdk';

// From any Lambda handler — vibe scripter writes:
await broadcast({
  users: ['userId-abc', 'userId-def'],
  payload: { type: 'alert', severity: 'high', message: '...' },
});

// Or by group:
await broadcast({
  groups: ['admins'],
  payload: { type: 'alert', severity: 'high', message: '...' },
});

Internal: the broadcast helper looks up active connections from the DDB connections table, dispatches via API Gateway Management API, handles per-message retries and DLQ for permanently-disconnected receivers.

4. Contracts that carry over

Contract	How it applies to WebSockets
`governance_cell`	WebSocket connection table encrypted with the substrate's audit CMK; vibe app's outbound messages tagged with the app's governance cell
`three_layer_defense`	API Gateway uses Cognito authorizer at $connect (org SCP allows API Gateway with JWT-based auth); per-message $default routes still validate identity from connection metadata
`lockbox_only_pii`	PII detector runs on every incoming + outgoing WebSocket payload; lockbox helpers used for any PII reveal
`audit_emit_required`	Every $connect, $disconnect, $default, and broadcast emits a structured audit event
`cost_attribute`	Per-connection-minute and per-message costs tagged with app + cell + purpose

5. Authentication invariants

JWT validation at $connect only (subsequent messages inherit the connection's identity from the DDB lookup)
Group claims captured in the connection record at $connect time; remain valid for the connection's lifetime (≤24h by token TTL)
Re-auth required after JWT expiry: connection drops on $disconnect, client auto-reconnects with a fresh JWT
Cross-user broadcast routes through SDK helpers, never raw — vibe scripter cannot accidentally fan a message to all users

6. Cost model

API Gateway: ~$1.00 per million messages, ~$0.25 per million connection-minutes
For 10 concurrent users at 4-hour average sessions, 50 messages/hour: ~$0.06/month
For 100 concurrent users at full-day sessions: ~$2.50/month
Lambda + DDB writes: negligible (existing substrate cost shape)

7. When this gets built

Engineering team starts construction when the first vibe app proposes a use case that requires bidirectional or sub-second server push. The most likely first consumer is one of:

Live obs app alerts: when a GuardDuty severity-9 finding lands, the obs app's operators tab gets a real-time alert without a 30s polling delay
Cross-app event notifications: when vibe app 2's CSV ingest completes, an obs app banner updates
Multi-step agent progress: a long-running agent's "thinking → consulting tool A → consulting tool B → composing answer" stream visible to the user as it happens

The spec above survives until that moment. The build is ~1 day of engineering work against this spec.

8. Doctrine

Step 6.b doctrine: "Spec ahead of demand, build at demand."

WebSockets are a substantive substrate addition. Building them without a real consumer means engineering against assumptions. Specifying them ahead of demand lets the doctrine survive the engineering team's eventual review when the use case lands. The spec is the design; the consumer is the validator. When both exist, the build is straightforward.