diff --git a/docs/apps-module-migrations.json b/docs/apps-module-migrations.json index 03028171..4040cca2 100644 --- a/docs/apps-module-migrations.json +++ b/docs/apps-module-migrations.json @@ -21,9 +21,9 @@ "docs/module-layout.md", "docs/operations.md", "src/inferrsi/apps/api.py", - "src/inferrsi/apps/bridge.py", - "src/inferrsi/apps/candidate_provider.py", "src/inferrsi/apps/delivery/__init__.py", + "src/inferrsi/apps/handoff/bridge.py", + "src/inferrsi/apps/handoff/candidate_provider.py", "src/inferrsi/apps/storage/artifact_reader.py", "src/inferrsi/apps/views/attempt.py", "tests/check_installed.py", @@ -50,7 +50,7 @@ "docs/module-layout.md", "docs/operations.md", "src/inferrsi/apps/api.py", - "src/inferrsi/apps/candidate_provider.py", + "src/inferrsi/apps/handoff/candidate_provider.py", "src/inferrsi/apps/views/attempt.py", "tests/check_installed.py", "tests/test_apps_artifact_reader.py", @@ -77,9 +77,9 @@ "docs/module-layout.md", "docs/operations.md", "src/inferrsi/apps/api.py", - "src/inferrsi/apps/bridge.py", - "src/inferrsi/apps/candidate_provider.py", "src/inferrsi/apps/delivery/adapters.py", + "src/inferrsi/apps/handoff/bridge.py", + "src/inferrsi/apps/handoff/candidate_provider.py", "src/inferrsi/apps/storage/archive.py", "src/inferrsi/apps/storage/artifact_reader.py", "src/inferrsi/apps/views/attempt.py", @@ -108,5 +108,64 @@ "tests/test_first_wave_isolation_policy.py", "tests/test_repository_packs_facade.py" ] + }, + { + "old": "inferrsi.apps.bridge", + "canonical": "inferrsi.apps.handoff.bridge", + "exports": [ + "execution_fields", + "verify_protocol", + "check_assessment_identity", + "bind_execution", + "to_evidence" + ], + "consumers": [ + "docs/apps-output.md", + "docs/architecture.md", + "docs/module-layout.md", + "docs/operations.md", + "src/inferrsi/apps/api.py", + "src/inferrsi/apps/handoff/candidate_provider.py", + "src/inferrsi/apps/views/attempt.py", + "tests/check_installed.py", + "tests/test_apps_evidence.py", + "tests/test_apps_execution_binding.py", + "tests/test_apps_generation_plan.py", + "tests/test_apps_module_migrations.py" + ] + }, + { + "old": "inferrsi.apps.context_provider", + "canonical": "inferrsi.apps.handoff.context_provider", + "exports": [ + "DeliveredContextDraft", + "ContextProvider" + ], + "consumers": [ + "docs/apps-output.md", + "docs/architecture.md", + "docs/module-layout.md", + "docs/operations.md", + "tests/check_installed.py", + "tests/test_apps_context_provider.py", + "tests/test_apps_module_migrations.py", + "tests/test_harness_generation_seal.py" + ] + }, + { + "old": "inferrsi.apps.candidate_provider", + "canonical": "inferrsi.apps.handoff.candidate_provider", + "exports": [ + "CandidateProvider" + ], + "consumers": [ + "docs/apps-output.md", + "docs/architecture.md", + "docs/module-layout.md", + "docs/operations.md", + "src/inferrsi/apps/api.py", + "tests/check_installed.py", + "tests/test_apps_module_migrations.py" + ] } ] diff --git a/docs/apps-output.md b/docs/apps-output.md index 3eef4cc7..c0cf2bd1 100644 --- a/docs/apps-output.md +++ b/docs/apps-output.md @@ -134,6 +134,13 @@ deadline. OperationRecipe v1 has no per-step timeout, so the step timeout is null. The expected worker code digest comes from the fixed recipe. The bound spec is handed to the host-supplied Harness execution port. +`inferrsi.apps.handoff.bridge` owns that binding and the fixed evidence +projection. `handoff.context_provider` delivers Knowledge bytes for Harness to +seal, and `handoff.candidate_provider` owns generation planning and candidate +collection. `inferrsi.apps.api.CandidateProvider` exports the same canonical +class. The three former Apps modules retain their registered public exports; +the original attempt, public port signatures and fixed references are unchanged. + ## Fixed artifact reader `inferrsi.apps.storage.artifact_reader.ArtifactReader(storage_config)` implements diff --git a/docs/architecture.md b/docs/architecture.md index cba3b66f..87d68ac9 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -190,6 +190,10 @@ src/inferrsi/ __init__.py Import-free initializer repository_packs.py Neutral REPO_TYPES and pack.json reader; imports no inferrsi module apps/ + handoff/ + bridge.py Bind preparations to specs and fixed records to evidence + context_provider.py Deliver Knowledge bytes and pins for Harness sealing + candidate_provider.py Plan generation and collect fixed candidate outputs storage/ archive.py Immutable preparations/assessments and manifest.json/result.json artifact_reader.py Read verified artifacts through authorized mounts diff --git a/docs/module-layout.md b/docs/module-layout.md index 3550cf7a..1c93b831 100644 --- a/docs/module-layout.md +++ b/docs/module-layout.md @@ -41,8 +41,25 @@ through these exports; new pickles use the canonical definition. The retired root `inferrsi.evidence_paths` has no alias and remains unavailable. Shim removal requires a separate reviewed PR recording consumer migration, -wheel and plugin validation, and the first removal version. Handoff, workflows -and integrations remain subsequent #490 slices. +wheel and plugin validation, and the first removal version. Workflows, +integrations and integrated acceptance remain subsequent #490 slices. + +### Apps handoff migration + +`apps/handoff/bridge.py` binds fixed preparations to execution specifications +and projects saved records into evidence. `context_provider.py` delivers actual +Knowledge bytes and pins for Harness sealing. `candidate_provider.py` plans +generation and collects candidates from fixed Harness records. These modules +consume `apps/storage/`; storage never imports back into handoff. + +The three former Apps paths retain explicit public exports recorded in the +[migration inventory](apps-module-migrations.json). `apps.api.CandidateProvider` +and the former provider module export the one class defined in +`apps/handoff/candidate_provider.py`. `EvaluationPort` remains defined in +`apps/api.py`. The handoff initializer imports nothing, and importing either +path performs no Knowledge reads, device probes, process launches or service +registration. Harness owns the sealed context, original attempt and request +digest; these ownership boundaries and DTOs remain unchanged. ### Core and technical packages diff --git a/docs/operations.md b/docs/operations.md index 9832c147..283ce6a6 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -357,6 +357,10 @@ creation helper is `inferrsi.apps.storage.evidence_layout.ensure_evidence_layout The CLI entry remains `inferrsi.apps.cli:main`. See the [output contract](apps-output.md) and [migration inventory](apps-module-migrations.json) for the retained old Apps imports and canonical storage paths. +`inferrsi.apps.handoff.bridge`, `handoff.context_provider` and +`handoff.candidate_provider` implement execution/evidence binding, context +delivery and generation handoff. The API still exports the one canonical +`CandidateProvider`; `EvaluationPort` remains defined in `apps.api`. ### Inspect/prepare — `doctor`, `plan`, `--dry-run` diff --git a/src/inferrsi/apps/api.py b/src/inferrsi/apps/api.py index a1575bbf..0b137ee5 100644 --- a/src/inferrsi/apps/api.py +++ b/src/inferrsi/apps/api.py @@ -9,9 +9,14 @@ from inferrsi.harness.errors import PublicError from inferrsi.harness.execution_spec import request_digest -from .bridge import bind_execution as _bind_prepared_execution -from .bridge import check_assessment_identity, execution_fields, to_evidence, verify_protocol -from .candidate_provider import CandidateProvider as CandidateProvider +from .handoff.bridge import bind_execution as _bind_prepared_execution +from .handoff.bridge import ( + check_assessment_identity, + execution_fields, + to_evidence, + verify_protocol, +) +from .handoff.candidate_provider import CandidateProvider as CandidateProvider from .storage.archive import ( ResourceReader, RunOutput, diff --git a/src/inferrsi/apps/bridge.py b/src/inferrsi/apps/bridge.py index dac6048a..14e7372d 100644 --- a/src/inferrsi/apps/bridge.py +++ b/src/inferrsi/apps/bridge.py @@ -1,474 +1,17 @@ -"""Map fixed Benchmark preparation and a saved attempt into a Harness spec.""" - -import re -from copy import deepcopy -from hashlib import sha256 - -from inferrsi.contracts.json_v1 import decode, encode -from inferrsi.harness.errors import PublicError - -from .storage.archive import _logical_path -from .storage.result import validate_artifact_ref - -_ATTEMPT_FIELDS = { - "request_id", "run_id", "attempt_id", "owner", "target_request", "deadline_utc", - "resources", "budget", "retry_of", "retry_reason", -} -_PROPOSAL_FIELDS = {"candidate", "inputs", "generation_record_ref"} -_EXECUTE_FIELDS = {"schema_version", "prepared_ref", "proposal", "attempt", "output_root"} -_INPUT_FIELDS = { - "role", "source", "source_namespace", "source_ref", "snapshot_format", "expected_sha256", - "materialized_path", -} -_OUTPUT_FIELDS = {"role", "path", "required", "media_type", "format_schema"} -_CANDIDATE_FIELDS = {"candidate_id", "kind", "input_role", "parent_id", "parent_digest", - "context_refs"} -_RECIPE_FIELDS = { - "recipe_revision", "runtime_role", "entrypoint_kind", "entrypoint", "entrypoint_revision", - "code_sha256", "args", "input_roles", "outputs", "required_capabilities", -} -_PREPARED_FIELDS = { - "schema_version", "prepared_id", "task", "grader", "operation", "validation_scope", - "protocol", "protocol_digest", "candidate_contract", "expected_candidate", - "required_evidence", "recipe", "resources", "created_at", "display_notes", -} -_RESOURCE_FIELDS = {"role", "artifact", "required_for", "format_schema"} -_PROTOCOL_FIELDS = { - "schema_version", "task", "grader", "operation", "validation_scope", - "candidate_contract", "worker_recipe", "input_requirements", "claim_definitions", - "metric_definitions", "required_evidence", "task_parameters", "baseline", "reference", - "quality_reference", "sampling", "feedback_visibility", "budget_policy_refs", - "resources", "display_notes", -} -_PROTOCOL_COPIES = ( - "task", "grader", "operation", "validation_scope", "candidate_contract", "required_evidence", +"""Compatibility exports for :mod:`inferrsi.apps.handoff.bridge`.""" + +from .handoff.bridge import ( + bind_execution, + check_assessment_identity, + execution_fields, + to_evidence, + verify_protocol, ) -_RECORD_FIELDS = { - "schema_version", "request_id", "run_id", "attempt_id", "request_digest", "owner", - "target_request", "target_binding", "retry_of", "retry_reason", "generation_record_ref", - "prepared_ref", "protocol_digest", "operation", "validation_scope", "candidate", - "record_version", "recorded_at", "bound_inputs", "phase", "started", "side_effect_unknown", - "process_outcome", "exit_code", "elapsed_seconds", "steps", "cancellation", "cleanup", - "artifacts", "checks", "budget_admission", "usage", "resource_leases", "errors", -} -_ID = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:/@+-]{0,255}") -_DIGEST = re.compile(r"[0-9a-f]{64}") -_SEMANTIC_ID = re.compile(r"sha256:[0-9a-f]{64}") -_PLACEHOLDER = re.compile(r"\{(input|output):([^{}]+)\}") - - -def execution_fields(request: dict) -> dict: - """Return the fields that an execution binder must preserve exactly.""" - if not isinstance(request, dict) or request.keys() != _EXECUTE_FIELDS: - raise ValueError("expected AppsExecuteRequest fields") - attempt = request["attempt"] - proposal = request["proposal"] - if ( - type(request["schema_version"]) is not int - or request["schema_version"] != 1 - or not isinstance(attempt, dict) - or attempt.keys() != _ATTEMPT_FIELDS - or not isinstance(attempt["attempt_id"], str) - or not attempt["attempt_id"] - or attempt["request_id"] != attempt["attempt_id"] - or not isinstance(proposal, dict) - or proposal.keys() != _PROPOSAL_FIELDS - or not isinstance(proposal["inputs"], list) - ): - raise ValueError("expected a pre-allocated AttemptContext") - return { - **attempt, - "schema_version": 1, - "prepared_ref": request["prepared_ref"], - "output_root": request["output_root"], - "candidate": proposal["candidate"], - "generation_record_ref": proposal["generation_record_ref"], - } - - -def _id(value: object) -> bool: - return isinstance(value, str) and _ID.fullmatch(value) is not None - - -def _digest(value: object) -> bool: - return isinstance(value, str) and _DIGEST.fullmatch(value) is not None - - -def _definition(value: object) -> bool: - return ( - isinstance(value, dict) and value.keys() == {"name", "revision"} - and all(_id(value[key]) for key in ("name", "revision")) - ) - - -def _candidate_input(candidate: dict, prepared: dict, inputs: dict) -> None: - if not isinstance(candidate, dict) or candidate.keys() != _CANDIDATE_FIELDS: - raise ValueError("invalid candidate fields") - contract = prepared["candidate_contract"] - role = candidate["input_role"] - if ( - role not in inputs or role != contract["input_role"] - or candidate["kind"] != contract["kind"] or not _id(candidate["candidate_id"]) - or not _definition(contract["format_schema"]) - or (candidate["parent_id"] is None) != (candidate["parent_digest"] is None) - or not isinstance(candidate["context_refs"], list) - ): - raise ValueError("candidate does not match the frozen input role or format") - if candidate["parent_id"] is not None and ( - not _id(candidate["parent_id"]) or not _digest(candidate["parent_digest"]) - ): - raise ValueError("invalid parent identity") - for ref in candidate["context_refs"]: - validate_artifact_ref(ref) - _logical_path(ref["location"]) - rule = contract["identity_rule"] - expected = inputs[role]["expected_sha256"] - if rule not in ( - {"name": "captured-sha256", "revision": "1"}, - {"name": "expected-sha256", "revision": "1"}, - ): - raise PublicError( - "UnsupportedRuleVersion", stage="binder_validation", - message="The frozen candidate identity rule is unsupported.", - ) - if rule["name"] == "expected-sha256" and expected is None: - raise ValueError("candidate input is missing an expected digest") - frozen = prepared["expected_candidate"] - if frozen is not None and ( - not _digest(frozen["sha256"]) or expected != frozen["sha256"] - or candidate["candidate_id"] != frozen["candidate_id"] - or contract["format_schema"] != frozen["format_schema"] - ): - raise ValueError("candidate declaration conflicts with the frozen expectation") - - -def _input_paths(items: list) -> dict: - inputs = {} - for item in items: - if not isinstance(item, dict) or item.keys() != _INPUT_FIELDS: - raise ValueError("invalid input fields") - role, expected = item["role"], item["expected_sha256"] - if ( - not _id(role) or role in inputs or not _id(item["snapshot_format"]) - or not isinstance(item["source"], str) or not item["source"] - or (expected is not None and not _digest(expected)) - ): - raise ValueError("invalid or repeated input role or identity") - _logical_path(item["materialized_path"]) - source_ref = item["source_ref"] - if item["source_namespace"] == "artifact": - validate_artifact_ref(source_ref) - _logical_path(source_ref["location"]) - if item["source"] != source_ref["location"] or expected != source_ref["sha256"]: - raise ValueError("input source conflicts with its fixed artifact") - elif item["source_namespace"] not in ("controller", "target") or source_ref is not None: - raise ValueError("invalid input source namespace") - inputs[role] = item - return inputs - - -def _add_fixed_resources(inputs: dict, resources: list) -> None: - if not isinstance(resources, list): - raise ValueError("invalid fixed resource list") - seen = set() - for resource in resources: - if ( - not isinstance(resource, dict) or resource.keys() != _RESOURCE_FIELDS - or not _id(resource["role"]) or resource["role"] in seen - or not isinstance(resource["required_for"], list) - or not resource["required_for"] or not _definition(resource["format_schema"]) - or any(use not in ("prepare", "execute", "assess") for use in resource["required_for"]) - ): - raise ValueError("invalid or repeated fixed resource") - seen.add(resource["role"]) - if "execute" not in resource["required_for"]: - continue - role, ref = resource["role"], resource["artifact"] - validate_artifact_ref(ref) - _logical_path(ref["location"]) - if role in inputs: - raise ValueError("a fixed execution resource role is already bound") - role_hash = sha256(role.encode("ascii")).hexdigest() - inputs[role] = { - "role": role, - "source": ref["location"], - "source_namespace": "artifact", - "source_ref": ref, - "snapshot_format": "file-v1", - "expected_sha256": ref["sha256"], - "materialized_path": f"inputs/{role_hash}", - } - - -def _output_paths(outputs: list) -> dict: - paths = {} - for item in outputs: - if ( - not isinstance(item, dict) or item.keys() != _OUTPUT_FIELDS - or not _id(item["role"]) or item["role"] in paths - or type(item["required"]) is not bool - or not isinstance(item["media_type"], str) or not item["media_type"] - or not _definition(item["format_schema"]) - ): - raise ValueError("invalid or repeated output declaration") - _logical_path(item["path"]) - paths[item["role"]] = item["path"] - return paths - - -def _bind_args(args: list, inputs: dict, outputs: dict) -> list[str]: - bound = [] - for arg in args: - if not isinstance(arg, str): - raise ValueError("recipe arguments must be strings") - match = _PLACEHOLDER.fullmatch(arg) - if match: - kind, role = match.groups() - bound.append(inputs[role] if kind == "input" else outputs[role]) - elif "{input:" in arg or "{output:" in arg: - raise ValueError("recipe placeholders must occupy the whole argument") - else: - bound.append(arg) - return bound - - -def _require_disjoint_paths(paths: list[str]) -> None: - ordered = sorted(_logical_path(path) for path in paths) - if any(second[:len(first)] == first for first, second in zip(ordered, ordered[1:])): - raise ValueError("input and output paths must not overlap") - - -def _resource_projection(resource: dict) -> dict: - if not isinstance(resource, dict) or resource.keys() != _RESOURCE_FIELDS: - raise ValueError("invalid protocol resource") - return {**resource, "artifact": _artifact_projection(resource["artifact"])} - - -def verify_protocol(prepared: dict, data: bytes) -> None: - """Check the archived protocol's identity and the preparation's frozen fields.""" - try: - ref = prepared["protocol"] - validate_artifact_ref(ref) - protocol = decode(data) - if ( - not isinstance(protocol, dict) or protocol.keys() != _PROTOCOL_FIELDS - or type(protocol["schema_version"]) is not int or protocol["schema_version"] != 1 - or not isinstance(protocol["resources"], list) - or not isinstance(prepared["resources"], list) - ): - raise ValueError("invalid ProtocolV1 envelope") - projection = dict(protocol) - del projection["display_notes"] - resources = [_resource_projection(item) for item in protocol["resources"]] - closure = list(resources) - projection["resources"] = resources - for key in ("baseline", "reference", "quality_reference"): - if protocol[key] is not None: - projection[key] = _resource_projection(protocol[key]) - closure.append(projection[key]) - digest = "sha256:" + sha256(encode(projection)).hexdigest() - fixed_resources = [_resource_projection(item) for item in prepared["resources"]] - expected_resources = {item["role"]: item for item in closure} - if len(expected_resources) != len(closure): - raise ValueError("protocol resource roles must be unique") - if ( - ref["size_bytes"] != len(data) or ref["sha256"] != sha256(data).hexdigest() - or prepared["protocol_digest"] != digest - or encode(prepared["recipe"]) != encode(protocol["worker_recipe"]) - or any(encode(prepared[key]) != encode(protocol[key]) for key in _PROTOCOL_COPIES) - or encode(fixed_resources) != encode( - [expected_resources[role] for role in sorted(expected_resources)] - ) - ): - raise PublicError( - "IdentityMismatch", stage="binder_validation", - message="The fixed preparation disagrees with its archived protocol.", - ) - except (KeyError, TypeError, ValueError): - raise PublicError( - "InvalidExecutionSpec", stage="binder_validation", - message="The fixed preparation or protocol is malformed.", - ) from None - - -def _artifact_projection(ref: dict) -> dict: - validate_artifact_ref(ref) - _logical_path(ref["location"]) - return {key: value for key, value in ref.items() if key != "location"} - - -def check_assessment_identity(assessment: dict) -> None: - """Verify the v1 semantic ID while preserving the assessor's original bytes.""" - projection = deepcopy(assessment) - identity = projection.pop("assessment_id") - del projection["assessed_at"] - refs = [projection["prepared_ref"], projection["record_ref"], *projection["derived_from"]] - refs.extend(item["against"] for item in projection["comparison"]) - if projection["supersedes"] is not None: - refs.append(projection["supersedes"]) - for ref in refs: - ref["artifact"] = _artifact_projection(ref["artifact"]) - for items, field in ((projection["claims"], "evidence"), - (projection["metrics"], "raw_samples")): - for item in items: - item[field] = [_artifact_projection(ref) for ref in item[field]] - projection["evidence_artifacts"] = [ - _artifact_projection(ref) for ref in projection["evidence_artifacts"] - ] - if projection["candidate"] is not None: - candidate = projection["candidate"] - candidate["context_refs"] = [_artifact_projection(ref) for ref in candidate["context_refs"]] - if identity != "sha256:" + sha256(encode(projection)).hexdigest(): - raise ValueError("invalid assessment semantic identity") - - -def _check_prepared_ref(prepared: dict, ref: dict, *, stage: str) -> None: - if ( - not isinstance(ref, dict) or ref.keys() != {"prepared_id", "schema_version", "artifact"} - or not isinstance(prepared, dict) or prepared.keys() != _PREPARED_FIELDS - ): - raise ValueError("invalid prepared object or reference fields") - validate_artifact_ref(ref["artifact"]) - _logical_path(ref["artifact"]["location"]) - data = encode(prepared) - if ( - type(ref["schema_version"]) is not int or ref["schema_version"] != 1 - or type(prepared["schema_version"]) is not int or prepared["schema_version"] != 1 - or not _SEMANTIC_ID.fullmatch(ref["prepared_id"]) - or prepared["prepared_id"] != ref["prepared_id"] - or ref["artifact"]["media_type"] != "application/json" - or ref["artifact"]["size_bytes"] != len(data) - or ref["artifact"]["sha256"] != sha256(data).hexdigest() - ): - raise PublicError( - "IdentityMismatch", stage=stage, - message="The preparation does not match its fixed reference.", - ) - if ( - not _id(prepared["operation"]) or not _id(prepared["validation_scope"]) - or not _SEMANTIC_ID.fullmatch(prepared["protocol_digest"]) - ): - raise ValueError("invalid prepared operation, scope, or protocol digest") - - -def _bind_spec(request: dict, prepared: dict) -> dict: - fields = execution_fields(request) - _check_prepared_ref(prepared, fields["prepared_ref"], stage="binder_validation") - _logical_path(fields["output_root"]) - inputs = _input_paths(request["proposal"]["inputs"]) - _candidate_input(fields["candidate"], prepared, inputs) - _add_fixed_resources(inputs, prepared["resources"]) - recipe = prepared["recipe"] - if ( - not isinstance(recipe, dict) or recipe.keys() != _RECIPE_FIELDS - or not all(_id(recipe[key]) for key in ( - "recipe_revision", "runtime_role", "entrypoint_revision", - )) - or recipe["entrypoint_kind"] not in ("python_module", "executable") - or not isinstance(recipe["entrypoint"], str) or not recipe["entrypoint"] - or not _digest(recipe["code_sha256"]) - or not isinstance(recipe["input_roles"], list) - or not all(_id(role) for role in recipe["input_roles"]) - or len(set(recipe["input_roles"])) != len(recipe["input_roles"]) - or not isinstance(recipe["args"], list) - or not isinstance(recipe["outputs"], list) - or not isinstance(recipe["required_capabilities"], list) - or not all(_id(item) for item in recipe["required_capabilities"]) - ): - raise ValueError("invalid frozen worker recipe") - paths = {role: item["materialized_path"] for role, item in inputs.items()} - outputs = _output_paths(recipe["outputs"]) - _require_disjoint_paths([*paths.values(), *outputs.values()]) - worker_inputs = {role: paths[role] for role in recipe["input_roles"]} - return { - **fields, - "protocol_digest": prepared["protocol_digest"], - "operation": prepared["operation"], - "validation_scope": prepared["validation_scope"], - "inputs": [inputs[role] for role in sorted(inputs)], - "required_capabilities": recipe["required_capabilities"], - "steps": [{ - "step_id": "main", - "runtime_role": recipe["runtime_role"], - "entrypoint_kind": recipe["entrypoint_kind"], - "entrypoint": recipe["entrypoint"], - "entrypoint_revision": recipe["entrypoint_revision"], - "expected_code_sha256": recipe["code_sha256"], - "args": _bind_args(recipe["args"], worker_inputs, outputs), - "cwd": ".", - "outputs": recipe["outputs"], - "timeout_seconds": None, - }], - } - - -def bind_execution(request: dict, prepared: dict) -> dict: - """Bind one frozen worker at the attempt root with the original attempt deadline.""" - try: - return deepcopy(_bind_spec(request, prepared)) - except (KeyError, TypeError, ValueError, AttributeError): - raise PublicError( - "InvalidExecutionSpec", stage="binder_validation", - message="The saved request and frozen worker recipe could not be bound.", - ) from None - -def to_evidence( - prepared: dict, prepared_ref: dict, record_ref: dict, committed_payload: dict, -) -> dict: - """Project one committed record revision into the Benchmark evidence envelope.""" - try: - _check_prepared_ref(prepared, prepared_ref, stage="assessment_binding") - if ( - record_ref.keys() != {"attempt_id", "record_version", "artifact"} - or not _id(record_ref["attempt_id"]) - or type(record_ref["record_version"]) is not int or record_ref["record_version"] < 1 - or not isinstance(committed_payload, dict) - or committed_payload.keys() != _RECORD_FIELDS - or type(committed_payload["schema_version"]) is not int - or committed_payload["schema_version"] != 1 - or type(committed_payload["record_version"]) is not int - ): - raise ValueError("invalid fixed record shape") - artifact = record_ref["artifact"] - validate_artifact_ref(artifact) - _logical_path(artifact["location"]) - if artifact["media_type"] != "application/json": - raise ValueError("expected a JSON record") - data = encode(committed_payload) - if artifact["sha256"] != sha256(data).hexdigest() or artifact["size_bytes"] != len(data): - raise PublicError( - "ArtifactIntegrityError", stage="assessment_binding", - message="The record bytes do not match the fixed reference.", - ) - if committed_payload["candidate"] is None: - raise PublicError( - "IdentityMismatch", stage="assessment_binding", - message="The fixed evaluation record has no candidate declaration.", - ) - if ( - committed_payload["attempt_id"] != record_ref["attempt_id"] - or committed_payload["request_id"] != record_ref["attempt_id"] - or committed_payload["record_version"] != record_ref["record_version"] - or committed_payload["prepared_ref"] != prepared_ref - or any(committed_payload[key] != prepared[key] - for key in ("protocol_digest", "operation", "validation_scope")) - ): - raise PublicError( - "IdentityMismatch", stage="assessment_binding", - message="The record does not belong to this attempt and preparation.", - ) - return deepcopy({ - "schema_version": 1, - "record_ref": record_ref, - "record_digest": artifact["sha256"], - "task": prepared["task"], - "task_source": "prepared_ref", - "record": committed_payload, - "artifact_checks": [], - }) - except (AttributeError, KeyError, TypeError, ValueError): - raise PublicError( - "InvalidRequest", stage="assessment_binding", - message="Expected a fixed v1 evaluation record and preparation.", - ) from None +__all__ = [ + "execution_fields", + "verify_protocol", + "check_assessment_identity", + "bind_execution", + "to_evidence", +] diff --git a/src/inferrsi/apps/candidate_provider.py b/src/inferrsi/apps/candidate_provider.py index bf2b27c6..10203121 100644 --- a/src/inferrsi/apps/candidate_provider.py +++ b/src/inferrsi/apps/candidate_provider.py @@ -1,321 +1,9 @@ -"""Plan candidate generation and collect the outputs retained by Harness.""" +"""Compatibility exports for :mod:`inferrsi.apps.handoff.candidate_provider`.""" -from collections.abc import Callable -from copy import deepcopy -from hashlib import sha256 - -from inferrsi.contracts.json_v1 import decode, encode -from inferrsi.harness.errors import PublicError - -from .bridge import ( - _ATTEMPT_FIELDS, - _CANDIDATE_FIELDS, - _definition, - _digest, - _id, - _input_paths, - _output_paths, - _require_disjoint_paths, +from .handoff.candidate_provider import ( + CandidateProvider, ) -from .storage.archive import _logical_path -from .storage.artifact_reader import ArtifactReader -from .storage.result import _RECORD_OBSERVATIONS, _check_ref, validate_artifact_ref - -_CONTEXT_FIELDS = { - "campaign_id", "generation_id", "candidate", "parent", "task_materials", - "delivered_context", "allowed_feedback", "output_contract", -} -_OUTPUT_CONTRACT_FIELDS = { - "manifest_role", "candidate_role", "format_schema", "required_input_roles", "parser_revision", -} -_MANIFEST_FIELDS = {"schema_version", "provider", "output_contract", "context_refs", "attempt_id"} -_PLAN_ROLE = "generation_plan" - - -class CandidateProvider: - """Apps adapter for the generation leg of a Harness loop. - - The configured parser implements the frozen parser revision. Given the worker's - manifest and candidate bytes, it returns candidate metadata (without context refs) - and a mapping from evaluation input roles to declared generation output roles. - """ - - def __init__( - self, *, provider: dict, output_contract: dict, steps: list[dict], - bind_inputs: Callable[[dict], list[dict]], output_root_for: Callable[[str], str], - required_capabilities: list[str], - parse_candidate: Callable[[bytes, bytes], tuple[dict, dict[str, str]]] | None = None, - ): - self._provider = deepcopy(provider) - self._output_contract = deepcopy(output_contract) - self._steps = deepcopy(steps) - self._bind_inputs = bind_inputs - self._output_root_for = output_root_for - self._required_capabilities = deepcopy(required_capabilities) - self._parse_candidate = parse_candidate - - def plan_generation(self, context: dict, attempt: dict) -> dict: - """Bind the authorized context and original attempt to the configured worker.""" - return _plan_generation( - context, attempt, provider=self._provider, output_contract=self._output_contract, - steps=self._steps, bind_inputs=self._bind_inputs, output_root_for=self._output_root_for, - required_capabilities=self._required_capabilities, - ) - - def collect_candidate(self, record: dict, *, artifacts: ArtifactReader) -> dict: - """Build a proposal from a fixed successful generation record and its outputs.""" - if self._parse_candidate is None: - raise PublicError( - "UnsupportedOperation", stage="candidate_collection", - message="No candidate parser is configured for this provider.", - ) - try: - record_ref, payload = _generation_record(record, artifacts) - manifest = _generation_manifest( - payload, artifacts, self._provider, self._output_contract, - ) - outputs = _generation_outputs(payload, self._steps) - contract = manifest["output_contract"] - manifest_ref = outputs[contract["manifest_role"]] - candidate_ref = outputs[contract["candidate_role"]] - worker_manifest = _read_artifact(artifacts, manifest_ref) - candidate_bytes = _read_artifact(artifacts, candidate_ref) - candidate, bindings = self._parse_candidate(worker_manifest, candidate_bytes) - inputs = _candidate_inputs(candidate, bindings, contract, outputs) - verified = {encode(manifest_ref), encode(candidate_ref)} - refs = [item["source_ref"] for item in inputs] - refs.extend(outputs[output["role"]] for step in self._steps - for output in step["outputs"] if output["required"]) - for ref in refs: - identity = encode(ref) - if identity not in verified: - with artifacts.open(ref): - pass - verified.add(identity) - except (AttributeError, KeyError, TypeError, ValueError) as exc: - raise PublicError( - "InvalidRequest", stage="candidate_collection", - message="Expected an accepted generation plan and a valid candidate output.", - ) from exc - return deepcopy({ - "candidate": {**candidate, "context_refs": manifest["context_refs"]}, - "inputs": inputs, - "generation_record_ref": record_ref, - }) - - -def _read_artifact(artifacts: ArtifactReader, ref: dict) -> bytes: - validate_artifact_ref(ref) - _logical_path(ref["location"]) - with artifacts.open(ref) as stream: - return stream.read() - - -def _generation_record(record: dict, artifacts: ArtifactReader) -> tuple[dict, dict]: - ref = record["record_ref"] - _check_ref(ref, "attempt_id", "record_version") - if ref["artifact"]["media_type"] != "application/json": - raise ValueError("expected a JSON record") - data = _read_artifact(artifacts, ref["artifact"]) - payload = decode(data) - receipt = {key: value for key, value in record.items() if key not in _RECORD_OBSERVATIONS} - if ( - encode(receipt) != data or payload["attempt_id"] != ref["attempt_id"] - or payload["request_id"] != ref["attempt_id"] - or payload["record_version"] != ref["record_version"] - ): - raise PublicError( - "IdentityMismatch", stage="candidate_collection", - message="The generation receipt differs from the committed record.", - ) - if ( - payload["phase"] != "finished" or payload["process_outcome"] != "exited" - or type(payload["exit_code"]) is not int or payload["exit_code"] != 0 - or payload["side_effect_unknown"] is not False - or any(payload[field] is not None for field in ( - "candidate", "prepared_ref", "protocol_digest", "operation", "validation_scope", - )) - ): - raise ValueError("incomplete or unsuccessful generation record") - return ref, payload - - -def _generation_manifest( - record: dict, artifacts: ArtifactReader, provider: dict, output_contract: dict, -) -> dict: - plans = [item for item in record["bound_inputs"] if item["role"] == _PLAN_ROLE] - if len(plans) != 1: - raise ValueError("expected one bound generation plan") - plan = plans[0] - ref = plan["retained_ref"] - if ( - plan["attempt_id"] != record["attempt_id"] or plan["identity_status"] != "matched" - or plan["actual_sha256"] != ref["sha256"] or plan["expected_sha256"] != ref["sha256"] - ): - raise ValueError("generation plan identity was not verified") - manifest = decode(_read_artifact(artifacts, ref)) - if ( - not isinstance(manifest, dict) or manifest.keys() != _MANIFEST_FIELDS - or type(manifest["schema_version"]) is not int or manifest["schema_version"] != 1 - or manifest["provider"] != provider or manifest["output_contract"] != output_contract - or manifest["attempt_id"] != record["attempt_id"] - or not isinstance(manifest["context_refs"], list) or not manifest["context_refs"] - ): - raise ValueError("generation manifest does not match the attempt and configured parser") - for context in manifest["context_refs"]: - validate_artifact_ref(context) - _logical_path(context["location"]) - return manifest - - -def _generation_outputs(record: dict, steps: list[dict]) -> dict: - declarations = {output["role"]: (step["step_id"], output) - for step in steps for output in step["outputs"]} - outputs = {} - for item in record["artifacts"]: - role = item["role"] - if role not in declarations: - continue - step_id, declaration = declarations[role] - if ( - role in outputs or item["attempt_id"] != record["attempt_id"] - or item["step_id"] != step_id or item["format_schema"] != declaration["format_schema"] - ): - raise ValueError("generation output must match its unique declared producer") - outputs[role] = item["artifact"] if item["status"] == "available" else None - if any(declaration["required"] and outputs.get(role) is None - for role, (_, declaration) in declarations.items()): - raise PublicError( - "ArtifactUnavailable", stage="candidate_collection", - message="A required generation output was not retained.", - ) - return outputs - - -def _candidate_inputs(candidate: dict, bindings: dict, contract: dict, outputs: dict) -> list: - if ( - not isinstance(candidate, dict) or candidate.keys() != _CANDIDATE_FIELDS - {"context_refs"} - or not all(_id(candidate[field]) for field in ("candidate_id", "input_role", "kind")) - or (candidate["parent_id"] is None) != (candidate["parent_digest"] is None) - or (candidate["parent_id"] is not None and ( - not _id(candidate["parent_id"]) or not _digest(candidate["parent_digest"]) - )) - or not isinstance(bindings, dict) - or bindings.keys() != {*contract["required_input_roles"], candidate["input_role"]} - or bindings[candidate["input_role"]] != contract["candidate_role"] - ): - raise ValueError("candidate metadata and input roles must match the frozen output contract") - inputs = [] - for role, output_role in sorted(bindings.items()): - ref = outputs.get(output_role) - if ref is None: - raise PublicError( - "ArtifactUnavailable", stage="candidate_collection", - message="A candidate input does not name a retained output.", - ) - validate_artifact_ref(ref) - inputs.append({ - "role": role, "source": ref["location"], "source_namespace": "artifact", - "source_ref": ref, "snapshot_format": "file-v1", "expected_sha256": ref["sha256"], - "materialized_path": f"inputs/{sha256(role.encode('ascii')).hexdigest()}", - }) - _input_paths(inputs) - return inputs - - -def _plan_generation( - context: dict, attempt: dict, *, provider: dict, output_contract: dict, - steps: list[dict], bind_inputs: Callable[[dict], list[dict]], - output_root_for: Callable[[str], str], required_capabilities: list[str], -) -> dict: - """Build the fixed-input plan for Harness to seal and execute.""" - try: - if ( - not isinstance(context, dict) or context.keys() != _CONTEXT_FIELDS - or not _id(context["campaign_id"]) or not _id(context["generation_id"]) - or not isinstance(attempt, dict) or attempt.keys() != _ATTEMPT_FIELDS - or not _id(attempt["attempt_id"]) or attempt["request_id"] != attempt["attempt_id"] - or not _definition(provider) - ): - raise ValueError("expected a candidate context, provider and allocated attempt") - if ( - not isinstance(output_contract, dict) - or output_contract.keys() != _OUTPUT_CONTRACT_FIELDS - or not all(_id(output_contract[key]) - for key in ("manifest_role", "candidate_role", "parser_revision")) - or not _definition(output_contract["format_schema"]) - or output_contract["format_schema"] != context["output_contract"]["format_schema"] - ): - raise ValueError("invalid generation output contract") - roles = output_contract["required_input_roles"] - if not isinstance(roles, list) or not all(_id(role) for role in roles): - raise ValueError("invalid required input roles") - if len(set(roles)) != len(roles): - raise ValueError("duplicate required input role") - delivery = context["delivered_context"]["artifact"] - for key in ("task_materials", "allowed_feedback"): - if not isinstance(context[key], list): - raise ValueError("expected lists of authorized generation artifacts") - allowed = set() - for ref in [delivery, *context["task_materials"], *context["allowed_feedback"]]: - validate_artifact_ref(ref) - _logical_path(ref["location"]) - allowed.add(encode(ref)) - inputs = bind_inputs(deepcopy(context)) - if not isinstance(inputs, list): - raise ValueError("expected generation inputs") - by_role = _input_paths(inputs) - if _PLAN_ROLE in by_role: - raise ValueError("the generation_plan input role is reserved for Harness sealing") - used = set() - for item in by_role.values(): - if item["source_namespace"] != "artifact": - raise ValueError("generation inputs must use fixed artifacts") - used.add(encode(item["source_ref"])) - if not used <= allowed or encode(delivery) not in used: - raise ValueError("expected the delivered context and only authorized fixed inputs") - if not isinstance(steps, list) or not steps: - raise ValueError("expected generation command steps") - outputs = [] - for step in steps: - if step["expected_code_sha256"] is not None or not isinstance(step["outputs"], list): - raise ValueError("expected ordinary generation command steps") - outputs.extend(step["outputs"]) - paths = _output_paths(outputs) - manifest_role = output_contract["manifest_role"] - candidate_role = output_contract["candidate_role"] - required = {output["role"]: output for output in outputs if output["required"]} - if ( - manifest_role == candidate_role or manifest_role not in required - or candidate_role not in required - or required[candidate_role]["format_schema"] != output_contract["format_schema"] - ): - raise ValueError("expected distinct required manifest and candidate outputs") - _require_disjoint_paths([*paths.values(), *(item["materialized_path"] for item in inputs)]) - output_root = output_root_for(attempt["attempt_id"]) - _logical_path(output_root) - if not isinstance(required_capabilities, list) or not all( - _id(capability) for capability in required_capabilities - ): - raise ValueError("invalid generation capabilities") - plan = { - "spec": { - **attempt, "schema_version": 1, "generation_record_ref": None, - "prepared_ref": None, "protocol_digest": None, "operation": None, - "validation_scope": None, "candidate": None, "inputs": inputs, - "steps": steps, "output_root": output_root, - "required_capabilities": required_capabilities, - }, - "manifest": { - "schema_version": 1, "provider": provider, "output_contract": output_contract, - "context_refs": [delivery], "attempt_id": attempt["attempt_id"], - }, - } - encode(plan) - except (KeyError, TypeError, ValueError) as exc: - raise PublicError( - "InvalidExecutionSpec", stage="generation_plan", - message="The generation plan could not be bound to the supplied context and attempt.", - ) from exc - return deepcopy(plan) +__all__ = [ + "CandidateProvider", +] diff --git a/src/inferrsi/apps/context_provider.py b/src/inferrsi/apps/context_provider.py index 58fdc682..d906a8af 100644 --- a/src/inferrsi/apps/context_provider.py +++ b/src/inferrsi/apps/context_provider.py @@ -1,137 +1,11 @@ -"""Project Knowledge selection into the in-process Harness delivery draft.""" +"""Compatibility exports for :mod:`inferrsi.apps.handoff.context_provider`.""" -import re -from dataclasses import dataclass -from hashlib import sha256 +from .handoff.context_provider import ( + ContextProvider, + DeliveredContextDraft, +) -from inferrsi.contracts.json_v1 import MAX_SAFE_INTEGER -from inferrsi.knowledge.knowledge_operations import KnowledgeReader - -_REQUEST_FIELDS = {"query", "ids", "pins", "selection_limits", "max_bytes", "round_id"} -_TEXT_OPTIONS = {"kind", "repo", "tier", "backend", "scenario", "relevance", "relevance_method"} -_SIZE_OPTIONS = {"limit", "max_bytes"} -_ID = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:/@+-]{0,255}") - - -@dataclass(frozen=True) -class DeliveredContextDraft: - """The actual bytes and metadata for Harness to retain and seal.""" - - content: bytes - intended_location: str - sha256: str - items: list[dict] - selection: dict - omissions: list[dict] - limitations: list[str] - - -class ContextProvider: - """Deliver whole UTF-8 resources in Knowledge's selection order.""" - - def __init__(self, reader: KnowledgeReader): - self.reader = reader - - def collect(self, request: dict) -> DeliveredContextDraft: - if not isinstance(request, dict) or request.keys() != _REQUEST_FIELDS: - raise ValueError("expected ContextRequest fields") - query, ids, pins = request["query"], request["ids"], request["pins"] - limits, max_bytes, round_id = ( - request["selection_limits"], request["max_bytes"], request["round_id"] - ) - if query is not None and not isinstance(query, str): - raise ValueError("expected a string or null query") - if not isinstance(ids, list) or not all(_identifier(item) for item in ids): - raise ValueError("expected Knowledge ids") - if type(max_bytes) is not int or not 0 <= max_bytes <= MAX_SAFE_INTEGER: - raise ValueError("expected a delivery byte limit in the v1 unsigned integer range") - if not _identifier(round_id): - raise ValueError("expected a round_id") - if not isinstance(limits, dict) or not limits.keys() <= _TEXT_OPTIONS | _SIZE_OPTIONS: - raise ValueError("unsupported Knowledge selection option") - if any(not isinstance(limits[key], str) for key in limits.keys() & _TEXT_OPTIONS): - raise ValueError("invalid Knowledge selection option value") - if any( - type(limits[key]) is not int or not 1 <= limits[key] <= MAX_SAFE_INTEGER - for key in limits.keys() & _SIZE_OPTIONS - ): - raise ValueError("invalid Knowledge selection option value") - - result = self.reader.collect( - query or "", ids=ids or None, revisions=_revisions(pins), - context_bytes=max_bytes or None, **limits, - ) - selection = {**result.get("selection", {}), **result["retrieval"]["selection"]} - selection.update(no_match=result["no_match"], collisions=result["collisions"]) - omissions = [_omission(item, stage="knowledge_selection") for item in result["omissions"]] - limitations = list(result["limitations"]) - items, payloads = [], [] - if max_bytes == 0: - omissions.extend( - _omission({**item, "reason": "context_limit"}, stage="context_delivery") - for item in result["items"] - ) - for item in result.get("context_omissions", ()): - omissions.append(_omission(item, stage="context_delivery")) - for context in result.get("contexts", ()): - reference, revision = context["ref"], context["revision"] - parts, roles = [], [] - for resource in context["resources"]: - body = resource["content"].encode("utf-8") - if sha256(body).hexdigest() != resource["sha256"]: - raise ValueError("Knowledge context resource digest mismatch") - parts.append(body) - roles.append(resource["role"]) - block = b"".join(parts) - if len(block) != context["content_bytes"]: - raise ValueError("Knowledge context byte count mismatch") - payloads.append(block) - items.append({ - "pin": {"reference": reference, "revision": revision}, - "delivered_roles": list(dict.fromkeys(roles)), - "delivered_bytes": len(block), - }) - omissions.extend( - _omission({**item, "ref": reference}, stage="context_delivery") - for item in context["omissions"] - ) - limitations.extend(context["limitations"]) - content = b"".join(payloads) - if len(content) > max_bytes: - raise ValueError("Knowledge context exceeds the delivery byte limit") - # A round identifier can contain path separators or platform-specific names. - round_key = sha256(round_id.encode("ascii")).hexdigest() - return DeliveredContextDraft( - content=content, intended_location=f"context/{round_key}/delivered.bin", - sha256=sha256(content).hexdigest(), items=items, selection=selection, - omissions=omissions, limitations=list(dict.fromkeys(limitations)), - ) - - -def _identifier(value: object) -> bool: - return isinstance(value, str) and _ID.fullmatch(value) is not None - - -def _revisions(pins: object) -> dict[str, str]: - if not isinstance(pins, list): - raise ValueError("expected Knowledge pins") - revisions = {} - for pin in pins: - if ( - not isinstance(pin, dict) or pin.keys() != {"name", "revision"} - or not _identifier(pin["name"]) or not _identifier(pin["revision"]) - ): - raise ValueError("expected Knowledge pin name and revision") - name, revision = pin["name"], pin["revision"] - if revisions.setdefault(name, revision) != revision: - raise ValueError("conflicting Knowledge revisions") - return revisions - - -def _omission(item: dict, *, stage: str) -> dict: - reference = item.get("ref", item.get("id")) - location = "/".join(part for part in (reference, item.get("path")) if part) - return { - "code": item["reason"], "stage": stage, "message": f"{location}: {item['reason']}", - "retryable": False, - } +__all__ = [ + "DeliveredContextDraft", + "ContextProvider", +] diff --git a/src/inferrsi/apps/handoff/__init__.py b/src/inferrsi/apps/handoff/__init__.py new file mode 100644 index 00000000..6717806f --- /dev/null +++ b/src/inferrsi/apps/handoff/__init__.py @@ -0,0 +1 @@ +"""Bind Apps inputs and retained evidence to the injected Harness interfaces.""" diff --git a/src/inferrsi/apps/handoff/bridge.py b/src/inferrsi/apps/handoff/bridge.py new file mode 100644 index 00000000..2c609943 --- /dev/null +++ b/src/inferrsi/apps/handoff/bridge.py @@ -0,0 +1,474 @@ +"""Map fixed Benchmark preparation and a saved attempt into a Harness spec.""" + +import re +from copy import deepcopy +from hashlib import sha256 + +from inferrsi.contracts.json_v1 import decode, encode +from inferrsi.harness.errors import PublicError + +from ..storage.archive import _logical_path +from ..storage.result import validate_artifact_ref + +_ATTEMPT_FIELDS = { + "request_id", "run_id", "attempt_id", "owner", "target_request", "deadline_utc", + "resources", "budget", "retry_of", "retry_reason", +} +_PROPOSAL_FIELDS = {"candidate", "inputs", "generation_record_ref"} +_EXECUTE_FIELDS = {"schema_version", "prepared_ref", "proposal", "attempt", "output_root"} +_INPUT_FIELDS = { + "role", "source", "source_namespace", "source_ref", "snapshot_format", "expected_sha256", + "materialized_path", +} +_OUTPUT_FIELDS = {"role", "path", "required", "media_type", "format_schema"} +_CANDIDATE_FIELDS = {"candidate_id", "kind", "input_role", "parent_id", "parent_digest", + "context_refs"} +_RECIPE_FIELDS = { + "recipe_revision", "runtime_role", "entrypoint_kind", "entrypoint", "entrypoint_revision", + "code_sha256", "args", "input_roles", "outputs", "required_capabilities", +} +_PREPARED_FIELDS = { + "schema_version", "prepared_id", "task", "grader", "operation", "validation_scope", + "protocol", "protocol_digest", "candidate_contract", "expected_candidate", + "required_evidence", "recipe", "resources", "created_at", "display_notes", +} +_RESOURCE_FIELDS = {"role", "artifact", "required_for", "format_schema"} +_PROTOCOL_FIELDS = { + "schema_version", "task", "grader", "operation", "validation_scope", + "candidate_contract", "worker_recipe", "input_requirements", "claim_definitions", + "metric_definitions", "required_evidence", "task_parameters", "baseline", "reference", + "quality_reference", "sampling", "feedback_visibility", "budget_policy_refs", + "resources", "display_notes", +} +_PROTOCOL_COPIES = ( + "task", "grader", "operation", "validation_scope", "candidate_contract", "required_evidence", +) +_RECORD_FIELDS = { + "schema_version", "request_id", "run_id", "attempt_id", "request_digest", "owner", + "target_request", "target_binding", "retry_of", "retry_reason", "generation_record_ref", + "prepared_ref", "protocol_digest", "operation", "validation_scope", "candidate", + "record_version", "recorded_at", "bound_inputs", "phase", "started", "side_effect_unknown", + "process_outcome", "exit_code", "elapsed_seconds", "steps", "cancellation", "cleanup", + "artifacts", "checks", "budget_admission", "usage", "resource_leases", "errors", +} +_ID = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:/@+-]{0,255}") +_DIGEST = re.compile(r"[0-9a-f]{64}") +_SEMANTIC_ID = re.compile(r"sha256:[0-9a-f]{64}") +_PLACEHOLDER = re.compile(r"\{(input|output):([^{}]+)\}") + + +def execution_fields(request: dict) -> dict: + """Return the fields that an execution binder must preserve exactly.""" + if not isinstance(request, dict) or request.keys() != _EXECUTE_FIELDS: + raise ValueError("expected AppsExecuteRequest fields") + attempt = request["attempt"] + proposal = request["proposal"] + if ( + type(request["schema_version"]) is not int + or request["schema_version"] != 1 + or not isinstance(attempt, dict) + or attempt.keys() != _ATTEMPT_FIELDS + or not isinstance(attempt["attempt_id"], str) + or not attempt["attempt_id"] + or attempt["request_id"] != attempt["attempt_id"] + or not isinstance(proposal, dict) + or proposal.keys() != _PROPOSAL_FIELDS + or not isinstance(proposal["inputs"], list) + ): + raise ValueError("expected a pre-allocated AttemptContext") + return { + **attempt, + "schema_version": 1, + "prepared_ref": request["prepared_ref"], + "output_root": request["output_root"], + "candidate": proposal["candidate"], + "generation_record_ref": proposal["generation_record_ref"], + } + + +def _id(value: object) -> bool: + return isinstance(value, str) and _ID.fullmatch(value) is not None + + +def _digest(value: object) -> bool: + return isinstance(value, str) and _DIGEST.fullmatch(value) is not None + + +def _definition(value: object) -> bool: + return ( + isinstance(value, dict) and value.keys() == {"name", "revision"} + and all(_id(value[key]) for key in ("name", "revision")) + ) + + +def _candidate_input(candidate: dict, prepared: dict, inputs: dict) -> None: + if not isinstance(candidate, dict) or candidate.keys() != _CANDIDATE_FIELDS: + raise ValueError("invalid candidate fields") + contract = prepared["candidate_contract"] + role = candidate["input_role"] + if ( + role not in inputs or role != contract["input_role"] + or candidate["kind"] != contract["kind"] or not _id(candidate["candidate_id"]) + or not _definition(contract["format_schema"]) + or (candidate["parent_id"] is None) != (candidate["parent_digest"] is None) + or not isinstance(candidate["context_refs"], list) + ): + raise ValueError("candidate does not match the frozen input role or format") + if candidate["parent_id"] is not None and ( + not _id(candidate["parent_id"]) or not _digest(candidate["parent_digest"]) + ): + raise ValueError("invalid parent identity") + for ref in candidate["context_refs"]: + validate_artifact_ref(ref) + _logical_path(ref["location"]) + rule = contract["identity_rule"] + expected = inputs[role]["expected_sha256"] + if rule not in ( + {"name": "captured-sha256", "revision": "1"}, + {"name": "expected-sha256", "revision": "1"}, + ): + raise PublicError( + "UnsupportedRuleVersion", stage="binder_validation", + message="The frozen candidate identity rule is unsupported.", + ) + if rule["name"] == "expected-sha256" and expected is None: + raise ValueError("candidate input is missing an expected digest") + frozen = prepared["expected_candidate"] + if frozen is not None and ( + not _digest(frozen["sha256"]) or expected != frozen["sha256"] + or candidate["candidate_id"] != frozen["candidate_id"] + or contract["format_schema"] != frozen["format_schema"] + ): + raise ValueError("candidate declaration conflicts with the frozen expectation") + + +def _input_paths(items: list) -> dict: + inputs = {} + for item in items: + if not isinstance(item, dict) or item.keys() != _INPUT_FIELDS: + raise ValueError("invalid input fields") + role, expected = item["role"], item["expected_sha256"] + if ( + not _id(role) or role in inputs or not _id(item["snapshot_format"]) + or not isinstance(item["source"], str) or not item["source"] + or (expected is not None and not _digest(expected)) + ): + raise ValueError("invalid or repeated input role or identity") + _logical_path(item["materialized_path"]) + source_ref = item["source_ref"] + if item["source_namespace"] == "artifact": + validate_artifact_ref(source_ref) + _logical_path(source_ref["location"]) + if item["source"] != source_ref["location"] or expected != source_ref["sha256"]: + raise ValueError("input source conflicts with its fixed artifact") + elif item["source_namespace"] not in ("controller", "target") or source_ref is not None: + raise ValueError("invalid input source namespace") + inputs[role] = item + return inputs + + +def _add_fixed_resources(inputs: dict, resources: list) -> None: + if not isinstance(resources, list): + raise ValueError("invalid fixed resource list") + seen = set() + for resource in resources: + if ( + not isinstance(resource, dict) or resource.keys() != _RESOURCE_FIELDS + or not _id(resource["role"]) or resource["role"] in seen + or not isinstance(resource["required_for"], list) + or not resource["required_for"] or not _definition(resource["format_schema"]) + or any(use not in ("prepare", "execute", "assess") for use in resource["required_for"]) + ): + raise ValueError("invalid or repeated fixed resource") + seen.add(resource["role"]) + if "execute" not in resource["required_for"]: + continue + role, ref = resource["role"], resource["artifact"] + validate_artifact_ref(ref) + _logical_path(ref["location"]) + if role in inputs: + raise ValueError("a fixed execution resource role is already bound") + role_hash = sha256(role.encode("ascii")).hexdigest() + inputs[role] = { + "role": role, + "source": ref["location"], + "source_namespace": "artifact", + "source_ref": ref, + "snapshot_format": "file-v1", + "expected_sha256": ref["sha256"], + "materialized_path": f"inputs/{role_hash}", + } + + +def _output_paths(outputs: list) -> dict: + paths = {} + for item in outputs: + if ( + not isinstance(item, dict) or item.keys() != _OUTPUT_FIELDS + or not _id(item["role"]) or item["role"] in paths + or type(item["required"]) is not bool + or not isinstance(item["media_type"], str) or not item["media_type"] + or not _definition(item["format_schema"]) + ): + raise ValueError("invalid or repeated output declaration") + _logical_path(item["path"]) + paths[item["role"]] = item["path"] + return paths + + +def _bind_args(args: list, inputs: dict, outputs: dict) -> list[str]: + bound = [] + for arg in args: + if not isinstance(arg, str): + raise ValueError("recipe arguments must be strings") + match = _PLACEHOLDER.fullmatch(arg) + if match: + kind, role = match.groups() + bound.append(inputs[role] if kind == "input" else outputs[role]) + elif "{input:" in arg or "{output:" in arg: + raise ValueError("recipe placeholders must occupy the whole argument") + else: + bound.append(arg) + return bound + + +def _require_disjoint_paths(paths: list[str]) -> None: + ordered = sorted(_logical_path(path) for path in paths) + if any(second[:len(first)] == first for first, second in zip(ordered, ordered[1:])): + raise ValueError("input and output paths must not overlap") + + +def _resource_projection(resource: dict) -> dict: + if not isinstance(resource, dict) or resource.keys() != _RESOURCE_FIELDS: + raise ValueError("invalid protocol resource") + return {**resource, "artifact": _artifact_projection(resource["artifact"])} + + +def verify_protocol(prepared: dict, data: bytes) -> None: + """Check the archived protocol's identity and the preparation's frozen fields.""" + try: + ref = prepared["protocol"] + validate_artifact_ref(ref) + protocol = decode(data) + if ( + not isinstance(protocol, dict) or protocol.keys() != _PROTOCOL_FIELDS + or type(protocol["schema_version"]) is not int or protocol["schema_version"] != 1 + or not isinstance(protocol["resources"], list) + or not isinstance(prepared["resources"], list) + ): + raise ValueError("invalid ProtocolV1 envelope") + projection = dict(protocol) + del projection["display_notes"] + resources = [_resource_projection(item) for item in protocol["resources"]] + closure = list(resources) + projection["resources"] = resources + for key in ("baseline", "reference", "quality_reference"): + if protocol[key] is not None: + projection[key] = _resource_projection(protocol[key]) + closure.append(projection[key]) + digest = "sha256:" + sha256(encode(projection)).hexdigest() + fixed_resources = [_resource_projection(item) for item in prepared["resources"]] + expected_resources = {item["role"]: item for item in closure} + if len(expected_resources) != len(closure): + raise ValueError("protocol resource roles must be unique") + if ( + ref["size_bytes"] != len(data) or ref["sha256"] != sha256(data).hexdigest() + or prepared["protocol_digest"] != digest + or encode(prepared["recipe"]) != encode(protocol["worker_recipe"]) + or any(encode(prepared[key]) != encode(protocol[key]) for key in _PROTOCOL_COPIES) + or encode(fixed_resources) != encode( + [expected_resources[role] for role in sorted(expected_resources)] + ) + ): + raise PublicError( + "IdentityMismatch", stage="binder_validation", + message="The fixed preparation disagrees with its archived protocol.", + ) + except (KeyError, TypeError, ValueError): + raise PublicError( + "InvalidExecutionSpec", stage="binder_validation", + message="The fixed preparation or protocol is malformed.", + ) from None + + +def _artifact_projection(ref: dict) -> dict: + validate_artifact_ref(ref) + _logical_path(ref["location"]) + return {key: value for key, value in ref.items() if key != "location"} + + +def check_assessment_identity(assessment: dict) -> None: + """Verify the v1 semantic ID while preserving the assessor's original bytes.""" + projection = deepcopy(assessment) + identity = projection.pop("assessment_id") + del projection["assessed_at"] + refs = [projection["prepared_ref"], projection["record_ref"], *projection["derived_from"]] + refs.extend(item["against"] for item in projection["comparison"]) + if projection["supersedes"] is not None: + refs.append(projection["supersedes"]) + for ref in refs: + ref["artifact"] = _artifact_projection(ref["artifact"]) + for items, field in ((projection["claims"], "evidence"), + (projection["metrics"], "raw_samples")): + for item in items: + item[field] = [_artifact_projection(ref) for ref in item[field]] + projection["evidence_artifacts"] = [ + _artifact_projection(ref) for ref in projection["evidence_artifacts"] + ] + if projection["candidate"] is not None: + candidate = projection["candidate"] + candidate["context_refs"] = [_artifact_projection(ref) for ref in candidate["context_refs"]] + if identity != "sha256:" + sha256(encode(projection)).hexdigest(): + raise ValueError("invalid assessment semantic identity") + + +def _check_prepared_ref(prepared: dict, ref: dict, *, stage: str) -> None: + if ( + not isinstance(ref, dict) or ref.keys() != {"prepared_id", "schema_version", "artifact"} + or not isinstance(prepared, dict) or prepared.keys() != _PREPARED_FIELDS + ): + raise ValueError("invalid prepared object or reference fields") + validate_artifact_ref(ref["artifact"]) + _logical_path(ref["artifact"]["location"]) + data = encode(prepared) + if ( + type(ref["schema_version"]) is not int or ref["schema_version"] != 1 + or type(prepared["schema_version"]) is not int or prepared["schema_version"] != 1 + or not _SEMANTIC_ID.fullmatch(ref["prepared_id"]) + or prepared["prepared_id"] != ref["prepared_id"] + or ref["artifact"]["media_type"] != "application/json" + or ref["artifact"]["size_bytes"] != len(data) + or ref["artifact"]["sha256"] != sha256(data).hexdigest() + ): + raise PublicError( + "IdentityMismatch", stage=stage, + message="The preparation does not match its fixed reference.", + ) + if ( + not _id(prepared["operation"]) or not _id(prepared["validation_scope"]) + or not _SEMANTIC_ID.fullmatch(prepared["protocol_digest"]) + ): + raise ValueError("invalid prepared operation, scope, or protocol digest") + + +def _bind_spec(request: dict, prepared: dict) -> dict: + fields = execution_fields(request) + _check_prepared_ref(prepared, fields["prepared_ref"], stage="binder_validation") + _logical_path(fields["output_root"]) + inputs = _input_paths(request["proposal"]["inputs"]) + _candidate_input(fields["candidate"], prepared, inputs) + _add_fixed_resources(inputs, prepared["resources"]) + recipe = prepared["recipe"] + if ( + not isinstance(recipe, dict) or recipe.keys() != _RECIPE_FIELDS + or not all(_id(recipe[key]) for key in ( + "recipe_revision", "runtime_role", "entrypoint_revision", + )) + or recipe["entrypoint_kind"] not in ("python_module", "executable") + or not isinstance(recipe["entrypoint"], str) or not recipe["entrypoint"] + or not _digest(recipe["code_sha256"]) + or not isinstance(recipe["input_roles"], list) + or not all(_id(role) for role in recipe["input_roles"]) + or len(set(recipe["input_roles"])) != len(recipe["input_roles"]) + or not isinstance(recipe["args"], list) + or not isinstance(recipe["outputs"], list) + or not isinstance(recipe["required_capabilities"], list) + or not all(_id(item) for item in recipe["required_capabilities"]) + ): + raise ValueError("invalid frozen worker recipe") + paths = {role: item["materialized_path"] for role, item in inputs.items()} + outputs = _output_paths(recipe["outputs"]) + _require_disjoint_paths([*paths.values(), *outputs.values()]) + worker_inputs = {role: paths[role] for role in recipe["input_roles"]} + return { + **fields, + "protocol_digest": prepared["protocol_digest"], + "operation": prepared["operation"], + "validation_scope": prepared["validation_scope"], + "inputs": [inputs[role] for role in sorted(inputs)], + "required_capabilities": recipe["required_capabilities"], + "steps": [{ + "step_id": "main", + "runtime_role": recipe["runtime_role"], + "entrypoint_kind": recipe["entrypoint_kind"], + "entrypoint": recipe["entrypoint"], + "entrypoint_revision": recipe["entrypoint_revision"], + "expected_code_sha256": recipe["code_sha256"], + "args": _bind_args(recipe["args"], worker_inputs, outputs), + "cwd": ".", + "outputs": recipe["outputs"], + "timeout_seconds": None, + }], + } + + +def bind_execution(request: dict, prepared: dict) -> dict: + """Bind one frozen worker at the attempt root with the original attempt deadline.""" + try: + return deepcopy(_bind_spec(request, prepared)) + except (KeyError, TypeError, ValueError, AttributeError): + raise PublicError( + "InvalidExecutionSpec", stage="binder_validation", + message="The saved request and frozen worker recipe could not be bound.", + ) from None + + +def to_evidence( + prepared: dict, prepared_ref: dict, record_ref: dict, committed_payload: dict, +) -> dict: + """Project one committed record revision into the Benchmark evidence envelope.""" + try: + _check_prepared_ref(prepared, prepared_ref, stage="assessment_binding") + if ( + record_ref.keys() != {"attempt_id", "record_version", "artifact"} + or not _id(record_ref["attempt_id"]) + or type(record_ref["record_version"]) is not int or record_ref["record_version"] < 1 + or not isinstance(committed_payload, dict) + or committed_payload.keys() != _RECORD_FIELDS + or type(committed_payload["schema_version"]) is not int + or committed_payload["schema_version"] != 1 + or type(committed_payload["record_version"]) is not int + ): + raise ValueError("invalid fixed record shape") + artifact = record_ref["artifact"] + validate_artifact_ref(artifact) + _logical_path(artifact["location"]) + if artifact["media_type"] != "application/json": + raise ValueError("expected a JSON record") + data = encode(committed_payload) + if artifact["sha256"] != sha256(data).hexdigest() or artifact["size_bytes"] != len(data): + raise PublicError( + "ArtifactIntegrityError", stage="assessment_binding", + message="The record bytes do not match the fixed reference.", + ) + if committed_payload["candidate"] is None: + raise PublicError( + "IdentityMismatch", stage="assessment_binding", + message="The fixed evaluation record has no candidate declaration.", + ) + if ( + committed_payload["attempt_id"] != record_ref["attempt_id"] + or committed_payload["request_id"] != record_ref["attempt_id"] + or committed_payload["record_version"] != record_ref["record_version"] + or committed_payload["prepared_ref"] != prepared_ref + or any(committed_payload[key] != prepared[key] + for key in ("protocol_digest", "operation", "validation_scope")) + ): + raise PublicError( + "IdentityMismatch", stage="assessment_binding", + message="The record does not belong to this attempt and preparation.", + ) + return deepcopy({ + "schema_version": 1, + "record_ref": record_ref, + "record_digest": artifact["sha256"], + "task": prepared["task"], + "task_source": "prepared_ref", + "record": committed_payload, + "artifact_checks": [], + }) + except (AttributeError, KeyError, TypeError, ValueError): + raise PublicError( + "InvalidRequest", stage="assessment_binding", + message="Expected a fixed v1 evaluation record and preparation.", + ) from None diff --git a/src/inferrsi/apps/handoff/candidate_provider.py b/src/inferrsi/apps/handoff/candidate_provider.py new file mode 100644 index 00000000..d4234f16 --- /dev/null +++ b/src/inferrsi/apps/handoff/candidate_provider.py @@ -0,0 +1,321 @@ +"""Plan candidate generation and collect the outputs retained by Harness.""" + +from collections.abc import Callable +from copy import deepcopy +from hashlib import sha256 + +from inferrsi.contracts.json_v1 import decode, encode +from inferrsi.harness.errors import PublicError + +from ..storage.archive import _logical_path +from ..storage.artifact_reader import ArtifactReader +from ..storage.result import _RECORD_OBSERVATIONS, _check_ref, validate_artifact_ref +from .bridge import ( + _ATTEMPT_FIELDS, + _CANDIDATE_FIELDS, + _definition, + _digest, + _id, + _input_paths, + _output_paths, + _require_disjoint_paths, +) + +_CONTEXT_FIELDS = { + "campaign_id", "generation_id", "candidate", "parent", "task_materials", + "delivered_context", "allowed_feedback", "output_contract", +} +_OUTPUT_CONTRACT_FIELDS = { + "manifest_role", "candidate_role", "format_schema", "required_input_roles", "parser_revision", +} +_MANIFEST_FIELDS = {"schema_version", "provider", "output_contract", "context_refs", "attempt_id"} +_PLAN_ROLE = "generation_plan" + + +class CandidateProvider: + """Apps adapter for the generation leg of a Harness loop. + + The configured parser implements the frozen parser revision. Given the worker's + manifest and candidate bytes, it returns candidate metadata (without context refs) + and a mapping from evaluation input roles to declared generation output roles. + """ + + def __init__( + self, *, provider: dict, output_contract: dict, steps: list[dict], + bind_inputs: Callable[[dict], list[dict]], output_root_for: Callable[[str], str], + required_capabilities: list[str], + parse_candidate: Callable[[bytes, bytes], tuple[dict, dict[str, str]]] | None = None, + ): + self._provider = deepcopy(provider) + self._output_contract = deepcopy(output_contract) + self._steps = deepcopy(steps) + self._bind_inputs = bind_inputs + self._output_root_for = output_root_for + self._required_capabilities = deepcopy(required_capabilities) + self._parse_candidate = parse_candidate + + def plan_generation(self, context: dict, attempt: dict) -> dict: + """Bind the authorized context and original attempt to the configured worker.""" + return _plan_generation( + context, attempt, provider=self._provider, output_contract=self._output_contract, + steps=self._steps, bind_inputs=self._bind_inputs, output_root_for=self._output_root_for, + required_capabilities=self._required_capabilities, + ) + + def collect_candidate(self, record: dict, *, artifacts: ArtifactReader) -> dict: + """Build a proposal from a fixed successful generation record and its outputs.""" + if self._parse_candidate is None: + raise PublicError( + "UnsupportedOperation", stage="candidate_collection", + message="No candidate parser is configured for this provider.", + ) + try: + record_ref, payload = _generation_record(record, artifacts) + manifest = _generation_manifest( + payload, artifacts, self._provider, self._output_contract, + ) + outputs = _generation_outputs(payload, self._steps) + contract = manifest["output_contract"] + manifest_ref = outputs[contract["manifest_role"]] + candidate_ref = outputs[contract["candidate_role"]] + worker_manifest = _read_artifact(artifacts, manifest_ref) + candidate_bytes = _read_artifact(artifacts, candidate_ref) + candidate, bindings = self._parse_candidate(worker_manifest, candidate_bytes) + inputs = _candidate_inputs(candidate, bindings, contract, outputs) + verified = {encode(manifest_ref), encode(candidate_ref)} + refs = [item["source_ref"] for item in inputs] + refs.extend(outputs[output["role"]] for step in self._steps + for output in step["outputs"] if output["required"]) + for ref in refs: + identity = encode(ref) + if identity not in verified: + with artifacts.open(ref): + pass + verified.add(identity) + except (AttributeError, KeyError, TypeError, ValueError) as exc: + raise PublicError( + "InvalidRequest", stage="candidate_collection", + message="Expected an accepted generation plan and a valid candidate output.", + ) from exc + return deepcopy({ + "candidate": {**candidate, "context_refs": manifest["context_refs"]}, + "inputs": inputs, + "generation_record_ref": record_ref, + }) + + +def _read_artifact(artifacts: ArtifactReader, ref: dict) -> bytes: + validate_artifact_ref(ref) + _logical_path(ref["location"]) + with artifacts.open(ref) as stream: + return stream.read() + + +def _generation_record(record: dict, artifacts: ArtifactReader) -> tuple[dict, dict]: + ref = record["record_ref"] + _check_ref(ref, "attempt_id", "record_version") + if ref["artifact"]["media_type"] != "application/json": + raise ValueError("expected a JSON record") + data = _read_artifact(artifacts, ref["artifact"]) + payload = decode(data) + receipt = {key: value for key, value in record.items() if key not in _RECORD_OBSERVATIONS} + if ( + encode(receipt) != data or payload["attempt_id"] != ref["attempt_id"] + or payload["request_id"] != ref["attempt_id"] + or payload["record_version"] != ref["record_version"] + ): + raise PublicError( + "IdentityMismatch", stage="candidate_collection", + message="The generation receipt differs from the committed record.", + ) + if ( + payload["phase"] != "finished" or payload["process_outcome"] != "exited" + or type(payload["exit_code"]) is not int or payload["exit_code"] != 0 + or payload["side_effect_unknown"] is not False + or any(payload[field] is not None for field in ( + "candidate", "prepared_ref", "protocol_digest", "operation", "validation_scope", + )) + ): + raise ValueError("incomplete or unsuccessful generation record") + return ref, payload + + +def _generation_manifest( + record: dict, artifacts: ArtifactReader, provider: dict, output_contract: dict, +) -> dict: + plans = [item for item in record["bound_inputs"] if item["role"] == _PLAN_ROLE] + if len(plans) != 1: + raise ValueError("expected one bound generation plan") + plan = plans[0] + ref = plan["retained_ref"] + if ( + plan["attempt_id"] != record["attempt_id"] or plan["identity_status"] != "matched" + or plan["actual_sha256"] != ref["sha256"] or plan["expected_sha256"] != ref["sha256"] + ): + raise ValueError("generation plan identity was not verified") + manifest = decode(_read_artifact(artifacts, ref)) + if ( + not isinstance(manifest, dict) or manifest.keys() != _MANIFEST_FIELDS + or type(manifest["schema_version"]) is not int or manifest["schema_version"] != 1 + or manifest["provider"] != provider or manifest["output_contract"] != output_contract + or manifest["attempt_id"] != record["attempt_id"] + or not isinstance(manifest["context_refs"], list) or not manifest["context_refs"] + ): + raise ValueError("generation manifest does not match the attempt and configured parser") + for context in manifest["context_refs"]: + validate_artifact_ref(context) + _logical_path(context["location"]) + return manifest + + +def _generation_outputs(record: dict, steps: list[dict]) -> dict: + declarations = {output["role"]: (step["step_id"], output) + for step in steps for output in step["outputs"]} + outputs = {} + for item in record["artifacts"]: + role = item["role"] + if role not in declarations: + continue + step_id, declaration = declarations[role] + if ( + role in outputs or item["attempt_id"] != record["attempt_id"] + or item["step_id"] != step_id or item["format_schema"] != declaration["format_schema"] + ): + raise ValueError("generation output must match its unique declared producer") + outputs[role] = item["artifact"] if item["status"] == "available" else None + if any(declaration["required"] and outputs.get(role) is None + for role, (_, declaration) in declarations.items()): + raise PublicError( + "ArtifactUnavailable", stage="candidate_collection", + message="A required generation output was not retained.", + ) + return outputs + + +def _candidate_inputs(candidate: dict, bindings: dict, contract: dict, outputs: dict) -> list: + if ( + not isinstance(candidate, dict) or candidate.keys() != _CANDIDATE_FIELDS - {"context_refs"} + or not all(_id(candidate[field]) for field in ("candidate_id", "input_role", "kind")) + or (candidate["parent_id"] is None) != (candidate["parent_digest"] is None) + or (candidate["parent_id"] is not None and ( + not _id(candidate["parent_id"]) or not _digest(candidate["parent_digest"]) + )) + or not isinstance(bindings, dict) + or bindings.keys() != {*contract["required_input_roles"], candidate["input_role"]} + or bindings[candidate["input_role"]] != contract["candidate_role"] + ): + raise ValueError("candidate metadata and input roles must match the frozen output contract") + inputs = [] + for role, output_role in sorted(bindings.items()): + ref = outputs.get(output_role) + if ref is None: + raise PublicError( + "ArtifactUnavailable", stage="candidate_collection", + message="A candidate input does not name a retained output.", + ) + validate_artifact_ref(ref) + inputs.append({ + "role": role, "source": ref["location"], "source_namespace": "artifact", + "source_ref": ref, "snapshot_format": "file-v1", "expected_sha256": ref["sha256"], + "materialized_path": f"inputs/{sha256(role.encode('ascii')).hexdigest()}", + }) + _input_paths(inputs) + return inputs + + +def _plan_generation( + context: dict, attempt: dict, *, provider: dict, output_contract: dict, + steps: list[dict], bind_inputs: Callable[[dict], list[dict]], + output_root_for: Callable[[str], str], required_capabilities: list[str], +) -> dict: + """Build the fixed-input plan for Harness to seal and execute.""" + try: + if ( + not isinstance(context, dict) or context.keys() != _CONTEXT_FIELDS + or not _id(context["campaign_id"]) or not _id(context["generation_id"]) + or not isinstance(attempt, dict) or attempt.keys() != _ATTEMPT_FIELDS + or not _id(attempt["attempt_id"]) or attempt["request_id"] != attempt["attempt_id"] + or not _definition(provider) + ): + raise ValueError("expected a candidate context, provider and allocated attempt") + if ( + not isinstance(output_contract, dict) + or output_contract.keys() != _OUTPUT_CONTRACT_FIELDS + or not all(_id(output_contract[key]) + for key in ("manifest_role", "candidate_role", "parser_revision")) + or not _definition(output_contract["format_schema"]) + or output_contract["format_schema"] != context["output_contract"]["format_schema"] + ): + raise ValueError("invalid generation output contract") + roles = output_contract["required_input_roles"] + if not isinstance(roles, list) or not all(_id(role) for role in roles): + raise ValueError("invalid required input roles") + if len(set(roles)) != len(roles): + raise ValueError("duplicate required input role") + delivery = context["delivered_context"]["artifact"] + for key in ("task_materials", "allowed_feedback"): + if not isinstance(context[key], list): + raise ValueError("expected lists of authorized generation artifacts") + allowed = set() + for ref in [delivery, *context["task_materials"], *context["allowed_feedback"]]: + validate_artifact_ref(ref) + _logical_path(ref["location"]) + allowed.add(encode(ref)) + inputs = bind_inputs(deepcopy(context)) + if not isinstance(inputs, list): + raise ValueError("expected generation inputs") + by_role = _input_paths(inputs) + if _PLAN_ROLE in by_role: + raise ValueError("the generation_plan input role is reserved for Harness sealing") + used = set() + for item in by_role.values(): + if item["source_namespace"] != "artifact": + raise ValueError("generation inputs must use fixed artifacts") + used.add(encode(item["source_ref"])) + if not used <= allowed or encode(delivery) not in used: + raise ValueError("expected the delivered context and only authorized fixed inputs") + + if not isinstance(steps, list) or not steps: + raise ValueError("expected generation command steps") + outputs = [] + for step in steps: + if step["expected_code_sha256"] is not None or not isinstance(step["outputs"], list): + raise ValueError("expected ordinary generation command steps") + outputs.extend(step["outputs"]) + paths = _output_paths(outputs) + manifest_role = output_contract["manifest_role"] + candidate_role = output_contract["candidate_role"] + required = {output["role"]: output for output in outputs if output["required"]} + if ( + manifest_role == candidate_role or manifest_role not in required + or candidate_role not in required + or required[candidate_role]["format_schema"] != output_contract["format_schema"] + ): + raise ValueError("expected distinct required manifest and candidate outputs") + _require_disjoint_paths([*paths.values(), *(item["materialized_path"] for item in inputs)]) + output_root = output_root_for(attempt["attempt_id"]) + _logical_path(output_root) + if not isinstance(required_capabilities, list) or not all( + _id(capability) for capability in required_capabilities + ): + raise ValueError("invalid generation capabilities") + plan = { + "spec": { + **attempt, "schema_version": 1, "generation_record_ref": None, + "prepared_ref": None, "protocol_digest": None, "operation": None, + "validation_scope": None, "candidate": None, "inputs": inputs, + "steps": steps, "output_root": output_root, + "required_capabilities": required_capabilities, + }, + "manifest": { + "schema_version": 1, "provider": provider, "output_contract": output_contract, + "context_refs": [delivery], "attempt_id": attempt["attempt_id"], + }, + } + encode(plan) + except (KeyError, TypeError, ValueError) as exc: + raise PublicError( + "InvalidExecutionSpec", stage="generation_plan", + message="The generation plan could not be bound to the supplied context and attempt.", + ) from exc + return deepcopy(plan) diff --git a/src/inferrsi/apps/handoff/context_provider.py b/src/inferrsi/apps/handoff/context_provider.py new file mode 100644 index 00000000..58fdc682 --- /dev/null +++ b/src/inferrsi/apps/handoff/context_provider.py @@ -0,0 +1,137 @@ +"""Project Knowledge selection into the in-process Harness delivery draft.""" + +import re +from dataclasses import dataclass +from hashlib import sha256 + +from inferrsi.contracts.json_v1 import MAX_SAFE_INTEGER +from inferrsi.knowledge.knowledge_operations import KnowledgeReader + +_REQUEST_FIELDS = {"query", "ids", "pins", "selection_limits", "max_bytes", "round_id"} +_TEXT_OPTIONS = {"kind", "repo", "tier", "backend", "scenario", "relevance", "relevance_method"} +_SIZE_OPTIONS = {"limit", "max_bytes"} +_ID = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:/@+-]{0,255}") + + +@dataclass(frozen=True) +class DeliveredContextDraft: + """The actual bytes and metadata for Harness to retain and seal.""" + + content: bytes + intended_location: str + sha256: str + items: list[dict] + selection: dict + omissions: list[dict] + limitations: list[str] + + +class ContextProvider: + """Deliver whole UTF-8 resources in Knowledge's selection order.""" + + def __init__(self, reader: KnowledgeReader): + self.reader = reader + + def collect(self, request: dict) -> DeliveredContextDraft: + if not isinstance(request, dict) or request.keys() != _REQUEST_FIELDS: + raise ValueError("expected ContextRequest fields") + query, ids, pins = request["query"], request["ids"], request["pins"] + limits, max_bytes, round_id = ( + request["selection_limits"], request["max_bytes"], request["round_id"] + ) + if query is not None and not isinstance(query, str): + raise ValueError("expected a string or null query") + if not isinstance(ids, list) or not all(_identifier(item) for item in ids): + raise ValueError("expected Knowledge ids") + if type(max_bytes) is not int or not 0 <= max_bytes <= MAX_SAFE_INTEGER: + raise ValueError("expected a delivery byte limit in the v1 unsigned integer range") + if not _identifier(round_id): + raise ValueError("expected a round_id") + if not isinstance(limits, dict) or not limits.keys() <= _TEXT_OPTIONS | _SIZE_OPTIONS: + raise ValueError("unsupported Knowledge selection option") + if any(not isinstance(limits[key], str) for key in limits.keys() & _TEXT_OPTIONS): + raise ValueError("invalid Knowledge selection option value") + if any( + type(limits[key]) is not int or not 1 <= limits[key] <= MAX_SAFE_INTEGER + for key in limits.keys() & _SIZE_OPTIONS + ): + raise ValueError("invalid Knowledge selection option value") + + result = self.reader.collect( + query or "", ids=ids or None, revisions=_revisions(pins), + context_bytes=max_bytes or None, **limits, + ) + selection = {**result.get("selection", {}), **result["retrieval"]["selection"]} + selection.update(no_match=result["no_match"], collisions=result["collisions"]) + omissions = [_omission(item, stage="knowledge_selection") for item in result["omissions"]] + limitations = list(result["limitations"]) + items, payloads = [], [] + if max_bytes == 0: + omissions.extend( + _omission({**item, "reason": "context_limit"}, stage="context_delivery") + for item in result["items"] + ) + for item in result.get("context_omissions", ()): + omissions.append(_omission(item, stage="context_delivery")) + for context in result.get("contexts", ()): + reference, revision = context["ref"], context["revision"] + parts, roles = [], [] + for resource in context["resources"]: + body = resource["content"].encode("utf-8") + if sha256(body).hexdigest() != resource["sha256"]: + raise ValueError("Knowledge context resource digest mismatch") + parts.append(body) + roles.append(resource["role"]) + block = b"".join(parts) + if len(block) != context["content_bytes"]: + raise ValueError("Knowledge context byte count mismatch") + payloads.append(block) + items.append({ + "pin": {"reference": reference, "revision": revision}, + "delivered_roles": list(dict.fromkeys(roles)), + "delivered_bytes": len(block), + }) + omissions.extend( + _omission({**item, "ref": reference}, stage="context_delivery") + for item in context["omissions"] + ) + limitations.extend(context["limitations"]) + content = b"".join(payloads) + if len(content) > max_bytes: + raise ValueError("Knowledge context exceeds the delivery byte limit") + # A round identifier can contain path separators or platform-specific names. + round_key = sha256(round_id.encode("ascii")).hexdigest() + return DeliveredContextDraft( + content=content, intended_location=f"context/{round_key}/delivered.bin", + sha256=sha256(content).hexdigest(), items=items, selection=selection, + omissions=omissions, limitations=list(dict.fromkeys(limitations)), + ) + + +def _identifier(value: object) -> bool: + return isinstance(value, str) and _ID.fullmatch(value) is not None + + +def _revisions(pins: object) -> dict[str, str]: + if not isinstance(pins, list): + raise ValueError("expected Knowledge pins") + revisions = {} + for pin in pins: + if ( + not isinstance(pin, dict) or pin.keys() != {"name", "revision"} + or not _identifier(pin["name"]) or not _identifier(pin["revision"]) + ): + raise ValueError("expected Knowledge pin name and revision") + name, revision = pin["name"], pin["revision"] + if revisions.setdefault(name, revision) != revision: + raise ValueError("conflicting Knowledge revisions") + return revisions + + +def _omission(item: dict, *, stage: str) -> dict: + reference = item.get("ref", item.get("id")) + location = "/".join(part for part in (reference, item.get("path")) if part) + return { + "code": item["reason"], "stage": stage, "message": f"{location}: {item['reason']}", + "retryable": False, + } diff --git a/src/inferrsi/apps/views/attempt.py b/src/inferrsi/apps/views/attempt.py index b39bedaa..8759b979 100644 --- a/src/inferrsi/apps/views/attempt.py +++ b/src/inferrsi/apps/views/attempt.py @@ -5,7 +5,7 @@ from inferrsi.contracts.json_v1 import decode from inferrsi.harness.errors import PublicError -from ..bridge import check_assessment_identity +from ..handoff.bridge import check_assessment_identity from ..storage.archive import read_assessment from ..storage.artifact_reader import ArtifactReader from ..storage.result import _check_ref diff --git a/tests/check_installed.py b/tests/check_installed.py index 66641673..04de8547 100644 --- a/tests/check_installed.py +++ b/tests/check_installed.py @@ -14,6 +14,7 @@ import inferrsi import inferrsi.harness +from inferrsi.apps.api import CandidateProvider, EvaluationPort from inferrsi.apps.cli import main from inferrsi.benchmark.registry import builtin_tasks, describe_task, task_resources from inferrsi.contracts import RunSpec, claim, evidence, json_v1 @@ -614,10 +615,15 @@ def _inventory(root, prefix): else: raise AssertionError("an unknown repository type must be refused") assert evidence.EVIDENCE_SEGMENTS == ("plan", "results", "patch", "validator") -# #490 storage: both installed import paths expose the same canonical objects. -for name in ("archive", "artifact_reader", "result", "evidence_layout"): +# #490: installed compatibility exports resolve to their canonical definitions. +for name, group in ( + ("archive", "storage"), ("artifact_reader", "storage"), + ("result", "storage"), ("evidence_layout", "storage"), + ("bridge", "handoff"), ("context_provider", "handoff"), + ("candidate_provider", "handoff"), +): old_name = f"inferrsi.apps.{name}" - canonical_name = f"inferrsi.apps.storage.{name}" + canonical_name = f"inferrsi.apps.{group}.{name}" old, canonical = import_module(old_name), import_module(canonical_name) assert find_spec(old_name) is not None and find_spec(canonical_name) is not None for exported in old.__all__: @@ -626,6 +632,11 @@ def _inventory(root, prefix): if getattr(value, "__module__", None) == canonical_name: assert pickle.loads(f"c{old_name}\n{exported}\n.".encode("ascii")) is value assert canonical_name.encode("ascii") in pickle.dumps(value, protocol=0) +assert CandidateProvider is ( + import_module("inferrsi.apps.handoff.candidate_provider").CandidateProvider +) +assert CandidateProvider is import_module("inferrsi.apps.candidate_provider").CandidateProvider +assert EvaluationPort.__module__ == "inferrsi.apps.api" for retired in ("_repo_pack_data", "evidence_paths"): assert find_spec(f"inferrsi.{retired}") is None, retired assert not installed_root & {"_repo_pack_data.py", "evidence_paths.py"} diff --git a/tests/test_apps_context_provider.py b/tests/test_apps_context_provider.py index 353a4781..b08e3aa0 100644 --- a/tests/test_apps_context_provider.py +++ b/tests/test_apps_context_provider.py @@ -5,7 +5,7 @@ import pytest -from inferrsi.apps.context_provider import ContextProvider +from inferrsi.apps.handoff.context_provider import ContextProvider from inferrsi.apps.knowledge import knowledge_reader _CGROUP = "package:inferrsi.common.skills.cgroup_resource_controls" diff --git a/tests/test_apps_evidence.py b/tests/test_apps_evidence.py index 2cacd13b..1c73a801 100644 --- a/tests/test_apps_evidence.py +++ b/tests/test_apps_evidence.py @@ -5,7 +5,7 @@ import pytest -from inferrsi.apps.bridge import to_evidence +from inferrsi.apps.handoff.bridge import to_evidence from inferrsi.contracts.json_v1 import decode, encode from inferrsi.harness.errors import PublicError diff --git a/tests/test_apps_execution_binding.py b/tests/test_apps_execution_binding.py index ead7165a..b987005b 100644 --- a/tests/test_apps_execution_binding.py +++ b/tests/test_apps_execution_binding.py @@ -7,7 +7,7 @@ import pytest from inferrsi.apps.api import execute -from inferrsi.apps.bridge import bind_execution, verify_protocol +from inferrsi.apps.handoff.bridge import bind_execution, verify_protocol from inferrsi.contracts.json_v1 import decode, encode from inferrsi.harness.errors import PublicError from inferrsi.harness.execution_spec import request_digest diff --git a/tests/test_apps_generation_plan.py b/tests/test_apps_generation_plan.py index 3d751982..33885144 100644 --- a/tests/test_apps_generation_plan.py +++ b/tests/test_apps_generation_plan.py @@ -8,7 +8,7 @@ import pytest from inferrsi.apps.api import CandidateProvider -from inferrsi.apps.bridge import bind_execution +from inferrsi.apps.handoff.bridge import bind_execution from inferrsi.apps.storage.artifact_reader import ArtifactReader from inferrsi.contracts.json_v1 import decode, encode from inferrsi.harness.api import Harness diff --git a/tests/test_apps_module_migrations.py b/tests/test_apps_module_migrations.py index e6a7a824..606297e0 100644 --- a/tests/test_apps_module_migrations.py +++ b/tests/test_apps_module_migrations.py @@ -109,7 +109,7 @@ def test_active_consumers_use_canonical_paths_and_are_registered(): def _is_handoff(name): - # The root implementations remain here until the next #490 slice. + # Include retained shims as well as the canonical handoff implementations. return name in { "inferrsi.apps.api", "inferrsi.apps.bridge", "inferrsi.apps.context_provider", "inferrsi.apps.candidate_provider", @@ -147,17 +147,20 @@ def test_storage_dependency_check_rejects_a_handoff_back_edge(tmp_path, indirect assert any("inferrsi.contracts.helper ->" in chain for _, chain in violations) -def test_storage_initializer_imports_nothing_and_module_bodies_do_no_io(): - tree = ast.parse((ROOT / "apps/storage/__init__.py").read_text(encoding="utf-8")) - assert len(tree.body) == 1 and ast.get_docstring(tree) - modules = ["inferrsi.apps.storage"] + [ +def test_migrated_initializers_import_nothing_and_module_bodies_do_no_io(): + packages = ["inferrsi.apps.storage", "inferrsi.apps.handoff"] + for package in packages: + path = REPO / "src" / package.replace(".", "/") / "__init__.py" + tree = ast.parse(path.read_text(encoding="utf-8")) + assert len(tree.body) == 1 and ast.get_docstring(tree) + modules = packages + [ entry[key] for entry in MIGRATIONS for key in ("old", "canonical") ] result = _fresh(IO_PROBE, json.dumps(modules), IO_CONTROL) seen = result["seen"] assert {"os.listdir", "open"} <= set(seen.pop("control")) assert seen == {name: [] for name in modules} - assert result["defined"]["inferrsi.apps.storage"] == [] + assert all(result["defined"][package] == [] for package in packages) def test_cold_storage_imports_do_not_load_handoff_or_probe_modules(): @@ -180,6 +183,67 @@ def find_spec(self, name, path=None, target=None): importlib.import_module(name) print(json.dumps({'parent_only': parent_only, 'warnings': [str(w.message) for w in caught]})) """ - modules = [entry[key] for entry in MIGRATIONS for key in ("old", "canonical")] + modules = [entry[key] for entry in MIGRATIONS if ".storage." in entry["canonical"] + for key in ("old", "canonical")] result = _fresh(script, json.dumps(modules)) assert result == {"parent_only": ["inferrsi.apps", "inferrsi.apps.storage"], "warnings": []} + + +def test_public_candidate_provider_is_the_one_canonical_class(): + from inferrsi.apps import api + from inferrsi.apps.handoff.candidate_provider import CandidateProvider + + old = import_module("inferrsi.apps.candidate_provider") + assert api.CandidateProvider is old.CandidateProvider is CandidateProvider + assert CandidateProvider.__module__ == "inferrsi.apps.handoff.candidate_provider" + assert api.EvaluationPort.__module__ == "inferrsi.apps.api" + + +def test_delivered_context_draft_loads_a_legacy_instance_pickle(): + from inferrsi.apps.handoff.context_provider import DeliveredContextDraft + + value = DeliveredContextDraft(b"context", "context/test/delivered.bin", "a" * 64, + [], {}, [], []) + data = pickle.dumps(value, protocol=0) + canonical = b"cinferrsi.apps.handoff.context_provider\nDeliveredContextDraft\n" + assert data.count(canonical) == 1 + legacy = data.replace(canonical, b"cinferrsi.apps.context_provider\nDeliveredContextDraft\n") + restored = pickle.loads(legacy) + assert type(restored) is DeliveredContextDraft and restored == value + + +def test_cold_handoff_imports_do_not_read_data_probe_or_launch_services(): + script = """ +import builtins, importlib, importlib.abc, io, json, socket, sqlite3, subprocess, sys, warnings +from unittest.mock import patch +blocked = ('inferrsi.apps.api', 'inferrsi.infra', 'inferrsi.benchmark', 'inferrsi.model', + 'inferrsi.harness.api', 'inferrsi.harness.run_store', 'inferrsi.harness.generation', + 'torch', 'numpy', 'PIL', 'vllm') +class Block(importlib.abc.MetaPathFinder): + def find_spec(self, name, path=None, target=None): + if any(name == item or name.startswith(item + '.') for item in blocked): + raise ImportError('unexpected import: ' + name) +sys.meta_path.insert(0, Block()) +def deny(*args, **kwargs): + raise AssertionError('unexpected data read, device probe, process or service') +with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter('always') + importlib.import_module('inferrsi.apps.handoff') + parent_only = sorted(name for name in sys.modules if name.startswith('inferrsi.apps')) + with patch.object(builtins, 'open', deny), patch.object(io, 'open', deny), \\ + patch.object(subprocess, 'Popen', deny), patch.object(sqlite3, 'connect', deny), \\ + patch.object(socket, 'socket', deny): + for name in json.loads(sys.argv[1]): + importlib.import_module(name) + try: + io.open('control') + except AssertionError: + control = True +print(json.dumps({'parent_only': parent_only, 'warnings': [str(w.message) for w in caught], + 'control': control})) +""" + modules = [entry[key] for entry in MIGRATIONS if ".handoff." in entry["canonical"] + for key in ("old", "canonical")] + result = _fresh(script, json.dumps(modules)) + assert result == {"parent_only": ["inferrsi.apps", "inferrsi.apps.handoff"], + "warnings": [], "control": True} diff --git a/tests/test_harness_generation_seal.py b/tests/test_harness_generation_seal.py index 751b8bc7..f1f9af0b 100644 --- a/tests/test_harness_generation_seal.py +++ b/tests/test_harness_generation_seal.py @@ -12,7 +12,7 @@ import pytest -from inferrsi.apps.context_provider import ContextProvider +from inferrsi.apps.handoff.context_provider import ContextProvider from inferrsi.apps.knowledge import knowledge_reader from inferrsi.contracts.json_v1 import decode, encode from inferrsi.harness import run_store