osrforge.contracts.run
Run metadata: the run.json contract.
run.json is operational metadata — per-stage status, timestamps, and token
usage for one conversion run. Timestamps are legal here and only here: the pure
artifacts (adventure.json, report.json, previews) must contain none, or
assembly purity's byte-stability guarantee dies.
StageState
module-attribute
StageState = Literal['pending', 'running', 'completed', 'failed']
One stage's lifecycle state.
RunMeta
Bases: BaseModel
The run.json document: source identity, settings echo, and stage table.
osrforge_version
class-attribute
instance-attribute
osrforge_version: str = Field(default_factory=osrforge_version)
with_stage
with_stage(stage: Stage, status: StageStatus) -> RunMeta
Return a copy with one stage's status replaced.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
stage
|
Stage
|
The stage to update. |
required |
status
|
StageStatus
|
Its new status entry. |
required |
Returns:
| Type | Description |
|---|---|
RunMeta
|
A new |
with_model
Return a copy with the provider and model identity set.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
provider
|
str
|
The provider class name, e.g. |
required |
model_id
|
str
|
The model identifier the service returned. |
required |
Returns:
| Type | Description |
|---|---|
RunMeta
|
A new |
Stage
Bases: StrEnum
The pipeline stage names, as run.json wire values.
These key run.json's stage table; changing one is a schema-version event.
They do not name the stages/ cache files — the workdir layout pins
those separately, and only the model-calling stages have caches. Geometry is
deterministic and recomputed inside every assembly rather than cached; its
run.json entry completes inside every assemble(), tracked separately so
a failure in the build leaves an honest geometry: completed.