pixelkiln 0.12.0 → 0.13.0

package/CONTRIBUTING.md

@@ -15,6 +15,7 @@ npm ci
 npm run test:release
 npm run typecheck
 npm run test:docs
+npm run test:security
 npm test
 npm run build
 npm run test:package
@@ -72,6 +73,9 @@ wire contracts.
   workflow detail in `docs/`, and link every guide from `docs/README.md`.
 - Run `npm run test:docs` after changing Markdown or the CLI command/flag
   surface. It checks local links, the docs index, README size, and CLI coverage.
+- Run `npm run test:security` after changing provider source handling, lockfile
+  fixtures, or benchmark state. It scans tracked JSON without printing a
+  credential-bearing value.
 - Run the website lint and build checks when changing `website/` or the
   canonical Markdown it renders.
 - Run the package smoke test when changing exports, build configuration, the
@@ -85,6 +89,8 @@ wire contracts.
   I/O and estimates must carry their cost unit.
 - Provider responses are untrusted input and need runtime validation before
   entering the lockfile.
+- Temporary signed URLs must not settle in a committed lockfile. Persist a
+  refreshable provider reference and keep storage credentials transient.
 - Lockfile writes must remain atomic and resumable. Additive defaults should
   preserve valid v2 files when extending lock entries.
 - Unknown flags and ambiguous output selection are errors. Silent widening is

package/PROVIDERS.md

@@ -1,13 +1,13 @@
 # Provider comparison
 
-PixelKiln can run one manifest through PixelLab, Retro Diffusion, or a
-self-hosted ComfyUI server. Planning, budgets, review, recovery, and packaging
-stay the same. Each adapter handles its service's authentication, prices,
-request lifecycle, and file formats.
+PixelKiln can route one manifest through PixelLab, Retro Diffusion, and a
+self-hosted ComfyUI server. Planning, review, recovery, and packaging stay the
+same. Each adapter handles its service's authentication, prices, request
+lifecycle, and file formats.
 
 PixelLab remains the default so existing manifests and spec hashes remain
-compatible. Select another backend with the manifest's top-level `provider`
-field and keep its settings under the matching `providerOptions` key.
+compatible. The manifest's top-level `provider` is the default; a style may
+override it. Keep service settings under the matching `providerOptions` key.
 
 To configure a project, use [Set up PixelLab](./docs/PIXELLAB.md),
 [Set up Retro Diffusion](./docs/RETRO_DIFFUSION.md), or
@@ -26,6 +26,8 @@ them.
 Live tests now cover single-candidate RD Fast and RD Plus stills from cost quote
 through submit, poll, PNG download, lockfile provenance, and cache validation.
 The RD Plus run covered isometric-asset, top-down-asset, and environment styles.
+Lockfiles retain refreshable `retrodiffusion://` result references rather than
+temporary signed storage URLs.
 Retro Diffusion's multi-candidate review, tileset, GIF, and spritesheet paths
 have mocked integration coverage but still need representative paid live runs.
 
@@ -113,58 +115,36 @@ repeatable.
 
 ## Use multiple providers in one project
 
-One manifest selects one provider. PixelKiln does not currently support a
-provider override on an individual style or asset. The boundary is deliberate:
-one command constructs one account adapter, and one `--budget` must have one
-meaning. PixelLab generations and Retro Diffusion dollars cannot share a safe
-ceiling.
-
-A repository can still use multiple providers today. Give each provider its own
-manifest, lockfile, and output directory:
-
-```text
-art/
-  pixelkiln.pixellab.manifest.json
-  pixelkiln.pixellab.lock.json
-  pixelkiln.retrodiffusion.manifest.json
-  pixelkiln.retrodiffusion.lock.json
-  pixelkiln.comfyui.manifest.json
-  pixelkiln.comfyui.lock.json
-pixelkiln.workspace.json
-```
-
-Plan and authorize each manifest separately:
+Set a provider on any style that differs from the manifest default. Planning
+and confirmations remain grouped by provider and unit, so PixelLab generations
+and Retro Diffusion dollars are never added together. A mixed run takes a
+separate named ceiling for each paid provider; the free group may be explicit:
 
 ```bash
-pixelkiln plan --manifest art/pixelkiln.pixellab.manifest.json --lock art/pixelkiln.pixellab.lock.json
-pixelkiln gen --manifest art/pixelkiln.pixellab.manifest.json --lock art/pixelkiln.pixellab.lock.json --budget <generations>
+pixelkiln plan
+pixelkiln gen \
+  --budget pixellab=12 \
+  --budget retrodiffusion=0.20 \
+  --budget comfyui=0
+```
 
-pixelkiln plan --manifest art/pixelkiln.retrodiffusion.manifest.json --lock art/pixelkiln.retrodiffusion.lock.json
-pixelkiln gen --manifest art/pixelkiln.retrodiffusion.manifest.json --lock art/pixelkiln.retrodiffusion.lock.json --budget <usd>
+The same lockfile records which provider accepted each item. Resumed polling,
+review, download, restore, and tagging follow that recorded provider. Account
+operations such as `balance`, `adopt`, `salvage`, and `purge` require an
+explicit `--provider` in a mixed manifest.
 
-pixelkiln plan --manifest art/pixelkiln.comfyui.manifest.json --lock art/pixelkiln.comfyui.lock.json
-pixelkiln gen --manifest art/pixelkiln.comfyui.manifest.json --lock art/pixelkiln.comfyui.lock.json --budget 0
-```
+This works well when PixelLab handles prompt-sensitive buildings and account
+recovery, Retro Diffusion handles environment-styled backdrops, clean cutouts,
+or native animation, and ComfyUI handles private or project-specific model
+experiments that can absorb manual cleanup. Retro Diffusion is not a
+higher-resolution route through PixelKiln today: its useful environment styles
+cap at 384×384, while PixelLab `map` reaches 400×400. Its advantage is the
+model/style and output type, not raw dimensions.
 
-Register the manifests in the workspace catalog for aggregate status and
-complete claim checks. Keep the provider lockfiles separate. Package their
-reviewed outputs independently, or combine explicit files with `pixelkiln pack
---inputs <file> --out <path>`.
-
-This split works when PixelLab handles prompt-sensitive buildings and
-account recovery, Retro Diffusion handles environment-styled backdrops, clean
-cutouts, or native animation, and ComfyUI handles private or project-specific
-model experiments that can absorb manual cleanup. Retro Diffusion is not a higher-resolution
-route through PixelKiln today: its useful environment styles cap at 384×384,
-while PixelLab `map` reaches 400×400. Its advantage is the model/style and
-output type, not raw dimensions.
-
-Native mixed-provider support inside one manifest would be a larger feature,
-not a schema-only change. It needs provider selection on each style, plans and
-confirmations grouped by provider and cost unit, separate budget ceilings,
-per-provider polling and downloads, and an explicit provider for account-wide
-commands. The lockfile already records a provider on every entry, so the state
-format can support that direction without merging provider identities.
+See [Mixed-provider projects](./docs/MIXED_PROVIDERS.md) for the manifest,
+budget, recovery, and account-command contract. Separate manifests remain a
+good boundary when different teams, credentials, or release schedules should
+not share one runtime.
 
 ## Cost comparison
 
@@ -199,8 +179,8 @@ The provider boundary owns behavior that differs between services:
 - downloads and optional account capabilities such as balance, listing,
   tagging, and deletion.
 
-Planning groups costs by unit instead of adding incompatible values. A budget
-is interpreted in the active provider's unit. Providers without a balance or
+Planning groups costs by provider and unit instead of adding incompatible
+values. Mixed runs use provider-keyed ceilings. Providers without a balance or
 account-management endpoint can still generate safely because the offline
 estimate and hard budget remain enforced.
 
@@ -212,12 +192,10 @@ and the approval record work. The tested SDXL plus Pixel Art XL graph can find
 a composition, but it is not a production preset. Background removal stays in
 the graph. A person must still check the brief, pixel clusters, and drawing.
 
-Native per-style provider routing remains the highest-value orchestration
-feature. One manifest should be able to send a building style to PixelLab, an
-animation style to Retro Diffusion, and a private model workflow to ComfyUI.
-That requires provider-keyed budgets and confirmations, independently
-rate-limited adapters, and an explicit provider for account-wide commands. The
-lockfile already records the provider on each entry.
+Per-style provider routing now lets one manifest send a building style to
+PixelLab, an animation style to Retro Diffusion, and a private model workflow
+to ComfyUI. Provider-keyed budgets, independent orchestration, lock-authoritative
+recovery, and explicit account-provider selection ship with it.
 
 Scenario remains the best next hosted provider candidate. The implementation
 scope and acceptance criteria are tracked in
@@ -239,16 +217,14 @@ captured before submission.
 
 Recommended order from here:
 
-1. Benchmark pinned ComfyUI models and prompt patterns across at least two scene
-   families. Reject any supposed improvement that helps only one subject.
-2. Add per-style provider selection, provider-keyed budgets, and mixed-provider
-   integration tests.
-3. Finish live Retro Diffusion multi-candidate, tileset, GIF, and spritesheet
+1. Finish live Retro Diffusion multi-candidate, tileset, GIF, and spritesheet
    smoke tests.
-4. Build the Scenario still-image spike from issue #52 with dry-run cost, submit, poll,
+2. Build the Scenario still-image spike from issue #52 with dry-run cost, submit, poll,
    download, and one custom-model or reference-image benchmark.
-5. Design ComfyUI Cloud as a separate authenticated and billable adapter.
-6. Consider general raster marketplaces only with explicit nearest-neighbor,
+3. Benchmark another pinned ComfyUI model and prompt pattern across at least two
+   scene families. Reject any improvement that helps only one subject.
+4. Design ComfyUI Cloud as a separate authenticated and billable adapter.
+5. Consider general raster marketplaces only with explicit nearest-neighbor,
    palette, transparency, and reproducibility checks.
 
 Midjourney is not an adapter target without an official public API. Automating

package/README.md

@@ -21,7 +21,8 @@ Plus stills; its multi-candidate, tileset, GIF, and spritesheet paths are tested
 with fixtures but still need paid live runs. ComfyUI has passed local generation,
 four-candidate review, cache recovery, and native-grid refinement on Apple MPS.
 Its tested SDXL workflow can find a composition, but it is not a finished
-pixel-art preset. The [provider comparison](./PROVIDERS.md) lists the tested
+pixel-art preset. Styles in one manifest may use different providers with
+separate budget ceilings. The [provider comparison](./PROVIDERS.md) lists the tested
 limits and the best route for buildings and environments. `FakeProvider` covers
 the same contract in automated tests.
 
@@ -54,10 +55,10 @@ PixelKiln keeps the missing record:
 
 | Workflow | What PixelKiln provides |
 |---|---|
-| Plan and budget | Offline manifest/lock/disk diff, provider-unit estimates, hard `--budget` ceiling, JSON/CI gate. |
+| Plan and budget | Offline manifest/lock/disk diff, provider-grouped estimates, keyed mixed-provider budget ceilings, JSON/CI gate. |
 | Generate and review | Resumable submit/poll/pick/fetch pipeline with a fast local candidate sheet. |
 | Existing-art onboarding | Manifest scaffolding, exact-hash account adoption, and prompt recovery. |
-| Recovery | Validated local content cache, provider URL restore, account object-hash cache, and resumable jobs. |
+| Recovery | Validated local content cache, durable provider-reference restore, account object-hash cache, and resumable jobs. |
 | Shared-account safety | Cross-project claim files or a registered workspace catalog, sibling-style exclusion, reviewed salvage, keep/discard tags, separate confirmed purge. |
 | Quality control | Palette distance, transparency, color-count, relative outlier, cache-integrity, and doctor gates. |
 | Sprite packaging | Deterministic RGBA packing, stable-cell mounting, explicit external input lists, structural output roles. |
@@ -138,7 +139,8 @@ See [Getting started](./docs/GETTING_STARTED.md) for new and existing projects.
 Use [Set up PixelLab](./docs/PIXELLAB.md),
 [Set up Retro Diffusion](./docs/RETRO_DIFFUSION.md), or
 [Set up ComfyUI](./docs/COMFYUI.md) for provider-specific configuration,
-manifest examples, and current limits.
+manifest examples, and current limits. See [Mixed-provider projects](./docs/MIXED_PROVIDERS.md)
+when styles in one manifest need different backends.
 
 ## Agent skill
 
@@ -335,16 +337,14 @@ import {
   buildPlan,
   loadLock,
   loadManifest,
-  PixelLabProvider,
   resolveSpecs,
 } from "pixelkiln"
 
 const loaded = await loadManifest("pixelkiln.manifest.json")
-const provider = PixelLabProvider.forOffline()
-const specs = await resolveSpecs(loaded, { provider })
+const specs = await resolveSpecs(loaded)
 const plan = await buildPlan(specs, await loadLock("pixelkiln.lock.json"))
 
-console.log(plan.cost, plan.costUnit, plan.actionable.length)
+console.log(plan.groups, plan.actionable.length)
 ```
 
 The package also exports audit and image-regression gates, provider-neutral refinement, lock/output
@@ -364,6 +364,7 @@ exporters, managed artifact writes, and offline provenance verification. See
 | [Versioned recipes](./docs/RECIPES.md) | Pinned workflow packs, model hashes, manifest templates, and quality contracts. |
 | [CLI reference](./docs/CLI.md) | Every command, flag, JSON mode, and exit contract. |
 | [Manifest reference](./docs/MANIFEST.md) | Every style/asset field and generator constraint. |
+| [Mixed-provider projects](./docs/MIXED_PROVIDERS.md) | Per-style routing, provider-keyed budgets, recovery, and account commands. |
 | [Agent workflows](./docs/AGENTS.md) | Official skill install, operating model, and provider-aware safety. |
 | [Generators](./docs/GENERATORS.md) | Capability choice, measured costs, palettes, style references, and tiles. |
 | [Environment provider benchmark](./docs/PROVIDER_BENCHMARK.md) | Thirty provider outputs plus native-grid and final-palette results comparing large scenes, transparency, palette size, and file readiness. |

package/SECURITY.md

@@ -29,10 +29,19 @@ reporter.
 
 PixelKiln handles provider credentials, paid API actions, remote object deletion,
 local output paths, a localhost review server, and generated HTML containing
-provider data. Reports involving authentication leakage, path traversal,
+provider data. Temporary provider result URLs can also contain signing
+credentials in their query string. Reports involving authentication leakage, path traversal,
 cross-origin review actions, HTML/script injection, unsafe overwrite/delete
 behavior, lockfile corruption, or budget bypass are security relevant.
 
 Never attach a real `PIXELLAB_API_KEY`, `RD_API_KEY`, `.env` file, private
 provider URL, or unredacted lockfile from a confidential project to a public
 report.
+
+PixelKiln keeps durable provider references in lockfiles when an adapter can
+refresh an expiring result. After successful ingestion it removes signed URLs,
+inline data URLs, and local file URLs from settled lock entries. A failed
+download may retain its source locally so `fetch` can retry, but that in-flight
+lockfile should not be committed. `npm run test:security` checks every tracked
+JSON file for credential-bearing URLs and reports only the file and JSON path,
+never the sensitive value.

package/dist/cli.d.ts

@@ -12,6 +12,8 @@ interface Args {
     force: boolean;
     yes: boolean;
     budget?: number;
+    /** Repeatable provider-keyed budgets used by a mixed-provider run. */
+    providerBudgets: Record<string, number>;
     dryRun: boolean;
     all: boolean;
     json: boolean;
@@ -50,7 +52,7 @@ interface Args {
     workspace?: string;
     /** Positional target for recipe and workspace subcommands. */
     target?: string;
-    /** `workspace add`: provider id to register the project under. Defaults to "pixellab". */
+    /** Account provider selector; also the `workspace add` catalog provider hint. */
     provider?: string;
     /** `workspace add`: free-form account label, e.g. distinguishing sandboxes. */
     account?: string;