# Phase 01 — Event enrichment dataflow contract ## 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, resolve every role in `requires_roles` to `06-contracts/.md`, write `.buildprint/phase-runs//team-gates.md`, write bounded handoffs for every required role, use subagents/delegated workers when available or self-simulate when unavailable, write return artifacts for every required role, implement the first real vertical path, review architecture/UX/QA, verify, write proof, and record evidence. You may not append evidence or mark this phase passed until the phase-flow required artifacts exist. requires_roles: - product-architect - data-persistence - test-and-verification ## Capability outcome Define and prove the event enrichment dataflow: input schema, transform semantics, output schema, audit-note, reload/repeatability, and quality-note proof. ## Phase mode contract - blueprint_mode: data-pipeline - phase_style: dataflow_contract - Lens: this phase defines the dataflow contract — input datasets/schemas, transform semantics, output artifacts, audit-note, reload/repeatability, and quality proof. - Shared proof spine: - Preconditions/inputs: raw events in `events` table with id, type, payload, created_at. - Entrypoint/use site: pipeline runner reads input schema and executes the transform. - Execution behavior: validate input schema, apply enrichment transform, write to `enriched_events`, record audit-note row. - State/artifact effects: `enriched_events` table, audit-note record, quality assertion results. - Observable proof: schema validation test, transform proof with sample data, audit-note assertion, quality-note check. - Failure/recovery: invalid schema, missing fields, duplicate repeatability key, quality threshold failure. - Non-goals: serving API, UI, ML training. ## Mapped capability obligations - Input schema: events(id, type, payload, created_at). - Transform: enrich `type` with category lookup; add `enriched_at` timestamp. - Output schema: enriched_events(id, type, category, payload, created_at, enriched_at). - audit-note: append one audit-note row per run recording source version, transform version, row counts. - reload/repeatability: re-running the same run_id is repeatable; duplicate rows deduplicated. - quality-note: row count matches input; no null category for known types. ## Behavior compatibility contract - Disposition: preserve dataflow capability; transform implementation may differ. - Equivalent target behavior: schema validation, transform, output schema, audit-note, reload/repeatability, quality-note. - Compatibility impact: mapped schema names are evidence, not mandatory column parity. ## Implementation scope 1. Implement schema validation for input events. 2. Apply enrichment transform with category lookup. 3. Write enriched output and record audit-note row. 4. Add repeatability key and deduplication. 5. Run quality-note assertions and append proof rows. ## Interfaces touched - 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 - Define state and runtime ownership appropriate to this phase's mode. - Use a real seam; do not fake success in any state only. - Runtime artifacts/generated outputs: label explicitly as runtime artifact, not packet file. ## UX/UI requirements This phase is not UI-bearing. Consumer or operator experience proof must include usage examples for empty, error, success, and recovery states. Screenshot critique: critique developer/operator experience against the experience quality contract in `02-project-setup.md`; visual proof is not required for this non-UI phase. ## Safety/security constraints - Define and preserve auth/session/tenant/privacy boundaries appropriate to the mode. - Never expose secrets in logs, UI, screenshots, reports, or evidence rows. - Ask before destructive actions, external writes, paid providers, deployments, or irreversible migrations. ## Quality gates - Run the smallest meaningful typecheck/lint/test/build gate for changed files. - Add or update tests for changed behavior and failure states. - For persistence/provider behavior, prove readback and provider adapter/config/test behavior; record blockers only for unavailable live credentials. ## Proof gate - Proof id: proof-01-event-enrichment - Required proofs: persistence_roundtrip, clean_room_implementation_trace, no_fake_scan_pass, provider_adapter_config_test_required, live_provider_proof_blocker_only, worker_retry_cancel_recovery, migration_retention_backup_upload_limits adapter/config/test wiring exists before claiming live provider proof. Missing credentials block live proof only. - 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` Required runtime evidence row must use `phase_id: 01-event-enrichment` and write to `.buildprint/evidence/evidence-ledger.jsonl`. ## Repair routing If this phase fails verification, return here before editing again. - 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` Do not continue to the next phase if the core path does not persist state, cannot be read back, has unresolved security/destructive ambiguity, or fails tests.