# Phase 01 - Micro Chat Runtime

## How to implement this phase

Before writing code, read:

- `03-phases/phase-flow.md`
- `.buildprint/next-agent.md`
- current project `AGENTS.md`

Then execute this phase through `03-phases/phase-flow.md`: declare the phase objective, write compact runtime artifact `.buildprint/phase-runs/<phase-id>/team-gates.md`, implement the first real vertical path, review architecture/UX/QA, verify, write proof, and record evidence. Create handoff/return files only when real delegation happens.

You may not append evidence or mark this phase passed until the phase-flow required artifacts exist.

Fast-eval constraint: this packet is intentionally tiny. Do not build a CLI, HTTP server, frontend, worker daemon, Docker setup, or package-install path. Prove the phase with dependency-free Node.js modules plus one proof/test command, then write the runtime evidence ledger immediately after that proof command passes.

requires_roles:
  - product-architect
  - integration-runtime
  - data-persistence
  - security-boundary
  - test-and-verification

## Product outcome

Implement one tiny AI chat runtime slice: accept a prompt, route it through a provider adapter, persist the conversation durably, expose readback, and report unavailable live-provider proof honestly.

## Source evidence

Source surface IDs: SRC-AI-MICRO-001.

Product obligations: provider seam, deterministic no-network fallback, persisted conversation readback, negative provider/persistence paths, and evidence honesty.

Source evidence refs:
- eval-fixture/micro-ai-chat describes a local-first AI chat runtime with provider adapter, persistence, and no live-provider claim without runtime proof.

This packet is source-independent: use these observations to preserve product behavior, not to depend on a source repository at implementation time.

## Source surface dispositions

- Surface id: SRC-AI-MICRO-001 chat runtime.
  - Disposition: preserve capability, target route/function names may differ.
  - Equivalent target behavior: prompt -> provider adapter -> assistant response -> durable conversation -> readback.
  - Compatibility impact: implementation names may differ; this is not route/function parity.

## Implementation scope

1. Implement a minimal dependency-free Node.js chat module and proof script. Do not use Python or install packages.
2. Implement provider adapter/config/test seams before any live-proof blocker.
3. Implement durable local persistence and readback.
4. Add negative tests for missing prompt, provider failure, malformed provider response, and persistence failure.
5. Append proof or blocker rows to `.buildprint/evidence/evidence-ledger.jsonl` using `phase_id: 01-micro-chat-runtime` immediately after the proof command passes. Do not defer ledger writing until final summary.

Inputs: user prompt, optional conversation id, provider mode.

Outputs/downstream handoff: persisted conversation id, assistant response, provider-mode disclosure, error state.

## Interfaces touched

- API/routes/adapters/frontend-backend contracts: identify and implement only those required by this phase.
- Provider/tool contracts: implement provider adapter/config/test seams before live proof; disclose deterministic, sandbox, or live mode where provider behavior is claimed.
- None - reason: only if this phase truly touches no interface boundary.

## State/runtime touched

Production runtime: define worker queue ownership, retry/cancel/failure recovery, progress persistence, restart behavior, and health/observability hooks when this phase touches async or runtime behavior.

Data lifecycle: define migrations, retention/delete/export, backup/readback, upload limits, object/file storage, and sensitive data handling when this phase touches durable state or uploads.

Stable obligations:
- Provider behavior must come through a seam, not inline static text.
- Persistence must survive readback from a separate operation.
- Missing live provider must become a non-upgrading blocker, not a reason to omit provider wiring.

Free choices:
- Node.js module layout and command names may vary if proof gates pass. Python and package-install-based runtimes are out of scope for this micro eval.
- Keep file count minimal. A small provider module, store module, runtime module, proof/test script, no-fake scan, and required `.buildprint/phase-runs` artifacts are enough.

Boundary requirements:
Provider-backed behavior must disclose deterministic-test-double, sandbox live, or production live mode. Secrets must remain in environment variables or secret stores and must never appear in logs, screenshots, reports, or ledger entries.

## UX/UI requirements

This micro phase may be API-only. If no UI is implemented, explicitly record UI/browser proof as a non-upgrading blocker or not-applicable review note. If UI is implemented, proof must include repeatable browser/e2e coverage plus screenshot or DOM evidence for empty, loading, error, blocked, and success states.

## Safety/security constraints

- Define local session ownership for persisted conversations.
- Never expose secrets in logs, UI, screenshots, reports, or evidence rows.
- Ask before external writes, paid providers, deployments, or irreversible migrations.
- Stop rather than claim live provider/runtime behavior from deterministic adapters; live credentials block live proof only after adapter/config/test/runtime wiring exists.
- Stop on failed core local runtime/API proof, missing provider seam, or missing persistence readback. Missing live-provider, browser/e2e, screenshot, deployment, or external-service proof limits claim qualification; record a non-upgrading blocker with blocks_continuation: false and continue if the core phase path is implemented and locally proven.

## Quality gates

- Run the smallest meaningful dependency-free Node test/build gate for changed files.
- Add tests for provider success/failure, persistence readback, and validation failure.
- Run or create a no-fake scan.
- For UI-facing behavior, provide repeatable browser/e2e proof plus screenshot or DOM evidence, or an honest blocker for unavailable browser tooling.

## Proof gate

- Proof id: proof-01-micro-chat-runtime
- Required proof tracks:
  - unit_or_integration_test
  - negative_test
  - browser_trace_or_runtime_trace
  - persistence_roundtrip
  - evidence_ledger_entry
  - provider_adapter_config_test_required
  - live_provider_proof_blocker_only
  - worker_retry_cancel_recovery
  - repeatable_browser_e2e
  - security_boundary_review
  - clean_room_implementation_trace
  - no_fake_scan_pass
Do not copy all proof tracks into one evidence row. Each runtime row must list only the proof labels backed by its commands and artifacts. Browser/e2e/screenshot, worker, security, and live-provider claims require separate matching proof rows or non-upgrading blocker rows.

Live credentials, paid services, or external deployment approval may block live proof only after adapter/config/test/runtime wiring exists. Do not satisfy this phase with deterministic-only providers, screenshots-only UI proof, in-memory-only state, route-shaped handlers, or local MVP shortcuts.

- Negative tests: missing prompt, provider failure, malformed provider response, persistence failure, and phase safety/security constraints.
- Runtime evidence ledger: `.buildprint/evidence/evidence-ledger.jsonl` in the implementation workspace
- Immutable evidence seed: `05-evidence/evidence-ledger.jsonl`
- Claim rules: `04-evaluation.md`
- Evidence schema: `05-evidence/evidence-ledger.schema.json`

Required runtime evidence row must use `phase_id: 01-micro-chat-runtime` and write to `.buildprint/evidence/evidence-ledger.jsonl`.

Evidence timing requirement: write the ledger directly after the local runtime/proof command passes, before optional cleanup, optional docs, or final response. A replay that proves behavior but times out before the ledger is still a failed replay.

## Repair routing

If this phase fails verification, return here before editing again. Re-read product outcome, implementation scope, interfaces touched, state/runtime touched, UX/UI requirements, safety/security constraints, and proof gate.

- test/build/runtime/UI/proof failure -> current phase
- architecture contradiction -> `02-project-setup.md`
- missing human preference that affects product identity/cost/secrets/destructive action -> `01-questions.md`
- missing dependency -> required prior phase from `03-phases/phase-index.yaml`
- external blocker -> `.buildprint/evidence/evidence-ledger.jsonl`