pixelkiln 0.89.1 → 0.89.2

package/docs/ARCHITECTURE.md

@@ -112,6 +112,14 @@ retain:
   same output bytes, which is what lets a restore reproduce a recorded hash.
   It is compared against the manifest on every `plan`: a difference is
   `recoverable`, never `stale`, because no provider work is involved;
+- `terrainSettings`, `terrain` entries only: the settings the request was
+  sent with that `specHash` leaves out (the older mode, transition size,
+  view, shape, and raggedness knobs, and each terrain's description as
+  sent). Hashing them would have made every existing terrain entry stale,
+  so `plan` compares this record instead and reports `stale` naming each
+  changed setting. An entry from before it was recorded has none and is
+  taken as current. A history entry keeps its own, so a restore is
+  compared against the generation it brought back;
 - temporary `supersededOutputs[]` ownership hashes while a stale generation is
   being replaced;
 - provider-specific metadata under a provider-id namespace;

package/docs/MANIFEST.md

@@ -155,7 +155,7 @@ One asset using the fields most projects reach for:
 | `terrainBoundarySeed` | `0` | `terrain`, with `terrainBoundaryAmplitude`. Which meander, an integer. |
 | `terrainStepSlope` | `0` | `terrain`, `pro` at `terrainTransitionSize` 0.25 only. 0 a cliff to 2 a gentle slope. |
 | `terrainConnectDiagonals` | `false` | `terrain`, `pro` only. Join the diagonal tiles' upper corners into one area. |
-| `terrainSpreadX` / `terrainSlopeSize` | | Deprecated: PixelLab ignores both. Still accepted. |
+| `terrainSpreadX` / `terrainSlopeSize` | | Deprecated: PixelLab ignores both. Still accepted. Changing any `terrain*` field marks the set stale: the older ones (mode, transition size, view, shape style, raggedness, these two) and the descriptions as sent are recorded per lock entry as `terrainSettings` rather than hashed, compared as written (an explicit default counts as a change), and absent on sets generated before that record existed, which stay current. |
 | `mode` | `standard` | `character` only. `standard`, `v3`, `pro`, or `pro-flash`; see [Characters](./CHARACTERS.md). |
 | `directions` | `8` | `character` only. `4` or `8`; every engine but `standard` draws 8. |
 | `template` | `mannequin` | `character` only. Body template: `mannequin`, or `bear`, `cat`, `dog`, `horse`, `lion`; `custom` for `pro-flash`. |

package/package.json

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

package/skills/pixelkiln/references/pixellab-roadmap.md

@@ -84,6 +84,16 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
   15 up to 32px and 25 at 64px, standard 4 (the top of its quoted 1 to 4),
   sidescroller 3. What is still open is in
   [Pro tilesets](#pro-tilesets-what-is-left-after-04130) below.
+- **Older terrain fields as identity.** `terrainMode`,
+  `terrainTransitionSize`, `terrainRaggedness`, `terrainShapeStyle`,
+  `terrainView`, the deprecated `terrainSpreadX`/`terrainSlopeSize`, and
+  the descriptions as sent (the prompt wrapped in the style's prefix and
+  suffix) never entered `specHash`, and hashing them would have made every
+  existing terrain entry stale at once. Closed without a migration: submit
+  records them on the entry as `terrainSettings` (kept through history and
+  `restore --generation`), and the plan marks a set stale naming each one
+  that changed. An entry from before the record has none and stays current
+  until it is next regenerated. The 0.4.130 fields stay hashed (when set).
 - **Pro-tier full-bleed background generation** (`generate-image-v2`, PixelLab's
   Pro image tier) at arbitrary custom aspect ratios (not just square) —
   already measured at 40 generations in `docs/ENDPOINTS.md`, but `pixflux`
@@ -444,11 +454,6 @@ connecting different tilesets") are now mostly covered; see the closed
   `/create-tileset-sidescroller` has no `mode` field, and its tile size is
   16 or 32. pixelkiln's sidescroller sets use whatever model that endpoint
   runs.
-- **Older terrain fields are not identity.** `terrainMode`,
-  `terrainTransitionSize`, `terrainRaggedness`, `terrainShapeStyle`, and
-  `terrainView` never entered `specHash`, so changing one does not mark a set stale. The 0.4.130 fields
-  are hashed (when set). Hashing the older ones would make every existing
-  terrain lock entry stale at once, so it needs a deliberate migration.
 - **Wall-continuation twins export as duplicates.** The 25-tile layout has
   21 distinct corner combinations. Four tiles share corners with a twin and
   differ only in `pattern_4x4`, which pixelkiln records but cannot express in

package/skills/pixelkiln/references/pixellab.md

@@ -127,6 +127,16 @@ reads it:
 both now, so leave them out. Reference images, a forced palette, and the
 remaining tunables (`tileStrength`, `tilesetAdherence`) are not modeled.
 
+Changing any terrain setting marks the set stale. The Pro shape controls
+are in `specHash`; the older ones (`terrainMode`, `terrainTransitionSize`,
+`terrainRaggedness`, `terrainShapeStyle`, `terrainView`, the deprecated
+pair) and the style's `promptPrefix`/`promptSuffix` are recorded on the
+lock entry as `terrainSettings` instead, and `plan` names the one that
+changed ("terrainTransitionSize changed from 0.25 to 0.5"). A setting is
+compared as written: adding `terrainMode: "standard"` to a style that left
+it out is a change, even though it is the default. A set generated before
+this record existed has none and stays current until it is regenerated.
+
 **Connected sets.** An asset's `connect` makes one of its terrains the very
 terrain of another set in the same style, so ocean, sand, and grass paint on
 one map: `"connect": { "lower": { "of": "coast", "terrain": "upper" } }` is