---
id: FLUID-WP-0002
type: workplan
title: "FLUID foundations and the wire contract"
domain: infotech
repo: fluid-core
status: active
owner: worsch
topic_slug: fluid-core
created: "2026-09-04"
updated: "2026-09-04"
planning_priority: high
planning_order: 1
related_repos:
  - fluid-telegram
  - fluid-x
  - fluid-substack
---

# FLUID-WP-0002 - Foundations and the wire contract

Establish the boundary before any code depends on it. fluid-core integrates
out of process, so its contract is a set of on-the-wire artifacts, not a Go
API. Everything downstream assumes these schemas are stable.

Reference: `spec/FluidHypothesisRevisionSchema.md`, `spec/ArchitectureBlueprint.md`
§36 (revision descriptor), §17 (routing policy), §44 (control APIs).

## T01 - Repository scaffold and INTENT

```task
id: FLUID-WP-0002-T01
status: done
priority: high
```

Go module, directory tree per the plan, `INTENT.md` declaring the wire-contract
boundary and the four invariants this repo defends hardest.

## T02 - Record schemas

```task
id: FLUID-WP-0002-T02
status: todo
priority: high
```

JSON Schema for `fluid_pressure`, `fluid_hypothesis`, `fluid_revision`,
`fluid_experiment`, `fluid_event`, `fluid_backend_requirement` and the feedback
record. Transcribe field names faithfully from the schema document — they are
the interop surface, per its §1.

## T03 - Descriptor and policy schemas

```task
id: FLUID-WP-0002-T03
status: todo
priority: high
```

JSON Schema for the revision descriptor (Blueprint §36) and the routing policy
(Blueprint §17). These two are what the gateway consumes at runtime and must be
readable without any fluid-core code.

## T04 - Type generation

```task
id: FLUID-WP-0002-T04
status: todo
priority: high
```

Generate Go types into `internal/contract/` from `schemas/`. Hand-written record
types are prohibited — drift between spec and implementation must fail CI.

## T05 - Spec examples as fixtures

```task
id: FLUID-WP-0002-T05
status: todo
priority: high
```

Extract the YAML examples embedded in the spec documents and validate them
against the schemas in CI. If the spec changes and the schema does not, the
build breaks.

## T06 - Build, CI and identifier conventions

```task
id: FLUID-WP-0002-T06
status: todo
priority: medium
```

Makefile, GitHub Actions (build, vet, test, schema validation), and the
identifier prefix helpers from schema doc §16: `H- R- E- P- BR- D- EV- F- C-`.

## T07 - Architecture decision records

```task
id: FLUID-WP-0002-T07
status: todo
priority: medium
```

ADRs for: Go as the implementation language; out-of-process attachment; the
wire contract as boundary; SQLite to Postgres evidence store; and the revision
identity scheme, which Blueprint §54 leaves deliberately open.