feat: compile governance lineage Iceberg Atlas - #168
Conversation
Spec Compliance ReportTraceability Audit
Invariant Validators
Ruff Lint✅ Exit code: 0 Tests & Coverage✅ Tests exit code: 0
|
|
Warning Review limit reached
Next review available in: 59 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (19)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Backlog engagement 2026-07-19 — disposition: evolving. Verified live state before touching: MERGEABLE/CLEAN and all checks green ( |
There was a problem hiding this comment.
Pull request overview
This PR introduces Engine-owned “distill” and “render” cadence stages for governance lineage compilation and deterministic Iceberg Atlas generation, including durable receipt custody resolution and extensive contract-style tests to ensure exact digest-bound outputs and fail-closed semantics.
Changes:
- Add bounded governance cadence owner adapters (
distill/render) plus read-only predicates and contracts to validate digest bindings, readiness derivation, and proof traversal behavior. - Implement the deterministic Iceberg Atlas compiler (dual timelines, six zooms, quarantine/cursor resumption, readiness gating, and optional “blocked but renderable” output without emitting verified events).
- Add Engine durable receipt resolution by convention (
receipt:engine:<key>→receipts/engine/<key>.json), plus custody docs/fixtures and pin RFC 8785 canonical JSON dependency.
Reviewed changes
Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
tests/test_governance_receipt_custody.py |
Verifies receipt:engine:* resolution, digest exactness, and public-safe custody constraints. |
tests/test_governance_cadence.py |
Contract tests for distill/render adapters, predicates, bounded denominator enforcement, and proof traversal invariants. |
tests/test_governance_atlas.py |
Large regression fixture suite for Atlas determinism, quarantine, readiness gating, resumable cursor, and redaction behavior. |
src/organvm_engine/testament/receipt_registry.py |
Adds convention-based durable Engine receipt resolver. |
src/organvm_engine/testament/iceberg_atlas.py |
Implements deterministic Iceberg Atlas compiler/renderer, receipt emission, and event spine behavior. |
src/organvm_engine/testament/governance_compiler.py |
Adds bounded candidate-testament compiler with non-ratifying/corroboration rules. |
src/organvm_engine/testament/governance_cadence.py |
Adds distill/render owner commands that compile in temporary custody, validate, then atomically install outputs. |
src/organvm_engine/testament/governance_cadence_predicate.py |
Adds independent read-only predicate entrypoints for distill/render. |
src/organvm_engine/testament/governance_cadence_contract.py |
Adds shared pure validation contracts for owner/predicate including digest bindings and readiness semantics. |
src/organvm_engine/testament/__init__.py |
Re-exports Atlas compiler types/functions. |
src/organvm_engine/corpus/governance_lineage.py |
Adds/extends canonical JSON digesting + state normalization/finalization used by the Atlas compiler. |
src/organvm_engine/corpus/governance_bundle.py |
Adds local resolver for snapshot-bundle artifact references with exact digest verification. |
src/organvm_engine/corpus/__init__.py |
Exposes selected governance-lineage helpers from the corpus package. |
src/organvm_engine/cli/testament.py |
Adds CLI entrypoints for candidate-testament and iceberg-atlas compilation (dry-run/write modes). |
src/organvm_engine/cli/__init__.py |
Wires new testament subcommands into the top-level CLI dispatch. |
receipts/README.md |
Documents receipt custody conventions and a pinned candidate receipt digest. |
receipts/engine/candidate-testament-governance-native-20260716.json |
Adds a tracked Engine-owned candidate-testament receipt fixture. |
pyproject.toml |
Pins rfc8785==0.1.4 for canonical JSON. |
docs/governance-cadence-owner.md |
Documents owner command invocation, env bindings, and predicate behavior. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| "coverage": { | ||
| "exact_all": bool(bundle["coverage"]["exact_all"]) and not state["quarantine"], | ||
| "source_count": len(state["source_envelopes"]), | ||
| "event_count": len(bundle.get("normalized_events", nodes)), | ||
| "node_count": len(nodes), |
| root = ( | ||
| repository_root.resolve() | ||
| if repository_root is not None | ||
| else Path(__file__).resolve().parents[3] | ||
| ) | ||
| path = root / "receipts" / "engine" / f"{key}.json" | ||
| if path.is_symlink() or not path.is_file(): | ||
| raise ReceiptResolutionError(f"Engine receipt is not tracked: {reference}") |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0f7ecc0545
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| matching_nodes = [ | ||
| node | ||
| for node in nodes.values() | ||
| if node["source_envelope_id"] == source_id and node["lane"] == "operator_intent" | ||
| ] |
There was a problem hiding this comment.
In the render activation path, this match accepts any operator_intent node for the authority source. Nothing later requires review_state == "reviewed", so a ratified testament that references an immutable but still-unreviewed operator node is activated and can produce a ready Atlas/verified event. Please include the review-state check in the authority-node match before accepting the ratification.
Useful? React with 👍 / 👎.
| or normalized.get("authority_class") != "operator_intent" | ||
| or normalized.get("normalized_role") != "operator" | ||
| or normalized.get("identity_basis", {}).get("content_hash") | ||
| != source.get("body_hash") |
There was a problem hiding this comment.
In the render path, this condition binds the normalized authority event by id/source/content hash but never compares normalized["occurred_at"] with the source envelope/node timestamp. A normalized event with a stale or fabricated timestamp but the same content hash therefore still activates the directive and can emit a ready Atlas, whereas the candidate compiler rejects the same mismatch. Please add the timestamp check before accepting the authority event.
Useful? React with 👍 / 👎.
| quarantine_ids = [ | ||
| f"{item.get('reason', 'quarantine')}:{item.get('unit_id', 'unknown')}" | ||
| for item in finalized["quarantine"] | ||
| if isinstance(item, Mapping) | ||
| ] |
There was a problem hiding this comment.
For blocked renders with compiler quarantines, finalized["quarantine"] entries have diagnostic_id, collection, source_index, record_hash, and error_code, not reason or unit_id. This turns every compiler quarantine in the Atlas receipt into the same quarantine:unknown string, so multiple malformed children collapse into one debt item and the receipt no longer points operators at the hashed diagnostic they need to fix. Use the diagnostic id or record hash here instead.
Useful? React with 👍 / 👎.
| if paths.node_self_image_set is not None: | ||
| bundle["node_self_image_set"] = load_object(paths.node_self_image_set) | ||
| _validate_core_snapshot(bundle, require_ratified=require_ratified) | ||
| if require_ratified: |
There was a problem hiding this comment.
When require_ratified is false for the distill owner path, this skips the stronger bundle validation and returns after only core header checks; run_distill then derives readiness from the coverage and ideal-form ready fields. A candidate run with inconsistent coverage counts or a stale ideal-register self digest can still emit a ready distill projection, giving downstream ratification a false readiness signal. Add equivalent coverage semantics and self-digest validation before computing distill readiness.
Useful? React with 👍 / 👎.
| for source in bundle["source_envelopes"] | ||
| if isinstance(source, Mapping) | ||
| } | ||
| or detail.get("assertion_evidence") != bundle["assertion_evidence"] |
There was a problem hiding this comment.
When a render input contains more than one assertion and the JSONL/array is not already sorted by assertion_id, the compiler normalizes state["assertions"] into sorted order before writing detail["assertion_evidence"], but the predicate compares that list to the original input order here. Valid owner artifacts in a different order therefore fail with Atlas receipt does not bind its direct owner artifacts. Compare assertions by id, as the source-envelope check does, or preserve input order.
Useful? React with 👍 / 👎.
| self._receipt_event( | ||
| str(bundle["snapshot_id"]), | ||
| input_digest, | ||
| artifact_digest, | ||
| ) |
There was a problem hiding this comment.
For a ready Atlas through the public compiler/CLI, _receipt_event appends to the Event Spine before any atlas, detail, receipt, or cursor file is written. If one of those writes fails, for example because the output directory is full or not writable, the append-only spine retains a testament.verified event for artifacts that were never materialized. Stage the event until after successful artifact/cursor writes or write it in the same temporary custody.
Useful? React with 👍 / 👎.
| assertion_reference = ratification.get("assertion_evidence_reference") | ||
| assertion_reference_is_id = assertion_reference in assertions | ||
| operator_assertions = [ | ||
| assertion | ||
| for assertion in resolved_assertions | ||
| if ( | ||
| not assertion_reference_is_id | ||
| or assertion["assertion_id"] == assertion_reference |
There was a problem hiding this comment.
When assertion_evidence_reference is present but does not match an assertion id, assertion_reference_is_id is false and this filter stops constraining the operator assertion at all. A typo or stale ratification reference such as assertion:does-not-exist still activates any cited operator-directive assertion and can produce a ready Atlas/verified event. Treat an unresolved assertion reference as debt instead of disabling the check.
Useful? React with 👍 / 👎.
| "node_self_image_set": { | ||
| **deepcopy(bundle["node_self_image_set"]), | ||
| "self_images": deepcopy(state["self_images"]), | ||
| }, |
There was a problem hiding this comment.
For bundles with multiple self-images whose input order differs from the compiler's sorted state order, this replaces the original self_images list while preserving the original set_digest. The render can still be ready, but node_self_image_set in the private detail no longer verifies against its own sha256-rfc8785-excluding-self-digest-v1 digest. Preserve the original contract projection or recompute the digest for the rewritten body.
Useful? React with 👍 / 👎.
| if ratified_input: | ||
| if verification_state != "verified" or not constitutional_evidence: | ||
| raise ValueError( | ||
| "ratified input requires verified constitutional assertion evidence", | ||
| ) |
There was a problem hiding this comment.
For ratified inputs, this requires every assertion in the bundle to carry a ratified_constitutional_record. A legitimate ratified snapshot that also includes verified external/current-state assertions without constitutional-record evidence cannot be reprojected into its exact candidate, even though only the operator-directive assertion needs that ratification backing. Apply this requirement only to the referenced/cited directive assertion.
Useful? React with 👍 / 👎.
| custody = source.get("custody_snapshot") | ||
| if not isinstance(custody, Mapping) or custody.get("immutable") is not True: | ||
| raise ValueError("candidate source envelope is not immutable") |
There was a problem hiding this comment.
The public candidate compiler accepts any immutable source envelope here without checking that its custody_snapshot.snapshot_id matches the candidate bundle's snapshot_id. A candidate can therefore be marked ready_for_owner_ratification while one of its cited native operator sources is from a different custody snapshot. Include the snapshot binding check before adding the source to the candidate authority set.
Useful? React with 👍 / 👎.
Summary
unverifieduntil CORPVS ratificationstrict=False) without emitting a verified Event Spine eventBounded cadence owners
Engine now owns the
distillandrenderstages in Limen's nine-stage cadence.distillconsumes direct source/event/lineage/assertion/coverage/ideal/testament artifacts and emits an exact non-ratifying candidate plus compiler receipt.renderrequires the CORPVS-ratified testament and reconciled node self-image set, then emits the public Atlas, private detail, Atlas receipt, cursor, event-spine projection, and typed owner projection.LIMEN_GOV_MAX_ITEMS.Readiness semantics
readyrequires valid snapshot contracts and self-digests, exact source coverage, a ratified evidence-backed testament, verified assertions, receipt-derived complete ideals and self-images, nonempty operator and artifact timelines, all six populated zooms, reviewed relationships, zero citation debt, and zero compiler quarantine.Blocked compilation still materializes a deterministic Atlas and receipt with the exact debt. It does not emit a verified Atlas event. A missing immutable event, blocked constitutional scope, fabricated identity, handwritten pass value, stale digest, single-source assertion, or missing zoom therefore cannot become a false
ready.Real frozen evidence
Against frozen snapshot
governance-native-20260716, the newdistillowner processed 125,985 bounded units and produced:sha256:1082c824d2608eefef63de75963a47289fafb44663ee358aa259381f6197cd6cexact_all: trueready: falseclosed_with_owner_routed_debtThe independent real predicate passed. A proof traversal produced an exact
skipped_completedchild with the prior receipt digest and zero events.Verification at exact head
0da635bruff check src/ tests/ --ignore SIM105): passedgit diff --check: passedThe broader repository test attempt reached 5,298 passing and 71 skipped tests; remaining failures were environment/optional-dependency cases outside these changed governance modules. The prior exact-head CI exposed one COM812 formatting failure;
0da635bcorrects it and passes the exact lint command locally. Current-head public CI remains the remote authority.Dependency and honest boundary
The baseline public contracts are merged through schema-definitions #10. This branch additionally consumes the proposed denominator and raw-unit/cadence contracts in schema-definitions #11 and #12, plus direct Ontologia/CORPVS owner artifacts.
This PR does not itself ratify CORPVS or acquire inaccessible exports.
distilldeliberately stops at a candidate, andrenderdeliberately refuses that candidate. CORPVS must materialize the exact authority transition before the final render can execute. Global readiness remains false until that transition, self-image reconciliation, the blocked source debt, and the full two-traversal cadence are all resolved.