exlab_wizard.api.schemas

msgspec.Struct types for the ExLab-Wizard cache files.

This module is the single source of truth for the on-disk JSON schemas documented in design spec §11.3 (creation.json), §11.4 (readme_fields.json), §11.4.1 (equipment.json), §11.4.2 (test_runs.json), and §13.4 (ingest.json). Every cache reader and writer in the codebase round-trips its bytes through these Struct types via msgspec.json.decode(blob, type=...) / msgspec.json.encode(obj); schema validation happens during decode in one pass.

Design choices that affect every Struct in this module:

• frozen=False – a few fields on CreationJson (sync_status, validation_overrides) are mutated in place by CreationWriter after the initial write (Backend Spec §4.4.5; §11.3 “mutated in place” note).

• omit_defaults=True – field values that equal their declared default are omitted from the encoded JSON. Keeps writes compact and matches the on-disk shape shown in spec §11.3 (no nullable-but-null fields, no empty arrays for unused sub-blocks).

• forbid_unknown_fields=False – unknown fields are silently preserved on round-trip via the writer’s raw_extras mechanism in cache/creation_writer.py. This is required by §11.9.3 writer policy rule 2: a v0.7 writer mutating a file written by a v0.8 writer MUST NOT drop the v0.8 fields it doesn’t recognize.

The validation_overrides field is typed as list[dict[str, Any]] rather than list[OverrideEntry | TombstoneEntry] because msgspec struct unions require an explicit tag (tag or tag_field) and the discriminator the spec mandates – the boolean revoked flag – cannot be used as a tag (msgspec tags must be strings or ints). Helpers override_entry_to_dict, tombstone_entry_to_dict, and parse_validation_override_entry bridge the wire form (dict) and the typed form (Struct) for callers that want either representation.

Functions

override_entry_to_dict(entry)	Serialize an OverrideEntry to a wire-form dict.
parse_validation_override_entry(entry)	Inspect entry["revoked"] and entry["revokes"] to decide which Struct shape to convert into.
tombstone_entry_to_dict(entry)	Serialize a TombstoneEntry to a wire-form dict.

Classes

CreationJson(schema_version, created_at, ...)	Top-level creation.json payload at schema version 1.8.
EquipmentJson(schema_version, id, label, ...)	equipment.json at schema version 1.0.
LimsProjectBlock(uid, short_id, name_at_creation)	LIMS-side project identity captured at creation time.
OrchestratorBlock(enabled, host, label[, ...])	Orchestrator-mode metadata.
OverrideEntry(id, problem_class, operator, ...)	Operator-recorded validation override entry.
PathsBlock(local, nas)	Resolved on-disk paths captured at creation time.
PluginApplied(plugin, version, ...[, isolation])	Per-plugin invocation record written into plugins_applied.
PluginIsolation(duration_ms, exit_code, ...)	Plugin worker isolation telemetry.
ReadmeFieldsJson(schema_version, ...)	readme_fields.json at schema version 1.1.
TemplateBlock(name, version, source_path[, ...])	Template provenance captured at creation time.
TestRunsJson(schema_version, created_at, ...)	test_runs.json marker at schema version 1.0.
TombstoneEntry(id, revokes, operator, ...[, ...])	Tombstone entry that revokes a prior override by id.

class exlab_wizard.api.schemas.CreationJson(schema_version: str, created_at: str, created_by: str, level: ~exlab_wizard.constants.enums.CreationLevel, run_kind: ~exlab_wizard.constants.enums.RunKind, lims_project: ~exlab_wizard.api.schemas.LimsProjectBlock, template: ~exlab_wizard.api.schemas.TemplateBlock, variables: dict[str, ~typing.Any], paths: ~exlab_wizard.api.schemas.PathsBlock, plugins_applied: list[~exlab_wizard.api.schemas.PluginApplied] = <factory>, orchestrator: ~exlab_wizard.api.schemas.OrchestratorBlock | None = None, sync_status: ~exlab_wizard.constants.enums.SyncStatus = SyncStatus.PENDING, validation_overrides: list[dict[str, ~typing.Any]] = <factory>)

Bases: Struct

Top-level creation.json payload at schema version 1.8.

Reading: msgspec.json.decode(blob, type=CreationJson) validates every required field and rejects type errors in one pass. Unknown fields are silently ignored at the Struct boundary; the writer re-serializes them via cache/creation_writer.py’s extras pass so forward-compat is preserved.

Writing: every write goes through CacheWriter; direct msgspec.json.encode(payload) calls are reserved for tests and for the writer’s tempfile pass.

created_at: str

created_by: str

level: CreationLevel

lims_project: LimsProjectBlock

orchestrator: OrchestratorBlock | None

paths: PathsBlock

plugins_applied: list[PluginApplied]

run_kind: RunKind

schema_version: str

sync_status: SyncStatus

template: TemplateBlock

validation_overrides: list[dict[str, Any]]

variables: dict[str, Any]

class exlab_wizard.api.schemas.EquipmentJson(schema_version: str, id: str, label: str, configured_local_root: str, configured_nas_root: str, first_seen_at: str, last_modified_at: str)

Bases: Struct

equipment.json at schema version 1.0. Spec §11.4.1.

configured_local_root: str

configured_nas_root: str

first_seen_at: str

id: str

label: str

last_modified_at: str

schema_version: str

class exlab_wizard.api.schemas.FileSyncRecord(synced_signature: tuple[int, int] | None = None, verified_at: str | None = None, keep_local: bool = False, verified_sha256: str | None = None)

Bases: Struct

Per-file sync record stored under sync_state.json’s files map.

One record per run-relative POSIX path. These records are freely mutated in place by SyncStateWriter as a file is synced, re-modified, and re-synced.

• synced_signature – the (st_size, st_mtime_ns) captured at the last successful sync. None means the file has never synced. A file whose current signature differs is “modified since sync” and becomes eligible again once it re-settles.

• verified_at – the ISO-8601 timestamp at which the file’s SHA-256 was confirmed against the NAS copy. None until verified; a file counts toward the SYNCED rollup only once this is set.

• keep_local – when True the file still syncs to the NAS but is excluded from cleanup deletion.

• verified_sha256 – the SHA-256 hex digest of the local bytes captured at sync time. Slot A of the 2026-05-26 rclone-only migration: rclone check --download --combined confirms the NAS copy matches the local source, and we record the local SHA here so the offline-audit affordance lost by dropping checksums.sha256 is preserved without any wire cost. None for records that pre-date the migration or for files synced via the legacy verify path; reads must tolerate its absence.

keep_local: bool

synced_signature: tuple[int, int] | None

verified_at: str | None

verified_sha256: str | None

class exlab_wizard.api.schemas.LimsProjectBlock(uid: str, short_id: str, name_at_creation: str, source: LIMSProjectSource = LIMSProjectSource.LIVE, cache_freshness_at_use: str | None = None)

Bases: Struct

LIMS-side project identity captured at creation time. Spec §11.3.

Required on project- and run-level creation.json files at schema version >= 1.5. source and cache_freshness_at_use were added in 1.8; on a 1.7 file they are absent and read as "live" / None per the migration policy in §11.9.2.

cache_freshness_at_use: str | None

name_at_creation: str

short_id: str

source: LIMSProjectSource

uid: str

class exlab_wizard.api.schemas.OrchestratorBlock(enabled: bool, host: str, label: str, equipment_label: str | None = None)

Bases: Struct

Orchestrator-mode metadata. Spec §11.3 / §13 / Redesign Spec §3.3.

Always present on a v1 creation.json; the redesign collapses the single-equipment / orchestrator distinction into a per-equipment sync role and the orchestrator block always carries the producing device’s identity.

The equipment_label field travels with the push so the receiving orchestrator can auto-discover received equipment (Redesign Spec §3.3) without a per-equipment registry of its own. It is optional for forward-compat with creation.json files written by earlier writers. The former completeness-signal relay fields were removed by the operator-free quiescence-sync redesign (2026-05-21).

enabled: bool

equipment_label: str | None

host: str

label: str

class exlab_wizard.api.schemas.OverrideEntry(id: str, problem_class: str, operator: str, recorded_at: str, reason: str, revoked: bool = False, expires_at: str | None = None)

Bases: Struct

Operator-recorded validation override entry. Spec §11.3.

revoked is False on every override entry. The default is kept for ergonomic construction; the writer helper override_entry_to_dict ensures the field is always present on the wire (the spec requires it on every entry).

expires_at: str | None

id: str

operator: str

problem_class: str

reason: str

recorded_at: str

revoked: bool

class exlab_wizard.api.schemas.PathsBlock(local: str, nas: str)

Bases: Struct

Resolved on-disk paths captured at creation time. Spec §11.3.

local: str

nas: str

class exlab_wizard.api.schemas.PluginApplied(plugin: str, version: str, files_affected: list[str], status: PluginStatus, isolation: PluginIsolation | None = None)

Bases: Struct

Per-plugin invocation record written into plugins_applied.

Spec §6.2.4 / §11.3. isolation was added in schema version 1.3; older readers ignore it and older writers treat its absence as a no-op.

files_affected: list[str]

isolation: PluginIsolation | None

plugin: str

status: PluginStatus

version: str

class exlab_wizard.api.schemas.PluginIsolation(duration_ms: int, exit_code: int, peak_memory_mb: int)

Bases: Struct

Plugin worker isolation telemetry. Spec §6.2.4 / §11.3 (added 1.3).

duration_ms: int

exit_code: int

peak_memory_mb: int

class exlab_wizard.api.schemas.ReadmeFieldsJson(schema_version: str, generated_at: str, core_fields: dict[str, str], system_fields: dict[str, ~typing.Any], template_fields: dict[str, ~typing.Any] = <factory>, config_fields: dict[str, ~typing.Any] = <factory>, custom_fields: list[dict[str, str]] = <factory>)

Bases: Struct

readme_fields.json at schema version 1.1. Spec §11.4.

config_fields: dict[str, Any]

core_fields: dict[str, str]

custom_fields: list[dict[str, str]]

generated_at: str

schema_version: str

system_fields: dict[str, Any]

template_fields: dict[str, Any]

class exlab_wizard.api.schemas.SyncStateJson(schema_version: str, cleared_at: str | None = None, files: dict[str, ~exlab_wizard.cache.sync_state_schema.FileSyncRecord]=<factory>)

Bases: Struct

sync_state.json per-run sync-state record at schema version 1.0.

Written by the orchestrator only. A freely-mutable current-state map (not append-only): files maps a run-relative POSIX path to its FileSyncRecord. cleared_at is set once the run’s staging copy has been cleaned up. The run-level SYNCING/SYNCED/CLEARED rollup is derived on read from this payload, never persisted as such.

cleared_at: str | None

files: dict[str, FileSyncRecord]

schema_version: str

class exlab_wizard.api.schemas.TemplateBlock(name: str, version: str, source_path: str, run_scope: RunScope | None = None, provenance_path: str = '')

Bases: Struct

Template provenance captured at creation time. Spec §11.3.

name: str

provenance_path: str

run_scope: RunScope | None

source_path: str

version: str

class exlab_wizard.api.schemas.TestRunsJson(schema_version: str, created_at: str, project: str, equipment: str, run_kind: RunKind = RunKind.TEST)

Bases: Struct

test_runs.json marker at schema version 1.0. Spec §11.4.2.

Filename retained from v0.5 for backward compatibility even though the parent folder was renamed to TestRuns/ in v0.6.

created_at: str

equipment: str

project: str

run_kind: RunKind

schema_version: str

class exlab_wizard.api.schemas.TombstoneEntry(id: str, revokes: str, operator: str, recorded_at: str, reason: str, revoked: bool = True)

Bases: Struct

Tombstone entry that revokes a prior override by id. Spec §11.3.

revoked is True on every tombstone. The default is kept for ergonomic construction; the writer helper tombstone_entry_to_dict ensures the field is always present on the wire.

id: str

operator: str

reason: str

recorded_at: str

revoked: bool

revokes: str

exlab_wizard.api.schemas.override_entry_to_dict(entry)

Serialize an OverrideEntry to a wire-form dict.

Uses msgspec.structs.asdict so that revoked (which equals its default of False on every override) is included. Spec §11.3 requires the field on every entry.

Parameters:

entry (OverrideEntry)

Return type:

dict[str, Any]

exlab_wizard.api.schemas.parse_validation_override_entry(entry)

Inspect entry["revoked"] and entry["revokes"] to decide which Struct shape to convert into.

The spec says tombstones carry revoked: True AND a revokes pointer; overrides carry revoked: False AND a problem_class. Use revoked first, revokes as a tiebreaker for old files (pre-1.6) where revokes may have been the only discriminator.

Parameters:

entry (dict[str, Any])

Return type:

OverrideEntry | TombstoneEntry

exlab_wizard.api.schemas.tombstone_entry_to_dict(entry)

Serialize a TombstoneEntry to a wire-form dict. Mirrors override_entry_to_dict; revoked is always emitted.

Parameters:

entry (TombstoneEntry)

Return type:

dict[str, Any]