6.aPhase A — Chatbot, the Console's first dogfood

1. Why a chatbot for Phase A (not docs-only)

The original Step 6 framing put Phase A as "docs only — spec the SDK, no code." That's the safe path: lock the doctrine, then build. The risk: SDK packages specced in a vacuum tend to be wrong in subtle ways that only show up at integration time, after the developer's mental model has already congealed around the wrong shape.

The chatbot reframe: ship the smallest real app that exercises four of the five contracts. The SDK packages get written as the chatbot demands them. The shape is validated under real usage before vibe app 2 lands next week with the the external developer. The doctrine is preserved (still doc-first — this Step 6.a doc precedes the code) but the validation is structural, not theoretical.

Why a chatbot specifically:

• Touches Bedrock — exercises vibecode/sdk/agent.ts wrapper with audit + cost attribution.
• Touches the DB layer — thread persistence in DDB exercises the four-layer DB boundary's IAM tier scoping.
• Touches the browser→Lambda surface — the three-layer defense pattern (Step 4.5.b) gets re-exercised; we confirm the obs-app pattern composes for a new app cleanly.
• Has a persistent state model — threads accumulate; exercises read-write-update DDB patterns, not just read-only metrics like the obs app.
• Is genuinely useful — the platform owner gets a "chat with Claude through the platform with audit + cost attribution" tool. The platform owner is also the first user. Recursive dogfood.

2. The user flow — what the user actually sees

1. the user opens https://chat.<TBD> (or https://<obs-app-domain>/chat if we reuse the obs app domain — see decisions §8).
2. Cognito Hosted UI — sign in with the existing mmbtang@gmail.comlt;your-gmailmmbtang@gmail.comgt; credentials + TOTP. Same dual-auth Step 4.5 pattern.
3. App loads. Left rail: thread list (the user's previous threads). Main pane: empty (or last open thread).
4. the user clicks "New thread" — a thread row appears in the rail; main pane shows an empty conversation.
5. the user types a message in the input box at the bottom and hits send.
6. Within ~300ms, Claude Haiku starts streaming tokens into a new assistant message bubble. the user sees the response materialize character-by-character.
7. When streaming completes, the thread updates in DDB. Audit event fires (one for the user message, one for the assistant response). Cost attribution lands on the chatbot app's bucket. Thread title auto-generated from first user message.
8. the user can navigate back to any past thread — threads persist across sessions, keyed by user ID. Each thread has its own conversation context that gets fed to Bedrock on each new message.
9. Each interaction is measured. Every Bedrock call emits structured audit (user, thread, model, input/output tokens, cost). Console's cross-app observability surface aggregates these.

No PII flows through this app. The conversation is the platform owner asking Claude things about the platform, the substrate, the strategy. lockbox_only_pii contract is satisfied vacuously, but its plumbing — the PII detector in the audit emitter — runs anyway.

3. Architecture — substrate, Console, app layers in this delivery

Every layer boundary is the substrate's: app talks only to Console; Console talks only to substrate. App's Terraform module imports the Console's app-template. App's Lambda code imports the Console's SDK packages. No direct AWS SDK calls from app code — that's the lockout chip running for real for the first time.

4. SDK contracts exercised

Four contracts actively driven; one vacuously satisfied but with its enforcement plumbing tested. Vibe app 2 (Sales reports with real PII) inherits the tested plumbing for contract 3 instead of building it from scratch.

5. SDK packages that crystallize

Three SDK packages get written as TypeScript modules, packaged for Lambda Node 20 runtime. No CodeArtifact registry yet (that's Phase D); for Phase A they're imported via relative path from the app's lambda/ directory. Mono-repo shape, single source of truth.

vibecode/sdk/agent.ts

// API surface (signatures only — actual code in Phase A delivery)
export interface AgentInvocation {
  model: 'claude-haiku-4-5' | 'claude-sonnet-4-6';
  messages: ChatMessage[];
  attribution: {
    app: string;       // required — no default
    cell: string;      // required — must be in governance grid
    purpose: string;   // required — operational tag
    threadId?: string; // optional but recommended
  };
  opts?: { temperature?: number; maxTokens?: number };
}

export interface ChatMessage {
  role: 'user' | 'assistant' | 'system';
  content: string;
}

// Streams response chunks back as they arrive from Bedrock
export async function* invokeAgent(
  inv: AgentInvocation
): AsyncIterable<{ text: string; done: boolean; usage?: TokenUsage }>;

// Convenience for non-streaming callers
export async function invokeAgentSync(inv: AgentInvocation): Promise<string>;

Internally: validates attribution (throws if missing), emits start audit event, calls Bedrock's InvokeModelWithResponseStream, accumulates token counts, emits completion audit event with cost attribution and usage.

vibecode/sdk/audit.ts

export interface AuditEvent {
  app: string;
  op: string;          // 'chat.message.send', 'chat.thread.create', etc.
  user: string;        // Cognito sub or username
  timestamp?: string;  // auto-filled if missing
  payload: Record<string, unknown>;
  // PII-shape detector scrubs values matching email/phone/SSN patterns
  // and replaces them with `[REDACTED:<shape>]` before emission.
}

export async function emit(event: AuditEvent): Promise<void>;

// Middleware for Lambda handlers — ensures emit() was called before
// the route handler's response is sent. If not, the response is replaced
// with a structured 500 and the operation is logged as a violation.
export function withAuditEnforcement(
  handler: RouteHandler
): RouteHandler;

Internally: puts a structured JSON event into a per-app CloudWatch log group on the backend governance CMK. PII detection uses a denylist of regex patterns (email, US phone, SSN-shape, common name forms). Scrubbed values become [REDACTED:email] etc.

vibecode/sdk/cost.ts

export interface CostAttribution {
  app: string;
  cell: string;
  purpose: string;
  // operational metadata
  inputTokens: number;
  outputTokens: number;
  model: string;
}

export function computeCost(usage: TokenUsage, model: string): number;

export async function emitCost(attr: CostAttribution): Promise<void>;

Internally: puts a custom CloudWatch metric (AISandbox/Vibe/BedrockCost) with dimensions app, cell, purpose, model. The cross-app observability surface in Phase C reads from this namespace.

6. Data layer — thread persistence + audit emission

Threads table

New DDB table: ai-sandbox-chatbot-threads

Encryption: at-rest with the chatbot app's governance cell CMK. The substrate's gateway endpoint policy (Layer 1 of the four-layer DB boundary) constrains which DDB actions are even reachable; the app's Lambda execution role grants only Get/Put/Update/Query on this specific table.

Tags: boundary: non-pii, governance_cell: eng-low-risk, owner: chatbot-app. The SDK's PII boundary check reads the table's tags before issuing a write.

Audit log group

Per-app CloudWatch log group: /aws/vibe-apps/chatbot/audit. Encrypted with eng-low-risk CMK. Retention 365 days for Phase A (longer retention is a Phase D decision). One log event per audit.emit() call. Structured JSON; consumable by CloudWatch Logs Insights and by the cross-app observability surface in Phase C.

7. Streaming — Bedrock response → Lambda → browser

Phase A uses Lambda Function URL Response Streaming (not API Gateway WebSocket, not Server-Sent Events directly from the SPA — we use Lambda's native streaming output mode).

Why Function URL streaming

• Already in the substrate (we use Function URL for the obs app).
• CloudFront forwards streaming responses natively when configured with the right cache policy.
• Lambda invocation mode RESPONSE_STREAM emits chunks as they're produced (no buffering).
• Bedrock's InvokeModelWithResponseStream emits its own chunks; Lambda passes them through.
• Browser reads via fetch() with response.body.getReader() — standard ReadableStream API.

The full streaming chain

Persistence ordering

The thread is updated after the assistant response streams in full. If the Lambda errors mid-stream, the user's message is retained in DDB but the partial assistant response is dropped. The audit event for the partial completion fires with an explicit { status: 'stream_failed', reason: ... } shape; cost is attributed for whatever tokens did flow.

Future enhancement (Phase B+): chunk-buffered persistence for very long responses so a mid-stream failure preserves partial work. Out of scope for Phase A.

8. Open decisions, with recommendations

Several shaping decisions where the right answer is non-obvious. Each presented with my recommended default and reasoning. Push back where the recommendation is wrong.

9. Failure modes — what each contract catches

10. Concrete deliverables list

Files and resources that exist at end of Phase A:

Substrate additions

• New DDB table: ai-sandbox-chatbot-threads (per the data layer §6)
• Optional: new Cognito app client added to existing user pool (per Decision 8.1)
• No new CMKs — reuse eng-low-risk per Decision 8.3

Console SDK packages

• vibecode/sdk/agent.ts — Bedrock streaming wrapper with attribution
• vibecode/sdk/audit.ts — structured event emission with PII detection
• vibecode/sdk/cost.ts — cost attribution + CloudWatch metric emission
• vibecode/sdk/governance/cell.ts — Terraform helper to wire cell CMK ARN
• vibecode/sdk/app-template/ — Terraform module taking (app_name, governance_cell)

Chatbot app

• cartridges/global/chatbot/ — Terraform module consuming the app-template
• cartridges/global/chatbot/lambda/ — Node 20 ARM64 Lambda handler using the SDK
• cartridges/global/chatbot/frontend/ — SPA: index.html, app.js, styles.css
• Composition wiring in substrate/environments/ai-sandbox/main.tf

Docs

• This Step 6.a doc (committed before code)
• Update Step 6 (parent doctrine doc): change Phase A description from "docs only" to "chatbot dogfood"
• Update MODULES.md: move agent.ts, audit.ts, cost.ts from "planned" to "Phase A delivery"
• (Optional) Step 6.b: App Review PR template draft (still doc-only, no code)
• (Optional) Step 6.c: Developer Portal vibe app spec (the second Phase B vibe app, still doc-only)

11. This-week rollout

1. Day 1 (today): This doc reviewed and committed. the platform owner says yes / fix this / fix that. Open decisions in §8 locked.
2. Day 2: SDK packages (agent.ts, audit.ts, cost.ts) written as standalone TypeScript modules in vibecode/sdk/. Unit tests covering the attribution validator, the PII detector, and the audit middleware.
3. Day 3: Terraform app-template module written, taking (app_name, governance_cell). Tested by spinning up a hello-world app that just returns "ok" from a Lambda. Validates the app-template before the chatbot consumes it.
4. Day 4: Chatbot Lambda handler + DDB integration. Streaming proven via curl before the SPA exists. Audit events visible in CloudWatch.
5. Day 5: Chatbot SPA. Thread list + message pane + streaming input. End-to-end demo: the user opens the URL, signs in, types "what's the data governance grid?", watches Claude stream the answer, sees the audit + cost events flow.

Five working days, doc-locked decisions, no surprises. The chatbot exists by end of week; the first 3 SDK packages are written and tested; the app-template is proven by a real consumer.

12. Doctrine

• The first consumer drives the SDK shape. SDK packages specced in a vacuum tend to be wrong in subtle ways. The chatbot is the first consumer; its needs shape the API surface for vibe apps 2 + 3. If the chatbot reveals a bad shape, the SDK changes before vibe app 2 starts.
• Dogfood is the validation. The platform owner is the first user. the platform owner chatting with Claude through the platform is the most rigorous test of the SDK because the platform's owner notices broken shape immediately.
• Doc-first survives. This Step 6.a doc precedes the code. The doctrine is fixed before implementation. Implementation executes the doctrine; it doesn't invent the doctrine. The chatbot is doc-first because the doc IS this file.
• Vacuous contract satisfaction still ships the plumbing. lockbox_only_pii is vacuously satisfied for the chatbot (no PII in the chat). But the PII-shape detector ships anyway, so vibe app 2 inherits tested plumbing instead of building it itself. The SDK matures by serving the easy case first; the hard cases inherit.
• The Console's first delivery proves the substrate's leverage compounds. If the chatbot ships in a week with three SDK packages crystallized as a byproduct, the Console is delivering its promise. If it takes a month and the SDK shape keeps changing, the doctrine has a problem worth fixing before vibe apps 2 + 3.