Effect Contract Annotation¶
Document — instantiates Declared Effect Boundary Enforcement
Documents allowed reads, writes, emissions, notifications, and external calls in or near the interface definition.
Effect Contract Annotation is the written promise attached to an interface that states, in plain terms a caller will actually read, what the action may read, write, emit, notify, or delegate — and, by implication, what it may not. Its defining trait is that it is a declaration, not an enforcer: it changes no runtime behavior and blocks nothing. Its entire value is making the effect boundary explicit and legible right where the interface is defined, so the promise exists to be relied upon, checked against, and audited. It converts a tacit "this just recomputes eligibility" into a stated contract with named allowed effects.
Example¶
A benefits agency maintains a standard operating procedure for the step "recheck eligibility." As written, the procedure said only that — recheck eligibility — and clerks reasonably assumed it merely read a file and updated a status. In practice the action also flipped an automated benefit-suspension flag that a downstream payment system watched, occasionally cutting off a claimant nobody meant to touch.
The fix is not new software but an annotation on the procedure itself. Beside the step, the interface now carries an explicit effect clause: reads — applicant file; writes — eligibility_status; emits — notice-of-change letter; touches — benefit-suspension flag (downstream payment surface); does NOT touch — payment schedule. A clerk reading the procedure now sees the suspension flag named as a consequence, at the moment of acting, instead of discovering it in an incident review. The annotation still cannot stop a misuse — but it ends the pretense that the effect was out of scope.
How it works¶
- Effect clause at the interface. Allowed reads, writes, emissions, notifications, and external calls are listed on the interface, spec, schema, or procedure — wherever the caller looks — not buried in an implementation.
- Boundary by inclusion and exclusion. The clause names both what is inside the allowed set and, where confusion is likely, what is pointedly outside it.
- Written for its audience. The wording targets whoever must rely on it — implementer, caller, operator, or affected party — rather than defaulting to technical shorthand.
- Versioned promise. The annotation travels with the interface and is updated when the effects change, so the contract and the code do not silently drift apart.
Tuning parameters¶
- Effect granularity — broad categories ("writes analytics events") versus specific surfaces ("increments search_impression_count"). Finer is more honest and more maintenance.
- Boundary audience — how much explanation the clause carries for implementers versus users, auditors, or regulators, who need different depth.
- Placement — inline with the signature, in adjacent docs, or in a separate policy register; closer placement is harder to ignore.
- Formality — free prose versus a machine-checkable schema. A structured clause can be verified by a tool later; prose cannot.
When it helps, and when it misleads¶
Its strength is that it is cheap, early, and makes the effect contract exist — a declared boundary can be reviewed, taught, and pointed to, where an undeclared one can only be discovered by accident.[n1]
Its defining weakness is that it is only as strong as its checkers: an annotation nobody verifies drifts out of sync with the code, and a stale contract is worse than none because it is trusted. The related trap is overbroad declaration — "may change any user record" technically keeps the promise while making the boundary useless. The guarding discipline is to keep the clause narrow by resource, actor, and context, and to pair it with a detector that catches the gap between declared and actual effects rather than trusting the words alone.
How it implements the components¶
declared_effect_contract— it is the contract: the stated, versioned promise of what the action may read, write, emit, and delegate.effect_boundary— by naming what is inside and outside the allowed set, it draws the boundary in the interface where callers and operators can see it.
It does NOT implement mutation_gateway or effect_observability_record — it states the promise but neither enforces it at the write path nor records whether it held; enforcement is Permission Scope or Capability Token and the durable record of what actually happened is Audit Log and Trace.
Related¶
- Instantiates: Declared Effect Boundary Enforcement — supplies the declared contract the whole pattern is built to keep honest.
- Consumes: Effect Review Checklist surfaces the shared-state surfaces that the contract must then declare.
- Sibling mechanisms: Audit Log and Trace · Command–Query Separation · Compensating Action Protocol · Effect Review Checklist · Immutable Data or Copy-on-Write · Permission Scope or Capability Token · Sandbox or Staging Execution · State Diff Test · Transaction Boundary
Editorial Notes¶
Form Classification¶
Form family: Rule, Policy & Commitment
Rationale: The annotation establishes a versioned standing contract that permits named reads, writes, emissions, notifications, and calls while excluding undeclared effects.
Nearest alternative: Representation, Specification & Plan — The clause is represented near the interface, but its operative force is the continuing constraint it places on implementations and callers, not documentation alone.
Review outcome: Adjudicated after independent review; high confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Single lineage
Present-day reach: Specialized
Rationale: Programming-language effect systems and software interface contracts cohered explicit declarations of the reads, writes, emissions, and external calls an operation may perform.
Review resolution: The current reviewers agree that computer_science is primary. For the reported differences (domain_reach_disagreement), the evidence supports single_lineage, specialized, and no alternate origin; these choices preserve materially formative origins without conflating later domain reach.
Review outcome: Reconciled after independent review; high confidence.
Notes¶
[n1] In program specification, a frame condition declares which locations a routine is permitted to modify — everything else must remain unchanged. Formal notations such as JML's assignable clause make this a checkable promise; an effect annotation is the human-readable analogue attached to any interface, not just code. ↩