Jobs and delivery truth

When no node is online

The control plane durably retains the job. An eligible node claims it after reconnecting, writes the claim and document reference into its local SQLite queue, then acknowledges ownership. Expiry and cancellation still apply while offline.

Large documents

Upload binary content directly to object storage using the SDK. The SDK computes SHA-256, sends no Piqae credential to the signed upload URL, and verifies the upload before job creation. The hosted V1 limit is 50 MiB per document; stream from disk in production when the runtime supports it.

Idempotency

Use one stable key for one logical print. Retrying an identical request returns the original job. Reusing the key with different content returns a conflict.

await customer.printPdf({
  printerId,
  title: 'Packing slip',
  pdf,
  idempotencyKey: `order-${order.id}-packing-slip-v1`
});

Lifecycle

• registered: the service durably owns the job.
• agent_accepted: one node durably owns a local copy.
• accepted_by_spooler: the operating-system queue accepted the submission.
• completed_reported: the OS reports completion; physical output may remain unknowable.
• delivery_uncertain: a crash crossed the handoff boundary and automatic retry could duplicate output.