agent-seam

One producer, one consumer, one direction, one payload. Write it as a line: signal-research hands relevance one account-facts record.

If the two agents talk both ways in one pass, a request out and an answer back, that is two seams and you spec both. If three agents all write into one, that is three seams, not one fan-in, and the differences between them are where the consumer breaks.

A cycle is a different thing from two seams, and the test is whether the second payload re-enters the first agent as new input to redo its work. Researcher asks, writer answers, done, is two seams. Writer drafts, researcher corrects, writer redrafts, is a cycle. A cycle needs two things written down before anything gets built: what terminates it, and how many passes are allowed. Without both, do not build it, and say which of the two are missing rather than refusing the whole request. The card comes out BLOCKED on that pair of seams and READY on the rest.

The payload is what the consumer needs. Not everything the producer happens to know.

Start from the consumer's input line, field by field, and pull only those from the producer's output schema. Whatever is left over stays home. A payload that carries the producer's whole output makes every field a dependency, and two months later someone deletes one and something unrelated breaks.

An optional consumer field with no producer source anywhere is a different thing from one that is sometimes absent: its absence rule fires on every record, forever. Say that on the card, because an absence rule written for the odd case reads very differently once you know it is the only case, and the consumer's contract usually needs changing rather than the seam.

If a required consumer field has no source anywhere in the producer's output schema, that is a gap at the seam and not a mapping exercise. Name it on the card as a GAP, say which side should produce it, and carry on writing the rest of the seam. The card comes out BLOCKED with one named gap, which is exactly the thing the two owners can act on. Projecting one field onto another because the names are close, a consumer that needs a dated fact and a producer that emits untyped news items, is how a required field arrives empty in production and the chain blames the consumer.

One more shape, because half the agents in a chain have it. When the consumer's grain is a set rather than a record, a clusterer, a rollup, a report, the unit crossing the seam is the batch: the payload is a list plus a batch id, the manifest is the list of keys in that batch, and the validator checks the batch before any of it is read. The no carry rule then applies between batches rather than between records, because carrying between records is the whole function of an aggregator. Say which of the two shapes the seam is, record or batch, on the card. A batch assembled across several runs, a month of nightly output, is its own case: it carries a batch_id and a batch level manifest, while each member keeps the run_id it was produced under. Specifying a batch consumer per record is how you hand an agent a must-never that forbids its own job.

The correlation key, the run id and the schema version sit on top of the intersection rather than inside it. They are seam fields: the consumer did not ask for them and the seam cannot work without them, so they go in the payload and, when neither contract carries them, onto the change request list. That is the one exception to pulling only what the consumer's input line names.

Then mark each field on the consumer's side:

• Required. Absent means the record does not cross. No default, ever.
• Optional, with a defined absence. The consumer has a rule for missing. Write the rule here, not in the prompt.

Three states, and collapsing them is the most common seam defect in existence: present, null because the producer looked and there is nothing, and missing because the producer never looked. Null and missing mean different things and the consumer must treat them differently. If the producer's schema has no way to say "looked and found nothing" as distinct from "never looked", that is a change request on the producer rather than a state you quietly drop. A schema offering only a complete answer or a refusal collapses the two on every record. A seam that turns "never checked" into an empty string is how an agent writes confidently about an account nobody researched.

The consumer validates every record it receives, against the payload schema, before doing any work. Always the consumer, for one reason: the producer cannot be the thing that certifies the producer.

A record that fails validation does not get fixed and does not get guessed at. It gets rejected with the field that failed, and it goes to the operator, not to the next step. Write down where rejections land. A rejection nobody sees is a silent skip, and a silent skip in a twenty account run is the one you find out about from the prospect.

The producer's job at the seam is smaller and it is not nothing: stamp the payload with its own version and the correlation key, and never emit a partial record. Half a record is worse than no record, because half a record validates on the fields that are there.

Both sides already have an abstain state from agent-contract. The seam decides what happens when one fires.

The rule: a refusal upstream is a refusal for the record, not a null field downstream. When signal-research says it found no dated fact, the composer does not receive an empty facts array and write something anyway. It receives a refusal for that account and the account leaves the chain with its reason attached.

Write three lines:

• What the consumer does with an upstream refusal. Usually: stop this record, carry the reason forward, continue the batch.
• Where the refused records collect. One list, visible, with the reason on each. This list is the most useful artifact the chain produces and almost nobody keeps it.
• Whether a refusal is final or re-enterable. If a human can supply the missing fact and re-run that one record, say how, because that is the highest value human move in the whole pipeline.

Fan-in changes this rule, and it is the case people get wrong. When several producers feed one consumer, a refusal from one of them is not automatically a refusal for the record. So the consumer marks each inbound payload required or contributing: a refusal on a required input ends the record, and a refusal on a contributing input degrades the output and is named inside it. A forecast rollup should not die because one rep-notes summarizer abstained, and it should also not present itself as complete when it did.

Fan-in needs two more lines that nobody writes. What key joins the inbound records into one output, which is the correlation key and never the arrival order. And whether the consumer waits for all of them or runs on whatever arrived by a deadline, which is what decides whether a slow producer is a delay or a missing field.

A chain that drops refusals quietly will always look like it worked.

Every record crossing every seam carries a correlation key and a run id. Not for tidiness. Because the failure mode of a batch is contamination, and contamination is invisible in the output.

Two rules:

• The run carries a manifest, the list of keys this run is supposed to process, and the consumer refuses any record whose key is not on it. If there is no manifest, say so on the card: the isolation test below is then the only protection you have, and it is the weaker one.
• Nothing carries between records, or between batches where the consumer's grain is a set. No cached page, no last good value, no "the customer story from the previous account." State that as a must-never on the consumer if it is not there already, test it with a batch where two records are deliberately adjacent and similar, and write the result of that test on the card. An untested isolation rule is a sentence.

READY is a status a card earns after the chain has run once, not at the moment it is specified, so most cards are PROVISIONAL on the day they are written and that is correct rather than a failure. The test gates going live, not writing the card. Write it out, mark it PENDING with the three inputs it needs, and the card is PROVISIONAL until somebody runs it. What is not allowed is a READY card whose isolation rule has never been exercised.

The test that catches this: run the chain over three accounts where account two has almost no data. If account two's output contains anything that can only have come from account one or three, the chain has a contamination defect, and a single account run will never show it.

Walk the chain and mark the first step that spends money, sends something, writes into a system other people read, or cannot be undone. That is the cost line.

A chain of pure reads has no cost line, and that is a finding rather than a blank to fill. Say so, skip the checkpoint, and put a sample review on the chain's terminal output instead, which is the last seam when another agent consumes it and the screen or the document when a human does: the owner reads a handful of outputs, worst first, because the failure mode of a read-only chain is not a cost, it is a wrong answer nobody checked. Never name a false cost line to satisfy the step.

Where more than one step is irreversible, each one gets its own checkpoint. The first is the cost line; the others do not become free because the first one was approved.

When the cost line is the consumer itself, a sender that sends the moment it receives, there is nowhere above it to put a checkpoint inside the existing system. That is a change request on that consumer and the card says BLOCKED, with the checkpoint written out as the thing to build. Never specify a checkpoint as though it already exists, and never let "the sender is already live" settle it: already live is a description of the risk, not a resolution of it.

The checkpoint goes immediately above it, and it is a human approving a batch, not a human approving each record, unless the per record cost is high enough to deserve it. Write what the human sees at the checkpoint: the thing that will be spent, the count, and the records that are about to go through with the weakest inputs. Ranked worst first, because the checkpoint is a sampling instrument and an unordered list of twenty gets approved without being read.

Retries stop at the cost line too. Idempotent reads retry freely. Anything that spends gets one attempt and a ledger of what was already done, keyed by correlation id, so a re-run does not pay twice. A chain without that ledger will eventually bill you twice for the same twenty renders.

Multiply the pass rates of the links on the serial path, the ones every record has to pass through to reach the output. That product is the chain rate, and it is the number that matters, not any individual agent's 95 percent. Contributing inputs do not multiply, because a record survives their refusal, so list them beside the product with what the output loses when each is absent.

Two things do not belong in the product. The test for whether a step is an agent: does it make a judgment from an input that could have come out differently? A writer and a scorer do. A mail API, a render call and a person pressing send do not, whatever their uptime. A step that is not an agent is not scored even when somebody has attached a number to it, because its failure mode is availability rather than judgment and a 0.99 on a mail API is measuring a different thing than a 0.91 on a writer: name it, count it out, and say the product covers the agent links only. And a by design abstain is not a failure. An agent that correctly declines a third of accounts because those accounts have no tickets should not drag the chain rate down for doing its job, so compute that link's rate over the records it actually answered, and publish the abstain rate beside it as its own number. A sentiment reader that answers 60 of 100 accounts and is right on 53 of those is a 0.88 link with a 40 percent by design abstain rate, not a 0.53 link. An abstain that was supposed to happen and a wrong answer are not the same event, and the arithmetic has to stop treating them as one.

Then compare it to your chain floor, and to the batch size when you have one. When the product is unknown because a link on the serial path has no verdict, there is no comparison to make and the decision is already decided: gate that link first. Say that rather than leaving the step half run. A 0.81 chain over twenty records is roughly four records that need a human. Decide, out loud, which of these four things you are doing about that:

• Raise a link. Find the weakest and send it back to its own gate.
• Move the checkpoint. Accept the rate and catch the four at the checkpoint, which is the right answer more often than people expect.
• Shorten the chain. Two agents at 0.95 beat four at 0.95, and one of the four is usually plumbing that did not need to be an agent.
• Add a sample review. The option for a chain of pure reads, where there is no cost line to put a checkpoint above. The owner reads a fixed number of terminal outputs per week, worst first.

Two things about this step. The recommendation is yours and the decision is the pipeline owner's, so write it as a recommendation with the owner named, never as an acceptance issued on their behalf: accepting a rate below the floor is a risk somebody has to own and it is not you. And what you may not do is report the best link's number as the chain's number. Publish the product.

One card per seam, plus one chain line for the whole thing. File it with the consumer, at public-skills/<consumer-slug>/evals/seams.md, and link it from the producer. The seam belongs to both builds, and a document with two owners gets read by neither, so it lives with the side that validates and the other side is pointed at it. If neither has a directory yet, it lives with the work until one does.