Job lifecycle

View Markdown llms-full.txt

Every SimReady conversion follows the lifecycle below. A conversion starts from either an uploaded 3D file or a prototype submitted by Asset Composer. Simulation jobs reuse the same job envelope.

Asset Composer has a separate workflow envelope because planning and prototype generation happen before conversion. See SimReady Asset Composer for its statuses and stages; after submission, conversion_job_id links to the lifecycle below.

Status flow

submitting ──► preprocessing ──► queued ──► running ──► completed
                                                    └─► failed

Status	Meaning
`submitting`	Initial state — file being staged. Usually invisible to clients.
`preprocessing`	Non-GLB input is being converted to a clean GLB on the makina-worker.
`queued`	Submitted to the SimReady pipeline, waiting for a runner.
`running`	Pipeline is actively processing (export → align → physics → collision → USD).
`completed`	Done. `output.model.url` is ready. `credits_charged` records the actual cost.
`failed`	Something went wrong. `error` is populated. Any paid charge is auto-refunded.

GLB inputs skip the preprocessing state and go straight to queued.

What does and does not reach `failed`

A SimReady conformance failure does not fail the job or affect billing. A non-conformant asset is still delivered with status: "completed"; the verdict rides along in report.validation, which is where you check it. See SimReady Validation.

What reaches failed is a correctness problem — a statement about our own output rather than about the specification:

the USD and the MJCF disagree about the asset they describe
an internal invariant is violated
an export is missing or unwritable
an input manifest does not match the mesh it describes

Plus the ordinary infrastructure cases: a malformed upload, an unreachable upstream, a pipeline crash.

Progress and stage

progress is 0-100. stage is a free-form string identifying the current pipeline step (e.g. "export", "physics", "collision_decompose"). Don’t pattern-match on stage — treat it as a hint for human-readable progress UI.

Preprocessing component

When the input is non-GLB, the response includes a preprocess block:

{
  "preprocess": {
    "status": "completed",
    "steps": ["export", "align", "transform", "compress", "process"],
    "started_at": "2026-05-06T12:00:05.000Z",
    "completed_at": "2026-05-06T12:00:42.000Z",
    "error": null,
    "input_stats": { "vertex_count": 12345, "face_count": 6789, "...": "..." },
    "telemetry": { "duration_ms": 37123, "...": "..." },
    "intermediate_glb": {
      "url": "https://assets.rigyd.com/.../intermediate.glb",
      "name": "intermediate.glb"
    }
  }
}

preprocess.status enum: skipped · pending · running · completed · failed. For GLB inputs status === "skipped" and the rest of the block is null.

Full payload shape

{
  "data": {
    "id": "abc123...",
    "physiq_job_id": "phy_...",
    "status": "completed",
    "filename": "toolbox.glb",
    "file_size_bytes": 1245678,
    "stage": "export",
    "progress": 100,
    "error": null,
    "timing": {
      "queued_at": "...",
      "started_at": "...",
      "completed_at": "..."
    },
    "parameters": {
      // Conversion settings and provenance, including composition_id when applicable
    },
    "report": {
      // pipeline.*    — mass, friction, inertia, collision, timing
      // validation.*  — SimReady conformance. Badge `validation.profiles_passing`;
      //                 `validation.spec_release` names the spec release scored against
      // invariants.*  — our own correctness checks; `ok` is always true on a delivered asset
    },
    "job_type": "glb_to_simready",
    "credits_charged": 0,
    "input": {
      "model": { "url": "...", "name": "toolbox.glb" },         // 3D submissions
      "images": [{ "url": "...", "name": "front.jpg" }],         // Composer references/captures
      "metadata": null                                            // Set for ZIP uploads
    },
    "preprocess": { /* see above */ },
    "output": {
      "model":        { "url": "...", "name": "toolbox.usd", "size": 982341 },
      "textures":     [{ "url": "...", "name": "diffuse.png" }],
      "mjcf_package": { "url": "...", "name": "toolbox-mjcf.zip", "size": 1234 },
      "sim_video":    null,  // populated on simulate_usd jobs
      "sim_gif":      null,
      "sim_log":      null
    },
    "source_job":  null,    // populated on simulate_usd jobs (points back at the parent)
    "simulations": [],      // simulations[] of this job (children)
    "createdAt":   "2026-05-06T12:00:00.000Z",
    "updatedAt":   "2026-05-06T12:01:32.000Z"
  }
}

Billing on failure

Direct conversion and simulation currently report credits_charged: 0. Asset Composer charges for prototype generation separately; a prototype-generation or rendering failure is refunded once, but a later free conversion failure does not reverse the completed prototype charge. See Pricing.