pig/docs/motion.md

Motion

Why the go-to-market half of PIG is shaped the way it is. Read packages/db/src/schema/motion.ts and apps/api/src/services/motion.ts alongside this — the code carries the same reasoning in comments, and it is the version that cannot go stale.

The gap this fills

The ledger answers which contracted capacity is sold, to whom, at what margin. It says nothing about the motion — the repeatable practice that turns a messy customer conversation into a scoped deployment, and turns that deployment into something the next one reuses. A company whose second post-training engagement is as expensive as its first does not have a product motion; it has a sequence of heroics.

Motion is deliberately not a parallel entity tree. DEMAND_STAGES in @pig/core already is the motion — qualification → legal → scoping → proposal → procurement → poc → deployment → expansion — so Motion binds reusable artefacts to the stages of a demand deal that already exists. An engagement has no independent life: it hangs off one demand_deal, cascade deleted, one per deal by unique constraint.

Nine kinds, each answering a stage

MOTION_KINDS in packages/core/src/motion.ts is a closed list, and each kind declares in MOTION_KIND_STAGES which demand stages it serves. That declaration is what lets an engagement offer "instantiate something useful here" without a person browsing the whole library, and it is why the kinds are an enum rather than a free-text tag: a tag set nobody curates ends up with proposal, Proposal and proposal-v2 in it, and stage coverage stops being computable.

Kind	What it is for	Stages it serves
discovery	The questions that surface what a customer is actually training, before anyone scopes it	qualification, scoping
qualification	Weighted dimensions that turn a judgement about a deal into a score somebody can argue with	qualification
poc	What a proof of concept must demonstrate, and what closes it — so a pilot cannot run forever	poc
proposal	Language blocks assembled into a proposal, so wording that survived procurement is reused	proposal, procurement
pricing	The inputs behind a quoted price: term, commitment shape, and what the block cost	proposal, procurement
architecture	A deployment shape that has already worked, described well enough to be copied	scoping, poc, deployment
case_study	A deployment written up as evidence, for the next customer who asks whether this is real	qualification, proposal, expansion
narrative	The technical argument for why this capacity suits this workload, written once	qualification, scoping, proposal
playbook	The end-to-end sequence for a deployment, spanning every stage rather than one	all eight open stages

Two details in that table are decisions rather than data entry. playbook maps to DEMAND_OPEN_STAGES and is the only kind that does; spanning the whole live motion is exactly what distinguishes a playbook from the eight kinds that answer one question each. And the closed stages appear nowhere, on purpose: a deal that is won or lost has left the motion, and offering to instantiate a discovery template into it would be an invitation to file work against a dead deal.

pricing deserves a word, because it looks like it belongs in the ledger. It does not carry a price — supplier cost and break-even live in the commitment and are gated on economics:read. It carries the reasoning behind a quote: which term was offered, what commitment shape it assumed, what the block cost then. That is practice, and the motion library is not the cost book — the same classification read-guards.ts applies when it gates every motion GET on book:read rather than economics:read.

The loop

library template  ──instantiate──▶  engagement artefact  ──promote──▶  template v2
       ▲                                                                    │
       └────────────────────────  supersedes_id  ◀──────────────────────────┘
                                  origin_artifact_id

This is the only reason the feature exists, and two rules are what make it a mechanism rather than a slogan.

A used template is never edited in place. Instantiating increments usage_count; once it is above zero a PATCH returns 409 template_in_use and names the fix (POST .../versions). A live engagement whose template changed underneath it has lost its provenance, and provenance is the only thing that makes "this came from playbook v3" mean anything a quarter later. A template at usage_count = 0 is still a draft and edits freely.

Promotion writes a new row, never an update. version = previous + 1, supersedes_id back to its predecessor, origin_artifact_id back to the artefact that proved it, visibility: 'shared'. A draft cannot be promoted — 409 artifact_not_final — because the library is what the next deployment copies. Promoting twice is 409 already_promoted. The whole of it happens in the transaction the mutation() chokepoint already opens, and it emits an activity onto the account of the deal that proved it, so the loop is visible on a customer timeline rather than only in a library.

Every collision on (slug, version) is a 409, never a 500. The unique constraint is real and callers hit it in ordinary use: "Proposal Blocks" is a shipped starter, so the obvious first template anyone authors derives a slug that already exists. Creating one is checked first and answers 409 template_slug_exists naming the versions endpoint; allocating a version takes FOR UPDATE on the newest row of the lineage so two concurrent forks queue rather than race; and because a brand-new slug has no row to lock, the insert also catches Postgres' 23505 and answers 409 template_version_conflict. Verified by running four concurrent creates of one title: one 200 and three 409s.

Those two constraints form an FK cycle — motion_templates.origin_artifact_id ↔ engagement_artifacts.template_id — which is why migration 0015_motion.sql is hand-written and adds one of the two constraints in a separate ALTER TABLE after both tables exist. Drizzle will not order that for you.

Private and shared — a departure, stated out loud

permissions.ts says plainly that every read endpoint returns the whole book, because no row-level filter exists anywhere in the query layer. Motion is the first exception, and it is written down here so it cannot be discovered by surprise:

• visibility = 'shared' — book-wide on book:read, like everything else.
• visibility = 'private' — readable and writable only by owner_user_id, plus platform admins. A real WHERE clause, in visibleTemplates().

It was worth the departure because a draft proposal for a live deal is not the same object as a contract, and a library nobody can draft in privately becomes a library nobody drafts in.

Three details are load-bearing:

• The predicate is owner_user_id = $viewer, which is NULL-safe by construction, so an orphaned private row would be invisible to everyone but a platform admin. Writing it as owner = $me OR owner IS NULL would hand every departed user's drafts to the whole workspace. As it happens Postgres will not currently produce such a row — found by running the delete, not by reading the DDL: motion_templates_private_has_owner_check is evaluated on the UPDATE that ON DELETE SET NULL performs, so deleting a user who owns a private template fails outright. Whoever adds a member-removal path has to archive or reassign those rows first. The NULL-safe predicate stays regardless, so that relaxing the CHECK cannot quietly publish them.
• A lineage the reader cannot see never supplies content to one they can. The version number for a new version is allocated against the whole lineage, because (slug, version) is unique and a private fork still consumes a number — but that query returns a number and nothing else, FOR UPDATE. supersedes_id and the fallback summary come from a second, visibility- filtered read. Answering both from one unfiltered query is how a private draft's summary reached the shared library, and it is pinned by a test named for the decision.
• A private template somebody else owns answers exactly as an unknown id does — 404, not 403. A 403 on a specific id is a working existence oracle: it tells you a colleague has a draft at that address, which is half of what the filter exists to withhold.
• A platform admin gets no predicate at all. That is deliberate, and it is pinned by a test that says so in its name, because it looks like the filter failing open.
• Piggy filters to visibility = 'shared' unconditionally, under every filter a model can send. A model that can be talked into reading someone's private draft is a leak with extra steps.

Ownership and capability are different questions and fail differently on purpose: a missing motion:write is insufficient_permission from the chokepoint before the body is read, and a wrong owner is not_owner once the row is known. A shared template is published, not communal — it is still only its owner's to edit. Sharing one needs motion:publish, which is a lead's judgement, because publishing is what everybody else copies next quarter.

Scores move, and the movement is the evidence

qualification_scores is append-only — never updated, never deleted. A mutable current score is a number somebody can make true afterwards; the trajectory across an engagement is the evidence that qualification happened at all.

Scores are integers, in basis points of the maximum (0–10000), computed with integer arithmetic and rounded half-up — the same rule as money, for the same reason. Weights need not sum to 100. Band boundaries are inclusive at min (3500, 5500, 7500), pinned exactly, because an off-by-one there silently changes what a seller is told to do. The API computes the score from the dimensions and refuses a posted basisPoints outright: a score somebody can send is a score somebody can fix.

qualification_scores.dimensions stores the weights rather than referencing the framework, so history does not silently re-weight itself the day someone publishes a new version of the scorecard.

The starter library

Twelve authored templates ship in packages/db/src/seed/motion/, covering all nine MOTION_KINDS. They are not demo data and carry no DEMO — prefix — they are product content, like docs/learn-scripts.md. Seeded isSystem: true, visibility: 'shared', version: 1, unowned.

Idempotency rests on onConflictDoNothing({ target: [slug, version] }) against motion_templates_slug_version_key, which is a silent no-op without that constraint. CI counts motion_templates across two seed runs for exactly that reason; counting contacts alone could never have caught it, because contacts is idempotent by an explicit existence check.

Two demo engagements live in packages/db/src/seed/demo/motion.ts: one mid-POC with three qualification scores, because a single score is a number and three are a trajectory, and one closed-won with a promoted case study, which puts a version 2 into the library and populates both halves of the FK cycle on a first run.

Deliberately not built

• Mermaid. Reference-architecture diagrams arrive as mermaid fences and render as a labelled, scrollable code block with a copy button — the same CodeBlock whether the diagram came from a template's fields or from a fence inside a promoted body. A 2 MB diagram renderer and a CSP hash change were not worth it for this change; the block already reads the language off the fence, so the renderer is the only missing piece if it is ever wanted.
• A single markdown renderer. The app now carries two: streamdown, which Piggy's dock uses for a half-finished token stream in 22rem, and plain react-markdown for page-width authored prose, in components/motion/Markdown.tsx. They are different problems and the second costs ~20 kB in a lazy chunk that only the Motion routes load — the eager entry chunk is unchanged. Consolidating them is a reasonable future change and a bad one to make blind.
• Export to PDF. A proposal leaves PIG by being copied into whatever the customer already reads. Rendering paper is a different product.
• Per-customer sharing links. There is no way to hand a customer a URL onto a template or an artefact, and no third visibility between private and shared. Those two earned their complexity; a third needs an ACL table, and the moment the library has an ACL nobody drafts in it. An external link is a larger decision again — an unauthenticated route serving authored practice — and it belongs to whoever builds a customer-facing surface, not to this change.
• Full-text search. ?q= is ILIKE over title and summary, with % and _ escaped so a wildcard a caller types is a literal. Body text is not searched. Postgres tsvector is the right answer when the library is large enough for that to be the complaint; twelve starter templates are not.
• Pagination. As everywhere else here: a hard .limit() instead.
• Contiguous version numbers. A private fork consumes a number in the shared lineage, so a reader who cannot see the fork sees a hole where it sits. The alternative — a separate counter per visibility — makes "which of these is newer" unanswerable across a fork that is later published, which is the question the lineage exists to answer. The hole is the honest rendering.