Skip to content

M1 remediation handoff (EstateComparison architecture)

Issue: hector-sanchez-eu/conductor#3
Brief: brief.md
External review: review.md
Current implementation: draft PR branch codex/gate-c-discovery-scope M1 status: verified

Latest external decision

  • Gates A-D are approved and Gate D's candidate import is complete.
  • The M1.5 real-estate pilot reviewed six Assets and six relationships.
  • Live fresh-process retrieval passes physical validation and complete approved-scope Notion/GitHub enumeration, but correctly returns insufficient-context.

Governing instruction

External architectural recommendation: stop incremental bypass patching. Physical decoding, completeness, semantic assertions, and reuse decisions must not cross an open dictionary authority boundary.

Historical decision context

  • Gate A: approved (originally design-only; Gate D subsequently authorized and completed mutation).
  • Gate B: was changes-requested after event-bound re-review of 636f06d (payload not bound, overbroad classes, fake evt.*, orphan batch escape, forgeable Boolean, repos/envs omitted).

Remediations in this pass

  1. Typed EstateComparison — frozen dataclass with full decisive payload (claims polarity/text/citations, dispositions, no-gap, extend). Parsed from Decisions/Events comparison_payload + asserted_need / claim/disposition IDs (estate_comparison.py).
  2. Opaque ExhaustiveSnapshot — adapter-seal factory only; Boolean/search_coverage exhaustiveness ignored.
  3. Evaluator rewrite — evaluate_reuse consumes only EstateComparison + ExhaustiveSnapshot + mapped Assets. Caller dictionaries never authorize.
  4. Physical Decision/Event schema — asserted_need, claim_ids, disposition_ids, comparison_payload documented on Decisions/Events; comparison authority limited to estate-comparison / portfolio-disposition.
  5. Global batch validation — all Assets/repos/envs/evidence/relationships/events (including orphans); no evt.* prefix trust; duplicate index keys fail; relation has_more fails closed.
  6. Preparation path — queries repositories/environments; builds snapshot after batch validation; parses need-matching comparison events.
  7. Invariant test — mutating caller search_coverage / Boolean / raw events cannot change a decisive outcome.

Reproduction / invariant negatives

  • caller_dict_cannot_change_decisive_outcome
  • reinterpreted_claim_payload_cannot_authorize
  • other_event_class_rejected_by_parser
  • fake_event_extend_unresolved
  • orphan_batch_validation_catches_malformed_rows
  • exhaustive_snapshot_requires_adapter_seal

Deferred downstream execution

These are not M1 blockers:

  1. Unattended GitHub authentication is decided with the M3 runtime.
  2. Broad candidate triage is performed by the future preparation/review workflow, not manually before that workflow exists.
  3. A request-bound decisive EstateComparison and exhaustive snapshot are M4 golden-path evidence.

M1 independent verification passed at PR #14 head 5f738f9.

Validation

powershell python -m pytest service/tests/test_read_adapters.py -q python -m pytest service/tests -q python -m mkdocs build --strict

Current result: 48 focused tests and 86 service tests pass; strict docs build passes.

Independent verification remediation

The first independent M1 verification found two blockers:

  1. comparison, batch, and caller-declared completeness could be issued independently and combined into a forged decisive result;
  2. the approved gh-operator mode was documented but absent from the service adapter.

The current implementation binds an exhaustive snapshot to adapter-issued read envelopes, the complete validated physical batch, its exact Decision/Event, estate IDs, source completeness, request, and comparison digest. An unrelated batch or free-form completeness input cannot issue a snapshot. A regression fixture reproduces the forged parser/batch/snapshot chain and receives insufficient-context.

GitHub reads now support bounded gh repo list calls for approved owners, remove environment token variables from the subprocess, and disclose auth-mode: gh-operator in provenance. Dedicated read tokens remain an optional M3 unattended mode.

Independent re-verification returned VERIFIED. Evidence: PR #14.