pixelkiln 0.20.1 → 0.20.2

package/docs/ARCHITECTURE.md

@@ -111,9 +111,15 @@ plan → submit → poll → pick (when needed) → fetch
                     └──────── structural/inline outputs ────────┘
 ```
 
-Remote ids are saved immediately after submission. Generation and download
-failures remain separate, so paid work with a temporary CDN failure is
-recoverable at zero generation cost. Each stage can be rerun independently;
+Remote ids are saved immediately after submission. Providers that need several
+requests for one asset receive a checkpoint callback. Each accepted remote id
+is written before the next request begins. An incomplete checkpoint remains
+submit-actionable; a complete checkpoint is safe to poll even if the provider
+is interrupted before returning. Checkpoints are reused only when provider,
+generator, and resolved spec hash still match.
+
+Generation and download failures remain separate, so paid work with a temporary
+CDN failure is recoverable at zero generation cost. Each stage can be rerun independently;
 `gen` is only their everyday orchestration. Planning maps current `processing`,
 `review`, and `selected`/`download-failed` entries to `poll`, `pick`, and
 `fetch`, respectively.
@@ -200,6 +206,8 @@ uploads manifest-owned PNG/JPEG inputs by content hash, submits an input-bound
 clone, polls local history, and stores portable `comfyui://` output references
 so a lockfile does not retain a workstation hostname or input path. It supports
 `map` candidates and atomic `frames` sets from one still-image output node.
+Each accepted frame prompt is checkpointed in the lockfile, so a retry resumes
+at the first unsubmitted frame instead of queuing the whole set again.
 Frame-set transport, ordered review/fetch, shared-palette refinement,
 step/phase verification, approval, and packing have deterministic integration
 coverage. Live Apple MPS runs cover a small Stable

package/docs/CLI.md

@@ -83,13 +83,17 @@ step. It does not run or approve that step on the user's behalf.
 Queue selected missing/stale generation work without polling it. Enforces the
 provider spacing and concurrency limits, validates estimates at the spending
 boundary, and saves each remote id immediately. Revision inputs are rechecked
-after any queue wait and before a provider request begins.
+after any queue wait and before a provider request begins. For a provider that
+needs several requests per asset, an unchanged incomplete checkpoint resumes
+without repeating requests the provider already accepted.
 
 ### `poll`
 
 Advance submitted jobs to completed, failed, or selection-ready states. It can
 be rerun safely after an interrupted session. When work settles in another
 stage, the command prints the exact next command instead of ending silently.
+An incomplete multi-request checkpoint stays blocked here; rerun `submit` to
+finish it before polling.
 
 ### `pick`
 

package/docs/COMFYUI.md

@@ -219,8 +219,12 @@ The frame count comes from the array, so it cannot disagree with a separate
 count field.
 
 PixelKiln submits one still workflow per value but tracks the result as one
-asset. A partial completion remains in progress. The review page shows an
-animated loop and ordered strip; accepting any frame accepts the whole set.
+asset. After ComfyUI accepts a prompt, PixelKiln saves its id before submitting
+the next frame. An interrupted retry continues at the first missing frame. A
+changed spec starts a fresh set. Incomplete sets cannot be polled into review,
+and one failed render rejects the complete set while retaining every submitted
+prompt id for diagnosis. The review page shows an animated loop and ordered
+strip; accepting any frame accepts the whole set.
 Fetch writes `hero-idle-frame-00.png`, `hero-idle-frame-01.png`, and so on.
 `pack` already turns those role-stable files into a sprite sheet and atlas.
 
@@ -627,8 +631,8 @@ that GPU time, electricity, hosted hardware, or model licenses are free.
 
 When `numImages` is greater than one, `pixelkiln pick` opens the same local
 candidate review used by hosted providers. A `frames` job always opens an
-ordered, animated whole-set review. The lockfile stores the ComfyUI
-prompt ID, output node, workflow hash, and selected output. Durable source
+ordered, animated whole-set review. The lockfile stores every accepted ComfyUI
+prompt id, the expected frame count, output node, workflow hash, and selected output. Durable source
 references use `comfyui://` rather than embedding a workstation hostname.
 `pixelkiln restore` first uses the validated local content cache, then resolves
 the portable reference against the current `COMFYUI_BASE_URL`.

package/docs/LIBRARY.md

@@ -57,8 +57,8 @@ and optional strength. Paths are excluded from the hash; input bytes are not.
 
 `resumeActions` groups current paid-work states into `poll`, `pick`, and
 `fetch`. It ignores stale specs and entries missing the remote id needed by
-their stage, so integrations can offer safe continuation without implying that
-a new submission is required.
+their stage. It also excludes incomplete multi-request checkpoints; those
+remain actionable in `buildPlan` and must return through `submit`.
 
 For custom orchestration, inspect the dependency gate directly:
 
@@ -284,6 +284,14 @@ every byte or scalar that can change provider output and must exclude
 machine-local paths or credentials. Providers that omit the hook fail closed
 when an asset declares non-empty `providerInputs`.
 
+`Provider.submit` receives an optional third `SubmitContext` argument. A custom
+provider that needs several remote mutations for one asset should call
+`await context.checkpoint({ jobId, metadata, complete })` after each accepted
+mutation and before starting the next one. PixelKiln persists that checkpoint
+atomically. On an unchanged retry, `previousJobId` and `previousMetadata` let
+the provider continue from the first missing request. Set `complete: true` only
+when the returned job id is safe to poll as the complete asset.
+
 These low-level operations intentionally accept one provider. A mixed-provider
 caller should partition specs and plan items by `spec.provider`, instantiate
 each adapter independently, and preserve the provider recorded on a lock entry

package/docs/RECOVERY.md

@@ -23,7 +23,8 @@ Use the lock state rather than guessing which stage to rerun:
 
 | State | Safe next command |
 |---|---|
-| `pending` or `processing` | `pixelkiln poll` |
+| incomplete submission checkpoint | `pixelkiln submit` |
+| complete `pending` or `processing` submission | `pixelkiln poll` |
 | `review` | `pixelkiln pick` |
 | `selected` or `download-failed` | `pixelkiln fetch` |
 | downloaded output is missing | `pixelkiln restore` |
@@ -36,6 +37,14 @@ still refused; after inspecting it, `pixelkiln fetch --force` explicitly lets
 the new result take ownership. This also recovers interrupted jobs created by
 older PixelKiln versions that could not retain the prior output hash.
 
+ComfyUI frame sets submit one prompt per frame. PixelKiln saves the compound
+job after every accepted prompt, before asking ComfyUI to queue the next one.
+If submission stops halfway through, `plan` reports the saved checkpoint and
+`pixelkiln submit` continues at the first missing frame. `poll` will not advance
+an incomplete set into review. A changed prompt, workflow, input image, seed
+schedule, or other spec identity starts a fresh set instead of appending to old
+prompt ids.
+
 Provider adapters should keep expiring signed result URLs transient and store a
 provider-neutral reference that can refresh them. Once ingestion succeeds,
 PixelKiln removes credential-bearing URLs, inline data URLs, and local file URLs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixelkiln",
-  "version": "0.20.1",
+  "version": "0.20.2",
   "description": "Manifest-driven pixel-art generation, review, recovery, and packaging with deterministic provenance.",
   "type": "module",
   "sideEffects": false,