@rig-c/parts 1.65.0 → 1.67.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.
@@ -0,0 +1,91 @@
1
+ /** Explicit motion observations; no automatic declaration in check. */
2
+ import type { BoneEntry, CharacterConfig, Segment } from './config.ts';
3
+ import type { Problem } from './errors.ts';
4
+ import { tagOf, type PartRecord } from './parts.ts';
5
+
6
+ export interface MotionSeamDeclaration {
7
+ part: string;
8
+ neighbour: string;
9
+ }
10
+
11
+ /** Both readers share shape, name, self-pair and unordered uniqueness rules. */
12
+ export function motionSeamProblems(value: unknown, names: ReadonlySet<string>, at: string, code: string): Problem[] {
13
+ const problems: Problem[] = [];
14
+ const bad = (object: string, detail: string): void => { problems.push({ code, object, detail }); };
15
+ if (!Array.isArray(value)) {
16
+ bad(at, 'requires an array of {part, neighbour} declarations');
17
+ return problems;
18
+ }
19
+ const seen = new Set<string>();
20
+ value.forEach((row: unknown, i) => {
21
+ const object = `${at}[${i}]`;
22
+ if (typeof row !== 'object' || row === null || Array.isArray(row)) { bad(object, 'requires {part, neighbour}'); return; }
23
+ const r = row as Record<string, unknown>;
24
+ for (const key of Object.keys(r)) if (key !== 'part' && key !== 'neighbour') bad(`${object}.${key}`, 'is unknown; only part and neighbour are read');
25
+ for (const key of ['part', 'neighbour']) {
26
+ if (typeof r[key] !== 'string' || r[key] === '') bad(`${object}.${key}`, 'requires a nonempty output part name');
27
+ else if (!names.has(r[key])) bad(`${object}.${key}`, `names "${r[key]}", which is no output part; known: ${[...names].join(', ')}`);
28
+ }
29
+ if (typeof r.part !== 'string' || typeof r.neighbour !== 'string') return;
30
+ if (r.part === r.neighbour) bad(object, `names "${r.part}" on both sides; two different parts are required`);
31
+ const key = JSON.stringify([r.part, r.neighbour].sort());
32
+ if (seen.has(key)) bad(object, 'duplicates an earlier pair, including reversed order; declare each unordered pair once');
33
+ seen.add(key);
34
+ });
35
+ return problems;
36
+ }
37
+
38
+ /** Expand only declared links; a miss has no inferred parent. */
39
+ export function motionSeamParents(bones: readonly BoneEntry[]): Map<string, string> {
40
+ const parents = new Map<string, string>();
41
+ for (const bone of bones) {
42
+ if ('name' in bone) parents.set(bone.name, bone.parent);
43
+ else bone.points.forEach((_, i) => parents.set(`${bone.chain}${i}`, i === 0 ? bone.parent : `${bone.chain}${i - 1}`));
44
+ }
45
+ return parents;
46
+ }
47
+
48
+ /**
49
+ * Source-bound declaration generator, also callable on a frozen handed config.
50
+ * A non-limb topwear mesh has exactly two single-bone carriers, a named parent
51
+ * and child. Every handwear carrier is strictly below the same nearest member
52
+ * of that pair, either parent or child, and none is a trunk carrier itself.
53
+ * This proves the declared binding structure, not positive
54
+ * compiled vertex weights or alpha overlap (the stock seam reader observes that).
55
+ * No motion keys, thresholds, part spelling or nearest geometry select a pair.
56
+ */
57
+ export function draftMotionSeams(config: Pick<CharacterConfig, 'bones' | 'meshes' | 'regions' | 'limbs'>, parts: readonly Pick<PartRecord, 'name' | 'from' | 'limb'>[]): MotionSeamDeclaration[] {
58
+ const parents = motionSeamParents(config.bones);
59
+ const singles = new Set(config.bones.flatMap(b => 'name' in b ? [b.name] : []));
60
+ const chains = new Map(config.bones.flatMap(b => 'chain' in b ? [[b.chain, b.points.map((_, i) => `${b.chain}${i}`)] as const] : []));
61
+ const bound = (part: string): string[] => {
62
+ const mesh = config.meshes[part];
63
+ if (mesh !== undefined && 'segments' in mesh) return [...new Set(mesh.segments.flatMap((s: Segment) => typeof s === 'string' ? chains.get(s) ?? [s] : [s[0]]))];
64
+ const region = config.regions[part];
65
+ return region === undefined ? [] : [typeof region === 'string' ? region : region.bone];
66
+ };
67
+ const consumed = new Set(Object.values(config.limbs ?? {}).flatMap(l => l.segments.map(s => s.from)));
68
+ const out: MotionSeamDeclaration[] = [];
69
+ for (const body of parts) {
70
+ if (body.limb !== undefined || consumed.has(body.name) || tagOf(body.from) !== 'topwear' || config.meshes[body.name] === undefined) continue;
71
+ const trunk = bound(body.name);
72
+ if (trunk.length !== 2 || !trunk.every(b => singles.has(b))) continue;
73
+ const child = trunk.find(b => parents.get(b) === trunk.find(other => other !== b));
74
+ if (child === undefined) continue;
75
+ for (const sleeve of parts) {
76
+ if (sleeve.limb !== undefined || consumed.has(sleeve.name) || !['handwear-r', 'handwear-l'].includes(tagOf(sleeve.from) ?? '')) continue;
77
+ const carriers = bound(sleeve.name);
78
+ const nearestTrunk = (bone: string): string | undefined => {
79
+ const seen = new Set<string>();
80
+ for (let b: string | undefined = parents.get(bone); b !== undefined && !seen.has(b); b = parents.get(b)) {
81
+ if (trunk.includes(b)) return b;
82
+ seen.add(b);
83
+ }
84
+ return undefined;
85
+ };
86
+ const carrierTrunk = carriers.length === 0 ? undefined : nearestTrunk(carriers[0]);
87
+ if (carrierTrunk !== undefined && carriers.every(b => parents.has(b) && !trunk.includes(b) && nearestTrunk(b) === carrierTrunk)) out.push({ part: body.name, neighbour: sleeve.name });
88
+ }
89
+ }
90
+ return out;
91
+ }
package/src/parts.ts CHANGED
@@ -85,6 +85,7 @@
85
85
  * a later stage. The writer's key order is fixed, so two runs over the same
86
86
  * inputs write the same bytes.
87
87
  */
88
+ import { motionSeamProblems, type MotionSeamDeclaration } from './motionseams.ts';
88
89
  import { existsSync, readFileSync, writeFileSync } from 'node:fs';
89
90
  import { type Problem, refuseIfAny } from './errors.ts';
90
91
  import { KEYPOINT_NAMES, type PosePoints } from './skeleton.ts';
@@ -355,6 +356,8 @@ export interface PartsFile {
355
356
  scale_rig_per_source: number;
356
357
  parts: PartRecord[];
357
358
  ghost_px: Record<string, number>;
359
+ /** Explicit observations only; check never regenerates a removed declaration. */
360
+ motion_seams?: MotionSeamDeclaration[];
358
361
  /** Absent in a `parts.json` the reference wrote; `assemble` always writes it. */
359
362
  recomposite?: RecompositeRecord;
360
363
  /** Written only under `config.scene` (issue #242): the recomposite was read inside this figure; absent otherwise. */
@@ -397,8 +400,8 @@ export interface SceneRecord {
397
400
  figure_mask: string;
398
401
  }
399
402
 
400
- const TOP_KEYS = ['rig_size', 'scale_rig_per_source', 'parts', 'ghost_px', 'recomposite', 'scene', 'single_run_pad', 'alternates'] as const;
401
- const REQUIRED_TOP_KEYS = TOP_KEYS.filter((k) => k !== 'recomposite' && k !== 'scene' && k !== 'single_run_pad' && k !== 'alternates');
403
+ const TOP_KEYS = ['rig_size', 'scale_rig_per_source', 'parts', 'ghost_px', 'recomposite', 'scene', 'single_run_pad', 'alternates', 'motion_seams'] as const;
404
+ const REQUIRED_TOP_KEYS = TOP_KEYS.filter((k) => k !== 'recomposite' && k !== 'scene' && k !== 'single_run_pad' && k !== 'alternates' && k !== 'motion_seams');
402
405
  export const SINGLE_RUN_PAD_KEYS = ['file_size', 'side', 'left', 'top'] as const;
403
406
  export const SCENE_KEYS = ['figure_alpha_above', 'figure_px', 'figure_mask'] as const;
404
407
  export const RECOMPOSITE_KEYS = ['mean_abs', 'within_limit', 'within_share', 'error_limit', 'error_px', 'covered_alpha', 'uncovered_error_px', 'hole_count', 'holes_listed', 'holes'] as const;
@@ -475,6 +478,7 @@ export function serializeParts(file: PartsFile): string {
475
478
  rig_size: file.rig_size,
476
479
  scale_rig_per_source: file.scale_rig_per_source,
477
480
  parts: serializePartList(file.parts),
481
+ ...(file.motion_seams === undefined ? {} : { motion_seams: file.motion_seams.map(({ part, neighbour }) => ({ part, neighbour })) }),
478
482
  ghost_px: Object.fromEntries(Object.keys(file.ghost_px).sort().map((k) => [k, file.ghost_px[k]])),
479
483
  ...(file.recomposite === undefined ? {} : { recomposite: serializeRecomposite(file.recomposite) }),
480
484
  ...(file.scene === undefined ? {} : { scene: Object.fromEntries(SCENE_KEYS.map((k) => [k, (file.scene as SceneRecord)[k]])) }),
@@ -515,7 +519,7 @@ export function writeParts(path: string, file: PartsFile): void {
515
519
  }
516
520
 
517
521
  export function readParts(path: string): PartsFile {
518
- if (!existsSync(path)) refuseIfAny([{ code: 'PARTS_FILE_PRESENT', object: path, detail: 'no such file' }]);
522
+ if (!existsSync(path)) refuseIfAny([{ code: 'PARTS_FILE_PRESENT', object: path, detail: 'no such file; --parts names the directory holding parts.json and parts/ (work/rig from assemble --out work, or out from build --out out)' }]);
519
523
  let raw: unknown;
520
524
  try {
521
525
  raw = JSON.parse(readFileSync(path, 'utf8'));
@@ -663,6 +667,10 @@ function checkParts(raw: unknown, path: string): PartsFile {
663
667
  }
664
668
  }
665
669
  if (Array.isArray(o.parts)) checkLimbRecords(o.parts, '', fail);
670
+ if ('motion_seams' in o) {
671
+ const names = new Set((Array.isArray(o.parts) ? o.parts : []).flatMap(p => typeof p === 'object' && p !== null && typeof p.name === 'string' ? [p.name] : []));
672
+ problems.push(...motionSeamProblems(o.motion_seams, names, `${path} motion_seams`, 'PARTS_MOTION_SEAM'));
673
+ }
666
674
  if ('scene' in o) {
667
675
  const sc = o.scene;
668
676
  if (typeof sc !== 'object' || sc === null || Array.isArray(sc)) fail('PARTS_FIELD_TYPE', `${path} field "scene"`, `is ${show(sc)}; an object is required`);
package/src/propose.ts CHANGED
@@ -147,6 +147,8 @@ import { type Mask, newMask, newRaster, type Raster } from './raster/types.ts';
147
147
  import { npMean, npMedian, npPercentile, pyFixed, pyInt, pyIntList, pyRepr, pyRound, pyStrList } from './pyfmt.ts';
148
148
  import type { JointState, RigJoint, RigJoints } from './keypoints.ts';
149
149
  import { IDLE_FPS } from './motion.ts';
150
+ import { draftMotionSeams, type MotionSeamDeclaration } from './motionseams.ts';
151
+ export { draftMotionSeams } from './motionseams.ts';
150
152
  import { FORK_SMOOTH_MAX_INFLUENCES, influenceFarthest } from './rig.ts';
151
153
  import { type Segment as WeightSegment } from './weights.ts';
152
154
  import { pyRound as roundTo } from './round.ts';
@@ -278,6 +280,8 @@ export interface Proposal {
278
280
  regions: Record<string, string>;
279
281
  /** Only under `--keypoints`, where an arm or a leg is drafted from its joints (issue #349): absent otherwise, so a proposal without one is the one written before it. */
280
282
  limbs?: Record<string, Limb>;
283
+ /** Source-bound torso/sleeve observations, written only when the structure resolves. */
284
+ motion_seams?: MotionSeamDeclaration[];
281
285
  motion: {
282
286
  duration: number;
283
287
  tracks: Array<ProposedSingleTrack | ProposedChainTrack>;
@@ -304,7 +308,7 @@ export interface Proposal {
304
308
  * {@link Proposal} key it does not hold, and the selftest's `TY18` holds every
305
309
  * paste sentence in the documents to it.
306
310
  */
307
- export const PROPOSAL_CONFIG_SECTIONS = ['bones', 'meshes', 'regions', 'limbs', 'motion', 'constraints', 'turn', 'proposed_rig_scale'] as const satisfies ReadonlyArray<Exclude<keyof Proposal, 'notes'>>;
311
+ export const PROPOSAL_CONFIG_SECTIONS = ['bones', 'meshes', 'regions', 'limbs', 'motion', 'constraints', 'turn', 'motion_seams', 'proposed_rig_scale'] as const satisfies ReadonlyArray<Exclude<keyof Proposal, 'notes'>>;
308
312
 
309
313
  /** A {@link Proposal} key that is neither `notes` nor in {@link PROPOSAL_CONFIG_SECTIONS}; `never` while the list is whole. */
310
314
  type UnlistedProposalSection = Exclude<keyof Proposal, 'notes' | (typeof PROPOSAL_CONFIG_SECTIONS)[number]>;
@@ -661,7 +665,7 @@ export function withTurn(p: Proposal, draft: { turn: TurnSpec | null; notes: str
661
665
  }
662
666
  turn = { pivot: turn.pivot, depths };
663
667
  }
664
- return { bones: p.bones, meshes: p.meshes, regions: p.regions, ...(p.limbs === undefined ? {} : { limbs: p.limbs }), motion: p.motion, ...(p.constraints === undefined ? {} : { constraints: p.constraints }), ...(turn === null ? {} : { turn }), proposed_rig_scale: p.proposed_rig_scale, notes: [...p.notes, ...draft.notes] };
668
+ return { bones: p.bones, meshes: p.meshes, regions: p.regions, ...(p.limbs === undefined ? {} : { limbs: p.limbs }), ...(p.motion_seams === undefined ? {} : { motion_seams: p.motion_seams }), motion: p.motion, ...(p.constraints === undefined ? {} : { constraints: p.constraints }), ...(turn === null ? {} : { turn }), proposed_rig_scale: p.proposed_rig_scale, notes: [...p.notes, ...draft.notes] };
665
669
  }
666
670
 
667
671
  // ---------------------------------------------------------------------------
@@ -3493,13 +3497,49 @@ export function proposeWithBasis(
3493
3497
  meshes[name] = { influence: { cell, radius, across: decl.across, max, shape: decl.shape, ...(held ? { hold_tip: true as const } : {}) }, segments };
3494
3498
  }
3495
3499
  const constrained = clothConstraints.length === 0 ? {} : { constraints: clothConstraints };
3500
+ const motionSeams = draftMotionSeams({ bones, meshes, regions, ...drafted }, P.recs);
3501
+ const observed = motionSeams.length === 0 ? {} : { motion_seams: motionSeams };
3496
3502
  return {
3497
- proposal: { bones, meshes, regions, ...drafted, motion: blink === undefined ? { duration: IDLE_SECONDS, tracks: idleTracks } : { duration: IDLE_SECONDS, tracks: idleTracks, blink }, ...constrained, proposed_rig_scale: P.rigScale, notes },
3503
+ proposal: draftPassingChainSigns(P, { bones, meshes, regions, ...drafted, ...observed, motion: blink === undefined ? { duration: IDLE_SECONDS, tracks: idleTracks } : { duration: IDLE_SECONDS, tracks: idleTracks, blink }, ...constrained, proposed_rig_scale: P.rigScale, notes }),
3498
3504
  basis: { frame, bones: records },
3499
3505
  draftLint: [...jointsOffArt, ...radii],
3500
3506
  };
3501
3507
  }
3502
3508
 
3509
+ /**
3510
+ * Issue #751: a fresh draft need not leave a measured, passing sign choice to its author.
3511
+ * The supplied-config lint never calls this. The reader and bar are unchanged; an
3512
+ * unread or still-failing alternative stays a LINT, not a guessed correction.
3513
+ */
3514
+ export function draftPassingChainSigns(P: PartSet, proposal: Proposal): Proposal {
3515
+ const images = new Map(P.recs.filter((p) => P.images.has(p.name)).map((p) => [p.name, { x: p.x, y: p.y, image: P.images.get(p.name) as Raster }]));
3516
+ const key = (f: { mesh: string; a: { chain: string }; b: { chain: string } }): string => JSON.stringify([f.mesh, f.a.chain, f.b.chain]);
3517
+ let current = proposal;
3518
+ let reading = chainSqueezes(current, images);
3519
+ const initial = reading.findings;
3520
+ for (const original of initial) {
3521
+ const finding = reading.findings.find((f) => key(f) === key(original));
3522
+ if (finding === undefined || finding.turned === null || !Number.isFinite(finding.turned) || finding.turned > TEXTURE_STRETCH_CEILING) continue;
3523
+ const candidate: Proposal = {
3524
+ ...current,
3525
+ motion: { ...current.motion, tracks: current.motion.tracks.map((t) => 'chain' in t && t.chain === finding.b.chain ? { ...t, amps: t.amps.map((a) => -a) } : t) },
3526
+ };
3527
+ // A track can be shared by other pairs/meshes. Accept no new or worsened
3528
+ // finding, and do not turn a previously readable pair into an unread one.
3529
+ const after = chainSqueezes(candidate, images);
3530
+ if (JSON.stringify(after.unread) !== JSON.stringify(reading.unread) || after.findings.some((f) => {
3531
+ const before = reading.findings.find((old) => key(old) === key(f));
3532
+ return key(f) === key(finding) || before === undefined || f.both.severity > before.both.severity;
3533
+ })) continue;
3534
+ current = {
3535
+ ...candidate,
3536
+ notes: [...current.notes, `shared-mesh chain signs: ${finding.a.chain} and ${finding.b.chain} on mesh ${pyRepr(finding.mesh)} were opposed; drafted one sign by reversing ${finding.b.chain}'s amplitudes, keeping their magnitudes and timing: squeeze ${pyFixed(finding.both.severity, 3)} -> ${pyFixed(finding.turned, 3)} (<= ${TEXTURE_STRETCH_CEILING}, check's TEXTURE_STRETCH bar); all shared pairs re-read without a new or worsened finding`],
3537
+ };
3538
+ reading = after;
3539
+ }
3540
+ return current;
3541
+ }
3542
+
3503
3543
  /**
3504
3544
  * The note the `figure` grid rule writes (issue #265): the spacing and where it came from, per lattice part its own
3505
3545
  * spacing and the one drafted, what it costs and what it was calibrated on.
package/src/rig.ts CHANGED
@@ -648,7 +648,8 @@ export interface TurnRow {
648
648
  * the control {@link TURN_BONE} under `root` at its origin, nothing keying it;
649
649
  * for each part `config.turn.depths` lists, in parts.json order, a leaf twin of
650
650
  * every bone the part's slots bind (its region's bone, a blink.still piece's
651
- * bone, a mesh's slot bone and every bone its weights name) — an identity child,
651
+ * bone, a mesh's slot bone and every bone its weights name), in `bones`
652
+ * declaration order (issue #746) — an identity child,
652
653
  * x 0, y 0, no rotation, so its world transform is its bone's exactly and every
653
654
  * idle key, physics step or constraint on the bone reaches it — the part's
654
655
  * slots and weights moved onto the twins, and one transform constraint per part
@@ -672,7 +673,7 @@ export interface TurnRow {
672
673
  * constraint. A name the turn needs that is taken is refused by name
673
674
  * (`RIG_TURN_NAME_FREE`).
674
675
  */
675
- function applyTurn(
676
+ export function applyTurn(
676
677
  turn: TurnSpec,
677
678
  order: readonly string[],
678
679
  bones: RigBone[],
@@ -681,8 +682,21 @@ function applyTurn(
681
682
  constraints: readonly ConfigConstraint[],
682
683
  frontSlots: ReadonlySet<string> = new Set(),
683
684
  slotFamilies: ReadonlyMap<string, readonly string[]> = new Map(),
685
+ stops: ReadonlyArray<{ links: readonly string[] }> | null = null,
686
+ orderByDeclaration: boolean = true,
684
687
  ): { constraints: Array<Record<string, unknown>>; detached: DetachedRule[]; rows: TurnRow[] } {
685
688
  const problems: Problem[] = [];
689
+ const undrawn = new Map<string, string>();
690
+ for (const s of stops ?? []) for (const l of s.links) undrawn.set(`${l}_d`, l);
691
+ const boneOrder = new Map(bones.map((b, i) => [b.name, i * 2]));
692
+ const orderOf = (b: string): number => {
693
+ const direct = boneOrder.get(b);
694
+ if (direct !== undefined) return direct;
695
+ const base = undrawn.get(b);
696
+ const baseIdx = base === undefined ? undefined : boneOrder.get(base);
697
+ if (baseIdx === undefined) throw new Error(`applyTurn: bound bone "${b}" is not in bones`);
698
+ return baseIdx + 1;
699
+ };
686
700
  const taken = new Set(bones.map((b) => b.name));
687
701
  const transforms = new Set(constraints.filter((c) => c.type === 'transform').map((c) => c.name));
688
702
  if (taken.has(TURN_BONE)) problems.push({ code: 'RIG_TURN_NAME_FREE', object: `bone "${TURN_BONE}"`, detail: 'is the control the rig stage adds for config.turn, and the rig already has a bone of that name; rename it' });
@@ -702,6 +716,8 @@ function applyTurn(
702
716
  bind(sl.bone);
703
717
  for (const att of Object.values(skin[sl.name] ?? {})) if ('type' in att) for (const v of att.weights) for (const w of v) bind(w.bone);
704
718
  }
719
+ for (const b of bound) orderOf(b);
720
+ if (orderByDeclaration) bound.sort((a, b) => orderOf(a) - orderOf(b));
705
721
  for (const b of bound) {
706
722
  const twin = turnTwin(f.part, b);
707
723
  if (taken.has(twin)) problems.push({ code: 'RIG_TURN_NAME_FREE', object: `bone "${twin}"`, detail: `is the twin that carries part "${f.part}" on "${b}" under config.turn, and the rig already has a bone of that name; rename it` });
@@ -1259,6 +1275,7 @@ export function buildRig(
1259
1275
  maxLoopPasses: number = ONE_LOOP_PASSES,
1260
1276
  idleKeys: IdleKeys = DEFAULT_IDLE_KEYS,
1261
1277
  reduce: Reducer = runReduction,
1278
+ turnOrderByDeclaration: boolean = true,
1262
1279
  ): RigOutput {
1263
1280
  // Generated bands have a fixed one-pixel lattice, with their axial weights
1264
1281
  // below; config never supplies a second mesh policy for the same source.
@@ -2835,7 +2852,7 @@ export function buildRig(
2835
2852
  // ---- the turn control (issue #251) -------------------------------------
2836
2853
  // Only when the config has `turn`: every other build adds nothing here, so no byte moves.
2837
2854
  if (cfg.turn !== undefined) refuseIfAny(turnRiderProblems(cfg.turn, cfg, parts.parts));
2838
- const turned = cfg.turn === undefined ? null : applyTurn(cfg.turn, parts.parts.map((p) => p.name), bones, rebound, skin, cfg.constraints ?? [], declaredFront, slotFamilies);
2855
+ const turned = cfg.turn === undefined ? null : applyTurn(cfg.turn, parts.parts.map((p) => p.name), bones, rebound, skin, cfg.constraints ?? [], declaredFront, slotFamilies, stops, turnOrderByDeclaration);
2839
2856
  for (const row of turned?.rows ?? []) for (const t of row.twins) layoutAlias(explicitLayout.plan, t.bone, t.twin);
2840
2857
  // issue #536: every row names the bones the emitted attachment binds, read once the turn and the stops have
2841
2858
  // rebound the weights; a rig with neither rebinds nothing, so this reads back the names each row already holds.
@@ -45,7 +45,7 @@ export function readConfigWriteTarget(path: string): ConfigWriteTarget {
45
45
  const target = resolve(path);
46
46
  let stat: ReturnType<typeof lstatSync>;
47
47
  try { stat = lstatSync(target); }
48
- catch (error) { return refusal('CONFIG_FILE_PRESENT', target, `cannot read the existing config: ${error instanceof Error ? error.message : String(error)}`); }
48
+ catch (error) { return refusal('CONFIG_FILE_PRESENT', target, `cannot read the existing config: ${error instanceof Error ? error.message : String(error)}; without --cloth, --write-config updates an existing config in place (only propose --cloth --write-config writes to a new file)`); }
49
49
  if (!stat.isFile()) return refusal('CONFIG_FIELD_TYPE', target, 'is not a regular file (symlinks are not replaced); --write-config updates an existing config file in place');
50
50
  let original: string;
51
51
  try { original = readFileSync(target, 'utf8'); }
@@ -133,7 +133,7 @@ export function stageConfigWrite(target: ConfigWriteTarget | FreshConfigWrite, p
133
133
  if (error instanceof Error && 'code' in error && error.code === 'ENOENT') return;
134
134
  return ioFailure(path, 'checking the fresh destination failed', error);
135
135
  }
136
- refusal('PROPOSE_WRITE_CONFIG_FRESH', path, 'exists; the config is written to a new file, never over the --cloth config or an earlier one');
136
+ refusal('PROPOSE_WRITE_CONFIG_FRESH', path, 'exists; the config is written to a new file, never over the --cloth config or an earlier one (unlike assemble --propose-plan and propose without --cloth, which update an existing --config in place)');
137
137
  };
138
138
  if (fresh) freshAbsent();
139
139
  const temp = join(dirname(path), `.${basename(path)}.rig-parts-${randomBytes(8).toString('hex')}.tmp`);
@@ -182,7 +182,7 @@ export function stageConfigWrite(target: ConfigWriteTarget | FreshConfigWrite, p
182
182
  // refuses an intervening creator atomically; rename would overwrite it.
183
183
  try { (files.publish ?? linkSync)(temp, path); }
184
184
  catch (error) {
185
- if (error instanceof Error && 'code' in error && error.code === 'EEXIST') refusal('PROPOSE_WRITE_CONFIG_FRESH', path, 'exists; the config is written to a new file, never over the --cloth config or an earlier one');
185
+ if (error instanceof Error && 'code' in error && error.code === 'EEXIST') refusal('PROPOSE_WRITE_CONFIG_FRESH', path, 'exists; the config is written to a new file, never over the --cloth config or an earlier one (unlike assemble --propose-plan and propose without --cloth, which update an existing --config in place)');
186
186
  throw error;
187
187
  }
188
188
  cancel();