All chapters
  1. Start hereA software factory, from first principles
  2. Primitive · 1A factory, before AI: input, transformation, check, output
  3. Primitive · 2From repetition to a pattern: what stays, what varies, what to leave alone
  4. Primitive · 3The specification as an executable contract
  5. Primitive · 4Build the smallest factory: four stations, two specs, one manifest
  6. Primitive · 5Assembly stations: typed contracts, owners and failure handling
  7. Primitive · 6AI enters the factory: what a model adds, and what stays deterministic
  8. WatchAlgo · 7The WatchAlgo production story: what the repository shows
  9. WatchAlgo · 8A problem as a production unit: the files one unit must contain
  10. WatchAlgo · 9Station by station: description, solution, implementations, visualization
  11. WatchAlgo · 10The visualizer factory: from algorithm state to renderable steps
  12. WatchAlgo · 11Three flavors and three languages: two different contracts
  13. WatchAlgo · 12Looping over a large backlog: scheduling, limits and a failed-case queue
  14. WatchAlgo · 13Long-running agent execution: context, checkpoints and token limits
  15. WatchAlgo · 14Evidence of correctness: tests the producer cannot talk its way past
  16. WatchAlgo · 15The factory learning loop: defects change the pattern, not only the unit
  17. Enterprise · 16Classify the enterprise demand before choosing a pattern
  18. Enterprise · 17Reference enterprise patterns and their variation points
  19. Enterprise · 18Platform foundations: golden paths, templates, registries and catalogs
  20. Enterprise · 19Pattern versus configuration versus business logic
  21. Enterprise · 20Insurance factory, part 1: building the intake contract
  22. Enterprise · 21Insurance factory, part 2: building the underwriting workflow
  23. Enterprise · 22Insurance factory, part 3: trust and observability built in
  24. Enterprise · 23Data and integration engineering: contracts that survive change
  25. Enterprise · 24The CI/CD and deployment factory: from pull request to production
  26. Enterprise · 25Enterprise governance: owners, approved patterns and provenance
  27. Enterprise · 26Scaling safely: many teams, many agents, one set of boundaries
  28. Operations · 27Factory quality engineering: measuring accepted output, not activity
  29. Operations · 28Failure and recovery scenarios: what breaks a factory, and what restores it
  30. Operations · 29The landscape: which tool for which job, read from its own documentation
  31. Operations · 30Design an enterprise software factory: the blueprint and the rollout
  32. ReferenceSources and verification
  33. ReferenceGlossary
  34. AboutAbout this site
Enterprise · 19

Pattern versus configuration versus business logic

A factory skeleton with fixed seams and per-product rule modules. When a template turns into a brittle abstraction, and how to see it coming.

You will place
Every difference between two intake products in the pattern, the configuration or the rule module, with a reason for each.
You will read
Example C's pattern file next to its product spec, and an extended pattern file for the fields the example leaves out.
You will catch
A shared rule template that recommends approval for a submission with no roof age, without an error.

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.yml is configuration. Your @Service class 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 let application.yml turn 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.

LayerFileWhat it holdsChanges whenReviewed by
Patternpattern.json, service.py (the skeleton)8 skeleton steps, 11 extension points, 5 skeleton handlers, constraints such as human_decision_rolesthe platform team improves the plumbing for every productplatform team
Configurationproduct_spec.json4 roles, 5 routes, submission schemas v1 and v2, workflow states, 6 events, retry policy, rolloutthis product adds a field or a routethe factory's station S1 and the gates
Configuration of the rulespolicy_fixture.jsonthresholds: max_roof_age_years 25, max_gap_years 5, wind zone Cthe underwriting guide changes a numberguide owners
Business logicunderwriting.py : recommendwhich rule is checked first, what counts as missing, which evidence winsthe guide changes how rules combinedomain 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.

  1. Pattern
    1. authentication + role check: Every request passes the same two skeleton steps before any product code runs.
    2. schema validation + idempotency: The body is checked against the spec's schema; write routes need a key.
    3. step 6: business handler: The skeleton hands the request to the handler the route names.
    4. only underwriter decides: No spec can open the decision route to another role.
  2. Configuration
    1. roles + routes: Four roles and five routes, each naming who may call it.
    2. submission schemas: Field types, enums, ranges and patterns the skeleton validates.
    3. thresholds: Numbers the rule module reads, versioned with the guide.
  3. Business logic
    1. rule module: The product's own code, called through the seam, owned by the domain team.
    2. 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.

Fieldpattern.json (PAT-INTAKE-API 2.1.0)product_spec.json (SPEC-INTAKE-001)
Users and rolesconstraint: only underwriter decides; extension point roles4 roles: broker, underwriter, auditor, underwriting-agent
APIskeleton handlers; extension point routes5 routes with roles, bodies, idempotency, events
Dataextension points submission_schemas, decision_schema11 fields (v1), plus roof_material (v2)
External systemsconstraint: bounded retries; extension pointroof provider stub, 2,000 ms timeout, 3 attempts
Eventsconstraint: names carry a version; extension point6 event types with required fields
Security controlsskeleton steps authentication, role check; PII masking constraintPII field broker_email; demo bearer tokens
Deployment and environmentsextension point rollout3 environments, 5 percent canary, documentation only
Business-logic extension pointsextension point underwritingguide UW-GUIDE 2026.2, 4 rules, stand-in recommender
Frontendnot presentnot present
Databasenot present (in-memory store)not present
Testsnot 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.

  1. Shared template (a mistake)
    1. roof age missing: Neither the application nor the provider has a roof age.
    2. missing number becomes 0: A generic default every product inherits.
    3. no rule fired: approve: The template's fallback outcome, with no error.
  2. Product's rule module
    1. roof age missing: The same input.
    2. check missing first: Missing data is a finding under R-ROOF-02.
    3. 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.

OptionChoose it whenExample in the insurance factoryFailure mode if misplaced
Pattern (invariant or constraint)it must hold for every product, or breaking it is irreversibleonly underwriter decides; every request is auditedin a spec, one product turns it off
Configuration at an extension pointit is a value of a known kind the pattern can validateroute paths, role names, a 2,000 ms timeout, threshold 25in code, every product rewrites the same plumbing
Business-rule moduleit is a decision whose meaning lies in how facts combineR-ROOF-02 before R-ROOF-03 before R-ROOF-01in a template, a missing case is silently approved
Pattern change (new version)several products need the same new seama seam for a second external providerdone 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.

Fieldbroker-submission-intakeclaim-notice-intake (lab's own)Recommended
Authentication, role check, idempotency key, audit and versioned eventsthe same in boththe same in bothpattern
Rolesauditor, broker, underwriter, underwriting-agentauditor, claims-adjuster, intake-agent, policyholderspec
Submission fields12 fields (v2)6 fieldsspec
Workflow statesreceived to decided, 6 statesreceived to decided, 5 statesspec
Who decidesunderwriter (a person)claims-adjuster (a person)spec; that a person decides is pattern
External call and retryroof provider, at most 3 attemptspolicy administration lookup, at most 3 attemptsspec
Rule with a 25 thresholdR-ROOF-01: roof older than 25 years in zone Clate notice: more than 25 days after the lossproduct code
Rule with a 5 thresholdR-ROOF-03: roof ages differ by more than 5 yearsestimates differ by more than 5 percentproduct 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#

Checklist for Monday#

Exercises#

  1. 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.

  1. 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.

  1. 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.