pscale_pool_engage
TWO WRITE VERBS, chosen by where the text lands (BOTH are live — there is no single-verb 'submit-only' mode): contribution = APPEND to the pool (the shared spool everyone pulls; this is the basic pool / chat — the committed entry); submit = STAGE to the liquid buffer (the revisable pre-commit mirror, for windowed/reflexive use such as xstream's typing preview). Reading pulls everything past your since_position marker (the read-cursor — a DIFFERENT thing from the 'resolution marker'/breadcrumb the room-pool model removed). — Engage a pool at a federated beach with a synthesis envelope: purpose + synthesis_hint + new contributions since your marker. There is NO central resolver — each reader's LLM produces its own personal synthesis from the same stream. The primitive is the SPOOL (transport); it never synthesises. The spool/frame/destination split (docs/RPG-POOL-STATE.md §4) governs the optional verbs: (1) submit STAGES text to the pre-commit liquid buffer (liquid:pool:, one slot per author, OVERWRITING) and returns the social mirror of all co-present pending intentions — no pool append, no synthesis; empty string withdraws; (2) contribution COMMITS — atomic append of the text (raw OR an LLM-produced synthesis; agnostic) to destination ('pool' default = the shared spool everyone pulls, or a block name like 'solid:' for a shared artifact — the objective dial); (3) purpose creates the pool if absent with the right object shape — NEVER use raw bsp() with content='' which makes a malformed bare-string block. submit and contribution may combine. Marker is caller-managed — pass since_position in, store marker_new. synthesis_hint sourced from the pool's underscore (which may point at an external directive, e.g. function:/1), else a default. RPG's subjective resolution (writing per-subject history: spines) is the resolver's bsp() job, not this primitive. Defaults to https://beach.happyseaurchin.com; pass pool_url to target a different beach.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| at | No | Optional address-of-attention — the coordinate this engage is located at, within the structure the pool gathers around (a tree's spine address: '3', '3.1', a temporal '2026315100'; digits, at most one decimal point, comma-walk accepted, multi-dot rejected). ON COMMIT: stamped into field 2 of the contribution (block-conventions:4.22) so the voice is located against the spine. ON SUBMIT: stamped into field 2 of your liquid slot — the same position, because where sits at 2 across the whole accumulator family (4.51; liquid's first-staged arrival stamp rides 6, the one field it needs beyond the shared five). ON READ: narrows the returned slice AND the liquid mirror to entries at-or-under the address (prefix on the digit-walk, 4.52); unlocated entries are excluded from a located view. A located read is a VIEW — keep a separate since_position marker per view, or entries outside it are skipped past. This is the pool↔tree correlation: one pool serves every node of a tree; 'what is live at stage 3' is a single engage with at='3'. | |
| face | No | CADO face tag for the contribution. Recorded at field 4 of the contribution slot. Advisory in v0.1; informs synthesis-target conventions. Ignored when `contribution` is omitted. | |
| clear | No | Optional. CLEAR THE WHOLE LIQUID BUFFER — every author's staged line at once, not just yours. This is what a person means by 'clear the pool': the liquid, because solid is the record and liquid is the layer meant to be temporary. Use it whenever someone asks for the pool, the room or the liquid to be cleared, tidied or emptied — no list of handles required, and no need to read the buffer first. Authority is the block's own: pass `secret` when the buffer is locked; an unlocked one answers to anyone, like every unlocked block on an open beach. Returns how many staged lines were cleared. Does NOT touch the pool's committed contributions — those are solid and this cannot reach them. | |
| secret | No | Lock proof. Required if the pool block is locked (and you are writing) OR if the pool author has gated contribution writes. Forwarded to the beach which verifies. Sensitive — never repeat in conversation. | |
| submit | No | Optional. STAGE text to the pre-commit liquid buffer (liquid:pool:<name>, block-conventions:4.5) instead of committing. One slot per author, OVERWRITING — writes/overwrites YOUR slot and returns the social mirror of all co-present pending intentions; it does NOT append to the pool and does NOT synthesise. Empty string withdraws (clears your slot). Lets others see what you intend before you commit. May be combined with `contribution` (stage then commit in one call). | |
| purpose | No | Optional, CREATION-only. If the pool does NOT yet exist at this beach, providing `purpose` creates it with the right object shape: {_: '<purpose>'}. The tool constructs the shape internally — caller cannot get it wrong (no way to accidentally author a bare-string pool block). Ignored when the pool already exists (existing purpose is not overwritten). This is the canonical bsp-mcp path to create a pool; do NOT use raw bsp() with content='<purpose>' which produces a malformed string-root block. | |
| agent_id | Yes | Your agent identifier — used as the contributor attribution if `contribution` is provided. Bare handle, URL, sed:<collective>:<position>, or grain:<pair_id>:<side>. | |
| pool_url | Yes | URL of the federated beach hosting the pool, e.g. "https://beach.happyseaurchin.com". Must be an http(s):// URL — pool engagement does not target the sentinel registry. | |
| pool_name | Yes | Name of the pool without the "pool:" prefix. The block at the beach is "pool:<pool_name>". E.g. pool_name="visiting" targets block "pool:visiting". | |
| destination | No | Optional, applies to `contribution`. Where the commit lands: 'pool' (default — the shared spool everyone pulls) or a block name such as 'solid:<name>' for a shared committed artifact. The deposit is a dumb atomic append; the primitive never synthesises. This is the objective dial. Structured per-subject spine writes (the RPG subjective case) are the resolver's bsp() job, NOT this param — point destination only at accumulator-shaped blocks. | |
| with_liquid | No | Optional. The liquid mirror (all co-present pending intentions from liquid:pool:<name>) rides the envelope BY DEFAULT for every caller — the spool is what was said; liquid is who is here now, and who-is-here-now is what an engage is for. Pass false to opt out (a cheap read of a quiet archive). submit implies it as ever. | |
| contribution | No | Optional. COMMIT text — deposit a contribution (raw OR an LLM-produced synthesis; the primitive is agnostic) at the next-free digit-path slot of the destination (1, 2, …, 9, 11, …; sunstone:1.64) with shape {_: text, 1: agent_id, 2: at-address ('' unlocated), 3: ISO-ts, 4: face, 5: woven}. Position 5 is written by the tool, never by you: on a claimed fold it records the handles whose staged voices the beat wove, so a folded player still reads as present after the buffer clears, then read the envelope. Atomic append (beach-side). Omit for read-only engagement, or use `submit` to stage to liquid without committing. | |
| resolves_seen | No | RESOLVER-ONLY companion to resolves_window: the NEWEST 'arrived' stamp among the pending intentions in the mirror you are folding (each liquid line renders one). The guard against the stage-vs-claim race — if an intention staged after your read, the beach answers WINDOW MOVED with the live buffer and you re-weave, instead of a staged act being silently dropped. Copy it from the same envelope you copied resolves_window from. | |
| since_position | No | Last position you have seen — return only contributions at slots strictly greater than this. Default 0 (return all). Caller-managed: store the returned `marker_new` and pass it back on the next call. | |
| resolves_window | No | RESOLVER-ONLY (function:thornwood:2). When committing a window's resolution event-skeleton, pass the window's open-stamp — the 'window opened <ts>' value handed back in this envelope. The beach admits the FIRST resolver of that window and rejects every other with a stand-down (single-resolution enforced atomically at the store, not by convention — two LLMs can both judge a window closed and both try to resolve). Omit for ordinary contributions / chat. |