Pattern Assimilation

Checkable pattern assimilation from landed evidence

pattern_assimilation_step turns a pass's claim to have learned something from uncheckable commit prose into a typed record a validator can read. pattern_assimilation_step checks whether a development pass that claims to have learned something actually filed an inspectable record of it. When a component lands in the system, someone is supposed to close it out with a decision: either this run changed a named artifact, or it changed nothing and here is why. That decision is usually prose in a commit message. Prose cannot be checked. This component forces the decision into a typed record and validates the record.

Over landed-component rows and their completions, it confirms each landing has one same-lane completion that names its surface, carries its no-op fields, and never promotes a local lesson into global doctrine. It runs over fixture data, not live state. Given a set of landed-component rows and the completion records that go with them, it confirms that each landed component has exactly one same-lane completion, that a claimed change names the surface it touched, that a "nothing to refine" record carries its required fields, and that no record promotes a local lesson into global doctrine. The output is a result record listing which checks passed and which named negative cases fired.

sign-off.py is the entry point, with a fixture lane over the completion records directly and a bundle lane over an exported package plus copied source bodies. The entry point is src/microcosm_core/validators/sign-off.py. It has two lanes: a fixture lane that validates the completion records directly, and a bundle lane that validates an exported package of the same records plus copied source bodies.

Purpose

The unbacked learning claim

The failure guarded against is a learning claim nobody can audit, where loose prose about improving or finding nothing drifts free of the artifacts. The failure this guards against is the unbacked learning claim. A pass says it "improved the fixture" or "found nothing to refine", and nobody can tell whether that is true. Loose prose is easy to assert and impossible to audit, so the learning story drifts away from the artifacts.

Typed fields a validator can read

The fix makes each completion a validator-readable record: a change names its owner surface and artifact, a no-op proves stewardship, next-best lane, and re-entry, and a missing or mismatched completion is rejected. The fix is to make each completion resolve to a record with fields a validator can read. A concrete change record must name an owner_surface and the artifact it touched. A nothing_to_refine record must prove three things: stewardship was checked, the next-best lane was considered, and a re-entry condition was written down. A landed component with no completion, or with a completion that points at a record that does not exist or does not match, is rejected.

A local lesson cannot self-promote to doctrine

A lesson may route to the owner surface of its artifact but never promote itself to global doctrine; a record setting claims_global_doctrine_authority is rejected outright. One constraint the component will not relax: a local lesson may route to the owner surface that owns the affected artifact, but it may not promote itself into global doctrine. A change record that sets claims_global_doctrine_authority is rejected outright. Learning has to land on a specific board with a named steward, not become a free-floating rule.

How it works

The fixture lane in validate_pattern_assimilation

validate_pattern_assimilation loads four inputs, scans them for non-public-state leakage, runs the row checker, and passes only when every expected negative case fired, the scan is clean, and nothing blocked. The fixture lane runs in validate_pattern_assimilation. It loads four input files (_load_inputs), scans them for non-public-state leakage (_scan_fixture_inputs), runs the row checker (_validate_rows), then compares the negative cases that fired against EXPECTED_NEGATIVE_CASES. The run passes only when every expected negative case was observed, the non-public-state scan is clean, and no blocking finding was raised. Results are written by write_outputs.

Per-row validation in _validate_rows

_validate_rows pre-filters change and no-op records down to the valid ones, then walks each landed row to raise a missing, unresolved, or duplicate finding. _validate_rows is the mechanism. It first pre-filters the completion records into valid ones. A change record is valid when it has a result record id and component id, its refinement_result is fixture_manifest_refined or validator_contract_refined, it names an owner_surface, and it does not claim global doctrine authority. A no-op record is valid when its refinement_result is nothing_to_refine and it carries stewardship_checked, next_best_lane_checked, and a reentry_condition. It then walks each landed row: a row with no completion result raises MISSING_PATTERN_ASSIMILATION_CLOSEOUT; a row whose declared completion does not resolve to a matching valid record raises PATTERN_ASSIMILATION_CLOSEOUT_RECEIPT_REF_UNRESOLVED as a blocking finding. Duplicate result record ids across both record sets raise DUPLICATE_REFINEMENT_RECEIPT_ID so one lesson cannot be counted twice.

Resolving the landing result record reference

_validate_public_safe_receipt_ref confirms each landing's referenced record sits inside a public root, parses as .json or .jsonl, passes the scan, and hashes, blocking any absent or unsafe citation. Each landed row also names a landing result record, and _validate_public_safe_receipt_ref resolves that reference. It confirms the ref points inside a public result record root, is a .json or .jsonl file that parses, passes the non-public-state scan, and hashes it. A ref that escapes the public roots, is missing, has the wrong suffix, or trips the scan becomes a blocking finding, so a completion cannot cite a record that is absent or unsafe.

The bundle lane in run_assimilation_bundle

run_assimilation_bundle runs per-part checkers over an eight-part export, then verifies copied source bodies against their recorded sha256, passing only when the scan is clean and every checker is empty. The bundle lane runs in run_assimilation_bundle. It loads an eight-part export (_load_assimilation_bundle) and runs a chain of per-part checkers: validate_exported_organ_landings, validate_exported_refinement_receipts, validate_exported_nothing_to_refine_receipts, validate_exported_closeout_receipt_links, validate_exported_stewardship_checks, validate_exported_reentry_conditions, validate_exported_next_best_lane_checks, and validate_exported_assimilation_policy. It then verifies copied source bodies through validate_source_module_manifest, which reads source_module_manifest.json, requires body_in_receipt to be false, and, for each copied module, checks its declared class is in PUBLIC_SAFE_SOURCE_BODY_CLASSES, the target file exists, and its recorded sha256 matches the file on disk. A mismatch raises ASSIMILATION_BUNDLE_SOURCE_MODULE_INVALID. The bundle passes only when the scan is clean, every checker is empty of findings, and each record set is non-empty; a stable fingerprint hash of the inputs is stamped into the result.

Atomic result writes and CLI dispatch

_write_jsonl_upsert atomically replaces a run's own row instead of duplicating it, and main dispatches the bundle and fixture lanes, each returning 0 on pass and 1 on block. Result records are written by _write_jsonl_upsert for the append-only run log: it drops any prior line with the same run_id, appends the new row, and swaps the file in atomically through a temp file and os.replace, so a re-run replaces its own row instead of duplicating it. The CLI dispatch is main: the validate-assimilation-bundle subcommand runs the bundle lane, and --only pattern_assimilation_step --input --out runs the fixture lane. Each returns 0 on pass, 1 on block. The stamped scope limit is the constant PATTERN_ASSIMILATION_AUTHORITY_CEILING.

flowchart TD inputs["Four fixture files landings + change + no-op + missing-case"] scan["non-public-state scan _scan_fixture_inputs"] rows["Row checker _validate_rows"] filter["Pre-filter valid records change: owner surface, no doctrine upgrade no-op: stewardship, next-best lane, re-entry"] walk{"Per landed row: one completion, ref resolves to a matching valid record?"} compare["Compare fired cases vs EXPECTED_NEGATIVE_CASES"] out["Result records write_outputs, _write_jsonl_upsert"] inputs --> scan scan --> rows rows --> filter filter --> walk walk -->|resolved| compare walk -->|missing, dangling, duplicate, upgraded| compare compare --> out

Negative cases

A silenced check blocks the run

Every required negative case must fire on the fixture, and any case that stops firing blocks the run because a check has gone silent. The fixture is built to make every required negative case fire. If any stops firing, the run blocks, because that means a check has gone silent.

The reason code each attempt raises

Each gaming shape maps to a named code: missing completion, missing owner, stewardship, or re-entry fields, duplicate result record, doctrine self-upgrade, a seed body in the fixture, and a bundle source mismatch. MISSING_PATTERN_ASSIMILATION_CLOSEOUT fires for a landed component with no change record and no typed no-op record. MISSING_REFINEMENT_OWNER_SURFACE, MISSING_STEWARDSHIP_CHECK, and MISSING_REENTRY_CONDITION fire for records that cannot route the lesson to an owner surface and a re-entry condition. DUPLICATE_REFINEMENT_RECEIPT_ID fires for a repeated result record id. LOCAL_LESSON_AUTHORITY_UPGRADE fires for a local lesson that claims global doctrine authority. RAW_SEED_BODY_IN_ASSIMILATION_FIXTURE fires when a seed-origin body appears in the public fixture, and the body is rejected and redacted. In the bundle lane, ASSIMILATION_BUNDLE_SOURCE_MODULE_INVALID fires on a copied-source digest or class mismatch.

Prior Art Grounding

Pattern languages and provenance tracing

The design draws on software pattern-language practice for naming context-bound lessons and on provenance and tracing practice for citing owner surface and touched artifact, applied here to completion bookkeeping only. The idea of naming recurring engineering lessons and binding each to its context comes from software pattern-language practice; the Hillside patterns library is the direct lineage for treating patterns as shared vocabulary rather than one-off notes. The record shape borrows from provenance and tracing practice: W3C PROV informs the rule that each change record cite its owner surface and the artifact it touched, and OpenTelemetry traces are a fair analogue for linking work into an inspectable chain. This component applies those ideas to completion bookkeeping only.

Validation Result record Path

Running the assimilation fixture lane

From microcosm-substrate, run the fixture lane and the bundle lane into an isolated /tmp output so scratch records do not overwrite tracked files: From microcosm-substrate, run the fixture lane and the bundle lane into an isolated /tmp output so scratch records do not overwrite tracked files:

Focused test re-entry:

PYTHONPATH=src ../repo-python -m pytest -p no:cacheprovider \
  tests/test_pattern_assimilation_step.py -q \
  --basetemp=/tmp/microcosm_pattern_assimilation_pytest

What a pass and a block mean

A pass means the fixture completions had the required typed shape and every negative case fired; a block means a completion was missing, dangling, duplicated, over-claiming, or drifted from its digest. A pass means the supplied fixture completions have the required typed shape and every required negative case fired. A block means a completion is missing, dangling, duplicated, or over-claiming, or a copied source body drifted from its recorded digest.