spine-parts 2.28.0 → 2.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/AUTHORING.md CHANGED
@@ -5355,8 +5355,12 @@ or a joint.
5355
5355
  inpaints it on a ComfyUI box. `--graph lama` (the default) uses the
5356
5356
  comfyui-inpaint-nodes pack and its LaMa model (`--model`, default
5357
5357
  `big-lama.pt`). `--graph core` uses ComfyUI's own nodes and the checkpoint
5358
- `--model` names, with `--steps`, `--prompt` and `--negative`; it needs a
5359
- painting whose sides are multiples of 8. Every node, input and model of the
5358
+ `--model` names, with `--steps`, `--prompt` and `--negative`; when a painting's
5359
+ width or height is not a multiple of 8, it pads the uploaded painting (`edge-replicate`)
5360
+ and grown mask (`zero`, kept as context) on the right and bottom (`pad: [0, 0]`)
5361
+ to the next multiple of 8, crops the box's output back at `[0, 0]` before
5362
+ pasting inside the mask, and records `grid_transform` in `receipt.json`
5363
+ (on-grid paintings run unpadded and omit `grid_transform`). Every node, input and model of the
5360
5364
  graph is checked against the box's `/object_info` before anything is
5361
5365
  uploaded, so a box without the pack refuses `lama` and still runs `core`. The
5362
5366
  job is appended behind any other job: never put in front, nothing reordered,
@@ -5400,10 +5404,11 @@ recorded transform. The record fields and sampling formula are specified in
5400
5404
  | <a id="PLATE_MASK_SOURCE"></a><a id="PLATE_MASK_GRID"></a><a id="PLATE_MASK_VALUES"></a><a id="PLATE_MASK_EMPTY"></a>`PLATE_MASK_SOURCE`, `PLATE_MASK_GRID`, `PLATE_MASK_VALUES`, `PLATE_MASK_EMPTY` | no `--mask-from`, or a source directory holding no See-through run or no scene figure mask; a source on another grid without a valid recorded `input_transform`; a `figure_rig.png` holding other than opaque white and black; a mask with no figure pixel | run `comfy seethrough` on the original painting to record its input transform, or `assemble` with `config.scene` at the painting grid |
5401
5405
  | <a id="PLATE_MASK_RUN"></a>`PLATE_MASK_RUN` | the figure source has no readable `rig-run/1` assemble `run.json`, or its `figure_rig.png`, `parts.json` or declared `painting_in_rig.png` lacks exactly one matching output hash; or the See-through source has no readable `meta.json` with `image_sha256` and `layers` hashes, or a layer PNG on disk lacks a matching `layers` entry | re-run `assemble` with the source config to regenerate `run.json` and its `rig/` files together, or re-run `comfy seethrough` on the painting to regenerate `meta.json` and `parts/` together |
5402
5406
  | <a id="PLATE_MASK_PAINTING"></a>`PLATE_MASK_PAINTING` | `parts.json` has an invalid `painting_in_rig` declaration, its recorded painting is missing, undecodable or differs from its declared hash, or the supplied painting differs from the recorded opaque RGB; or the supplied painting's SHA-256 differs from a See-through source's `meta.json` `image_sha256` | use the original `--painting` file for this source, or re-run `assemble` or `comfy seethrough` on this painting |
5403
- | <a id="PLATE_CHECKPOINT_SHA256"></a><a id="PLATE_MODEL_GIVEN"></a><a id="PLATE_CORE_GRID"></a>`PLATE_CHECKPOINT_SHA256`, `PLATE_MODEL_GIVEN`, `PLATE_CORE_GRID` | `--checkpoint-sha256` absent or not 64 hex characters; `--graph core` without `--model`; a painting off the multiple-of-8 grid under `--graph core` | the flag, or `--graph lama` |
5407
+ | <a id="PLATE_CHECKPOINT_SHA256"></a><a id="PLATE_MODEL_GIVEN"></a>`PLATE_CHECKPOINT_SHA256`, `PLATE_MODEL_GIVEN` | `--checkpoint-sha256` absent or not 64 hex characters; `--graph core` without `--model` | the flag |
5408
+ | <a id="PLATE_CORE_GRID"></a>PLATE_CORE_GRID *(retired)* | retired in 2.x: off-grid `core` now pads to the next multiple of 8 and records `grid_transform`; see [STABILITY](STABILITY.md#plate-receipt) | none |
5404
5409
  | <a id="PLATE_PAINTING_PRESENT"></a><a id="PLATE_OUT_EMPTY"></a>`PLATE_PAINTING_PRESENT`, `PLATE_OUT_EMPTY` | no `--painting` file, or an `--out` that already holds entries | `--painting`, `--out` |
5405
- | <a id="COMFY_GPU_NAMED"></a><a id="COMFY_PLATE_SIZE"></a>`COMFY_GPU_NAMED`, `COMFY_PLATE_SIZE` | `/system_stats` does not name exactly one device; the box's image is not the painting's size | the box |
5406
- | <a id="PLATE_RECEIPT_READ"></a><a id="PLATE_RECEIPT_SPEC"></a><a id="PLATE_RECEIPT_KEYS"></a><a id="PLATE_RECEIPT_FILE"></a><a id="PLATE_RECEIPT_HASH"></a>`PLATE_RECEIPT_READ`, `PLATE_RECEIPT_SPEC`, `PLATE_RECEIPT_KEYS`, `PLATE_RECEIPT_FILE`, `PLATE_RECEIPT_HASH` | the receipt read back before it is published is not JSON, not this spec, not in its key order, names a file that is gone, or records a sha256 that is not the file's | nothing to change by hand: the run is refused and `<out>` is not written |
5410
+ | <a id="COMFY_GPU_NAMED"></a><a id="COMFY_PLATE_SIZE"></a>`COMFY_GPU_NAMED`, `COMFY_PLATE_SIZE` | `/system_stats` does not name exactly one device; the box's image is not the painting's size (or, for off-grid `core`, the padded size) | the box |
5411
+ | <a id="PLATE_RECEIPT_READ"></a><a id="PLATE_RECEIPT_SPEC"></a><a id="PLATE_RECEIPT_KEYS"></a><a id="PLATE_RECEIPT_FILE"></a><a id="PLATE_RECEIPT_HASH"></a><a id="PLATE_RECEIPT_GRID_TRANSFORM"></a>`PLATE_RECEIPT_READ`, `PLATE_RECEIPT_SPEC`, `PLATE_RECEIPT_KEYS`, `PLATE_RECEIPT_FILE`, `PLATE_RECEIPT_HASH`, `PLATE_RECEIPT_GRID_TRANSFORM` | the receipt read back before it is published is not JSON, not this spec, not in its key order, names a file that is gone, records a sha256 that is not the file's, or has a missing, unexpected, malformed or mismatched `grid_transform` | nothing to change by hand: the run is refused and `<out>` is not written |
5407
5412
  | <a id="MATTE_MODEL"></a><a id="MATTE_MODEL_INSTALLED"></a>`MATTE_MODEL`, `MATTE_MODEL_INSTALLED` | absent or unsupported explicit node/model, or the supported weight file is absent from the server model listing | use `--node BiRefNetRMBG --model BiRefNet-HR-matting` with installed weights |
5408
5413
  | <a id="MATTE_PARAMS"></a>`MATTE_PARAMS` | resolution is outside [64,2048] or not a multiple of 8, or threshold is outside integer [0,254] | set `--resolution` and `--threshold` within these bounds |
5409
5414
  | <a id="MATTE_RECEIPT"></a><a id="MATTE_PAINTING"></a><a id="MATTE_HASH"></a>`MATTE_RECEIPT`, `MATTE_PAINTING`, `MATTE_HASH` | `matte:<dir>` lacks a complete ordered receipt, names another painting, or raw/final mask bytes differ from their recorded hashes | re-run `comfy matte` on the supplied painting and keep its receipt and both masks together |
package/docs/STABILITY.md CHANGED
@@ -451,10 +451,22 @@ new spec version. Every path in it is relative to the receipt's directory.
451
451
  | `params` | every parameter of the run, the seed included, in a fixed order per graph: `lama` — `seed`, `grow_px`, `mask_alpha_above`; `core` — `seed`, `grow_px`, `steps`, `cfg`, `sampler`, `scheduler`, `denoise`, `prompt`, `negative`, `mask_alpha_above`; `foreground` — `mask_alpha_above` |
452
452
  | `graph` | `"rig-parts/plate-background-lama/1"`, `"rig-parts/plate-background-core/1"`, or the fixed local id `"rig-parts/plate-foreground/1"` |
453
453
  | `gpu` | the device `/system_stats` names (the same seed gives other pixels on another GPU), or null for `foreground` |
454
+ | `grid_transform` | present only when `mode` is `"background"`, `graph` is `"rig-parts/plate-background-core/1"`, and the painting's width or height is not a multiple of 8 (issue #1209, additive): `{ source: [width, height], padded: [ceil(width/8)*8, ceil(height/8)*8], pad: [0, 0], pad_fill: "edge-replicate", mask_pad_fill: "zero", inverse: "crop" }` in that key order. Omitted for on-grid `core`, `lama`, and `foreground` |
454
455
  | `output` | `{ path, sha256 }` of `plate.png` |
455
456
 
456
457
  The receipt is read back against the bytes on disk before `<out>` is published;
457
- a hash that is not its file's refuses the run.
458
+ a hash that is not its file's refuses the run. `verifyPlateReceipt` also
459
+ re-derives `grid_transform` from the decoded painting, `mode` and `graph`, and
460
+ refuses a missing, unexpected, malformed or mismatched transform as
461
+ `PLATE_RECEIPT_GRID_TRANSFORM`. For off-grid `--graph core` paintings, the
462
+ uploaded painting is padded on the right and bottom by replicating its edge
463
+ pixels (`pad_fill: "edge-replicate"`), the uploaded grown mask is padded with
464
+ zero (`mask_pad_fill: "zero"`, kept as context outside the hole), the box's
465
+ output is required at `padded` dimensions (`COMFY_PLATE_SIZE` otherwise) and
466
+ cropped at `[0, 0]` back to `source` before pasting inside the native mask, so
467
+ pixels outside the hole equal the painting byte for byte. On-grid `core`
468
+ paintings retain their original upload bytes, graph and 9-key receipt. Because
469
+ every painting grid is covered by this transform, `PLATE_CORE_GRID` is retired.
458
470
 
459
471
  ### Matte source receipt
460
472
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "spine-parts",
3
- "version": "2.28.0",
3
+ "version": "2.29.0",
4
4
  "description": "AI-authored 2D character parts from one anime painting and its See-through layer decomposition: measured parts, weighted-mesh rig specs, verified through rig-c before anything is written. A CLI for agents that cannot see the image.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -6,17 +6,20 @@
6
6
  *
7
7
  * 1. the source mask is read (`src/plate.ts`); with none, the run is refused
8
8
  * before anything is written and before the host is reached;
9
- * 2. the declared checkpoint sha256 and, for `core`, the painting's grid are
9
+ * 2. the declared checkpoint sha256 and, for `core`, the checkpoint name are
10
10
  * checked;
11
11
  * 3. the box answers `/system_stats` and names its GPU;
12
12
  * 4. every node, input and model of the chosen graph is on the box's
13
13
  * `/object_info` (`checkGraph`) — a box without the inpaint pack is refused
14
14
  * here for `lama`, before anything is uploaded;
15
- * 5. the painting and the grown mask are uploaded and the graph is appended
15
+ * 5. the painting and the grown mask (for off-grid `core`, padded to the next
16
+ * multiple of 8 on the right and bottom with `grid_transform` recorded) are
17
+ * uploaded and the graph is appended
16
18
  * to the queue: behind every other job, never in front, nothing reordered
17
19
  * and nothing cancelled; a wait past `--wait` while pending is refused
18
20
  * naming the job's place (`COMFY_QUEUE_BEHIND`);
19
- * 6. the box's image is read back, required at the painting's size, pasted
21
+ * 6. the box's image is read back, required at the uploaded size (then cropped
22
+ * at `[0, 0]` back to the painting's size for off-grid `core`), pasted
20
23
  * into the painting inside the mask only, and written with its receipt
21
24
  * through `publishPlate` (staged, read back, then moved).
22
25
  */
@@ -26,8 +29,8 @@ import {
26
29
  assertPlateOutFree,
27
30
  CORE_DEFAULTS,
28
31
  type CoreParams,
29
- coreGridProblem,
30
32
  corePlateGraph,
33
+ cropCoreGrid,
31
34
  declaredChecksum,
32
35
  type FigureMask,
33
36
  growMask,
@@ -40,6 +43,7 @@ import {
40
43
  PLATE_GRAPH_IDS,
41
44
  type PlateGraph,
42
45
  type PlateReceipt,
46
+ prepareCoreGrid,
43
47
  publishPlate,
44
48
  readPlatePainting,
45
49
  readSourceMask,
@@ -77,19 +81,20 @@ export function gpuName(stats: Record<string, unknown>, host: string): string {
77
81
 
78
82
  /** `connect` is called only after every local check has passed, so a refused run never resolves a host or reaches a box. */
79
83
  export async function runBackground(connect: () => ComfyClient, run: BackgroundRun, say: (line: string) => void): Promise<PlateReceipt> {
80
- // Local first: no source mask, a bad checksum or an off-grid painting is refused before the box is reached.
84
+ // Local first: no source mask, a bad checksum or a missing checkpoint is refused before the box is reached.
81
85
  const from = parseMaskFrom(run.maskFrom);
82
86
  const painting = readPlatePainting(run.painting);
83
87
  const { width: W, height: H } = painting.raster;
84
88
  const source: FigureMask = readSourceMask(from.source, from.dir, W, H, painting.raster, painting.bytes);
85
89
  const checkpoint = declaredChecksum(run.checkpointSha256);
86
- if (run.graph === 'core') {
87
- if (run.model === undefined) refuse('PLATE_MODEL_GIVEN', '--model', 'is absent; the core graph needs the checkpoint the box loads, by its name on the box — there is no default checkpoint');
88
- const grid = coreGridProblem(W, H, run.painting);
89
- if (grid !== null) refuseIfAny([grid]);
90
+ if (run.graph === 'core' && run.model === undefined) {
91
+ refuse('PLATE_MODEL_GIVEN', '--model', 'is absent; the core graph needs the checkpoint the box loads, by its name on the box — there is no default checkpoint');
90
92
  }
91
93
  assertPlateOutFree(run.out);
92
94
  const mask = growMask(source, run.growPx);
95
+ const prepared = run.graph === 'core' ? prepareCoreGrid(painting.raster, mask) : { painting: painting.raster, mask };
96
+ const uploadPaintingBytes = prepared.transform === undefined ? painting.bytes : encodePngBytes(prepared.painting);
97
+ const uploadMaskBytes = encodePngBytes(maskImage(prepared.mask));
93
98
  const model = run.model ?? LAMA_MODEL;
94
99
  const lama: LamaParams = { seed: run.seed, grow_px: run.growPx };
95
100
  const core: CoreParams = { seed: run.seed, grow_px: run.growPx, steps: run.steps, cfg: CORE_DEFAULTS.cfg, sampler: CORE_DEFAULTS.sampler, scheduler: CORE_DEFAULTS.scheduler, denoise: CORE_DEFAULTS.denoise, prompt: run.prompt ?? CORE_DEFAULTS.prompt, negative: run.negative ?? CORE_DEFAULTS.negative };
@@ -102,9 +107,9 @@ export async function runBackground(connect: () => ComfyClient, run: BackgroundR
102
107
  refuseIfAny(checkGraph(build(`${prefix}_painting.png`, `${prefix}_mask.png`), info, client.host, new Set(['1.image', '2.image'])));
103
108
  say(` box: every node, input and model of the ${run.graph} graph is on its /object_info; GPU ${gpu}`);
104
109
 
105
- const paintingRef = await client.uploadImage(painting.bytes, `${prefix}_painting.png`);
106
- const maskRef = await client.uploadImage(encodePngBytes(maskImage(mask)), `${prefix}_mask.png`);
107
- say(` uploaded ${run.painting} (${W}x${H}) and its mask (${mask.inside.reduce((a, b) => a + b, 0)} px, grown ${run.growPx} px)`);
110
+ const paintingRef = await client.uploadImage(uploadPaintingBytes, `${prefix}_painting.png`);
111
+ const maskRef = await client.uploadImage(uploadMaskBytes, `${prefix}_mask.png`);
112
+ say(` uploaded ${run.painting} (${prepared.painting.width}x${prepared.painting.height}) and its mask (${mask.inside.reduce((a, b) => a + b, 0)} px, grown ${run.growPx} px)`);
108
113
  const id = await client.submit(build(paintingRef, maskRef), 'rig-parts');
109
114
  say(` appended prompt ${id} to the queue (behind any other job; nothing reordered or cancelled)`);
110
115
  const { entry, elapsed } = await client.waitBehind(id, run.wait, run.timeout, say);
@@ -112,7 +117,15 @@ export async function runBackground(connect: () => ComfyClient, run: BackgroundR
112
117
  const images = historyImages(entry);
113
118
  if (images.length !== 1) refuse('COMFY_HISTORY_OUTPUTS', `prompt ${id}`, `lists ${images.length} image(s); the graph's one SaveImage is required to have saved exactly one`);
114
119
  const got = decodePngBytes(await client.view(images[0].filename, images[0].subfolder, images[0].type), images[0].filename);
115
- if (got.width !== W || got.height !== H) refuse('COMFY_PLATE_SIZE', `prompt ${id} ${images[0].filename}`, `is ${got.width}x${got.height}; the painting's ${W}x${H} is required — the plate is pasted into the painting pixel for pixel, never resized`);
120
+ const [expectedW, expectedH] = prepared.transform === undefined ? [W, H] : prepared.transform.padded;
121
+ if (got.width !== expectedW || got.height !== expectedH) {
122
+ refuse(
123
+ 'COMFY_PLATE_SIZE',
124
+ `prompt ${id} ${images[0].filename}`,
125
+ `is ${got.width}x${got.height}; ${prepared.transform === undefined ? `the painting's ${W}x${H}` : `the padded core grid ${expectedW}x${expectedH} (for painting ${W}x${H})`} is required — the plate is pasted into the painting pixel for pixel, never resized`,
126
+ );
127
+ }
128
+ const inpainted = prepared.transform === undefined ? got : cropCoreGrid(got, prepared.transform);
116
129
 
117
130
  return publishPlate({
118
131
  out: run.out,
@@ -123,10 +136,11 @@ export async function runBackground(connect: () => ComfyClient, run: BackgroundR
123
136
  source: from.source,
124
137
  sourceDir: from.dir,
125
138
  mask,
126
- plate: pasteInside(painting.raster, got, mask),
139
+ plate: pasteInside(painting.raster, inpainted, mask),
127
140
  model: { name: model, checkpoint_sha256: checkpoint, checkpoint_sha256_from: 'declared' },
128
141
  params: run.graph === 'lama' ? { ...lama, mask_alpha_above: OPAQUE_ALPHA_ABOVE } : { ...core, mask_alpha_above: OPAQUE_ALPHA_ABOVE },
129
142
  graph: PLATE_GRAPH_IDS[run.graph],
130
143
  gpu,
144
+ gridTransform: prepared.transform,
131
145
  });
132
146
  }
package/src/plate.ts CHANGED
@@ -46,13 +46,26 @@ export const PLATE_RECEIPT_FILE = 'receipt.json';
46
46
  export const PLATE_MASK_FILE = 'mask.png';
47
47
  export const PLATE_OUTPUT_FILE = 'plate.png';
48
48
 
49
- /** The receipt's top-level keys, in the order they are written. */
49
+ /** The receipt's top-level keys when `grid_transform` is absent, in the order they are written. */
50
50
  export const PLATE_RECEIPT_KEYS = ['spec', 'mode', 'painting', 'mask', 'model', 'params', 'graph', 'gpu', 'output'] as const;
51
+ /** The receipt's top-level keys when `grid_transform` is present (off-grid `core`), in the order they are written. */
52
+ export const PLATE_RECEIPT_GRID_TRANSFORM_KEYS = ['spec', 'mode', 'painting', 'mask', 'model', 'params', 'graph', 'gpu', 'grid_transform', 'output'] as const;
53
+ /** The `grid_transform` object's keys, in the order they are written. */
54
+ export const CORE_GRID_TRANSFORM_KEYS = ['source', 'padded', 'pad', 'pad_fill', 'mask_pad_fill', 'inverse'] as const;
51
55
 
52
56
  export type PlateMode = 'background' | 'foreground';
53
57
  export type PlateGraph = 'lama' | 'core';
54
58
  export type MaskSource = 'seethrough' | 'figure-mask' | 'matte';
55
59
 
60
+ export interface CoreGridTransform {
61
+ source: [number, number];
62
+ padded: [number, number];
63
+ pad: [0, 0];
64
+ pad_fill: 'edge-replicate';
65
+ mask_pad_fill: 'zero';
66
+ inverse: 'crop';
67
+ }
68
+
56
69
  /** The graph ids a receipt names: one per background graph, and the fixed local id of the foreground derivation. */
57
70
  export const PLATE_GRAPH_IDS = {
58
71
  lama: 'rig-parts/plate-background-lama/1',
@@ -74,6 +87,7 @@ export interface PlateReceipt {
74
87
  params: Record<string, string | number | boolean>;
75
88
  graph: string;
76
89
  gpu: string | null;
90
+ grid_transform?: CoreGridTransform;
77
91
  output: { path: string; sha256: string };
78
92
  }
79
93
 
@@ -412,19 +426,91 @@ export function corePlateGraph(painting: string, mask: string, checkpoint: strin
412
426
  };
413
427
  }
414
428
 
415
- /** The `core` graph encodes through the VAE, which crops to multiples of 8; a painting off that grid is refused before anything is uploaded. */
416
- export function coreGridProblem(width: number, height: number, painting: string): Problem | null {
417
- return width % 8 === 0 && height % 8 === 0 ? null : { code: 'PLATE_CORE_GRID', object: painting, detail: `is ${width}x${height}; the core graph needs both sides a multiple of 8 (the VAE crops otherwise) — use --graph lama, or a painting on that grid` };
429
+ /** The pad-to-8 transform for an off-grid painting on the `core` background graph; `undefined` when already a multiple of 8. */
430
+ export function coreGridTransform(width: number, height: number): CoreGridTransform | undefined {
431
+ if (width % 8 === 0 && height % 8 === 0) return undefined;
432
+ return {
433
+ source: [width, height],
434
+ padded: [Math.ceil(width / 8) * 8, Math.ceil(height / 8) * 8],
435
+ pad: [0, 0],
436
+ pad_fill: 'edge-replicate',
437
+ mask_pad_fill: 'zero',
438
+ inverse: 'crop',
439
+ };
440
+ }
441
+
442
+ /** Validate a recorded `grid_transform` against the bound painting's `width`x`height` and key order. */
443
+ export function isCoreGridTransform(value: unknown, width: number, height: number): value is CoreGridTransform {
444
+ if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
445
+ const v = value as Record<string, unknown>;
446
+ if (Object.keys(v).join(',') !== CORE_GRID_TRANSFORM_KEYS.join(',')) return false;
447
+ const pair = (p: unknown): p is [number, number] => Array.isArray(p) && p.length === 2 && p.every((n) => Number.isSafeInteger(n));
448
+ if (!pair(v.source) || !pair(v.padded) || !pair(v.pad)) return false;
449
+ const expected = coreGridTransform(width, height);
450
+ if (expected === undefined) return false;
451
+ return (
452
+ v.source[0] === expected.source[0] &&
453
+ v.source[1] === expected.source[1] &&
454
+ v.padded[0] === expected.padded[0] &&
455
+ v.padded[1] === expected.padded[1] &&
456
+ v.pad[0] === 0 &&
457
+ v.pad[1] === 0 &&
458
+ v.pad_fill === 'edge-replicate' &&
459
+ v.mask_pad_fill === 'zero' &&
460
+ v.inverse === 'crop'
461
+ );
462
+ }
463
+
464
+ /**
465
+ * Pad an off-grid painting and its grown mask to the next multiple of 8 on
466
+ * the right and bottom (`pad: [0, 0]`): the painting replicates its right and
467
+ * bottom edges (`edge-replicate`), and the mask pads with `0` (kept as
468
+ * context, never inside the hole). On-grid paintings return unchanged with no
469
+ * transform.
470
+ */
471
+ export function prepareCoreGrid(painting: Raster, mask: FigureMask): { painting: Raster; mask: FigureMask; transform?: CoreGridTransform } {
472
+ const transform = coreGridTransform(painting.width, painting.height);
473
+ if (transform === undefined) return { painting, mask };
474
+ const [W, H] = transform.source;
475
+ const [paddedW, paddedH] = transform.padded;
476
+ const paddedPainting = newRaster(paddedW, paddedH);
477
+ for (let y = 0; y < paddedH; y++) {
478
+ const sy = Math.min(y, H - 1);
479
+ for (let x = 0; x < paddedW; x++) {
480
+ const sx = Math.min(x, W - 1);
481
+ const src = (sy * W + sx) * 4;
482
+ const dst = (y * paddedW + x) * 4;
483
+ paddedPainting.data.set(painting.data.subarray(src, src + 4), dst);
484
+ }
485
+ }
486
+ const paddedMask: FigureMask = { width: paddedW, height: paddedH, inside: new Uint8Array(paddedW * paddedH) };
487
+ for (let y = 0; y < H; y++) {
488
+ paddedMask.inside.set(mask.inside.subarray(y * W, (y + 1) * W), y * paddedW);
489
+ }
490
+ return { painting: paddedPainting, mask: paddedMask, transform };
491
+ }
492
+
493
+ /** Crop a padded `core` output back to the painting's exact `source` grid at `transform.pad` (`[0, 0]`). */
494
+ export function cropCoreGrid(padded: Raster, transform: CoreGridTransform): Raster {
495
+ const [W, H] = transform.source;
496
+ const [padX, padY] = transform.pad;
497
+ const out = newRaster(W, H);
498
+ for (let y = 0; y < H; y++) {
499
+ const src = ((y + padY) * padded.width + padX) * 4;
500
+ out.data.set(padded.data.subarray(src, src + W * 4), y * W * 4);
501
+ }
502
+ return out;
418
503
  }
419
504
 
420
505
  // ---------------------------------------------------------------------------
421
506
  // the receipt
422
507
  // ---------------------------------------------------------------------------
423
508
 
424
- /** The receipt's JSON text, its keys in `PLATE_RECEIPT_KEYS` order. */
509
+ /** The receipt's JSON text, its keys in `PLATE_RECEIPT_KEYS` (or `PLATE_RECEIPT_GRID_TRANSFORM_KEYS` when `grid_transform` is present) order. */
425
510
  export function receiptText(r: PlateReceipt): string {
426
511
  const ordered: Record<string, unknown> = {};
427
- for (const k of PLATE_RECEIPT_KEYS) ordered[k] = r[k];
512
+ const keys = r.grid_transform === undefined ? PLATE_RECEIPT_KEYS : PLATE_RECEIPT_GRID_TRANSFORM_KEYS;
513
+ for (const k of keys) ordered[k] = r[k];
428
514
  return `${JSON.stringify(ordered, null, 2)}\n`;
429
515
  }
430
516
 
@@ -435,21 +521,28 @@ export function receiptPath(receiptDir: string, path: string): string {
435
521
 
436
522
  /**
437
523
  * Every problem between a receipt and the bytes on disk: its spec and key
438
- * order, and each of the painting, mask and output whose sha256 is not that of
439
- * the file it names (or whose file is gone).
524
+ * order, each of the painting, mask and output whose sha256 is not that of
525
+ * the file it names (or whose file is gone), and `grid_transform` re-derived
526
+ * from the decoded painting, mode and graph.
440
527
  */
441
528
  export function verifyPlateReceipt(receiptFile: string): Problem[] {
442
529
  const problems: Problem[] = [];
443
530
  let r: Record<string, unknown>;
444
531
  try {
445
- r = JSON.parse(readFileSync(receiptFile, 'utf8')) as Record<string, unknown>;
532
+ const parsed: unknown = JSON.parse(readFileSync(receiptFile, 'utf8'));
533
+ if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
534
+ return [{ code: 'PLATE_RECEIPT_READ', object: receiptFile, detail: 'does not parse as a JSON object' }];
535
+ }
536
+ r = parsed as Record<string, unknown>;
446
537
  } catch (err) {
447
538
  return [{ code: 'PLATE_RECEIPT_READ', object: receiptFile, detail: `does not parse as JSON (${(err as Error).message})` }];
448
539
  }
449
540
  if (r.spec !== PLATE_RECEIPT_SPEC) problems.push({ code: 'PLATE_RECEIPT_SPEC', object: receiptFile, detail: `has spec ${JSON.stringify(r.spec)}; "${PLATE_RECEIPT_SPEC}" is required` });
450
541
  const keys = Object.keys(r).join(',');
451
- if (keys !== PLATE_RECEIPT_KEYS.join(',')) problems.push({ code: 'PLATE_RECEIPT_KEYS', object: receiptFile, detail: `has keys ${keys}; ${PLATE_RECEIPT_KEYS.join(',')} in that order is required` });
542
+ const expectedKeys = 'grid_transform' in r ? PLATE_RECEIPT_GRID_TRANSFORM_KEYS : PLATE_RECEIPT_KEYS;
543
+ if (keys !== expectedKeys.join(',')) problems.push({ code: 'PLATE_RECEIPT_KEYS', object: receiptFile, detail: `has keys ${keys}; ${expectedKeys.join(',')} in that order is required` });
452
544
  const base = dirname(receiptFile);
545
+ let paintingRaster: Raster | undefined;
453
546
  for (const field of ['painting', 'mask', 'output'] as const) {
454
547
  const f = r[field] as { path?: unknown; sha256?: unknown } | undefined;
455
548
  if (typeof f?.path !== 'string' || typeof f.sha256 !== 'string') {
@@ -461,8 +554,42 @@ export function verifyPlateReceipt(receiptFile: string): Problem[] {
461
554
  problems.push({ code: 'PLATE_RECEIPT_FILE', object: `${receiptFile} ${field}`, detail: `names ${f.path}, which does not exist` });
462
555
  continue;
463
556
  }
464
- const found = sha256(new Uint8Array(readFileSync(file)));
557
+ const bytes = new Uint8Array(readFileSync(file));
558
+ const found = sha256(bytes);
465
559
  if (found !== f.sha256) problems.push({ code: 'PLATE_RECEIPT_HASH', object: `${receiptFile} ${field}`, detail: `records sha256 ${f.sha256} for ${f.path}; the file on disk has ${found}` });
560
+ if (field === 'painting') {
561
+ try { paintingRaster = decodePngBytes(bytes, file); } catch { /* hash/read already covers invalid bytes */ }
562
+ }
563
+ }
564
+ if (paintingRaster !== undefined) {
565
+ const expectedTransform = r.mode === 'background' && r.graph === PLATE_GRAPH_IDS.core ? coreGridTransform(paintingRaster.width, paintingRaster.height) : undefined;
566
+ if (expectedTransform !== undefined) {
567
+ if (!('grid_transform' in r) || r.grid_transform === undefined) {
568
+ problems.push({
569
+ code: 'PLATE_RECEIPT_GRID_TRANSFORM',
570
+ object: `${receiptFile} grid_transform`,
571
+ detail: `is absent; off-grid core painting (${paintingRaster.width}x${paintingRaster.height}) requires ${JSON.stringify(expectedTransform)}`,
572
+ });
573
+ } else if (!isCoreGridTransform(r.grid_transform, paintingRaster.width, paintingRaster.height)) {
574
+ problems.push({
575
+ code: 'PLATE_RECEIPT_GRID_TRANSFORM',
576
+ object: `${receiptFile} grid_transform`,
577
+ detail: `is ${JSON.stringify(r.grid_transform)}; off-grid core painting (${paintingRaster.width}x${paintingRaster.height}) requires ${JSON.stringify(expectedTransform)} in ${CORE_GRID_TRANSFORM_KEYS.join(',')} order`,
578
+ });
579
+ }
580
+ } else if ('grid_transform' in r) {
581
+ problems.push({
582
+ code: 'PLATE_RECEIPT_GRID_TRANSFORM',
583
+ object: `${receiptFile} grid_transform`,
584
+ detail: `is ${JSON.stringify(r.grid_transform)}; no grid_transform is permitted for ${r.mode === 'background' && r.graph === PLATE_GRAPH_IDS.core ? `on-grid painting ${paintingRaster.width}x${paintingRaster.height}` : `mode ${JSON.stringify(r.mode)} graph ${JSON.stringify(r.graph)}`}`,
585
+ });
586
+ }
587
+ } else if ('grid_transform' in r && (typeof r.grid_transform !== 'object' || r.grid_transform === null || Array.isArray(r.grid_transform) || Object.keys(r.grid_transform as object).join(',') !== CORE_GRID_TRANSFORM_KEYS.join(','))) {
588
+ problems.push({
589
+ code: 'PLATE_RECEIPT_GRID_TRANSFORM',
590
+ object: `${receiptFile} grid_transform`,
591
+ detail: `is ${JSON.stringify(r.grid_transform)}; a valid grid_transform in ${CORE_GRID_TRANSFORM_KEYS.join(',')} order is required`,
592
+ });
466
593
  }
467
594
  return problems;
468
595
  }
@@ -500,6 +627,7 @@ export interface PlateWrite {
500
627
  params: PlateReceipt['params'];
501
628
  graph: string;
502
629
  gpu: string | null;
630
+ gridTransform?: CoreGridTransform;
503
631
  }
504
632
 
505
633
  let foregroundStageSeq = 0;
@@ -528,6 +656,7 @@ export function publishPlate(w: PlateWrite): PlateReceipt {
528
656
  params: w.params,
529
657
  graph: w.graph,
530
658
  gpu: w.gpu,
659
+ ...(w.gridTransform === undefined ? {} : { grid_transform: w.gridTransform }),
531
660
  output: { path: PLATE_OUTPUT_FILE, sha256: plate.sha256 },
532
661
  };
533
662
  writeFileSync(join(stage, PLATE_RECEIPT_FILE), receiptText(receipt));