Smart-Flow Phase 01: Contracts and Vocabulary

Purpose

Introduce the domain vocabulary and contracts that distinguish observations, evidence clusters, hypotheses, confidence, abstention, and user-facing insight projections.

Why this phase comes now

The current system has useful infrastructure but overconfident domain names. Before changing classifier behavior, the codebase needs the language to express what is observed, what is inferred, what is uncertain, and when the system should abstain.

Dependencies on earlier phases

islandflow-259.1 - Synthetic deterministic spine, so contract work can align with canonical raw event and provenance assumptions.

Likely files/modules touched

packages/types/src/events.ts
Shared type exports in packages/types/
Compatibility type aliases where legacy names are still needed
Storage schema planning docs or migration notes
Tests for schema parsing or event compatibility

In-scope work

Define or prepare contracts for FlowEvidenceCluster, FlowCandidate, FlowHypothesisEvent, SmartFlowInsight, EvidenceQuality, BaselineSnapshot, and version fields.
Mark legacy "smart money" naming as compatibility or projection language, not canonical truth.
Define how facts, evidence, hypotheses, scores, confidence, and abstention differ.
Preserve compatibility aliases for existing API/UI paths where necessary.
Add concise migration notes for future phases.

Explicitly out-of-scope work

Rewriting classifier scoring.
Moving ingest policy.
Adding new API endpoints or UI drawers.
Building replay golden suites.
Historical calibration or research-grade model fitting.

Acceptance criteria

Contracts distinguish observations, evidence, hypotheses, insight projections, confidence, alternatives, and abstention.
Legacy naming remains only where compatibility requires it.
Version fields are included for policy/model evolution.
Future phases can refer to these contracts without redefining the vocabulary.
Migration risk and compatibility aliases are documented.

Test strategy

Use type-level checks and schema/serialization tests where practical. Add compatibility tests only for public contracts that must remain stable. Avoid broad behavior tests until evidence extraction and scoring phases exist.

Risks / design traps

Renaming everything without compatibility will break consumers.
Keeping "smart money" as canonical language will preserve the old overconfidence.
Mixing facts and hypotheses in one event shape will make replay evaluation weaker.
Adding too many future fields can make contracts noisy before behavior exists.

Suggested future Codex implementation prompt

Implement docs/implementation/smart-money/01-contracts-vocabulary.md for Beads issue islandflow-zxh.1. Focus on contracts, vocabulary, version fields, and compatibility aliases only. Do not rewrite scoring, API/UI explainability, replay tests, or calibration.

Matching Beads issue title/id

islandflow-zxh.1 - Smart-flow phase 01: contracts and vocabulary

3 KiB Raw Blame History