Cognitive capability should be encapsulated

Object-oriented design did not invent encapsulation. It named a settlement teams already needed when software grew past a single file. Callers depend on an interface. Implementations change behind that interface. Tests attach to behaviour exposed at the boundary, not to every private field.

Thoughtware needs the same settlement for cognitive capability. Without it, every model swap becomes a repository-wide prompt hunt. Every reliability improvement duplicates templates across services. Every evaluation baseline fractures because callers depended on wording inside the template, not on the declared decision.

This page states White Paper Principle 3 as an architectural rule: cognitive capability is encapsulated behind stable contracts. The Weekly Meal Companion examples use the same named edges as the rest of the collection so substitution stories stay concrete.

Helpful context: What a name buys explains why identity matters. What is a cognitive unit is the encapsulated edge. Libraries of cognition package cognitive units for sharing. Six shapes of cognitive units describes what callers buy at the boundary.

The failure mode without encapsulation

Imagine busy-evening logic copied into three places: the mobile client copy, the API middleware, and the ComposeWeek template. Each copy drifts. Tuesday passes the UI check and fails on the server. Or both pass while violating endorsed household knowledge. Fixing practicality requires editing three prompts and three test suites that were never synchronized.

Encapsulation collapses that duplication into one library entry: AssessMealPracticality. Callers pass declared inputs. They receive structured fit verdicts, abstentions, or referrals. They do not import prompt strings. When v2 improves calibration, the agent strategy and deterministic shell stay stable. Only the library implementation behind the interface changes, followed by remeasurement. That story is ordinary in conventional software. It becomes radical only because many AI teams still treat prompts as copy-paste configuration rather than as hidden implementation details.

What hides and what must not

Encapsulation has two sides. Some details hide so implementations can evolve. Other details remain visible so accountability survives.

Hidden behind the interface belong prompt wording, default model choice, sampling parameters, retrieval mechanics, internal retry or critic wrappers, and the exact harness that runs during development. Those are identity and policy details versioned with the cognitive unit, not dependencies for every caller.

Exposed at the boundary belong the decision sentence, declared inputs and context grants, structured outputs including abstain and refer, purity level, cost profile expectations, and the suite identity with published figures. The black box may hide mechanism. It must not hide which cognitive responsibility the caller invoked. That responsibility belongs in the name and in the decides field from a contract, not a prompt.

Hidden (implementation)	Exposed (contract)
Prompt wording	Decision sentence
Model and sampling	Result shape and abstain/refer
Retrieval mechanics	Declared inputs
Internal retry or critic wrappers	Purity level and cost profile
Evaluation harness wiring	Suite identity and published figures

One software parallel

In conventional code, you swap a sorting implementation when complexity requirements change. Callers still pass arrays and receive sorted arrays. Benchmarks decide whether the swap was worth it.

In Thoughtware, you swap a cognitive unit implementation when terrain shifts, when cost targets tighten, or when a new model generation improves calibration on labeled cases. The swap is economical only if callers never imported template fragments. Libraries exist to make substitution a measured operation: promote v2 behind the same contract, rerun suites, publish figures, update semantic versioning policy. Encapsulation is also what makes evaluation part of architecture feasible. Suites attach to interface identity, not to every call site that once pasted a paragraph of instructions.

Libraries and substitution

Domain libraries package cognitive units for reuse. The Meal Companion places GenerateCandidates, AssessMealPracticality, and RecommendMealSubstitution in a meal-planning domain library. Judge-library entries calibrate across products. Organisational libraries hold edges like AskTargetedQuestion that serve many agents.

Substitution rules (substitution rules) depend on encapsulation. You cannot substitute what was never bounded. When a library entry declares compatibility and passes suites, downstream agents change a pointer, not a scatter of prompts. Without encapsulation, "improve the meal checker" means archaeology. With encapsulation, it means a library operation with semantic versioning, release notes, and remeasurement. That difference shows up in sprint planning and in incident response.

Cognitive capability should be encapsulated.

Thoughtware White Paper · Pr. 3

What this looks like in practice

Ship AssessMealPracticality v1 with a suite on labeled busy evenings. Evaluation shows v2 improves calibration on those cases without new failure modes on variety or allergy edges. Because inputs, outputs, and the decision sentence are stable, promotion follows a measured path: run the v2 suite against the same case classes, publish figures bound to template version and model pairing, update the library pointer used by the agent strategy, and leave deterministic allergy validation and purchase gates untouched.

Callers did not read templates to integrate. They depended on the contract. Reviewers can audit the change as a version bump with evidence, not as a vague "prompt tweak." Invoice intake parallels the structure in enterprise material. Extraction and classification cognitive units live in libraries. Orchestration code depends on contracts, not on vendor-specific chain definitions pasted into three services.

Encapsulation versus secrecy

Encapsulation is not secrecy from operators. Runtime inspectability (runtime inspectability) still matters. Traces, structured outputs, and suite records remain visible. The principle forbids caller dependence on implementation trivia, not observability for people responsible for reliability.

Teams sometimes resist encapsulation because they want "full transparency" into prompts. Transparency for operators belongs in tooling and evaluation artifacts. Transparency for callers belongs at the contract layer. Mixing the two is how prompts leak into orchestration code and become undeclared dependencies.

Versioning and caller stability

Encapsulation interacts directly with three rings of a cognitive unit. Identity carries the decision sentence and template body. Policy carries model defaults and sampling overrides callers may apply at the call site. Environment carries logging and stores outside the declaration.

When busy-evening logic improves, architects ask whether the change belongs in identity or policy. Wording changes that alter the open decision require identity semantic version and suite rebuilds. Cheaper screening models for low-stakes calls may be policy swaps with remeasurement on high-stakes classes. Callers who imported template text never notice either change if they depended on the contract. That stability is the payoff.

Teams sometimes resist encapsulation because they want shared prompt fragments for "consistency." Shared fragments belong inside library implementations or documented includes within identity, not in orchestration strings. Consistency at the contract layer means consistent decision sentences and result shapes. Consistency at the template layer is an implementation concern reviewers audit through library diffs and suite records.

Common mistakes

String import antipattern. Middleware imports prompt constants from another service. Extraction breaks on the first template edit.

Leaking retrieval into caller logic. Orchestration code branches on which documents were retrieved instead of on structured cognitive unit outputs. Retrieval becomes an undeclared part of the public behaviour.

Evaluation coupled to call sites. Each service maintains its own ad hoc grader because no shared identity exists. Figures cannot compare across versions.

False encapsulation. A thin wrapper re-exports a template without a decision sentence, suite pointer, or abstain path. The name looks official while behaviour remains undefined.

When a pull request touches a cognitive edge, four encapsulation questions belong in review before approval: Can callers still depend on the decision sentence and result schema without reading the diff template? Does the change require identity semantic version or policy remeasurement? Are suite records updated for affected case classes? Did any orchestration file import prompt text instead of calling the library entry? Affirmative answers to the last question block merge. Encapsulation regressions are cheap to introduce and expensive to unwind because they spread duplicated judgment across services that drift independently.

What to do next

Write contracts callers can depend on without reading templates. Cross-service imports of prompt strings are the primary vector for regression, so library entries and declared calls replace them. Version identity when the decision or template body changes, swap policy only when suites show safety, and publish suite figures with the interface rather than as tribal knowledge in chat.

When reviewing a pull request, ask one question: if the model vendor changed tomorrow, would this diff touch one library entry or thirty call sites? Encapsulation is the discipline that keeps the answer at one.

Read next: Judgment should be explicit.