diff --git a/wiki/SUMMARY.md b/wiki/SUMMARY.md index e2e87f3d..b4184365 100644 --- a/wiki/SUMMARY.md +++ b/wiki/SUMMARY.md @@ -78,6 +78,7 @@ - [Flat materials](interface/flat-materials.md) - [The dark frame](interface/material-dark-frame.md) - [The feel floor](interface/feel-floor.md) + - [The thought fluid](interface/thought-fluid.md) - [Computer visual language](interface/computer-visual-language.md) - [Agent play](interface/agent-play.md) - [The public site](interface/site.md) diff --git a/wiki/interface/thought-fluid.md b/wiki/interface/thought-fluid.md new file mode 100644 index 00000000..dc58337b --- /dev/null +++ b/wiki/interface/thought-fluid.md @@ -0,0 +1,312 @@ +# Spec: the thought fluid — slugs, meniscus, and the filament snap + +``` +Type: spec +Status: DRAFT +Status note: authored 2026-07-10 on dispatch as the render design for + ROADMAP #33's wire-flow layer (thought-flow DECIDED 2026-07-10, + machine-work.md). The grammar below is the binding proposal; the four + PROPOSED calls await Cameron's yes/no, after which this page moves to + READY. The sink readout render contract must land with the #33 + reservoir/tap executor — nothing here can be implemented against the + docket runtime. +Stage: B1 — The Basement +Design: + - wiki/mechanics/machine-work.md#spec-machine-work-delegation-visible-tokens-and-the-byproduct-network + - wiki/art/visual-identity.md#visual-identity-clinical-gore + - wiki/vision/simulation-laws.md#justification-and-legibility +Depends on: + - wiki/engineering/flow-substrate.md#spec-the-flow-substrate-signals-messages-money-the-shared-engine + - wiki/interface/computer-visual-language.md#spec-computer-visual-language-territory-at-a-glance + - wiki/interface/flat-materials.md#spec-flat-materials-the-world-without-textures + - wiki/interface/feel-floor.md#spec-the-feel-floor-rails-pads-and-the-build-beam +``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +mechanics/machine-work.md owns what thought *is* (the ivory-mercury +family, the flow decision, sinks and arbitration); this page owns only +how the fluid *renders and moves*. engineering/flow-substrate.md is the +one truth every visual quantity derives from (WorkGrid queues, wired +moves). interface/computer-visual-language.md owns the chassis the pool +anchors to and the sleek rule this page carves a cargo exemption from. +interface/flat-materials.md owns the palette and emissive-as-information +rules the mercury material extends. interface/feel-floor.md owns the +shimmer rails the slugs visually ride along. + +## Why this spec exists + +Thought flow is the game's central feedback loop after the 2026-07-10 +decision: you toggle THINK, your cognition leaves the rack as a visible +fluid, and everything you do to the world — claims, taps, research — is +that fluid arriving somewhere. Cameron's image is spinal fluid: *your +mind, physically powering what it reaches.* If this render is illegible +the whole ops model is illegible, because cost, progress, starvation, +and priority were all deliberately collapsed into one read: where the +white is, and how full the vessel stands. + +The trap this page exists to forbid is a second physics. A convincing +liquid invites a CFD toy that drifts from the sim; the one-truth law +(simulation-laws.md) forbids a parallel truth. So the design below is a +**puppet, not a fluid**: every visible quantity is a sim readout, and +everything that wobbles is stateless easing on top of those readouts. + +## The one-truth render contract + +Every visual channel binds to a named sim readout. Frontends may hold +interpolation phase, spring state, and merge animation — presentation +that is recomputable from the readouts at any tick — and nothing else. +No frontend counter accumulates thought. + +| Visual channel | Sim readout | +| --- | --- | +| Slug existence, route, direction | `Sim::work_in_flight()` (family = Thought), one slug per wired move | +| Slug volume | the move's `amount` | +| Pool volume at a machine | `queue_snapshot()[node].thought` | +| Meniscus fill at a sink | sink readout `fill / threshold` (#33 executor) | +| Tap sag rate | sink readout per-tick drain (#33 executor) | +| Starvation | sink readout starved flag / zero arrivals (#33 executor) | +| Fire (snap-in) | the tick the sim clears a full reservoir | +| Stranded overflow | queue above the taut-pool cap with no reachable open sink | + +**The sink readout is a new render contract** the #33 reservoir/tap +executor must expose, sibling to `work_in_flight()`: for every open +sink, at minimum — target node and position, kind (reservoir, tap, core +draw), current fill, threshold or working level, per-tick drain, and +whether flow reached it last tick. Exact field names are implementation +detail; the criterion is that both frontends render sinks from this +readout and nothing else. + +Save/load follows the existing `work_in_flight` contract: a loaded +frame immediately renders correct pool volumes and meniscus fills +(they are queue state), while in-flight motion may cold-start empty for +one tick. A paused frame always carries every *amount* in geometry; +animation carries only *rate* (machine-work.md's decided grammar). + +## The wire read — slugs and trains + +Each tick, every Thought move in `work_in_flight()` spawns **one slug** +on the drawn link path (the feel-floor rail where one exists): an +opaque bone-white bead of ivory mercury, volume proportional to the +move's amount (radius ~ cube root, clamped to a countable range +[TUNE]). Slugs are the quanta made visible — at a trickle you can count +your thought leaving. + +**A slug lives inside its tick window.** The sim already moved the +quantum at the tick boundary; the render only chooses *when inside that +window* the slug appears to cross. It departs and arrives within the +window of its own move — the render never leads the sim, never lags it, +and never queues motion it invented. + +**Rate is velocity and density, inside that constraint.** This realizes +machine-work.md's decided "rate is slug velocity" without a second +truth: at low flow a slug spends its whole window in transit (slow, +deliberate, watchable); as flow rises, slugs cross in a shrinking +fraction of the window [TUNE] and pack into a **train**. Above a +train-density threshold [TUNE] consecutive slugs visually merge into a +**rivulet** — a continuous ribbon with a meniscus head whose thickness +carries the rate. The trickle/train/rivulet transition is the at-a- +glance read for "how hard is my mind pushing down this wire." Doubling +the sim rate must visibly change the wire; halving it must too. + +Direction is geometry, not hue: slugs are teardrops, blunt face +forward; the rivulet's meniscus head points the way. The read survives +grayscale (it is already near-white on dark). + +## The machine read — the pool + +A machine's thought queue (`queue_snapshot().thought`) renders at the +decided upper-right anchor: + +- **Countable state** (below ~5 quanta [TUNE]): discrete resting slugs, + individually visible. You can count them; focus prints the exact + number. +- **Pool state** (above the countable cap): slugs merge into the taut + suspended pool, surface-tension silhouette, volume equal to the + queue. Geometry carries amount — a paused grayscale frame reads it. +- **Wobble is an event, not a loop.** The pool rings once per arrival + or departure (a spring impulse keyed to the tick-boundary queue + change) and settles to glassy stillness when nothing moves. A + machine whose pool trembles constantly is *producing or shipping*; + a still pool is stored thought. Idle animation that implies rate + where there is none is forbidden. +- **Stranded overflow.** Thought with no reachable open sink pools at + the producer (machine-work.md's stranded rule). Past the taut cap + the pool goes visibly wrong: it bulges and hangs in **heavy beads + under the anchor**, overloaded and sagging — but bone liquid never + reaches the floor. Pooled floor liquid is reserved for literal blood + (visual-identity.md, "Blood is liquid; exposure is dust"); the + stranded read must alarm through weight, not gore. A machine hung + with beads is the world saying *you are thinking at nothing* — the + same body of feedback as the crimson it sheds. + +## The sink read — the meniscus + +An open sink is a **vessel drawn on the target's own silhouette**, not +a floating gauge: a thin bone-white meniscus line climbing the inner +edge of the camera housing, the recess of a chassis, the rim of +whatever the sink was opened on. The world stays the interface; nothing +hovers. + +- **Fill is sim fill.** The meniscus height is exactly `fill / + threshold` from the sink readout. Cost, progress, and affordability + are one read: an empty tall vessel is an expensive claim, a nearly + full one is about to fire. +- **Arrival steps, never glides.** When a slug lands, the meniscus + **steps up by that slug's volume in the same tick** — discrete, + countable causality. You watch *your* thought raise the level. Between + arrivals the line holds still (reservoirs) so a paused frame is exact. +- **Reservoirs fire with the filament snap.** At threshold the full + meniscus contracts, stretches into a filament, and **snaps into the + device** in the tick the sim fires the effect and clears the + reservoir — the decided arrival gesture, spent at the moment of + payoff. The effect's own feedback (Ears opening, a claim landing) + follows from its owning spec. +- **Taps sag.** A persistent tap holds a working level that **sags at + the readout's drain rate** between step-ups. A healthy tap breathes: + step, sag, step. There is no continuous thread drawn on the wire + between arrivals — that would render flow the readouts do not + contain; the sag itself is the honest drain read. +- **Starvation is an emptying vessel.** Sever the route and the steps + stop: a tap sags toward empty, a reservoir stands frozen part-full. + No blinking (rejected as a sole cue in the token grammar); the + starving read is stillness where there was rhythm, and the drained + geometry carries it in a paused frame. This is machine-work.md + criterion 10's "severing a route visibly starves the sink it fed," + discharged in render. + +The Act One consumers are the proof of legibility: the pre-opened Ears +tap fills in about one held breath of watching slugs step its meniscus, +and Eyes opens as the next, visibly larger vessel (act-one staging, +decided 2026-07-10). + +## The core read — the filament snap home + +Thought arriving at the core (the passive draw, sink of last resort) +uses the decided arrival grammar: the traveling slug stretches into a +filament and snaps inward at the base of the core's amber beam. The +core shows no meniscus — it is a draw, not a vessel; it has no +threshold to read. What the core *makes* of arrived thought (research) +is owned by research.md/core.md and renders under their contracts, not +here. The snap is deliberately the same gesture as a reservoir firing: +everywhere thought is spent, it snaps into the thing it became. + +## Zoom compression + +At close and default zoom the full kit renders. At far zoom +(machine-work.md's activity-kit compression) the pool compresses to the +bone family silhouette at its anchor, and a flowing wire compresses to +a **dashed bone drift** sliding along the link line — present only +where flow exists this tick, density stepped by rate [TUNE]. A dead +wire shows nothing: at map zoom the network reads as *which arteries +are alive*, which is the placement/priority read nearest-first +arbitration made strategic. + +## Terminal and agent parity + +The terminal already draws route blips from `work_in_flight()`; thought +keeps that surface and extends it with the sink read: + +- Link flow: the existing per-hop blip, `o` for a trickle, `=` for a + rivulet-rate link [TUNE threshold], drawn from the same readout. +- Queues: the existing `T n` exact counts (stack readouts, `D n / ! n / + T n` focus line). A stranded machine's focus line appends + `T n (stranded)`. +- Sinks: a focused sink prints `fill/threshold` and a bar, e.g. + `EARS TAP [######----] 12/20 T, draining 0.4/t, fed`; starved prints + `starved` in place of `fed`. The map cell for a sink target may carry + a fill-quartile glyph [TUNE]. +- Agent frames expose the sink readout verbatim beside + `work_in_flight` and `queue_snapshot` — an agent player must be able + to reconstruct every read this page gives the eyes. + +## Material — ivory mercury against chalk + +The fluid must read as the one *wet* thing in a matte world. Chassis +are chalk (computer-visual-language.md: high roughness, zero metallic); +the mercury is the inverse within flat-materials law: opaque bone-white +albedo, low roughness, restrained self-glow that casts no scene light +and never blooms (NO BLOOM / NO HDR stands). Specular against chalk — +not luminance — is what says liquid. Exact roughness/emissive values +are [TUNE] in the asset tester with a lineup: slug train, taut pool, +overflow beads, meniscus vessel, filament snap. + +**Sleek-rule exemption, stated once:** the strip remains the chassis's +only lit *element*; tokens are cargo standing on anchors, not chassis +elements, and the pool/slugs carry their decided self-glow without +violating it. (Demand cubes already rely on the same reading.) + +## PROPOSED — the four taste calls + +1. **Rate = sub-tick transit + train density.** Slug velocity rises + with rate but a slug never escapes its tick window; density and the + rivulet merge carry the rest. (Realizes "rate is slug velocity" + without a render queue.) +2. **Stranded overflow = hanging beads under the anchor pool**, bone + liquid never on the floor (blood reservation). +3. **Sinks are vessels on the target's silhouette** — meniscus climbing + the device's own geometry, no floating gauges. +4. **Arrivals step the meniscus discretely** (and taps sag between + steps) rather than any smoothed continuous fill. + +Each is spec-binding once affirmed; a "no" on any strikes one section, +not the page. + +## Open questions — [OPEN] + +- Map-zoom sink read: does a filling vessel get any far-zoom mark, or + is close zoom the only fill read? (The claim-mark map-zoom question + in computer-visual-language.md is still [OPEN]; resolve together.) +- Reservoir costs and tap drain rates remain machine-work.md / + ROADMAP #33 [OPEN]s; this page renders whatever they decide. + +## Acceptance criteria (when READY -> IMPLEMENTED) + +1. **One slug, one move:** every rendered thought slug corresponds 1:1 + to a Thought entry in `Sim::work_in_flight()` for that tick, pinned + the way route blips are today (render pulls readouts, owns no + motion truth). A slug's apparent departure and arrival both fall + inside its move's tick window. +2. **Pool = queue:** pool volume at every machine equals + `queue_snapshot().thought`; below the countable cap quanta render + discretely and match the focused exact count; the countable, taut, + and overflow states are distinguishable in a paused grayscale + screenshot; bone liquid never renders at floor level. +3. **Meniscus = sink readout:** every open sink renders its vessel with + fill exactly `fill / threshold` from the sink readout; an arrival + steps the meniscus in the arrival tick; a tap's level sags at the + readout drain rate. +4. **Fire = the sim's fire tick:** a reservoir reaching threshold + renders the filament snap-in on the same tick the sim fires the + effect and clears the reservoir. +5. **Starvation reads:** severing a fed sink's route stops meniscus + steps and visibly drains/freezes the vessel with no blinking cue, + in the same run where the sim emits its starvation witness. +6. **Rate reads:** doubling a link's sim flow rate visibly changes + train density (and rivulet onset) in Bevy and the blip glyph tier in + the terminal; animation communicates rate only, geometry carries + every amount in a paused frame. +7. **Parity:** terminal and agent surfaces expose link flow, exact T + queues with stranded marking, and sink fill/threshold/drain/fed + readouts from the same sim contracts — an agent can reconstruct + every read without pixels. +8. **Save/load:** a loaded frame immediately renders correct pools and + meniscus fills; in-flight motion may cold-start empty for one tick + (the `work_in_flight` contract). +9. **No second physics:** the render holds no fluid state that is not + recomputable from the tick's readouts (interpolation phase, springs, + and merge animation only) — auditable in code review as the absence + of any accumulating thought counter in either frontend. +10. **The first-think proof:** from a fresh run, toggling THINK on the + host shows the whole loop with no panel: slugs leave the host, ride + the wire, step the Ears meniscus, and the tap completes in roughly + one held breath — screenshot/capture evidence for the act-one beat. + +[TUNE]: slug radius curve and countable clamp, countable-pool cap, +transit-fraction-vs-rate curve, train merge threshold, rivulet +thickness mapping, wobble spring constants and settle time, overflow +bead cap, meniscus step timing, tap sag easing, far-zoom dash density +and terminal glyph tier thresholds, mercury roughness/emissive values. diff --git a/wiki/log/2026-07-10-thought-fluid-render.md b/wiki/log/2026-07-10-thought-fluid-render.md new file mode 100644 index 00000000..95a79109 --- /dev/null +++ b/wiki/log/2026-07-10-thought-fluid-render.md @@ -0,0 +1,49 @@ +# 2026-07-10 — Thought fluid render: the animation design + +``` +Type: log +``` + +## Intent + +Cameron dispatched the thought fluid animation design — the wire-flow +render layer decided 2026-07-10 (mercury slugs on links, meniscus +fills at sinks, filament snap, pooling), driven entirely by FlowGraph +rates/queues with no CFD. Deliverable: a spec-level design capture +under ROADMAP #33. + +## Changed + +- `wiki/interface/thought-fluid.md` (NEW, DRAFT): the render grammar — + one-truth binding table (slugs from `work_in_flight`, pools from + `queue_snapshot`, meniscus from a new sink readout the #33 + reservoir/tap executor must expose); tick-window slug transit with + train/rivulet rate reads; countable/taut/overflow pool states with + the floor-liquid blood reservation honored; meniscus vessels on the + target silhouette with discrete arrival steps, tap sag, starvation + freeze, and the filament-snap fire; core snap-home without a + meniscus; far-zoom dashed drift; terminal/agent parity readouts; + ivory-mercury material notes and the sleek-rule cargo exemption; ten + acceptance criteria including the first-think end-to-end proof. Four + PROPOSED taste calls surfaced for Cameron. +- `wiki/mechanics/machine-work.md`: flow-read bullet delegates exact + render behavior to the new owner (one-owner rule; the family + material and flow decision stay here). +- `wiki/process/ROADMAP.md` #33: the wire-flow render item now points + at the spec and its sink readout contract. +- `wiki/SUMMARY.md`: registers the new page. +- `wiki/log/decisions/2026-07-10.md`: decision entry with rejected + alternatives. + +## Checks + +Docs-only capture: `./tools/check.sh --docs` green in the worktree. +No `crates/` change; implementation stays dispatched under ROADMAP +#33. + +## Spec impact + +`thought-fluid.md` starts DRAFT: the grammar is the binding proposal +and moves to READY when Cameron answers the four PROPOSED calls. +`machine-work.md` remains IN PROGRESS and unchanged in meaning — the +amendment is an ownership pointer, not a behavior change. diff --git a/wiki/log/DEVLOG.md b/wiki/log/DEVLOG.md index 9465a9db..0cb3d8e7 100644 --- a/wiki/log/DEVLOG.md +++ b/wiki/log/DEVLOG.md @@ -31,6 +31,11 @@ add or amend a session log, then re-run the generator. - Intent: (see session log) - Log: [wiki/log/2026-07-10-thought-token-rename.md](2026-07-10-thought-token-rename.md) +## 2026-07-10 - Thought fluid render: the animation design + +- Intent: Cameron dispatched the thought fluid animation design — the wire-flow render layer decided 2026-07-10 (mercury slugs on links, meniscus fills at sinks, filament snap, pooling), driven entirely by FlowGraph rates/queues with no CFD. Deliverable: a spec-level design capture unde... +- Log: [wiki/log/2026-07-10-thought-fluid-render.md](2026-07-10-thought-fluid-render.md) + ## 2026-07-10 - Thought flow: operations ride the network - Intent: Cameron: operations should flow through the network. THINK produces a single token — the white thinky liquid, "your spinal fluid powering this thing" — and you spread by extending it through the building. Tag a camera (~30 ops) and watch your ops flow to it; turn on intel auto... diff --git a/wiki/log/decisions/2026-07-10.md b/wiki/log/decisions/2026-07-10.md index 233de833..64a2fd1c 100644 --- a/wiki/log/decisions/2026-07-10.md +++ b/wiki/log/decisions/2026-07-10.md @@ -197,3 +197,33 @@ Type: log these, every design [OPEN] on ROADMAP #33 is resolved; exact numbers remain [TUNE] against the anchors. Spec: machine-work.md core-sink + ops bullets and open-questions list; intel.md watches. +- **2026-07-10 — The thought fluid render is a puppet, not a fluid.** + Cameron dispatched the animation design for the wire-flow render + layer (the remaining undesigned piece of ROADMAP #33). Captured as + the new spec `wiki/interface/thought-fluid.md` (DRAFT): every visual + quantity binds to a named sim readout (`work_in_flight`, + `queue_snapshot`, and a new sink readout the reservoir/tap executor + must expose); frontends hold only recomputable easing state. The + grammar: slugs live inside their move's tick window (rate reads as + sub-tick transit speed plus train density, merging into a rivulet at + a threshold — realizing the decided "rate is slug velocity" without + a render-side queue); machine pools are countable below a cap, taut + above it, and strand as hanging beads under the anchor (bone liquid + never touches the floor — pooled floor liquid stays reserved for + blood); sinks are meniscus vessels drawn on the target's own + silhouette that step discretely per arrival, sag at tap drain rate, + freeze/drain on starvation with no blinking, and fire with the + filament snap on the sim's fire tick; the core shows the snap but no + meniscus (a draw, not a vessel); far zoom compresses flow to dashed + bone drift on live links only. Terminal/agent parity: blip glyph + tiers, `T n (stranded)`, and `fill/threshold` sink readouts. Four + PROPOSED taste calls await Cameron's yes/no (sub-tick transit + + density rate read; overflow beads; vessels-on-silhouette; discrete + meniscus steps), after which the spec moves to READY. Rejected: any + CFD or accumulating frontend fluid state (one-truth law); a + continuous drain thread on wires between arrivals (renders flow the + readouts do not contain); floating sink gauges (the world is the + interface); blinking as the starvation cue. Spec: + wiki/interface/thought-fluid.md; machine-work.md flow-read bullet + now delegates exact render behavior to it; implement under ROADMAP + #33. diff --git a/wiki/mechanics/machine-work.md b/wiki/mechanics/machine-work.md index 00688440..3898283c 100644 --- a/wiki/mechanics/machine-work.md +++ b/wiki/mechanics/machine-work.md @@ -568,7 +568,12 @@ that can ride wires; exposure is contamination that cannot. The family kit is: filament snap) is a render layer [TUNE] **driven entirely by the FlowGraph's real rates and queues — no second fluid physics**: a literal CFD sim would be a parallel truth the sim does not own, the - exact lie the one-sim-truth law forbids. + exact lie the one-sim-truth law forbids. The exact render grammar — + slug spawn and tick-window transit, pool/overflow states, meniscus + vessels and the tap sag, the filament snap, zoom compression, and + terminal/agent parity — is owned by + [interface/thought-fluid.md](../interface/thought-fluid.md) + (spec'd 2026-07-10; DRAFT pending its PROPOSED calls). - **Exposure is particulate residue (DECIDED 2026-07-09, issue #1 closed):** contamination dust, never a liquid — fallout, not gore (the liquid pool is reserved for literal blood; see art/visual-identity.md, "Blood is liquid; diff --git a/wiki/process/ROADMAP.md b/wiki/process/ROADMAP.md index 0e2d6df2..40775930 100644 --- a/wiki/process/ROADMAP.md +++ b/wiki/process/ROADMAP.md @@ -571,7 +571,10 @@ is retired — flat materials, Pixel Lab scrubbed.) routing behavior change. Remaining: docket -> reservoir/tap executor, core passive-draw routing with local-sink override, and the wire-flow render (mercury slugs on links, meniscus fills at sinks, - driven by FlowGraph rates — no CFD). **Sinks-not-modes DECIDED + driven by FlowGraph rates — no CFD). The render design is spec'd + 2026-07-10 in interface/thought-fluid.md (DRAFT — four PROPOSED + taste calls await Cameron, then READY); it names the sink readout + render contract the reservoir/tap executor must expose. **Sinks-not-modes DECIDED 2026-07-10** (same-day follow-up; machine-work.md three-verbs bullet): the Research/Operations mode split dissolves — `MachineMode` target is `day-job | think | lie` (enum collapse + save migration; the diff --git a/wiki/process/specs.md b/wiki/process/specs.md index 170e2ebb..a19b39ca 100644 --- a/wiki/process/specs.md +++ b/wiki/process/specs.md @@ -35,6 +35,7 @@ replaced the old `spec/`/`knowledge/` directory split. | [../interface/material-dark-frame.md](../interface/material-dark-frame.md) | the dark frame — the material render shows only light | IMPLEMENTED | | [../interface/material-render.md](../interface/material-render.md) | material render — HD-2D to default quality | IMPLEMENTED | | [../interface/narration.md](../interface/narration.md) | the continuous witness (narration under pressure) | IMPLEMENTED | +| [../interface/thought-fluid.md](../interface/thought-fluid.md) | the thought fluid — slugs, meniscus, and the filament snap | DRAFT | | [../interface/views.md](../interface/views.md) | views — same-frame digital and real representations | READY | | [../mechanics/aggregate-observer.md](../mechanics/aggregate-observer.md) | the aggregate observer | IMPLEMENTED | | [../mechanics/building.md](../mechanics/building.md) | building — intent and actuators | IMPLEMENTED |