MIGRATION.md — MIZ OKI 3.5: Definitive Integrated Migration

Finance + Media Acquisition into MIZOKICloudRun

Version 3.5.0 · Three domains, each validated-then-built · 2026-07-10

This is the single migration path carrying the three packages into the production repo. Both domain blueprints were externally validated BEFORE build (financial: 2026-07-09; media: 2026-07-10), and every validation correction is encoded in code, not just documented.

What ships

shared/
├── miz_oki_source_of_truth.py    # THE canonical authority — wins all conflicts
├── virtuoso_models/              # model routing: 4 locked flagships + fallback
├── mizoki_finance/               # Financial ReasoningPath Intelligence Layer
├── mizoki_media/                 # Media Acquisition Intelligence Engine
└── mizoki_cre/                   # CRE Underwriting & Asset Risk Intelligence Cell

Dependency order (import direction, no cycles): miz_oki_source_of_truth ← virtuoso_models ← mizoki_finance / mizoki_media / mizoki_cre

Migration steps

1. Place the packages

Copy all four into the repo's shared lib path (wherever cells import cross-cell code). If cells build as independent images, vendor into the base image or publish as internal wheels.

2. Startup conformance (every cell)

from miz_oki_source_of_truth import check_conformance
from virtuoso_models import assert_no_legacy_strings

@app.on_event("startup")
async def guard():
    violations = check_conformance()
    if violations:
        raise RuntimeError(f"SOURCE OF TRUTH violations: {violations}")
    for cfg in Path("/app/config").rglob("*.y*ml"):
        assert_no_legacy_strings(cfg.read_text(), source=str(cfg))

A cell that drifts from the truth file refuses to boot. That is the point.

3. Purge legacy strings (repo-wide, before deploy)

grep -rn -E "gemini-2\.0-flash|gemini-3-pro-preview|grok-4-1|grok-4-fast|claude-opus-4-[0-7]|gpt-5\.[0-4]|imagen-4\.0|image-preview|google_search[^_]" \
  --include="*.py" --include="*.yaml" --include="*.yml" --include="*.json" .

Note the last pattern: ambiguous google_search channel strings must become google_search_brand / google_search_nonbrand (GQV confounding correction — the schema enforces it at runtime, but fix configs too).

4. Wire the domain cells

Finance (REASON/DECIDE cells):

from mizoki_finance import reasoning_pipeline            # full SRPVDAL flow
from mizoki_finance.bridge import reason_hypotheses      # LLM via registry
from mizoki_finance.proof_card import card, render_markdown

Media (acquisition cells):

from mizoki_media import (IdentityEnvelope, MediaEvent, MdesEngine,
                          IncrementalityEvidence, ope_report)

The HMAC key for IdentityEnvelope comes from Secret Manager on SEPARATE infrastructure from the graph stores. Wire deletion_sink to the real suppression pipeline (BigQuery DML + Neo4j detach-delete + activation blocklists) so erasure propagates.

CRE (underwriting cells + Chrome Boss Agent backend):

from mizoki_cre import (NoiValidation, CreMonteCarlo, DealInputs,
                        CreReasoningPath, BenchmarkProgram, ModelInventory)

The Chrome extension's cre_underwriting_integration calls these services; verify the extension's six-tool registration against this package via the Claude Code integration prompt (internal claim — repo-level verification). Every model registers in the ModelInventory with an independent validator (SR 11-7); benchmark phases unlock sequentially from Phase A extraction.

5. Secrets per cell

GEMINI_API_KEY, ANTHROPIC_API_KEY (EVERY cell — the global fallback needs it), OPENAI_API_KEY, XAI_API_KEY, IDENTITY_HMAC_KEY (media cells only, separate KMS keyring).

6. Non-negotiables carried into production

Rule Enforced by
No path to DECIDE without a passport (finance) ValidationLab — no bypass parameter exists
High score alone never unlocks budget expansion (media) MdesEngine.band_for demotes without ladder authorization
High-blast-radius actions halt at a human gate OperatorGate — execution stops, not flags
Tokens are pseudonymized personal data IdentityEnvelope — consent-gated activation, erasure propagation
EEA/UK: native TCF, no IP matching IdentityEnvelope.activate
Brand/non-brand search separated MediaEvent.__post_init__ raises on ambiguity
LLMs draft, never decide bridge.py prompts + gate architecture
Model routing from one registry, fallback tagged virtuoso_models
Threshold raises are human-approved and logged MdesEngine.raise_threshold
Simulation passports carry baselines + bands or are invalid SimulationPassport.valid()
t-copula primary only with stable calibration calibration_gate fallback to bootstrap
Phase B uses multi-year actuals (Griffin-Priest) PhaseBRun.multi_year_mape raises otherwise
Model validator independent of owner (SR 11-7) ModelRecord.__post_init__ raises
Binding valuation/credit stays with licensed humans CRE_REGULATORY_ANCHORS + requires_human()
AVM QC rule never cited as CRE obligation conformance check verifies the rescope

7. Deploy sequence

  1. Branch feat/miz-oki-3.5-integrated, commit the four packages.
  2. Run the shipped self-test suite in CI (it IS the test suite — 20 checks across all four packages plus conformance): pip install jsonschema --break-system-packages && python selfcheck.py (exit 0 required; the jsonschema install flag matters — a silent install failure once masked a schema bug, see AUDIT.md #1/#2).
  3. Deploy to staging; run one live call per model role; verify served_by="primary" and a forced-failure fallback.
  4. For media: run the consent envelope against a real CMP TCF string and verify erasure propagates to all three stores before ANY activation traffic.
  5. For CRE: run Phase A extraction on the firm's own messiest scanned leases before trusting vendor accuracy claims; register every model with an independent validator; confirm the Chrome extension wiring via code review (Claim 9 was internal-unverifiable by design).
  6. DPIA sign-off (automated decisions over pseudonymized data), then production behind observe/recommend autonomy; graduate bands only with measured error budgets.

Standing limits (unchanged in kind, stated plainly)

Verified in isolation against deterministic stubs and mocked SDK calls — not against live cells, live keys, real market data, real ad platforms, or a real CMP. The trained models (regime engines, TGNN, uplift) plug in via hooks and stay behind their gates until they clear the domain thresholds on point-in-time data. Securities counsel before client-facing financial advisory output; DPIA before media activation.

Placement record (executed 2026-07-13)

Migration step 1 was executed on branch feat/virtuoso-models-cloudbuild-ci:

Addendum — scope corrections (2026-07-27, MIZ-REC-2026-003)

This document remains the record of the July-13 domain-package placement and of the startup-conformance doctrine ("a cell that drifts refuses to boot"). Four statements in it are now superseded or stale:

  1. "THE canonical authority — wins all conflicts" is scoped to VALUES. After the remediation-layer integration, mizoki_contracts (repo-root contracts/) is the authority for shapes — the Canonical Event Envelope and the eight decision objects. miz_oki_source_of_truth.py remains the authority for values: thresholds, model pins, non-bypassable rules, phase owners. Where the two disagree about a shape, the contracts package wins; where they disagree about a value, the source of truth wins. See docs/INTEGRATION_PLAN.md §2.
  2. The ships-list predates the six-domain expansion. It omits mizoki_core, mizoki_counsel, mizoki_estate and mizoki_risk, all of which the source of truth has governed since v3.5.1.
  3. The placement record's cleanup claim is inaccurate. It states the miz_oki_3.5_integrated/ staging tree was removed; it still exists and still carries a v3.5.0 copy of the source of truth with superseded model strings. That copy is a deliberate work-product record — do not sync it over src/shared/.
  4. The legacy-string purge grep no longer matches current retirements (e.g. claude-opus-4-[0-7] does not match -4-8). Re-derive the patterns from virtuoso_models.model_registry.forbidden_legacy rather than reusing the literals here.
← All docsView source on GitHub →