rig-parts 1.82.2 → 1.83.0

package/cli.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+import { applyTakenLayers } from './src/takelayers.ts';
 /**
  * rig-parts — one painting and its See-through layers in, Spine-ready parts
  * and rig specs out, verified through rig-c.
@@ -1722,10 +1723,12 @@ function cmdAssemble(args: string[]): number {
     if (propose) {
       const target = writePath === undefined ? null : readConfigWriteTarget(writePath);
       const src = readSource(source);
-      const runs = readRuns(full, head);
-      const g = proposeFields(loadEarlyConfig(config, 'layers'), runs.single ? { w: src.width, h: src.height } : null);
+      const cfg = loadEarlyConfig(config, 'layers');
+      const runs = applyTakenLayers(readRuns(full, head), src, { ...cfg, assemble: { ...cfg.assemble, plan: undefined } }, config);
+      const g = proposeFields(cfg, runs.single ? { w: src.width, h: src.height } : null);
       const geometry = { sourceW: src.width, sourceH: src.height, ...g };
       const proposal = runs.single ? proposeSinglePlan(runs.full, geometry) : proposePlan(runs.full, runs.head, geometry);
+      proposal.notes.unshift(...runs.notes);
       if (target !== null) {
         staged = stageConfigWrite(target, { kind: 'assemble-plan', plan: proposal.plan, extend_below_crop: proposal.extend_below_crop });
         staged.commit();

package/docs/AUTHORING.md

@@ -615,6 +615,88 @@ remain separate authoring decisions; a shifted shoe can still require work on
 its neighbouring shin. A walk built from eight generated keyframes motivated
 the opt-in placement; it does not change the default for existing inputs.
 
+### Taking named layers from another run (`assemble.take`, issue #866)
+
+A run of the same painting, or a different painting with the same pixels under
+some layers, can supply those tags without editing either run directory:
+
+```json
+"take": [{
+  "run": "full",
+  "run_dir": "runs/other",
+  "st_input": "inputs/other_full.png",
+  "tags": ["front hair", "mouth"]
+}]
+```
+
+This array belongs in `assemble`. Every entry requires all four fields. `run`
+is the **target** `full` or `head` run; `head` requires `--head`. `run_dir` and
+`st_input` resolve relative to the config, for assemble, build and
+`assemble --propose-plan` alike. Each target run/tag may be selected once. Empty
+`take` and absent `take` leave the existing output unchanged. This selects base
+run layers; alternate painting sets keep their own existing declarations.
+
+`st_input` is the author's explicit declaration of the original PNG fed to the
+donor. The tool reads `run_dir/layers.json`
+and `run_dir/meta.json`, requiring a nonempty `prompt_id` and a nonnegative safe
+integer `seed`; it never infers either from the target config. Existing metadata
+does **not** bind that PNG's bytes to the prompt or layers. This checks the
+supplied evidence's pixel identity, not cryptographic provenance of a remote
+execution. Keep the original run, its metadata and original input together;
+renaming a supplied image does not establish that it was the donor's input.
+
+The target input is derived from the painting by the existing input model:
+`full` uses the exact centred white `squarePad`, and `head` the configured
+`head_box`. A nonsquare single-run file uses the painting at its original file
+size before the assembler's existing padding. Donor and target run canvases must
+have equal dimensions; donor and target input PNGs must also have equal
+dimensions. Incompatible canvases or input sizes are refused, never resized to
+make the comparison pass.
+
+For each selected layer, support means its **original** alpha > 8, including
+specks before ghost cleanup. Grow that support by the existing projection-core
+`CORE_KERNEL` (5 x 5, radius 2 run pixels), clipped to the run canvas. Map each
+covered run cell to **every intersecting** original input pixel cell. Compare
+all four RGBA bytes exactly, with no filtering or tolerance. Checking each
+layer's grown support checks their union too; the note reports both per-layer
+and union counts. A mismatch names the donor run, tag, number of differing
+pixels and `[left, top, right, bottom]` bbox in input pixels, right/bottom
+exclusive. A tag absent from the donor, or with no alpha > 8 support, is refused.
+An input difference outside that union is permitted.
+
+Taken layers replace the target's tag, keeping the donor's tag and
+`depth_median`, so existing hair/blink classification continues to read `from`.
+Larger depth draws behind smaller depth. Numeric ties keep manifest order only
+inside one original run. Equal or null depths **across** runs are ambiguous
+and refused, even if the plan gives an order. A supplied plan reversing the
+mixed-run depth order is also refused; `--propose-plan` drafts the depth order.
+Replacing a layer with hidden companion art is refused because independent
+hidden-art identity has not been declared. Active scalar depth sheets (`depth`
+opt-in or already bound sheets) are also refused: selecting donor art does not
+rebind a target atlas or invent donor scalar units. Inactive `depth_filename`
+hints remain inactive; numeric `depth_median` ordering is preserved.
+
+The proposal's `notes` and assemble/build log name every taken layer's run
+directory, prompt ID, seed and input path, plus support/checked/differing counts.
+`parts.json` adds `taken_layers` only to affected parts: each entry records
+`run`, `tag`, `run_dir`, `st_input`, `prompt_id`, `seed`, `support_px` (run cells),
+`checked_px` (original input cells), and `differing_px` (zero). Cuts, generated
+arm layers, limb segments and copied extension sources retain these receipts.
+The strict parts reader refuses partial, unknown, duplicate or nonzero-difference
+receipts. These source identities are separate from pixel-writer counts.
+
+Motivation, from the recorded 2026-10-30 decomposition measurements: a side-view
+control held 62,627 front-hair, 36,643 headwear and 595 mouth pixels at
+**alpha >= 250**. Three body repaints reported zero pixels at that threshold
+for front hair and mouth at seed 42; their alpha > 8 counts were nonzero.
+Six further runs at seeds 43, 101 and 2027 reported no run retaining both front
+hair and headwear. These are recorded measurements, not a new pixel audit:
+the retained run receipts contain no original layer PNGs. The records report
+identical head input pixels and body-dependent limb results; this feature makes
+identity an executable check on supplied original inputs instead of trusting
+that claim or hand-editing `layers.json`. Seed and painting selection remain
+the author's decisions.
+
 ### Alternate part layers (`assemble.alternates[i].layers`, issue #666)
 
 A gesture run may hold a raised arm only in a layer the author added, while
@@ -4365,6 +4447,19 @@ those settings. Changing a config seed alone cannot change a no-config run.
 
 | rule | means | change |
 | --- | --- | --- |
+| <a id="ASSEMBLE_TAKE_INPUT_IDENTITY"></a>`ASSEMBLE_TAKE_INPUT_IDENTITY` | original input RGBA differs under a taken tag's grown support; detail gives run/tag, count and exclusive input bbox | select a compatible donor and its actual original `st_input`; no tolerance or repaint is applied |
+| <a id="ASSEMBLE_TAKE_TAG_IN_RUN"></a>`ASSEMBLE_TAKE_TAG_IN_RUN` | selected donor does not hold the tag | choose a tag present in that donor |
+| <a id="ASSEMBLE_TAKE_SUPPORT"></a>`ASSEMBLE_TAKE_SUPPORT` | selected layer has zero alpha > 8 pixels | choose a nonempty donor layer |
+| <a id="ASSEMBLE_TAKE_DEPTH_AMBIGUOUS"></a>`ASSEMBLE_TAKE_DEPTH_AMBIGUOUS` | different original runs have equal or null depths | use a run with distinct numeric depths; do not invent an inter-run tie order |
+| <a id="ASSEMBLE_TAKE_PLAN_ORDER"></a>`ASSEMBLE_TAKE_PLAN_ORDER` | supplied plan reverses mixed-run depth order | use the depth order drafted by `assemble --propose-plan` |
+| <a id="ASSEMBLE_TAKE_GEOMETRY"></a>`ASSEMBLE_TAKE_GEOMETRY` | missing target head, unequal run canvases or unequal original input dimensions | supply matching geometry; the check does not resize inputs |
+| <a id="ASSEMBLE_TAKE_META"></a>`ASSEMBLE_TAKE_META` | donor `meta.json` lacks a readable prompt ID or seed | retain the original run metadata |
+| <a id="ASSEMBLE_TAKE_INPUT"></a>`ASSEMBLE_TAKE_INPUT` | declared donor input PNG cannot be read | name its original PNG relative to the config |
+| <a id="ASSEMBLE_TAKE_DEPTH_SHEET"></a>`ASSEMBLE_TAKE_DEPTH_SHEET` | taking layers with an active depth opt-in or bound scalar sheets has no declared mixed-run binding | keep scalar depth inactive; numeric ordering depth is retained, and a target sheet is never attached silently |
+| <a id="ASSEMBLE_TAKE_HIDDEN"></a>`ASSEMBLE_TAKE_HIDDEN` | a replaced tag has hidden companion art | independent hidden-art identity is undeclared; choose a run without that companion |
+| <a id="ASSEMBLE_TAKE_UNIQUE"></a>`ASSEMBLE_TAKE_UNIQUE` | repeated donor for one target tag at runtime | declare each target run/tag once |
+| <a id="CONFIG_TAKE_UNIQUE"></a>`CONFIG_TAKE_UNIQUE` | config selects the same target run/tag more than once | retain one donor per target tag |
+| <a id="PARTS_TAKEN_LAYERS"></a>`PARTS_TAKEN_LAYERS` | a taken-layer receipt is partial, unknown, duplicated, malformed or claims differing pixels | regenerate parts with assemble; never patch source receipts by hand |
 | <a id="ASSEMBLE_FIELD_PRESENT"></a>`ASSEMBLE_FIELD_PRESENT` | `seethrough.head_box` is missing | `propose --head-box` proposes it (§3) |
 | <a id="ASSEMBLE_RIG_SIZE"></a>`ASSEMBLE_RIG_SIZE` | `rig_scale` makes an empty rig | `assemble.rig_scale` |
 | <a id="ASSEMBLE_HEAD_BOX_INSIDE"></a>`ASSEMBLE_HEAD_BOX_INSIDE` | the head box is outside the painting | `head_box` — `propose --head-box` holds it inside |

package/docs/STABILITY.md

@@ -129,10 +129,11 @@ part name, `[i]` an entry of a list):
 - **generation.control.skeleton**, the pose file it names when it is no built-in — required: `width`, `height`, `points`
 - **seethrough** — required: `resolution`, `steps`, `seed`, `offload`; optional: `head_box`, `arm_split`
 - **seethrough.arm_split** — required: `order`, and one of `x` or `line` (issue #439)
-- **assemble** — required: `rig_scale`, `plan` (from plain `assemble` on); optional: `extend_below_crop`, `patches`, `cuts`, `alternates`, `head_face_underfill`, `yield_refused`, `keep_under_occluders`, `extend_painting`
+- **assemble** — required: `rig_scale`, `plan` (from plain `assemble` on); optional: `extend_below_crop`, `patches`, `cuts`, `alternates`, `head_face_underfill`, `yield_refused`, `keep_under_occluders`, `extend_painting`, `take`
 - **assemble.alternates[i]** — required: `name`; optional: `source`, `full`, `head`, `parts`, `hides`, `head_box`, `cuts`, `skeleton`, `anchor`, `base_anchor`, `drawn`, `tips`, `front`, `layers`, `focus` (issues #454, #465, #543, #652, #664, #666, #719, #780). `focus` is an authored finite `[x, y]` in painting pixels, within its canvas (edges included), refused as CONFIG_SET_FOCUS before assemble output when invalid; only when present, `parts.json` records it with focus_source_size and `sets.json` emits it in setup-world coordinates through the actual rig resize and `src/coords.ts`. Absent focus emits no field or inferred value; changing/removing it requires reassembly
 - **assemble.extend_below_crop[i]** — required: `part`, `run`, `tag`
 - **assemble.extend_painting[i]** — required: `part`, `band`, `max_distance`; optional: `min_held_alpha`, `order` (issues #848, #854, #855; explicit final layer-derived part, half-open rig band and positive four-neighbour path bound; base painting only). The optional integer floor 1–255 admits exact original alpha-over coverage strictly below it; absent or 1 blocks every nonzero holder. Only selected target samples below the floor may take painting RGBA; target samples at/above the floor and every non-target holder remain exact. By default overlapping reachable claims refuse. With `order` on every entry (unique nonnegative safe integers), lower values claim first and their gains block later candidates and paths; array order never breaks ties or supplies missing precedence
+- **assemble.take[i]** — required: `run`, `run_dir`, `st_input`, `tags` (issue #866)
 - **assemble.patches[i]** — required: `name`, `box`, `alpha`, `draw`
 - **assemble.patches[i].draw**, when an object — required: `before`
 - **assemble.cuts[i]** — required: `from`, `into`, `polygon`, `draw`, `overlap`; optional: `under`, `under_fill`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-parts",
-  "version": "1.82.2",
+  "version": "1.83.0",
   "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.",
   "type": "module",
   "bin": {

package/src/assemble.ts

@@ -1,3 +1,4 @@
+import { unionTakenSources } from './takesource.ts';
 import { paintingExtensionMasks, paintingExtensionProblems, type PaintingExtension } from './paintingextension.ts';
 import { AUTOMATIC_WRITERS as AW, compactValueBaseline, pixelProvenance, rgbaEqual, type ValueBaseline } from './provenance.ts';
 import { bindDepthRun, copyDepthMaterial, registerDepthRun, transportPartDepth, type DepthConfig, type RegisteredDepth } from './depthsheets.ts';
@@ -1494,6 +1495,7 @@ export function applyArmSplit(set: LayerSet, resolution: number, armSplit: ArmSp
     name,
     tag: readLayerTag(name) as LayerTagReading,
     file: refLayer.file,
+    takenLayers: unionTakenSources(handLayers.map(l => l.takenLayers)),
     pixels: crop(canvas, m.x0, m.y0, m.x1 - m.x0 + 1, m.y1 - m.y0 + 1),
     left: m.x0,
     top: m.y0,
@@ -1803,6 +1805,7 @@ export function splitMergedArmRunsWithNotes(
         name,
         tag: readLayerTag(name) as LayerTagReading,
         file: hwLayer.file,
+        ...(hwLayer.takenLayers === undefined ? {} : { takenLayers: hwLayer.takenLayers }),
         pixels: crop(canvas, x0, y0, x1 - x0 + 1, y1 - y0 + 1),
         left: x0,
         top: y0,
@@ -2098,6 +2101,7 @@ function prepareHeadFace(
       const postStats = measureCoverage(comp);
       const replacedLayer: Layer = {
         ...headFaceLayer,
+        takenLayers: unionTakenSources([headFaceLayer.takenLayers, fullFaceLayer.takenLayers]),
         pixels: crop(comp, x0, y0, x1 - x0 + 1, y1 - y0 + 1),
         left: x0,
         top: y0,
@@ -5522,6 +5526,13 @@ export function assemble(input: AssembleInput): AssembleResult {
       merged_px: merged,
       seam_override_px: 0,
     };
+    const sourceKeys = new Set([key, ...extendKeys.filter((_, i) => trace.from.some(v => v === i))]);
+    const takenLayers = unionTakenSources([...sourceKeys].map(k => {
+      const colon = k.indexOf(':');
+      const run = k.slice(0, colon) as Run;
+      return (run === 'full' ? full : head).layers.find(l => l.name === k.slice(colon + 1))?.takenLayers;
+    }));
+    if (takenLayers.length > 0) record.taken_layers = takenLayers;
     const paintingGain = paintingGains.get(name);
     if (paintingGain !== undefined) record.painting_extension_px = paintingGain.data.reduce((sum, value) => sum + value, 0);
     if (pushedHere.length > 0) record.fringe_pushed_back = pushedHere;
@@ -5542,6 +5553,15 @@ export function assemble(input: AssembleInput): AssembleResult {
       },
       ...((limb?.cap?.image_px ?? 0) > 0 || (limb?.cap?.lower_px ?? 0) > 0 ? { unsupported: `cap copies ${(limb?.cap?.image_px ?? 0) + (limb?.cap?.lower_px ?? 0)} pixels from a separate cap image whose scalar grid is undeclared` } : {}),
     });
+    if (capSource !== null && upperIndex >= 0 && capSource.codes.some(code => code === CAP_FROM_UPPER)) {
+      const upper = limbPieces[upperIndex];
+      const keys = [upper.key, ...upper.extendKeys.filter((_, i) => upper.trace.from.some(v => v === i))];
+      const sources = unionTakenSources([record.taken_layers, ...keys.map(k => {
+        const colon = k.indexOf(':');
+        return (k.slice(0, colon) === 'full' ? full : head).layers.find(l => l.name === k.slice(colon + 1))?.takenLayers;
+      })]);
+      if (sources.length > 0) record.taken_layers = sources;
+    }
     if (scalar !== undefined) record.depth = scalar.reference;
     if (scalar !== undefined && scalar.clampedSamples > 0) depthClamps.push({ part: name, samples: scalar.clampedSamples });
     set({ record, image, ...(scalar === undefined ? {} : { depthImage: scalar.image }) });

package/src/build.ts

@@ -1,3 +1,4 @@
+import { applyTakenLayers } from './takelayers.ts';
 import { ownershipLines, provenanceLines } from './provenance.ts';
 import { readSourceDepth } from './depthsheets.ts';
 import { orderedBaseAnchor } from './baseanchor.ts';
@@ -320,7 +321,8 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   // regions and motion, so it requires only what it reads (issue #20).
   const cfg = loadEarlyConfig(input.config, 'assemble');
   const src = readSource(input.source);
-  const runs = readRuns(input.full, input.head);
+  const runs = applyTakenLayers(readRuns(input.full, input.head), src, cfg, input.config);
+  for (const note of runs.notes) log(`note: ${note}`);
   const fields = stageFields(cfg, runs.single ? { w: src.width, h: src.height } : null);
   const under = readUnders(input.config, fields.cuts);
   const caps = fields.limbs === undefined ? undefined : readCaps(input.config, fields.limbs);

package/src/config.ts

@@ -1,3 +1,4 @@
+import type { TakeLayers } from './takelayers.ts';
 import { paintingExtensionProblems, type PaintingExtension } from './paintingextension.ts';
 import { baseAnchorProblems, type BaseAnchor } from './baseanchor.ts';
 import type { DepthConfig } from './depthsheets.ts';
@@ -299,6 +300,8 @@ export interface AlternateSetConfig {
 }
 
 export interface Assemble {
+  /** Verified named replacements from another See-through run (#866). */
+  take?: TakeLayers[];
   /** Rig pixels per source pixel. */
   rig_scale: number;
   plan: PlanEntry[];
@@ -1619,7 +1622,7 @@ export interface EarlyConfig {
   depth?: DepthConfig;
   key: string;
   seethrough: SeeThrough;
-  assemble: { rig_scale: number; head_face_underfill?: boolean; yield_refused?: boolean; keep_under_occluders?: string[]; extend_painting?: PaintingExtension[] };
+  assemble: { rig_scale: number; take?: TakeLayers[]; head_face_underfill?: boolean; yield_refused?: boolean; keep_under_occluders?: string[]; extend_painting?: PaintingExtension[] };
 }
 
 /** What plain `assemble` reads: the early config plus the plan `--propose-plan` printed. */
@@ -1688,7 +1691,7 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null):
   if (door === 'layers') {
     if ('seethrough' in t) checkSeeThrough(c, t.seethrough);
     if ('assemble' in t) {
-      const a = c.object('config.assemble', t.assemble, sectionRequired(door, 'assemble'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates', 'head_face_underfill', 'yield_refused', 'keep_under_occluders', 'extend_painting']);
+      const a = c.object('config.assemble', t.assemble, sectionRequired(door, 'assemble'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates', 'head_face_underfill', 'yield_refused', 'keep_under_occluders', 'extend_painting', 'take']);
       if (a !== null) {
         if ('rig_scale' in a) c.number('config.assemble.rig_scale', a.rig_scale, 'positive');
         if ('head_face_underfill' in a && typeof a.head_face_underfill !== 'boolean') {
@@ -1696,6 +1699,7 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null):
         }
         checkKeepUnderOccluders(c, a, null);
         if ('extend_painting' in a) checkPaintingExtensions(c, a.extend_painting);
+        if ('take' in a) checkTakeLayers(c, a.take);
         if ('yield_refused' in a && typeof a.yield_refused !== 'boolean') {
           c.fail('CONFIG_FIELD_TYPE', 'config.assemble.yield_refused', `is ${show(a.yield_refused)}; true or false is required`);
         }
@@ -2433,9 +2437,29 @@ function checkKeepUnderOccluders(c: Check, a: Record<string, Json>, plan: readon
   });
 }
 
+function checkTakeLayers(c: Check, value: Json): void {
+  const at = 'config.assemble.take';
+  if (!c.array(at, value, false)) return;
+  const seen = new Set<string>();
+  (value as Json[]).forEach((v, i) => {
+    const p = `${at}[${i}]`, o = c.object(p, v, ['run', 'run_dir', 'st_input', 'tags'], []);
+    if (o === null) return;
+    if (o.run !== 'full' && o.run !== 'head') c.fail('CONFIG_FIELD_TYPE', p + '.run', '"full" or "head" is required');
+    for (const k of ['run_dir', 'st_input']) c.string(`${p}.${k}`, o[k]);
+    if (!c.array(p + '.tags', o.tags, true)) return;
+    (o.tags as Json[]).forEach((tag, j) => {
+      const reading = typeof tag === 'string' ? readLayerTag(tag) : null;
+      if (reading === null || reading.group === 'author') c.fail('CONFIG_TAG_KNOWN', `${p}.tags[${j}]`, 'a See-through tag is required; author layers do not carry a See-through role');
+      const key = `${String(o.run)}:${String(tag)}`;
+      if (seen.has(key)) c.fail('CONFIG_TAKE_UNIQUE', `${p}.tags[${j}]`, `names ${key} again; one donor per target tag is required`);
+      seen.add(key);
+    });
+  });
+}
+
 function checkAssemble(c: Check, v: Json, door: 'assemble' | 'full'): { parts: string[]; patches: string[]; cuts: string[] } {
   const required = sectionRequired(door, 'assemble');
-  const a = c.object('config.assemble', v, required.filter((k) => k !== 'plan'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates', 'head_face_underfill', 'yield_refused', 'keep_under_occluders', 'extend_painting']);
+  const a = c.object('config.assemble', v, required.filter((k) => k !== 'plan'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates', 'head_face_underfill', 'yield_refused', 'keep_under_occluders', 'extend_painting', 'take']);
   if (a === null) return { parts: [], patches: [], cuts: [] };
   if (required.includes('plan') && !('plan' in a)) {
     c.fail('CONFIG_FIELD_PRESENT', 'config.assemble.plan', 'is absent and required; `assemble --propose-plan` prints one from the two runs — paste its plan and extend_below_crop into config.assemble');
@@ -2471,6 +2495,7 @@ function checkAssemble(c: Check, v: Json, door: 'assemble' | 'full'): { parts: s
   }
   checkKeepUnderOccluders(c, a, parts);
   if ('extend_painting' in a) checkPaintingExtensions(c, a.extend_painting);
+  if ('take' in a) checkTakeLayers(c, a.take);
   if ('extend_below_crop' in a && c.array(`${p}.extend_below_crop`, a.extend_below_crop, false)) {
     (a.extend_below_crop as Json[]).forEach((entry, i) => {
       const at = `${p}.extend_below_crop[${i}]`;

package/src/layers.ts

@@ -1,3 +1,4 @@
+import type { TakenLayerSource } from './takesource.ts';
 /**
  * The input contract: one See-through decomposition as a `LayerSet`.
  *
@@ -53,6 +54,8 @@ export const CORE_ALPHA = 250;
 export const NEAR_WHITE_MIN = 235;
 
 export interface Layer {
+  /** Verified donor identities retained through generated splits. */
+  takenLayers?: TakenLayerSource[];
   /** As the input names it: a v3 tag, possibly with a `-r`/`-l` side, or an author-made layer's `author:<label>`. */
   name: string;
   tag: LayerTagReading;

package/src/parts.ts

@@ -1,3 +1,4 @@
+import { takenSourceProblems, type TakenLayerSource } from './takesource.ts';
 import { AUTOMATIC_WRITERS, provenanceAddsUp, type PixelProvenance, type CutOwnership } from './provenance.ts';
 import { baseAnchorProblems, orderedBaseAnchor, type BaseAnchor } from './baseanchor.ts';
 import { partDepthProblems, type PartDepthReference } from './depthsheets.ts';
@@ -97,6 +98,8 @@ import { edgeLength } from './length.ts';
 import { recordedFocusProblems } from './setfocus.ts';
 
 export interface PartRecord {
+  /** Verified donor sources, including sources of cuts, limbs and extensions. */
+  taken_layers?: TakenLayerSource[];
   /** Report-only final last-writer census (#817); absent on older records. */
   provenance?: PixelProvenance;
   /** Painting ownership gained by #848, independent of final raw-value equality. */
@@ -426,6 +429,7 @@ export const PART_KEYS = [
   'name',
   'from',
   'cut_from',
+  'taken_layers',
   'x',
   'y',
   'w',
@@ -451,10 +455,10 @@ const FRINGE_KEY = 'fringe_pushed_back';
 const CUT_FROM_KEY = 'cut_from';
 /** The one part field that is a record of its own: a limb segment's provenance (issue #349), written only on one. */
 const LIMB_KEY = 'limb';
-const COUNT_KEYS = PART_KEYS.slice(2).filter((k) => k !== FRINGE_KEY && k !== CUT_FROM_KEY && k !== LIMB_KEY && k !== 'depth' && k !== 'provenance') as ReadonlyArray<(typeof PART_KEYS)[number]>;
+const COUNT_KEYS = PART_KEYS.slice(2).filter((k) => k !== FRINGE_KEY && k !== CUT_FROM_KEY && k !== LIMB_KEY && k !== 'depth' && k !== 'provenance' && k !== 'taken_layers') as ReadonlyArray<(typeof PART_KEYS)[number]>;
 /** The port's own counts: all three or none (none = a record the reference wrote). */
 export const VISIBILITY_KEYS = ['visible_px', 'occluded_px', 'visible_not_projected_px'] as const;
-const REQUIRED_KEYS = PART_KEYS.filter((k) => k !== 'painting_extension_px' && !(VISIBILITY_KEYS as readonly string[]).includes(k) && k !== FRINGE_KEY && k !== CUT_FROM_KEY && k !== LIMB_KEY && k !== 'depth' && k !== 'provenance');
+const REQUIRED_KEYS = PART_KEYS.filter((k) => k !== 'painting_extension_px' && !(VISIBILITY_KEYS as readonly string[]).includes(k) && k !== FRINGE_KEY && k !== CUT_FROM_KEY && k !== LIMB_KEY && k !== 'depth' && k !== 'provenance' && k !== 'taken_layers');
 
 /** Where a part came from: a See-through run and a v3 tag or an author-made layer's `author:<label>` (issue #256), or the painting itself for a patch. */
 export type From = { run: 'full' | 'head'; tag: string } | { run: 'painting'; patch: string };
@@ -504,7 +508,7 @@ function orderedProvenance(p: PixelProvenance): PixelProvenance {
 
 function serializePartList(parts: readonly PartRecord[]): Array<Record<string, unknown>> {
   return parts.map((p) =>
-    Object.fromEntries(PART_KEYS.filter((k) => p[k] !== undefined).map((k) => [k, k === FRINGE_KEY ? (p.fringe_pushed_back ?? []).map((q) => ({ part: q.part, px: q.px })) : k === LIMB_KEY ? orderedLimb(p.limb as LimbRecord) : k === 'provenance' ? orderedProvenance(p.provenance as PixelProvenance) : p[k]])),
+    Object.fromEntries(PART_KEYS.filter((k) => p[k] !== undefined).map((k) => [k, k === FRINGE_KEY ? (p.fringe_pushed_back ?? []).map((q) => ({ part: q.part, px: q.px })) : k === LIMB_KEY ? orderedLimb(p.limb as LimbRecord) : k === 'taken_layers' ? p.taken_layers?.map(t => ({ run: t.run, tag: t.tag, run_dir: t.run_dir, st_input: t.st_input, prompt_id: t.prompt_id, seed: t.seed, support_px: t.support_px, checked_px: t.checked_px, differing_px: t.differing_px })) : k === 'provenance' ? orderedProvenance(p.provenance as PixelProvenance) : p[k]])),
   );
 }
 
@@ -649,6 +653,7 @@ function checkParts(raw: unknown, path: string): PartsFile {
         return;
       }
       const r = p as Record<string, unknown>;
+      if ('taken_layers' in r) problems.push(...takenSourceProblems(r.taken_layers, `${at}.taken_layers`));
       if ('depth' in r) problems.push(...partDepthProblems(r.depth, `${path} part depth`));
       const label = typeof r.name === 'string' ? `part "${r.name}"` : at;
       for (const k of Object.keys(r)) if (!(PART_KEYS as readonly string[]).includes(k)) fail('PARTS_KEY_KNOWN', `${label} key "${k}"`, `is not a part field; known: ${PART_KEYS.join(', ')}`);

package/src/takelayers.ts

@@ -0,0 +1,110 @@
+/** Verified replacement in an existing full/head run; never writes or forges a run manifest. */
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import type { EarlyConfig, PlanEntry, Run } from './config.ts';
+import { CORE_KERNEL } from './assemble.ts';
+import { makeInputs } from './inputs.ts';
+import { OPAQUE_ALPHA_ABOVE, readLayers, type Layer, type LayerSet } from './layers.ts';
+import { PartsError, refuseIfAny, type Problem } from './errors.ts';
+import { dilate } from './raster/morph.ts';
+import { newMask, type Raster } from './raster/types.ts';
+import { readPng } from './raster/png.ts';
+import type { TakenLayerSource } from './takesource.ts';
+
+export interface TakeLayers {
+  run: Run;
+  run_dir: string;
+  /** The exact PNG supplied to See-through, resolved from the config directory. */
+  st_input: string;
+  tags: string[];
+}
+function refuse(code: string, object: string, detail: string): never { throw new PartsError([{ code, object, detail }]); }
+function metadata(path: string): { prompt_id: string; seed: number } {
+  let value: unknown;
+  try { value = JSON.parse(readFileSync(path, 'utf8')); } catch { return refuse('ASSEMBLE_TAKE_META', path, 'a readable meta.json with prompt_id and seed from the donor run is required'); }
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return refuse('ASSEMBLE_TAKE_META', path, 'a metadata object with prompt_id and seed is required');
+  const o = value as Record<string, unknown>;
+  if (typeof o.prompt_id !== 'string' || !o.prompt_id.trim() || !Number.isSafeInteger(o.seed) || (o.seed as number) < 0) return refuse('ASSEMBLE_TAKE_META', path, 'a nonempty prompt_id and nonnegative safe integer seed are required; neither is invented');
+  return { prompt_id: o.prompt_id, seed: o.seed as number };
+}
+function identity(layer: Layer, canvas: LayerSet['canvas'], donor: Raster, target: Raster, object: string): { support: number; checked: Uint8Array } {
+  const mask = newMask(canvas.w, canvas.h); let support = 0;
+  for (let y = 0; y < layer.pixels.height; y++) for (let x = 0; x < layer.pixels.width; x++) if (layer.pixels.data[(y * layer.pixels.width + x) * 4 + 3] > OPAQUE_ALPHA_ABOVE) {
+    mask.data[(layer.top + y) * canvas.w + layer.left + x] = 1; support++;
+  }
+  if (support === 0) return refuse('ASSEMBLE_TAKE_SUPPORT', object, `has 0 pixels of alpha above ${OPAQUE_ALPHA_ABOVE}; a nonempty taken layer is required`);
+  const grown = dilate(mask, CORE_KERNEL, CORE_KERNEL);
+  const checked = new Uint8Array(target.width * target.height);
+  // A run pixel is a cell on st_input, not a sample that can be rounded to a
+  // neighbouring centre. Compare EVERY intersecting input cell before any resize.
+  for (let y = 0; y < canvas.h; y++) for (let x = 0; x < canvas.w; x++) if (grown.data[y * canvas.w + x] === 1) {
+    for (let iy = Math.floor(y * target.height / canvas.h); iy < Math.ceil((y + 1) * target.height / canvas.h); iy++)
+      for (let ix = Math.floor(x * target.width / canvas.w); ix < Math.ceil((x + 1) * target.width / canvas.w); ix++) checked[iy * target.width + ix] = 1;
+  }
+  let differing = 0, x0 = target.width, y0 = target.height, x1 = 0, y1 = 0;
+  for (let p = 0; p < checked.length; p++) if (checked[p] === 1 && [0, 1, 2, 3].some(c => donor.data[p * 4 + c] !== target.data[p * 4 + c])) {
+    differing++; const x = p % target.width, y = Math.floor(p / target.width); x0 = Math.min(x0, x); y0 = Math.min(y0, y); x1 = Math.max(x1, x + 1); y1 = Math.max(y1, y + 1);
+  }
+  if (differing > 0) return refuse('ASSEMBLE_TAKE_INPUT_IDENTITY', object, `${differing} differing pixel(s), bbox [${x0}, ${y0}, ${x1}, ${y1}] in st_input pixels (right/bottom exclusive); exact RGBA identity under alpha > ${OPAQUE_ALPHA_ABOVE}, grown by ${CORE_KERNEL}x${CORE_KERNEL}, is required`);
+  return { support, checked };
+}
+export function takeLayerNote(source: TakenLayerSource): string {
+  return `take ${source.run}:${source.tag} from ${source.run_dir}; prompt_id ${source.prompt_id}; seed ${source.seed}; st_input ${source.st_input}; support ${source.support_px} run px; checked ${source.checked_px} input px; differing ${source.differing_px}; alpha > ${OPAQUE_ALPHA_ABOVE}, ${CORE_KERNEL}x${CORE_KERNEL} margin`;
+}
+/** Apply every declaration together, so replacing all tied layers from one run can retain its known order. */
+export function applyTakenLayers(runs: { full: LayerSet; head: LayerSet; single: boolean }, painting: Raster, cfg: Pick<EarlyConfig, 'seethrough' | 'depth'> & { assemble: { take?: TakeLayers[]; plan?: PlanEntry[] } }, configPath: string): { full: LayerSet; head: LayerSet; single: boolean; notes: string[] } {
+  const declarations = cfg.assemble.take ?? [];
+  if (declarations.length === 0) return { ...runs, notes: [] };
+  if (cfg.depth !== undefined || [...runs.full.layers, ...runs.head.layers].some(l => l.depthSheet !== undefined)) return refuse('ASSEMBLE_TAKE_DEPTH_SHEET', 'config.assemble.take', 'active scalar depth sheets have no mixed-run binding; disable the depth opt-in or assemble a separately bound run before taking layers (numeric depth_median ordering is retained)');
+  const inputs = makeInputs(painting, cfg, 'take target painting');
+  const base = dirname(resolve(configPath));
+  const lists = { full: [...runs.full.layers], head: [...runs.head.layers] };
+  const origins = new Map<Layer, string>();
+  const notes: string[] = [], seen = new Set<string>();
+  for (const d of declarations) {
+    const at = `config.assemble.take run "${d.run_dir}" (${d.run})`;
+    if (d.run === 'head' && runs.single) return refuse('ASSEMBLE_TAKE_GEOMETRY', at, 'there is no --head run; choose full or supply a head run');
+    const target = d.run === 'head' ? inputs.head : runs.single && (runs.full.canvas.w !== runs.full.canvas.h) ? painting : inputs.full;
+    const set = runs[d.run];
+    const donor = readLayers(resolve(base, d.run_dir));
+    const meta = metadata(resolve(base, d.run_dir, 'meta.json'));
+    let image: Raster;
+    try { image = readPng(resolve(base, d.st_input)); } catch { return refuse('ASSEMBLE_TAKE_INPUT', at, `st_input "${d.st_input}" must name the original readable PNG supplied to the donor run`); }
+    if (target === null || donor.canvas.w !== set.canvas.w || donor.canvas.h !== set.canvas.h || image.width !== target.width || image.height !== target.height) return refuse('ASSEMBLE_TAKE_GEOMETRY', at, `donor canvas ${donor.canvas.w}x${donor.canvas.h}, target canvas ${set.canvas.w}x${set.canvas.h}, donor st_input ${image.width}x${image.height}, target st_input ${target?.width ?? 0}x${target?.height ?? 0}; equal canvases and equal input dimensions are required (full uses squarePad; head uses head_box)`);
+    const union = new Uint8Array(image.width * image.height);
+    for (const tag of d.tags) {
+      const key = `${d.run}:${tag}`;
+      if (seen.has(key)) return refuse('ASSEMBLE_TAKE_UNIQUE', at, `tag "${tag}" replaces ${key} twice; declare one donor per target tag`);
+      seen.add(key);
+      const layer = donor.layers.find(l => l.name === tag);
+      if (layer === undefined) return refuse('ASSEMBLE_TAKE_TAG_IN_RUN', at, `tag "${tag}" is absent; a named See-through tag held by that donor is required`);
+      const checked = identity(layer, donor.canvas, image, target, `${at} tag "${tag}"`);
+      for (let p = 0; p < union.length; p++) union[p] |= checked.checked[p];
+      const source: TakenLayerSource = { run: d.run, tag, run_dir: d.run_dir, st_input: d.st_input, prompt_id: meta.prompt_id, seed: meta.seed, support_px: checked.support, checked_px: checked.checked.reduce((a, b) => a + b, 0), differing_px: 0 };
+      const replacement: Layer = { ...layer, takenLayers: [source] };
+      lists[d.run] = [...lists[d.run].filter(l => l.name !== tag), replacement];
+      origins.set(replacement, resolve(base, d.run_dir));
+      notes.push(takeLayerNote(source));
+    }
+    notes.push(`take union ${d.run} from ${d.run_dir}: checked ${union.reduce((a, b) => a + b, 0)} input px; differing 0`);
+  }
+  for (const run of ['full', 'head'] as const) {
+    const list = lists[run], targetOrigin = resolve(dirname(runs[run].source));
+    const origin = (l: Layer): string => origins.get(l) ?? targetOrigin;
+    const problems: Problem[] = [];
+    for (let i = 0; i < list.length; i++) for (let j = i + 1; j < list.length; j++) if (origin(list[i]) !== origin(list[j]) && (list[i].depth === null || list[j].depth === null || list[i].depth === list[j].depth)) problems.push({ code: 'ASSEMBLE_TAKE_DEPTH_AMBIGUOUS', object: `${run}: "${list[i].name}" (${origin(list[i])}) / "${list[j].name}" (${origin(list[j])})`, detail: `depths ${list[i].depth} / ${list[j].depth}; distinct numeric depths across runs are required; manifest order resolves ties only inside the same run` });
+    refuseIfAny(problems);
+    list.sort((a, b) => a.depth === null || b.depth === null || a.depth === b.depth ? a.drawOrder - b.drawOrder : b.depth - a.depth);
+    lists[run] = list.map((l, drawOrder) => ({ ...l, drawOrder }));
+    const selected = (cfg.assemble.plan ?? []).filter(p => p[1] === run).map(p => ({ part: p[0], layer: list.find(l => l.name === p[2]) }));
+    for (let i = 0; i < selected.length; i++) for (let j = i + 1; j < selected.length; j++) {
+      const a = selected[i], b = selected[j];
+      if (a.layer !== undefined && b.layer !== undefined && origin(a.layer) !== origin(b.layer) && list.indexOf(a.layer) > list.indexOf(b.layer)) problems.push({ code: 'ASSEMBLE_TAKE_PLAN_ORDER', object: `${run} plan parts "${a.part}" / "${b.part}"`, detail: `plan order reverses mixed-run depths ${a.layer.depth} / ${b.layer.depth}; put the larger depth behind, as in assemble --propose-plan` });
+    }
+    refuseIfAny(problems);
+    const replaced = new Set(declarations.filter(d => d.run === run).flatMap(d => d.tags));
+    if (runs[run].hidden.some(l => replaced.has(l.of)) || declarations.some(d => d.run === run && readLayers(resolve(base, d.run_dir)).hidden.some(l => d.tags.includes(l.of)))) return refuse('ASSEMBLE_TAKE_HIDDEN', run, 'a replaced layer has hidden companion art; separate hidden provenance is not declared, so the combination is refused');
+  }
+  const full = { ...runs.full, layers: lists.full }, head = runs.single ? full : { ...runs.head, layers: lists.head };
+  return { full, head, single: runs.single, notes };
+}

package/src/takesource.ts

@@ -0,0 +1,43 @@
+/** Layer identity receipts, retained independently of part names and derived geometry. */
+import type { Problem } from './errors.ts';
+import { readLayerTag } from './tags.ts';
+export interface TakenLayerSource {
+  run: 'full' | 'head';
+  tag: string;
+  run_dir: string;
+  st_input: string;
+  prompt_id: string;
+  seed: number;
+  support_px: number;
+  checked_px: number;
+  differing_px: 0;
+}
+export function unionTakenSources(lists: readonly (readonly TakenLayerSource[] | undefined)[]): TakenLayerSource[] {
+  const out: TakenLayerSource[] = [];
+  for (const list of lists) for (const item of list ?? []) if (!out.some(p => p.run === item.run && p.tag === item.tag && p.run_dir === item.run_dir)) out.push(item);
+  return out;
+}
+/** Strict parts reader: unknown fields and partial or invented identity receipts are refused. */
+export function takenSourceProblems(value: unknown, at: string): Problem[] {
+  const problems: Problem[] = [];
+  const fail = (detail: string): void => { problems.push({ code: 'PARTS_TAKEN_LAYERS', object: at, detail }); };
+  const keys = ['run', 'tag', 'run_dir', 'st_input', 'prompt_id', 'seed', 'support_px', 'checked_px', 'differing_px'];
+  if (!Array.isArray(value) || value.length === 0) { fail('a non-empty list of verified layer sources is required'); return problems; }
+  const seen = new Set<string>();
+  for (const item of value) {
+    if (typeof item !== 'object' || item === null || Array.isArray(item)) { fail('each source must be a complete identity receipt'); continue; }
+    const o = item as Record<string, unknown>;
+    const tag = typeof o.tag === 'string' ? readLayerTag(o.tag) : null;
+    if (Object.keys(o).some(k => !keys.includes(k)) || keys.some(k => !(k in o)) ||
+        (o.run !== 'full' && o.run !== 'head') || tag === null || tag.group === 'author' ||
+        ['run_dir', 'st_input', 'prompt_id'].some(k => typeof o[k] !== 'string' || !(o[k] as string).trim()) ||
+        !Number.isSafeInteger(o.seed) || (o.seed as number) < 0 ||
+        ['support_px', 'checked_px'].some(k => !Number.isSafeInteger(o[k]) || (o[k] as number) <= 0) || o.differing_px !== 0) {
+      fail('each source requires exactly run, See-through tag, run_dir, st_input, prompt_id, nonnegative safe integer seed, positive support_px/checked_px and differing_px 0'); continue;
+    }
+    const key = JSON.stringify([o.run, o.tag, o.run_dir]);
+    if (seen.has(key)) fail(`duplicate source ${key}; each source must appear once`);
+    seen.add(key);
+  }
+  return problems;
+}