firedrill-run 2.0.0__py3-none-any.whl

firedrill/__init__.py

@@ -0,0 +1,55 @@
+"""Firedrill's native, authenticated Python client."""
+from .client import AsyncFiredrill, Firedrill, SimulationProgress, RunnerCapacity
+from .errors import FiredrillError, RecoveryRequired, TransportError, CLIENT_DIAGNOSTICS_VERSION, DiagnosticCategory, RetrySafety, WorkStarted
+from .models import ASSESSMENT_POLICY_VERSION, NUMERIC_CHECK_VERSION, REPORT_LINK_VERSION, TARGET_INVOCATION_VERSION, TargetScenario, ReportLink, BatchResult, CONTRACT_VERSION, SEQUENCE_VERSION, SERVICE_CONTROL_VERSION, SERVICE_CONTROL_CLOCK_VERSION, RunContext
+from .batch_receipt import batch_receipt, BatchReceipt, BATCH_RECEIPT_VERSION
+from .models import RESULT_LIFECYCLE_VERSION, ResultLifecycle, ResultEvidence, ResultCleanup, ResultRecovery, BatchLifecycleRead, RetentionAvailability
+from .services import ConnectionGrant, FiredrillServices, AsyncFiredrillServices
+from .run_tools import RunTool
+from .credentials import CREDENTIAL_VERSION, IssuedCredential, FiredrillCredentials, AsyncFiredrillCredentials
+from .capacity import CAPACITY_REQUEST_VERSION, CapacityResource, CapacityRequest, CapacityRequestPage, FiredrillCapacity, AsyncFiredrillCapacity
+from .retention import RETENTION_VERSION, FiredrillRetention, AsyncFiredrillRetention, RetentionResource
+from .interventions import RUN_INTERVENTION_VERSION, RUN_CLOCK_INTERVENTION_VERSION, FiredrillInterventions, AsyncFiredrillInterventions
+from .login import FiredrillLogin, AsyncFiredrillLogin
+from .device_authorization import DeviceAuthorizationError, start_device_authorization, refresh_provider_tokens
+from .ci import CI_CONTEXT_VERSION, CI_REPORT_VERSION, CiContext, CiReportReceipt
+from .activity import ACTIVITY_VERSION, ActivityFilters, ActivityPageMetadata
+from .scoring import COMPOSITE_VERSION, CompositePolicy, CompositeComponent, CompositeResult
+from .task_metrics import (TASK_METRIC_VERSION, TaskMetricDefinition, TaskMetricDirection,
+                           TaskMetricResult, TaskMetricSummary)
+from .follow import FOLLOW_VERSION, FollowObservation, FollowResult
+from .submission import SUBMISSION_RECEIPT_VERSION, SubmissionReceipt, SubmissionError
+from .artifact_downloads import ArtifactReference, ArtifactManifest, ArtifactContent, ArtifactDownload, ArtifactRetention, UnavailableArtifact, RetainedArtifact
+from .service_build_diagnostics import SERVICE_BUILD_DIAGNOSTICS_VERSION, ServiceBuild, ServiceBuildFailure, ServiceBuildDiagnostic, ServiceBuildDiagnosticCode
+from .read_scope import READ_SCOPE_VERSION
+from .population_disclosure import (POPULATION_PURPOSE_VERSION, POPULATION_DISCLOSURE_VERSION,
+                                    PopulationPurpose, PopulationDisclosure, PopulationProvenance)
+from .discovery import (DISCOVERY_VERSION, AUTHORING_SCHEMA_IDS, AuthoringSchemaId,
+                        ProductCapability, ProductDiscovery, AuthoringSchemaDocument)
+from .retained_values import (RETAINED_VALUE_VERSION, OPERATOR_DOCUMENT_VERSION, RetainedValueOptions, RetainedValueChunk,
+                              RetainedValueReference, RetainedResource, RetainedValueSource,
+                              RunValueSource, RetainedValueType, OperatorDocument)
+
+__all__ = ["Firedrill", "AsyncFiredrill", "SimulationProgress", "RunnerCapacity", "BatchResult", "BatchReceipt", "batch_receipt", "BATCH_RECEIPT_VERSION", "RunContext", "TARGET_INVOCATION_VERSION", "TargetScenario", "FiredrillError",
+           "TransportError", "RecoveryRequired", "CONTRACT_VERSION", "SEQUENCE_VERSION", "SERVICE_CONTROL_VERSION", "SERVICE_CONTROL_CLOCK_VERSION", "ASSESSMENT_POLICY_VERSION", "ConnectionGrant", "FiredrillServices", "AsyncFiredrillServices", "RunTool",
+           "CLIENT_DIAGNOSTICS_VERSION", "DiagnosticCategory", "RetrySafety", "WorkStarted",
+           "RESULT_LIFECYCLE_VERSION", "ResultLifecycle", "ResultEvidence", "ResultCleanup", "ResultRecovery", "BatchLifecycleRead", "RetentionAvailability",
+           "CREDENTIAL_VERSION", "IssuedCredential", "FiredrillCredentials", "AsyncFiredrillCredentials",
+           "CAPACITY_REQUEST_VERSION", "CapacityResource", "CapacityRequest", "CapacityRequestPage", "FiredrillCapacity", "AsyncFiredrillCapacity",
+           "RETENTION_VERSION", "FiredrillRetention", "AsyncFiredrillRetention", "RetentionResource",
+           "RUN_INTERVENTION_VERSION", "RUN_CLOCK_INTERVENTION_VERSION", "FiredrillInterventions", "AsyncFiredrillInterventions",
+           "FiredrillLogin", "AsyncFiredrillLogin", "DeviceAuthorizationError", "start_device_authorization", "refresh_provider_tokens",
+           "RETAINED_VALUE_VERSION", "OPERATOR_DOCUMENT_VERSION", "RetainedValueOptions", "RetainedValueChunk", "RetainedValueReference",
+           "RetainedResource", "RetainedValueSource", "RunValueSource", "RetainedValueType", "OperatorDocument",
+           "DISCOVERY_VERSION", "AUTHORING_SCHEMA_IDS", "AuthoringSchemaId", "ProductCapability", "ProductDiscovery", "AuthoringSchemaDocument", "NUMERIC_CHECK_VERSION",
+           "CI_CONTEXT_VERSION", "CI_REPORT_VERSION", "CiContext", "CiReportReceipt", "REPORT_LINK_VERSION", "ReportLink",
+           "ACTIVITY_VERSION", "ActivityFilters", "ActivityPageMetadata",
+           "COMPOSITE_VERSION", "CompositePolicy", "CompositeComponent", "CompositeResult",
+           "TASK_METRIC_VERSION", "TaskMetricDefinition", "TaskMetricDirection", "TaskMetricResult", "TaskMetricSummary",
+           "FOLLOW_VERSION", "FollowObservation", "FollowResult",
+           "SUBMISSION_RECEIPT_VERSION", "SubmissionReceipt", "SubmissionError",
+           "ArtifactReference", "ArtifactManifest", "ArtifactContent", "ArtifactDownload",
+           "ArtifactRetention", "UnavailableArtifact", "RetainedArtifact",
+           "SERVICE_BUILD_DIAGNOSTICS_VERSION", "ServiceBuild", "ServiceBuildFailure", "ServiceBuildDiagnostic", "ServiceBuildDiagnosticCode",
+           "POPULATION_PURPOSE_VERSION", "POPULATION_DISCLOSURE_VERSION",
+           "PopulationPurpose", "PopulationDisclosure", "PopulationProvenance"]

firedrill/activity.py

@@ -0,0 +1,107 @@
+"""Literal retained-activity filters and bounded page queries; no target actions."""
+from __future__ import annotations
+
+import re
+from typing import Literal, NotRequired, TypedDict
+from urllib.parse import urlencode
+
+from .errors import FiredrillError
+from .transport import segment
+
+ACTIVITY_VERSION = "2026-10-16-activity.1"
+
+
+class ActivityFilters(TypedDict):
+    """Wire field names retained in report.activity.filters."""
+    eventKind: NotRequired[str]
+    eventProducer: NotRequired[str]
+
+
+class ActivityPageMetadata(TypedDict):
+    schemaVersion: Literal["2026-10-16-activity.1"]
+    filters: ActivityFilters
+    filtered: bool
+    afterSequence: int
+
+
+def confirm_activity_selection(response, *, event_kind: str | None = None,
+                               event_producer: str | None = None, operator: bool = False):
+    """An older service may ignore query fields: never call that a filtered page."""
+    expected = {}
+    if event_kind is not None:
+        expected["eventKind"] = event_kind
+    if event_producer is not None:
+        expected["eventProducer"] = event_producer
+    if not expected:
+        return response  # Historical unfiltered reports remain readable.
+    body = response.get("value") if operator and isinstance(response, dict) else response
+    metadata = body.get("activity") if isinstance(body, dict) else None
+    if (not isinstance(metadata, dict)
+            or set(metadata) != {"schemaVersion", "filters", "filtered", "afterSequence"}
+            or metadata.get("schemaVersion") != ACTIVITY_VERSION or metadata.get("filtered") is not True
+            or type(metadata.get("afterSequence")) is not int or not 0 <= metadata["afterSequence"] <= 2147483647
+            or not isinstance(metadata.get("filters"), dict) or metadata["filters"] != expected):
+        raise FiredrillError("The service did not confirm the requested activity filters",
+            code="ACTIVITY_SELECTION_UNCONFIRMED",
+            repair="Use matching client/service versions, or deliberately clear the activity filters for an unfiltered read. No automatic retry or target execution occurred.")
+    return response
+
+
+def _invalid(message: str):
+    raise FiredrillError(message, code="ACTIVITY_QUERY_INVALID",
+        repair="Omit cursor for the first page. Reuse nextCursor with the same event_kind and event_producer; clear it when changing filters. No request was sent.")
+
+
+def _literal(value, maximum, name):
+    valid = isinstance(value, str)
+    if valid:
+        try:
+            valid = (1 <= len(value.encode("utf-16-le")) // 2 <= maximum
+                     and not any(ord(char) < 32 or ord(char) == 127 for char in value))
+            value.encode("utf-8")
+        except UnicodeEncodeError:
+            valid = False
+    if not valid:
+        _invalid(f"{name} must contain 1–{maximum} characters without control characters or unpaired Unicode surrogates; preserve case and spaces")
+    return value
+
+
+def activity_report_query(*, cursor: str | None = None, limit: int = 100,
+                          event_kind: str | None = None, event_producer: str | None = None,
+                          operator: bool = False, check_cursor: str | None = None) -> dict[str, str | int]:
+    """Do not decode opaque cursors or reinterpret their server-owned bindings."""
+    maximum = 20 if operator else 100
+    if type(limit) is not int or not 1 <= limit <= maximum:
+        _invalid(f"Report limit must be an integer between 1 and {maximum}")
+    query: dict[str, str | int] = {"limit": limit}
+    if operator:
+        query["view"] = "operator"
+    if event_kind is not None:
+        query["eventKind"] = _literal(event_kind, 120, "event_kind")
+    if event_producer is not None:
+        query["eventProducer"] = _literal(event_producer, 200, "event_producer")
+    filtered = event_kind is not None or event_producer is not None
+    if cursor is not None:
+        if not isinstance(cursor, str) or len(cursor) > 1024:
+            _invalid("Activity cursor must be a returned string of at most 1024 characters")
+        if cursor not in ("", "0"):
+            if filtered:
+                if not re.fullmatch(r"[A-Za-z0-9_-]+", cursor) or re.fullmatch(r"[0-9]+", cursor):
+                    _invalid("Filtered activity requires the returned opaque cursor, not a positive numeric offset")
+            elif not re.fullmatch(r"[1-9][0-9]{0,8}", cursor) or int(cursor) > 100000000:
+                _invalid("Unfiltered activity requires a nonnegative decimal cursor up to 100000000")
+        query["cursor"] = cursor
+    if check_cursor is not None:
+        if (not operator or not isinstance(check_cursor, str)
+                or not re.fullmatch(r"0|[1-9][0-9]{0,6}", check_cursor) or int(check_cursor) > 1000000):
+            _invalid("check_cursor is only valid for operator reports and must be the returned decimal cursor up to 1000000")
+        query["checkCursor"] = check_cursor
+    return query
+
+
+def report_path(run_id: str, *, cursor: str | None = None, limit: int = 100,
+                event_kind: str | None = None, event_producer: str | None = None) -> str:
+    if not isinstance(run_id, str) or not re.fullmatch(r"[A-Za-z0-9_-]{1,160}", run_id):
+        _invalid("Use the exact retained run ID")
+    query = activity_report_query(cursor=cursor, limit=limit, event_kind=event_kind, event_producer=event_producer)
+    return f"/v1/runs/{segment(run_id)}/report?" + urlencode(query)

firedrill/artifact_downloads.py

@@ -0,0 +1,191 @@
+"""Read captured evidence without target execution or operator-token disclosure."""
+from __future__ import annotations
+
+import hashlib
+from datetime import datetime
+import os
+from pathlib import Path
+import re
+import uuid
+from typing import Literal, NotRequired, TypedDict
+
+from .errors import FiredrillError, TransportError
+
+
+class ArtifactRetention(TypedDict):
+    schemaVersion: Literal["2026-10-15-retention.1"]
+    policyVersion: Literal["2026-10-15-retention.1", "historical_preserved"]
+    state: Literal["available", "historical_preserved", "expired", "deletion_pending", "deleted"]
+    payloadExpiresAt: str | None
+    metadataExpiresAt: str | None
+    removalId: str | None
+
+
+class ArtifactReference(TypedDict):
+    id: str
+    name: str
+    kind: Literal["screenshot", "trace", "browser_events", "recording", "file"]
+    mediaType: str
+    bytes: int
+    sha256: str
+    capturedAt: str
+    metadata: dict
+    runId: str
+    attemptId: str
+    state: Literal["pending", "available"]
+    uploadPath: str
+    downloadPath: str
+    metadataOnly: NotRequired[Literal[False]]
+    retention: NotRequired[ArtifactRetention]
+
+
+class UnavailableArtifact(TypedDict):
+    id: str
+    runId: str
+    metadataOnly: Literal[True]
+    retention: ArtifactRetention
+
+
+RetainedArtifact = ArtifactReference | UnavailableArtifact
+
+
+class ArtifactManifest(TypedDict):
+    items: list[RetainedArtifact]
+
+
+class ArtifactContent(TypedDict):
+    artifact: ArtifactReference
+    content: bytes
+
+
+class ArtifactDownload(TypedDict):
+    artifact: ArtifactReference
+    path: str
+    verified: Literal[True]
+
+
+def artifact_path(run_id: str, artifact_id: str | None = None) -> str:
+    if any(not isinstance(value, str) or re.fullmatch(r"[A-Za-z0-9_-]{1,160}", value) is None
+           for value in [run_id] + ([] if artifact_id is None else [artifact_id])):
+        raise FiredrillError("Select an exact retained run and artifact ID", code="ARTIFACT_ID_INVALID",
+                             repair="Use IDs from artifacts(run_id); a URL or local filename is not an artifact ID.")
+    return f"/v1/runs/{run_id}/artifacts" + ("" if artifact_id is None else f"/{artifact_id}")
+
+
+def _retention(value) -> ArtifactRetention | None:
+    if (not isinstance(value, dict) or value.get("schemaVersion") != "2026-10-15-retention.1"
+            or value.get("policyVersion") not in ("2026-10-15-retention.1", "historical_preserved")
+            or value.get("state") not in ("available", "historical_preserved", "expired", "deletion_pending", "deleted")):
+        return None
+    for key in ("payloadExpiresAt", "metadataExpiresAt"):
+        if key not in value:
+            return None
+        if value[key] is not None:
+            if not isinstance(value[key], str) or len(value[key]) > 64:
+                return None
+            try:
+                datetime.fromisoformat(value[key].replace("Z", "+00:00"))
+            except ValueError:
+                return None
+    if "removalId" not in value or value["removalId"] is not None and (not isinstance(value["removalId"], str) or re.fullmatch(r"removal_[a-f0-9]{24}", value["removalId"]) is None):
+        return None
+    return {key: value[key] for key in ArtifactRetention.__annotations__}
+
+
+def _reference(value, run_id, artifact_id=None) -> RetainedArtifact:
+    def invalid():
+        raise FiredrillError("The retained artifact metadata could not be confirmed", code="ARTIFACT_RESPONSE_MISMATCH",
+                             run_id=run_id, repair="Read this same run and artifact again in its original scope. No target is rerun and no file is written.")
+    if not isinstance(value, dict):
+        invalid()
+    if (value.get("runId") != run_id or artifact_id is not None and value.get("id") != artifact_id
+            or not isinstance(value.get("id"), str) or re.fullmatch(r"[A-Za-z0-9_-]{1,160}", value["id"]) is None):
+        invalid()
+    availability = _retention(value.get("retention"))
+    if "retention" in value and availability is None:
+        invalid()
+    if value.get("metadataOnly") is True:
+        if availability is None or availability["state"] not in ("expired", "deletion_pending", "deleted"):
+            invalid()
+        return {"id": value["id"], "runId": run_id, "metadataOnly": True, "retention": availability}
+    if ("metadataOnly" in value and value["metadataOnly"] is not False
+            or availability is not None and availability["state"] not in ("available", "historical_preserved")):
+        invalid()
+    if (value.get("runId") != run_id or artifact_id is not None and value.get("id") != artifact_id
+            or any(not isinstance(value.get(key), str) or re.fullmatch(r"[A-Za-z0-9_-]{1,160}", value[key]) is None for key in ("id", "attemptId"))
+            or not isinstance(value.get("name"), str) or re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._ -]{0,159}", value["name"]) is None
+            or value.get("kind") not in ("screenshot", "trace", "browser_events", "recording", "file")
+            or value.get("mediaType") not in ("image/png", "image/jpeg", "image/webp", "application/zip", "application/json", "text/plain", "video/webm", "text/markdown", "application/pdf", "application/octet-stream")
+            or type(value.get("bytes")) is not int or not 1 <= value["bytes"] <= 16 * 1024 * 1024
+            or not isinstance(value.get("sha256"), str) or re.fullmatch(r"[a-f0-9]{64}", value["sha256"]) is None
+            or not isinstance(value.get("capturedAt"), str) or not isinstance(value.get("metadata"), dict)
+            or value.get("state") not in ("pending", "available")):
+        invalid()
+    path = artifact_path(run_id, value["id"]) + "/content"
+    if value.get("uploadPath") != path or value.get("downloadPath") != path:
+        invalid()
+    return {**{key: value[key] for key in ArtifactReference.__annotations__ if key in value and key != "retention"},
+            **({"retention": availability} if availability is not None else {})}
+
+
+def _read(transport, path):
+    try:
+        return transport.request("GET", path)
+    except TransportError as error:
+        error.repair = "Retry this same retained artifact read. It does not execute a target or request evaluation."
+        raise
+
+
+def artifacts(transport, run_id: str) -> ArtifactManifest:
+    value = _read(transport, artifact_path(run_id))
+    if not isinstance(value, dict) or not isinstance(value.get("items"), list) or len(value["items"]) > 128:
+        raise FiredrillError("The artifact manifest is not a bounded retained listing", code="ARTIFACT_RESPONSE_MISMATCH", run_id=run_id)
+    items = [_reference(item, run_id) for item in value["items"]]
+    if len({item["id"] for item in items}) != len(items):
+        raise FiredrillError("The artifact manifest repeats an identity", code="ARTIFACT_RESPONSE_MISMATCH", run_id=run_id)
+    return {"items": items}
+
+
+def artifact_content(transport, run_id: str, artifact_id: str) -> ArtifactContent:
+    path = artifact_path(run_id, artifact_id)
+    artifact = _reference(_read(transport, path), run_id, artifact_id)
+    if artifact.get("metadataOnly") is True:
+        raise FiredrillError(f"The capture is {artifact['retention']['state']}; only its history remains", code="ARTIFACT_UNAVAILABLE", run_id=run_id,
+                             repair="Inspect retained metadata. Do not recreate removed evidence by rerunning the target.")
+    if artifact["state"] != "available":
+        raise FiredrillError("This capture has not finished uploading", code="ARTIFACT_PENDING", run_id=run_id,
+                             repair="Inspect the original run or let its runner reconcile the pending upload. Do not repeat the target to create replacement evidence.")
+    content, media_type = transport.download(path + "/content", artifact["bytes"])
+    if (len(content) != artifact["bytes"] or hashlib.sha256(content).hexdigest() != artifact["sha256"]
+            or not isinstance(media_type, str) or media_type.split(";", 1)[0].strip().lower() != artifact["mediaType"]):
+        raise FiredrillError("Downloaded evidence does not match its retained size, digest or media type", code="ARTIFACT_CONTENT_MISMATCH",
+                             run_id=run_id, repair="Read the same retained artifact again. Unverified bytes are not returned or written; the target is not rerun.")
+    return {"artifact": artifact, "content": content}
+
+
+def download_artifact(transport, run_id: str, artifact_id: str, output: str | Path) -> ArtifactDownload:
+    if not isinstance(output, (str, Path)) or not str(output).strip() or "\0" in str(output):
+        raise FiredrillError("Choose an explicit new local file for this capture", code="ARTIFACT_OUTPUT_INVALID",
+                             repair="Use an existing output directory and a new filename. Existing files are never overwritten.")
+    value = artifact_content(transport, run_id, artifact_id)
+    path = Path(os.path.abspath(output))
+    temporary = path.parent / (".firedrill-artifact-" + str(uuid.uuid4()))
+    created = False
+    try:
+        fd = os.open(temporary, os.O_CREAT | os.O_EXCL | os.O_WRONLY | os.O_NOFOLLOW, 0o600)
+        created = True
+        with os.fdopen(fd, "wb") as file:
+            file.write(value["content"])
+            file.flush()
+            os.fsync(file.fileno())
+        os.link(temporary, path)  # Publish atomically without replacing a file or symlink.
+        return {"artifact": value["artifact"], "path": str(path), "verified": True}
+    except OSError:
+        raise FiredrillError("The verified capture could not be saved to that new path", code="ARTIFACT_OUTPUT_UNAVAILABLE",
+                             run_id=run_id, repair="Choose a new filename in an existing writable directory. Existing files are preserved; downloading again never executes the target.") from None
+    finally:
+        if created:
+            try:
+                temporary.unlink()
+            except OSError:
+                pass  # A filesystem failure can leave only the private staging file.

firedrill/attachments.py

@@ -0,0 +1,167 @@
+"""Journaled artifact transport; captures remain customer-runner evidence.
+
+Wire fields and recovery ordering follow the root-owned Artifact contract and
+the sibling TypeScript attachment coordinator; this is a native Python adapter.
+"""
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import stat
+import uuid
+
+from .errors import FiredrillError, RecoveryRequired
+from .models import json_bytes
+from .transport import segment
+
+
+def metadata(value):
+    def require(condition):
+        if not condition:
+            raise ValueError("Invalid artifact field")
+
+    try:
+        item = json.loads(json_bytes(value))
+        required = {"id", "name", "kind", "mediaType", "bytes", "sha256", "capturedAt"}
+        require(isinstance(item, dict) and required <= item.keys() and not item.keys() - required - {"metadata"})
+        require(re.fullmatch(r"[a-zA-Z0-9_-]{1,160}", item["id"]))
+        require(re.fullmatch(r"[a-zA-Z0-9][a-zA-Z0-9._ -]{0,159}", item["name"]))
+        require(item["kind"] in {"screenshot", "trace", "browser_events", "recording", "file"})
+        require(item["mediaType"] in {"image/png", "image/jpeg", "image/webp", "application/zip", "application/json", "text/plain", "video/webm", "text/markdown", "application/pdf", "application/octet-stream"})
+        require(type(item["bytes"]) is int and 1 <= item["bytes"] <= 16 * 1024 * 1024)
+        require(re.fullmatch(r"[a-f0-9]{64}", item["sha256"]))
+        require(re.fullmatch(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z", item["capturedAt"]))
+        datetime.fromisoformat(item["capturedAt"].replace("Z", "+00:00"))
+        item.setdefault("metadata", {})
+        require(isinstance(item["metadata"], dict) and len(json_bytes(item["metadata"])) <= 16384)
+        return item
+    except (ValueError, TypeError, KeyError, OverflowError):
+        raise FiredrillError("Attachment metadata does not satisfy the artifact contract", code="ARTIFACT_INVALID",
+                             repair="Use supported media, bounded size, SHA-256, UTC capturedAt and a stable artifact ID.") from None
+
+
+def private_bytes(intent):
+    try:
+        fd = os.open(intent["path"], os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0))
+        with os.fdopen(fd, "rb") as stream:
+            info = os.fstat(stream.fileno())
+            if (not stat.S_ISREG(info.st_mode) or info.st_nlink != 1 or info.st_mode & 0o077
+                    or info.st_size != intent["artifact"]["bytes"] or info.st_size > 16 * 1024 * 1024
+                    or (hasattr(os, "getuid") and info.st_uid != os.getuid())):
+                raise OSError("Unsafe file")
+            content = stream.read(16 * 1024 * 1024 + 1)
+    except OSError:
+        raise FiredrillError("Attachment is not the expected private regular file", code="ARTIFACT_FILE_UNSAFE",
+                             repair="Preserve the capture; use a current-user-owned 0600 file without links.") from None
+    if len(content) != intent["artifact"]["bytes"] or hashlib.sha256(content).hexdigest() != intent["artifact"]["sha256"]:
+        raise FiredrillError("Attachment bytes changed from their saved digest", code="ARTIFACT_CONTENT_CHANGED",
+                             repair="Restore the exact original bytes; never replace evidence under an existing ID.")
+    return content
+
+
+class AttachmentCoordinator:
+    def __init__(self, entry, save, transport):
+        self.entry, self.save, self.transport = entry, save, transport
+        self.loop = asyncio.get_running_loop()
+        self.lock = asyncio.Lock()
+
+    def _active_invocation(self):
+        if self.entry["phase"] == "running":
+            return "single"
+        step = self.entry.get("sequenceStep", {})
+        if self.entry["phase"] == "sequence" and step.get("phase") == "running":
+            return ("sequence", step["ordinal"])
+        return None
+
+    def for_callback(self, value):
+        """Sync native threads block; async callbacks await on their owning loop."""
+        try:
+            running = asyncio.get_running_loop()
+        except RuntimeError:
+            running = None
+        if running is self.loop:
+            return self.attach(value)
+        if self.loop.is_closed() or not self.loop.is_running():
+            raise FiredrillError("Attachment runner lifecycle ended", code="ARTIFACT_LEASE_INACTIVE")
+        return asyncio.run_coroutine_threadsafe(self.attach(value), self.loop).result()
+
+    async def attach(self, value):
+        async with self.lock:
+            invocation = self._active_invocation()
+            if invocation is None or not self.entry.get("claim", {}).get("leaseToken"):
+                raise FiredrillError("Attachments require the invocation's active lifecycle", code="ARTIFACT_LEASE_INACTIVE",
+                                     repair="Complete context.attach inside the callback before it returns.")
+            if not isinstance(value, dict) or set(value) != {"path", "artifact"}:
+                raise FiredrillError("Use context.attach({path, artifact})", code="ARTIFACT_INVALID")
+            artifact = metadata(value["artifact"])
+            intents = self.entry.setdefault("attachments", [])
+            intent = next((item for item in intents if item["artifact"]["id"] == artifact["id"]), None)
+            if intent and intent["artifact"] != artifact:
+                raise FiredrillError("Artifact ID already describes different evidence", code="ARTIFACT_ID_CONFLICT",
+                                     repair="Use its original metadata and capture; new evidence needs a new ID.")
+            if intent is None:
+                intent = {"path": str(Path(value["path"]).expanduser().absolute()), "artifact": artifact,
+                          "key": str(uuid.uuid4()), "state": "pending"}
+                await asyncio.to_thread(private_bytes, intent)
+                # Lifecycle may have ended while the file was checked.
+                if self._active_invocation() != invocation:
+                    raise FiredrillError("Attachment runner lifecycle ended", code="ARTIFACT_LEASE_INACTIVE")
+                intents.append(intent)
+                self.save()  # Durable exact content/key intent precedes either network write.
+            return await self._upload(intent)
+
+    def _checked(self, ref, intent):
+        claim = self.entry["claim"]
+        if (not isinstance(ref, dict) or ref.get("runId") != claim["run"]["id"]
+                or ref.get("attemptId") != claim["attemptId"]
+                or any(ref.get(key) != value for key, value in intent["artifact"].items())):
+            raise FiredrillError("Attachment acknowledgement mismatches exact run, attempt or content",
+                                 code="ARTIFACT_RESPONSE_MISMATCH", repair="Preserve the journal; do not rerun the target.")
+        return ref
+
+    async def _upload(self, intent):
+        if intent["state"] == "available" and intent.get("retained"):
+            return json.loads(json_bytes(intent["retained"]))
+        claim = self.entry["claim"]
+        route = f"/v1/runs/{segment(claim['run']['id'])}/artifacts"
+        phase = "declaration"
+        try:
+            content = await asyncio.to_thread(private_bytes, intent)
+            ref = self._checked(await asyncio.to_thread(self.transport.request, "POST", route,
+                                {"attemptId": claim["attemptId"], "leaseToken": claim["leaseToken"], "artifact": intent["artifact"]}, intent["key"]), intent)
+            if ref["state"] != "available":
+                phase = "upload"
+                ref = self._checked(await asyncio.to_thread(self.transport.upload,
+                                    route + f"/{segment(intent['artifact']['id'])}/content", content,
+                                    intent["artifact"]["mediaType"], claim["attemptId"], claim["leaseToken"]), intent)
+            if ref["state"] != "available":
+                raise ValueError("Upload not confirmed")
+            intent.update(state="available", retained=ref)
+            self.save()
+            return json.loads(json_bytes(ref))
+        except Exception as exc:
+            if isinstance(exc, FiredrillError) and exc.code in {"ARTIFACT_FILE_UNSAFE", "ARTIFACT_CONTENT_CHANGED", "ARTIFACT_RESPONSE_MISMATCH"}:
+                self.save()
+                raise
+            cause = exc.code if isinstance(exc, FiredrillError) else "transport_uncertain"
+            request_id = getattr(exc, "request_id", None)
+            if not isinstance(request_id, str) or not re.fullmatch(r"[A-Za-z0-9_-]{1,160}", request_id):
+                request_id = None
+            failure = RecoveryRequired("Artifact upload acknowledgement is unconfirmed; exact intent and capture were preserved",
+                                       code="ARTIFACT_UPLOAD_PENDING", request_id=request_id,
+                                       status=getattr(exc, "status", None), cause_code=cause, phase=phase,
+                                       repair="Resume the saved operation while its lease is active. Preserve the original capture; never rerun the target to recover an attachment.")
+            intent["lastFailure"] = {name: value for name, value in failure.to_dict()["error"].items()
+                                     if name in ("causeCode", "status", "phase", "requestId")}
+            self.save()
+            raise failure from None
+
+    async def reconcile(self):
+        async with self.lock:
+            for intent in self.entry.get("attachments", []):
+                await self._upload(intent)