sable-sphynx 0.7.0.dev0__py3-none-any.whl

sphynx/integrated_workflow.py

@@ -0,0 +1,552 @@
+"""Protected grading and stage access for actual integrated RAG execution.
+
+The configured factory registers one explicit domain policy. Custom evaluators,
+review protocols and report shapes can instead register IntegratedDriver with
+LifecycleBackend. Neither path changes the neutral orchestration contracts.
+"""
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+import json
+import math
+
+from .assessment_contracts import Assessment, EvidenceView, _thaw
+from .integrated_rag import (
+    INTEGRATED_SCHEMA, INTEGRATED_STAGE_SCHEMA, INTEGRATED_STAGES, IntegratedDriver,
+    build_context, validate_answer,
+)
+from .integration_contracts import require_digest, value_digest
+from .lifecycle import LifecycleGradingRef, LifecycleJournal, RunPolicy, _selection
+from .lifecycle_workflow import LifecycleBackend, _comparison_require
+from .pipeline import _score
+from .pipeline_workflow import _CASE_SCHEMA, _validate_case
+from .stage_contracts import (
+    STAGE_EVIDENCE_CAPABILITY, StageContractError, StageEvidence, StageSelector,
+)
+from .workflow_contracts import (
+    Criterion, Dataset, DatasetDefinition, EvaluatorDefinition, MetricSpec,
+    PayloadSchema, SuiteDefinition, WorkflowContractError, contract_digest,
+)
+from .workflow_registry import WorkflowRegistry
+
+_REFERENCE = "sphynx.rag.integrated.references.v1"
+_REPORT = "sphynx.rag.integrated.report.v1"
+_EVALUATOR = "sphynx.rag.integrated.evaluator.v1"
+_REDUCER = "sphynx.rag.integrated.equal-case-trial-mean.v1"
+_COMPARISON = "sphynx.rag.integrated.paired-delta.v1"
+_PREFIX = "sphynx.rag.integrated."
+_NUMERIC = ("execution_completed", "routing_correct", "retained_pool_ndcg_at_5",
+            "retained_pool_recall_at_5", "context_count")
+_CRITERIA = tuple(_PREFIX + name for name in (*_NUMERIC, "answer_semantic_quality"))
+_RANKING_POPULATION = {
+    "boundary": "N17_retained_stage_pool",
+    "denominator": "retained_inherited_chunk_pool",
+    "source_truth_rule": "native_complete_source_span_inheritance.v1",
+    "duplicate_credit": "overlapping_or_duplicate_inherited_chunks_receive_separate_native_credit",
+    "interpretation": "conditional_stage_pool_diagnostic_not_fixed_source_evidence_recall",
+}
+_RANKING_LIMITS = ["ranking_diagnostics_condition_on_retained_inherited_chunk_pool",
+                  "overlapping_or_duplicate_chunks_receive_separate_native_credit",
+                  "not_end_to_end_source_evidence_recall"]
+
+
+def _metric_population(name):
+    return {"selection": "first_success_or_last_failed_per_case_trial", "missing": "excluded_with_coverage",
+            **(_RANKING_POPULATION if name.startswith("retained_pool_") else {})}
+
+
+def _require(value, message):
+    if not value:
+        raise WorkflowContractError(message)
+
+
+def _validate_reference(value):
+    _require(type(value) is dict and set(value) == {"source_sha256", "source_version", "task"},
+             "integrated reference fields differ")
+    _require(type(value["task"]) is dict and type(value["task"].get("should_call_rag")) is bool,
+             "integrated source reference is incomplete")
+    _require(all(type(value[key]) is str and value[key] for key in ("source_sha256", "source_version")),
+             "integrated reference revision is incomplete")
+    require_digest(value["source_sha256"], "reference source sha256")
+
+
+def _validate_stage(value):
+    required = {"schema_version", "run_id", "case_id", "trial", "attempt", "stage_id", "occurrence",
+                "operation", "input_digest", "input", "output", "output_digest", "status", "implementation"}
+    _require(type(value) is dict and required <= set(value)
+             and set(value) <= required | {"parent_elapsed_seconds", "error_type"},
+             "integrated stage fields differ")
+    _require(value["schema_version"] == INTEGRATED_STAGE_SCHEMA and value["stage_id"] in INTEGRATED_STAGES
+             and type(value["occurrence"]) is int and value["occurrence"] == 1
+             and value["status"] in {"started", "completed", "failed"},
+             "integrated stage identity/status differs")
+    _require(all(type(value[key]) is str and value[key] for key in ("run_id", "case_id", "operation"))
+             and all(type(value[key]) is int and value[key] > 0 for key in ("trial", "attempt"))
+             and type(value["input"]) is dict and type(value["implementation"]) is dict,
+             "integrated stage identity/payload types differ")
+    _require(value["input_digest"] == value_digest(value["input"]), "integrated stage input digest differs")
+    if value["status"] == "completed":
+        _require(value["output_digest"] == value_digest(value["output"]), "integrated stage output digest differs")
+    else:
+        _require(value["output"] is None and value["output_digest"] is None, "uncompleted stage has an output")
+    if "parent_elapsed_seconds" in value:
+        n = value["parent_elapsed_seconds"]
+        _require(type(n) in (float, int) and math.isfinite(n) and n >= 0, "stage wall observation differs")
+
+
+def _validate_report(value):
+    _require(type(value) is dict and value.get("schema_version") == _REPORT
+             and set(value) == {"schema_version", "run_id", "grading_id", "candidate", "scope", "metrics",
+                               "counts", "selection", "assessment_rows", "trust_tier", "limitations"},
+             "integrated report fields differ")
+
+
+def _evaluate(context):
+    """Deterministic source-bound diagnostics; no inferred answer-quality label."""
+    output = _thaw(context.outputs)
+    reference = _thaw(context.references)
+    _require(reference["task"]["task_id"] == context.case.case_id, "reference belongs to another case")
+    fields = dict(evaluator_id=_EVALUATOR, case_id=context.case.case_id,
+                  run_id=context.run_id, grading_id=context.grading_id,
+                  trial=context.metadata["trial"], attempt=context.metadata["attempt"],
+                  evidence_ids=tuple(e.evidence_id for e in context.evidence))
+    def assessment(name, kind, value=None, availability="available", reason=None):
+        return Assessment(_PREFIX + name, kind=kind, value=value, availability=availability, reason=reason, **fields)
+    failure = context.metadata["candidate_failure"]
+    rows = [assessment("execution_completed", "assertion", failure is None)]
+    observed = output.get("routing_decision")
+    rows.append(assessment("routing_correct", "assertion", observed == reference["task"]["should_call_rag"])
+                if type(observed) is bool else assessment("routing_correct", "assertion", availability="missing",
+                                                         reason="router_output_not_retained"))
+    retrieval = output.get("retrieval")
+    score = None
+    if retrieval is not None:
+        score, _ = _score(reference["task"], retrieval["response"], retrieval["request"])
+    for name in ("ndcg_at_5", "recall_at_5"):
+        value = None if score is None else score["stage_metrics"]["N17"][name]
+        rows.append(assessment("retained_pool_" + name, "score", value) if value is not None else
+                    assessment("retained_pool_" + name, "score", availability="undefined" if score is not None else "missing",
+                               reason="native_metric_population_undefined" if score is not None else
+                               "source_labels_unavailable" if retrieval is not None else "retrieval_not_observed"))
+    context_output = output.get("context")
+    rows.append(assessment("context_count", "score", len(context_output["rows"])) if context_output is not None else
+                assessment("context_count", "score", availability="missing", reason="context_not_observed"))
+    rows.append(assessment("answer_semantic_quality", "label", availability="missing",
+                           reason="evidence_bound_semantic_review_not_provided"))
+    return tuple(rows)
+
+
+def _planned(record):
+    definition = record["run"]["definition"]
+    return tuple((case["case_id"], trial) for case in definition["cases"]
+                 for trial in range(1, definition["policy"]["trials"] + 1))
+
+
+def _assessment_index(record):
+    result = {}
+    for row in record["rows"]:
+        if row["failure"] is not None:
+            continue
+        for assessment in row["output"]["assessments"]:
+            key = (row["case_id"], row["trial"], assessment["criterion_id"])
+            _require(key not in result, "duplicate selected integrated assessment")
+            result[key] = assessment
+    return result
+
+
+def _missing_reasons(record):
+    """Index each lane once; absent pairs must not rescan the whole cohort."""
+    selected, grading = _selection(record["run"]), {}
+    for row in record["rows"]:
+        key = (row["case_id"], row["trial"])
+        state = grading.setdefault(key, {"successful": False, "last_failure": None})
+        state["successful"] |= row["failure"] is None
+        state["last_failure"] = row["failure"]
+    result = {}
+    for key in _planned(record):
+        state = grading.get(key)
+        if key not in selected:
+            result[key] = "candidate_not_started"
+        elif state is None:
+            result[key] = "grading_not_started_or_unavailable"
+        elif not state["successful"]:
+            result[key] = "grading_failed:" + state["last_failure"]
+        else:
+            result[key] = "criterion_not_assessed"
+    return result
+
+
+def _reduce(record):
+    """Mean trials within each case, then equal weight to eligible cases."""
+    values, coverage = defaultdict(lambda: defaultdict(list)), defaultdict(Counter)
+    planned, index = _planned(record), _assessment_index(record)
+    for case, trial in planned:
+        for name in _CRITERIA:
+            assessment = index.get((case, trial, name))
+            availability = "ungraded" if assessment is None else assessment["availability"]
+            coverage[name][availability] += 1
+            if assessment is not None and availability == "available" and assessment["kind"] in {"assertion", "score"}:
+                values[name][case].append(float(assessment["value"]))
+    metrics = {}
+    for name in _NUMERIC:
+        identifier = _PREFIX + name
+        case_values = [sum(v) / len(v) for v in values[identifier].values()]
+        metrics[identifier] = {"value": sum(case_values) / len(case_values) if case_values else None,
+                               "eligible_cases": len(case_values), "planned_trials": len(planned),
+                               "ungraded_trials": coverage[identifier]["ungraded"], "coverage": dict(coverage[identifier]),
+                               "population": _metric_population(name)}
+    return {"policy_id": _REDUCER, "metrics": metrics,
+            "coverage": {key: dict(value) for key, value in coverage.items()}}
+
+
+def _project(record):
+    run, grading = record["run"], record["definition"]
+    selected = _selection(run)
+    rows = [a for row in record["rows"] if row["failure"] is None for a in row["output"]["assessments"]]
+    planned = len(run["definition"]["cases"]) * run["definition"]["policy"]["trials"]
+    return {"schema_version": _REPORT, "run_id": grading["run_id"], "grading_id": grading["grading_id"],
+            "candidate": run["definition"]["candidate_identity"], "scope": run["definition"]["identity"]["scope"],
+            "metrics": record.get("analysis", {}).get("metrics", {}),
+            "counts": {"candidate_attempts": len(run["attempts"]),
+                       "failed_candidate_attempts": sum(a["failure"] is not None for a in run["attempts"]),
+                       "grading_attempts": len(record["rows"]),
+                       "failed_grading_attempts": sum(a["failure"] is not None for a in record["rows"]),
+                       "planned_trials": planned, "selected_trials": len(selected),
+                       "graded_trials": len({(r["case_id"], r["trial"]) for r in record["rows"] if r["failure"] is None})},
+            "selection": [{"case_id": case, "trial": trial, "attempt": row["attempt"], "failure": row["failure"]}
+                          for (case, trial), row in sorted(selected.items())],
+            "assessment_rows": rows, "trust_tier": "local_unverified",
+            "limitations": ["caller_declared_revision_not_code_attestation", "semantic_review_unavailable",
+                            "source_span_represented_documents", "local_stage_wall_times_not_service_latency", *_RANKING_LIMITS]}
+
+
+def _compare(baseline, candidate):
+    left, right = (record["run"]["definition"] for record in (baseline, candidate))
+    _require(left["candidate_identity"]["context_policy"] == right["candidate_identity"]["context_policy"],
+             "integrated context policies differ")
+    planned = _planned(baseline)
+    _require(planned == _planned(candidate), "integrated planned comparison cohort differs")
+    a, b, pairs, metrics = _assessment_index(baseline), _assessment_index(candidate), [], {}
+    baseline_absent, candidate_absent = _missing_reasons(baseline), _missing_reasons(candidate)
+    for name in _NUMERIC:
+        criterion = _PREFIX + name
+        case_deltas = defaultdict(list)
+        eligible = excluded = 0
+        baseline_ungraded = candidate_ungraded = 0
+        for case, trial in planned:
+            key = (case, trial, criterion)
+            x, y = a.get(key), b.get(key)
+            baseline_ungraded += x is None
+            candidate_ungraded += y is None
+            valid = x is not None and y is not None and x["availability"] == y["availability"] == "available"
+            delta = float(y["value"]) - float(x["value"]) if valid else None
+            pairs.append({"case_id": key[0], "trial": key[1], "criterion_id": criterion,
+                          "baseline": None if x is None else x["value"], "candidate": None if y is None else y["value"],
+                          "delta": delta, "availability": "available" if valid else "unavailable",
+                          "baseline_availability": "ungraded" if x is None else x["availability"],
+                          "candidate_availability": "ungraded" if y is None else y["availability"],
+                          "baseline_reason": baseline_absent[(case, trial)] if x is None else x["reason"],
+                          "candidate_reason": candidate_absent[(case, trial)] if y is None else y["reason"]})
+            if valid:
+                eligible += 1
+                case_deltas[key[0]].append(delta)
+            else:
+                excluded += 1
+        means = [sum(v) / len(v) for v in case_deltas.values()]
+        metrics[criterion] = {"candidate_minus_baseline": sum(means) / len(means) if means else None,
+                              "planned_pairs": len(planned), "eligible_pairs": eligible, "excluded_pairs": excluded,
+                              "baseline_ungraded_trials": baseline_ungraded, "candidate_ungraded_trials": candidate_ungraded,
+                              "eligible_cases": len(means), "population": _metric_population(name)}
+    return {"policy_id": _COMPARISON, "baseline_run_id": left["run_id"], "candidate_run_id": right["run_id"],
+            "baseline_revision": left["candidate_identity"]["revision"],
+            "candidate_revision": right["candidate_identity"]["revision"], "metrics": metrics, "pairs": pairs,
+            "verdict": None, "reason": "no_quality_gate_or_statistical_significance_policy_selected",
+            "limitations": list(_RANKING_LIMITS)}
+
+
+def _bound_context_evaluator(registry):
+    """Opt-in adapter: keep the native criterion while binding its stage input."""
+    from dataclasses import replace
+    from .evaluator_bindings import (
+        EvaluatorBinding, InputRequirement, _dispatch_binding, _schema_identity,
+    )
+    evaluator_id = "sphynx.rag.integrated.context-count-stage.v1"
+    criterion_id = _PREFIX + "context_count"
+    schema = registry.get_schema(INTEGRATED_STAGE_SCHEMA)
+
+    def count_stage(context):
+        stage = context.outputs
+        available = stage.get("status") == "completed"
+        return (Assessment(criterion_id, evaluator_id, context.case.case_id, "score",
+            "available" if available else "missing",
+            len(stage["output"]["rows"]) if available else None,
+            reason=None if available else "context_not_observed",
+            evidence_ids=tuple(item.evidence_id for item in context.evidence),
+            run_id=context.run_id, grading_id=context.grading_id,
+            trial=context.metadata["trial"], attempt=context.metadata["attempt"]),)
+
+    definition = EvaluatorDefinition(evaluator_id, "v1", evaluator_id, (criterion_id,),
+                                    metric_ids=(criterion_id,))
+    registry.register_evaluator(definition, count_stage)
+    binding = EvaluatorBinding.for_evaluator("sphynx.integrated.context-count-binding.v1", "v1",
+        definition, target="stage", stage_id="context", stage_schema=_schema_identity(schema),
+        requirements=(InputRequirement.for_schema("outputs", schema, fields=("status",), optional=True),))
+
+    def evaluate(context):
+        # IntegratedBackend._run verified these terminal snapshots against the
+        # retained artifact bytes before this grading context was constructed.
+        selector = binding.selector(context)
+        raw = context.outputs.get("stages", {}).get("context")
+        if raw is None:
+            evidence = EvidenceView(context.run_id + ":unobserved:" + contract_digest(selector.to_dict()),
+                None, "application/json", "stage.event", "verified_integrated_grading", "candidate_permitted",
+                INTEGRATED_STAGE_SCHEMA, selector.case_id, selector.stage_id, "unavailable",
+                {"run_id": context.run_id, "trial": selector.trial, "attempt": selector.attempt})
+            stage = StageEvidence.unavailable(selector, evidence, reason="context_not_observed")
+        else:
+            value = _thaw(raw); artifact = value.pop("artifact")
+            _require((value["run_id"], value["case_id"], value["trial"], value["attempt"],
+                      value["stage_id"], value["occurrence"]) ==
+                     (context.run_id, selector.case_id, selector.trial, selector.attempt,
+                      selector.stage_id, selector.occurrence), "context stage grading selection differs")
+            matching = [item for item in context.evidence
+                        if item.evidence_id == context.run_id + ":" + artifact["path"]
+                        and item.sha256 == artifact["sha256"]]
+            _require(len(matching) == 1, "context stage lacks its verified retained artifact")
+            evidence = replace(matching[0], schema_version=INTEGRATED_STAGE_SCHEMA,
+                step_id=selector.stage_id, metadata={**_thaw(matching[0].metadata), "run_id": context.run_id})
+            stage = StageEvidence.projected(selector, evidence, value, schema=schema)
+        bound = _dispatch_binding(registry, binding, context, stage=stage)
+        allowed = {item.evidence_id for item in context.evidence}
+        # The primary native evaluator composes the child. Its new implementation
+        # identity and metadata bind that child; stable native criterion IDs remain.
+        mapped = tuple(replace(row, evaluator_id=_EVALUATOR,
+                               evidence_ids=tuple(key for key in row.evidence_ids if key in allowed)) for row in bound)
+        return tuple(row for row in _evaluate(context) if row.criterion_id != criterion_id) + mapped
+
+    primary = EvaluatorDefinition(_EVALUATOR, "v1", _EVALUATOR + ".context-binding.v1", _CRITERIA,
+        metric_ids=tuple(_PREFIX + name for name in _NUMERIC),
+        configuration={"stage_binding": binding.to_dict(), "composition": "native-criterion-stage-adapter.v1"})
+    return primary, evaluate
+
+
+class IntegratedBackend(LifecycleBackend):
+    """One configured local system boundary with protected native references.
+
+    ``authorize_references(case_id, access)`` must return True before source
+    labels can be loaded for grading. It grants no candidate access. The default
+    evaluator reports structural/routing/retrieval diagnostics; answer semantic
+    quality remains missing. For different criteria or bound reviews, register
+    the driver with the general LifecycleBackend and explicit domain callbacks.
+    """
+    def __init__(self, registry: WorkflowRegistry, driver: IntegratedDriver, *, authorize_references,
+                 reference_access=None, run_policy=None, grading_policy=None, suite_id="rag.integrated.v1",
+                 bind_context_evaluator=False):
+        _require(isinstance(driver, IntegratedDriver) and callable(authorize_references),
+                 "integrated backend needs driver and explicit reference authorization")
+        _require(type(bind_context_evaluator) is bool, "bind_context_evaluator must be boolean")
+        source = driver.pipeline.source
+        schema = registry.register_schema(PayloadSchema(_CASE_SCHEMA, "v1", "sphynx.pipeline.case-validator.v1", _validate_case))
+        reference = registry.register_schema(PayloadSchema(_REFERENCE, "v1", "sphynx.integrated.reference-validator.v1", _validate_reference))
+        registry.register_schema(PayloadSchema(INTEGRATED_STAGE_SCHEMA, "v1", "sphynx.integrated.stage-record-validator.v1", _validate_stage))
+        registry.register_schema(PayloadSchema(_REPORT, "v1", "sphynx.integrated.report-validator.v1", _validate_report))
+        definition = DatasetDefinition(source.dataset_id, source.version, suite_id + ".provider", _CASE_SCHEMA, _REFERENCE,
+            selection={"case_ids": list(source.case_ids), "order": "native_dataset_order"},
+            identity={"source_sha256": source.sha256, "reference_revision": source.version,
+                      "reference_rule": "native_complete_source_span_inheritance.v1"})
+        def load_reference(case_id):
+            _, tasks = driver.pipeline._loaded()
+            task = next((task for task in tasks if task["task_id"] == case_id), None)
+            _require(task is not None, "reference case is outside the selected cohort")
+            return {"source_sha256": source.sha256, "source_version": source.version, "task": task}
+        registry.register_provider(Dataset(definition, schema, lambda selection: driver.cases(),
+            reference_schema=reference, reference_loader=load_reference, authorize_references=authorize_references))
+        for identifier in _CRITERIA:
+            registry.register_criterion(Criterion(identifier, "v1", identifier.rsplit(".", 1)[-1]))
+        registry.register_policy(_REDUCER, version="v1", implementation_id=_REDUCER, kind="aggregation", callback=_reduce,
+            metadata={"population": "first_success_or_last_failed_per_case_trial; available_values_only",
+                      "weights": "mean_trials_within_case_then_equal_case_mean"})
+        registry.register_policy(_COMPARISON, version="v1", implementation_id=_COMPARISON, kind="comparison", callback=_compare,
+            metadata={"population": "same_case_trial_available_pairs", "quality_gate": None})
+        for name in _NUMERIC:
+            registry.register_metric(MetricSpec(_PREFIX + name, "v1", "count" if name == "context_count" else "ratio",
+                "descriptive" if name == "context_count" else "higher", _REDUCER, _COMPARISON,
+                population=_metric_population(name)))
+        if bind_context_evaluator:
+            evaluator, callback = _bound_context_evaluator(registry)
+            registry.register_evaluator(evaluator, callback)
+        else:
+            registry.register_evaluator(EvaluatorDefinition(_EVALUATOR, "v1", _EVALUATOR, _CRITERIA,
+                metric_ids=tuple(_PREFIX + name for name in _NUMERIC)), _evaluate)
+        registry.register_projection(_REPORT, _project, version="v1", implementation_id="sphynx.integrated.projection.v1")
+        suite = SuiteDefinition(suite_id, "v1", "sphynx.integrated." + suite_id, "Integrated retrieval, context and answer",
+            configuration={"boundary": "sphynx.rag.integrated.v1", "pipeline": driver.pipeline.describe(driver.pipeline.suite_id).to_dict(),
+                           "context_policy": {"max_bytes": driver.max_context_bytes,
+                                              "selection": "whole_chunks_in_final_rank_order_utf8_bytes.v1"}},
+            criterion_ids=_CRITERIA, evaluator_ids=(_EVALUATOR,), metric_ids=tuple(_PREFIX + name for name in _NUMERIC),
+            required_capabilities=(STAGE_EVIDENCE_CAPABILITY,), datasets=(definition,),
+            metadata={"candidate_source_bytes_verified": False, "semantic_review": "not_provided"})
+        def admit(plan, cases):
+            admitted = driver.admit(plan.candidate)
+            _require(tuple(c.case_id for c in cases) == source.case_ids, "integrated selected case order differs")
+            return {"artifact_bytes_verified": admitted.artifact_bytes_verified, "candidate_source_bytes_verified": False,
+                    "fixed": {"boundary": "sphynx.rag.integrated.v1", "source": source.to_dict(),
+                              "context_policy": _thaw(suite.configuration["context_policy"])},
+                    "candidate": {"identity": driver.candidate_identity(plan.candidate),
+                                  "pipeline_admission": admitted.to_dict()}}
+        super().__init__(registry, suite, driver=driver, evaluator_id=_EVALUATOR, projection_schema_id=_REPORT,
+            comparison_policy_id=_COMPARISON, run_policy=run_policy or RunPolicy(reducer_id=_REDUCER),
+            grading_policy=grading_policy, reference_access=reference_access, admission_verifier=admit,
+            scopes=("system",), capabilities=(STAGE_EVIDENCE_CAPABILITY, "sphynx.rag.integrated.v1"),
+            include_emitted_evidence=bind_context_evaluator)
+        registry.register_backend(self)
+        registry.register_suite(suite)
+
+    @staticmethod
+    def _comparison_conditions(baseline, candidate):
+        LifecycleBackend._comparison_conditions(baseline, candidate)
+        left, right = (record["run"]["definition"] for record in (baseline, candidate))
+        _comparison_require(left["candidate_identity"]["context_policy"] == right["candidate_identity"]["context_policy"],
+                 "integrated context policies differ")
+        _comparison_require(_planned(baseline) == _planned(candidate), "integrated planned comparison cohort differs")
+
+    def project_comparison(self, sources, native):
+        from ._comparison_adapters import _integrated_view
+        return _integrated_view(sources, native, {item.metric_id: item for item in self.registry.list_metrics()})
+
+    def _run(self, ref):
+        record = super()._run(ref)
+        _require(record["definition"]["identity"]["scope"] == "system"
+                 and record["definition"]["identity"]["mode"] == "local", "integrated saved scope/mode differs")
+        cases = {case["case_id"]: case for case in record["definition"]["cases"]}
+        identity = record["definition"]["candidate_identity"]
+        journal = LifecycleJournal(ref.path, ref.definition_sha256)
+        emitted = {e["data"]["binding"]["path"]: e["data"] for e in record["events"] if e["event"] == "artifact"}
+        for attempt in record["attempts"]:
+            output = attempt["outputs"]
+            if not output:
+                _require(attempt["failure"] is not None, "successful integrated attempt has no output")
+                continue
+            _require(output.get("schema_version") == INTEGRATED_SCHEMA
+                     and (output["case_id"], output["trial"], output["attempt"]) ==
+                         (attempt["case_id"], attempt["trial"], attempt["attempt"])
+                     and output["candidate_revision"] == identity["revision"]
+                     and output["input_digest"] == contract_digest(cases[attempt["case_id"]])
+                     and output["candidate_identity_digest"] == value_digest(identity), "integrated output binding differs")
+            terminals, order = {}, []
+            for index, event in enumerate(output["events"]):
+                _require(event["sequence"] == index and event["stage_id"] in INTEGRATED_STAGES
+                         and event["occurrence"] == 1 and event["phase"] in {"started", "completed", "failed"},
+                         "integrated event sequence differs")
+                if event["phase"] == "started":
+                    order.append(event["stage_id"])
+                binding = event["artifact"]
+                native = emitted.get(binding["path"])
+                _require(native is not None and native["binding"] == binding and
+                         binding["role"] == "integrated." + event["stage_id"] + "." + event["phase"] and
+                         (native["case_id"], native["trial"], native["attempt"]) ==
+                         (attempt["case_id"], attempt["trial"], attempt["attempt"]), "stage event is outside its attempt")
+                if native["truncated"]:
+                    continue
+                value = json.loads(journal.read_artifact(binding)); _validate_stage(value)
+                _require((value["run_id"], value["case_id"], value["trial"], value["attempt"], value["stage_id"], value["occurrence"], value["status"]) ==
+                         (ref.run_id, attempt["case_id"], attempt["trial"], attempt["attempt"], event["stage_id"], event["occurrence"], event["phase"]),
+                         "stage event selector binding differs")
+                if event["phase"] != "started":
+                    _require(event["stage_id"] not in terminals, "integrated stage has duplicate terminal events")
+                    terminals[event["stage_id"]] = event["phase"]
+                    _require(output["stages"].get(event["stage_id"]) == {**value, "artifact": binding}, "stage snapshot differs from retained bytes")
+            _require(order == list(INTEGRATED_STAGES[:len(order)]) and set(output["stages"]) == set(terminals),
+                     "integrated stages are not the retained execution prefix")
+            if attempt["failure"] is None:
+                expected = ["router"] if output.get("routing_decision") is False else list(INTEGRATED_STAGES)
+                _require(list(terminals) == expected and set(terminals.values()) == {"completed"},
+                         "successful integrated execution lacks required stages")
+            retrieval = output.get("retrieval")
+            if retrieval is not None:
+                request = retrieval["request"]
+                body = dict(request); digest = body.pop("input_digest")
+                _require(value_digest(body) == digest and request["case_id"] == attempt["case_id"]
+                         and request["query"] == output["rewritten_query"]
+                         and request["documents"] == cases[attempt["case_id"]]["inputs"]["documents"],
+                         "retained retrieval request/source binding differs")
+                from .pipeline import validate_pipeline_response
+                validate_pipeline_response(retrieval["response"], request)
+                for kind, value in retrieval["response"]["stages"].items():
+                    _require(output["stages"][kind]["output"] == value, "retrieval response differs from stage artifact")
+                if output.get("context") is not None:
+                    expected = build_context(retrieval["response"], request["documents"], identity["context_policy"]["max_bytes"])
+                    _require(output["context"] == expected and output["stages"]["context"]["output"] == expected,
+                             "integrated context differs from retained retrieval")
+            if output.get("answer") is not None:
+                generated = output["stages"]["generator"]
+                _require(generated["input"]["contexts"] == output["context"]["rows"]
+                         and generated["input"]["query"] == output["rewritten_query"], "generator handoff differs")
+                validate_answer(generated["output"], output["context"])
+                _require(all(generated["output"].get(key, [] if key == "citations" else None) == output[key]
+                             for key in ("answer", "citations", "abstained", "token_counts")), "answer differs from generation artifact")
+        return record
+
+    def _references(self, run_record):
+        references = super()._references(run_record)
+        source = self.driver.pipeline.source
+        for case, reference in references.items():
+            _require(reference["source_sha256"] == source.sha256 and reference["source_version"] == source.version
+                     and reference["task"]["task_id"] == case, "integrated reference revision/case differs")
+        return references
+
+    def stage_evidence(self, native_ref, selector):
+        if not isinstance(selector, StageSelector) or selector.stage_id not in INTEGRATED_STAGES or selector.occurrence != 1:
+            raise StageContractError("integrated stage selection requires a supported exact selector")
+        run_ref = native_ref.run if isinstance(native_ref, LifecycleGradingRef) else native_ref
+        record = self._run(run_ref)
+        if isinstance(native_ref, LifecycleGradingRef):
+            self._grading(native_ref)
+        starts = {(e["data"]["case_id"], e["data"]["trial"], e["data"]["attempt"])
+                  for e in record["events"] if e["event"] == "candidate_started"}
+        if (selector.case_id, selector.trial, selector.attempt) not in starts:
+            raise StageContractError("stage selector is outside the run's attempted cohort")
+        journal, result = LifecycleJournal(run_ref.path, run_ref.definition_sha256), []
+        for event in record["events"]:
+            data = event["data"]
+            if event["event"] != "artifact" or (data["case_id"], data["trial"], data["attempt"]) != (selector.case_id, selector.trial, selector.attempt):
+                continue
+            binding = data["binding"]
+            if not binding["role"].startswith("integrated." + selector.stage_id + "."):
+                continue
+            evidence = EvidenceView(run_ref.run_id + ":" + binding["path"], binding["sha256"], "application/json",
+                "stage.event", "parent_retained_integrated_stage", "candidate_permitted", INTEGRATED_STAGE_SCHEMA,
+                selector.case_id, selector.stage_id, "unavailable" if data["truncated"] else "available",
+                {"artifact_path": binding["path"], "journal_sequence": event["sequence"], "role": binding["role"],
+                 "timing_authority": "parent_observed_local_stage_wall", "trial": selector.trial, "attempt": selector.attempt})
+            if data["truncated"]:
+                result.append(StageEvidence.unavailable(selector, evidence, reason="lifecycle_output_limit_truncated_stage_record"))
+            else:
+                value = json.loads(journal.read_artifact(binding))
+                _require((value["run_id"], value["case_id"], value["trial"], value["attempt"], value["stage_id"], value["occurrence"]) ==
+                         (run_ref.run_id, selector.case_id, selector.trial, selector.attempt, selector.stage_id, selector.occurrence)
+                         and binding["role"] == "integrated." + selector.stage_id + "." + value["status"],
+                         "stage selector binding differs")
+                result.append(StageEvidence.projected(selector, evidence, value, schema=self.registry.get_schema(INTEGRATED_STAGE_SCHEMA)))
+        if result:
+            return tuple(result)
+        evidence = EvidenceView(run_ref.run_id + ":unobserved:" + contract_digest(selector.to_dict()), None,
+            "application/json", "stage.event", "parent_retained_integrated_stage", "candidate_permitted",
+            INTEGRATED_STAGE_SCHEMA, selector.case_id, selector.stage_id, "unavailable")
+        return (StageEvidence.unavailable(selector, evidence, reason="stage_not_observed_or_skipped"),)
+
+
+def build_integrated_registry(driver: IntegratedDriver, *, authorize_references, reference_access=None,
+                              run_policy=None, grading_policy=None, suite_id="rag.integrated.v1",
+                              bind_context_evaluator=False) -> WorkflowRegistry:
+    """Register configured local system execution; load no assets or references.
+
+    The default reducer is explicit equal-case mean of available trial means.
+    Plan policies can omit aggregation; per-case assessments remain available.
+    No quality gate, semantic review or authenticated revision is implied.
+    """
+    registry = WorkflowRegistry(legacy_ids=(driver.pipeline.source.dataset_id,))
+    IntegratedBackend(registry, driver, authorize_references=authorize_references, reference_access=reference_access,
+                      run_policy=run_policy, grading_policy=grading_policy, suite_id=suite_id,
+                      bind_context_evaluator=bind_context_evaluator)
+    return registry