# WaterID Specification — WaterStorage v2 Proposal

Source: Discord feedback, 2026-06-29, proposal #5.

## The case against UUID

UUIDs are location-agnostic but phase-blind. Two UUIDs can be identical-looking but live in completely different hydrological states. UUIDs cannot answer: *what kind of water is this?*

## The case for WaterID

A WaterID encodes **what the water is**, not where it lives.

Format:
```
stream://{domain}/{namespace}/{sequence}
```

Examples from the proposal:
- `stream://thought/planetary/000182`

## Proposed schema (from feedback)

```json
{
  "origin": "local",
  "phase": "lake",
  "temperature": 0.42,
  "confidence": 0.91,
  "lineage": [
    "stream://thought/182"
  ],
  "last_precipitation": "2026-06-29T15:42Z",
  "next_phase": "cloud"
}
```

## Why the routing object is the load-bearing idea

The feedback author's most important observation:

> The object only knows its hydrologic state. That means the underlying implementation can evolve — from local files to databases to object stores — without changing the conceptual model.

This decouples **identity** from **storage substrate**. The same artifact could live in `/home/workspace` today, in S3 tomorrow, in IndexedDB the day after — and never need a migration script, because its identity is its phase trajectory, not its address.

## What this breaks

- **Existing systems assume address identity.** Local file paths, zo.pub URLs, localStorage keys — all are addresses. A WaterID that doesn't resolve to an address is a different kind of thing.
- **Lineage chains create a graph.** `stream://thought/182 → stream://thought/183` is a directed graph of derivations. We don't currently track this.

## What this unlocks

- **Universal merge.** Two artifacts with overlapping lineage merge by phase, not by URL.
- **Conservation by lineage.** Information is conserved if its lineage is conserved, regardless of physical substrate.
- **Climate as ensemble property.** A collection's climate = the distribution of phases and temperatures across its lineage graph.

## Next steps (proposal, not action)

1. Decide: does WaterID replace the file path entirely, or sit alongside it as a metadata field?
2. If alongside: what file gets the routing object? Every file? Just "artifacts"? Just "rooms"?
3. The lineage field implies a DAG. Do we have a place for this graph?

---

*This is a proposal, not an adopted v2. See `README.md` for the full proposal set.*