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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo-interfaces
-Version: 0.12.0
+Version: 0.14.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.12.0 → simulo_interfaces-0.14.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo-interfaces"
-version = "0.12.0"
+version = "0.14.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.12.0 → simulo_interfaces-0.14.0}/src/simulo/interfaces/authoring/record.py

@@ -88,10 +88,10 @@ ProfileName = Literal["core", "standard", "full"]
 VALID_PROFILES: Tuple[str, ...] = ("core", "standard", "full")
 
 # Profile defaults table. Each profile lists ONLY the fields it turns on; any
-# field absent from a profile's dict defaults to False. SRD §10.1 mandates
+# field absent from a profile's dict defaults to False. MCAP recording mandates
 # Phase 1 robot/contact/sensor/video stay off; the `full` row below holds the
 # line by not enabling those streams in Phase 1. Wave 2 may flip them on
-# (plan §6 Wave 2 task F) — that edit is intentionally scoped to this table.
+# when enabled — that edit is intentionally scoped to this table.
 #
 # Wave Policy-Eval-Completeness (2026-06-21) — three changes to defaults:
 #
@@ -161,7 +161,7 @@ _PROFILE_DEFAULTS: Dict[str, Dict[str, bool]] = {
         "include_terminations": True,
         "include_events": True,
         # Wave 2 — Phase 2 streams enabled in the `full` profile per plan
-        # §6 Wave 2 task F + SRD §7 line 409. Phase 3 streams (video, depth,
+        # The full profile includes Phase 2 streams. Phase 3 streams (video, depth,
         # lidar) and `include_collisions` stay opt-in even under `full` to
         # avoid surprising users with high-volume captures.
         "include_robot_state": True,

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

@@ -16,7 +16,10 @@ from simulo.interfaces.platform.artifacts import (
     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,
@@ -109,6 +112,60 @@ from simulo.interfaces.platform.manifest import (
     PreflightResponse,
     RuntimeManifest,
 )
+from simulo.interfaces.platform.policy_bundle import (
+    EXPORT_VALIDATION_JOB_TYPE,
+    JOB_EXPORTS_ROUTE_TEMPLATE,
+    MAX_POLICY_BUNDLE_UNCOMPRESSED_BYTES,
+    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,
+    POLICY_BUNDLE_MODEL_PT_FILE,
+    POLICY_BUNDLE_NORMALIZATION_FILE,
+    POLICY_BUNDLE_OBSERVATION_SCHEMA_FILE,
+    POLICY_BUNDLE_OPTIONAL_FILES,
+    POLICY_BUNDLE_README_FILE,
+    POLICY_BUNDLE_REQUIRED_FILES,
+    POLICY_BUNDLE_REQUIREMENTS_FILE,
+    POLICY_BUNDLE_ROOT_DIR_TEMPLATE,
+    POLICY_BUNDLE_SCHEMA_VERSION,
+    POLICY_BUNDLE_TEST_VECTORS_FILE,
+    POLICY_BUNDLE_VERIFY_FILE,
+    POLICY_EQUIVALENCE_ABS_TOLERANCE,
+    POLICY_EQUIVALENCE_REL_TOLERANCE,
+    POLICY_GOLDEN_VECTOR_COUNT,
+    POLICY_NAME_TOKEN_FALLBACK,
+    POLICY_TENSOR_DTYPES,
+    POLICY_TEST_VECTOR_EXPECTED_OUTPUTS_KEY,
+    POLICY_TEST_VECTOR_INPUTS_KEY,
+    SUPPORTED_POLICY_BUNDLE_SCHEMA_MAJORS,
+    UNKNOWN,
+    PolicyActionComponent,
+    PolicyActionSchema,
+    PolicyBounds,
+    PolicyBundleManifest,
+    PolicyEquivalenceSpec,
+    PolicyExportFailureReason,
+    PolicyExportFormat,
+    PolicyExportValidation,
+    PolicyExportVerdict,
+    PolicyHistorySpec,
+    PolicyNormalization,
+    PolicyObservationComponent,
+    PolicyObservationSchema,
+    PolicySourceSpec,
+    PolicyTensorSpec,
+    Unknown,
+    is_supported_policy_bundle_schema,
+    policy_bundle_archive_name,
+    policy_bundle_root_dir,
+    policy_bundle_schema_major,
+    policy_name_token,
+    validate_policy_bundle,
+)
 from simulo.interfaces.platform.runs import (
     JOB_CANCEL_ROUTE_TEMPLATE,
     JOB_LIST_SCOPES,
@@ -201,6 +258,9 @@ __all__ = [
     "MAX_OUTPUT_FLAG_CODE_CHARS",
     "MAX_OUTPUT_FLAG_DETAIL_CHARS",
     "OUTPUT_FLAG_ANOMALY",
+    "OUTPUT_FLAG_OUTPUT_DROPPED",
+    "OUTPUT_DROPPED_DETAILS",
+    "OUTPUTS_UNDELIVERED_CODE",
     "DECLARED_OUTPUT_MISSING_CODE",
     # job-run contract (run record schema + jobs HTTP API shape)
     "TERMINAL_JOB_STATUSES",
@@ -322,6 +382,62 @@ __all__ = [
     "ConvertedArchive",
     "AssetValidationFinalize",
     "AssetPublishOptions",
+    # portable policy export bundle contract (issue #654) — schema version,
+    # bundle layout, naming rule, export routes/job type, equivalence
+    # defaults, enums, explicit-unknown marker, manifest dataclasses, the
+    # export-validation result, and the cross-file coherence check
+    "POLICY_BUNDLE_SCHEMA_VERSION",
+    "SUPPORTED_POLICY_BUNDLE_SCHEMA_MAJORS",
+    "policy_bundle_schema_major",
+    "is_supported_policy_bundle_schema",
+    "POLICY_BUNDLE_MODEL_ONNX_FILE",
+    "POLICY_BUNDLE_MODEL_PT_FILE",
+    "POLICY_BUNDLE_MANIFEST_FILE",
+    "POLICY_BUNDLE_OBSERVATION_SCHEMA_FILE",
+    "POLICY_BUNDLE_ACTION_SCHEMA_FILE",
+    "POLICY_BUNDLE_NORMALIZATION_FILE",
+    "POLICY_BUNDLE_TEST_VECTORS_FILE",
+    "POLICY_BUNDLE_VERIFY_FILE",
+    "POLICY_BUNDLE_REQUIREMENTS_FILE",
+    "POLICY_BUNDLE_README_FILE",
+    "POLICY_BUNDLE_FILES",
+    "POLICY_BUNDLE_REQUIRED_FILES",
+    "POLICY_BUNDLE_OPTIONAL_FILES",
+    "MAX_POLICY_BUNDLE_UNCOMPRESSED_BYTES",
+    "POLICY_TEST_VECTOR_INPUTS_KEY",
+    "POLICY_TEST_VECTOR_EXPECTED_OUTPUTS_KEY",
+    "POLICY_BUNDLE_ARTIFACT_KIND",
+    "POLICY_BUNDLE_ROOT_DIR_TEMPLATE",
+    "POLICY_BUNDLE_ARCHIVE_NAME_TEMPLATE",
+    "MAX_POLICY_NAME_TOKEN_CHARS",
+    "POLICY_NAME_TOKEN_FALLBACK",
+    "policy_name_token",
+    "policy_bundle_root_dir",
+    "policy_bundle_archive_name",
+    "JOB_EXPORTS_ROUTE_TEMPLATE",
+    "EXPORT_VALIDATION_JOB_TYPE",
+    "POLICY_EQUIVALENCE_ABS_TOLERANCE",
+    "POLICY_EQUIVALENCE_REL_TOLERANCE",
+    "POLICY_GOLDEN_VECTOR_COUNT",
+    "POLICY_TENSOR_DTYPES",
+    "PolicyExportFormat",
+    "PolicyExportVerdict",
+    "PolicyExportFailureReason",
+    "PolicyExportValidation",
+    "Unknown",
+    "UNKNOWN",
+    "PolicyTensorSpec",
+    "PolicyBounds",
+    "PolicyHistorySpec",
+    "PolicySourceSpec",
+    "PolicyEquivalenceSpec",
+    "PolicyObservationComponent",
+    "PolicyActionComponent",
+    "PolicyBundleManifest",
+    "PolicyObservationSchema",
+    "PolicyActionSchema",
+    "PolicyNormalization",
+    "validate_policy_bundle",
     # protocols
     "RuntimeProtocol",
     "AssetProtocol",

{simulo_interfaces-0.12.0 → simulo_interfaces-0.14.0}/src/simulo/interfaces/platform/artifacts.py

@@ -118,6 +118,29 @@ migration). Instead ``JobRecord.outputs`` carries an optional
   even if the transition loses a race) and partial recordings are dropped —
   cancel-uploaded checkpoints are intentionally **unsummarized**. A decision,
   not an oversight.
+* **A registered artifact reaches the general job-artifacts road on the
+  ``completed`` path only** — never on cancel, timeout, or failure. Also a
+  decision, and the reason it is not the worker's to reverse: the plan IS the
+  drained registration set, and the registry is drained **after the job body
+  returns** (``runner``'s ``--outputs-out`` write is on its success path only,
+  mirroring ``--result-out``). A cancelled, timed-out or crashed run never
+  reaches that drain, so no plan file exists and there is nothing to upload;
+  the worker's ``status == completed`` gate makes that explicit and
+  fail-closed rather than reading whatever sidecar happens to be on disk from
+  an earlier attempt. The two older roads look asymmetric here because they
+  are **sniffed** rather than planned — ``_gather_recordings`` /
+  ``_gather_models`` scan the run directory, so they still find (and, for
+  checkpoints, still upload) files a failed run left behind. This road has no
+  sniffer by construction.
+
+  The user-visible consequence, stated rather than buried: a ``report`` or
+  ``log`` that a FAILING run registers to explain itself is **not delivered**.
+  That is the price of "a partial file is not an honest artifact"; the file
+  stays on the worker's disk. The worker deliberately emits no warning for it
+  either — with no plan file it cannot distinguish "registered nothing" from
+  "registered, never drained", so the only available warning is one that would
+  fire on every failing job. A job that must hand back diagnostics on failure
+  should write them **before** the work that can fail and return normally.
 
 The ``/artifacts`` projection is a read-time union, not a home
 --------------------------------------------------------------
@@ -133,9 +156,12 @@ and the narrow ``job_artifacts`` table (everything registered via
 appears in the union **exactly once**. The projection reuses the
 platform-standard paginated envelope (``items``/``total``/``page``/``limit``/
 ``pages``; default ``limit=20``, max 100, out-of-range → 422) and the standard
-error shape.
+error shape — see :mod:`simulo.interfaces.platform.runs` for the full
+contract, including the ``pages >= 1`` invariant that holds even for
+``total == 0``.
 """
 
+import re
 from collections.abc import Mapping
 from dataclasses import dataclass, field
 
@@ -282,6 +308,74 @@ MAX_OUTPUT_FLAG_DETAIL_CHARS = 256
 #: comes from the persisted-rows projection, never from the flag).
 OUTPUT_FLAG_ANOMALY = "anomaly"
 
+#: :attr:`OutputFlag.code` announcing that at least one output the run
+#: REGISTERED never became an artifact — the uploader refused it. ``detail``
+#: carries the refusal reason, one of :data:`OUTPUT_DROPPED_DETAILS`, and the
+#: producer emits ONE flag per DISTINCT reason (the :data:`OUTPUT_FLAG_ANOMALY`
+#: rule: a flag states a property of the run, never an inventory of files).
+#: The worker emits it; the CLI renders it.
+#:
+#: WHY IT EXISTS. A registration the platform refuses is a defect in the JOB —
+#: it named a path the platform will never accept — not a transient condition.
+#: Every other trace of it is unreachable: the refusal is written to the
+#: WORKER's own stderr, while the log the platform uploads is the CHILD's.
+#: Without this flag such a run is reported a plain ``completed`` having
+#: delivered less than it claimed, with nothing anywhere for a user to see.
+#:
+#: SCOPE. This flag rides the ``complete`` body, which the control plane keeps
+#: for a ``completed`` job only. It therefore cannot describe a run that
+#: delivered NOTHING AT ALL — that run is not ``completed``, it is terminal
+#: :data:`OUTPUTS_UNDELIVERED_CODE`. The two signals are mutually exclusive by
+#: construction, and between them every refused output is reported.
+OUTPUT_FLAG_OUTPUT_DROPPED = "output_dropped"
+
+#: The closed ``detail`` vocabulary of :data:`OUTPUT_FLAG_OUTPUT_DROPPED` — why
+#: one registered output was refused:
+#:
+#: * ``malformed`` — the registration's ``name``/``path`` was not a string;
+#: * ``unresolvable`` — the path could not be resolved on the worker;
+#: * ``outside_roots`` — the resolved path lies outside every directory the
+#:   platform points a job's writes at. Uploading it anyway would let a
+#:   registration name any file the worker can read, so the refusal is the
+#:   guard working, and the flag is how the run says so;
+#: * ``no_pipeline`` — the declared kind has no artifact home to land in (a
+#:   checkpoint whose filename carries no role, or a kind outside
+#:   :class:`~simulo.interfaces.platform.enums.ArtifactKind`).
+OUTPUT_DROPPED_DETAILS: tuple[str, ...] = (
+    "malformed",
+    "unresolvable",
+    "outside_roots",
+    "no_pipeline",
+)
+
+#: Terminal ``status_reason`` of a run whose body exited 0 but which delivered
+#: NO artifact at all: every output it registered was refused (see
+#: :data:`OUTPUT_DROPPED_DETAILS`) and it produced no recording and no
+#: checkpoint either. Emitted by the worker, rendered by the CLI.
+#:
+#: Such a run is reported ``failed``, not ``completed``. Green-with-nothing is
+#: the worse of the two outcomes: a job whose whole purpose is one file, shown
+#: successful beside an empty artifact list, gives nobody a reason to look —
+#: whereas a job marked failed still has its log, and the run cost the same
+#: either way.
+#:
+#: The condition is deliberately "delivered nothing", not "every registered
+#: output was refused". A run whose checkpoints or recordings landed DID
+#: deliver something, and stays ``completed`` carrying
+#: :data:`OUTPUT_FLAG_OUTPUT_DROPPED` for what it lost — failing it would throw
+#: away hours of real training over one mis-registered path.
+#:
+#: THE RESULT SURVIVES. ``GET /v1/jobs/{id}/result`` serves the result of a
+#: run reported under this code, exactly as it does for a completed run — the
+#: one status other than ``completed`` for which a result is stored at all.
+#: The same argument that keeps a run with surviving checkpoints ``completed``
+#: applies to the dict the body returned: this run's code RAN, its metrics are
+#: as real as any completed run's, and only its FILES were refused. Discarding
+#: them too would destroy work the refusal never touched. The typed
+#: ``outputs`` summary is NOT preserved the same way — it describes the
+#: artifacts, which is precisely what this code already says.
+OUTPUTS_UNDELIVERED_CODE = "outputs_undelivered"
+
 #: Terminal ``status_reason`` code of a job whose declared **non-optional**
 #: output was missing after the run body succeeded (the runner's validation —
 #: see the module docstring). Emitted by the runner, rendered by the CLI.
@@ -365,6 +459,88 @@ def _validate_artifact_name(owner: str, name: str) -> None:
         raise ValueError(f"{owner} must not be a dots-only relative-path token, got {_truncated(name)}.")
 
 
+#: The SERVER's finalize-time filename rule, mirrored — the second, STRICTER
+#: gate an artifact ``name`` must clear before its bytes may be uploaded.
+#:
+#: Canonical implementation: ``simulo_control_plane.storage.base._KEY_SEGMENT_RE``,
+#: applied to ``ArtifactFinalizeRequest.name`` (and ``ModelFinalizeRequest.name``)
+#: through ``storage.base.is_safe_filename_segment`` — anything else is a 422.
+#: Mirrored here rather than imported for the reason ``jobs/constants.py``
+#: records at length: the control-plane build is self-contained and this
+#: contract package is NOT installed in its deploy image, so the dependency
+#: cannot run in that direction.
+#:
+#: **Why a mirror is worth carrying.** The upload order is presign → PUT →
+#: finalize, so a name that clears :func:`_validate_artifact_name` and then
+#: fails the server's rule has ALREADY written bytes to object storage when the
+#: 422 arrives: the artifact is lost, the object is permanently unreferenced
+#: (no row ever names it), and a job may repeat that up to
+#: ``simulo.outputs.MAX_REGISTERED_OUTPUTS`` times at unbounded size. Measured
+#: divergences — names :func:`_validate_artifact_name` ACCEPTS and this rule
+#: rejects: ``"my report.html"`` (space), ``"résumé.pdf"`` (non-ASCII),
+#: ``"eval (1).json"`` (parentheses), ``".hidden"`` (leading dot).
+#:
+#: Those are ordinary things to call a file, and the reachable path is the
+#: PUBLIC one: ``simulo.save_artifact("my report.html", path, kind="report")``
+#: passes the constructor and then orphans its bytes. A worker that checks
+#: BEFORE the presign turns that into an honest, named refusal on the warning
+#: channel instead of an unreferenced object.
+#:
+#: NOT affected, measured rather than assumed: the policy-export bundle name.
+#: ``policy_bundle.policy_name_token`` reduces a job title to ``[a-z0-9._-]``
+#: with a ``[a-z0-9]`` first character — deliberately, citing this very gate —
+#: so ``résumé-arm`` composes ``r-sum-arm-policy-best.zip``, which this rule
+#: ACCEPTS. That is a second, independent guard on one caller; this one is the
+#: general gate every other registered name needs.
+#:
+#: The drift guard is ``tests/integration/test_contract_mirror.py`` — the one
+#: environment holding both packages. It compares this pattern against the
+#: control plane's real compiled regex AND runs both implementations over a
+#: table of names, so a future divergence goes red there rather than orphaning
+#: objects in production.
+SAFE_FILENAME_SEGMENT_PATTERN = r"^[A-Za-z0-9][A-Za-z0-9._-]*\Z"
+_SAFE_FILENAME_SEGMENT_RE = re.compile(SAFE_FILENAME_SEGMENT_PATTERN)
+
+
+def is_safe_filename_segment(value: str) -> bool:
+    """``True`` when ``value`` is a name the control plane's finalize accepts.
+
+    Deliberately the same NAME as the control plane's own helper
+    (``storage.base.is_safe_filename_segment``), so the two read as the one
+    rule they are. Anchored with ``\\Z`` and not ``$`` for the reason recorded
+    on the server's copy: Python's ``$`` also matches just before a trailing
+    newline, so ``"rollout.mcap\\n"`` would wrongly pass.
+
+    NOT a replacement for :func:`_validate_artifact_name`, which stays the
+    contract's own construction-time rule (cross-platform separators, control
+    characters, dots-only tokens, the UTF-8 byte ceiling, and the type check).
+    This is the narrower *server-acceptance* question, asked by an uploader
+    before it spends bytes.
+    """
+    return bool(value) and bool(_SAFE_FILENAME_SEGMENT_RE.match(value))
+
+
+def _validate_finalizable_artifact_name(owner: str, name: str) -> None:
+    """Reject any ``name`` the server's finalize would answer 422 for.
+
+    Both gates, in the order an uploader must apply them: the contract's own
+    :func:`_validate_artifact_name` first (it owns the type check and the
+    length-before-echo discipline, so an over-length or non-``str`` value is
+    reported by its size/type and never reproduced), then
+    :func:`is_safe_filename_segment`.
+
+    Every rejection is a ``ValueError`` whose message names the offending value
+    (clamped by :func:`_truncated` — an uploader's message is worker-log
+    content and must never amplify its own input) and says which rule it broke.
+    """
+    _validate_artifact_name(owner, name)
+    if not is_safe_filename_segment(name):
+        raise ValueError(
+            f"{owner} must be a single safe filename segment the control plane's finalize will accept "
+            f"(letters, digits, '.', '_', '-'; must start with a letter or digit), got {_truncated(name)}."
+        )
+
+
 def _validate_artifact_path(owner: str, path: str) -> None:
     """Reject any ``path`` that could not name a real file for any consumer.
 
@@ -516,54 +692,33 @@ class ArtifactDeclaration:
 
 @dataclass(frozen=True, slots=True, kw_only=True)
 class Artifact:
-    """One registered job output — the execution-time record of a real file.
-
-    This is the type ``simulo.save_artifact(name, path)`` registers (tier 2)
-    and the type tier-0 producers register as they write files (the anomaly
-    monitor registers each capture session with its actual generated
-    filename — PR-B4). A registration always names a file the run really
-    produced at a path that really exists, which is exactly what
-    distinguishes it from :class:`ArtifactDeclaration` (the pre-run shape,
-    no path field): the drained registration set is the plan side of the
-    worker's ``plan ∪ sniff`` union, keyed by ``Path.resolve()`` of
-    :attr:`path` — declarations never enter that union. It is an authoring
-    value, not a wire row — it validates at construction so mistakes surface
-    on the author's machine (the
-    :class:`~simulo.interfaces.runtime.anomaly.DebugOnAnomaly` precedent);
-    the persisted/served row is :class:`ArtifactRecord`.
+    """A file registration created while a job is running.
+
+    ``simulo.save_artifact(name, path)`` builds this value and validates it
+    before adding it to the job's local output registry. It describes a real
+    file at a real path, but it is not confirmation that the file was uploaded.
+    The current managed platform does not publish general registered files for
+    download. Use a job result for small JSON values, a named volume for files
+    another job needs, or the supported model and recording workflows for
+    downloadable output.
     """
 
     name: str
-    """Logical name — the single filename the platform stores, lists, and
-    saves downloads under. Never a path: separators (including the Windows
-    drive ``:``), control characters, dots-only and whitespace-only tokens,
-    empty and over-:data:`MAX_ARTIFACT_NAME_BYTES` names are rejected at
-    construction (a traversal-shaped name would otherwise become the
-    filename a client writes a download to — see
-    :func:`_validate_artifact_name` for the full rule and the download-site
-    obligation)."""
+    """Logical filename for the registration. It must be one filename, never
+    a path. Separators, control characters, dots-only and whitespace-only
+    values, empty values, and names over
+    :data:`MAX_ARTIFACT_NAME_BYTES` are rejected."""
 
     path: str
-    """Filesystem path of the produced file in the job's working tree at
-    execution time. The worker's ``plan ∪ sniff`` de-duplication key is this
-    path **resolved** (``Path.resolve()``), the plan's kind winning.
-
-    Validated at construction for TYPE (a ``str``), LENGTH
-    (≤ :data:`MAX_ARTIFACT_PATH_BYTES`), non-emptiness, and absence of a NUL
-    byte — the four things that make a value unusable as a path *by any
-    consumer*, checked here so the consumer does not discover them mid-upload.
-    Deliberately NOT validated for shape or location: a path is legitimately
-    absolute and may point anywhere the job can write, so *where* it points is
-    contained at the uploader (see the ``simulo.outputs`` module warning), not
-    here."""
+    """Filesystem path of the produced file while the job is running.
+    Construction checks that it is a non-empty, NUL-free string within
+    :data:`MAX_ARTIFACT_PATH_BYTES`. The path may be absolute or relative."""
 
     kind: ArtifactKind = ArtifactKind.FILE
-    """What this output is (see :class:`~simulo.interfaces.platform.enums.ArtifactKind`).
-    ``save_artifact`` registers :attr:`~simulo.interfaces.platform.enums.ArtifactKind.FILE`
-    by default; tier-0 producers stamp the callback's implied kind when they
-    register (the anomaly monitor stamps ``anomaly_capture``). A plain wire
-    string is normalized to the enum at construction; an unknown kind string
-    is a ``ValueError`` on the author's machine."""
+    """What kind of file this is. The default is
+    :attr:`~simulo.interfaces.platform.enums.ArtifactKind.FILE`. You may pass
+    an ``ArtifactKind`` value or its string form; unknown values raise
+    ``ValueError``."""
 
     def __post_init__(self) -> None:
         object.__setattr__(self, "kind", ArtifactKind(self.kind))
@@ -621,8 +776,10 @@ class ArtifactRecord:
       (a checkpoint is NOT a trained model — Rule #8, stated in the
       :mod:`~simulo.interfaces.platform.domain` module docstring and on its
       ``Checkpoint``/``TrainedModel`` types).
-      ``trained_model`` has no producer today and is only ever stamped
-      explicitly by a future exporter, never inferred from a ``models`` row;
+      ``trained_model`` DOES have a producer — the worker's general
+      job-artifacts road (``worker._upload_job_artifact``), whose rows live in
+      ``job_artifacts`` — and it is only ever stamped explicitly, by the job
+      that registers the bundle, never inferred from a ``models`` row;
     * rows projected from ``job_recordings`` map a legacy NULL kind to
       :attr:`~simulo.interfaces.platform.enums.ArtifactKind.RECORDING` —
       never to ``replay_output`` (see the enum docstrings)."""