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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo-interfaces
-Version: 0.14.0
+Version: 0.15.2
 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.15.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo-interfaces"
-version = "0.14.0"
+version = "0.15.2"
 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.15.2}/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.15.2/src/simulo/interfaces/ids.py

@@ -0,0 +1,134 @@
+"""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 grammar-validated human-facing references.
+Their parsers normalize only outer ASCII whitespace and ASCII letter case;
+Unicode whitespace, Unicode case folding, wildcards, and partial IDs are
+deliberately rejected.
+"""
+
+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)
+ArtifactId = NewType("ArtifactId", str)  # a job-produced output in the /artifacts 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.15.2}/src/simulo/interfaces/platform/__init__.py

@@ -100,6 +100,34 @@ 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.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,
@@ -221,6 +249,33 @@ from simulo.interfaces.platform.volume import VolumeProtocol
 __all__ = [
     # enums
     "ArtifactKind",
+    # 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",

simulo_interfaces-0.15.2/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.15.2}/src/simulo/interfaces/platform/artifacts.py

@@ -165,7 +165,17 @@ import re
 from collections.abc import Mapping
 from dataclasses import dataclass, field
 
-from simulo.interfaces.ids import ArtifactId, JobId
+from simulo.interfaces.ids import (
+    ArtifactId,
+    JobId,
+    ModelPublicId,
+    OutputPublicId,
+    RecordingPublicId,
+    parse_model_public_id,
+    parse_output_public_id,
+    parse_recording_public_id,
+)
+from simulo.interfaces.platform._payload import known_payload_fields
 from simulo.interfaces.platform.enums import ArtifactKind
 
 # --------------------------------------------------------------------------
@@ -740,9 +750,9 @@ class ArtifactRecord:
 
     Wire-shaped by construction (``dataclasses.asdict`` serializes directly;
     ``kind`` is a ``StrEnum`` and JSON-encodes as its string value).
-    Reconstruction from a JSON payload coerces the enum, the
-    :class:`JobRecord <simulo.interfaces.platform.runs.JobRecord>` ``status``
-    precedent: ``ArtifactRecord(**{**payload, "kind": ArtifactKind(payload["kind"])})``.
+    Use :meth:`from_payload` for tolerant response reconstruction: it ignores
+    additive unknown fields and coerces the known enum and public-ID fields.
+    Direct typed construction keeps the dataclass's strict keyword surface.
     """
 
     artifact_id: ArtifactId
@@ -805,6 +815,32 @@ class ArtifactRecord:
     not record one (recordings rows — the ``ModelRecord.kind`` unknown-value
     precedent)."""
 
+    public_id: ModelPublicId | RecordingPublicId | OutputPublicId | None = None
+    """The row's home Model, Recording, or Output ID.
+
+    ``None`` means an older producer omitted the additive field. The union
+    projection never mints a second ID for model or recording bytes.
+    """
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, object]) -> "ArtifactRecord":
+        """Build from a response mapping while ignoring additive unknown fields."""
+
+        values = known_payload_fields(cls, payload, owner="ArtifactRecord.from_payload()")
+        if "kind" in values:
+            values["kind"] = ArtifactKind(values["kind"])
+        if values.get("public_id") is not None:
+            value = values["public_id"]
+            for parser in (parse_model_public_id, parse_recording_public_id, parse_output_public_id):
+                try:
+                    values["public_id"] = parser(value)
+                    break
+                except ValueError:
+                    continue
+            else:
+                raise ValueError("ArtifactRecord.from_payload() received a non-canonical public ID.")
+        return cls(**values)
+
 
 @dataclass(frozen=True, slots=True, kw_only=True)
 class OutputFlag:

simulo_interfaces-0.15.2/src/simulo/interfaces/platform/job_events.py

@@ -0,0 +1,244 @@
+"""Closed, versioned public job-event contract.
+
+Workers may publish only these Simulo-owned events.  The contract deliberately
+contains no free-form message, path, URL, exception, or metadata field; public
+copy is rendered by the trusted consumer from ``code`` and its typed ``data``.
+
+The write-side byte offset is over canonical projected text, not request JSON
+and not the legacy raw-log store.  ``offset == total`` appends.  An earlier
+offset is an idempotent retry only when a stored event starts exactly there
+with identical canonical projection bytes; different bytes (or an offset
+inside an event) are ``event_offset_conflict``.  A future offset is
+``event_offset_gap`` with the current public total.  Every event carries the
+current claim attempt and is fenced when it differs from the locked job row.
+Every event POST must also carry the current claim lease in
+:data:`simulo.interfaces.platform.submit.WORKER_LEASE_HEADER`; a missing or
+stale lease is ``409 lease_lost`` and cannot append.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Literal, TypeAlias
+
+PUBLIC_JOB_EVENT_SCHEMA_VERSION: Literal[1] = 1
+WORKER_JOB_EVENTS_ROUTE_TEMPLATE = "/internal/worker/jobs/{job_id}/events"
+
+# A public event is intentionally much smaller than the legacy 1 MiB raw-log
+# chunk.  The control plane applies this bound to the canonical projection.
+MAX_PUBLIC_JOB_EVENT_BYTES = 4 * 1024
+# Strict request-wire cap. Valid closed events are far smaller; this separate
+# bound protects authentication-passing callers before JSON parsing.
+MAX_PUBLIC_JOB_EVENT_WIRE_BYTES = 8 * 1024
+# Bounds the server-owned provenance ledger kept outside the worker claim.
+MAX_PUBLIC_JOB_EVENT_ENTRIES = 4_096
+MAX_PUBLIC_JOB_EVENT_ATTEMPT = 1_000
+MAX_PUBLIC_JOB_EVENT_QUIET_SECONDS = 24 * 60 * 60
+MAX_PUBLIC_ASSET_FINDING_COUNT = 1_000
+
+# Generated by trusted server code when an event-only job is enqueued.  It is
+# a correlation handle, not a credential or secret.
+PUBLIC_JOB_SUPPORT_ID_PREFIX = "sup_"
+PUBLIC_JOB_SUPPORT_ID_HEX_CHARS = 32
+
+PUBLIC_JOB_EVENT_OFFSET_GAP_CODE = "event_offset_gap"
+PUBLIC_JOB_EVENT_OFFSET_CONFLICT_CODE = "event_offset_conflict"
+PUBLIC_JOB_EVENT_ATTEMPT_MISMATCH_CODE = "event_attempt_mismatch"
+
+
+class PublicJobEventSeverity(StrEnum):
+    """Closed public severities used by the initial event set."""
+
+    INFO = "info"
+    WARNING = "warning"
+
+
+class PublicJobEventCode(StrEnum):
+    """Closed event codes required by the asset-validation worker."""
+
+    JOB_PREPARING = "job.preparing"
+    JOB_RUNNING = "job.running"
+    JOB_STILL_WORKING = "job.still_working"
+    JOB_ASSET_FINDING = "job.asset_finding"
+
+
+class PublicJobPreparationPhase(StrEnum):
+    """Safe preparation phases for the initial event schema."""
+
+    ASSET_VALIDATION = "asset_validation"
+
+
+class PublicAssetFindingReason(StrEnum):
+    """Stable, product-owned asset finding reasons.
+
+    These values classify a trusted adapter outcome.  They never carry the
+    native diagnostic or the asset's path/name.
+    """
+
+    ASSET_OPEN_FAILED = "asset_open_failed"
+    ASSET_REFERENCE_UNRESOLVED = "asset_reference_unresolved"
+    ASSET_MATERIAL_UNRESOLVED = "asset_material_unresolved"
+    ASSET_PRIM_INVALID = "asset_prim_invalid"
+
+
+def _validate_attempt(attempt: int) -> None:
+    if isinstance(attempt, bool) or not isinstance(attempt, int):
+        raise TypeError("attempt must be an integer")
+    if not 1 <= attempt <= MAX_PUBLIC_JOB_EVENT_ATTEMPT:
+        raise ValueError(f"attempt must be between 1 and {MAX_PUBLIC_JOB_EVENT_ATTEMPT}")
+
+
+def _validate_schema_version(schema_version: object) -> None:
+    # ``True == 1`` in Python; identity of the JSON scalar type is part of the
+    # version boundary, not merely numeric equality.
+    if type(schema_version) is not int or schema_version != PUBLIC_JOB_EVENT_SCHEMA_VERSION:
+        raise ValueError("unsupported public job-event schema version")
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class JobPreparingData:
+    phase: PublicJobPreparationPhase
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.phase, PublicJobPreparationPhase):
+            raise TypeError("phase must be a PublicJobPreparationPhase")
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class JobRunningData:
+    """The running transition needs no worker-controlled detail."""
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class JobStillWorkingData:
+    quiet_seconds: int
+
+    def __post_init__(self) -> None:
+        if isinstance(self.quiet_seconds, bool) or not isinstance(self.quiet_seconds, int):
+            raise TypeError("quiet_seconds must be an integer")
+        if not 1 <= self.quiet_seconds <= MAX_PUBLIC_JOB_EVENT_QUIET_SECONDS:
+            raise ValueError("quiet_seconds must be between 1 and " f"{MAX_PUBLIC_JOB_EVENT_QUIET_SECONDS}")
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class JobAssetFindingData:
+    reason: PublicAssetFindingReason
+    count: int = 1
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.reason, PublicAssetFindingReason):
+            raise TypeError("reason must be a PublicAssetFindingReason")
+        if isinstance(self.count, bool) or not isinstance(self.count, int):
+            raise TypeError("count must be an integer")
+        if not 1 <= self.count <= MAX_PUBLIC_ASSET_FINDING_COUNT:
+            raise ValueError(f"count must be between 1 and {MAX_PUBLIC_ASSET_FINDING_COUNT}")
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class JobPreparingEvent:
+    attempt: int
+    data: JobPreparingData
+    schema_version: Literal[1] = PUBLIC_JOB_EVENT_SCHEMA_VERSION
+    code: Literal[PublicJobEventCode.JOB_PREPARING] = PublicJobEventCode.JOB_PREPARING
+    severity: Literal[PublicJobEventSeverity.INFO] = PublicJobEventSeverity.INFO
+
+    def __post_init__(self) -> None:
+        _validate_attempt(self.attempt)
+        _validate_schema_version(self.schema_version)
+        if self.code is not PublicJobEventCode.JOB_PREPARING:
+            raise ValueError("code does not match JobPreparingEvent")
+        if self.severity is not PublicJobEventSeverity.INFO:
+            raise ValueError("severity does not match JobPreparingEvent")
+        if not isinstance(self.data, JobPreparingData):
+            raise TypeError("data must be JobPreparingData")
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class JobRunningEvent:
+    attempt: int
+    data: JobRunningData
+    schema_version: Literal[1] = PUBLIC_JOB_EVENT_SCHEMA_VERSION
+    code: Literal[PublicJobEventCode.JOB_RUNNING] = PublicJobEventCode.JOB_RUNNING
+    severity: Literal[PublicJobEventSeverity.INFO] = PublicJobEventSeverity.INFO
+
+    def __post_init__(self) -> None:
+        _validate_attempt(self.attempt)
+        _validate_schema_version(self.schema_version)
+        if self.code is not PublicJobEventCode.JOB_RUNNING:
+            raise ValueError("code does not match JobRunningEvent")
+        if self.severity is not PublicJobEventSeverity.INFO:
+            raise ValueError("severity does not match JobRunningEvent")
+        if not isinstance(self.data, JobRunningData):
+            raise TypeError("data must be JobRunningData")
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class JobStillWorkingEvent:
+    attempt: int
+    data: JobStillWorkingData
+    schema_version: Literal[1] = PUBLIC_JOB_EVENT_SCHEMA_VERSION
+    code: Literal[PublicJobEventCode.JOB_STILL_WORKING] = PublicJobEventCode.JOB_STILL_WORKING
+    severity: Literal[PublicJobEventSeverity.INFO] = PublicJobEventSeverity.INFO
+
+    def __post_init__(self) -> None:
+        _validate_attempt(self.attempt)
+        _validate_schema_version(self.schema_version)
+        if self.code is not PublicJobEventCode.JOB_STILL_WORKING:
+            raise ValueError("code does not match JobStillWorkingEvent")
+        if self.severity is not PublicJobEventSeverity.INFO:
+            raise ValueError("severity does not match JobStillWorkingEvent")
+        if not isinstance(self.data, JobStillWorkingData):
+            raise TypeError("data must be JobStillWorkingData")
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class JobAssetFindingEvent:
+    attempt: int
+    data: JobAssetFindingData
+    schema_version: Literal[1] = PUBLIC_JOB_EVENT_SCHEMA_VERSION
+    code: Literal[PublicJobEventCode.JOB_ASSET_FINDING] = PublicJobEventCode.JOB_ASSET_FINDING
+    severity: Literal[PublicJobEventSeverity.WARNING] = PublicJobEventSeverity.WARNING
+
+    def __post_init__(self) -> None:
+        _validate_attempt(self.attempt)
+        _validate_schema_version(self.schema_version)
+        if self.code is not PublicJobEventCode.JOB_ASSET_FINDING:
+            raise ValueError("code does not match JobAssetFindingEvent")
+        if self.severity is not PublicJobEventSeverity.WARNING:
+            raise ValueError("severity does not match JobAssetFindingEvent")
+        if not isinstance(self.data, JobAssetFindingData):
+            raise TypeError("data must be JobAssetFindingData")
+
+
+PublicJobEvent: TypeAlias = JobPreparingEvent | JobRunningEvent | JobStillWorkingEvent | JobAssetFindingEvent
+
+
+__all__ = [
+    "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",
+]

{simulo_interfaces-0.14.0 → simulo_interfaces-0.15.2}/src/simulo/interfaces/platform/runs.py

@@ -151,8 +151,9 @@ from collections.abc import Mapping
 from dataclasses import dataclass, field
 from typing import Any, Optional
 
-from simulo.interfaces.ids import JobId, PackageId
-from simulo.interfaces.platform.artifacts import JobOutputsSummary
+from simulo.interfaces.ids import JobId, JobPublicId, PackageId, parse_job_public_id
+from simulo.interfaces.platform._payload import known_payload_fields
+from simulo.interfaces.platform.artifacts import JobOutputsSummary, OutputFlag
 from simulo.interfaces.platform.enums import JobStatus
 
 #: Default TCP port for the jobs API. Locally this is where ``simulo-backend
@@ -234,7 +235,9 @@ class JobRecord:
     ``GET /v1/jobs/{job_id}``. Timestamps are ISO 8601 UTC strings (wire-shaped
     by construction so ``dataclasses.asdict`` serializes directly; ``status`` is
     a :class:`~simulo.interfaces.platform.enums.JobStatus` ``StrEnum`` and
-    JSON-encodes as its string value).
+    JSON-encodes as its string value). Use :meth:`from_payload` for responses:
+    it ignores additive unknown fields and coerces known nested and enum values.
+    Direct typed construction keeps the dataclass's strict keyword surface.
     """
 
     job_id: JobId
@@ -358,3 +361,58 @@ class JobRecord:
     docstring: ``flags`` are what the worker announced at ``complete`` time;
     ``counts`` are reconciled at read time from actually-persisted artifact
     rows, so a count never asserts bytes that did not land."""
+
+    public_id: Optional[JobPublicId] = None
+    """Human-facing Job ID, or ``None`` when an older producer omitted it."""
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, Any]) -> "JobRecord":
+        """Build from a response mapping while ignoring additive unknown fields."""
+
+        values = known_payload_fields(cls, payload, owner="JobRecord.from_payload()")
+        if "status" in values:
+            values["status"] = JobStatus(values["status"])
+        if "assets" in values:
+            assets = values["assets"]
+            if not isinstance(assets, (list, tuple)):
+                raise TypeError("JobRecord.from_payload().assets requires an array.")
+            if not all(isinstance(asset, str) for asset in assets):
+                raise TypeError("JobRecord.from_payload().assets[] requires a str.")
+            values["assets"] = tuple(assets)
+        if values.get("public_id") is not None:
+            values["public_id"] = parse_job_public_id(values["public_id"])
+
+        outputs = values.get("outputs")
+        if outputs is not None and not isinstance(outputs, JobOutputsSummary):
+            if not isinstance(outputs, Mapping):
+                raise TypeError("JobRecord.from_payload().outputs requires a mapping or JobOutputsSummary.")
+            output_values = known_payload_fields(
+                JobOutputsSummary,
+                outputs,
+                owner="JobRecord.from_payload().outputs",
+            )
+            if "counts" in output_values and not isinstance(output_values["counts"], Mapping):
+                raise TypeError("JobRecord.from_payload().outputs.counts requires a mapping.")
+            if "flags" in output_values:
+                flags = output_values["flags"]
+                if not isinstance(flags, (list, tuple)):
+                    raise TypeError("JobRecord.from_payload().outputs.flags requires an array.")
+                parsed_flags = []
+                for flag in flags:
+                    if isinstance(flag, OutputFlag):
+                        parsed_flags.append(flag)
+                    elif isinstance(flag, Mapping):
+                        parsed_flags.append(
+                            OutputFlag(
+                                **known_payload_fields(
+                                    OutputFlag,
+                                    flag,
+                                    owner="JobRecord.from_payload().outputs.flags[]",
+                                )
+                            )
+                        )
+                    else:
+                        raise TypeError("JobRecord.from_payload().outputs.flags[] requires a mapping or OutputFlag.")
+                output_values["flags"] = tuple(parsed_flags)
+            values["outputs"] = JobOutputsSummary(**output_values)
+        return cls(**values)

{simulo_interfaces-0.14.0 → simulo_interfaces-0.15.2}/src/simulo/interfaces/platform/submit.py

@@ -167,6 +167,16 @@ platform-standard shape: ``{"error": {"code": ..., "message": ..., "request_id":
        "lease_seconds": 300,
        "lease_id": "5e0c4a4e-..."}
 
+  A server-marked event-only asset-validation job additionally carries
+  ``public_event_schema_version``, ``public_log_offset``, and ``support_id``.
+  These fields are absent for ordinary and legacy jobs, so workers published
+  before the event contract continue to ignore the additive seam. The support
+  id is a server-generated, non-secret correlation handle; a worker reports
+  events without supplying or overriding it. See
+  :mod:`simulo.interfaces.platform.job_events` for the closed event schema.
+  The private provenance ledger that derives ``public_log_offset`` is never
+  included in the claim.
+
   or ``204`` with an empty body when there is no queued work. A claim is one
   atomic ``SELECT ... FOR UPDATE SKIP LOCKED`` transition of exactly one
   ``queued`` job to ``running`` — plus a status event, ``attempts += 1``, and
@@ -175,7 +185,7 @@ platform-standard shape: ``{"error": {"code": ..., "message": ..., "request_id":
   ``lease_id`` (lease-reaper wave, additive) is the **per-claim ownership
   token**: a fresh server-generated opaque id stamped on the job row by this
   claim. The worker must present it back on every subsequent job-scoped call
-  (heartbeat / logs / complete) in the :data:`WORKER_LEASE_HEADER` request
+  (heartbeat / logs / events / complete) in the :data:`WORKER_LEASE_HEADER` request
   header — it is what distinguishes "the worker holding the CURRENT claim"
   from "a worker that once held a claim on this job_id". A call whose
   presented lease does not match the job's current one (the job was reaped
@@ -197,9 +207,15 @@ platform-standard shape: ``{"error": {"code": ..., "message": ..., "request_id":
   a live run), because the atomic ``lease_id`` swap at reclaim is what
   fences out a stale worker, not the wall clock.
 
-* :data:`WORKER_JOB_LOGS_ROUTE_TEMPLATE` (``POST``, ``?offset=N``) — request
-  body is raw log bytes (not JSON), capped at :data:`MAX_LOG_CHUNK_BYTES` per
-  call. ``offset`` is the byte offset the worker believes the server is at
+* :data:`WORKER_JOB_LOGS_ROUTE_TEMPLATE` (``POST``, ``?offset=N``) — for an
+  ordinary job, the request body is raw log bytes (not JSON), capped at
+  :data:`MAX_LOG_CHUNK_BYTES` per call. Asset-validation jobs are mutually
+  exclusive with this legacy surface: marked and unmarked rows both reject a
+  raw append with ``409 raw_logs_disabled_for_asset_validation``. A marked
+  asset-validation worker instead posts the closed event body to
+  :data:`simulo.interfaces.platform.job_events.WORKER_JOB_EVENTS_ROUTE_TEMPLATE`;
+  the control plane renders the canonical public text and stores only those
+  bytes. ``offset`` is the byte offset the worker believes the server is at
   (mirrors the client-side ``GET .../logs?offset=N`` semantics in
   ``runs.py``, from the writer's side):
 
@@ -221,6 +237,29 @@ platform-standard shape: ``{"error": {"code": ..., "message": ..., "request_id":
   only channel). A stale lease is ``409 lease_lost`` — a reaped worker can
   never append into the stream a later attempt now owns.
 
+* :data:`simulo.interfaces.platform.job_events.WORKER_JOB_EVENTS_ROUTE_TEMPLATE`
+  (``POST``, ``?offset=N``) — the marked asset-validation replacement for raw
+  logs. Authentication and the machine rate limit run before the bounded body
+  is read; the JSON wire body is capped at
+  :data:`simulo.interfaces.platform.job_events.MAX_PUBLIC_JOB_EVENT_WIRE_BYTES`
+  and its canonical projection at
+  :data:`simulo.interfaces.platform.job_events.MAX_PUBLIC_JOB_EVENT_BYTES`.
+  Offsets are over canonical projected UTF-8 bytes only:
+
+  - ``offset == <public total>`` appends the new projection.
+  - ``offset < <public total>`` succeeds only when a ledger entry starts
+    exactly there with identical canonical projection bytes. Different bytes
+    or an offset inside an event answer ``409 event_offset_conflict``.
+  - ``offset > <public total>`` answers ``409 event_offset_gap`` with the
+    current public total.
+
+  The request must carry the current claim lease in
+  :data:`WORKER_LEASE_HEADER`; a missing or stale value answers ``409
+  lease_lost`` and cannot append. The body ``attempt`` must equal the locked
+  job row's current attempt; otherwise it is fenced with ``409
+  event_attempt_mismatch``. Physical legacy raw rows are outside this logical
+  byte space and cannot affect claim, retry, GET/tail, or flattening behavior.
+
 * :data:`WORKER_JOB_HEARTBEAT_ROUTE_TEMPLATE` (``POST``) — no request body
   required; extends the claim lease. The request carries the claim's
   ``lease_id`` in :data:`WORKER_LEASE_HEADER`; a stale lease is ``409
@@ -349,10 +388,20 @@ models; the list is empty, never an error.
 """
 
 import re
+from collections.abc import Mapping
 from dataclasses import dataclass
 from typing import Optional
 
-from simulo.interfaces.ids import JobId, RecordingId, TrainedModelId
+from simulo.interfaces.ids import (
+    JobId,
+    ModelPublicId,
+    RecordingId,
+    RecordingPublicId,
+    TrainedModelId,
+    parse_model_public_id,
+    parse_recording_public_id,
+)
+from simulo.interfaces.platform._payload import known_payload_fields
 
 # --------------------------------------------------------------------------
 # Client-facing routes (bearer = user JWT; require_active_org server-side)
@@ -443,7 +492,9 @@ SEED_SOURCE_CONFLICT_CODE = "seed_source_conflict"
 
 #: ``POST`` — atomically claim the next queued job (``FOR UPDATE SKIP LOCKED``).
 WORKER_CLAIM_ROUTE = "/internal/worker/claim"
-#: ``POST`` — append raw log bytes at a byte offset (``?offset=N``). ``.format(job_id=...)``.
+#: ``POST`` — append ordinary-job raw log bytes at a byte offset
+#: (``?offset=N``). Asset-validation jobs must use the closed event route.
+#: ``.format(job_id=...)``.
 WORKER_JOB_LOGS_ROUTE_TEMPLATE = "/internal/worker/jobs/{job_id}/logs"
 #: ``POST`` — extend the claim lease; response carries the ``cancelled`` seam.
 #: ``.format(job_id=...)``.
@@ -468,9 +519,9 @@ WORKER_JOB_MODELS_PRESIGN_ROUTE_TEMPLATE = "/internal/worker/jobs/{job_id}/model
 WORKER_JOB_MODELS_ROUTE_TEMPLATE = "/internal/worker/jobs/{job_id}/models"
 
 #: Request header carrying the claim's ``lease_id`` ownership token on every
-#: job-scoped worker call (heartbeat / logs / complete). A header — not a body
+#: job-scoped worker call (heartbeat / logs / events / complete). A header — not a body
 #: field — because the logs route's body is raw bytes and heartbeat has no
-#: body; one uniform channel for all three. A missing or mismatching value is
+#: body; one uniform channel for all four. A missing or mismatching value is
 #: ``409 lease_lost`` (see the module docstring's claim section for the full
 #: lease/reaper semantics). Recording presign/finalize are deliberately NOT
 #: lease-gated: the worker uploads recordings AFTER ``complete`` — i.e. after
@@ -525,6 +576,8 @@ class RecordingRecord:
     them. The three episode-summary fields are optional because not every
     recording is episodic (e.g. a raw rollout capture) and because a worker
     may finalize a recording before its summary stats are computed.
+    Use :meth:`from_payload` for tolerant response reconstruction; direct typed
+    construction keeps the dataclass's strict keyword surface.
     """
 
     recording_id: RecordingId
@@ -560,6 +613,18 @@ class RecordingRecord:
     success_rate: Optional[float] = None
     """Fraction of episodes that reached a success termination, if computed."""
 
+    public_id: Optional[RecordingPublicId] = None
+    """Human-facing Recording ID, or ``None`` when an older producer omitted it."""
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, object]) -> "RecordingRecord":
+        """Build from a response mapping while ignoring additive unknown fields."""
+
+        values = known_payload_fields(cls, payload, owner="RecordingRecord.from_payload()")
+        if values.get("public_id") is not None:
+            values["public_id"] = parse_recording_public_id(values["public_id"])
+        return cls(**values)
+
 
 #: The checkpoint kinds a training job produces (``simulo.checkpoint.v1``:
 #: ``best.pt`` = highest-mean-episode-reward snapshot, ``latest.pt`` = most
@@ -583,6 +648,8 @@ class ModelRecord:
     ``digest_sha256`` is always present (bare 64-hex): the worker hashes the
     checkpoint before finalizing, and clients MUST verify the downloaded bytes
     against it.
+    Use :meth:`from_payload` for tolerant response reconstruction; direct typed
+    construction keeps the dataclass's strict keyword surface.
     """
 
     model_id: TrainedModelId
@@ -609,6 +676,18 @@ class ModelRecord:
     created_at: str
     """When the model was finalized (ISO 8601 UTC)."""
 
+    public_id: Optional[ModelPublicId] = None
+    """Human-facing Model ID, or ``None`` when an older producer omitted it."""
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, object]) -> "ModelRecord":
+        """Build from a response mapping while ignoring additive unknown fields."""
+
+        values = known_payload_fields(cls, payload, owner="ModelRecord.from_payload()")
+        if values.get("public_id") is not None:
+            values["public_id"] = parse_model_public_id(values["public_id"])
+        return cls(**values)
+
 
 # --------------------------------------------------------------------------
 # Reserved runtime environment keys

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo-interfaces
-Version: 0.14.0
+Version: 0.15.2
 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.15.2}/src/simulo_interfaces.egg-info/SOURCES.txt

@@ -23,6 +23,7 @@ src/simulo/interfaces/authoring/terrain.py
 src/simulo/interfaces/authoring/visual.py
 src/simulo/interfaces/authoring/world.py
 src/simulo/interfaces/platform/__init__.py
+src/simulo/interfaces/platform/_payload.py
 src/simulo/interfaces/platform/app.py
 src/simulo/interfaces/platform/artifacts.py
 src/simulo/interfaces/platform/asset.py
@@ -31,6 +32,7 @@ src/simulo/interfaces/platform/callbacks.py
 src/simulo/interfaces/platform/debug.py
 src/simulo/interfaces/platform/domain.py
 src/simulo/interfaces/platform/enums.py
+src/simulo/interfaces/platform/job_events.py
 src/simulo/interfaces/platform/manifest.py
 src/simulo/interfaces/platform/policy_bundle.py
 src/simulo/interfaces/platform/runs.py

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

@@ -1,24 +0,0 @@
-"""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.
-"""
-
-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)
-ArtifactId = NewType("ArtifactId", str)  # a job-produced output in the /artifacts projection (Plan B)