@yahoo/uds-create-config 5.50.1 → 5.52.0

package/dist/framework/Config.js

@@ -222,6 +222,25 @@ function editionFor(prev, next) {
 */
 const derivedMembersCache = /* @__PURE__ */ new WeakMap();
 const derivedCache = /* @__PURE__ */ new WeakMap();
+/** How many colliding paths a refusal names before it counts the rest. */
+const COLLISIONS_NAMED = 5;
+/** Refuses an edit that leaves paths two sources offer as different entities, which derive neither
+*  and fail the build, naming them and the two ways out. */
+function rejectCollisions(collisions) {
+	const shown = collisions.slice(0, COLLISIONS_NAMED).map(({ kind, path, slugs, local }) => `${kind}:${path} (${[...local ? ["this system"] : [], ...slugs].join(", ")})`).join("; ");
+	const rest = collisions.length > COLLISIONS_NAMED ? `; and ${collisions.length - COLLISIONS_NAMED} more` : "";
+	const one = collisions.length === 1;
+	const local = collisions.some((at) => at.local);
+	const pins = collisions.some((at) => !at.local);
+	let by = "two linked systems";
+	if (local && pins) by = "two linked systems, or by a linked system and this one,";
+	else if (local) by = "a linked system and this one";
+	throw new ConfigRejection([{
+		code: "SOURCE_COLLISION",
+		collisions,
+		message: `This would leave ${collisions.length} ${one ? "path" : "paths"} offered by ${by} as different things, so neither applies: ${shown}${rest}. Take ${one ? "it" : "each"} from the system ${one ? "it" : "each"} should follow (\`linked-system/link\` with \`onLinked: 'take'\`), or make the link that only reaches ${one ? "it" : "them"} \`hybrid\`, so it uses what this system already has.`
+	}]);
+}
 /** The snapshot a derived snapshot came from, while the parent holds a row derivation the child has
 *  not yet checked against itself. See {@link Config.inheritedDerivation}.
 *
@@ -1344,7 +1363,10 @@ var Config = class Config {
 			deferred.reached = true;
 			return applied;
 		}
-		return applied.derivedForEdit(actionOf(patch));
+		return applied.derivedForEdit({
+			action: actionOf(patch),
+			before: this
+		});
 	}
 	/**
 	* `run` with each kind's invariants judged once, on the config it returns, rather than after every
@@ -1372,7 +1394,10 @@ var Config = class Config {
 			const settled = result.derive({ deferredInvariants: void 0 });
 			settled.assertInvariantsOf(settled.state.snapshot, deferred.kinds);
 			if (!deferred.reached) return settled;
-			return settled.derivedForEdit(EDIT_ACTION);
+			return settled.derivedForEdit({
+				action: EDIT_ACTION,
+				before: this
+			});
 		} catch {
 			deferred.open = false;
 			return run(this);
@@ -1403,6 +1428,7 @@ var Config = class Config {
 		if (!onlyReversions(patch, sourceIdentity, this.entityOf(patch.kind)?.sourceOrigin)) applied.assertDerivedDropsUnreferenced();
 		const derived = applied.withDerivedRows();
 		derived.assertDistinctSourceSlugs();
+		if (!onlyReversions(patch, sourceIdentity, this.entityOf(patch.kind)?.sourceOrigin)) this.assertNoNewCollisions(derived);
 		return derived;
 	}
 	/**
@@ -1447,12 +1473,13 @@ var Config = class Config {
 			};
 			const landed = settled();
 			const edits = patches.filter((patch) => !this.entityOf(patch.kind)?.sourceIdentity);
-			if (!(edits.length > 0 && this.reachesDerivation({
+			const derived = edits.length > 0 && this.reachesDerivation({
 				patches: edits,
 				before: this.state.snapshot,
 				after: landed.state.snapshot
-			}))) return landed;
-			return landed.derivedForEdit(actionOf(edits));
+			}) ? landed.derivedForEdit({ action: actionOf(edits) }) : landed;
+			this.assertNoNewCollisions(derived);
+			return derived;
 		}
 		const land = (checked) => {
 			let config = checked ? this : this.derive({ snapshot: this.state.snapshot.drafting() });
@@ -1474,7 +1501,10 @@ var Config = class Config {
 			before: this.state.snapshot,
 			after: config.state.snapshot
 		})) return config;
-		return config.derivedForEdit(actionOf(patches));
+		return config.derivedForEdit({
+			action: actionOf(patches),
+			before: this
+		});
 	}
 	/**
 	* `patches` with each delete preceded by the deletes that go with it, each judged against the state
@@ -1669,8 +1699,8 @@ var Config = class Config {
 	/**
 	* Whether patches on kinds that name no source can change the rows a derive mints between `before`
 	* and `after`: they wrote a pin (an edit to a minted row lands in its pin's `options`), or a row
-	* they touched points at a source, changes which source-qualified refs it holds, or appears or
-	* vanishes at a path a source offers. An authored style bag's keys are this config's own
+	* they touched points at a source, changes which source-qualified refs it holds, appears or vanishes
+	* at a path a source offers, or is a row of this config's own that a linked pin reaches. An authored style bag's keys are this config's own
 	* properties, so they don't count.
 	*
 	* Asked of the patches' own paths rather than of every row, so a batch pays per patch.
@@ -1680,6 +1710,7 @@ var Config = class Config {
 		const slugs = this.sourceSlugs();
 		if (slugs.length === 0) return false;
 		const offered = (kind, path) => slugs.some((slug) => this.sourceFor(slug)?.resolve(kind, path));
+		const shadowed = (kind, path) => this.caches.derivedRows?.shadowed.has(`${kind}:${path}`) ?? false;
 		const reaches = (kind, path) => {
 			return [[before.get(kind, path), after.get(kind, path)], [before.group(kind, path), after.group(kind, path)]].some(([prior, next]) => {
 				if (prior === next) return false;
@@ -1687,7 +1718,8 @@ var Config = class Config {
 				const priorBody = prior?.toJSON() ?? {};
 				const nextBody = next?.toJSON() ?? {};
 				if (pointsAtSource(priorBody) || pointsAtSource(nextBody)) return true;
-				return sourcedRefs(priorBody) !== sourcedRefs(nextBody);
+				if (sourcedRefs(priorBody) !== sourcedRefs(nextBody)) return true;
+				return prior !== void 0 && next !== void 0 && shadowed(kind, path);
 			});
 		};
 		return patches.some((patch) => {
@@ -4510,21 +4542,42 @@ var Config = class Config {
 		return [...reached].sort();
 	}
 	/**
+	* A refusal for a pin patch that would leave paths two sources offer as different entities, which
+	* derive neither and fail the build. Named here, when the patch is made, with the two ways out.
+	*/
+	assertNoNewCollisions(after) {
+		this.assertNoNewCollisionsIn(after.collidingSources());
+	}
+	/** {@link assertNoNewCollisions} against the collisions a derivation already found. */
+	assertNoNewCollisionsIn(collisions) {
+		const before = new Set((this.caches.derivedRows ?? this.rowDerivation()).collisions.map(({ kind, path }) => `${kind}:${path}`));
+		const added = collisions.filter(({ kind, path }) => !before.has(`${kind}:${path}`));
+		if (added.length > 0) rejectCollisions(added);
+	}
+	/**
 	* A refusal for a patch whose derive pass would retire a minted row that something authored here
 	* still points at. A minted row has no body of its own, so once it goes the referrer dangles;
 	* copying what is used, or breaking the link with `keep`, is how the value stays.
 	*
+	* A row retired because two sources now offer its path as different entities is refused as that
+	* collision instead, since resolving the collision is what keeps the row.
+	*
 	* `action` names what is refused, after "Cannot": a pin patch removes the link, and any other patch
 	* that reaches derivation — a deleted extension whose source reached the row — says what it did.
 	*/
 	assertDerivedDropsUnreferenced({ action = "remove the link", derivation = this.rowDerivation() } = {}) {
 		const { snapshot } = this.state;
+		const contested = new Set(derivation.collisions.map(({ kind, path }) => `${kind}:${path}`));
 		const stranded = [];
+		let collides = false;
 		for (const change of derivation.changes) {
 			if (change.value !== void 0) continue;
 			const referrers = this.referrersOf(snapshot, change.kind, change.path).filter((referrer) => !isMintedAt(snapshot, referrer));
-			if (referrers.length > 0) stranded.push(`${change.kind}:${change.path} (used by ${referrers.join(", ")})`);
+			if (referrers.length === 0) continue;
+			if (contested.has(`${change.kind}:${change.path}`)) collides = true;
+			stranded.push(`${change.kind}:${change.path} (used by ${referrers.join(", ")})`);
 		}
+		if (collides) rejectCollisions(derivation.collisions);
 		if (stranded.length === 0) return;
 		reject("REFERRERS_BLOCK", `Cannot ${action} — it would take away ${stranded.join("; ")}. Copy what is used first (\`linked-system/copy\`), or break the link keeping its values (\`linked-system/break\` with \`keep: true\`).`);
 	}
@@ -4608,10 +4661,13 @@ var Config = class Config {
 	* A session derives every value it advances to, so without the mark the same edit would pay for two
 	* derive passes: this one and the session's. The mark covers this instance only, and any later
 	* write is a new config, so each edit still gets exactly one pass, as it did from the session alone.
+	*
+	* `before` is the config the edit was made on, when the edit is refused for a collision it adds.
 	*/
-	derivedForEdit(action) {
+	derivedForEdit({ action, before }) {
 		if (derivedInEdit.has(this)) return this;
 		const derivation = this.rowDerivation();
+		if (derivation.collisions.length > 0) before?.assertNoNewCollisionsIn(derivation.collisions);
 		this.assertDerivedDropsUnreferenced({
 			action,
 			derivation
@@ -4652,6 +4708,14 @@ var Config = class Config {
 		return this.rowDerivation().collisions;
 	}
 	/**
+	* The paths a `hybrid` pin reaches as a different entity from the one another pin offers there.
+	* The other pin's row stands at the path, and what the hybrid pin brings is drawn with it
+	* ({@link drawsWithLocalRow}). Nothing here is refused, so this is what says the two differ.
+	*/
+	settledSources() {
+		return this.rowDerivation().settled;
+	}
+	/**
 	* The derivation made for the snapshot this one came from, when this edit could not have changed
 	* it: the same sources, no change to a pin or to which paths exist, and every row that did change
 	* is authored on both sides with the same source-qualified refs and the same style-bag keys —
@@ -4678,18 +4742,29 @@ var Config = class Config {
 			const after = snapshot.slice(kind);
 			if (before === after) continue;
 			if (sourceKinds.has(kind)) return void 0;
-			if (!this.sameRowsForDerivation(kind, before.items, after.items)) return;
-			if (!this.sameRowsForDerivation(kind, before.groups, after.groups)) return;
+			const { shadowed } = prior;
+			if (!this.sameRowsForDerivation({
+				kind,
+				before: before.items,
+				after: after.items,
+				shadowed
+			}) || !this.sameRowsForDerivation({
+				kind,
+				before: before.groups,
+				after: after.groups,
+				shadowed
+			})) return;
 		}
 		return prior;
 	}
 	/**
-	* Same paths in the same order, and every row that changed is authored on both sides and reaches
-	* the same sources the same way — see {@link inheritedDerivation}. Order counts because the walk
+	* Same paths in the same order, and every row that changed is authored on both sides, isn't one a
+	* linked pin reaches (`shadowed`), and reaches the same sources the same way — see
+	* {@link inheritedDerivation}. Order counts because the walk
 	* visits rows in stored order and mints in the order it reaches them, and key order is meaning
 	* downstream.
 	*/
-	sameRowsForDerivation(kind, before, after) {
+	sameRowsForDerivation({ kind, before, after, shadowed }) {
 		if (before.size !== after.size) return false;
 		const afterPaths = after.keys();
 		for (const [path, prior] of before) {
@@ -4697,6 +4772,7 @@ var Config = class Config {
 			const next = after.get(path);
 			if (!next) return false;
 			if (prior === next) continue;
+			if (shadowed.has(`${kind}:${path}`)) return false;
 			const priorBody = prior.toJSON();
 			const nextBody = next.toJSON();
 			if (pointsAtSource(priorBody) || pointsAtSource(nextBody)) return false;
@@ -4716,26 +4792,34 @@ var Config = class Config {
 		return JSON.stringify([[...sourced].sort(), [...bagKeys].sort()]);
 	}
 	/**
-	* Which of several sources offering `target` takes it, when exactly one pin's `link` declares it and
-	* every other source only reaches it through a borrowed style bag. `undefined` leaves it a collision.
+	* Which of several sources offering `target` takes it. `undefined` leaves it a collision.
 	*
-	* A reaching source counts only while its copy reads the same as the declarer's: one system built on
-	* another, pinned beside that other, reaches the same entity twice. Identity can't be traced instead,
-	* because an attached sibling arrives with what it borrowed inlined to literals. A copy that reads
-	* differently is its own entity, and picking either would hide the other.
+	* A path one pin's `link` declares goes to that pin when every other source only reaches it and
+	* either holds the same entity there or is `hybrid`, which brings in only what no other pin offers.
+	* A `linked` source reaching a different entity at a declared path is a collision.
+	*
+	* A path no pin declares goes to the first `linked` source when every `linked` source holding it
+	* reads the same entity, the `hybrid` ones yielding to them. With only `hybrid` sources it goes to
+	* the first on the same condition. Two pins declaring one path is a collision either way.
 	*/
 	declaringClaimant({ target, slugs, declaredBy }) {
 		const declarers = slugs.filter((slug) => declaredBy.get(slug)?.has(target));
-		const [declarer] = declarers;
-		if (declarer === void 0 || declarers.length > 1) return void 0;
+		if (declarers.length > 1) return void 0;
 		const kind = kindOf(target);
 		const path = pathOf(target);
-		return slugs.every((slug) => slug === declarer || this.sameEntityThrough({
-			held: declarer,
+		const agree = (held, others) => others.every((slug) => slug === held || this.sameEntityThrough({
+			held,
 			other: slug,
 			kind,
 			path
-		})) ? declarer : void 0;
+		}));
+		const linked = slugs.filter((slug) => this.sourceTypeOf(slug) === "linked");
+		const [declarer] = declarers;
+		if (declarer !== void 0) return agree(declarer, linked) ? declarer : void 0;
+		const deciding = linked.length > 0 ? linked : slugs;
+		const [first] = deciding;
+		if (first === void 0) return void 0;
+		return agree(first, deciding) ? first : void 0;
 	}
 	/**
 	* Whether `other`'s entity at `kind:path` is the one `held` offers there: one entity reached through
@@ -4744,14 +4828,60 @@ var Config = class Config {
 	*/
 	sameEntityThrough({ held, other, kind, path }) {
 		const theirs = this.sourceFor(held)?.resolve(kind, path);
+		if (!theirs) return false;
+		return this.sameEntityAs({
+			body: theirs.body,
+			other,
+			kind,
+			path
+		});
+	}
+	/** Whether `other`'s entity at `kind:path` reads as `body`, spelled the way this config spells it. */
+	sameEntityAs({ body, other, kind, path }) {
 		const reaching = this.sourceFor(other);
 		const copy = reaching?.resolve(kind, path);
-		if (!theirs || !reaching || !copy) return false;
+		if (!reaching || !copy) return false;
+		const provenance = Object.fromEntries([...this.entityOf(kind)?.computedKeys ?? [], "copiedFrom"].map((key) => [key, void 0]));
 		const entityOf = (body) => JSON.stringify({
 			...body,
-			borrowedFrom: void 0
+			...provenance
+		});
+		const bare = [...new Set([...reaching.sourceSlugs(), ...collectRefs(copy.body).flatMap((marker) => sourceOf(marker) ?? [])])].reduce((body, slug) => rewriteRefSource(body, slug, void 0), copy.body);
+		const ours = rewriteRefSource(body, other, void 0);
+		return entityOf(bare) === entityOf(ours);
+	}
+	/** How `slug`'s source joins this config ({@link EntityKind.sourceType}): `linked` unless its pin
+	*  says otherwise. */
+	sourceTypeOf(slug) {
+		for (const sourceKind of this.sourceKinds()) {
+			const asks = this.entityOf(sourceKind)?.sourceType;
+			const pin = this.storedBody(sourceKind, slug);
+			if (asks && pin) return asks(pin);
+		}
+		return "linked";
+	}
+	/**
+	* Whether a value `slug` brings is drawn with this config's row at `kind:path` rather than declared
+	* under the pin's own name: a token that something taken through `slug` names.
+	*
+	* A `hybrid` pin binds to any row here that isn't its own, authored or held through another pin, so
+	* what it brings uses this config's values. A `linked` pin binds only to a row held through another
+	* pin that is the same entity, the way {@link heldThroughAnotherPin} reads it; a different one there
+	* is a collision, and a row this config authored is its own entity under the same name.
+	*/
+	drawsWithLocalRow({ slug, kind, path }) {
+		const stored = this.storedBody(kind, path);
+		if (stored === void 0) return false;
+		const held = isRef(stored) ? sourceOf(stored.__ref) : void 0;
+		if (held === slug) return false;
+		if (this.sourceTypeOf(slug) === "hybrid") return true;
+		if (!isMintedRow(stored) || held === void 0) return false;
+		return this.sameEntityThrough({
+			held,
+			other: slug,
+			kind,
+			path
 		});
-		return entityOf([...new Set([...reaching.sourceSlugs(), ...collectRefs(copy.body).flatMap((marker) => sourceOf(marker) ?? [])])].reduce((body, slug) => rewriteRefSource(body, slug, void 0), copy.body)) === entityOf(theirs.body);
 	}
 	/**
 	* Whether `slug`'s entity at `kind:path` is one this config already holds through another pin, so a
@@ -4813,6 +4943,10 @@ var Config = class Config {
 		const declaredBy = /* @__PURE__ */ new Map();
 		/** The slugs whose source answered this pass, so a row of theirs that went unproduced is gone. */
 		const consulted = /* @__PURE__ */ new Set();
+		/** Per target, the linked slugs that reach a different entity than this config's own row there. */
+		const ownedAgainst = /* @__PURE__ */ new Map();
+		/** Every row of this config's own a linked pin reaches without declaring it. */
+		const shadowed = /* @__PURE__ */ new Set();
 		for (const slug of this.sourceSlugs()) {
 			const source = this.sourceFor(slug);
 			if (!source) continue;
@@ -4821,17 +4955,29 @@ var Config = class Config {
 			const mine = [];
 			const declared = new Set(this.adoptedFrom(slug));
 			declaredBy.set(slug, declared);
+			const strict = this.sourceTypeOf(slug) === "linked";
 			const wanted = new Set([...declared, ...this.groupRefMembers(slug)]);
 			for (const target of wanted) {
 				const kind = kindOf(target);
 				const path = pathOf(target);
-				if (!kindBorrowable(this.entityOf(kind), {
+				const entry = this.entityOf(kind);
+				if (!kindBorrowable(entry, {
 					config: this,
 					source
 				})) continue;
 				if (this.sourceExcludes(slug, kind, path)) continue;
 				const current = this.state.snapshot.get(kind, path);
-				if (current && !isMintedRow(current.toJSON())) continue;
+				if (current && !isMintedRow(current.toJSON())) {
+					const judged = strict && !entry?.answeredHere && !declared.has(target) && !isRef(current.toJSON()) && !placed.has(target);
+					if (judged) shadowed.add(target);
+					if (judged && source.resolve(kind, path) && !this.sameEntityAs({
+						body: current.body,
+						other: slug,
+						kind,
+						path
+					})) ownedAgainst.set(target, [...ownedAgainst.get(target) ?? [], slug]);
+					continue;
+				}
 				if (placed.has(target)) continue;
 				if (!source.resolve(kind, path)) continue;
 				if (!this.canBorrow({
@@ -4844,7 +4990,13 @@ var Config = class Config {
 			}
 			offeredBy.set(slug, mine);
 		}
-		const collisions = [];
+		const collisions = [...ownedAgainst].map(([target, slugs]) => ({
+			kind: kindOf(target),
+			path: pathOf(target),
+			slugs,
+			local: true
+		}));
+		const settled = [];
 		/** Every target this pass will derive a row for, and the slug it comes from. */
 		const claimedFrom = /* @__PURE__ */ new Map();
 		for (const [target, slugs] of wantedBy) {
@@ -4862,6 +5014,22 @@ var Config = class Config {
 				continue;
 			}
 			claimedFrom.set(target, claimant);
+			if (slugs.length > 1) {
+				const kind = kindOf(target);
+				const path = pathOf(target);
+				const over = slugs.filter((slug) => slug !== claimant && !this.sameEntityThrough({
+					held: claimant,
+					other: slug,
+					kind,
+					path
+				}));
+				if (over.length > 0) settled.push({
+					kind,
+					path,
+					kept: claimant,
+					over
+				});
+			}
 		}
 		const folders = [];
 		/** Folders this pass leaves as they stand — already held, over rows it still claims. */
@@ -4964,7 +5132,9 @@ var Config = class Config {
 		}
 		const planned = {
 			changes,
-			collisions
+			collisions,
+			settled,
+			shadowed
 		};
 		this.caches.derivedRows = planned;
 		return planned;
@@ -5171,6 +5341,7 @@ var Config = class Config {
 				});
 				continue;
 			}
+			if (local !== void 0 && !isMintedRow(local) && !(isRef(local) && sourceOf(local.__ref) === slug)) continue;
 			const body = source.resolve(kindOf(target), pathOf(target))?.toJSON();
 			if (body) visitEntity(kindOf(target), body, true, true);
 		}
@@ -5873,7 +6044,7 @@ var Config = class Config {
 	*  links from the provided sources. A declared `linkedKind` with no provided source throws. */
 	hydrateFrom(stored, options) {
 		const claimed = schemaVersionOf(stored);
-		if (claimed > 20261022152120) throw new SchemaVersionTooNew(claimed);
+		if (claimed > 20261022184639) throw new SchemaVersionTooNew(claimed);
 		const wire = upgradeSerializedConfig(stored);
 		if (!Array.isArray(wire.ownedKinds) || typeof wire.items !== "object" || wire.items === null) throw new ConfigFormatError(`Config "${stored.name ?? "system-config"}" cannot be hydrated: this is not a serialized config-v2 config (no "ownedKinds"/"items"). A pre-cutover build artifact converts through the registered cutover migration — import the config type's module (e.g. \`configs/system\`) before hydrating.`);
 		const leftover = wire.options;

package/dist/framework/defineEntity.d.ts

@@ -5,7 +5,7 @@ import { CreateInput, FieldsSchema } from "./utils/field-schema.js";
 import { FieldsCtx, UserSchemas } from "./schemas.js";
 import { SubEntityClass } from "./defineSubEntity.js";
 import { BulkOverlayWrite, BulkQuery, SourceOverlay, SourceResolutionSchemas } from "./sources.js";
-import { AuthoredValueForm, ComputedFields, EntityKind, Linkable } from "./registry.js";
+import { AuthoredValueForm, ComputedFields, EntityKind, Linkable, SourceType } from "./registry.js";
 import { PathOf } from "./registered.js";
 import { GroupBody, GroupInputValues, GroupInputs } from "./utils/group.js";
 import { Config, ListOptions, TreeNode } from "./Config.js";
@@ -310,7 +310,9 @@ declare function defineEntity<F extends FieldsSchema, G extends FieldsSchema = z
    * mean the ref has to say which.
    */
   bareMember?: string; /** Whether a leaf names an item on its own — see {@link EntityKind.uniqueLeaves}. */
-  uniqueLeaves?: boolean;
+  uniqueLeaves?: boolean; /** For a source kind: how a pin's source joins this config. See {@link EntityKind.sourceType}. */
+  sourceType?: (body: Record<string, unknown>) => SourceType; /** This config answers for every item of the kind. See {@link EntityKind.answeredHere}. */
+  answeredHere?: boolean;
   /**
    * Registration-time inputs `group()` takes beside the group's fields, keyed by body key. Each is
    * handed to its handler with the rest of the body and stripped before the body is branded, so the

package/dist/framework/defineEntity.js

@@ -135,7 +135,9 @@ function defineEntity(spec) {
 		mentionFields: spec.mentionFields,
 		invariants: spec.invariants,
 		structuralBody: spec.structuralBody,
-		authoredBody: spec.authoredBody
+		authoredBody: spec.authoredBody,
+		sourceType: spec.sourceType,
+		answeredHere: spec.answeredHere
 	});
 	const schema = refTo(spec.kind);
 	/**

package/dist/framework/projections.js

@@ -83,7 +83,7 @@ function linkedVarNaming(config, slug) {
 	return (tokenPath) => {
 		const local = held.get(tokenPath);
 		if (local !== void 0) return cssVar(config, "token", local);
-		if (config.heldThroughAnotherPin({
+		if (config.drawsWithLocalRow({
 			slug,
 			kind: "token",
 			path: tokenPath

package/dist/framework/registry.d.ts

@@ -297,6 +297,17 @@ interface EntityKind {
    * can be read but never edited through a minted row.
    */
   readonly bulkOverlayWrite?: (args: BulkOverlayWrite) => Record<string, unknown>;
+  /**
+   * Declared by a source kind: how a pin's source joins this config, read off the pin's body.
+   * {@link Config.sourceTypeOf} asks it.
+   */
+  readonly sourceType?: (body: Record<string, unknown>) => SourceType;
+  /**
+   * This config answers for every item of the kind, whatever a linked pin reaches: a borrowed value
+   * conditioned on one names it by path, and this config's item of that path is the one that holds.
+   * A source's different item at a path this config holds is never a collision.
+   */
+  readonly answeredHere?: true;
   /**
    * Edges this kind's data implies by name rather than by ref — `nameEdges(body)` for one item.
    *
@@ -389,9 +400,20 @@ interface EntityKind {
     element?: unknown;
   }[];
 }
+/** Derive a kind's immutable metadata from its field schemas — the value a `defineEntity`/
+ *  `defineDerivedEntity` attaches to its class and a `Config.register` stores in `#entities`. */
+/**
+ * How a pin's source joins a config.
+ *
+ * - `linked`: everything a linked entity references lands as a row from this pin, and a path another
+ *   pin offers as a different entity is a collision.
+ * - `hybrid`: it brings in only what no other pin offers. Where another pin offers a path, that pin's
+ *   row stands, and what this pin brings uses it; a component it renders stays its own source's.
+ */
+type SourceType = 'linked' | 'hybrid';
 /** Every operation a kind exposes — its merged `schemas` map, flattened to `{ kind, verb, ... }`.
  *  The single derivation the Operation entity maps over; nothing hardcodes a CRUD list. Reads the
  *  kind def a `Config` holds (`config.entityOf(kind)`); `undefined` → no ops. */
 declare function opsForKind(entry: EntityKind | undefined, config?: Config): DerivedOp[];
 //#endregion
-export { AuthoredValueForm, ComputedFields, ComputedInput, EntityKind, LayerKey, Linkable, opsForKind };
+export { AuthoredValueForm, ComputedFields, ComputedInput, EntityKind, LayerKey, Linkable, SourceType, opsForKind };

package/dist/framework/registry.js

@@ -29,10 +29,8 @@ function entityClassName(kind) {
 function titleCase(kind) {
 	return kind.split(/[-_]/).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
 }
-/** Derive a kind's immutable metadata from its field schemas — the value a `defineEntity`/
-*  `defineDerivedEntity` attaches to its class and a `Config.register` stores in `#entities`. */
 function buildKind(spec) {
-	const { name, prepareLinkedBody, rebaseLinkedBody, layerKeys, fields, groupFields, subEntities = {}, computed, label, labelPlural, schemas: userSchemas, derived, sourceIdentity, sourceOrigin, authoredRefs, linkable, localGroupFields, emergentGroups, singleton = false, bareMember, sourceResolution, bulkAdopts, bulkExcludes, bulkOverlay, bulkDirectives, bulkOverlayWrite, nameEdges, rewriteName, styleBags, uniqueLeaves, authoredValue, mentionFields, invariants, structuralBody, authoredBody } = spec;
+	const { name, prepareLinkedBody, rebaseLinkedBody, layerKeys, fields, groupFields, subEntities = {}, computed, label, labelPlural, schemas: userSchemas, derived, sourceIdentity, sourceOrigin, authoredRefs, linkable, localGroupFields, emergentGroups, singleton = false, bareMember, sourceResolution, bulkAdopts, bulkExcludes, bulkOverlay, bulkDirectives, bulkOverlayWrite, nameEdges, rewriteName, styleBags, uniqueLeaves, authoredValue, mentionFields, invariants, structuralBody, authoredBody, sourceType, answeredHere } = spec;
 	const allComputed = {
 		sources: ({ member, config }) => sourceSlugs(member, config),
 		borrowedFrom: ({ config, path }) => config.borrowedFrom(name, path),
@@ -85,7 +83,9 @@ function buildKind(spec) {
 		...mentionFields?.length ? { mentionFields } : {},
 		...invariants ? { invariants } : {},
 		...structuralBody ? { structuralBody } : {},
-		...authoredBody ? { authoredBody } : {}
+		...authoredBody ? { authoredBody } : {},
+		...sourceType ? { sourceType } : {},
+		...answeredHere ? { answeredHere: true } : {}
 	};
 }
 /** Every operation a kind exposes — its merged `schemas` map, flattened to `{ kind, verb, ... }`.

package/dist/framework/rejection.d.ts

@@ -1,3 +1,4 @@
+import { SourceCollision } from "./Config.js";
 import { z } from "zod";
 
 //#region src/framework/rejection.d.ts
@@ -22,7 +23,10 @@ type ConfigIssueCode = /** Nothing at that path / no such member — an update,
 | 'UNSUPPORTED'
 /** A delete that something still points at. Carries the referrers, because "42 things break" is
  *  only actionable as a list of which ones. */
-| 'REFERRERS_BLOCK';
+| 'REFERRERS_BLOCK'
+/** A pin patch that would leave a path two linked systems offer as different entities, which
+ *  derives neither. Carries the collisions. */
+| 'SOURCE_COLLISION';
 interface ConfigIssue {
   readonly code: ConfigIssueCode;
   readonly message: string;
@@ -33,6 +37,9 @@ interface ConfigIssue {
   /** What still points at the target of a refused delete, as `kind:path` refs — the
    *  `REFERRERS_BLOCK` list, so a surface can name each one in its own words. */
   readonly referrers?: readonly string[];
+  /** The paths a refused edit would leave two linked systems offering as different entities — the
+   *  `SOURCE_COLLISION` list, so a surface can say what differs in its own words. */
+  readonly collisions?: readonly SourceCollision[];
 }
 /**
  * A write this config refused. `issues` is never empty; `message` joins them so an uncaught one still

package/dist/framework/schema-version.d.ts

@@ -15,7 +15,7 @@ import { Patch, SerializedConfig } from "./Config.js";
  * sets this constant to its own older timestamp; the merge ref then carries a registered migration
  * newer than the constant, and the assertion fails until the author re-mints.
  */
-declare const CURRENT_SCHEMA_VERSION = 20261022152120;
+declare const CURRENT_SCHEMA_VERSION = 20261022184639;
 /** What the walkers need to see of an envelope — loose on purpose, so a typed `SerializedConfig`
  *  and a raw old-shape record both flow in without casts. */
 interface VersionStamped {

package/dist/framework/schema-version.js

@@ -13,7 +13,7 @@ import { ConfigFormatError } from "./rejection.js";
 * sets this constant to its own older timestamp; the merge ref then carries a registered migration
 * newer than the constant, and the assertion fails until the author re-mints.
 */
-const CURRENT_SCHEMA_VERSION = 20261022152120;
+const CURRENT_SCHEMA_VERSION = 20261022184639;
 /** The mint that moved `options` into the `settings` kind — restated here, rather than imported
 *  from the migration that owns it, because that migration imports this module. */
 const SETTINGS_AS_KIND_VERSION = 20260908171448;
@@ -45,7 +45,7 @@ function registerSchemaMigrations(...migrations) {
 	for (const migration of migrations) {
 		if (migration.version !== 1 && !isMintTimestamp(migration.version)) throw new Error(`Schema migration version ${migration.version} is not a mint timestamp — mint one with \`date +%Y%m%d%H%M%S\`, like a supabase migration.`);
 		if (REGISTERED.has(migration.version)) throw new Error(`A schema migration at version ${migration.version} is already registered.`);
-		if (migration.version > 20261022152120) throw new Error(`Schema migration ${migration.version} is newer than CURRENT_SCHEMA_VERSION (${CURRENT_SCHEMA_VERSION}) — a stale branch merged, or the mint forgot to bump the constant. Re-mint: set CURRENT_SCHEMA_VERSION to the newest migration version.`);
+		if (migration.version > 20261022184639) throw new Error(`Schema migration ${migration.version} is newer than CURRENT_SCHEMA_VERSION (${CURRENT_SCHEMA_VERSION}) — a stale branch merged, or the mint forgot to bump the constant. Re-mint: set CURRENT_SCHEMA_VERSION to the newest migration version.`);
 		REGISTERED.set(migration.version, migration);
 	}
 }
@@ -102,7 +102,7 @@ function pendingFor(version, target, options) {
 * Already-current input passes through untouched — same reference, so hot paths pay nothing.
 */
 function upgradeSerializedConfig(json, options) {
-	const target = options?.target ?? 20261022152120;
+	const target = options?.target ?? 20261022184639;
 	const version = detectedWireVersion(json);
 	if (version > target) throw new SchemaVersionTooNew(version, target);
 	const raw = json;
@@ -160,7 +160,7 @@ function upgradedSources(json, options) {
 * meaning under the current schema and replay skips it — reported by the caller, not swallowed here.
 */
 function upgradePatch(patch, writtenAt, options) {
-	const target = options?.target ?? 20261022152120;
+	const target = options?.target ?? 20261022184639;
 	if (writtenAt > target) throw new SchemaVersionTooNew(writtenAt, target);
 	let current = patch;
 	for (const migration of pendingFor(writtenAt, target, options)) {
@@ -179,7 +179,7 @@ function upgradePatch(patch, writtenAt, options) {
 * stamp would cause.
 */
 function upgradeDraftEntries(draft, options) {
-	const target = options?.target ?? 20261022152120;
+	const target = options?.target ?? 20261022184639;
 	const entries = [];
 	const held = [];
 	const retired = [];