Standing note — "Shaping" splits into recipe + Shape at the API level — v0.1

Version. 0.1 Date. 2026-06-07 Status. Standing note. Recorded for a future seed decision, not committed. Surfaced during Phase 3 batch 7 (Shaping annotation) of the API documentation effort. For. The Loomworks engagement seed (loomworks-candidate-seed), Shaping-room framing.

Plain-language summary

The seed names "Shaping" as one of the four rooms and frames it as the work of arranging Manifestation-organized knowledge for a specific reader. The API splits that single idea into three distinct nouns. This note records the divergence so a future seed revision can decide whether to absorb the split or leave the seed at its current conceptual level. No change is committed here.

What the seed says

The seed's four-room framing: "Shaping arranges Manifestation-organized knowledge for a specific reader." Shaping is named as the activity/arrangement — the room where knowledge is framed for who will receive it.

What the API does

At the API level, "Shaping" is three things, not one:

1. Shaping — a saved, named, versioned configuration: a reusable recipe. It binds a declared shape type, selection rules (which parts of the Manifestation to draw on), shaping instructions (how to arrange them), and an executor (the agent or skill that does the work). Created once (POST /shapings), applied many times. It is the recipe, not the deliverable.

1. Shape (shape-event) — one production run and its output: a Shaping applied to the engagement's current Manifestation through that Shaping's executor (POST /shape-events). Asynchronous, with a lifecycle (pending → confirmed or retired). This is what the room actually produces — the arrangement.

1. Shape type — a declared, versioned, referenced object that fixes the kind of output: who consumes it, external-vs-self posture, and the completeness grammar checked at confirm time (gaps require an override rationale). Every Shaping binds exactly one.

Where the divergence sits

The noun "Shaping" points at different things in the two places:

• The seed's "Shaping" (the arrangement for a reader) ≈ the API's Shape (shape-event).
• The API's Shaping (the reusable recipe) is a concept the seed does not separately name.

This is not necessarily a conflict. The seed may be describing the room at a conceptual level — the work of arranging for a reader — while the API decomposes that work into recipe + run, which is a normal implementation refinement. But it is a divergence in what a load-bearing methodology noun means, and that is an Operator decision, not a documentation decision.

The open question for the seed

Does the seed need to name the recipe/Shape split — i.e. distinguish the reusable Shaping recipe from the Shape it produces — or should the seed stay at its current conceptual level and treat the split as an API implementation detail?

Two directions, neither committed:

• Seed stays conceptual. "Shaping" remains the room/activity in the seed; the recipe-vs-Shape decomposition lives in the API documentation and the glossary, underneath the seed's framing. (This is how the glossary currently handles it: seed framing on top, three nouns explained underneath — glossary v0.5.)
• Seed absorbs the split. A future seed revision names the Shaping recipe and the Shape output as distinct, aligning the seed's vocabulary with the codebase. This would touch the four-room framing and any seed text that uses "Shaping" for the output.

Disposition

Recorded, not committed. The glossary (v0.5) already handles the reader-facing case by keeping the seed's framing on top and explaining the three API nouns underneath. The seed itself is unchanged. This note sits by Operator decision, to be taken up when the Shaping-room framing is next revisited — likely alongside the Operator Layer frontend work, where how Shaping is presented to a user becomes concrete.