Block A · What a tool call costs the turn

What a call costs the turn

The caller is an agent in a terminal, and the measure for everything in this block is that it gets a call right on the first attempt, and answers a failure, without opening an implementation file. Where a rule does not serve that, the rule is wrong.

Slow calls return a handle

Anything expected to exceed roughly two seconds is asynchronous: a bake, a fetch, a capture and a search. start gives a job, poll gives a stage from a short fixed vocabulary, result blocks only if asked to, and cancel actually stops paying. State is a file under .polyweave/jobs/, so a handle outlives the session that made it, and a poll that finds no live process and no result returns job.worker-gone rather than hanging.

Concurrency belongs to the caller

Four handles is four parallel samples, bounded by one number in the project config. Nothing in the plugin decides how much of your machine a search may use.

Every operation asserts its own output

  • ◆A mesh: at least one face, finite bounds, and no NaN in any vertex.
  • ◆A boolean: a face count that is not zero where both operands had faces.
  • ◆A render: not a single uniform colour, not fully transparent, and the dimensions that were asked for.
  • ◆A download: a byte length matching the declared one, with the sha256 recorded.
  • ◆Expensive assertions — a manifold check on a dense mesh — are opt-in and off by default. The cheap ones above always run, because the alternative is what cost the render that put this block on the roadmap.

Nothing outside the project tree

Working state goes in .polyweave/, which belongs in .gitignore. A cache in a home directory is state a repository cannot review and a colleague cannot reproduce.

The block itself

Six open lines, in the roadmap's own words

Each line names the failure it exists to remove and the measurement behind it. None of them has shipped. This list is generated from docs/ROADMAP.md, so it cannot describe a backlog the file does not have.

📋PW1an operation that takes minutes holds the turn, and nothing reports progress until it endsA two-minute bake and a ten-minute fetch are both dead time a session cannot spend elsewhere, and a timeout returns no evidence of how far it got.
📋PW2a tool reports success on an empty result, so the failure is found a render laterBlender's EXACT boolean returns an empty mesh with no error when its target was bevelled, and that silence cost a full render to locate.
📋PW3a tool's parameters are learned by reading the source that implements themCottony's rig has fourteen fields documented only as comments in a thousand-line module, so every caller pays a file read to find out what it may set.
📋PW4a failure arrives as a stack trace, so the fix is guessed from the frame that raised itA traceback names where the code gave up and not what the caller should do instead, which is the one thing needed to retry without another round trip.
📋PW5paths, palette and rig defaults are written into the tool, so a second project cannot run itCottony's tools resolve their own repository root and import a palette module beside them, so nothing in them is reachable from a project that is not Cottony.
📋PW6the renderer's version is not recorded, so a render that moved cannot be told from a changeA bake is not byte-reproducible, and without the library versions and the seed beside the output there is no way to attribute a difference to anything.
The other blocks

What this one sits next to

B

Seeing the result cheaply

A surface is read on a sphere in three seconds, a render returns its measurements in the same answer, a distribution is reported as a set rather than a mean, and a sheet shows an asset beside its siblings.

5 lines
C

The asset compiler

What counts as a correct render, written as a file a search can aim at; a search that finds the rig numbers instead of a person finding them by hand; a cache so nothing renders twice; and a trace of everything the search rejected.

4 lines
D

Fetching without surprise

A silhouette gate before the credit moves, a ceiling agreed once instead of a question per fetch, the mesh kept because the service deletes it at seventy-two hours, and a fetched asset normalised into this project's axes.

6 lines
E

One world with the engine

A Godot run judged by what the script printed rather than by an exit code that means nothing, a capture that works where there is no screen, a scale derived instead of tuned, and a runner pinned so two machines agree.

4 lines
F

Motion

A fetched mesh rigged so it can be posed at all, motion as a clip rather than a second static render, curves as text a diff can show, and one source for both a 2D sprite and a 3D scene.

4 lines
G

Geometry as a declaration

A shape stated as data rather than written as a program: a vocabulary read off real assets, numbers a search can reach, a review before anything is built, and a way back to code for the shape no format can state.

5 lines