diff --git a/docs/apps-module-migrations.json b/docs/apps-module-migrations.json new file mode 100644 index 00000000..03028171 --- /dev/null +++ b/docs/apps-module-migrations.json @@ -0,0 +1,112 @@ +[ + { + "old": "inferrsi.apps.archive", + "canonical": "inferrsi.apps.storage.archive", + "exports": [ + "ResourceReader", + "RunOutput", + "archive_mount", + "archive_prepared", + "read_archive_artifact", + "read_prepared", + "archive_assessment", + "read_assessment", + "validate_output_id", + "read_result", + "publish_result" + ], + "consumers": [ + "docs/apps-output.md", + "docs/architecture.md", + "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/storage/artifact_reader.py", + "src/inferrsi/apps/views/attempt.py", + "tests/check_installed.py", + "tests/test_apps_assess.py", + "tests/test_apps_module_migrations.py", + "tests/test_apps_output.py", + "tests/test_apps_port_validation.py", + "tests/test_apps_prepare.py", + "tests/test_apps_publication.py", + "tests/test_apps_replay.py", + "tests/test_result_delivery.py" + ] + }, + { + "old": "inferrsi.apps.artifact_reader", + "canonical": "inferrsi.apps.storage.artifact_reader", + "exports": [ + "ArtifactReader", + "AssessmentArtifacts" + ], + "consumers": [ + "docs/apps-output.md", + "docs/architecture.md", + "docs/module-layout.md", + "docs/operations.md", + "src/inferrsi/apps/api.py", + "src/inferrsi/apps/candidate_provider.py", + "src/inferrsi/apps/views/attempt.py", + "tests/check_installed.py", + "tests/test_apps_artifact_reader.py", + "tests/test_apps_assess.py", + "tests/test_apps_generation_plan.py", + "tests/test_apps_module_migrations.py" + ] + }, + { + "old": "inferrsi.apps.result", + "canonical": "inferrsi.apps.storage.result", + "exports": [ + "is_public_error", + "execution_result", + "preparation_result", + "assessment_result", + "publication_error", + "validate_artifact_ref", + "validate_result" + ], + "consumers": [ + "docs/apps-output.md", + "docs/architecture.md", + "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/storage/archive.py", + "src/inferrsi/apps/storage/artifact_reader.py", + "src/inferrsi/apps/views/attempt.py", + "tests/check_installed.py", + "tests/test_apps_module_migrations.py", + "tests/test_result_delivery.py" + ] + }, + { + "old": "inferrsi.apps.evidence_layout", + "canonical": "inferrsi.apps.storage.evidence_layout", + "exports": [ + "ensure_evidence_layout" + ], + "consumers": [ + "docs/apps-output.md", + "docs/architecture.md", + "docs/contracts/current-design.md", + "docs/module-layout.md", + "docs/operations.md", + "src/inferrsi/contracts/evidence.py", + "tests/_gate_policy_support.py", + "tests/check_installed.py", + "tests/test_apps_module_migrations.py", + "tests/test_evidence_paths.py", + "tests/test_first_wave_isolation_policy.py", + "tests/test_repository_packs_facade.py" + ] + } +] diff --git a/docs/apps-output.md b/docs/apps-output.md index 61ef1ab5..3eef4cc7 100644 --- a/docs/apps-output.md +++ b/docs/apps-output.md @@ -109,7 +109,15 @@ error retains the committed PreparedRef. `read_prepared` verifies the fixed prepared bytes and identity using the same storage configuration. `read_archive_artifact` reads protocol or resource bytes from the archive mount and verifies the reference's size and digest. Both -functions are under `inferrsi.apps.archive`. +functions are under `inferrsi.apps.storage.archive`. + +Storage construction and validation live in `inferrsi.apps.storage.result`. +The former `inferrsi.apps.archive`, `artifact_reader`, `result` and +`evidence_layout` modules retain explicit public exports during the #490 +migration. New consumers and private-helper test patches use `apps.storage`. +The [migration inventory](apps-module-migrations.json) lists the exact exports. +Persisted namespace values, artifact references and schema versions retain +their existing spelling. ## Execute binding @@ -128,7 +136,7 @@ The bound spec is handed to the host-supplied Harness execution port. ## Fixed artifact reader -`inferrsi.apps.artifact_reader.ArtifactReader(storage_config)` implements +`inferrsi.apps.storage.artifact_reader.ArtifactReader(storage_config)` implements `open(ArtifactRef)` for hosts composing execution or offline assessment. Locations select one configured mount by its full prefix and slash boundary. Directory mounts verify the declared bytes and reject links or traversal. @@ -151,5 +159,5 @@ code after a confirmed archive commit. Archive failure returns exit code 6 and keeps the assessment in the result with a null `assessment_ref`. If the archive commit succeeds and output publication fails, the result retains the committed `assessment_ref`. -`inferrsi.apps.archive.read_assessment` resolves that fixed reference and checks +`inferrsi.apps.storage.archive.read_assessment` resolves that fixed reference and checks the archived bytes, version and identity for reports and other read-only consumers. diff --git a/docs/architecture.md b/docs/architecture.md index 4a14f040..cba3b66f 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -190,7 +190,11 @@ src/inferrsi/ __init__.py Import-free initializer repository_packs.py Neutral REPO_TYPES and pack.json reader; imports no inferrsi module apps/ - evidence_layout.py Create the plan/results/patch/validator evidence directories + storage/ + archive.py Immutable preparations/assessments and manifest.json/result.json + artifact_reader.py Read verified artifacts through authorized mounts + result.py AppsResultV1 construction and validation + evidence_layout.py Create plan/results/patch/validator evidence directories campaign.py Knowledge values connected to Harness campaign records mindie/ project.py Opt-in per-checkout grant, the worker launch and the recorded read diff --git a/docs/contracts/current-design.md b/docs/contracts/current-design.md index a9e2eccf..c49dc43f 100644 --- a/docs/contracts/current-design.md +++ b/docs/contracts/current-design.md @@ -34,7 +34,7 @@ Permitted shared technical leaves are only: - `inferrsi.contracts.evidence` — the existing evidence segment names and pure path rules; it reads and writes no filesystem state and is not re-exported by the package initializer; - `inferrsi.resources.repository_packs` — the neutral raw pack-data reader and the existing static data enumeration (D020), formerly root `inferrsi._repo_pack_data`. Its parent initializer `resources/__init__.py` imports nothing. Outside Knowledge it has one permanent importer, `inferrsi.infra.inspection`, which binds only `repository_pack`; that exact rule is not a compatibility pair. A1 (#408) removed the separate temporary entry for root `arguments.py`: the moved parser `inferrsi.apps.cli.arguments` reads the same `REPO_TYPES` object through `inferrsi.knowledge.catalog` and does not import the leaf. -The neutral leaf carries no target selection, task, scoring, scheduling, or public business DTO, and imports none of K/H/B/Apps. It still finds the Harness-owned `pack.json` through `files("inferrsi").joinpath("harness", "data", "repo_packs", ...)`, so reading it never imports Harness. Creating the evidence directories is host I/O and stays in Apps, in `inferrsi.apps.evidence_layout`; that module is not a shared leaf. The list is exact: a `contracts.` or `resources.` prefix admits no other module. +The neutral leaf carries no target selection, task, scoring, scheduling, or public business DTO, and imports none of K/H/B/Apps. It still finds the Harness-owned `pack.json` through `files("inferrsi").joinpath("harness", "data", "repo_packs", ...)`, so reading it never imports Harness. Creating the evidence directories is host I/O and stays in Apps, in `inferrsi.apps.storage.evidence_layout`; that module is not a shared leaf. The list is exact: a `contracts.` or `resources.` prefix admits no other module. Why: this matches the accepted A–D direction and removes the reverse dependency that a shared DTO package creates. Rejected: a shared business DTO package; Apps owning scoring/sampling/budget algorithms; creating empty packages to declare migration done. diff --git a/docs/module-layout.md b/docs/module-layout.md index bfd68633..2bc2eb57 100644 --- a/docs/module-layout.md +++ b/docs/module-layout.md @@ -11,12 +11,14 @@ package is dissolved. Its campaign records, traces, logs and profile captures are in `harness/records/`, its dashboard views and templates are in `apps/views/`, and the collected-context projection is in `knowledge/context_projection.py`. -#371 remains the proposal for the Apps package path and is not accepted here. +#371 owns the Apps composition. Its accepted directory follow-up +[#490](https://github.com/InferMatrixLab/InferRSI/issues/490) starts with the +`apps/storage/` slice described below. The old `run` chain is split by owner. Its gates are in `benchmark/legacy_run_v0.py`, its execution facts stay in `harness/`, and -`apps/legacy/` composes them with the report. `apps/legacy/` is the path named -by the confirmed split for this slice; that use does not accept #371. +`apps/legacy/` composes them with the report. That path was established by +the earlier confirmed split. `apps/cli/` imports the old run only inside its `run` command, so the other commands, including ordinary optimization, still load no Benchmark module. R1 deleted the three root forwarders of that chain (`evaluation.py`, @@ -24,6 +26,26 @@ R1 deleted the three root forwarders of that chain (`evaluation.py`, ## Target modules +### Apps storage migration + +`apps/storage/` owns `archive.py`, `artifact_reader.py`, `result.py` and +`evidence_layout.py`. API, handoff, view and delivery consumers import these +canonical implementations. Storage has no direct or transitive import back to +handoff. The package initializer imports nothing. + +The four old Apps paths remain explicit static exports of the same public +objects. [apps-module-migrations.json](apps-module-migrations.json) records the +implemented paths, exports and consumers. Private-helper imports and test +patches must target the canonical module. Old Apps pickle references load +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. + +### Core and technical packages + The four target modules are peers: `knowledge`, `harness`, `benchmark`, and `apps`. Knowledge, Harness, and Benchmark do not import one another. Apps is the only assembler. `src/inferrsi/contracts/__init__.py` re-exports only @@ -33,7 +55,7 @@ business DTOs and performs no core or host initialization. `contracts/evidence.py` holds the evidence segment names and the per-campaign path rules. It only builds paths and does no filesystem I/O. Creating the -directories is `apps/evidence_layout.py`, which reuses those rules, so `mkdir` +directories is `apps/storage/evidence_layout.py`, which reuses those rules, so `mkdir` stays out of the contracts package. `resources/repository_packs.py` is the neutral repository-pack facade: the one `REPO_TYPES` tuple and the `pack.json` reader. It imports no `inferrsi` module, and `resources/__init__.py` imports @@ -89,7 +111,7 @@ contract slice. Do not treat PR #338 as a reason to add a top-level `tests/architecture_closed_loop.py` is the handoff exercised by `tests/test_architecture_closed_loop.py`. The coordinator does not import Knowledge, Harness, or Benchmark. Refusal cases still inject outcomes. That -file is not the Apps package, and #371 remains the proposal for that path. +file is not the Apps implementation owned by #371. It does not change Bundle revision. `tests/architecture_real_ports.py` is the CPU/offline connection injected for @@ -119,18 +141,19 @@ Several flat modules remain shared seams until their slice starts. | `apps/skill_evaluation.py`, `apps/skill_eval_engineering.py`, `apps/improvement.py` | Composed skill-evaluation entries | Join Knowledge reads, Harness execution and Benchmark rules behind the signatures that `harness/` held before the split | | `knowledge/knowledge_operations.py`, `knowledge/knowledge_store.py`, `knowledge/catalog.py`, `knowledge/research.py`, `knowledge/skill_catalog.py`, `knowledge/_skill_selection.py`, `knowledge/_source_snapshot.py` | The seven Knowledge implementations, moved by K01 | Interfaces unchanged; the same-named root shells were deleted by R1 | | `harness/records/` | Campaign manifests, traces, logs, profile captures and delivered-context captures | Imports no Knowledge or Apps module; `apps/campaign.py` supplies the backend names, the selection default and the context projection | -| `apps/views/`, `apps/campaign.py` | Dashboard views, templates and the Knowledge-to-records connection | Apps path still follows the #371 proposal | +| `apps/views/`, `apps/campaign.py` | Dashboard views, templates and the Knowledge-to-records connection | Apps composition under #371; campaign organization follows in #490 | | `apps/mindie/` (`project.py`, `context.py`, `mcp.py`, `read_worker.py`) | The local MindIE adapter: project grant, stdio MCP, context export and the read worker | M1 (#452) moved the four root MindIE files here; no Harness, Knowledge or Infra module names MindIE, and the initializer imports nothing | | `harness/` | Mixed legacy tree, not target isolation | Not redefined | | `harness/runner.py`, `harness/scenarios/external.py`, `harness/atomic_json.py` | Old run execution facts and Harness-owned JSON writes | Ports injected; no Model edge, and no Infra edge except the local process executor | | `benchmark/legacy_run_v0.py`, `benchmark/sampling.py` | Old run gates and metric validation; image/video sample collection | Imports only `model/protocols/metrics`; owns its rule inputs and verdict labels | -| `apps/legacy/` | Old run composition, old `evaluate` entry and HTML report | Supplies the Git source snapshot from `infra/targets`; path follows the confirmed split, #371 still proposed | +| `apps/legacy/` | Old run composition, old `evaluate` entry and HTML report | Supplies the Git source snapshot from `infra/targets`; remains in Apps | | `apps/inspection.py` | Prepared-environment inspection bound to this host | Binds the `infra/inspection.py` facts API to `infra.commands.probe_command` and `infra.targets.repository_identity`; replaces root `inspection.py`, which R1 deleted with the three old-run root forwarders | | `model/validators/` | Benchmark-leaning checks | Not moved | | `infra/` | Seams used by the current tree, including the `infra/inspection.py` facts API | Not a fourth core; reaches no Knowledge, Harness, Benchmark or Apps module | | `apps/views/summary_chart.py` | Stdlib SVG gain chart and report figure spec | A2 (#408) moved root `summary_chart.py` here; the renderer, its specification checks and its `main` are unchanged, and `tools/campaign_summary_chart.py` calls it | | `contracts/` (`runspec.py`, `json_v1.py`, `claim.py`, `evidence.py`) | Technical-only contracts: RunSpec, canonical JSON, verdict vocabulary, evidence segment and path rules | Exact module set; the initializer re-exports only `RunSpec`; not a fourth core | -| `apps/evidence_layout.py` | Evidence directory creation over the `contracts/evidence.py` path rules | The `mkdir` half of former root `evidence_paths.py`; host I/O stays in Apps | +| `apps/storage/evidence_layout.py` | Evidence directory creation over the `contracts/evidence.py` path rules | The `mkdir` half of former root `evidence_paths.py`; host I/O stays in Apps | +| `apps/storage/` (`archive.py`, `artifact_reader.py`, `result.py`) | Fixed artifact publication and reads; normalized AppsResultV1 | #490 storage slice; the old Apps modules retain explicit public exports | | `resources/repository_packs.py` | Neutral `REPO_TYPES` and `repository_pack` facade | Former root `_repo_pack_data.py`, bytes unchanged; import-free initializer; not a fourth core | | `knowledge/data/`, `harness/data/` | Packaged resources, placed by owner since K02 | Corpus under Knowledge; pack descriptions under Harness | diff --git a/docs/operations.md b/docs/operations.md index 806b2602..9832c147 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -350,6 +350,14 @@ normal scoped PR path. ## Experiments +The public preparation, execution and assessment API remains +`inferrsi.apps.api`. Its fixed artifact access and output publication use +`inferrsi.apps.storage.archive`, `artifact_reader` and `result`; the directory +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. + ### Inspect/prepare — `doctor`, `plan`, `--dry-run` - **Inputs:** repository/backend/device flags; `plan` takes the full experiment specification. diff --git a/src/inferrsi/apps/api.py b/src/inferrsi/apps/api.py index 6b0661d3..a1575bbf 100644 --- a/src/inferrsi/apps/api.py +++ b/src/inferrsi/apps/api.py @@ -9,7 +9,10 @@ from inferrsi.harness.errors import PublicError from inferrsi.harness.execution_spec import request_digest -from .archive import ( +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 .storage.archive import ( ResourceReader, RunOutput, archive_assessment, @@ -20,11 +23,8 @@ read_prepared, validate_output_id, ) -from .artifact_reader import ArtifactReader, AssessmentArtifacts -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 .result import ( +from .storage.artifact_reader import ArtifactReader, AssessmentArtifacts +from .storage.result import ( assessment_result, execution_result, is_public_error, diff --git a/src/inferrsi/apps/archive.py b/src/inferrsi/apps/archive.py index 6ca423a4..8d8f1403 100644 --- a/src/inferrsi/apps/archive.py +++ b/src/inferrsi/apps/archive.py @@ -1,575 +1,29 @@ -"""Store fixed preparations and standardized Apps output in authorized directories.""" - -import ctypes -import errno -import os -import re -import sys -from collections.abc import Callable -from copy import deepcopy -from dataclasses import dataclass -from datetime import datetime, timezone -from hashlib import sha256 -from io import BytesIO -from pathlib import Path -from tempfile import TemporaryDirectory -from typing import BinaryIO -from uuid import uuid4 - -from inferrsi.contracts.json_v1 import decode, encode -from inferrsi.harness.errors import PublicError - -from .result import publication_error, validate_artifact_ref, validate_result - -_OUTPUT_ID = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}") -_RESERVED_NAMES = re.compile(r"CON|PRN|AUX|NUL|COM[0-9]|LPT[0-9]", re.IGNORECASE) -_PATH_CONTROL = re.compile(r'[\\:\x00-\x1f\x7f]') -_INVALID_FILE_PART = re.compile(r'[<>"|?*]') -_SEMANTIC_ID = re.compile(r"sha256:[0-9a-f]{64}") -_STORAGE_FIELDS = {"schema_version", "mounts", "archive_namespace", "harness_namespace"} -_MOUNT_FIELDS = {"prefix", "kind", "root", "namespace"} -ResourceReader = Callable[[str], bytes | BinaryIO] - - -@dataclass(frozen=True) -class RunOutput: - """The Apps result and the location of its publication, if successful.""" - - output_id: str - directory: Path | None - result: dict - - -def _logical_path(value: object) -> tuple[str, ...]: - if not isinstance(value, str) or _PATH_CONTROL.search(value): - raise ValueError("expected a canonical relative location") - parts = tuple(value.split("/")) - if any(part in ("", ".", "..") for part in parts): - raise ValueError("expected a canonical relative location") - return parts - - -def _storage_mounts(config: dict) -> dict[str, tuple[str, str, Path]]: - try: - if ( - not isinstance(config, dict) - or config.keys() != _STORAGE_FIELDS - or type(config["schema_version"]) is not int - or config["schema_version"] != 1 - or not isinstance(config["mounts"], list) - ): - raise ValueError - mounts = {} - prefixes = [] - for mount in config["mounts"]: - if not isinstance(mount, dict) or mount.keys() != _MOUNT_FIELDS: - raise ValueError - namespace = mount["namespace"] - if not isinstance(namespace, str) or not _OUTPUT_ID.fullmatch(namespace): - raise ValueError - if namespace in mounts or mount["kind"] not in ("directory", "harness_sqlite"): - raise ValueError - prefix = _logical_path(mount["prefix"]) - root_path = mount["root"] - if not isinstance(root_path, str) or "\0" in root_path: - raise ValueError - root = Path(root_path) - if not root.is_absolute() or root.anchor.startswith(("\\\\", "//")): - raise ValueError - if mount["kind"] == "harness_sqlite" and prefix[-1] != namespace: - raise ValueError - if any( - prefix[:len(other)] == other or other[:len(prefix)] == prefix for other in prefixes - ): - raise ValueError - prefixes.append(prefix) - mounts[namespace] = (mount["kind"], mount["prefix"], root) - if config["archive_namespace"] not in mounts or config["harness_namespace"] not in mounts: - raise ValueError - except (KeyError, TypeError, ValueError): - raise PublicError( - "InvalidRequest", stage="storage_config", message="Invalid Apps storage configuration." - ) from None - return mounts - - -def archive_mount(config: dict, *, for_write: bool = False) -> tuple[str, Path]: - """Select the trusted local archive mount and check write configuration.""" - mounts = _storage_mounts(config) - kind, prefix, root = mounts[config["archive_namespace"]] - if kind != "directory": - raise PublicError( - "InvalidRequest", stage="storage_config", message="The Apps archive needs a directory." - ) - if for_write: - try: - root = _directory(root) - except (OSError, PublicError): - raise PublicError( - "InvalidRequest", stage="storage_config", - message="The Apps archive root must be an existing authorized directory.", - ) from None - return prefix, root - - -def _prepared_identity(prepared: object) -> str: - if ( - not isinstance(prepared, dict) - or type(prepared.get("schema_version")) is not int - or prepared["schema_version"] != 1 - or not isinstance(prepared.get("prepared_id"), str) - or not _SEMANTIC_ID.fullmatch(prepared["prepared_id"]) - ): - raise ValueError("invalid prepared identity") - return prepared["prepared_id"] - - -def _prepared_error(code: str, message: str) -> PublicError: - return PublicError(code, stage="prepared_archive", message=message) - - -def _check_bytes(ref: dict, size: int, digest: str, *, stage: str = "prepared_archive") -> None: - if ref["size_bytes"] != size or ref["sha256"] != digest: - raise PublicError( - "ArtifactIntegrityError", stage=stage, message="Artifact bytes do not match." - ) - - -def _write_verified(path: Path, ref: dict, source: bytes | BinaryIO) -> None: - digest = sha256() - size = 0 - reader = BytesIO(source) if isinstance(source, bytes) else source - if not callable(getattr(reader, "read", None)): - raise ValueError("expected bytes or a binary resource stream") - with reader: - with path.open("xb") as target: - while True: - try: - chunk = reader.read(1024 * 1024) - except OSError: - raise _prepared_error( - "ArtifactUnavailable", "Could not read a resource." - ) from None - if not isinstance(chunk, bytes): - raise ValueError("expected a binary resource") - if not chunk: - break - size += len(chunk) - if size > ref["size_bytes"]: - raise _prepared_error( - "ArtifactIntegrityError", "Prepared artifact is oversized." - ) - digest.update(chunk) - target.write(chunk) - _check_bytes(ref, size, digest.hexdigest()) - target.flush() - os.fsync(target.fileno()) - - -def _directory(root: Path) -> Path: - try: - resolved = root.resolve(strict=True) - except RuntimeError: - raise _prepared_error("UnsafeArtifactPath", "Invalid Apps archive directory.") from None - if root != resolved or not resolved.is_dir(): - raise _prepared_error("UnsafeArtifactPath", "Invalid Apps archive directory.") - return resolved - - -def archive_prepared( - prepared: dict, - protocol: bytes, - read_resource: ResourceReader, - *, - mount: tuple[str, Path], - encode_prepared: Callable[[dict], bytes], - validate_prepared: Callable[[dict, bytes], None], -) -> dict: - """Commit a frozen preparation and its complete closure on the selected mount.""" - identity = _prepared_identity(prepared) - prefix, root = mount - directory = uuid4().hex - location = f"{prefix}/{directory}" - relocated = deepcopy(prepared) - protocol_ref = relocated["protocol"] - validate_artifact_ref(protocol_ref) - _logical_path(protocol_ref["location"]) - if not isinstance(protocol, bytes): - raise ValueError("expected canonical protocol bytes") - _check_bytes(protocol_ref, len(protocol), sha256(protocol).hexdigest()) - if not isinstance(decode(protocol), dict): - raise ValueError("expected a protocol object") - protocol_ref["location"] = f"{location}/protocol.json" - resources = relocated["resources"] - if not isinstance(resources, list) or any(not isinstance(item, dict) for item in resources): - raise ValueError("expected a role-keyed resource closure") - roles = [item["role"] for item in resources] - if any(not isinstance(role, str) or not role for role in roles) or roles != sorted(set(roles)): - raise ValueError("expected distinct resources sorted by role") - for index, resource in enumerate(resources): - validate_artifact_ref(resource["artifact"]) - _logical_path(resource["artifact"]["location"]) - resource["artifact"]["location"] = f"{location}/resource-{index}" - - expected = encode(relocated) - data = encode_prepared(relocated) - if not isinstance(data, bytes) or data != expected: - raise ValueError("Benchmark encoded a different prepared object") - frozen = decode(data) - validate_prepared(deepcopy(frozen), protocol) - ref = { - "prepared_id": identity, - "schema_version": 1, - "artifact": { - "location": f"{location}/prepared.json", - "sha256": sha256(data).hexdigest(), - "size_bytes": len(data), - "media_type": "application/json", - }, - } - - published = False - try: - root = _directory(root) - with TemporaryDirectory(prefix=".pending-", dir=root) as temporary: - staging = Path(temporary) - _write_file(staging / "prepared.json", data) - _write_file(staging / "protocol.json", protocol) - for index, resource in enumerate(frozen["resources"]): - try: - source = read_resource(resource["role"]) - except (KeyError, OSError): - source = None - if source is None: - raise _prepared_error("ArtifactUnavailable", "A prepared resource is missing.") - _write_verified(staging / f"resource-{index}", resource["artifact"], source) - _sync_directory(staging) - _publish_directory(staging, root / directory) - published = True - _sync_directory(root) - except OSError: - message = ( - "Could not confirm the durability of the prepared archive." - if published else "Could not commit the prepared closure." - ) - raise _prepared_error("ArchivePersistenceError", message) from None - return ref - - -def read_archive_artifact(storage_config: dict, ref: dict) -> bytes: - """Read and verify an artifact under the selected Apps archive mount.""" - prefix, root = archive_mount(storage_config) - return _read_directory_artifact(prefix, root, ref) - - -def _read_directory_artifact( - prefix: str, root: Path, ref: dict, *, stage: str = "prepared_archive", -) -> bytes: - try: - validate_artifact_ref(ref) - parts = _logical_path(ref["location"]) - mount_parts = _logical_path(prefix) - suffix = parts[len(mount_parts):] - if ( - parts[:len(mount_parts)] != mount_parts - or not suffix - or suffix[0].startswith(".pending-") - or any( - part.rstrip(" .") != part or _INVALID_FILE_PART.search(part) - or _RESERVED_NAMES.fullmatch(part.split(".")[0]) - for part in suffix - ) - ): - raise ValueError - data = _read_file(_directory(root).joinpath(*suffix)) - except (ValueError, RuntimeError, PublicError): - raise PublicError( - "UnsafeArtifactPath", stage=stage, message="Invalid directory artifact location." - ) from None - except OSError: - raise PublicError( - "ArtifactUnavailable", stage=stage, message="Could not read the directory artifact." - ) from None - _check_bytes(ref, len(data), sha256(data).hexdigest(), stage=stage) - return data - - -def read_prepared(storage_config: dict, ref: dict) -> dict: - """Read a fixed PreparedRef and verify its original bytes and identity.""" - try: - identity = _prepared_identity(ref) - if ref.keys() != {"prepared_id", "schema_version", "artifact"}: - raise ValueError - validate_artifact_ref(ref["artifact"]) - if ref["artifact"]["media_type"] != "application/json": - raise ValueError - except ValueError: - raise _prepared_error("InvalidRequest", "Invalid PreparedRef.") from None - data = read_archive_artifact(storage_config, ref["artifact"]) - try: - prepared = decode(data) - prepared_id = _prepared_identity(prepared) - except ValueError: - raise _prepared_error( - "ArtifactIntegrityError", "Invalid archived prepared bytes." - ) from None - if prepared_id != identity: - raise _prepared_error("IdentityMismatch", "PreparedRef identifies a different preparation.") - return prepared - - -def archive_assessment(identity: str, data: bytes, *, mount: tuple[str, Path]) -> dict: - """Commit canonical assessment bytes and return their fixed reference.""" - prefix, root = mount - directory = uuid4().hex - ref = { - "assessment_id": identity, - "schema_version": 1, - "artifact": { - "location": f"{prefix}/{directory}/assessment.json", - "sha256": sha256(data).hexdigest(), - "size_bytes": len(data), - "media_type": "application/json", - }, - } - published = False - try: - root = _directory(root) - with TemporaryDirectory(prefix=".pending-", dir=root) as temporary: - staging = Path(temporary) - _write_file(staging / "assessment.json", data) - _sync_directory(staging) - _publish_directory(staging, root / directory) - published = True - _sync_directory(root) - except (OSError, PublicError): - message = ( - "Could not confirm the durability of the assessment archive." - if published else "Could not commit the assessment." - ) - raise PublicError( - "ArchivePersistenceError", stage="assessment_archive", message=message - ) from None - return ref - - -def read_assessment(storage_config: dict, ref: dict) -> dict: - """Read one archived assessment for reporting or independent replay.""" - try: - if ( - not isinstance(ref, dict) - or ref.keys() != {"assessment_id", "schema_version", "artifact"} - ): - raise ValueError("invalid AssessmentRef fields") - validate_artifact_ref(ref["artifact"]) - if ( - type(ref["schema_version"]) is not int or ref["schema_version"] != 1 - or not isinstance(ref["assessment_id"], str) - or not _SEMANTIC_ID.fullmatch(ref["assessment_id"]) - or ref["artifact"]["media_type"] != "application/json" - ): - raise ValueError("invalid AssessmentRef metadata") - except ValueError: - raise PublicError( - "InvalidRequest", stage="assessment_archive", message="Invalid AssessmentRef." - ) from None - prefix, root = archive_mount(storage_config) - data = _read_directory_artifact(prefix, root, ref["artifact"], stage="assessment_archive") - try: - assessment = decode(data) - if not isinstance(assessment, dict): - raise ValueError("expected an archived assessment object") - except ValueError: - raise PublicError( - "ArtifactIntegrityError", stage="assessment_archive", - message="Invalid archived assessment bytes.", - ) from None - if ( - assessment.get("assessment_id") != ref["assessment_id"] - or type(assessment.get("schema_version")) is not int or assessment["schema_version"] != 1 - ): - raise PublicError( - "IdentityMismatch", stage="assessment_archive", - message="AssessmentRef identifies a different assessment.", - ) - return assessment - - -def validate_output_id(output_id: str) -> None: - if ( - not isinstance(output_id, str) - or not _OUTPUT_ID.fullmatch(output_id) - or output_id.endswith(".") - or _RESERVED_NAMES.fullmatch(output_id.split(".", 1)[0]) - ): - raise ValueError("output_id must be a portable directory name") - - -def _output_root(workspace: Path, *, create: bool) -> Path: - root = Path(workspace).resolve(strict=True) / "output" - if root.is_symlink() or root.resolve() != root: - raise OSError("invalid Apps output root") - if create: - root.mkdir(exist_ok=True) - return root - - -def _result_entry(data: bytes) -> dict: - return { - "path": "result.json", - "sha256": sha256(data).hexdigest(), - "size_bytes": len(data), - "media_type": "application/json", - } - - -def _manifest(output_id: str, created_at: str, result: dict, entry: dict) -> dict: - return { - "schema_version": 1, - "output_id": output_id, - "created_at": created_at, - "operation": result["operation"], - "run_id": result["execution"]["run_id"] if result["execution"] is not None else None, - "attempt_id": result["attempt_id"], - "result": entry, - } - - -def _read_file(path: Path) -> bytes: - if path.resolve(strict=True) != path or not path.is_file(): - raise ValueError("expected a regular Apps output file") - return path.read_bytes() - - -def _read_output(directory: Path, output_id: str) -> dict: - if directory.resolve(strict=True) != directory or not directory.is_dir(): - raise ValueError("expected an Apps output directory") - manifest_data = _read_file(directory / "manifest.json") - manifest = decode(manifest_data) - if not isinstance(manifest, dict) or type(manifest.get("schema_version")) is not int: - raise ValueError("invalid Apps output manifest") - if manifest["schema_version"] != 1: - raise ValueError("unsupported Apps output manifest version") - created_at = manifest.get("created_at") - if not isinstance(created_at, str) or not created_at.endswith("Z") or "T" not in created_at: - raise ValueError("invalid Apps output creation time") - datetime.fromisoformat(created_at[:-1] + "+00:00") - - entry = manifest.get("result") - if not isinstance(entry, dict) or entry.get("path") != "result.json": - raise ValueError("invalid Apps manifest result path") - data = _read_file(directory / "result.json") - expected_entry = _result_entry(data) - if entry != expected_entry: - raise ValueError("Apps output manifest does not match result.json bytes") - result = decode(data) - validate_result(result) - if manifest_data != encode(_manifest(output_id, created_at, result, expected_entry)): - raise ValueError("Apps output manifest does not match result.json") - return result - - -def read_result(workspace: Path, output_id: str) -> RunOutput: - """Read the named publication, checking its version, metadata and result bytes.""" - validate_output_id(output_id) - directory = _output_root(workspace, create=False) / output_id - return RunOutput(output_id, directory, _read_output(directory, output_id)) - - -def _write_file(path: Path, data: bytes) -> None: - with path.open("xb") as handle: - handle.write(data) - handle.flush() - os.fsync(handle.fileno()) - - -def _publish_directory(staging: Path, destination: Path) -> None: - """Atomically publish a complete directory without replacing any entry.""" - if os.name == "nt": - staging.rename(destination) - return - - libc = ctypes.CDLL(None, use_errno=True) - source = os.fsencode(staging) - target = os.fsencode(destination) - try: - if sys.platform == "linux": - at_fdcwd, rename_noreplace = -100, 1 - rename = libc.renameat2 - rename.argtypes = ( - ctypes.c_int, ctypes.c_char_p, ctypes.c_int, ctypes.c_char_p, ctypes.c_uint, - ) - status = rename(at_fdcwd, source, at_fdcwd, target, rename_noreplace) - elif sys.platform == "darwin": - rename_excl = 0x00000004 - rename = libc.renamex_np - rename.argtypes = (ctypes.c_char_p, ctypes.c_char_p, ctypes.c_uint) - status = rename(source, target, rename_excl) - else: - raise OSError(errno.ENOTSUP, "atomic no-replace directory rename is unavailable") - except AttributeError as exc: - raise OSError(errno.ENOTSUP, "atomic no-replace directory rename is unavailable") from exc - if status != 0: - error = ctypes.get_errno() - raise OSError(error, os.strerror(error)) - - -def _sync_directory(path: Path) -> None: - """Persist directory entries on POSIX; Windows has no portable equivalent.""" - if os.name == "nt": - return - fd = os.open(path, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)) - try: - os.fsync(fd) - finally: - os.close(fd) - - -def _publication_message(error: Exception, *, published: bool) -> str: - # Never expose local paths or arbitrary exception messages in shared output. - if published: - return ( - "Output directory was published, but durability confirmation failed. " - "Publication state is uncertain; inspect the existing output ID before retrying." - ) - code = getattr(error, "errno", None) - if code in (errno.EEXIST, errno.ENOTEMPTY) or getattr(error, "winerror", None) in (80, 183): - return "Output publication conflict: destination already exists and was not replaced." - if code in (errno.ENOTSUP, errno.EOPNOTSUPP, errno.ENOSYS, errno.EINVAL): - return ("Output publication unsupported: " - "atomic no-replace rename or directory sync unavailable.") - if isinstance(error, ValueError): - return "Output publication validation failed; no output was published." - return "Output publication I/O failed; no output was published." - - -def publish_result(workspace: Path, result: dict, *, output_id: str | None = None) -> RunOutput: - """Publish an AppsResultV1 after the underlying operation has returned.""" - if output_id is None: - output_id = uuid4().hex - validate_output_id(output_id) - validate_result(result) - data = encode(result) - created_at = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z") - manifest = encode(_manifest(output_id, created_at, result, _result_entry(data))) - - published = False - try: - root = _output_root(workspace, create=True) - _sync_directory(root.parent) - destination = root / output_id - with TemporaryDirectory(prefix=".pending-", dir=root) as temporary: - staging = Path(temporary) - _write_file(staging / "result.json", data) - _write_file(staging / "manifest.json", manifest) - verified_result = _read_output(staging, output_id) - _sync_directory(staging) - _sync_directory(root) - _publish_directory(staging, destination) - published = True - _sync_directory(root) - except (OSError, ValueError) as error: - failed = publication_error(result) - failed["error"]["message"] = _publication_message(error, published=published) - return RunOutput(output_id, None, failed) - return RunOutput(output_id, destination, verified_result) +"""Compatibility exports for :mod:`inferrsi.apps.storage.archive`.""" + +from .storage.archive import ( + ResourceReader, + RunOutput, + archive_assessment, + archive_mount, + archive_prepared, + publish_result, + read_archive_artifact, + read_assessment, + read_prepared, + read_result, + validate_output_id, +) + +__all__ = [ + "ResourceReader", + "RunOutput", + "archive_mount", + "archive_prepared", + "read_archive_artifact", + "read_prepared", + "archive_assessment", + "read_assessment", + "validate_output_id", + "read_result", + "publish_result", +] diff --git a/src/inferrsi/apps/artifact_reader.py b/src/inferrsi/apps/artifact_reader.py index e07ac63a..15e33a8f 100644 --- a/src/inferrsi/apps/artifact_reader.py +++ b/src/inferrsi/apps/artifact_reader.py @@ -1,93 +1,11 @@ -"""Route fixed artifact references through trusted local storage mounts.""" +"""Compatibility exports for :mod:`inferrsi.apps.storage.artifact_reader`.""" -from io import BytesIO +from .storage.artifact_reader import ( + ArtifactReader, + AssessmentArtifacts, +) -from inferrsi.contracts.json_v1 import encode -from inferrsi.harness.errors import PublicError - -from .archive import _logical_path, _read_directory_artifact, _storage_mounts -from .result import validate_artifact_ref - - -class ArtifactReader: - """Read exact artifact bytes from one matching mount, without write access.""" - - def __init__(self, storage_config: dict): - self._mounts = _storage_mounts(storage_config) - if any( - kind == "harness_sqlite" and prefix != f"stores/{namespace}" - for namespace, (kind, prefix, _) in self._mounts.items() - ): - raise PublicError( - "InvalidRequest", stage="storage_config", - message="A Harness SQLite mount must use its canonical stores prefix.", - ) - - def open(self, ref: dict) -> BytesIO: - """Return a stream of verified bytes for a fixed ArtifactRef.""" - try: - validate_artifact_ref(ref) - except ValueError: - raise PublicError( - "InvalidRequest", stage="open", message="Invalid ArtifactRef." - ) from None - - location = ref["location"] - try: - _logical_path(location) - except ValueError: - raise PublicError( - "UnsafeArtifactPath", stage="open", message="Invalid artifact location." - ) from None - - for namespace, (kind, prefix, root) in self._mounts.items(): - if location.startswith(prefix + "/"): - if kind == "directory": - return BytesIO(_read_directory_artifact(prefix, root, ref, stage="open")) - # Archive-only consumers never load the SQLite implementation. - from inferrsi.harness.run_store import RunStoreReader - - return RunStoreReader.from_mount({ - "prefix": prefix, "kind": kind, "root": str(root), "namespace": namespace, - }).open(ref) - raise PublicError( - "UnsafeArtifactPath", stage="open", message="No mount matches the artifact location." - ) - - -class AssessmentArtifacts: - """Limit an assessor to the frozen protocol and the selected revision's retained bytes.""" - - def __init__(self, reader: ArtifactReader, prepared: dict, record: dict): - self._reader = reader - refs = [prepared["protocol"], *(item["artifact"] for item in prepared["resources"])] - for field, key in (("artifacts", "artifact"), ("bound_inputs", "retained_ref")): - refs.extend( - item[key] for item in record[field] if item["attempt_id"] == record["attempt_id"] - ) - refs.extend( - item["artifact"] for step in record["steps"] for item in step["artifacts"] - if item["attempt_id"] == record["attempt_id"] - ) - refs.extend( - ref for check in record["checks"] if check["attempt_id"] == record["attempt_id"] - for ref in check["evidence_refs"] - ) - if record["target_binding"] is not None: - refs.extend(item["environment_identity"] - for item in record["target_binding"]["runtime_bindings_by_step"]) - self._refs = {encode(ref) for ref in refs if ref is not None} - - def open(self, ref: dict) -> BytesIO: - try: - validate_artifact_ref(ref) - except ValueError: - raise PublicError( - "InvalidRequest", stage="open", message="Invalid ArtifactRef." - ) from None - if encode(ref) not in self._refs: - raise PublicError( - "ArtifactUnavailable", stage="open", - message="The artifact is outside the fixed assessment inputs.", - ) - return self._reader.open(ref) +__all__ = [ + "ArtifactReader", + "AssessmentArtifacts", +] diff --git a/src/inferrsi/apps/bridge.py b/src/inferrsi/apps/bridge.py index dfa6b2eb..dac6048a 100644 --- a/src/inferrsi/apps/bridge.py +++ b/src/inferrsi/apps/bridge.py @@ -7,8 +7,8 @@ from inferrsi.contracts.json_v1 import decode, encode from inferrsi.harness.errors import PublicError -from .archive import _logical_path -from .result import validate_artifact_ref +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", diff --git a/src/inferrsi/apps/candidate_provider.py b/src/inferrsi/apps/candidate_provider.py index 6b45ff07..bf2b27c6 100644 --- a/src/inferrsi/apps/candidate_provider.py +++ b/src/inferrsi/apps/candidate_provider.py @@ -7,8 +7,6 @@ from inferrsi.contracts.json_v1 import decode, encode from inferrsi.harness.errors import PublicError -from .archive import _logical_path -from .artifact_reader import ArtifactReader from .bridge import ( _ATTEMPT_FIELDS, _CANDIDATE_FIELDS, @@ -19,7 +17,9 @@ _output_paths, _require_disjoint_paths, ) -from .result import _RECORD_OBSERVATIONS, _check_ref, validate_artifact_ref +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", diff --git a/src/inferrsi/apps/delivery/__init__.py b/src/inferrsi/apps/delivery/__init__.py index cc93f3d4..959492d1 100644 --- a/src/inferrsi/apps/delivery/__init__.py +++ b/src/inferrsi/apps/delivery/__init__.py @@ -10,7 +10,7 @@ from ... import __version__ from ...infra.artifacts import file_lock -from .. import archive +from ..storage import archive from . import adapters from .projection import iterative from .render import reports diff --git a/src/inferrsi/apps/delivery/adapters.py b/src/inferrsi/apps/delivery/adapters.py index 72c75d09..eb549df1 100644 --- a/src/inferrsi/apps/delivery/adapters.py +++ b/src/inferrsi/apps/delivery/adapters.py @@ -1,7 +1,7 @@ """Historical adapters keep their original scope and explicitly disclose mapping gaps.""" -from ..result import _selected_verdict -from ..result import validate_result as validate_apps_result +from ..storage.result import _selected_verdict +from ..storage.result import validate_result as validate_apps_result from .projection import assessment, metric from .schema import gap, timestamp diff --git a/src/inferrsi/apps/evidence_layout.py b/src/inferrsi/apps/evidence_layout.py index 8510920e..6b87961f 100644 --- a/src/inferrsi/apps/evidence_layout.py +++ b/src/inferrsi/apps/evidence_layout.py @@ -1,19 +1,9 @@ -"""Create the standard evidence directories for one campaign root. +"""Compatibility exports for :mod:`inferrsi.apps.storage.evidence_layout`.""" -This is the host I/O half of the evidence layout. The segment names and path rules -are ``inferrsi.contracts.evidence``, which never touches the filesystem. -""" +from .storage.evidence_layout import ( + ensure_evidence_layout, +) -from __future__ import annotations - -from pathlib import Path - -from inferrsi.contracts.evidence import evidence_subpaths - - -def ensure_evidence_layout(root: Path) -> dict[str, Path]: - """Create standard evidence subdirectories if missing (local/dev helper).""" - paths = evidence_subpaths(root) - for path in paths.values(): - path.mkdir(parents=True, exist_ok=True) - return paths +__all__ = [ + "ensure_evidence_layout", +] diff --git a/src/inferrsi/apps/result.py b/src/inferrsi/apps/result.py index 23b3eebb..1a01315b 100644 --- a/src/inferrsi/apps/result.py +++ b/src/inferrsi/apps/result.py @@ -1,398 +1,21 @@ -"""Assemble and check the AppsResultV1 output envelope.""" - -import re -from dataclasses import fields -from hashlib import sha256 - -from inferrsi.contracts.json_v1 import encode -from inferrsi.harness.errors import PUBLIC_ERROR_CODES, PartialExecutionFacts - -_EXIT_CODES = { - "success": 0, - "error": 2, - "not_started": 3, - "in_progress": 4, - "recovery_required": 5, - "persistence_error": 6, - "execution_failed": 7, - "fail": 8, - "inconclusive": 9, -} -_ERROR_OUTCOMES = { - "AttemptInProgress": "in_progress", - "RecoveryRequired": "recovery_required", - "ExecutionPersistenceError": "persistence_error", - "ArchivePersistenceError": "persistence_error", -} -_RESULT_FIELDS = { - "schema_version", "operation", "outcome", "reason_code", "exit_code", - "primary_scope", "primary_claim_id", "attempt_id", "admission", "execution", - "prepared_ref", "record_ref", "assessment_ref", "assessment", "error", -} -_ERROR_FIELDS = { - "code", "stage", "attempt_id", "started", "latest_record_ref", - "partial_record", "retained_refs", "field_errors", "message", -} -_PARTIAL_FIELDS = {field.name for field in fields(PartialExecutionFacts)} -_REF_FIELDS = { - "prepared_ref": ("prepared_id", "schema_version"), - "record_ref": ("attempt_id", "record_version"), - "assessment_ref": ("assessment_id", "schema_version"), -} -_SHA256 = re.compile(r"[0-9a-f]{64}") -_RECORD_OBSERVATIONS = {"record_ref", "observed_at", "controller_observation"} -_VERDICT_OUTCOMES = {"PASS": "success", "FAIL": "fail", "INCONCLUSIVE": "inconclusive"} - - -def is_public_error(value: object) -> bool: - return ( - isinstance(value, dict) - and value.keys() == _ERROR_FIELDS - and isinstance(value["code"], str) - and value["code"] in PUBLIC_ERROR_CODES - ) - - -def _execute_outcome(record: dict) -> str: - if record.get("phase") == "recovery_required": - return "recovery_required" - if record.get("phase") != "finished": - raise ValueError("expected a terminal Harness record") - process = record.get("process_outcome") - if process == "not_started": - return "not_started" - if process in ("timed_out", "cancelled", "execution_error"): - return "execution_failed" - if process == "exited" and type(record.get("exit_code")) is int: - return "success" if record["exit_code"] == 0 else "execution_failed" - raise ValueError("unsupported Harness process outcome") - - -def execution_result(*, record: dict | None = None, error: dict | None = None) -> dict: - """Project a committed Harness record or a PublicError into AppsResultV1.""" - if (record is None) == (error is None): - raise ValueError("expected one Harness record or PublicError") - facts = record if record is not None else {} - return { - **_operation_result( - "execute", error, _execute_outcome(record) if record is not None else "error" - ), - "attempt_id": facts.get("attempt_id"), - "admission": facts.get("budget_admission"), - "execution": record, - "prepared_ref": facts.get("prepared_ref"), - "record_ref": facts.get("record_ref"), - } - - -def preparation_result(*, prepared_ref: dict | None = None, error: dict | None = None) -> dict: - """Project a committed PreparedRef or a PublicError into AppsResultV1.""" - if (prepared_ref is None) == (error is None): - raise ValueError("expected one PreparedRef or PublicError") - return {**_operation_result("prepare", error, "success"), "prepared_ref": prepared_ref} - - -def assessment_result( - *, - primary: tuple[str, str] | None = None, - assessment: dict | None = None, - assessment_ref: dict | None = None, - error: dict | None = None, -) -> dict: - """Project the selected claim and fixed assessment into AppsResultV1.""" - verdict = _selected_verdict(assessment, primary) if assessment is not None else None - result = _operation_result("assess", error, _VERDICT_OUTCOMES.get(verdict, "error")) - if assessment is not None: - result.update({ - field: assessment[field] for field in ("attempt_id", "prepared_ref", "record_ref") - }) - if primary is not None: - result["primary_claim_id"], result["primary_scope"] = primary - return {**result, "assessment": assessment, "assessment_ref": assessment_ref} - - -def _operation_result(operation: str, error: dict | None, outcome: str) -> dict: - reason = error["code"] if error is not None else None - if reason is not None: - outcome = _ERROR_OUTCOMES.get(reason, "error") - return { - "schema_version": 1, - "operation": operation, - "outcome": outcome, - "reason_code": reason, - "exit_code": _EXIT_CODES[outcome], - "primary_scope": None, - "primary_claim_id": None, - "attempt_id": None, - "admission": None, - "execution": None, - "prepared_ref": None, - "record_ref": None, - "assessment_ref": None, - "assessment": None, - "error": error, - } - - -def publication_error(result: dict) -> dict: - """Report an output failure while keeping every confirmed underlying fact.""" - prior = result["error"] or {} - record = result["execution"] or {} - code = "ArchivePersistenceError" - return { - **result, - "outcome": "persistence_error", - "reason_code": code, - "exit_code": 6, - "error": { - "code": code, - "stage": "output_publication", - "attempt_id": result["attempt_id"] or prior.get("attempt_id"), - "started": record.get("started", prior.get("started")), - "latest_record_ref": result["record_ref"] or prior.get("latest_record_ref"), - "partial_record": prior.get("partial_record"), - "retained_refs": prior.get("retained_refs", []), - "field_errors": prior.get("field_errors", []), - "message": "Could not publish the Apps output files.", - }, - } - - -def validate_artifact_ref(artifact: object) -> None: - if ( - not isinstance(artifact, dict) - or artifact.keys() != {"location", "sha256", "size_bytes", "media_type"} - or not isinstance(artifact["location"], str) or not artifact["location"] - or not isinstance(artifact["sha256"], str) or not _SHA256.fullmatch(artifact["sha256"]) - or type(artifact["size_bytes"]) is not int or artifact["size_bytes"] < 0 - or not isinstance(artifact["media_type"], str) or not artifact["media_type"] - ): - raise ValueError("invalid Apps reference metadata") - - -def _check_ref(ref: object, id_field: str, version_field: str) -> None: - if not isinstance(ref, dict) or ref.keys() != {id_field, version_field, "artifact"}: - raise ValueError("invalid Apps reference fields") - identity, version = ref[id_field], ref[version_field] - if ( - not isinstance(identity, str) or not identity - or type(version) is not int or version < 1 - or (version_field == "schema_version" and version != 1) - ): - raise ValueError("invalid Apps reference metadata") - validate_artifact_ref(ref["artifact"]) - - -def _check_partial(partial: dict) -> None: - if not isinstance(partial, dict) or partial.keys() != _PARTIAL_FIELDS: - raise ValueError("invalid partial execution fields") - if any(not isinstance(partial[key], str) or not partial[key] - for key in ("request_id", "run_id", "attempt_id")): - raise ValueError("invalid partial execution identity") - digest, version = partial["request_digest"], partial["proposed_record_version"] - if (digest is not None and (not isinstance(digest, str) - or not re.fullmatch(r"sha256:[0-9a-f]{64}", digest))) or ( - version is not None and (type(version) is not int or version < 0) - ): - raise ValueError("invalid partial execution revision") - if partial["phase"] not in ( - None, "registered", "preparing", "running", "stopping", "finalizing", - "finished", "recovery_required", - ) or (partial["started"] is not None and type(partial["started"]) is not bool) or ( - type(partial["side_effect_unknown"]) is not bool - ): - raise ValueError("invalid partial execution state") - for key in ("steps", "checks", "artifacts", "usage", "errors"): - if not isinstance(partial[key], list) or any( - not isinstance(item, dict) for item in partial[key] - ): - raise ValueError("invalid partial execution observations") - for key in ("budget_admission", "resource_leases"): - if partial[key] is not None and not isinstance(partial[key], dict): - raise ValueError("invalid partial execution accounting") - - -def _check_error(error: dict, outcome: str) -> None: - if ( - not is_public_error(error) - or outcome != _ERROR_OUTCOMES.get(error["code"], "error") - or not isinstance(error["stage"], str) or not error["stage"] - or (error["attempt_id"] is not None and not isinstance(error["attempt_id"], str)) - or (error["started"] is not None and not isinstance(error["started"], bool)) - or not isinstance(error["message"], str) - or not isinstance(error["field_errors"], list) - or any(not isinstance(item, str) for item in error["field_errors"]) - or not isinstance(error["retained_refs"], list) - ): - raise ValueError("invalid Apps PublicError") - partial = error["partial_record"] - if partial is not None: - _check_partial(partial) - if error["latest_record_ref"] is not None: - _check_ref(error["latest_record_ref"], *_REF_FIELDS["record_ref"]) - for ref in error["retained_refs"]: - validate_artifact_ref(ref) - - -def _check_artifact_ref(ref: dict, payload: dict) -> None: - artifact = ref["artifact"] - data = encode(payload) - if artifact["sha256"] != sha256(data).hexdigest() or artifact["size_bytes"] != len(data): - raise ValueError("fixed reference does not match the archived bytes") - - -def _check_record(result: dict, record: dict) -> None: - ref = result["record_ref"] - if ( - not isinstance(record, dict) - or ref is None - or not _RECORD_OBSERVATIONS <= record.keys() - or record["record_ref"] != ref - or not isinstance(record.get("budget_admission"), dict) - or record["budget_admission"] != result["admission"] - or record.get("prepared_ref") != result["prepared_ref"] - or record.get("attempt_id") != result["attempt_id"] - or not isinstance(record.get("run_id"), str) - or not record["run_id"] - or result["attempt_id"] is None - or ref.get("attempt_id") != result["attempt_id"] - or type(record.get("record_version")) is not int - or record["record_version"] < 1 - or ref.get("record_version") != record["record_version"] - ): - raise ValueError("inconsistent Apps execution and record reference") - _check_artifact_ref( - ref, {field: value for field, value in record.items() if field not in _RECORD_OBSERVATIONS} - ) - - -def _check_assessment(result: dict, *, output_error: bool) -> None: - assessment, ref = result["assessment"], result["assessment_ref"] - if assessment is not None and ( - not isinstance(assessment, dict) - or any( - result[field] is None or assessment.get(field) != result[field] - for field in ("attempt_id", "prepared_ref", "record_ref") - ) - ): - raise ValueError("inconsistent Apps assessment") - error = result["error"] - if ref is None: - if error is None: - raise ValueError("expected an archived assessment") - return - if ( - (error is not None and not output_error) - or assessment is None - or not assessment.get("assessment_id") - or assessment.get("assessment_id") != ref.get("assessment_id") - or assessment.get("schema_version") != ref.get("schema_version") - ): - raise ValueError("inconsistent Apps assessment reference") - _check_artifact_ref(ref, assessment) - verdict = _selected_verdict( - assessment, (result["primary_claim_id"], result["primary_scope"]) - ) - if not output_error and _VERDICT_OUTCOMES[verdict] != result["outcome"]: - raise ValueError("Apps outcome must match the selected primary claim") - - -def _selected_verdict(assessment: dict, primary: tuple[str, str] | None) -> str: - if primary is None or any(value is None for value in primary): - raise ValueError("expected a selected primary claim") - claims = assessment.get("claims") - if not isinstance(claims, list): - raise ValueError("expected assessment claims") - verdicts = [ - claim.get("verdict") - for claim in claims - if isinstance(claim, dict) - and (claim.get("claim_id"), claim.get("validation_scope")) == primary - ] - if ( - len(verdicts) != 1 - or not isinstance(verdicts[0], str) - or verdicts[0] not in _VERDICT_OUTCOMES - ): - raise ValueError("Apps outcome must match the selected primary claim") - return verdicts[0] - - -def validate_result(result: object) -> None: - """Check the Apps envelope and its links to the core responses.""" - if not isinstance(result, dict) or result.keys() != _RESULT_FIELDS: - raise ValueError("invalid AppsResultV1 fields") - if type(result["schema_version"]) is not int or result["schema_version"] != 1: - raise ValueError("unsupported Apps result version") - operation = result["operation"] - if operation not in ("prepare", "execute", "assess"): - raise ValueError("invalid Apps operation") - outcome, exit_code = result["outcome"], result["exit_code"] - if ( - not isinstance(outcome, str) - or type(exit_code) is not int - or _EXIT_CODES.get(outcome) != exit_code - ): - raise ValueError("inconsistent Apps outcome and exit code") - error = result["error"] - if error is not None: - _check_error(error, outcome) - if result["reason_code"] != (error["code"] if error is not None else None): - raise ValueError("inconsistent Apps reason and error") - if error is None and outcome in ("error", "in_progress", "persistence_error"): - raise ValueError("expected a PublicError for the Apps outcome") - for field, (id_field, version_field) in _REF_FIELDS.items(): - if result[field] is not None: - _check_ref(result[field], id_field, version_field) - for field in ("primary_scope", "primary_claim_id", "attempt_id"): - if result[field] is not None and ( - not isinstance(result[field], str) or not result[field] - ): - raise ValueError("invalid Apps identifier") - - record = result["execution"] - if record is not None: - _check_record(result, record) - - output_error = ( - error is not None and error["code"] == "ArchivePersistenceError" - and error["stage"] == "output_publication" - ) - if operation == "assess": - _check_assessment(result, output_error=output_error) - return - - if any( - result[field] is not None - for field in ("assessment", "assessment_ref", "primary_scope", "primary_claim_id") - ): - raise ValueError("unexpected assessment fields for the Apps operation") - if operation == "prepare": - if error is not None and any( - error[key] is not None - for key in ("attempt_id", "started", "latest_record_ref", "partial_record") - ): - raise ValueError("unexpected execution facts in prepare error") - if any( - result[field] is not None - for field in ("execution", "record_ref", "attempt_id", "admission") - ): - raise ValueError("unexpected execution fields for prepare") - if ( - not output_error - and (result["prepared_ref"] is not None) != (error is None) - ): - raise ValueError("inconsistent prepare archive reference") - if error is None and outcome != "success": - raise ValueError("expected a successful prepare outcome") - elif record is None: - if ( - error is None - or any( - result[field] is not None - for field in ("record_ref", "prepared_ref", "attempt_id", "admission") - ) - ): - raise ValueError("execute result requires a committed record for execution facts") - elif not output_error and (error is not None or outcome != _execute_outcome(record)): - raise ValueError("Apps execute outcome must match the committed record") +"""Compatibility exports for :mod:`inferrsi.apps.storage.result`.""" + +from .storage.result import ( + assessment_result, + execution_result, + is_public_error, + preparation_result, + publication_error, + validate_artifact_ref, + validate_result, +) + +__all__ = [ + "is_public_error", + "execution_result", + "preparation_result", + "assessment_result", + "publication_error", + "validate_artifact_ref", + "validate_result", +] diff --git a/src/inferrsi/apps/storage/__init__.py b/src/inferrsi/apps/storage/__init__.py new file mode 100644 index 00000000..4ae6fa90 --- /dev/null +++ b/src/inferrsi/apps/storage/__init__.py @@ -0,0 +1 @@ +"""Fixed artifact storage, normalized results and evidence directory creation.""" diff --git a/src/inferrsi/apps/storage/archive.py b/src/inferrsi/apps/storage/archive.py new file mode 100644 index 00000000..6ca423a4 --- /dev/null +++ b/src/inferrsi/apps/storage/archive.py @@ -0,0 +1,575 @@ +"""Store fixed preparations and standardized Apps output in authorized directories.""" + +import ctypes +import errno +import os +import re +import sys +from collections.abc import Callable +from copy import deepcopy +from dataclasses import dataclass +from datetime import datetime, timezone +from hashlib import sha256 +from io import BytesIO +from pathlib import Path +from tempfile import TemporaryDirectory +from typing import BinaryIO +from uuid import uuid4 + +from inferrsi.contracts.json_v1 import decode, encode +from inferrsi.harness.errors import PublicError + +from .result import publication_error, validate_artifact_ref, validate_result + +_OUTPUT_ID = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}") +_RESERVED_NAMES = re.compile(r"CON|PRN|AUX|NUL|COM[0-9]|LPT[0-9]", re.IGNORECASE) +_PATH_CONTROL = re.compile(r'[\\:\x00-\x1f\x7f]') +_INVALID_FILE_PART = re.compile(r'[<>"|?*]') +_SEMANTIC_ID = re.compile(r"sha256:[0-9a-f]{64}") +_STORAGE_FIELDS = {"schema_version", "mounts", "archive_namespace", "harness_namespace"} +_MOUNT_FIELDS = {"prefix", "kind", "root", "namespace"} +ResourceReader = Callable[[str], bytes | BinaryIO] + + +@dataclass(frozen=True) +class RunOutput: + """The Apps result and the location of its publication, if successful.""" + + output_id: str + directory: Path | None + result: dict + + +def _logical_path(value: object) -> tuple[str, ...]: + if not isinstance(value, str) or _PATH_CONTROL.search(value): + raise ValueError("expected a canonical relative location") + parts = tuple(value.split("/")) + if any(part in ("", ".", "..") for part in parts): + raise ValueError("expected a canonical relative location") + return parts + + +def _storage_mounts(config: dict) -> dict[str, tuple[str, str, Path]]: + try: + if ( + not isinstance(config, dict) + or config.keys() != _STORAGE_FIELDS + or type(config["schema_version"]) is not int + or config["schema_version"] != 1 + or not isinstance(config["mounts"], list) + ): + raise ValueError + mounts = {} + prefixes = [] + for mount in config["mounts"]: + if not isinstance(mount, dict) or mount.keys() != _MOUNT_FIELDS: + raise ValueError + namespace = mount["namespace"] + if not isinstance(namespace, str) or not _OUTPUT_ID.fullmatch(namespace): + raise ValueError + if namespace in mounts or mount["kind"] not in ("directory", "harness_sqlite"): + raise ValueError + prefix = _logical_path(mount["prefix"]) + root_path = mount["root"] + if not isinstance(root_path, str) or "\0" in root_path: + raise ValueError + root = Path(root_path) + if not root.is_absolute() or root.anchor.startswith(("\\\\", "//")): + raise ValueError + if mount["kind"] == "harness_sqlite" and prefix[-1] != namespace: + raise ValueError + if any( + prefix[:len(other)] == other or other[:len(prefix)] == prefix for other in prefixes + ): + raise ValueError + prefixes.append(prefix) + mounts[namespace] = (mount["kind"], mount["prefix"], root) + if config["archive_namespace"] not in mounts or config["harness_namespace"] not in mounts: + raise ValueError + except (KeyError, TypeError, ValueError): + raise PublicError( + "InvalidRequest", stage="storage_config", message="Invalid Apps storage configuration." + ) from None + return mounts + + +def archive_mount(config: dict, *, for_write: bool = False) -> tuple[str, Path]: + """Select the trusted local archive mount and check write configuration.""" + mounts = _storage_mounts(config) + kind, prefix, root = mounts[config["archive_namespace"]] + if kind != "directory": + raise PublicError( + "InvalidRequest", stage="storage_config", message="The Apps archive needs a directory." + ) + if for_write: + try: + root = _directory(root) + except (OSError, PublicError): + raise PublicError( + "InvalidRequest", stage="storage_config", + message="The Apps archive root must be an existing authorized directory.", + ) from None + return prefix, root + + +def _prepared_identity(prepared: object) -> str: + if ( + not isinstance(prepared, dict) + or type(prepared.get("schema_version")) is not int + or prepared["schema_version"] != 1 + or not isinstance(prepared.get("prepared_id"), str) + or not _SEMANTIC_ID.fullmatch(prepared["prepared_id"]) + ): + raise ValueError("invalid prepared identity") + return prepared["prepared_id"] + + +def _prepared_error(code: str, message: str) -> PublicError: + return PublicError(code, stage="prepared_archive", message=message) + + +def _check_bytes(ref: dict, size: int, digest: str, *, stage: str = "prepared_archive") -> None: + if ref["size_bytes"] != size or ref["sha256"] != digest: + raise PublicError( + "ArtifactIntegrityError", stage=stage, message="Artifact bytes do not match." + ) + + +def _write_verified(path: Path, ref: dict, source: bytes | BinaryIO) -> None: + digest = sha256() + size = 0 + reader = BytesIO(source) if isinstance(source, bytes) else source + if not callable(getattr(reader, "read", None)): + raise ValueError("expected bytes or a binary resource stream") + with reader: + with path.open("xb") as target: + while True: + try: + chunk = reader.read(1024 * 1024) + except OSError: + raise _prepared_error( + "ArtifactUnavailable", "Could not read a resource." + ) from None + if not isinstance(chunk, bytes): + raise ValueError("expected a binary resource") + if not chunk: + break + size += len(chunk) + if size > ref["size_bytes"]: + raise _prepared_error( + "ArtifactIntegrityError", "Prepared artifact is oversized." + ) + digest.update(chunk) + target.write(chunk) + _check_bytes(ref, size, digest.hexdigest()) + target.flush() + os.fsync(target.fileno()) + + +def _directory(root: Path) -> Path: + try: + resolved = root.resolve(strict=True) + except RuntimeError: + raise _prepared_error("UnsafeArtifactPath", "Invalid Apps archive directory.") from None + if root != resolved or not resolved.is_dir(): + raise _prepared_error("UnsafeArtifactPath", "Invalid Apps archive directory.") + return resolved + + +def archive_prepared( + prepared: dict, + protocol: bytes, + read_resource: ResourceReader, + *, + mount: tuple[str, Path], + encode_prepared: Callable[[dict], bytes], + validate_prepared: Callable[[dict, bytes], None], +) -> dict: + """Commit a frozen preparation and its complete closure on the selected mount.""" + identity = _prepared_identity(prepared) + prefix, root = mount + directory = uuid4().hex + location = f"{prefix}/{directory}" + relocated = deepcopy(prepared) + protocol_ref = relocated["protocol"] + validate_artifact_ref(protocol_ref) + _logical_path(protocol_ref["location"]) + if not isinstance(protocol, bytes): + raise ValueError("expected canonical protocol bytes") + _check_bytes(protocol_ref, len(protocol), sha256(protocol).hexdigest()) + if not isinstance(decode(protocol), dict): + raise ValueError("expected a protocol object") + protocol_ref["location"] = f"{location}/protocol.json" + resources = relocated["resources"] + if not isinstance(resources, list) or any(not isinstance(item, dict) for item in resources): + raise ValueError("expected a role-keyed resource closure") + roles = [item["role"] for item in resources] + if any(not isinstance(role, str) or not role for role in roles) or roles != sorted(set(roles)): + raise ValueError("expected distinct resources sorted by role") + for index, resource in enumerate(resources): + validate_artifact_ref(resource["artifact"]) + _logical_path(resource["artifact"]["location"]) + resource["artifact"]["location"] = f"{location}/resource-{index}" + + expected = encode(relocated) + data = encode_prepared(relocated) + if not isinstance(data, bytes) or data != expected: + raise ValueError("Benchmark encoded a different prepared object") + frozen = decode(data) + validate_prepared(deepcopy(frozen), protocol) + ref = { + "prepared_id": identity, + "schema_version": 1, + "artifact": { + "location": f"{location}/prepared.json", + "sha256": sha256(data).hexdigest(), + "size_bytes": len(data), + "media_type": "application/json", + }, + } + + published = False + try: + root = _directory(root) + with TemporaryDirectory(prefix=".pending-", dir=root) as temporary: + staging = Path(temporary) + _write_file(staging / "prepared.json", data) + _write_file(staging / "protocol.json", protocol) + for index, resource in enumerate(frozen["resources"]): + try: + source = read_resource(resource["role"]) + except (KeyError, OSError): + source = None + if source is None: + raise _prepared_error("ArtifactUnavailable", "A prepared resource is missing.") + _write_verified(staging / f"resource-{index}", resource["artifact"], source) + _sync_directory(staging) + _publish_directory(staging, root / directory) + published = True + _sync_directory(root) + except OSError: + message = ( + "Could not confirm the durability of the prepared archive." + if published else "Could not commit the prepared closure." + ) + raise _prepared_error("ArchivePersistenceError", message) from None + return ref + + +def read_archive_artifact(storage_config: dict, ref: dict) -> bytes: + """Read and verify an artifact under the selected Apps archive mount.""" + prefix, root = archive_mount(storage_config) + return _read_directory_artifact(prefix, root, ref) + + +def _read_directory_artifact( + prefix: str, root: Path, ref: dict, *, stage: str = "prepared_archive", +) -> bytes: + try: + validate_artifact_ref(ref) + parts = _logical_path(ref["location"]) + mount_parts = _logical_path(prefix) + suffix = parts[len(mount_parts):] + if ( + parts[:len(mount_parts)] != mount_parts + or not suffix + or suffix[0].startswith(".pending-") + or any( + part.rstrip(" .") != part or _INVALID_FILE_PART.search(part) + or _RESERVED_NAMES.fullmatch(part.split(".")[0]) + for part in suffix + ) + ): + raise ValueError + data = _read_file(_directory(root).joinpath(*suffix)) + except (ValueError, RuntimeError, PublicError): + raise PublicError( + "UnsafeArtifactPath", stage=stage, message="Invalid directory artifact location." + ) from None + except OSError: + raise PublicError( + "ArtifactUnavailable", stage=stage, message="Could not read the directory artifact." + ) from None + _check_bytes(ref, len(data), sha256(data).hexdigest(), stage=stage) + return data + + +def read_prepared(storage_config: dict, ref: dict) -> dict: + """Read a fixed PreparedRef and verify its original bytes and identity.""" + try: + identity = _prepared_identity(ref) + if ref.keys() != {"prepared_id", "schema_version", "artifact"}: + raise ValueError + validate_artifact_ref(ref["artifact"]) + if ref["artifact"]["media_type"] != "application/json": + raise ValueError + except ValueError: + raise _prepared_error("InvalidRequest", "Invalid PreparedRef.") from None + data = read_archive_artifact(storage_config, ref["artifact"]) + try: + prepared = decode(data) + prepared_id = _prepared_identity(prepared) + except ValueError: + raise _prepared_error( + "ArtifactIntegrityError", "Invalid archived prepared bytes." + ) from None + if prepared_id != identity: + raise _prepared_error("IdentityMismatch", "PreparedRef identifies a different preparation.") + return prepared + + +def archive_assessment(identity: str, data: bytes, *, mount: tuple[str, Path]) -> dict: + """Commit canonical assessment bytes and return their fixed reference.""" + prefix, root = mount + directory = uuid4().hex + ref = { + "assessment_id": identity, + "schema_version": 1, + "artifact": { + "location": f"{prefix}/{directory}/assessment.json", + "sha256": sha256(data).hexdigest(), + "size_bytes": len(data), + "media_type": "application/json", + }, + } + published = False + try: + root = _directory(root) + with TemporaryDirectory(prefix=".pending-", dir=root) as temporary: + staging = Path(temporary) + _write_file(staging / "assessment.json", data) + _sync_directory(staging) + _publish_directory(staging, root / directory) + published = True + _sync_directory(root) + except (OSError, PublicError): + message = ( + "Could not confirm the durability of the assessment archive." + if published else "Could not commit the assessment." + ) + raise PublicError( + "ArchivePersistenceError", stage="assessment_archive", message=message + ) from None + return ref + + +def read_assessment(storage_config: dict, ref: dict) -> dict: + """Read one archived assessment for reporting or independent replay.""" + try: + if ( + not isinstance(ref, dict) + or ref.keys() != {"assessment_id", "schema_version", "artifact"} + ): + raise ValueError("invalid AssessmentRef fields") + validate_artifact_ref(ref["artifact"]) + if ( + type(ref["schema_version"]) is not int or ref["schema_version"] != 1 + or not isinstance(ref["assessment_id"], str) + or not _SEMANTIC_ID.fullmatch(ref["assessment_id"]) + or ref["artifact"]["media_type"] != "application/json" + ): + raise ValueError("invalid AssessmentRef metadata") + except ValueError: + raise PublicError( + "InvalidRequest", stage="assessment_archive", message="Invalid AssessmentRef." + ) from None + prefix, root = archive_mount(storage_config) + data = _read_directory_artifact(prefix, root, ref["artifact"], stage="assessment_archive") + try: + assessment = decode(data) + if not isinstance(assessment, dict): + raise ValueError("expected an archived assessment object") + except ValueError: + raise PublicError( + "ArtifactIntegrityError", stage="assessment_archive", + message="Invalid archived assessment bytes.", + ) from None + if ( + assessment.get("assessment_id") != ref["assessment_id"] + or type(assessment.get("schema_version")) is not int or assessment["schema_version"] != 1 + ): + raise PublicError( + "IdentityMismatch", stage="assessment_archive", + message="AssessmentRef identifies a different assessment.", + ) + return assessment + + +def validate_output_id(output_id: str) -> None: + if ( + not isinstance(output_id, str) + or not _OUTPUT_ID.fullmatch(output_id) + or output_id.endswith(".") + or _RESERVED_NAMES.fullmatch(output_id.split(".", 1)[0]) + ): + raise ValueError("output_id must be a portable directory name") + + +def _output_root(workspace: Path, *, create: bool) -> Path: + root = Path(workspace).resolve(strict=True) / "output" + if root.is_symlink() or root.resolve() != root: + raise OSError("invalid Apps output root") + if create: + root.mkdir(exist_ok=True) + return root + + +def _result_entry(data: bytes) -> dict: + return { + "path": "result.json", + "sha256": sha256(data).hexdigest(), + "size_bytes": len(data), + "media_type": "application/json", + } + + +def _manifest(output_id: str, created_at: str, result: dict, entry: dict) -> dict: + return { + "schema_version": 1, + "output_id": output_id, + "created_at": created_at, + "operation": result["operation"], + "run_id": result["execution"]["run_id"] if result["execution"] is not None else None, + "attempt_id": result["attempt_id"], + "result": entry, + } + + +def _read_file(path: Path) -> bytes: + if path.resolve(strict=True) != path or not path.is_file(): + raise ValueError("expected a regular Apps output file") + return path.read_bytes() + + +def _read_output(directory: Path, output_id: str) -> dict: + if directory.resolve(strict=True) != directory or not directory.is_dir(): + raise ValueError("expected an Apps output directory") + manifest_data = _read_file(directory / "manifest.json") + manifest = decode(manifest_data) + if not isinstance(manifest, dict) or type(manifest.get("schema_version")) is not int: + raise ValueError("invalid Apps output manifest") + if manifest["schema_version"] != 1: + raise ValueError("unsupported Apps output manifest version") + created_at = manifest.get("created_at") + if not isinstance(created_at, str) or not created_at.endswith("Z") or "T" not in created_at: + raise ValueError("invalid Apps output creation time") + datetime.fromisoformat(created_at[:-1] + "+00:00") + + entry = manifest.get("result") + if not isinstance(entry, dict) or entry.get("path") != "result.json": + raise ValueError("invalid Apps manifest result path") + data = _read_file(directory / "result.json") + expected_entry = _result_entry(data) + if entry != expected_entry: + raise ValueError("Apps output manifest does not match result.json bytes") + result = decode(data) + validate_result(result) + if manifest_data != encode(_manifest(output_id, created_at, result, expected_entry)): + raise ValueError("Apps output manifest does not match result.json") + return result + + +def read_result(workspace: Path, output_id: str) -> RunOutput: + """Read the named publication, checking its version, metadata and result bytes.""" + validate_output_id(output_id) + directory = _output_root(workspace, create=False) / output_id + return RunOutput(output_id, directory, _read_output(directory, output_id)) + + +def _write_file(path: Path, data: bytes) -> None: + with path.open("xb") as handle: + handle.write(data) + handle.flush() + os.fsync(handle.fileno()) + + +def _publish_directory(staging: Path, destination: Path) -> None: + """Atomically publish a complete directory without replacing any entry.""" + if os.name == "nt": + staging.rename(destination) + return + + libc = ctypes.CDLL(None, use_errno=True) + source = os.fsencode(staging) + target = os.fsencode(destination) + try: + if sys.platform == "linux": + at_fdcwd, rename_noreplace = -100, 1 + rename = libc.renameat2 + rename.argtypes = ( + ctypes.c_int, ctypes.c_char_p, ctypes.c_int, ctypes.c_char_p, ctypes.c_uint, + ) + status = rename(at_fdcwd, source, at_fdcwd, target, rename_noreplace) + elif sys.platform == "darwin": + rename_excl = 0x00000004 + rename = libc.renamex_np + rename.argtypes = (ctypes.c_char_p, ctypes.c_char_p, ctypes.c_uint) + status = rename(source, target, rename_excl) + else: + raise OSError(errno.ENOTSUP, "atomic no-replace directory rename is unavailable") + except AttributeError as exc: + raise OSError(errno.ENOTSUP, "atomic no-replace directory rename is unavailable") from exc + if status != 0: + error = ctypes.get_errno() + raise OSError(error, os.strerror(error)) + + +def _sync_directory(path: Path) -> None: + """Persist directory entries on POSIX; Windows has no portable equivalent.""" + if os.name == "nt": + return + fd = os.open(path, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)) + try: + os.fsync(fd) + finally: + os.close(fd) + + +def _publication_message(error: Exception, *, published: bool) -> str: + # Never expose local paths or arbitrary exception messages in shared output. + if published: + return ( + "Output directory was published, but durability confirmation failed. " + "Publication state is uncertain; inspect the existing output ID before retrying." + ) + code = getattr(error, "errno", None) + if code in (errno.EEXIST, errno.ENOTEMPTY) or getattr(error, "winerror", None) in (80, 183): + return "Output publication conflict: destination already exists and was not replaced." + if code in (errno.ENOTSUP, errno.EOPNOTSUPP, errno.ENOSYS, errno.EINVAL): + return ("Output publication unsupported: " + "atomic no-replace rename or directory sync unavailable.") + if isinstance(error, ValueError): + return "Output publication validation failed; no output was published." + return "Output publication I/O failed; no output was published." + + +def publish_result(workspace: Path, result: dict, *, output_id: str | None = None) -> RunOutput: + """Publish an AppsResultV1 after the underlying operation has returned.""" + if output_id is None: + output_id = uuid4().hex + validate_output_id(output_id) + validate_result(result) + data = encode(result) + created_at = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z") + manifest = encode(_manifest(output_id, created_at, result, _result_entry(data))) + + published = False + try: + root = _output_root(workspace, create=True) + _sync_directory(root.parent) + destination = root / output_id + with TemporaryDirectory(prefix=".pending-", dir=root) as temporary: + staging = Path(temporary) + _write_file(staging / "result.json", data) + _write_file(staging / "manifest.json", manifest) + verified_result = _read_output(staging, output_id) + _sync_directory(staging) + _sync_directory(root) + _publish_directory(staging, destination) + published = True + _sync_directory(root) + except (OSError, ValueError) as error: + failed = publication_error(result) + failed["error"]["message"] = _publication_message(error, published=published) + return RunOutput(output_id, None, failed) + return RunOutput(output_id, destination, verified_result) diff --git a/src/inferrsi/apps/storage/artifact_reader.py b/src/inferrsi/apps/storage/artifact_reader.py new file mode 100644 index 00000000..e07ac63a --- /dev/null +++ b/src/inferrsi/apps/storage/artifact_reader.py @@ -0,0 +1,93 @@ +"""Route fixed artifact references through trusted local storage mounts.""" + +from io import BytesIO + +from inferrsi.contracts.json_v1 import encode +from inferrsi.harness.errors import PublicError + +from .archive import _logical_path, _read_directory_artifact, _storage_mounts +from .result import validate_artifact_ref + + +class ArtifactReader: + """Read exact artifact bytes from one matching mount, without write access.""" + + def __init__(self, storage_config: dict): + self._mounts = _storage_mounts(storage_config) + if any( + kind == "harness_sqlite" and prefix != f"stores/{namespace}" + for namespace, (kind, prefix, _) in self._mounts.items() + ): + raise PublicError( + "InvalidRequest", stage="storage_config", + message="A Harness SQLite mount must use its canonical stores prefix.", + ) + + def open(self, ref: dict) -> BytesIO: + """Return a stream of verified bytes for a fixed ArtifactRef.""" + try: + validate_artifact_ref(ref) + except ValueError: + raise PublicError( + "InvalidRequest", stage="open", message="Invalid ArtifactRef." + ) from None + + location = ref["location"] + try: + _logical_path(location) + except ValueError: + raise PublicError( + "UnsafeArtifactPath", stage="open", message="Invalid artifact location." + ) from None + + for namespace, (kind, prefix, root) in self._mounts.items(): + if location.startswith(prefix + "/"): + if kind == "directory": + return BytesIO(_read_directory_artifact(prefix, root, ref, stage="open")) + # Archive-only consumers never load the SQLite implementation. + from inferrsi.harness.run_store import RunStoreReader + + return RunStoreReader.from_mount({ + "prefix": prefix, "kind": kind, "root": str(root), "namespace": namespace, + }).open(ref) + raise PublicError( + "UnsafeArtifactPath", stage="open", message="No mount matches the artifact location." + ) + + +class AssessmentArtifacts: + """Limit an assessor to the frozen protocol and the selected revision's retained bytes.""" + + def __init__(self, reader: ArtifactReader, prepared: dict, record: dict): + self._reader = reader + refs = [prepared["protocol"], *(item["artifact"] for item in prepared["resources"])] + for field, key in (("artifacts", "artifact"), ("bound_inputs", "retained_ref")): + refs.extend( + item[key] for item in record[field] if item["attempt_id"] == record["attempt_id"] + ) + refs.extend( + item["artifact"] for step in record["steps"] for item in step["artifacts"] + if item["attempt_id"] == record["attempt_id"] + ) + refs.extend( + ref for check in record["checks"] if check["attempt_id"] == record["attempt_id"] + for ref in check["evidence_refs"] + ) + if record["target_binding"] is not None: + refs.extend(item["environment_identity"] + for item in record["target_binding"]["runtime_bindings_by_step"]) + self._refs = {encode(ref) for ref in refs if ref is not None} + + def open(self, ref: dict) -> BytesIO: + try: + validate_artifact_ref(ref) + except ValueError: + raise PublicError( + "InvalidRequest", stage="open", message="Invalid ArtifactRef." + ) from None + if encode(ref) not in self._refs: + raise PublicError( + "ArtifactUnavailable", stage="open", + message="The artifact is outside the fixed assessment inputs.", + ) + return self._reader.open(ref) diff --git a/src/inferrsi/apps/storage/evidence_layout.py b/src/inferrsi/apps/storage/evidence_layout.py new file mode 100644 index 00000000..8510920e --- /dev/null +++ b/src/inferrsi/apps/storage/evidence_layout.py @@ -0,0 +1,19 @@ +"""Create the standard evidence directories for one campaign root. + +This is the host I/O half of the evidence layout. The segment names and path rules +are ``inferrsi.contracts.evidence``, which never touches the filesystem. +""" + +from __future__ import annotations + +from pathlib import Path + +from inferrsi.contracts.evidence import evidence_subpaths + + +def ensure_evidence_layout(root: Path) -> dict[str, Path]: + """Create standard evidence subdirectories if missing (local/dev helper).""" + paths = evidence_subpaths(root) + for path in paths.values(): + path.mkdir(parents=True, exist_ok=True) + return paths diff --git a/src/inferrsi/apps/storage/result.py b/src/inferrsi/apps/storage/result.py new file mode 100644 index 00000000..23b3eebb --- /dev/null +++ b/src/inferrsi/apps/storage/result.py @@ -0,0 +1,398 @@ +"""Assemble and check the AppsResultV1 output envelope.""" + +import re +from dataclasses import fields +from hashlib import sha256 + +from inferrsi.contracts.json_v1 import encode +from inferrsi.harness.errors import PUBLIC_ERROR_CODES, PartialExecutionFacts + +_EXIT_CODES = { + "success": 0, + "error": 2, + "not_started": 3, + "in_progress": 4, + "recovery_required": 5, + "persistence_error": 6, + "execution_failed": 7, + "fail": 8, + "inconclusive": 9, +} +_ERROR_OUTCOMES = { + "AttemptInProgress": "in_progress", + "RecoveryRequired": "recovery_required", + "ExecutionPersistenceError": "persistence_error", + "ArchivePersistenceError": "persistence_error", +} +_RESULT_FIELDS = { + "schema_version", "operation", "outcome", "reason_code", "exit_code", + "primary_scope", "primary_claim_id", "attempt_id", "admission", "execution", + "prepared_ref", "record_ref", "assessment_ref", "assessment", "error", +} +_ERROR_FIELDS = { + "code", "stage", "attempt_id", "started", "latest_record_ref", + "partial_record", "retained_refs", "field_errors", "message", +} +_PARTIAL_FIELDS = {field.name for field in fields(PartialExecutionFacts)} +_REF_FIELDS = { + "prepared_ref": ("prepared_id", "schema_version"), + "record_ref": ("attempt_id", "record_version"), + "assessment_ref": ("assessment_id", "schema_version"), +} +_SHA256 = re.compile(r"[0-9a-f]{64}") +_RECORD_OBSERVATIONS = {"record_ref", "observed_at", "controller_observation"} +_VERDICT_OUTCOMES = {"PASS": "success", "FAIL": "fail", "INCONCLUSIVE": "inconclusive"} + + +def is_public_error(value: object) -> bool: + return ( + isinstance(value, dict) + and value.keys() == _ERROR_FIELDS + and isinstance(value["code"], str) + and value["code"] in PUBLIC_ERROR_CODES + ) + + +def _execute_outcome(record: dict) -> str: + if record.get("phase") == "recovery_required": + return "recovery_required" + if record.get("phase") != "finished": + raise ValueError("expected a terminal Harness record") + process = record.get("process_outcome") + if process == "not_started": + return "not_started" + if process in ("timed_out", "cancelled", "execution_error"): + return "execution_failed" + if process == "exited" and type(record.get("exit_code")) is int: + return "success" if record["exit_code"] == 0 else "execution_failed" + raise ValueError("unsupported Harness process outcome") + + +def execution_result(*, record: dict | None = None, error: dict | None = None) -> dict: + """Project a committed Harness record or a PublicError into AppsResultV1.""" + if (record is None) == (error is None): + raise ValueError("expected one Harness record or PublicError") + facts = record if record is not None else {} + return { + **_operation_result( + "execute", error, _execute_outcome(record) if record is not None else "error" + ), + "attempt_id": facts.get("attempt_id"), + "admission": facts.get("budget_admission"), + "execution": record, + "prepared_ref": facts.get("prepared_ref"), + "record_ref": facts.get("record_ref"), + } + + +def preparation_result(*, prepared_ref: dict | None = None, error: dict | None = None) -> dict: + """Project a committed PreparedRef or a PublicError into AppsResultV1.""" + if (prepared_ref is None) == (error is None): + raise ValueError("expected one PreparedRef or PublicError") + return {**_operation_result("prepare", error, "success"), "prepared_ref": prepared_ref} + + +def assessment_result( + *, + primary: tuple[str, str] | None = None, + assessment: dict | None = None, + assessment_ref: dict | None = None, + error: dict | None = None, +) -> dict: + """Project the selected claim and fixed assessment into AppsResultV1.""" + verdict = _selected_verdict(assessment, primary) if assessment is not None else None + result = _operation_result("assess", error, _VERDICT_OUTCOMES.get(verdict, "error")) + if assessment is not None: + result.update({ + field: assessment[field] for field in ("attempt_id", "prepared_ref", "record_ref") + }) + if primary is not None: + result["primary_claim_id"], result["primary_scope"] = primary + return {**result, "assessment": assessment, "assessment_ref": assessment_ref} + + +def _operation_result(operation: str, error: dict | None, outcome: str) -> dict: + reason = error["code"] if error is not None else None + if reason is not None: + outcome = _ERROR_OUTCOMES.get(reason, "error") + return { + "schema_version": 1, + "operation": operation, + "outcome": outcome, + "reason_code": reason, + "exit_code": _EXIT_CODES[outcome], + "primary_scope": None, + "primary_claim_id": None, + "attempt_id": None, + "admission": None, + "execution": None, + "prepared_ref": None, + "record_ref": None, + "assessment_ref": None, + "assessment": None, + "error": error, + } + + +def publication_error(result: dict) -> dict: + """Report an output failure while keeping every confirmed underlying fact.""" + prior = result["error"] or {} + record = result["execution"] or {} + code = "ArchivePersistenceError" + return { + **result, + "outcome": "persistence_error", + "reason_code": code, + "exit_code": 6, + "error": { + "code": code, + "stage": "output_publication", + "attempt_id": result["attempt_id"] or prior.get("attempt_id"), + "started": record.get("started", prior.get("started")), + "latest_record_ref": result["record_ref"] or prior.get("latest_record_ref"), + "partial_record": prior.get("partial_record"), + "retained_refs": prior.get("retained_refs", []), + "field_errors": prior.get("field_errors", []), + "message": "Could not publish the Apps output files.", + }, + } + + +def validate_artifact_ref(artifact: object) -> None: + if ( + not isinstance(artifact, dict) + or artifact.keys() != {"location", "sha256", "size_bytes", "media_type"} + or not isinstance(artifact["location"], str) or not artifact["location"] + or not isinstance(artifact["sha256"], str) or not _SHA256.fullmatch(artifact["sha256"]) + or type(artifact["size_bytes"]) is not int or artifact["size_bytes"] < 0 + or not isinstance(artifact["media_type"], str) or not artifact["media_type"] + ): + raise ValueError("invalid Apps reference metadata") + + +def _check_ref(ref: object, id_field: str, version_field: str) -> None: + if not isinstance(ref, dict) or ref.keys() != {id_field, version_field, "artifact"}: + raise ValueError("invalid Apps reference fields") + identity, version = ref[id_field], ref[version_field] + if ( + not isinstance(identity, str) or not identity + or type(version) is not int or version < 1 + or (version_field == "schema_version" and version != 1) + ): + raise ValueError("invalid Apps reference metadata") + validate_artifact_ref(ref["artifact"]) + + +def _check_partial(partial: dict) -> None: + if not isinstance(partial, dict) or partial.keys() != _PARTIAL_FIELDS: + raise ValueError("invalid partial execution fields") + if any(not isinstance(partial[key], str) or not partial[key] + for key in ("request_id", "run_id", "attempt_id")): + raise ValueError("invalid partial execution identity") + digest, version = partial["request_digest"], partial["proposed_record_version"] + if (digest is not None and (not isinstance(digest, str) + or not re.fullmatch(r"sha256:[0-9a-f]{64}", digest))) or ( + version is not None and (type(version) is not int or version < 0) + ): + raise ValueError("invalid partial execution revision") + if partial["phase"] not in ( + None, "registered", "preparing", "running", "stopping", "finalizing", + "finished", "recovery_required", + ) or (partial["started"] is not None and type(partial["started"]) is not bool) or ( + type(partial["side_effect_unknown"]) is not bool + ): + raise ValueError("invalid partial execution state") + for key in ("steps", "checks", "artifacts", "usage", "errors"): + if not isinstance(partial[key], list) or any( + not isinstance(item, dict) for item in partial[key] + ): + raise ValueError("invalid partial execution observations") + for key in ("budget_admission", "resource_leases"): + if partial[key] is not None and not isinstance(partial[key], dict): + raise ValueError("invalid partial execution accounting") + + +def _check_error(error: dict, outcome: str) -> None: + if ( + not is_public_error(error) + or outcome != _ERROR_OUTCOMES.get(error["code"], "error") + or not isinstance(error["stage"], str) or not error["stage"] + or (error["attempt_id"] is not None and not isinstance(error["attempt_id"], str)) + or (error["started"] is not None and not isinstance(error["started"], bool)) + or not isinstance(error["message"], str) + or not isinstance(error["field_errors"], list) + or any(not isinstance(item, str) for item in error["field_errors"]) + or not isinstance(error["retained_refs"], list) + ): + raise ValueError("invalid Apps PublicError") + partial = error["partial_record"] + if partial is not None: + _check_partial(partial) + if error["latest_record_ref"] is not None: + _check_ref(error["latest_record_ref"], *_REF_FIELDS["record_ref"]) + for ref in error["retained_refs"]: + validate_artifact_ref(ref) + + +def _check_artifact_ref(ref: dict, payload: dict) -> None: + artifact = ref["artifact"] + data = encode(payload) + if artifact["sha256"] != sha256(data).hexdigest() or artifact["size_bytes"] != len(data): + raise ValueError("fixed reference does not match the archived bytes") + + +def _check_record(result: dict, record: dict) -> None: + ref = result["record_ref"] + if ( + not isinstance(record, dict) + or ref is None + or not _RECORD_OBSERVATIONS <= record.keys() + or record["record_ref"] != ref + or not isinstance(record.get("budget_admission"), dict) + or record["budget_admission"] != result["admission"] + or record.get("prepared_ref") != result["prepared_ref"] + or record.get("attempt_id") != result["attempt_id"] + or not isinstance(record.get("run_id"), str) + or not record["run_id"] + or result["attempt_id"] is None + or ref.get("attempt_id") != result["attempt_id"] + or type(record.get("record_version")) is not int + or record["record_version"] < 1 + or ref.get("record_version") != record["record_version"] + ): + raise ValueError("inconsistent Apps execution and record reference") + _check_artifact_ref( + ref, {field: value for field, value in record.items() if field not in _RECORD_OBSERVATIONS} + ) + + +def _check_assessment(result: dict, *, output_error: bool) -> None: + assessment, ref = result["assessment"], result["assessment_ref"] + if assessment is not None and ( + not isinstance(assessment, dict) + or any( + result[field] is None or assessment.get(field) != result[field] + for field in ("attempt_id", "prepared_ref", "record_ref") + ) + ): + raise ValueError("inconsistent Apps assessment") + error = result["error"] + if ref is None: + if error is None: + raise ValueError("expected an archived assessment") + return + if ( + (error is not None and not output_error) + or assessment is None + or not assessment.get("assessment_id") + or assessment.get("assessment_id") != ref.get("assessment_id") + or assessment.get("schema_version") != ref.get("schema_version") + ): + raise ValueError("inconsistent Apps assessment reference") + _check_artifact_ref(ref, assessment) + verdict = _selected_verdict( + assessment, (result["primary_claim_id"], result["primary_scope"]) + ) + if not output_error and _VERDICT_OUTCOMES[verdict] != result["outcome"]: + raise ValueError("Apps outcome must match the selected primary claim") + + +def _selected_verdict(assessment: dict, primary: tuple[str, str] | None) -> str: + if primary is None or any(value is None for value in primary): + raise ValueError("expected a selected primary claim") + claims = assessment.get("claims") + if not isinstance(claims, list): + raise ValueError("expected assessment claims") + verdicts = [ + claim.get("verdict") + for claim in claims + if isinstance(claim, dict) + and (claim.get("claim_id"), claim.get("validation_scope")) == primary + ] + if ( + len(verdicts) != 1 + or not isinstance(verdicts[0], str) + or verdicts[0] not in _VERDICT_OUTCOMES + ): + raise ValueError("Apps outcome must match the selected primary claim") + return verdicts[0] + + +def validate_result(result: object) -> None: + """Check the Apps envelope and its links to the core responses.""" + if not isinstance(result, dict) or result.keys() != _RESULT_FIELDS: + raise ValueError("invalid AppsResultV1 fields") + if type(result["schema_version"]) is not int or result["schema_version"] != 1: + raise ValueError("unsupported Apps result version") + operation = result["operation"] + if operation not in ("prepare", "execute", "assess"): + raise ValueError("invalid Apps operation") + outcome, exit_code = result["outcome"], result["exit_code"] + if ( + not isinstance(outcome, str) + or type(exit_code) is not int + or _EXIT_CODES.get(outcome) != exit_code + ): + raise ValueError("inconsistent Apps outcome and exit code") + error = result["error"] + if error is not None: + _check_error(error, outcome) + if result["reason_code"] != (error["code"] if error is not None else None): + raise ValueError("inconsistent Apps reason and error") + if error is None and outcome in ("error", "in_progress", "persistence_error"): + raise ValueError("expected a PublicError for the Apps outcome") + for field, (id_field, version_field) in _REF_FIELDS.items(): + if result[field] is not None: + _check_ref(result[field], id_field, version_field) + for field in ("primary_scope", "primary_claim_id", "attempt_id"): + if result[field] is not None and ( + not isinstance(result[field], str) or not result[field] + ): + raise ValueError("invalid Apps identifier") + + record = result["execution"] + if record is not None: + _check_record(result, record) + + output_error = ( + error is not None and error["code"] == "ArchivePersistenceError" + and error["stage"] == "output_publication" + ) + if operation == "assess": + _check_assessment(result, output_error=output_error) + return + + if any( + result[field] is not None + for field in ("assessment", "assessment_ref", "primary_scope", "primary_claim_id") + ): + raise ValueError("unexpected assessment fields for the Apps operation") + if operation == "prepare": + if error is not None and any( + error[key] is not None + for key in ("attempt_id", "started", "latest_record_ref", "partial_record") + ): + raise ValueError("unexpected execution facts in prepare error") + if any( + result[field] is not None + for field in ("execution", "record_ref", "attempt_id", "admission") + ): + raise ValueError("unexpected execution fields for prepare") + if ( + not output_error + and (result["prepared_ref"] is not None) != (error is None) + ): + raise ValueError("inconsistent prepare archive reference") + if error is None and outcome != "success": + raise ValueError("expected a successful prepare outcome") + elif record is None: + if ( + error is None + or any( + result[field] is not None + for field in ("record_ref", "prepared_ref", "attempt_id", "admission") + ) + ): + raise ValueError("execute result requires a committed record for execution facts") + elif not output_error and (error is not None or outcome != _execute_outcome(record)): + raise ValueError("Apps execute outcome must match the committed record") diff --git a/src/inferrsi/apps/views/attempt.py b/src/inferrsi/apps/views/attempt.py index 26c99223..b39bedaa 100644 --- a/src/inferrsi/apps/views/attempt.py +++ b/src/inferrsi/apps/views/attempt.py @@ -5,10 +5,10 @@ from inferrsi.contracts.json_v1 import decode from inferrsi.harness.errors import PublicError -from ..archive import read_assessment -from ..artifact_reader import ArtifactReader from ..bridge import check_assessment_identity -from ..result import _check_ref +from ..storage.archive import read_assessment +from ..storage.artifact_reader import ArtifactReader +from ..storage.result import _check_ref _EXECUTION_FIELDS = ( "run_id", "attempt_id", "record_version", "phase", "started", "side_effect_unknown", diff --git a/src/inferrsi/contracts/evidence.py b/src/inferrsi/contracts/evidence.py index 32bf0ee5..6b30f346 100644 --- a/src/inferrsi/contracts/evidence.py +++ b/src/inferrsi/contracts/evidence.py @@ -1,7 +1,7 @@ """Evidence segment names and per-campaign path rules (portable; no campaign pins). Path construction only. Nothing here reads or writes the filesystem; creating the -directories is ``inferrsi.apps.evidence_layout.ensure_evidence_layout``. +directories is ``inferrsi.apps.storage.evidence_layout.ensure_evidence_layout``. """ from __future__ import annotations diff --git a/tests/_gate_policy_support.py b/tests/_gate_policy_support.py index 1eb2f021..0914fd02 100644 --- a/tests/_gate_policy_support.py +++ b/tests/_gate_policy_support.py @@ -119,7 +119,7 @@ # import, so a module that may use the encoder also loads these two names, and no other. CONTRACTS_INIT_EXPORT = ("inferrsi.contracts.runspec", "RunSpec") # #451 C2 adds exactly one module: the evidence segment and path rules. Directory -# creation is ``inferrsi.apps.evidence_layout`` and is not a contracts module. +# creation is ``inferrsi.apps.storage.evidence_layout`` and is not a contracts module. CONTRACTS_EVIDENCE = "inferrsi.contracts.evidence" CONTRACTS_MODULES = frozenset( { diff --git a/tests/check_installed.py b/tests/check_installed.py index 1d11b1d8..66641673 100644 --- a/tests/check_installed.py +++ b/tests/check_installed.py @@ -3,6 +3,7 @@ import io import json import os +import pickle import subprocess import sys import tempfile @@ -613,7 +614,18 @@ def _inventory(root, prefix): else: raise AssertionError("an unknown repository type must be refused") assert evidence.EVIDENCE_SEGMENTS == ("plan", "results", "patch", "validator") -assert find_spec("inferrsi.apps.evidence_layout") is not None +# #490 storage: both installed import paths expose the same canonical objects. +for name in ("archive", "artifact_reader", "result", "evidence_layout"): + old_name = f"inferrsi.apps.{name}" + canonical_name = f"inferrsi.apps.storage.{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__: + value = getattr(canonical, exported) + assert getattr(old, exported) is value, (old_name, exported) + 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) 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_artifact_reader.py b/tests/test_apps_artifact_reader.py index ac823fce..a8f11008 100644 --- a/tests/test_apps_artifact_reader.py +++ b/tests/test_apps_artifact_reader.py @@ -4,7 +4,7 @@ import pytest -from inferrsi.apps.artifact_reader import ArtifactReader +from inferrsi.apps.storage.artifact_reader import ArtifactReader from inferrsi.harness.errors import PublicError from inferrsi.harness.run_store import RunStore, artifact_ref from tests.h01_run_store_child import make_attempt, make_digest, make_payload diff --git a/tests/test_apps_assess.py b/tests/test_apps_assess.py index 68da1112..c054bacf 100644 --- a/tests/test_apps_assess.py +++ b/tests/test_apps_assess.py @@ -11,11 +11,11 @@ import pytest -from inferrsi.apps import archive from inferrsi.apps.api import EvaluationPort, read_attempt_view from inferrsi.apps.api import assess as run_assess -from inferrsi.apps.artifact_reader import ArtifactReader from inferrsi.apps.cli import main +from inferrsi.apps.storage import archive +from inferrsi.apps.storage.artifact_reader import ArtifactReader from inferrsi.apps.views.dashboard_live import DashboardServer from inferrsi.contracts.json_v1 import decode, encode from inferrsi.harness.errors import PublicError @@ -476,7 +476,7 @@ def test_new_process_reassesses_the_requested_sqlite_revision(tmp_path, offline) from pathlib import Path from inferrsi.contracts.json_v1 import decode, encode from inferrsi.apps.api import EvaluationPort, assess as run_assess, read_attempt_view -from inferrsi.apps.archive import read_assessment +from inferrsi.apps.storage.archive import read_assessment workspace = Path.cwd() request, config, decision, receipt = decode((workspace / 'offline.json').read_bytes()) diff --git a/tests/test_apps_generation_plan.py b/tests/test_apps_generation_plan.py index 2f93cf99..3d751982 100644 --- a/tests/test_apps_generation_plan.py +++ b/tests/test_apps_generation_plan.py @@ -8,8 +8,8 @@ import pytest from inferrsi.apps.api import CandidateProvider -from inferrsi.apps.artifact_reader import ArtifactReader from inferrsi.apps.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 from inferrsi.harness.errors import PublicError diff --git a/tests/test_apps_module_migrations.py b/tests/test_apps_module_migrations.py new file mode 100644 index 00000000..e6a7a824 --- /dev/null +++ b/tests/test_apps_module_migrations.py @@ -0,0 +1,185 @@ +"""Compatibility and dependency checks for the implemented #490 slices.""" + +import ast +import inspect +import json +import pickle +from importlib import import_module +from pathlib import Path +from typing import get_origin + +import pytest + +from tests import _gate_policy_support as support +from tests.test_contracts_package import IO_CONTROL, IO_PROBE, _fresh + +REPO = Path(__file__).resolve().parents[1] +ROOT = REPO / "src/inferrsi" +MIGRATIONS = json.loads((REPO / "docs/apps-module-migrations.json").read_text(encoding="utf-8")) + + +@pytest.mark.parametrize("entry", MIGRATIONS, ids=lambda entry: entry["old"]) +def test_shim_is_an_explicit_export_of_the_same_objects(entry): + path = REPO / "src" / (entry["old"].replace(".", "/") + ".py") + tree = ast.parse(path.read_text(encoding="utf-8")) + docstring, imported, declared = tree.body + assert isinstance(docstring, ast.Expr) and isinstance(docstring.value, ast.Constant) + assert isinstance(imported, ast.ImportFrom) and imported.level == 1 + assert "inferrsi.apps." + imported.module == entry["canonical"] + assert sorted((name.name, name.asname) for name in imported.names) == sorted( + (name, None) for name in entry["exports"] + ) + assert isinstance(declared, ast.Assign) + assert [target.id for target in declared.targets] == ["__all__"] + assert ast.literal_eval(declared.value) == entry["exports"] + old, canonical = import_module(entry["old"]), import_module(entry["canonical"]) + assert old.__all__ == entry["exports"] + assert sorted(name for name in vars(old) if not name.startswith("_")) == sorted(old.__all__) + for name in entry["exports"]: + value = getattr(canonical, name) + assert getattr(old, name) is value + # Generic aliases retain stdlib metadata; only definitions move modules. + if get_origin(value) is None and (inspect.isfunction(value) or inspect.isclass(value)): + assert value.__module__ == entry["canonical"] + # Protocol 0 GLOBAL references mirror pre-migration function/class pickles. + assert pickle.loads(f"c{entry['old']}\n{name}\n.".encode("ascii")) is value + new_pickle = pickle.dumps(value, protocol=0) + assert entry["canonical"].encode("ascii") in new_pickle + assert pickle.loads(new_pickle) is value + + +def test_generic_alias_identity_does_not_depend_on_inspect_isclass(monkeypatch): + from inferrsi.apps.storage.archive import ResourceReader + + original = inspect.isclass + monkeypatch.setattr( + inspect, "isclass", lambda value: value is ResourceReader or original(value) + ) + entry = next(entry for entry in MIGRATIONS if entry["old"] == "inferrsi.apps.archive") + test_shim_is_an_explicit_export_of_the_same_objects(entry) + + +def test_old_run_output_instance_pickle_loads_and_preserves_its_data(): + # Construct the legacy bytes using the original definition from the old module. + source = """from dataclasses import dataclass +from pathlib import Path +@dataclass(frozen=True) +class RunOutput: + output_id: str + directory: Path | None + result: dict +""" + import sys + from types import ModuleType + from unittest.mock import patch + + old = ModuleType("inferrsi.apps.archive") + with patch.dict(sys.modules, {old.__name__: old}): + exec(source, old.__dict__) + data = pickle.dumps(old.RunOutput("output-test", Path("outputs/test"), {"retained": True})) + from inferrsi.apps.storage.archive import RunOutput + + restored = pickle.loads(data) + assert type(restored) is RunOutput + assert restored == RunOutput("output-test", Path("outputs/test"), {"retained": True}) + + +def test_active_consumers_use_canonical_paths_and_are_registered(): + modules = support._module_index(ROOT) + old_names = {entry["old"] for entry in MIGRATIONS} + entries = {entry["canonical"]: entry for entry in MIGRATIONS} + shims = {name.replace(".", "/") + ".py" for name in old_names} + for entry in MIGRATIONS: + assert entry["consumers"] and len(entry["consumers"]) == len(set(entry["consumers"])) + assert all((REPO / path).is_file() for path in entry["consumers"]) + for base in (REPO / "src", REPO / "tests", REPO / "tools", REPO / "plugins"): + for path in base.rglob("*.py"): + if path.is_relative_to(REPO / "tests/fixtures/legacy"): + continue + relative = path.relative_to(REPO).as_posix() + if relative.removeprefix("src/") in shims: + continue + package = ".".join(path.relative_to(base).parts[:-1]) + targets = support._direct_targets( + ast.parse(path.read_text(encoding="utf-8")), package, modules + ) + assert not targets & old_names, (relative, targets & old_names) + for target in targets & entries.keys(): + assert relative in entries[target]["consumers"], (relative, target) + + +def _is_handoff(name): + # The root implementations remain here until the next #490 slice. + return name in { + "inferrsi.apps.api", "inferrsi.apps.bridge", "inferrsi.apps.context_provider", + "inferrsi.apps.candidate_provider", + } or name == "inferrsi.apps.handoff" or name.startswith("inferrsi.apps.handoff.") + + +def test_storage_has_no_direct_or_transitive_handoff_dependency(): + graph = support._scan(ROOT, frozenset()) + for name in graph.edges: + if name == "inferrsi.apps.storage" or name.startswith("inferrsi.apps.storage."): + _, violations = support._walk(name, graph.edges, _is_handoff) + assert not violations, violations + + +@pytest.mark.parametrize("indirect", [False, True]) +def test_storage_dependency_check_rejects_a_handoff_back_edge(tmp_path, indirect): + files = { + "apps/__init__.py": "", + "apps/storage/__init__.py": "", + "apps/handoff/__init__.py": "", + "apps/handoff/bridge.py": "VALUE = 1\n", + "apps/storage/archive.py": "from ..handoff import bridge\n", + } + if indirect: + files["apps/storage/archive.py"] = "from inferrsi.contracts import helper\n" + files["contracts/helper.py"] = "from inferrsi.apps.handoff import bridge\n" + for relative, source in files.items(): + path = tmp_path / relative + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(source, encoding="utf-8") + graph = support._scan(tmp_path, frozenset()) + _, violations = support._walk("inferrsi.apps.storage.archive", graph.edges, _is_handoff) + assert any(target == "inferrsi.apps.handoff.bridge" for target, _ in violations) + if 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"] + [ + 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"] == [] + + +def test_cold_storage_imports_do_not_load_handoff_or_probe_modules(): + script = """ +import importlib, importlib.abc, json, sys, warnings +blocked = ('inferrsi.apps.handoff', 'inferrsi.apps.api', 'inferrsi.apps.bridge', + 'inferrsi.apps.context_provider', 'inferrsi.apps.candidate_provider', + 'inferrsi.infra', 'inferrsi.knowledge', 'inferrsi.benchmark', + 'inferrsi.harness.api', 'inferrsi.harness.run_store') +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()) +with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter('always') + importlib.import_module('inferrsi.apps.storage') + parent_only = sorted(name for name in sys.modules if name.startswith('inferrsi.apps')) + for name in json.loads(sys.argv[1]): + 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")] + result = _fresh(script, json.dumps(modules)) + assert result == {"parent_only": ["inferrsi.apps", "inferrsi.apps.storage"], "warnings": []} diff --git a/tests/test_apps_output.py b/tests/test_apps_output.py index 034dc2c4..f1238bae 100644 --- a/tests/test_apps_output.py +++ b/tests/test_apps_output.py @@ -11,9 +11,9 @@ import pytest -from inferrsi.apps import archive from inferrsi.apps.api import execute -from inferrsi.apps.archive import publish_result, read_result +from inferrsi.apps.storage import archive +from inferrsi.apps.storage.archive import publish_result, read_result from inferrsi.contracts.json_v1 import decode, encode from inferrsi.harness.errors import PublicError from inferrsi.harness.run_store import Claim, RunStore, flatten, request_digest, utc_now diff --git a/tests/test_apps_port_validation.py b/tests/test_apps_port_validation.py index f1c9eff3..815140a4 100644 --- a/tests/test_apps_port_validation.py +++ b/tests/test_apps_port_validation.py @@ -6,7 +6,7 @@ import pytest from inferrsi.apps.api import execute -from inferrsi.apps.archive import read_result +from inferrsi.apps.storage.archive import read_result from inferrsi.harness.errors import PartialExecutionFacts, PublicError from inferrsi.harness.execution_spec import request_digest from inferrsi.harness.run_store import request_digest as legacy_digest diff --git a/tests/test_apps_prepare.py b/tests/test_apps_prepare.py index 1038d00a..077dfbe2 100644 --- a/tests/test_apps_prepare.py +++ b/tests/test_apps_prepare.py @@ -11,9 +11,9 @@ import pytest -from inferrsi.apps import archive from inferrsi.apps.api import prepare -from inferrsi.apps.archive import read_archive_artifact, read_prepared, read_result +from inferrsi.apps.storage import archive +from inferrsi.apps.storage.archive import read_archive_artifact, read_prepared, read_result from inferrsi.contracts.json_v1 import decode, encode from inferrsi.harness.errors import PublicError @@ -166,7 +166,7 @@ def validate(value, data): import json import sys from inferrsi.contracts.json_v1 import encode -from inferrsi.apps.archive import read_archive_artifact, read_prepared +from inferrsi.apps.storage.archive import read_archive_artifact, read_prepared config, ref = json.load(sys.stdin) prepared = read_prepared(config, ref) diff --git a/tests/test_apps_publication.py b/tests/test_apps_publication.py index 2c867483..97e5df6d 100644 --- a/tests/test_apps_publication.py +++ b/tests/test_apps_publication.py @@ -7,7 +7,7 @@ import pytest -from inferrsi.apps import archive +from inferrsi.apps.storage import archive def _result(): diff --git a/tests/test_apps_replay.py b/tests/test_apps_replay.py index d995a8ef..2762e56f 100644 --- a/tests/test_apps_replay.py +++ b/tests/test_apps_replay.py @@ -12,7 +12,7 @@ from pathlib import Path from inferrsi.apps.api import execute -from inferrsi.apps.archive import read_result +from inferrsi.apps.storage.archive import read_result from inferrsi.harness.run_store import Claim, RunStore, request_digest from tests.test_apps_output import _bind, _request, _submit_to_run_store diff --git a/tests/test_evidence_paths.py b/tests/test_evidence_paths.py index 05c7ab6e..d263c0a8 100644 --- a/tests/test_evidence_paths.py +++ b/tests/test_evidence_paths.py @@ -1,7 +1,7 @@ """Evidence path rules and directory creation are separate modules (#451 C2). ``inferrsi.contracts.evidence`` builds paths and never touches the filesystem. -``inferrsi.apps.evidence_layout`` is the one place that calls ``mkdir``. Root +``inferrsi.apps.storage.evidence_layout`` is the one place that calls ``mkdir``. Root ``inferrsi.evidence_paths`` is retired without an alias. """ @@ -19,8 +19,8 @@ import pytest -from inferrsi.apps import evidence_layout -from inferrsi.apps.evidence_layout import ensure_evidence_layout +from inferrsi.apps.storage import evidence_layout +from inferrsi.apps.storage.evidence_layout import ensure_evidence_layout from inferrsi.contracts import evidence from inferrsi.contracts.evidence import ( EVIDENCE_SEGMENTS, @@ -36,7 +36,7 @@ AUDIT = """ import json, sys from pathlib import Path -from inferrsi.apps.evidence_layout import ensure_evidence_layout +from inferrsi.apps.storage.evidence_layout import ensure_evidence_layout from inferrsi.contracts.evidence import campaign_evidence_root, evidence_subpaths IO_EVENTS = ("os.", "shutil.", "pathlib.", "tempfile.", "glob.", "subprocess.", "socket.") seen = {"rules": [], "layout": []} @@ -190,7 +190,7 @@ def mkdir_calls(path: Path) -> list[ast.Call]: for path in sorted((ROOT / "contracts").glob("*.py")): assert mkdir_calls(path) == [], path.name - calls = mkdir_calls(ROOT / "apps" / "evidence_layout.py") + calls = mkdir_calls(ROOT / "apps" / "storage" / "evidence_layout.py") assert len(calls) == 1 and calls[0].args == [] assert {key.arg: key.value.value for key in calls[0].keywords} == { "parents": True, "exist_ok": True, @@ -294,7 +294,9 @@ def test_retired_evidence_paths_module_has_no_alias() -> None: # New pickles name the canonical modules, and path values are plain data. assert b"inferrsi.contracts.evidence" in pickle.dumps(evidence_subpaths, protocol=0) assert pickle.loads(pickle.dumps(campaign_evidence_root)) is campaign_evidence_root - assert b"inferrsi.apps.evidence_layout" in pickle.dumps(ensure_evidence_layout, protocol=0) + assert b"inferrsi.apps.storage.evidence_layout" in pickle.dumps( + ensure_evidence_layout, protocol=0 + ) assert pickle.loads(pickle.dumps(ensure_evidence_layout)) is ensure_evidence_layout assert b"inferrsi" not in pickle.dumps(EVIDENCE_SEGMENTS, protocol=0) assert b"inferrsi" not in pickle.dumps(evidence_subpaths(Path("root")), protocol=0) diff --git a/tests/test_first_wave_isolation_policy.py b/tests/test_first_wave_isolation_policy.py index 953ee6e0..4b938ecc 100644 --- a/tests/test_first_wave_isolation_policy.py +++ b/tests/test_first_wave_isolation_policy.py @@ -894,6 +894,11 @@ def test_contract_modules_import_no_inferrsi_module(self) -> None: "from inferrsi.apps import evidence_layout\n", "inferrsi.contracts.evidence imports inferrsi.apps.evidence_layout", ), + ( + "contracts/evidence.py", + "from inferrsi.apps.storage import evidence_layout\n", + "inferrsi.contracts.evidence imports inferrsi.apps.storage", + ), ( "contracts/evidence.py", "from ..harness import api\n", diff --git a/tests/test_repository_packs_facade.py b/tests/test_repository_packs_facade.py index 4ba246d1..7b6de346 100644 --- a/tests/test_repository_packs_facade.py +++ b/tests/test_repository_packs_facade.py @@ -203,14 +203,14 @@ def test_facade_and_parent_load_under_a_hook_that_blocks_every_other_inferrsi_im def test_module_bodies_do_no_io_on_import() -> None: modules = ("inferrsi.resources", "inferrsi.resources.repository_packs", - "inferrsi.apps.evidence_layout") + "inferrsi.apps.storage.evidence_layout") result = _fresh(IO_PROBE, json.dumps(modules), IO_CONTROL) seen, defined = result["seen"], result["defined"] assert {"os.listdir", "open"} <= set(seen.pop("control")) assert seen == {name: [] for name in modules} assert defined["inferrsi.resources"] == [] assert {"REPO_TYPES", "repository_pack"} <= set(defined["inferrsi.resources.repository_packs"]) - assert "ensure_evidence_layout" in defined["inferrsi.apps.evidence_layout"] + assert "ensure_evidence_layout" in defined["inferrsi.apps.storage.evidence_layout"] assert sorted(name for name in vars(resources) if not name.startswith("_")) == [ "repository_packs" ] diff --git a/tests/test_result_delivery.py b/tests/test_result_delivery.py index 03e8878a..6f56a4d9 100644 --- a/tests/test_result_delivery.py +++ b/tests/test_result_delivery.py @@ -4,12 +4,13 @@ import pytest -from inferrsi.apps import archive, delivery +from inferrsi.apps import delivery from inferrsi.apps.cli import main from inferrsi.apps.delivery.projection import metric from inferrsi.apps.delivery.schema import decode, validate_result from inferrsi.apps.delivery.snapshot import MAX_DOCUMENT_BYTES, Snapshot -from inferrsi.apps.result import preparation_result +from inferrsi.apps.storage import archive +from inferrsi.apps.storage.result import preparation_result from inferrsi.harness import optimization from inferrsi.infra.artifacts import atomic_write_json, sha256