The platform team of the synthetic insurer is proud of a new idea. Every intake product has eligibility rules, and every team writes them as code, a little differently. So the team ships a shared rule template: a product lists its rules as configuration (field, operator, threshold, outcome), and one evaluator in the pattern applies them. The property team moves its two roof rules into the new format in an afternoon. The tests for submissions SUB-1004 and SUB-1101 pass.
Then submission SUB-1003 arrives with no roof age, and the roof-data provider has no record either. The illustrative guide UW-GUIDE 2026.2 is clear: rule R-ROOF-02 says an unknown roof age cannot be assessed, so request it. The shared template recommends approve. Nothing failed. The evaluator treated a missing number as zero, no rule fired, and "no rule fired" meant approve.
The template was tidy and wrong in a way no one could see from inside it. A rule that belonged to one product had been turned into data for a mechanism that did not know the rule existed.
The learner's question: in an enterprise factory, which differences between products belong in the shared pattern, which are configuration a spec fills in, and which are business logic that must stay in each product's own module, even when two products' rules look the same?
Three kinds of difference#
Plain English. The pattern is the plumbing every product of a kind shares. Configuration is the settings each product fills in. Business logic is the product's own decisions, written as code its domain team owns. Each one changes for different reasons and is reviewed by different people.
From repetition to a pattern introduced invariants and variation points on two small algorithm requests. This page is the enterprise depth of that idea, in the insurance factory of Example C (examples/c-insurance-service/). Three terms carry it.
A seam is a place in the pattern's code where product-specific behavior plugs in, with a fixed contract on both sides. An extension point is a named seam the pattern declares and a product spec must fill; PAT-INTAKE-API 2.1.0 declares eleven of them, from roles to rollout. Configuration is the data a spec supplies at an extension point: route paths, role names, field types, a retry limit, a threshold. A business-rule module is the code that makes the product's own decisions, owned and reviewed by its domain team, called by the pattern through a seam and never contained in it.
Before AI. A Spring Boot service already has all three. The framework's filter chain and auto-configuration are the pattern.application.ymlis configuration. Your@Serviceclass with the pricing logic is the business-rule module. Nobody would put the pricing logic into a YAML file with operators in it, and nobody would letapplication.ymlturn off the security filter for one endpoint without review. The same split protects a factory, for the same reasons.
The operational consequence is ownership. A change to the pattern reaches every product on its version line and is reviewed by the platform team. A change to configuration reaches one product and is checked by the factory's validators. A change to a rule module changes one product's decisions and is reviewed by the people accountable for those decisions; for the insurer, that includes the underwriting guide's owners.
Example C's three layers, file by file#
Example C keeps the three layers in different files, which makes the split visible.
| Layer | File | What it holds | Changes when | Reviewed by |
|---|---|---|---|---|
| Pattern | pattern.json, service.py (the skeleton) | 8 skeleton steps, 11 extension points, 5 skeleton handlers, constraints such as human_decision_roles | the platform team improves the plumbing for every product | platform team |
| Configuration | product_spec.json | 4 roles, 5 routes, submission schemas v1 and v2, workflow states, 6 events, retry policy, rollout | this product adds a field or a route | the factory's station S1 and the gates |
| Configuration of the rules | policy_fixture.json | thresholds: max_roof_age_years 25, max_gap_years 5, wind zone C | the underwriting guide changes a number | guide owners |
| Business logic | underwriting.py : recommend | which rule is checked first, what counts as missing, which evidence wins | the guide changes how rules combine | domain team and guide owners |
The second and third rows are both configuration, and the difference between rows three and four is the heart of this page. Raising the age limit from 25 to 30 years is a number in policy_fixture.json. Checking the age gap before the age limit is logic in recommend, and the order matters, as the demonstration below shows.
The seam in the skeleton is one line. Step 6 of Service._pipeline in service.py, quoted verbatim, hands every request that passed the invariant steps to the handler the spec's route names:
# 6 business handler (the spec's extension point)
resp = self.handlers[route["id"]](ctx, principal, params, body, rec, key)
Everything before that line (parsing, authentication, role check, schema validation, idempotency) is the same for every product. The assessment handler then calls the rule module, again quoted from Service._assess_submission:
rec_obj = recommend(rec["submission"], result, self.policy, self.cfg["policy_version"])
The module is the scripted stand-in for the underwriting agent's recommendation step; no model is called. Its first three decisions, from underwriting.py : recommend, show logic that no threshold table can express:
if app is None and prov is None:
return shape("request_info",
["The application gives no roof age.", "The roof-data provider has no record.",
"R-ROOF-02: request the roof age or an inspection."],
["R-ROOF-02"], ["roof_age_years"], 0.9)
gap = rules["R-ROOF-03"]["max_gap_years"]
if app is not None and prov is not None and abs(app - prov) > gap:
Missing data is checked first and named. The gap between the two sources is checked before the age limit, so a conflict always reaches a person as an escalation instead of being settled by whichever number happens to trip a limit. And the provider's value is preferred over the application's when both agree within the gap. Each of those is an underwriting decision, written where the underwriting owners can read and test it.
One honest limit of the example: the skeleton imports the module directly (from underwriting import recommend at the top of service.py). The extension point underwriting in the spec names the guide, its version and the rules, but the pattern does not declare the module's interface as a contract the factory checks. A production pattern should: a declared signature and result shape for the rule module, checked at assembly time, is what makes the seam a seam rather than an import.
Diagram: Pattern, configuration and business logic in Example C
Three lanes for the three layers. The pattern lane is the invariant skeleton of PAT-INTAKE-API: parsing, authentication, role check, schema validation, idempotency, then one seam. The configuration lane is SPEC-INTAKE-001 and the policy file: routes and roles, schemas, thresholds. The business-logic lane is the product's rule module, which decides in a fixed order: missing data, then the gap between sources, then the age limit. The pattern owns the boxes and arrows, the spec owns their values, the domain team owns what happens behind the seam.
- Pattern
- authentication + role check: Every request passes the same two skeleton steps before any product code runs.
- schema validation + idempotency: The body is checked against the spec's schema; write routes need a key.
- step 6: business handler: The skeleton hands the request to the handler the route names.
- only underwriter decides: No spec can open the decision route to another role.
- Configuration
- roles + routes: Four roles and five routes, each naming who may call it.
- submission schemas: Field types, enums, ranges and patterns the skeleton validates.
- thresholds: Numbers the rule module reads, versioned with the guide.
- Business logic
- rule module: The product's own code, called through the seam, owned by the domain team.
- missing, then gap, then age: R-ROOF-02 before R-ROOF-03 before R-ROOF-01; a threshold table cannot express the order.
Read the diagram from left to right. A request crosses the pattern's invariant steps, configured by values from the spec, and reaches one seam. Behind the seam sits the product's rule module, which reads its thresholds from the policy file and returns a recommendation in the series shape. The pattern owns the boxes and the arrows; the spec owns the labels on them; the domain team owns what happens behind the seam.
The pattern file and the product spec, side by side#
An enterprise pattern file must say, for a product kind, what is fixed and what a spec must supply across the whole system: users and roles, frontend, API, database, external systems, events, deployment, security controls, tests, environments, and the extension points for business logic. A product spec fills those fields for one product.
Example C covers part of that list. The table checks each field against the two real files.
| Field | pattern.json (PAT-INTAKE-API 2.1.0) | product_spec.json (SPEC-INTAKE-001) |
|---|---|---|
| Users and roles | constraint: only underwriter decides; extension point roles | 4 roles: broker, underwriter, auditor, underwriting-agent |
| API | skeleton handlers; extension point routes | 5 routes with roles, bodies, idempotency, events |
| Data | extension points submission_schemas, decision_schema | 11 fields (v1), plus roof_material (v2) |
| External systems | constraint: bounded retries; extension point | roof provider stub, 2,000 ms timeout, 3 attempts |
| Events | constraint: names carry a version; extension point | 6 event types with required fields |
| Security controls | skeleton steps authentication, role check; PII masking constraint | PII field broker_email; demo bearer tokens |
| Deployment and environments | extension point rollout | 3 environments, 5 percent canary, documentation only |
| Business-logic extension points | extension point underwriting | guide UW-GUIDE 2026.2, 4 rules, stand-in recommender |
| Frontend | not present | not present |
| Database | not present (in-memory store) | not present |
| Tests | not present in the file (50 tests live in tests/) | not present |
Three fields are missing from both files: frontend, database and tests. The block below adds them, together with explicit security controls and environments, as an extended pattern-file shape. Teaching reconstruction: this is not a file in Example C, and nothing in this site's examples reads it. It shows the shape a pattern file takes when it covers a whole service, with each field saying whether it is fixed by the pattern or filled by the spec.
{
"pattern_id": "PAT-INTAKE-API",
"version": "3.0.0-draft",
"owner": "platform team",
"users_and_roles": {"fixed": {"human_decision_roles": ["underwriter"], "deny_by_default": true}, "spec_fills": ["roles"]},
"frontend": {"fixed": {"kind": "server-rendered forms", "accessibility": "the organization's standard"}, "spec_fills": ["screens", "field_labels"]},
"api": {"fixed": {"errors": ["400", "401", "403", "404", "409", "422"], "write_routes_require_idempotency_key": true}, "spec_fills": ["routes"]},
"database": {"fixed": {"engine": "relational", "migrations": "forward-only, backward-compatible reads"}, "spec_fills": ["tables", "retention_days"]},
"external_systems": {"fixed": {"retries": "bounded", "timeouts": "required"}, "spec_fills": ["systems"]},
"events": {"fixed": {"envelope": ["event_id", "event_type", "event_schema_version", "trace_id", "correlation_id"], "names_carry_version": true}, "spec_fills": ["event_types"]},
"security_controls": {"fixed": ["authentication", "role_check", "audit_record_per_request", "pii_masked_in_logs", "secret_scan"], "spec_fills": ["pii_fields", "data_classification"]},
"tests": {"fixed": ["401 and 403 per route", "422 field errors", "idempotent replay", "schema compatibility"], "spec_fills": ["golden_cases"]},
"deployment": {"fixed": {"canary": true, "rollback_on": "error rate above the spec's threshold"}, "spec_fills": ["canary_percentage", "rollback_conditions"]},
"environments": {"fixed": ["dev", "staging", "production"], "spec_fills": []},
"business_logic_extension_points": [
{"id": "recommend", "signature": "recommend(submission, evidence, policy, version) -> recommendation", "result_shape": "series recommendation shape", "owner": "domain team"}
]
}
And the matching fragment of a product spec that fills it, for the claims product this page's lab uses as the second product. Teaching reconstruction: claim-notice-intake (SPEC-INTAKE-002) is the extract lab's own synthetic product, not part of Example C.
{
"spec_id": "SPEC-INTAKE-002",
"product": "claim-notice-intake",
"pattern": {"id": "PAT-INTAKE-API", "version": "3.0.0-draft"},
"roles": ["policyholder", "intake-agent", "claims-adjuster", "auditor"],
"screens": ["report a loss", "upload photos"],
"tables": ["claim_notice"],
"retention_days": 2555,
"systems": [{"id": "policy_administration_lookup", "timeout_ms": 2000, "max_attempts": 3}],
"pii_fields": ["policy_number", "contact_phone"],
"data_classification": "confidential",
"golden_cases": ["late notice is referred", "estimate gap above 5 percent escalates"],
"canary_percentage": 5,
"rollback_conditions": ["any 5xx on record_decision"],
"business_logic": {"recommend": "claims_rules.recommend", "unknowns": ["what counts as the loss date for a continuous leak"]}
}
Two fields deserve attention. retention_days is a number someone must decide; the pattern requires the field but cannot know the answer, which is why it is a spec field and not a default. And the spec carries an unknowns list: a question nobody has answered yet, written down instead of guessed. The numbers in this block are illustrative.
Choosing a pattern does not answer the questions#
A common hope is that picking a proven pattern settles most of the design. It settles the plumbing. It does not settle what the product should do, and the factory must refuse to guess. Example C's station S1, factory.py : s1_validate_spec, does this for the parts it can see; its docstring reads "Unknowns become errors, not guesses: selecting a pattern does not excuse a missing behavior."
The script below was written for this page and run on a scratch copy of Example C. It edits copies of the real spec in four ways and asks the factory to assemble each. What it demonstrates: S1 refuses a spec with missing extension points, a decision route opened to the agent, a route the skeleton has no handler for, and an event without a version. What it does not demonstrate: that a filled extension point is filled sensibly. The last case shows the limit.
unedited spec: 0 problems
spec without workflow and underwriting: REFUSED
FactoryError: extension point not filled: workflow; extension point not filled: underwriting
decision route opened to the agent: REFUSED
FactoryError: route record_decision lets ['underwriter', 'underwriting-agent'] decide; pattern allows only ['underwriter']
new route and unversioned event: REFUSED
FactoryError: route bulk_import has no handler in the pattern skeleton; event submission.imported does not carry a version
workflow present but empty: built, 5 artifacts, stations ['passed', 'passed', 'passed', 'passed']
first request raised KeyError: 'transitions'
The first three refusals are the pattern doing its job: an unfilled extension point, a constraint broken, a route with no seam behind it. The second refusal is the most important, because it protects the rule that the model recommends and a person decides; no product spec can open that route, whatever it says.
The last two lines are a real gap in Example C, found while writing this page. S1 checks that each extension point is present (if ep not in spec), not what it contains. A spec with "workflow": {} passes all four stations, the factory writes five artifacts and a manifest marked passed, and the service fails on its first request with a KeyError. Selecting the pattern did not excuse the missing workflow, but the factory's check only looked for the key. The fix is to give every extension point its own schema and validate the value at S1, so "present" means "specified". The specification as an executable contract is the home of spec validation.
When a template becomes a brittle abstraction#
A brittle abstraction is a shared mechanism that works for the cases it was designed from and fails, often silently, as soon as a product needs something it has no place for. The opening story is one. The code below is that mistake, labelled as one and kept so you can run it: a generic rule template of the kind a platform team might ship, version 2, after abs_diff_gt and field2 were added so that R-ROOF-03 could be written at all. It was written for this page and run against Example C's real recommend and policy_fixture.json from a scratch copy.
OPS = {"gt": lambda a, b, t: a > t, "abs_diff_gt": lambda a, b, t: abs(a - b) > t}
def evaluate(rules: list, record: dict) -> str:
"""First matching rule wins; missing numbers default to 0; no match means approve."""
for r in rules:
if any(record.get(k) != v for k, v in r.get("when", {}).items()):
continue
a = record.get(r["field"]) or 0
b = record.get(r.get("field2", ""), 0) or 0
if OPS[r["op"]](a, b, r["value"]):
return r["outcome"] + " (" + r["id"] + ")"
return "approve (no rule fired)"
PROPERTY_RULES = [
{"id": "R-ROOF-01", "field": "roof_age_years", "op": "gt", "value": 25, "when": {"wind_zone": "C"}, "outcome": "decline"},
{"id": "R-ROOF-03", "field": "roof_age_years", "field2": "provider_roof_age_years", "op": "abs_diff_gt", "value": 5, "outcome": "escalate"},
]
case app prov zone template module (Example C)
UW-004 9 22 C escalate (R-ROOF-03) escalate (R-ROOF-03)
UW-F01 28 27 C decline (R-ROOF-01) decline (R-ROOF-01)
UW-003 None None B approve (no rule fired) request_info (R-ROOF-02) <- differs
page's own 27 20 C decline (R-ROOF-01) escalate (R-ROOF-03) <- differs
template keys in use: ['field', 'field2', 'id', 'op', 'outcome', 'value', 'when'] ops: ['abs_diff_gt', 'gt']
The first two rows are the cases the template was designed from, and they agree. The third row is series case UW-003: no roof age anywhere. The template's default of zero for a missing number is reasonable for a generic evaluator and wrong for this product, because the product's rule says a missing age is a finding in itself. The fourth row is an input this page constructed (application 27 years, provider 20, zone C). The template checks rules in list order, so the application's age trips the limit first and the result is a decline; the module checks the gap first and escalates the conflict to a person. Neither row raised an error.
Diagram: How a shared rule template drops a rule without an error
Follow submission SUB-1003, which has no roof age. In the template path, the evaluator defaults the missing number to zero, no rule fires, and no rule fired means approve. In the module path, the product's code checks for missing data first and returns request_info under R-ROOF-02. The template was correct for the cases it was built from; the rule it had no field for disappeared.
- Shared template (a mistake)
- roof age missing: Neither the application nor the provider has a roof age.
- missing number becomes 0: A generic default every product inherits.
- no rule fired: approve: The template's fallback outcome, with no error.
- Product's rule module
- roof age missing: The same input.
- check missing first: Missing data is a finding under R-ROOF-02.
- request_info (R-ROOF-02): A recommendation with missing: roof_age_years.
The two paths start from the same submission. The top path never reaches a decision about missing data, because the template has no place where that decision could live; the bottom path makes it first. The difference is not a bug in either line of code. It is where the rule was allowed to exist.
The mechanism is worth stating plainly. The template is a small language: seven keys and two operators after one version. Every new product rule either fits that language or forces the platform team to extend it, and each extension changes the evaluator under every product. The rules that fail are the ones whose meaning lives in how they combine (what counts as missing, which check comes first), and that meaning has no field in the template. Worse, a rule that cannot be expressed tends to be approximated with the fields that exist, which is how R-ROOF-02 disappeared without anyone deleting it.
The corrected state is the one Example C already has. The pattern shares the seam and the result shape; each product writes its rules as code in its own module, with its thresholds in its own policy file, and tests them with its own cases. The extract lab's intake preset makes the same point from the other side: two products whose rules read "more than 25, then stop" and "differ by more than 5, then escalate", in different units and owned by different teams.
Common confusion. A threshold in a file is configuration; the rule that uses it is logic. Moving every number of a rule into configuration does not make the rule configurable. It makes the rule's structure implicit, and the structure is what usually changes.
What this is not. This page places differences inside one product kind. Versioning a pattern and computing who a change reaches is Factory learning loop; the eight reference patterns and their variation points are Reference enterprise patterns; the platform foundations around the pattern are Platform foundations. Typed contracts and validation at a seam in depth are Schema Engineering.
Where does a difference belong?#
The page's own decision, asked of every difference between two products on one pattern.
| Option | Choose it when | Example in the insurance factory | Failure mode if misplaced |
|---|---|---|---|
| Pattern (invariant or constraint) | it must hold for every product, or breaking it is irreversible | only underwriter decides; every request is audited | in a spec, one product turns it off |
| Configuration at an extension point | it is a value of a known kind the pattern can validate | route paths, role names, a 2,000 ms timeout, threshold 25 | in code, every product rewrites the same plumbing |
| Business-rule module | it is a decision whose meaning lies in how facts combine | R-ROOF-02 before R-ROOF-03 before R-ROOF-01 | in a template, a missing case is silently approved |
| Pattern change (new version) | several products need the same new seam | a seam for a second external provider | done as a product hack, it becomes a fork |
The criteria, in order: who is accountable if it is wrong; whether the pattern can validate it without knowing the business; how many products need it; and whether it changes on the pattern's schedule or the product's. The counterexample is masking: which fields are personal data is product configuration (observability.pii_fields), but that logs are masked at all is a pattern constraint (logs_mask_pii). One concern, two layers.
In a coding agent. When a coding agent such as Claude Code or Codex staffs the station that writes a product's rule module, the split tells it where it may write: the module file and its tests, never the skeleton and never the pattern file. The factory's own tests, including the product's golden cases, decide whether the module advances, and a person with merge rights on the domain team reviews it. The runtime controls around that run belong to Harness Engineering.
Try it#
The lab's intake preset puts Example C's SPEC-INTAKE-001 next to the lab's own claim-notice-intake. Mark each field as pattern, spec or product code, and read the warnings. It starts from a plain diff, which puts equal values into the pattern and different values into the spec.
The table is the same information for a reader without JavaScript, from docs/LABS.md and examples/labcore/a_extract.py. The recommended split is this site's recommendation, not a standard.
| Field | broker-submission-intake | claim-notice-intake (lab's own) | Recommended |
|---|---|---|---|
| Authentication, role check, idempotency key, audit and versioned events | the same in both | the same in both | pattern |
| Roles | auditor, broker, underwriter, underwriting-agent | auditor, claims-adjuster, intake-agent, policyholder | spec |
| Submission fields | 12 fields (v2) | 6 fields | spec |
| Workflow states | received to decided, 6 states | received to decided, 5 states | spec |
| Who decides | underwriter (a person) | claims-adjuster (a person) | spec; that a person decides is pattern |
| External call and retry | roof provider, at most 3 attempts | policy administration lookup, at most 3 attempts | spec |
| Rule with a 25 threshold | R-ROOF-01: roof older than 25 years in zone C | late notice: more than 25 days after the loss | product code |
| Rule with a 5 threshold | R-ROOF-03: roof ages differ by more than 5 years | estimates differ by more than 5 percent | product code |
Reading: of 11 fields, the plain diff matches the recommendation on 9 and warns on 2, the two threshold rules, which a diff would put into the spec as pattern switches. No model takes part in this lab. Where Example C puts an agent at a station, the agent is a scripted stand-in, so these results show how the factory mechanics work, not how good any model is.
WatchAlgo in practice#
WatchAlgo's unit contract has no business rules in the insurance sense, but its repository shows the same three layers and one failure that comes from a missing seam.
Observed in the repository (zenalgo-frontend, HEAD 1b183564; docs/EVIDENCE.md rows 3 and 7 and the metrics inventory): the three-file unit contract is the invariant. The three narrative flavors (technical, fun, spiritual) are variant outputs inside it, with different fields per flavor, and the visualization's states are shared by all three. The solution validator validate_payload (in scripts/generate_batch37_next10.py, cb6e7ac3) plays the role of station S1. EVIDENCE.md records that it reads only data["solution"], and that unit wa-001378 declares its brute-force approach as not applicable, with a reason, which the validator does not model, so it raises KeyError('complexity').
Read through this page: wa-001378 made a legitimate choice the pattern had no extension point for. With no declared place for "this approach does not apply", a valid variation looks exactly like a broken file. That is the brittle-abstraction failure seen from the validator's side, and it is the same gap as Example C's empty workflow: a check that knows a key, not its meaning.
Reported by the author: specialized agents handled individual station responsibilities. The repository does not show a pattern file that declares the unit's extension points; Station-by-station decomposition maps what it does show.
Enterprise translation#
At the insurer, the three layers map to three review paths. The platform team reviews changes to PAT-INTAKE-API and its skeleton, and releases them under a version. The factory's S1 and gates check configuration in each product spec, and a domain engineer reviews it like any code change. Changes to a rule module and its policy file go through the domain team and the owners of the underwriting guide, because they change what the service recommends to an underwriter.
What dominates the critical path is the third path. Agreeing what R-ROOF-02 means when the provider has a record but the application does not is a conversation with underwriting, not a template change. A factory accelerates the first two layers well. It does not shorten the third, and a design that pretends it does (by turning rules into configuration "so the business can edit them") moves that conversation into production.
Failure test#
The failure: a product spec fills an extension point with an empty value, "workflow": {}. The factory accepts it, writes five artifacts and a manifest whose four stations all say passed, and the assembled service raises KeyError: 'transitions' on its first submission.
How the factory catches it: in Example C as it stands, it does not, before runtime. S1 checks presence, the contract gate checks routes, roles and events, and the unit tests use the real spec. The fix this page recommends is a schema per extension point, validated at S1, plus one smoke request against the assembled service as a station of its own. A factory that marks a run passed and ships a service that cannot accept a request has violated the site's rule that a self-report of done is not evidence.
What to run or toggle: copy Example C to a scratch folder, set "workflow": {} in the copy's product_spec.json, run /opt/homebrew/bin/python3 run.py, and read the traceback. Then restore the file. In the lab, mark the 25-threshold rule as pattern and read the warning.
Where to go deeper#
- Insurance factory, part 1: building the intake contract (next): the factory builds the intake endpoint and its validation from this spec.
- From repetition to a pattern: invariants, variation points and premature abstraction on two small requests.
- The specification as an executable contract: validating what a spec says, not only that it says something.
- Factory learning loop: releasing a pattern change and computing who it reaches.
- Platform foundations: templates, registries and the catalog around the pattern.
- Schema Engineering: typed contracts and validation at a seam.
Checklist for Monday#
- For every difference between two products on one pattern, write down its layer and its reviewer.
- Keep rules that must never vary in the pattern as enforced code, and refuse specs that try to change them.
- Give each extension point a schema and validate the value, not only the key.
- Declare the interface of every rule-module seam (signature, result shape) and check it at assembly.
- Keep thresholds in the product's policy file and the rule's structure in the product's module, tested by the product's own cases.
- Treat a shared rule format as a language with a version and an owner, or do not ship one.
Exercises#
- The underwriting guide raises the roof age limit in zone C from 25 to 30 years. Which file changes, and who reviews it?
Answer 1The policy file, reviewed by the guide's owners
policy_fixture.json (max_roof_age_years) under a new guide version, reviewed by the guide owners and the domain team, with the product's cases rerun. The pattern and the spec do not change; policy_version in every recommendation shows which guide was applied.
- Two products want a second external provider called after the first. Configuration or pattern change?
Answer 2Pattern change
The skeleton has one bounded-retry call per assessment. A second provider needs a new seam (ordering, timeout budget, what happens when one fails), which several products share, so it is a new pattern version, not a spec setting.
- Why is the template's "missing numbers default to 0" a reasonable choice for the platform team and a wrong one for the product?
Answer 3Generic defaults erase product meaning
A generic evaluator needs some default to run at all. For the property product, a missing roof age is itself the finding (R-ROOF-02), so any default replaces a business rule with a guess.
Advanced perspective#
Configuration languages grow into programming languagesThe rule template's path, and how to stop it early
The rule template on this page gained a key and an operator in its first revision. The next requests are predictable: "unless" conditions, date arithmetic for the claims product's late notice, percentages for its estimate gap, rule priorities, and then a way to say "if this field is missing, do that". Each is reasonable alone. Together they produce a small programming language with no debugger, no type checker, no tests of its own, and an evaluator every product depends on.
Three signs say the line is being crossed: rules start depending on the order they are listed in; the same field needs different defaults in different products; and the platform team receives feature requests for the evaluator from domain teams. The alternatives are a real language in the product module (with the product's tests), or a decision-table format whose semantics are fixed and fully specified, versioned and tested as its own product. A half-language in configuration is the worst of the three, because it moves logic out of the reach of the product's tests without moving it into the reach of anyone else's.
Making the seam a checked contractFrom an import to a declared interface
In Example C the seam between skeleton and rule module is a Python import. That works in one repository and fails quietly across many: a product that renames a field in its module's result shape will break the skeleton's event emission (recommendation.recorded.v1 requires recommendation) only at runtime.
A checked seam has three parts. The pattern declares the interface (the extended pattern file above writes it as a signature and a result shape). The factory checks at assembly that the product's module exists and matches, for example by calling it on the pattern's own fixture inputs and validating the result against the declared shape. And the result is validated again at runtime before it is recorded, because a module can pass a fixture and still return a malformed result for another input. That last check is where Example C's series shape (requires_human: true, policy_version, citations) becomes enforceable rather than conventional. Schema Engineering treats contract validation and repair as its own discipline.
Why switches in a pattern cannot be testedCombinations grow faster than products
Every boolean switch a pattern offers doubles the number of configurations it must work in. Ten switches is 1,024 configurations; the pattern team can test a handful, and each product runs one. The configurations that break are the ones nobody runs until a product needs them, and that product is the one that finds the bug in production. The arithmetic is illustrative. This site's view is that it explains why a pattern with many switches tends to be tested, in practice, only in the combinations its first products happen to use.
The defence is to prefer seams over switches. A seam has one contract and any number of implementations, each tested by the product that owns it. A switch has one implementation and many contracts, tested by nobody in full. When a switch is unavoidable, the pattern's own tests should cover every value of every switch at least once, and the catalog should record which products use which values, so a change can be tested against the combinations that exist. Factory learning loop covers the selective regression suite that makes that affordable.
Rule modules have their own version linePattern version, spec version, guide version
Example C carries three independent versions: the pattern (PAT-INTAKE-API 2.1.0), the spec (spec_version 1.0.0, plus its hash in the factory manifest) and the guide the rules implement (policy_version 2026.2, written into every recommendation). They change on different schedules and for different reasons, and an audit question ("why did SUB-1004 get escalated?") needs all three to be answered.
The governance consequence: a release of the service is identified by the triple, not by the pattern version alone. A guide change that keeps the pattern and spec unchanged is still a behavior change for underwriters, and it needs the domain review path and the product's golden cases, even though the factory's own gates might see no difference in the contract. Enterprise governance owns approvals; Insurance factory, part 3: trust owns the audit record that carries the versions.
In one breath#
An enterprise factory keeps three layers apart: the pattern holds plumbing and the rules that must never vary; configuration fills declared extension points with values the factory can validate; and each product's business-rule module holds decisions whose meaning lies in how facts combine. Example C shows all three in separate files, and also two honest limits: its S1 checks that an extension point exists, not what it says, and its rule seam is an import, not a checked contract. A shared rule template that turns logic into configuration fails silently on the first case it has no field for, as SUB-1003 showed.
The intake service now has a clear split: the skeleton from PAT-INTAKE-API, the values from SPEC-INTAKE-001, the rules in their own module. What the reader has not yet seen is the factory turning that spec into the actual intake endpoint, its schema checks, its error responses and the tests that prove each. Insurance factory, part 1: building the intake contract runs the factory and then sends real requests at what it built.