Substitution rules

Platform team publishes GenerateCandidates v2.0 with better grader scores on the same meal schema. Callers still invoke GenerateCandidates without code changes. Regression suite includes last quarter's busy-week failures. Substitution succeeds. Every product line on the domain library inherits improvement on the next allowed swap. Another team rewrites the template, skips the suite, and deploys under the same name. Callers unchanged. Evidence stale. Busy Tuesday fails in production while dashboards still show last quarter's figure. That is drift, not substitution.

Helpful context: Libraries of cognition packages judgments. Cognitive capability should be encapsulated hides implementation behind contracts. Applicability conditions travel with packages. This page covers the operational rules for platform teams who own swap policy.

What must stay identical

Substitution preserves the caller-facing contract. Everything else may change under measurement. The decision sentence, holes and result shape, abstain and refer branches, and applicability guards (when terrain-sensitive) must remain fixed. Template wording, model tier, wrapper stack, internal examples and routing, and cost or latency profile within declared bounds may vary, provided evidence supports the swap.

Must stay fixed	May vary under measurement
Decision sentence	Template wording
Holes and result shape	Model tier
Abstain / refer branches	Wrapper stack
Caller-facing contract	Internal examples and routing
Applicability guards (when terrain-sensitive)	Cost/latency profile within declared bounds

Changing behaviour under the same name without remeasurement is drift. Drift is how organisations lose trust in libraries: callers believe they reuse org knowledge while behaviour silently moves.

CallerFixed contractImplementation A or BMeasured evidence

Substitution keeps the contract fixed while implementation improves behind it.

Operational rules for platform teams

The substitution process works as a release gate, not a hope. The platform freezes the decision sentence, holes, result shape, and abstain/refer branches before any swap. The candidate implementation runs through the full suite, and regression must stay green on declared distributions. Eval evidence from the incumbent and the candidate is compared directly: grader floors, exact checks, calibration deltas. Substitution guarantees publish with the package manifest, including compatible semantic version bands and contract hash. When blast radius is large, a canary on sample callers watches failure modes and compares cost before full rollout. Rollback fires automatically when grader floor or exact checks fail in canary, through a defined path rather than tribal memory. Unmeasured provider drift wearing last quarter's figure is rejected outright, because model vendor updates are not implicit substitution.

Fast paths behind the same interface are legitimate substitution when the closed rule is measured. Slow and fast paths and tuning by wrapping describe this pattern. A fast path remains an implementation variant behind one contract, with evidence that the shortcut preserves outcomes on declared terrain.

The Meal Companion example

Swapping the candidate generator succeeds only when the meal plan schema is unchanged for callers (holes and result shape stable), the grader floor is met on declared busy-week distribution, regression includes known failure cases from prior quarters, and the operational profile falls within published bounds or the manifest is updated with caller-visible deltas.

Swapping the model tier inside AssessMealPracticality follows the same logic: the decision sentence stays fixed while the suite re-runs on single-evening fit distribution. Callers depend on evening-fit judgment, not on GPT-4 versus a newer tier.

Busy Week Pattern expertise substitution requires guard parity. Expertise is compressed strategy with guards. Swapping v0.2 for v0.3 without guard equivalence can license compression on terrain where full deliberation is still required.

Cross-shelf substitution is never valid. JudgeWeekdayPracticality and AssessMealPracticality both touch schedules, but they carry different contracts, different suites, and different inventory shelves. Search metadata must keep them apart, a concern sealed and searchable addresses.

When the decision itself changes

If the open judgment changes, meaning a new decision sentence, new holes, or new abstain semantics, the team is shipping a new cognitive unit identity or a major semantic version bump. Callers must consciously migrate. Evidence from the old identity does not transfer without remeasurement. Evidence dies when the template changes is the discipline note for teams who treat prompt rewrites as minor patches. Libraries make that failure visible. Dumps hide it until production breaks.

Major bumps trigger an explicit migration guide for callers, a parallel publish window when blast radius requires it, and new suite identity binding rather than reuse of old suite name on the new decision.

Substitution and inspectability

Callers select packages using runtime inspectability. Manifest substitution fields tell an agent whether v2.1 is compatible with v2.0 for a given interface before invocation. Inspect without substitution metadata invites silent mismatch, especially for autonomous composers mid-loop. Substitution rules belong in the manifest, not in Slack announcements. Platform teams own the policy. The catalog surfaces the guarantees.

Skill library substitution differs

cognitive unit libraries substitute on judgment contracts. Skill libraries substitute on capability contracts and procedure evidence, covering order, seams, invariants, and side effects. Skill library versus cognitive unit library develops this distinction. Swapping a Skill implementation without procedure suite re-run is the same failure mode as swapping a cognitive unit without judgment suite re-run: different eval focus, same architectural requirement.

Common mistakes

Silent model vendor updates are the most common failure. The provider changes weights, behaviour shifts, and the suite was not re-run. Vendor drift needs the same treatment as candidate substitution: evidence first, or pin the provider version explicitly. Template tweaks under a stable semantic version are a close second, where wording changes decision behaviour but the contract hash stays unchanged on paper, and production diverges from eval. Cross-shelf substitution, using a judge cognitive unit where an assessor is required or invoking a Skill when a single judgment suffices, happens when names sound similar. Missing rollback paths mean that when a canary fails, on-call engineers edit templates manually and library trust erodes.

What this looks like in practice

The meal-planning platform publishes GenerateCandidates v2.0 with a manifest declaring contract hash match with v1.x, grader floor improvement on the variety suite, and substitution allowed for callers on meal schema v3. The Meal Planning Agent inspects, confirms schema version, and swaps without strategy change. Tuesday's failure modes from v1 regressions are included in the v2 gate.

When canary exposes a regression on low-variety weeks, a corner case underrepresented in v1 training, the platform rolls back automatically. Callers remain on v1.9 until v2.0.1 passes the expanded suite. That rollback path is part of substitution policy, not incident heroics.

The invoice parallel works the same way: field interpretation cognitive units in the domain library substitute on field contract, and the extraction Skill substitutes on capability contract after procedure suite, as invoice intake overview describes.

Governance and swap policy ownership

Platform teams own substitution gates. Domain owners approve major semantic version bumps. Evaluators maintain suites that substitution depends on. Product teams consume, but do not silently fork when a swap fails. The escalation path runs through fixing the candidate, expanding the suite, or requesting contract change with new identity, not through undeclared template edits under a stable name.

Canary and rollback automation

Substitution policy includes automated canary on a fraction of production-shaped traffic, suite comparison against baseline, and rollback when regression IDs fail. Manual canary without a rollback path teaches teams to edit templates under fire instead of using library semantic versioning. Automation makes substitution trustworthy at scale. Contract hashes change when decision sentences, holes, or abstain semantics change. Teams that tweak wording without hash updates create silent drift under a stable semantic version. The publish pipeline blocks when hash changes without a semantic version bump appropriate to substitution policy.

Running substitution drills when semantic version bumps land verifies contract hash compatibility, rollback paths, and eval parity on held-out cases before agents auto-select newer packages. Substitution without rules invites silent behaviour change. Rules without drills invite paper compliance. Documenting which interfaces allow minor substitution and which require human approval makes the policy concrete, because meal planning may allow patch-level swaps while financial approvals may require explicit operator sign-off.

What to do next

Substitution policy benefits from documentation per library tier (cognitive unit library versus skill library). Automating the suite gate on publish removes the "trust me" from the process. Pairing substitution with inspect before you call ensures callers pick compatible versions. Auditing shared names for silent drift quarterly catches cases where semantic versioning without evidence is a warning sign. Defining rollback automation before broad canary, rather than after the first incident, makes the safety net real.

See sealed, evaluated, and searchable for catalog guarantees, libraries of cognition for placement, and packages, not prompts for semantic versioning discipline.

Read next: Inspect before you call.