stuart/databuild
1
1
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions

correct wants docs

Browse source
This commit is contained in:
Stuart Axelbrooke 2025-11-25 14:26:21 +08:00
parent 042526ea8c
commit efed281a5a
1 changed files with 11 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

23
docs/design/wants.md
View file

@ -8,26 +8,25 @@ Wants declare intent to have partitions exist. The graph continuously reconciles
## Want Identity
Wants are idempotent through deterministic ID generation:
Wants use UUID-based identity:
```protobuf
message PartitionWant {
string want_id = 1; // Hash(partition_ref + data_timestamp + source)
string root_want_id = 2; // Original user want
string parent_want_id = 3; // Want that triggered this
PartitionRef partition_ref = 4;
uint64 data_timestamp = 5; // Business time (e.g., "2024-01-01" → midnight UTC)
uint64 ttl_seconds = 6; // From data_timestamp
uint64 sla_seconds = 7; // From data_timestamp
WantSource source = 8;
message WantCreateEventV1 {
string want_id = 1; // UUID generated at creation time
repeated PartitionRef partitions = 2; // Partitions this want requests
uint64 data_timestamp = 3; // Business time (e.g., "2024-01-01" → midnight UTC)
uint64 ttl_seconds = 4; // From data_timestamp
uint64 sla_seconds = 5; // From data_timestamp
EventSource source = 6; // Origin: job, API, CLI, web app...
optional string comment = 7;
}
```
Multiple identical want requests produce the same `want_id`, preventing duplication.
Want IDs are UUIDs generated at creation time. Duplicate prevention is handled at the scheduling layer: the orchestrator checks canonical partition state before scheduling jobs, so multiple wants for the same partition simply observe the same build progress rather than triggering redundant work.
## Execution Flow
1. **Want Registration**: User/trigger creates wants with deterministic IDs
1. **Want Registration**: User/trigger creates wants (UUIDs assigned at creation)
2. **Immediate Dispatch**: Graph attempts execution without checking dependencies
3. **Runtime Discovery**: Jobs fail with `MissingDependenciesError(partitions)`
4. **Want Propagation**: Graph creates upstream wants from missing dependencies