simulo-interfaces 0.14.0__tar.gz → 0.16.0__tar.gz

{simulo_interfaces-0.14.0 → simulo_interfaces-0.16.0}/MANIFEST.in

@@ -1,4 +1,4 @@
-# Public-metadata discretion boundary (see release.yml Guard 5): the sdist is
+# Public-metadata discretion boundary (see release-pypi.yml Guard 5): the sdist is
 # PUBLIC on PyPI's "Download files" page just like the wheel, but setuptools'
 # sdist command auto-includes README.md and any top-level tests/ directory
 # regardless of the `readme = "PYPI.md"` pyproject setting. Exclude the

{simulo_interfaces-0.14.0/src/simulo_interfaces.egg-info → simulo_interfaces-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo-interfaces
-Version: 0.14.0
+Version: 0.16.0
 Summary: Type contracts for the Simulo SDK. Installed automatically as a dependency of the simulo package.
 Author-email: Simulo Team <team@simulo.ai>
 License: BSD-3-Clause

{simulo_interfaces-0.14.0 → simulo_interfaces-0.16.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo-interfaces"
-version = "0.14.0"
+version = "0.16.0"
 description = "Type contracts for the Simulo SDK. Installed automatically as a dependency of the simulo package."
 readme = "PYPI.md"
 requires-python = ">=3.11"

{simulo_interfaces-0.14.0 → simulo_interfaces-0.16.0}/src/simulo/interfaces/__init__.py

@@ -31,13 +31,21 @@ from simulo.interfaces.ids import (
     CheckpointId,
     Digest,
     JobId,
+    JobPublicId,
+    ModelPublicId,
     OrganizationId,
+    OutputPublicId,
     PackageId,
     ProjectId,
+    RecordingPublicId,
     ResourceId,
     ResourceUri,
     TagId,
     TrainedModelId,
+    parse_job_public_id,
+    parse_model_public_id,
+    parse_output_public_id,
+    parse_recording_public_id,
 )
 
 __all__ = [
@@ -56,6 +64,14 @@ __all__ = [
     "ProjectId",
     "PackageId",
     "JobId",
+    "JobPublicId",
+    "ModelPublicId",
+    "RecordingPublicId",
+    "OutputPublicId",
+    "parse_job_public_id",
+    "parse_model_public_id",
+    "parse_recording_public_id",
+    "parse_output_public_id",
     "ResourceId",
     "CheckpointId",
     "TrainedModelId",

simulo_interfaces-0.16.0/src/simulo/interfaces/ids.py

@@ -0,0 +1,135 @@
+"""Strongly-typed string identifiers for the platform domain model (Part B).
+
+``NewType`` aliases — zero runtime cost (each is the underlying ``str`` at
+runtime) but distinct to the type checker, so a ``ProjectId`` can never be
+passed where a ``JobId`` is expected.
+
+The ``*PublicId`` aliases identify the human-facing, grammar-validated
+references carried in response ``public_id`` fields.  Their parsers normalize
+only outer ASCII whitespace and ASCII letter case; Unicode whitespace, Unicode
+case folding, wildcard syntax, and partial identifiers are deliberately not
+accepted.
+"""
+
+import re
+from typing import NewType
+
+OrganizationId = NewType("OrganizationId", str)
+ProjectId = NewType("ProjectId", str)
+PackageId = NewType("PackageId", str)
+JobId = NewType("JobId", str)
+ResourceId = NewType("ResourceId", str)
+CheckpointId = NewType("CheckpointId", str)
+TrainedModelId = NewType("TrainedModelId", str)
+TagId = NewType("TagId", str)
+ResourceUri = NewType("ResourceUri", str)  # e.g. "robot/so-arm-100:v3"
+Digest = NewType("Digest", str)  # content-addressed package source digest
+RecordingId = NewType("RecordingId", str)  # a job-produced MCAP recording (PR-0 wire contract)
+WorkerId = NewType("WorkerId", str)  # a claiming worker process (PR-0 wire contract)
+AssetId = NewType("AssetId", str)  # a catalog asset (USD Asset Catalogs wire contract, PR-1)
+AssetVersionId = NewType("AssetVersionId", str)  # one immutable asset version (PR-1)
+OutputId = NewType("OutputId", str)  # a job-produced output in the /outputs projection (Plan B)
+
+JobPublicId = NewType("JobPublicId", str)
+ModelPublicId = NewType("ModelPublicId", str)
+RecordingPublicId = NewType("RecordingPublicId", str)
+OutputPublicId = NewType("OutputPublicId", str)
+
+_ASCII_WHITESPACE = " \t\n\r\v\f"
+_ASCII_LOWERCASE_TRANSLATION = str.maketrans(
+    "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
+    "abcdefghijklmnopqrstuvwxyz",
+)
+_JOB_STEM_PATTERN = r"[a-z]{3,10}-[a-z]{3,10}-[0-9a-hjkmnp-tv-z]{6}"
+_CANONICAL_CHILD_COUNTER_PATTERN = r"(?:(?!0000)[0-9]{4}|[1-9][0-9]{4,})"
+_JOB_PUBLIC_ID_RE = re.compile(rf"job_{_JOB_STEM_PATTERN}\Z")
+_MODEL_PUBLIC_ID_RE = re.compile(rf"mdl_{_JOB_STEM_PATTERN}-{_CANONICAL_CHILD_COUNTER_PATTERN}\Z")
+_RECORDING_PUBLIC_ID_RE = re.compile(rf"rec_{_JOB_STEM_PATTERN}-{_CANONICAL_CHILD_COUNTER_PATTERN}\Z")
+_OUTPUT_PUBLIC_ID_RE = re.compile(rf"out_{_JOB_STEM_PATTERN}-{_CANONICAL_CHILD_COUNTER_PATTERN}\Z")
+_MAX_JOB_PUBLIC_ID_LENGTH = 32
+_MAX_CHILD_PUBLIC_ID_LENGTH = 64
+
+
+def _normalize_public_id(value: str, *, parser: str) -> str:
+    if not isinstance(value, str):
+        raise TypeError(f"{parser}() requires a str, got {type(value).__name__}.")
+    return value.strip(_ASCII_WHITESPACE).translate(_ASCII_LOWERCASE_TRANSLATION)
+
+
+def _parse_public_id(value: str, *, parser: str, pattern: re.Pattern[str], max_length: int) -> str:
+    normalized = _normalize_public_id(value, parser=parser)
+    if len(normalized) > max_length or pattern.fullmatch(normalized) is None:
+        raise ValueError(f"{parser}() received a non-canonical public ID.")
+    return normalized
+
+
+def parse_job_public_id(value: str) -> JobPublicId:
+    """Return a canonical Job ID such as ``job_quiet-cedar-7k3m4q``.
+
+    Only outer ASCII whitespace is trimmed and only ASCII ``A-Z`` is
+    lowercased. Matching is exact: prefixes, partial values, wildcards, and
+    non-ASCII input are rejected.
+    """
+
+    return JobPublicId(
+        _parse_public_id(
+            value,
+            parser="parse_job_public_id",
+            pattern=_JOB_PUBLIC_ID_RE,
+            max_length=_MAX_JOB_PUBLIC_ID_LENGTH,
+        )
+    )
+
+
+def parse_model_public_id(value: str) -> ModelPublicId:
+    """Return a canonical Model ID such as ``mdl_quiet-cedar-7k3m4q-0001``.
+
+    Only outer ASCII whitespace is trimmed and only ASCII ``A-Z`` is
+    lowercased. Matching is exact and non-ASCII input is rejected. Counters
+    use exactly four digits through ``9999`` and expand unpadded at ``10000``.
+    """
+
+    return ModelPublicId(
+        _parse_public_id(
+            value,
+            parser="parse_model_public_id",
+            pattern=_MODEL_PUBLIC_ID_RE,
+            max_length=_MAX_CHILD_PUBLIC_ID_LENGTH,
+        )
+    )
+
+
+def parse_recording_public_id(value: str) -> RecordingPublicId:
+    """Return a Recording ID such as ``rec_quiet-cedar-7k3m4q-0001``.
+
+    Only outer ASCII whitespace is trimmed and only ASCII ``A-Z`` is
+    lowercased. Matching is exact and non-ASCII input is rejected. Counters
+    use exactly four digits through ``9999`` and expand unpadded at ``10000``.
+    """
+
+    return RecordingPublicId(
+        _parse_public_id(
+            value,
+            parser="parse_recording_public_id",
+            pattern=_RECORDING_PUBLIC_ID_RE,
+            max_length=_MAX_CHILD_PUBLIC_ID_LENGTH,
+        )
+    )
+
+
+def parse_output_public_id(value: str) -> OutputPublicId:
+    """Return an Output ID such as ``out_quiet-cedar-7k3m4q-0001``.
+
+    Only outer ASCII whitespace is trimmed and only ASCII ``A-Z`` is
+    lowercased. Matching is exact and non-ASCII input is rejected. Counters
+    use exactly four digits through ``9999`` and expand unpadded at ``10000``.
+    """
+
+    return OutputPublicId(
+        _parse_public_id(
+            value,
+            parser="parse_output_public_id",
+            pattern=_OUTPUT_PUBLIC_ID_RE,
+            max_length=_MAX_CHILD_PUBLIC_ID_LENGTH,
+        )
+    )

{simulo_interfaces-0.14.0 → simulo_interfaces-0.16.0}/src/simulo/interfaces/platform/__init__.py

@@ -7,27 +7,6 @@ implementation-free — concrete behaviour lives in the future
 ``simulo`` client and the ``simulo-backend`` SDK.
 """
 
-from simulo.interfaces.platform.artifacts import (
-    DECLARED_OUTPUT_MISSING_CODE,
-    JOB_ARTIFACT_DOWNLOAD_ROUTE_TEMPLATE,
-    JOB_ARTIFACTS_ROUTE_TEMPLATE,
-    MAX_ARTIFACT_NAME_BYTES,
-    MAX_ARTIFACT_PATH_BYTES,
-    MAX_OUTPUT_FLAG_CODE_CHARS,
-    MAX_OUTPUT_FLAG_DETAIL_CHARS,
-    MAX_OUTPUTS_BYTES,
-    OUTPUT_DROPPED_DETAILS,
-    OUTPUT_FLAG_ANOMALY,
-    OUTPUT_FLAG_OUTPUT_DROPPED,
-    OUTPUTS_UNDELIVERED_CODE,
-    WORKER_JOB_ARTIFACTS_PRESIGN_ROUTE_TEMPLATE,
-    WORKER_JOB_ARTIFACTS_ROUTE_TEMPLATE,
-    Artifact,
-    ArtifactDeclaration,
-    ArtifactRecord,
-    JobOutputsSummary,
-    OutputFlag,
-)
 from simulo.interfaces.platform.asset import AssetProtocol
 from simulo.interfaces.platform.asset_catalog import (
     ADMIN_ASSET_ROUTE_TEMPLATE,
@@ -99,7 +78,35 @@ from simulo.interfaces.platform.asset_catalog import (
 from simulo.interfaces.platform.callbacks import JobCallbackProtocol
 from simulo.interfaces.platform.debug import DebugSessionProtocol, ReplaySessionProtocol, VisualizationSessionProtocol
 from simulo.interfaces.platform.domain import Checkpoint, Job, Package, Project, Resource, Tag, TrainedModel
-from simulo.interfaces.platform.enums import ArtifactKind
+from simulo.interfaces.platform.enums import OutputKind
+from simulo.interfaces.platform.job_events import (
+    MAX_PUBLIC_ASSET_FINDING_COUNT,
+    MAX_PUBLIC_JOB_EVENT_ATTEMPT,
+    MAX_PUBLIC_JOB_EVENT_BYTES,
+    MAX_PUBLIC_JOB_EVENT_ENTRIES,
+    MAX_PUBLIC_JOB_EVENT_QUIET_SECONDS,
+    MAX_PUBLIC_JOB_EVENT_WIRE_BYTES,
+    PUBLIC_JOB_EVENT_ATTEMPT_MISMATCH_CODE,
+    PUBLIC_JOB_EVENT_OFFSET_CONFLICT_CODE,
+    PUBLIC_JOB_EVENT_OFFSET_GAP_CODE,
+    PUBLIC_JOB_EVENT_SCHEMA_VERSION,
+    PUBLIC_JOB_SUPPORT_ID_HEX_CHARS,
+    PUBLIC_JOB_SUPPORT_ID_PREFIX,
+    WORKER_JOB_EVENTS_ROUTE_TEMPLATE,
+    JobAssetFindingData,
+    JobAssetFindingEvent,
+    JobPreparingData,
+    JobPreparingEvent,
+    JobRunningData,
+    JobRunningEvent,
+    JobStillWorkingData,
+    JobStillWorkingEvent,
+    PublicAssetFindingReason,
+    PublicJobEvent,
+    PublicJobEventCode,
+    PublicJobEventSeverity,
+    PublicJobPreparationPhase,
+)
 from simulo.interfaces.platform.manifest import (
     FINDING_CLASSIFICATIONS,
     MAX_PREFLIGHT_BODY_BYTES,
@@ -112,6 +119,27 @@ from simulo.interfaces.platform.manifest import (
     PreflightResponse,
     RuntimeManifest,
 )
+from simulo.interfaces.platform.outputs import (
+    DECLARED_OUTPUT_MISSING_CODE,
+    JOB_OUTPUT_DOWNLOAD_ROUTE_TEMPLATE,
+    JOB_OUTPUTS_ROUTE_TEMPLATE,
+    MAX_OUTPUT_FLAG_CODE_CHARS,
+    MAX_OUTPUT_FLAG_DETAIL_CHARS,
+    MAX_OUTPUT_NAME_BYTES,
+    MAX_OUTPUT_PATH_BYTES,
+    MAX_OUTPUTS_BYTES,
+    OUTPUT_DROPPED_DETAILS,
+    OUTPUT_FLAG_ANOMALY,
+    OUTPUT_FLAG_OUTPUT_DROPPED,
+    OUTPUTS_UNDELIVERED_CODE,
+    WORKER_JOB_ARTIFACTS_PRESIGN_ROUTE_TEMPLATE,
+    WORKER_JOB_ARTIFACTS_ROUTE_TEMPLATE,
+    JobOutputsSummary,
+    Output,
+    OutputDeclaration,
+    OutputFlag,
+    OutputRecord,
+)
 from simulo.interfaces.platform.policy_bundle import (
     EXPORT_VALIDATION_JOB_TYPE,
     JOB_EXPORTS_ROUTE_TEMPLATE,
@@ -119,7 +147,6 @@ from simulo.interfaces.platform.policy_bundle import (
     MAX_POLICY_NAME_TOKEN_CHARS,
     POLICY_BUNDLE_ACTION_SCHEMA_FILE,
     POLICY_BUNDLE_ARCHIVE_NAME_TEMPLATE,
-    POLICY_BUNDLE_ARTIFACT_KIND,
     POLICY_BUNDLE_FILES,
     POLICY_BUNDLE_MANIFEST_FILE,
     POLICY_BUNDLE_MODEL_ONNX_FILE,
@@ -127,6 +154,7 @@ from simulo.interfaces.platform.policy_bundle import (
     POLICY_BUNDLE_NORMALIZATION_FILE,
     POLICY_BUNDLE_OBSERVATION_SCHEMA_FILE,
     POLICY_BUNDLE_OPTIONAL_FILES,
+    POLICY_BUNDLE_OUTPUT_KIND,
     POLICY_BUNDLE_README_FILE,
     POLICY_BUNDLE_REQUIRED_FILES,
     POLICY_BUNDLE_REQUIREMENTS_FILE,
@@ -220,7 +248,34 @@ from simulo.interfaces.platform.volume import VolumeProtocol
 
 __all__ = [
     # enums
-    "ArtifactKind",
+    "OutputKind",
+    # closed public job-event contract (#656)
+    "PUBLIC_JOB_EVENT_SCHEMA_VERSION",
+    "WORKER_JOB_EVENTS_ROUTE_TEMPLATE",
+    "MAX_PUBLIC_JOB_EVENT_BYTES",
+    "MAX_PUBLIC_JOB_EVENT_WIRE_BYTES",
+    "MAX_PUBLIC_JOB_EVENT_ENTRIES",
+    "MAX_PUBLIC_JOB_EVENT_ATTEMPT",
+    "MAX_PUBLIC_JOB_EVENT_QUIET_SECONDS",
+    "MAX_PUBLIC_ASSET_FINDING_COUNT",
+    "PUBLIC_JOB_SUPPORT_ID_PREFIX",
+    "PUBLIC_JOB_SUPPORT_ID_HEX_CHARS",
+    "PUBLIC_JOB_EVENT_OFFSET_GAP_CODE",
+    "PUBLIC_JOB_EVENT_OFFSET_CONFLICT_CODE",
+    "PUBLIC_JOB_EVENT_ATTEMPT_MISMATCH_CODE",
+    "PublicJobEventSeverity",
+    "PublicJobEventCode",
+    "PublicJobPreparationPhase",
+    "PublicAssetFindingReason",
+    "JobPreparingData",
+    "JobRunningData",
+    "JobStillWorkingData",
+    "JobAssetFindingData",
+    "JobPreparingEvent",
+    "JobRunningEvent",
+    "JobStillWorkingEvent",
+    "JobAssetFindingEvent",
+    "PublicJobEvent",
     # domain dataclasses
     "Tag",
     "Project",
@@ -243,18 +298,18 @@ __all__ = [
     # typed job outputs (Plan B, #531) — pre-run declaration, execution-time
     # registration, projection row, completion announcement, routes, caps,
     # pinned wire codes
-    "ArtifactDeclaration",
-    "Artifact",
-    "ArtifactRecord",
+    "OutputDeclaration",
+    "Output",
+    "OutputRecord",
     "OutputFlag",
     "JobOutputsSummary",
-    "JOB_ARTIFACTS_ROUTE_TEMPLATE",
-    "JOB_ARTIFACT_DOWNLOAD_ROUTE_TEMPLATE",
+    "JOB_OUTPUTS_ROUTE_TEMPLATE",
+    "JOB_OUTPUT_DOWNLOAD_ROUTE_TEMPLATE",
     "WORKER_JOB_ARTIFACTS_PRESIGN_ROUTE_TEMPLATE",
     "WORKER_JOB_ARTIFACTS_ROUTE_TEMPLATE",
     "MAX_OUTPUTS_BYTES",
-    "MAX_ARTIFACT_NAME_BYTES",
-    "MAX_ARTIFACT_PATH_BYTES",
+    "MAX_OUTPUT_NAME_BYTES",
+    "MAX_OUTPUT_PATH_BYTES",
     "MAX_OUTPUT_FLAG_CODE_CHARS",
     "MAX_OUTPUT_FLAG_DETAIL_CHARS",
     "OUTPUT_FLAG_ANOMALY",
@@ -406,7 +461,7 @@ __all__ = [
     "MAX_POLICY_BUNDLE_UNCOMPRESSED_BYTES",
     "POLICY_TEST_VECTOR_INPUTS_KEY",
     "POLICY_TEST_VECTOR_EXPECTED_OUTPUTS_KEY",
-    "POLICY_BUNDLE_ARTIFACT_KIND",
+    "POLICY_BUNDLE_OUTPUT_KIND",
     "POLICY_BUNDLE_ROOT_DIR_TEMPLATE",
     "POLICY_BUNDLE_ARCHIVE_NAME_TEMPLATE",
     "MAX_POLICY_NAME_TOKEN_CHARS",

simulo_interfaces-0.16.0/src/simulo/interfaces/platform/_payload.py

@@ -0,0 +1,15 @@
+"""Internal helpers for tolerant response-record reconstruction."""
+
+from collections.abc import Mapping
+from dataclasses import fields
+from typing import Any
+
+
+def known_payload_fields(record_type: Any, payload: Mapping[str, Any], *, owner: str) -> dict[str, Any]:
+    """Copy only fields declared by ``record_type`` from one response mapping."""
+
+    if not isinstance(payload, Mapping):
+        raise TypeError(f"{owner} requires a mapping, got {type(payload).__name__}.")
+    return {
+        definition.name: payload[definition.name] for definition in fields(record_type) if definition.name in payload
+    }

{simulo_interfaces-0.14.0 → simulo_interfaces-0.16.0}/src/simulo/interfaces/platform/asset_catalog.py

@@ -248,7 +248,7 @@ GLOBAL_ASSET_PUBLISHER = "simulo"
 #: (``^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])?$``, 3–63 chars): this pattern accepts
 #: **1–63** chars of lowercase letters/digits/hyphens, starting and ending with a
 #: letter or digit. The CP org-slug pattern's *effective* 3-char floor is an
-#: artifact of ``derive_slug()`` padding a short org NAME at derivation time
+#: output of ``derive_slug()`` padding a short org NAME at derivation time
 #: (``users/slug.py``: ``if len(s) < 3: s = s + "org"``), not a validation rule —
 #: short names like ``h1`` or ``go2`` are legitimate robot/world asset names and
 #: must validate. (An earlier draft of this pattern used the CP's own ``{1,61}``
@@ -689,7 +689,7 @@ ASSET_MISSING_CODE = "asset_missing"
 #: The ``jobs.job_type`` value of a platform-internal asset-validation job
 #: (PR-11 amendment, 2026-07-17). The claim response's job record carries a
 #: ``job_type`` field (additive; absent against a pre-PR-11 control plane) and
-#: the worker keys its artifact-pickup branch on THIS exact string: a claimed
+#: the worker keys its output-pickup branch on THIS exact string: a claimed
 #: job of this type has its run-dir validation outputs picked up and finalized
 #: against :data:`WORKER_JOB_ASSET_VALIDATION_ROUTE_TEMPLATE` after execution.
 #: Mirrors the control plane's ``assets/constants.py::ASSET_VALIDATION_JOB_TYPE``

{simulo_interfaces-0.14.0 → simulo_interfaces-0.16.0}/src/simulo/interfaces/platform/domain.py

@@ -12,7 +12,7 @@ Domain invariants encoded here:
 * ``Resource`` is a read-only, versioned, registry-resolved mount
   (robot / environment / dataset / …); it is NOT a package.
 * ``Project`` is the workspace anchor every other object hangs off.
-* ``Checkpoint`` (intermediate training artifact) and
+* ``Checkpoint`` (intermediate training output) and
   ``TrainedModel`` (final, deployable model) are separate types — never collapse.
 """
 
@@ -97,7 +97,7 @@ class Job:
 
 @dataclass(**_DC)
 class Checkpoint:
-    """Intermediate training artifact (Rule #8) — distinct from a TrainedModel."""
+    """Intermediate training output (Rule #8) — distinct from a TrainedModel."""
 
     id: CheckpointId
     job_id: JobId
@@ -108,7 +108,7 @@ class Checkpoint:
 
 @dataclass(**_DC)
 class TrainedModel:
-    """Final, deployable model artifact (Rule #8) — distinct from a Checkpoint."""
+    """Final, deployable model output (Rule #8) — distinct from a Checkpoint."""
 
     id: TrainedModelId
     project_id: ProjectId

{simulo_interfaces-0.14.0 → simulo_interfaces-0.16.0}/src/simulo/interfaces/platform/enums.py

@@ -22,7 +22,7 @@ class JobStatus(StrEnum):
     """Claimed by a worker and executing."""
 
     COMPLETED = "completed"
-    """Finished successfully — the result and artifacts are available."""
+    """Finished successfully — the result and outputs are available."""
 
     FAILED = "failed"
     """Finished unsuccessfully — see the job's logs for the failure."""
@@ -80,14 +80,14 @@ class ResourceKind(StrEnum):
     """
 
 
-class ArtifactKind(StrEnum):
-    """Kind of a job-produced artifact — a checkpoint is NOT a trained model.
+class OutputKind(StrEnum):
+    """Kind of a job-produced output — a checkpoint is NOT a trained model.
 
     Checkpoints are resumable training state; trained models are standalone,
-    deployable policy artifacts. The platform never conflates the two.
+    deployable policy outputs. The platform never conflates the two.
 
     Values are a stable wire ABI persisted in database rows (``job_recordings
-    .kind``, ``job_artifacts.kind``) and served by the ``/artifacts`` union
+    .kind``, ``job_artifacts.kind``) and served by the ``/outputs`` union
     projection: **append-only, never renumber, rename, or reorder** — the six
     members up to ``EVALUATION_OUTPUT`` predate the typed-outputs contract
     and every member added for the typed-outputs contract is appended after them.
@@ -100,7 +100,7 @@ class ArtifactKind(StrEnum):
     callback."""
 
     TRAINED_MODEL = "trained_model"
-    """A standalone, deployable policy artifact — for inference/playback."""
+    """A standalone, deployable policy output — for inference/playback."""
 
     LOG = "log"
     """The job's captured log stream."""
@@ -173,5 +173,8 @@ class ArtifactKind(StrEnum):
 
     FILE = "file"
     """A general produced file. This is the default kind used by
-    ``simulo.save_artifact``. The current managed platform records the
-    registration but does not publish general files for download."""
+    ``simulo.save_output``. After a successful job completes, the worker
+    uploads eligible registrations to ``job_artifacts``; persisted files are
+    listed by the external ``/outputs`` projection and can be downloaded.
+    Registration alone does not guarantee delivery on a failed run or when an
+    upload is refused."""