Requests and results

Change dataclass

Change(
    edits: tuple[Edit, ...] = (),
    new_revision_id: str | None = None,
    restore_from: str | None = None,
    task: Task = "simulation",
    author: str = "unknown",
)

§5.2: a ChangeSet without expected_revision and idempotency_key.

Those two are commit_change's own parameters, so a Change has no document of its own: its document is the ChangeSet, written by as_change_set and read by from_change_set.

Parameters:

Name	Type	Description	Default
edits	tuple[Edit, ...]	The edits, applied in order to the head revision (Edit).	()
new_revision_id	str | None	The new revision's id; the project assigns rev-<ordinal> when omitted.	None
restore_from	str | None	A revision to restore as the new head instead of editing.	None
task	Task	The task the new revision is validated for.	'simulation'
author	str	Recorded in the revision's provenance.	'unknown'

from_change_set classmethod

from_change_set(
    document: Mapping[str, Any],
) -> tuple[Self, str | None, str]

(change, expected_revision, idempotency_key), omitted members at their defaults.

Edit dataclass

Edit(
    operation: EditOperation,
    path: tuple[str | int, ...],
    value: Any = None,
)

§5.2. set and append carry a value (possibly null); remove carries none.

Parameters:

Name	Type	Description	Default
operation	EditOperation	"set", "append" or "remove".	required
path	tuple[str | int, ...]	The JSON path into the revision document: member names and array indices, for example ("specifications", 4, "value").	required
value	Any	The new value for set and append; omitted for remove.	None

RunResult dataclass

RunResult(
    job_id: str,
    run_id: str | None,
    revision_id: str,
    revision_content_sha256: str,
    policy_id: str,
    policy_sha256: str | None,
    check_policy_sha256: str | None,
    job_status: TerminalStatus,
    outcome: str | None,
    verification_status: VerificationStatus | None,
    structural_sha256: str | None,
    outputs: tuple[ArtifactRef, ...],
    error: ApiError | None = None,
    solve_path: SolvePath = "revision_eo",
    failure: RunFailure | None = None,
)

§5.7: what a solve job produced. job_status is not verification_status.

failure (ADR 0058 D5) is non-null iff outputs holds a failure_bundle; it says why the solve did not converge. error stays the operational failure (R-095). Verification is separate: a CONVERGED run whose certificate is FAILED has no failure.

raise_for_outcome

raise_for_outcome() -> Self

Raise unless the solve ran to its end and wrote no failure bundle; return self, so calls chain (MSG §3.4). An operational error raises ApplicationError; a failure, or a job that did not complete, raises SolveFailedError. Verification is separate: a converged run whose certificate is not VERIFIED does not raise.

RunFailure dataclass

RunFailure(
    outcome: str,
    taxonomy: str,
    message: str | None,
    code: str,
    chain: tuple[str, ...],
    implicated: tuple[str, ...],
    suggested_actions: tuple[str, ...],
    failure_bundle: str,
    params: Mapping[str, Any],
    explanation: Mapping[str, Any],
)

ADR 0058 D5 (MSG §3.4, §4.8): why a solve did not converge, read from its failure bundle.

outcome, taxonomy, message (observations.message, verbatim), implicated (implicated_sources) and suggested_actions (each action) are the stored failure bundle's; code is the explained code and chain the codes outer → inner; params the merged params (a quantity as {value, unit, kind}); failure_bundle the artifact id of failure-bundle.json. Derived on read, never stored; str() is the layered text.

TransactionResult dataclass

TransactionResult(
    status: TransactionStatus,
    revision_id: str | None,
    validation: ValidationReport | None,
    diff: SemanticDiff | None,
    invalidations: tuple[str, ...] = (),
    conflict: Mapping[str, str | None] | None = None,
    idempotency_key: str = "",
    error: ApiError | None = None,
)

§5.2: commit_change's and preview_change's result. rejected carries error.

JobRequest dataclass

JobRequest(
    operation: JobOperation,
    idempotency_key: str,
    body: JobBody,
    budgets: Budgets = Budgets(),
)

§5.3 job.schema.json#/$defs/job_request: the operation selects the body (J3).

request_sha256 property

request_sha256: str

§5.3: SHA-256 of the canonical JSON of the normalized request. Not policy-resolved.

as_document

as_document() -> dict[str, Any]

The normalized request: every optional member written, at its default if omitted.

SolveBody dataclass

SolveBody(
    revision_id: str,
    policy_id: str = DEFAULT_SOLVE_POLICY_ID,
    check_tolerances: Mapping[str, float] = dict(),
    max_property_calls: int | None = None,
    warm_start: WarmStartDeclaration | None = None,
)

§5.3 $defs/solve_body. warm_start (ADR 0070) appears in the document, and so in request_sha256, only when it is declared: a request without it is unchanged.

Job dataclass

Job(
    job_id: str,
    operation: JobOperation,
    request: JobRequest,
    request_sha256: str,
    principal_id: str,
    capability_id: str,
    policy_sha256: str,
    status: JobStatus,
    outputs: tuple[ArtifactRef, ...],
    progress: Progress | None,
    effective_budgets: EffectiveBudgets,
    cancel_requested: bool,
    event_count: int,
    created_at: str,
    started_at: str | None = None,
    ended_at: str | None = None,
    ending: JobEnding | None = None,
    error: ApiError | None = None,
)

§5.5 (J1, J3). completed means the operation ran to its end, never that it verified.

Cross-field rules — the operation is the request's, the status is the ending's, the outputs are the output events' — are the lifecycle checker's (§6.3), not this constructor's, so that the checker can be shown a job that breaks them.

from_document classmethod

from_document(
    document: Mapping[str, Any], *, lenient: bool = False
) -> Self

Strict for a producer; lenient keeps outputs of kinds this code does not know.

JobEvent dataclass

JobEvent(
    job_id: str,
    sequence: int,
    kind: str,
    ends_job: bool,
    recorded_at: str,
    progress: Progress | None = None,
    output: ArtifactRef | None = None,
    ending: JobEnding | None = None,
    error: ApiError | None = None,
    payload: Mapping[str, Any] = dict(),
)

§5.6 (J2, J5, J6). Whether the event ends the job is ends_job, never kind.

For a producer kind, the payload members are exactly its branch's (EVENT_PAYLOAD), and ends_job is the kind's (ENDS_JOB); the constructor refuses anything else. An event of a kind this code does not know exists only as a consumer read it (from_document(lenient=True)): its payload is kept whole in payload, unread.

from_document classmethod

from_document(
    document: Mapping[str, Any], *, lenient: bool = False
) -> Self

Strict: the producer schema. lenient: J5's consumer rule (module docstring).

JobResult dataclass

JobResult(
    operation: JobOperation,
    run_result: RunResult | None,
    replay_report: ReplayReport | None,
    error: ApiError | None,
    experiment: Mapping[str, Any] | None = None,
    surrogate_study: Mapping[str, Any] | None = None,
    optimization: Mapping[str, Any] | None = None,
    display_units: DisplayUnits | None = None,
)

§4.2 as amended by ruling round 1 R4 (job.schema.json#/$defs/job_result).

run_result is present iff the operation is solve (a failed or cancelled solve has one too); replay_report only for a reproduce whose report was produced; error is the job's. experiment (ADR 0033 D9) is an experiment job's answer and only its: the deterministic result, or the last attempt of a transient outcome, or None for a job that ended before any attempt was recorded (cancelled while queued). surrogate_study (ADR 0037 D6) is a surrogate_study job's answer and only its, None when the job ended before its study did. optimization (ADR 0071, OPT design §4.10) is an optimize job's report and only its, None when the job ended without one. display_units (ADR 0075 D7.4–D7.5) is the request's resolved display preference, echoed iff the request carried one; the result's explanations were rendered under it.

JobWait dataclass

JobWait(
    job: Job, events: tuple[JobEvent, ...], ended: bool
)

§4.2: wait_job's result — the job, the events after the caller's sequence, and ended.

SubmitResult dataclass

SubmitResult(job: Job, replayed: bool)

§4.2: submit_job's result. replayed: the key and body matched an existing job.

ProjectSummary dataclass

ProjectSummary(
    project_id: str,
    head: str | None,
    revision_count: int,
    job_counts: Mapping[str, int],
    solve_policies: tuple[tuple[str, str], ...],
    default_policy_id: str,
    principal_id: str,
    capability_id: str,
    rights: tuple[Right, ...],
    limits: Limits,
    server: ServerInfo,
    ambient_pressure: float | None = None,
)

§4.2 get_project: the project, its head and counts, the solve policies it offers, and the caller as the credential makes it — its principal, capability, rights and limits.

ModelRegistryView dataclass

ModelRegistryView(models: tuple[Mapping[str, Any], ...])

§4.2 list_models: each registered model's declarative signature as a document — {model_id, ports, required, zero, pins, choices} — in model-id order, each pin and option with the specifications that pin it (ADR 0019 Amendment 2). Built from the signatures alone; nothing is constructed.

RevisionSummary dataclass

RevisionSummary(
    revision_id: str,
    parent_revision: str | None,
    content_sha256: str,
    title: str | None,
    principal_id: str,
    created_at: str,
    head: bool,
)

§4.2 list_revisions: one stored revision without its document. title is the document's own (untrusted) text, or None when it has no string title.

SemanticDiff dataclass

SemanticDiff(
    added: tuple[str, ...],
    removed: tuple[str, ...],
    changed: tuple[str, ...],
    elements: tuple[DiffElement, ...] | None = None,
)

What changed, by path, in the revision's content — not its title or provenance.

elements is diff_revisions's alone (ADR 0019 Amendment 3, A3.2): None — and absent from the document — in commit_change's and preview_change's TransactionResult.diff, whose schema and ledger replays it does not change.

AuditRecord dataclass

AuditRecord(
    seq: int,
    at: str,
    principal_id: str,
    capability_id: str,
    operation: str,
    outcome: AuditOutcome,
    code: str | None,
    request_sha256: str | None,
    effect: str | None,
    idempotency_key: str | None,
)

ADR 0019 Amendment 3 (A3.3; M06 design note §4.3) list_audit: one row of the project's audit (§10.7) — an effect or a refusal — as the store holds it. effect is <kind>:<id>; idempotency_key is the ledger's key of an allowed row whose principal, operation and request hash it shares (a keyed request's hash covers its key), else None.