spine-parts 0.8.2 → 0.9.0

package/README.md

@@ -77,7 +77,9 @@ built from its own proposal with no hand edit at all —
 - **A character config** (`config.json`) — the part plan, the head box, the bones,
   which bones may pull which layer, and the idle's sines. `src/config.ts` is its
   schema and documents every field; the loader refuses an unknown or a missing field
-  by name. [docs/AUTHORING.md](docs/AUTHORING.md) says where each value comes from.
+  by name, and reads nothing under `note`, a `<name>_note` (a string) or a key
+  beginning `x-` (any JSON — a project's own records, such as a past build's gate
+  results). [docs/AUTHORING.md](docs/AUTHORING.md) says where each value comes from.
 
 ## What it gives out
 

package/docs/AUTHORING.md

@@ -47,9 +47,18 @@ examples use, and the one this guide assumes:
 
 `src/config.ts` is the schema and the loader. Every key is known or refused
 (`CONFIG_KEY_KNOWN`); a required key that is missing is `CONFIG_FIELD_PRESENT`.
-The one open door is annotation: `note`, and any key ending in `_note`, may hold a
-string anywhere an object is, and nothing reads it — write a hand correction's
-reason there, beside the value it corrected (the examples do).
+There are two open doors, and nothing reads what stands behind either. An
+annotation: `note`, and any key ending in `_note`, may hold a string anywhere an
+object is — write a hand correction's reason there, beside the value it corrected
+(the examples do). A record: any key beginning `x-` with a name after it may hold
+any JSON value in the same places — a project's own provenance, such as the gate
+results of a past build (`"x-status": {…}`) or the seeds a search rejected, with
+reasons (`generation.x-seeds_tried`). The record test comes first, so
+`x-seed_note` is a record. `xstatus`, `x_status`, `X-status` and a bare `x-` are
+not record names and are refused like any unknown key. The doors are not open in
+`meshes`, `regions` or `motion.blink.still`: their keys are part names, and an
+`x-` key there is a part like any other. Every refusal of an unknown key, of a
+retired one and of an annotation that is not a string says where a record goes.
 
 **Coordinates** in `bones`, `meshes` and `motion` are **rig pixels, y down, origin
 top-left** — the parts' own space, which is the painting times `assemble.rig_scale`.
@@ -570,7 +579,7 @@ See-through with another seed.
 | rule | means | change |
 | --- | --- | --- |
 | `CONFIG_FILE_PRESENT`, `CONFIG_IS_JSON` | no such file, or not JSON | `--config` |
-| `CONFIG_KEY_KNOWN`, `CONFIG_KEY_RETIRED`, `CONFIG_FIELD_PRESENT`, `CONFIG_FIELD_TYPE` | an unknown key (a retired one says what replaces it), a missing one, a wrong type | the named field |
+| `CONFIG_KEY_KNOWN`, `CONFIG_KEY_RETIRED`, `CONFIG_FIELD_PRESENT`, `CONFIG_FIELD_TYPE` | an unknown key (a retired one says what replaces it), a missing one, a wrong type; a project's own record under a plain key, or an annotation (`note`, `<name>_note`) holding something other than a string | the named field; a record goes under a key beginning `x-` (any JSON, read by nothing), a remark under `note` or `<name>_note` (a string) — §3 |
 | `CONFIG_HEAD_BOX_SQUARE` | `seethrough.head_box` is not a non-empty square | `head_box` — take `propose --head-box`'s |
 | `CONFIG_TAG_KNOWN`, `CONFIG_PART_NAME`, `CONFIG_PART_UNIQUE` | a plan entry names no v3 tag, a part name that is not a file name, or a part or layer twice — a patch named like a plan part or another patch included | `assemble.plan`, `assemble.patches` |
 | `CONFIG_NAME_RESOLVES` | a parent, segment, region, track, blink member, blink still part or bone, extend part or patch `draw.before` names nothing declared above it | the named reference, or the declaration it needs |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-parts",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "AI-authored Spine 2D character parts from one anime painting and its See-through layer decomposition: measured parts, weighted-mesh rig specs, verified through spine-rigc before anything is written. A CLI for agents that cannot see the image.",
   "type": "module",
   "bin": {

package/src/comfy/painting.ts

@@ -19,14 +19,16 @@
  *
  * The meta file holds the positive and negative prompts verbatim, what was
  * dropped as `DUP_WORDS`, where the pose words came from, the checkpoint, the
- * LoRAs and control as the graph used them (defaults resolved), the sampler,
- * the elapsed seconds and the prompt id — never the host.
+ * LoRAs, control and sampler as the graph used them (defaults resolved, each
+ * by its named fields, so an annotation or an `x-` record its author wrote in
+ * the config never reaches the meta), the elapsed seconds and the prompt id —
+ * never the host.
  */
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { PaintConfig } from '../config.ts';
 import { type Problem, refuseIfAny } from '../errors.ts';
-import { buildPrompts, checkGraph, paintingGraph, resolvedControl, resolvedLoras } from '../graphs.ts';
+import { buildPrompts, checkGraph, paintingGraph, resolvedControl, resolvedLoras, resolvedSampler } from '../graphs.ts';
 import { decodePngBytes, encodePngBytes } from '../raster/png.ts';
 import { renderSkeleton } from '../skeleton.ts';
 import { ComfyClient, historyImages, refuse } from './client.ts';
@@ -103,7 +105,7 @@ export async function runPainting(client: ComfyClient, run: PaintRun, say: (line
       key: run.config.key,
       checkpoint: g.checkpoint,
       loras: resolvedLoras(g.loras),
-      sampler: g.sampler,
+      sampler: resolvedSampler(g.sampler),
       control,
       pose_from: prompts.poseFrom,
       dropped: prompts.dropped,

package/src/config.ts

@@ -12,10 +12,20 @@
  *
  * 🔒 **Every key is known or refused.** An unknown key is refused by name and
  * so is a missing one — a config that half-loads is a rig nobody can reason
- * about. The one open door is annotation: `note`, and any key ending in
- * `_note`, may hold a string anywhere an object is expected, and nothing reads
- * it. Annotations are how a hand correction records its reason beside the value
- * it corrected, and refusing them would push that reason out of the file.
+ * about. There are two open doors, and both lead nowhere — nothing reads what
+ * stands behind them. Annotation: `note`, and any key ending in `_note`, may
+ * hold a string anywhere an object is expected. Annotations are how a hand
+ * correction records its reason beside the value it corrected, and refusing
+ * them would push that reason out of the file. Record: any key beginning with
+ * `x-` and at least one character after it may hold any JSON value in the same
+ * places (issue #70) — a project's own provenance, such as the gate results of
+ * a past build or the seeds a search rejected, kept beside the conditions that
+ * made the rig. The record test comes first, so `x-seed_note` is a record. The
+ * part-name maps (`meshes`, `regions`, `motion.blink.still`) are not objects
+ * in this sense: their keys are part names, and an `x-` key there is a part
+ * name like any other. No stage writes a vouched object whole into an output;
+ * each writer names its fields (`resolvedSampler` and its kin in
+ * `src/graphs.ts`), which is what keeps both doors read by nothing.
  *
  * ⛔ **The generation block is inline.** Configs written for the private
  * reference pointed at a character file and an art-job id elsewhere
@@ -224,11 +234,23 @@ const RETIRED: Record<string, Record<string, string>> = {
     art_job: 'named a job record outside this tree; put the costume words themselves in generation.costume and where they came from in generation.costume_note',
     identity_override: 'overrode the character file\'s identity; with the values inline, write the identity you want in generation.identity',
     lora_strength: 'overrode every LoRA\'s strength; with the values inline, set generation.loras[i].strength on each',
-    seed0: 'recorded where a seed search started; the chosen seed is generation.seed, and the search belongs in generation.seed_note',
-    seeds_tried: 'recorded the seeds a search tried; the chosen seed is generation.seed, and the search belongs in generation.seed_note',
+    seed0: 'recorded where a seed search started; the chosen seed is generation.seed, and the search belongs in generation.seed_note, or as a structured record in generation.x-seeds_tried',
+    seeds_tried: 'recorded the seeds a search tried; the chosen seed is generation.seed, and the search belongs in generation.seed_note, or as a structured record in generation.x-seeds_tried',
   },
 };
 
+/**
+ * A project's own record: a key beginning `x-` with at least one character
+ * after it, holding any JSON value, read by nothing. `X-`, `x_` and a bare
+ * `x-` are not record names, so a typo of one is still refused by name.
+ */
+function isRecordKey(key: string): boolean {
+  return key.length > 2 && key.startsWith('x-');
+}
+
+/** What every refusal of a key the schema does not know adds after its own sentence: the two doors. */
+const DOORS = 'a project\'s own record goes under a key beginning "x-" (any JSON, read by nothing), a remark under note or <name>_note (a string)';
+
 // ---------------------------------------------------------------------------
 // the checker
 // ---------------------------------------------------------------------------
@@ -242,7 +264,7 @@ class Check {
     this.problems.push({ code, object, detail });
   }
 
-  /** An object with exactly these keys (plus annotations); returns it, or null after refusing. */
+  /** An object with exactly these keys (plus records and annotations); returns it, or null after refusing. */
   object(path: string, v: Json, required: readonly string[], optional: readonly string[]): Record<string, Json> | null {
     if (typeof v !== 'object' || v === null || Array.isArray(v)) {
       this.fail('CONFIG_FIELD_TYPE', path, `is ${show(v)}; an object is required`);
@@ -252,13 +274,16 @@ class Check {
     const section = path.replace(/^config\.?/, '');
     for (const key of Object.keys(o)) {
       if (required.includes(key) || optional.includes(key)) continue;
+      if (isRecordKey(key)) continue;
       if (key === 'note' || key.endsWith('_note')) {
-        if (typeof o[key] !== 'string') this.fail('CONFIG_FIELD_TYPE', `${path}.${key}`, `is ${show(o[key])}; an annotation is a string`);
+        if (typeof o[key] !== 'string') {
+          this.fail('CONFIG_FIELD_TYPE', `${path}.${key}`, `is ${show(o[key])}; an annotation is a string — a structured record goes under a key beginning "x-" (any JSON, read by nothing)`);
+        }
         continue;
       }
       const retired = RETIRED[section]?.[key];
       if (retired !== undefined) this.fail('CONFIG_KEY_RETIRED', `${path}.${key}`, retired);
-      else this.fail('CONFIG_KEY_KNOWN', `${path}.${key}`, `is not a field here; known: ${[...required, ...optional].join(', ')}`);
+      else this.fail('CONFIG_KEY_KNOWN', `${path}.${key}`, `is not a field here; known: ${[...required, ...optional].join(', ')} — ${DOORS}`);
     }
     for (const key of required) if (!(key in o)) this.fail('CONFIG_FIELD_PRESENT', `${path}.${key}`, 'is absent and required');
     return o;
@@ -421,9 +446,10 @@ const TOP_KEYS = ['key', 'generation', 'seethrough', 'assemble', 'bones', 'meshe
  * vouched for (for `paint` that is everything but `key` and `generation`; for
  * `layers`, `assemble.plan`, `extend_below_crop`, `patches`, `bones`, `meshes`,
  * `regions` and `motion`; for `assemble`, the last four); a caller that needs
- * them uses {@link parseConfig}. Every other key is still refused by name, and
- * a retired one (`generation.character_file` and its kin) still with what
- * replaces it: a config is not allowed to be half-known at any stage.
+ * them uses {@link parseConfig}. Every other key that is not a record or an
+ * annotation is still refused by name, and a retired one
+ * (`generation.character_file` and its kin) still with what replaces it: a
+ * config is not allowed to be half-known at any stage.
  */
 export function parseEarlyConfig(raw: Json, door: 'paint'): PaintConfig;
 export function parseEarlyConfig(raw: Json, door: 'layers'): EarlyConfig;

package/src/graphs.ts

@@ -28,7 +28,7 @@
  * The two heads are the reference's verbatim, including the safety terms of
  * the negative head (no nudity, no minors): they are a guard, not a cast.
  */
-import type { Control, Generation, Lora } from './config.ts';
+import type { Control, Generation, Lora, Sampler } from './config.ts';
 import type { Problem } from './errors.ts';
 import { SKELETONS } from './skeleton.ts';
 
@@ -106,6 +106,16 @@ export function resolvedControl(c: Control): Required<Control> {
   return { skeleton: c.skeleton, strength: c.strength, end_percent: c.end_percent, model: c.model ?? CONTROL_MODEL };
 }
 
+/**
+ * The sampler as the graph uses it: its four fields by name, in this order.
+ * The config's own object also carries whatever annotations and `x-` records
+ * its author wrote, and the loader vouches for the four fields only, so a
+ * writer that copied the object whole would carry those into an output.
+ */
+export function resolvedSampler(s: Sampler): Sampler {
+  return { steps: s.steps, cfg: s.cfg, sampler: s.sampler, scheduler: s.scheduler };
+}
+
 /**
  * The painting graph: checkpoint -> LoRAs in order -> the two text encoders ->
  * (ControlNetApplyAdvanced over the uploaded skeleton) -> KSampler -> VAE