@yahoo/uds-create-config 5.27.1 → 5.29.0

package/dist/entities/system/link-plan.js

@@ -1,7 +1,8 @@
 import { rejectData } from "../../framework/rejection.js";
 import { collectRefs, isMintedRow, ref, sourceOf, splitRef } from "../../framework/utils/refs.js";
 import { blockedBy } from "../../framework/plan.js";
-import { PIN_KIND, covers, declarationOf, narrowDeclaration } from "./link-declaration.js";
+import { excludedCondition } from "../../framework/source-integrity.js";
+import { PIN_KIND, covers, declarationOf, entriesFor, excludePaths, excludes, includePaths, narrowDeclaration } from "./link-declaration.js";
 import { planCopy, sourceEntries } from "./copy-plan.js";
 //#region src/entities/system/link-plan.ts
 /** The kinds `data` names, with what to take of each. An accessor this config has no kind for is a typo, refused by name. */
@@ -201,7 +202,7 @@ function planLink({ config, input }) {
 	} else {
 		const next = { ...current ?? {} };
 		for (const [accessor, gain] of gains) {
-			const before = next[accessor];
+			const before = entriesFor(current, accessor);
 			if (before === "*") continue;
 			if (gain === "*") {
 				next[accessor] = "*";
@@ -213,7 +214,13 @@ function planLink({ config, input }) {
 				path
 			}));
 			if (added.length === 0) continue;
-			next[accessor] = [...before ?? [], ...new Set(added)];
+			next[accessor] = includePaths({
+				config,
+				slug,
+				kind: config.accessors()[accessor]?.kind ?? accessor,
+				entries: before ?? [],
+				paths: [...new Set(added)]
+			});
 		}
 		for (const [accessor, value] of Object.entries(next)) {
 			if (current !== void 0 && current[accessor] === value) continue;
@@ -361,6 +368,104 @@ function planUnlink({ config, input }) {
 	};
 }
 /**
+* Leave paths of a linked system out, with a `!` entry each in the pin's `link`. Stronger than
+* `unlink`: nothing derives there however the link reaches it, a linked token naming it included,
+* and the linked tokens' overrides under an excluded modifier are left out of the build. `link` with
+* the same path lifts it again.
+*/
+function planExclude({ config, input }) {
+	const { path: slug } = input;
+	const source = config.sourceFor(slug);
+	if (!source) rejectData(`Cannot exclude through "${slug}" — nothing has resolved that link.`);
+	const current = declarationOf(config, slug);
+	const next = current === void 0 ? {} : current === "*" ? { "*": "*" } : { ...current };
+	for (const { kind, accessor, paths } of wantedKinds({
+		config,
+		slug,
+		data: input.data,
+		verb: "exclude"
+	})) {
+		if (paths === "*") rejectData(`Cannot exclude every "${accessor}" through "${slug}" — name the paths to leave out, or \`unlink\` the kind.`, ["data", accessor]);
+		for (const path of paths) if (sourceEntries({
+			source,
+			kind,
+			path
+		}).length === 0) rejectData(`Cannot exclude "${path}" through "${slug}" — the source has no ${kind} there.`, ["data", accessor]);
+		next[accessor] = excludePaths(entriesFor(current, accessor), paths);
+	}
+	const declared = next;
+	const dropped = [];
+	const optionDeletes = {};
+	const options = config.storedBody("linked-system", slug).options ?? {};
+	for (const [accessor, entries] of Object.entries(options)) {
+		if (!entries || typeof entries !== "object") continue;
+		const kind = config.accessors()[accessor]?.kind ?? accessor;
+		for (const path of Object.keys(entries)) {
+			if (!excludes({
+				declared,
+				accessor,
+				path
+			})) continue;
+			dropped.push({
+				kind,
+				path
+			});
+			optionDeletes[`options.${accessor}.${path}`] = null;
+		}
+	}
+	const patches = [{
+		kind: PIN_KIND,
+		operation: "update",
+		path: slug,
+		data: {
+			link: declared,
+			...optionDeletes
+		}
+	}];
+	if (Object.entries(input.data).every(([accessor, paths]) => paths.every((path) => excludes({
+		declared: current,
+		accessor,
+		path
+	})))) return {
+		declared: current,
+		removed: [],
+		leftOut: [],
+		dropped: [],
+		blocked: `Nothing would change: what "${slug}" declares already leaves everything named out.`,
+		patches: []
+	};
+	const blocked = blockedBy(() => config.applyAll(patches));
+	const removed = [];
+	const leftOut = [];
+	if (blocked === void 0) {
+		const after = config.applyAll(patches);
+		for (const kind of config.borrowableKinds(slug)) for (const item of config.list(kind)) {
+			if (item.borrowedFrom !== slug) continue;
+			if (after.resolve(kind, item.path)?.borrowedFrom === slug) continue;
+			removed.push({
+				kind,
+				path: item.path
+			});
+		}
+		for (const item of after.list("token")) {
+			if (item.borrowedFrom !== slug) continue;
+			const body = source.resolve("token", item.path)?.toJSON();
+			for (const [override, { on }] of Object.entries(body?.overrides ?? {})) if (excludedCondition(after, on)) leftOut.push({
+				token: item.path,
+				override
+			});
+		}
+	}
+	return {
+		declared,
+		removed,
+		leftOut,
+		dropped,
+		...blocked === void 0 ? {} : { blocked },
+		patches
+	};
+}
+/**
 * The linked rows that point at what `data` names, followed to a fixpoint: a row pointing at one of
 * those, and so on. Read off both ref graphs, since a linked row's refs are the source's spelling and
 * this config's index holds them qualified.
@@ -832,4 +937,4 @@ function sourceRowStates({ config, slug }) {
 	return rows;
 }
 //#endregion
-export { planBreak, planLink, planUnlink, sourceRowStates };
+export { planBreak, planExclude, planLink, planUnlink, sourceRowStates };

package/dist/framework/Config.d.ts

@@ -73,7 +73,7 @@ interface RecordedSource {
  * The dense-counter `2` a short-lived scheme stamped before the chain existed reads as the mint
  * that replaced it (see `detectedWireVersion`).
  */
-declare const SERIALIZED_CONFIG_VERSION = 20261013164300;
+declare const SERIALIZED_CONFIG_VERSION = 20261013201548;
 interface SerializedConfig {
   /** See {@link SERIALIZED_CONFIG_VERSION}. Always written; a stored artifact may lack it. */
   readonly version: number;
@@ -1785,6 +1785,11 @@ declare class Config {
    * subject is the overlay rather than whether a row is minted at all.
    */
   sourceOverlay(slug: string, kind: string, path: string): SourceOverlay | undefined;
+  /**
+   * Whether the declared source at `slug` excludes one of its paths ({@link EntityKind.bulkExcludes}):
+   * left out on purpose, so no row derives there. Matched on the path the source spells.
+   */
+  sourceExcludes(slug: string, kind: string, path: string): boolean;
   /**
    * The field-path delta that records `overlay` as the pin's directive for one path, or `null` when
    * there is nothing to write.

package/dist/framework/Config.js

@@ -1,6 +1,6 @@
 import "./config-operation-kind.js";
 import { ConfigFormatError, ConfigRejection, isConfigRejection, issuePath, refusalIssues, reject, rejectData, rejectInvalid, rejectReferrers } from "./rejection.js";
-import { ENTITY_PATH_MESSAGE, MINTED, collectRefs, entityRefOf, isEntityPath, isExtendedRef, isMintedRow, isRef, kindOf, memberOf, memberRef, pathOf, qualifyRefs, ref, rewriteRefNamespace, rewriteRefSource, rewriteRefs, routedSource, singletonRef, sourceHops, sourceOf, splitRef } from "./utils/refs.js";
+import { MINTED, collectRefs, entityPathProblem, entityRefOf, isExtendedRef, isMintedRow, isRef, kindOf, memberOf, memberRef, pathOf, qualifyRefs, ref, rewriteRefNamespace, rewriteRefSource, rewriteRefs, routedSource, singletonRef, sourceHops, sourceOf, splitRef } from "./utils/refs.js";
 import { describePatch } from "./plan.js";
 import { applyPathDelta, isPlainObject, namedFields, pathSegments, sectionDelta, touchedFields } from "./utils/field-path.js";
 import { METADATA_KEYS, declaredField } from "./utils/field-schema.js";
@@ -2023,7 +2023,8 @@ var Config = class Config {
 		if (!entry.schemas[verb]) reject("UNSUPPORTED", `${patch.kind} has no ${verb} operation`);
 		if (entry.singleton && "path" in patch && patch.path !== void 0 && patch.path !== entry.name) reject("INVALID_PATH", `${patch.kind} has one item, at "${entry.name}" — leave \`path\` out. A field is written by its path in \`data\` (\`{ "${patch.path}": … }\`) or through sub-update/<section>.`);
 		if (patch.operation === "create") {
-			if (!isEntityPath(patch.path)) reject("INVALID_PATH", `Cannot create ${patch.kind} "${patch.path}" — ${ENTITY_PATH_MESSAGE}`);
+			const problem = entityPathProblem(patch.path);
+			if (problem !== void 0) reject("INVALID_PATH", `Cannot create ${patch.kind} "${patch.path}" — ${problem}`);
 			const occupant = snapshot.get(patch.kind, patch.path);
 			if (occupant && !isMintedRow(occupant.toJSON())) reject("ALREADY_EXISTS", `${patch.kind} "${patch.path}" already exists`);
 			return snapshot.withChanges([this.wholeBodyChange({
@@ -2113,7 +2114,8 @@ var Config = class Config {
 			}]);
 		}
 		if (patch.operation === "rename") {
-			if (!isEntityPath(patch.to)) reject("INVALID_PATH", `Cannot rename ${patch.kind} "${patch.path}" to "${patch.to}" — ${ENTITY_PATH_MESSAGE}`);
+			const problem = entityPathProblem(patch.to);
+			if (problem !== void 0) reject("INVALID_PATH", `Cannot rename ${patch.kind} "${patch.path}" to "${patch.to}" — ${problem}`);
 			const occupant = patch.to === patch.path ? void 0 : snapshot.get(patch.kind, patch.to);
 			if (occupant && !isMintedRow(occupant.toJSON())) reject("ALREADY_EXISTS", `Cannot rename ${patch.kind} "${patch.path}" to "${patch.to}" — a ${patch.kind} already exists there.`);
 			const storedBody = stored;
@@ -3612,6 +3614,23 @@ var Config = class Config {
 		return this.sourceDirective(slug, kind, path).overlay;
 	}
 	/**
+	* Whether the declared source at `slug` excludes one of its paths ({@link EntityKind.bulkExcludes}):
+	* left out on purpose, so no row derives there. Matched on the path the source spells.
+	*/
+	sourceExcludes(slug, kind, path) {
+		const accessor = this.accessorOf(kind);
+		return this.sourceKinds().some((sourceKind) => {
+			const excludes = this.entityOf(sourceKind)?.bulkExcludes;
+			const pin = this.storedBody(sourceKind, slug);
+			return excludes !== void 0 && pin !== void 0 && excludes({
+				body: pin,
+				kind,
+				accessor,
+				path
+			});
+		});
+	}
+	/**
 	* The field-path delta that records `overlay` as the pin's directive for one path, or `null` when
 	* there is nothing to write.
 	*
@@ -4791,6 +4810,7 @@ var Config = class Config {
 					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 (placed.has(target)) continue;
@@ -5833,7 +5853,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 > 20261013164300) throw new SchemaVersionTooNew(claimed);
+		if (claimed > 20261013201548) 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, or port the repo once with \`uds migrate\`.`);
 		const leftover = wire.options;
@@ -5952,7 +5972,8 @@ function isPathSegment(meta, kind, raw) {
 function loadItemChange(meta, kind, path, raw, phase = "author") {
 	const entry = meta.entities.get(kind);
 	if (!entry) throw new Error(`Unknown entity kind: ${kind}`);
-	if (phase === "author" && !isEntityPath(path)) reject("INVALID_PATH", `${kind} "${path}" — ${ENTITY_PATH_MESSAGE}`);
+	const problem = phase === "author" ? entityPathProblem(path) : void 0;
+	if (problem !== void 0) reject("INVALID_PATH", `${kind} "${path}" — ${problem}`);
 	if (phase === "author") refusePhantomsIn({
 		kind,
 		path,
@@ -6200,7 +6221,8 @@ function itemChange(entry, kind, path, raw, validate = false) {
 function loadGroupChange(meta, kind, path, raw, phase = "author") {
 	const entry = meta.entities.get(kind);
 	if (!entry) throw new Error(`Unknown entity kind: ${kind}`);
-	if (phase === "author" && !isEntityPath(path)) reject("INVALID_PATH", `${kind} group "${path}" — ${ENTITY_PATH_MESSAGE}`);
+	const problem = phase === "author" ? entityPathProblem(path) : void 0;
+	if (problem !== void 0) reject("INVALID_PATH", `${kind} group "${path}" — ${problem}`);
 	if (phase === "author") refusePhantomsIn({
 		kind,
 		path,

package/dist/framework/defineEntity.d.ts

@@ -338,10 +338,11 @@ declare function defineEntity<F extends FieldsSchema, G extends FieldsSchema = z
    */
   bulkAdopts?: (args: BulkQuery) => boolean;
   /**
-   * Whether the pin declines this path — the counterpart to {@link EntityKind.bulkAdopts}, and the
-   * tombstone `link`'s own note asks for. A declined path derives no row, so the name is free for
-   * this config to author, and the source's entity stays reachable qualified.
+   * Whether the pin leaves this path out on purpose — the counterpart to {@link EntityKind.bulkAdopts}.
+   * An excluded path derives no row however the link reaches it, so the name is free for this config
+   * to author, and the source's entity stays reachable qualified.
    */
+  bulkExcludes?: (args: BulkQuery) => boolean;
   /**
    * What the declared source lays over the entity at this path, when it declares anything — the
    * bodies a minted row carries in place of an empty `extend`, so a bulk adjustment and a hand-written

package/dist/framework/defineEntity.js

@@ -120,6 +120,7 @@ function defineEntity(spec) {
 		bareMember: spec.bareMember,
 		sourceResolution: spec.sourceResolution,
 		bulkAdopts: spec.bulkAdopts,
+		bulkExcludes: spec.bulkExcludes,
 		bulkOverlay: spec.bulkOverlay,
 		bulkDirectives: spec.bulkDirectives,
 		bulkOverlayWrite: spec.bulkOverlayWrite,

package/dist/framework/registry.d.ts

@@ -260,6 +260,11 @@ interface EntityKind {
    * nothing, and no delete is ever refused for it.
    */
   readonly bulkAdopts?: (args: BulkQuery) => boolean;
+  /**
+   * Whether the declaration leaves this path out on purpose. An excluded path derives no row, and an
+   * excluded modifier is one the source's tokens may vary under without this config stating it.
+   */
+  readonly bulkExcludes?: (args: BulkQuery) => boolean;
   /** What the declared source lays over the entity at this path, when it declares anything. */
   readonly bulkOverlay?: (args: BulkQuery) => SourceOverlay | undefined;
   /**

package/dist/framework/registry.js

@@ -32,7 +32,7 @@ function titleCase(kind) {
 /** 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, bulkOverlay, bulkDirectives, bulkOverlayWrite, nameEdges, rewriteName, styleBags, uniqueLeaves, authoredValue, mentionFields, invariants, structuralBody } = 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 } = spec;
 	const allComputed = {
 		sources: ({ member, config }) => sourceSlugs(member, config),
 		borrowedFrom: ({ config, path }) => config.borrowedFrom(name, path),
@@ -73,6 +73,7 @@ function buildKind(spec) {
 		...bareMember ? { bareMember } : {},
 		...sourceResolution ? { sourceResolution } : {},
 		...bulkAdopts ? { bulkAdopts } : {},
+		...bulkExcludes ? { bulkExcludes } : {},
 		...bulkOverlay ? { bulkOverlay } : {},
 		...bulkDirectives ? { bulkDirectives } : {},
 		...bulkOverlayWrite ? { bulkOverlayWrite } : {},

package/dist/framework/rejection.d.ts

@@ -8,8 +8,10 @@ import { z } from "zod";
  */
 type ConfigIssueCode = /** Nothing at that path / no such member — an update, delete or rename with no target. */'NOT_FOUND' /** A create over an existing path, or a rename onto a taken one. */ | 'ALREADY_EXISTS'
 /**
- * The address cannot be an identity — a path carrying `@` other than as a leading npm scope, which
- * `isEntityPath` refuses because it cannot be told apart from a borrowed address.
+ * The address cannot be an identity — a path `entityPathProblem` refuses: one carrying `@` other
+ * than as a leading npm scope, or `#`, or with an empty segment, or a segment starting with `!` or
+ * that is `*`. Each misreads as another address: a borrowed one, a member, a link's exclusion or
+ * its wildcard.
  *
  * A distinct code rather than `INVALID_DATA`: nothing about the data is wrong, and the surface that
  * reports it is a name field rather than a form. This is a distinction `apply` genuinely makes.

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 = 20261013164300;
+declare const CURRENT_SCHEMA_VERSION = 20261013201548;
 /** 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 = 20261013164300;
+const CURRENT_SCHEMA_VERSION = 20261013201548;
 /** 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 > 20261013164300) 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 > 20261013201548) 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 ?? 20261013164300;
+	const target = options?.target ?? 20261013201548;
 	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 ?? 20261013164300;
+	const target = options?.target ?? 20261013201548;
 	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 ?? 20261013164300;
+	const target = options?.target ?? 20261013201548;
 	const entries = [];
 	const held = [];
 	const retired = [];

package/dist/framework/source-integrity.d.ts

@@ -232,7 +232,14 @@ interface UnstatableCondition {
     consumer: ModifierCategory | 'plain';
   };
 }
-/** Borrowed conditions need a consumer modifier with the same name and category. */
+/**
+ * Whether an override's condition names a modifier this config doesn't hold because a pin excludes
+ * it ({@link Config.sourceExcludes}). Such an override is left out, as the stylesheet leaves out a
+ * condition it cannot state, and the build doesn't refuse it.
+ */
+declare function excludedCondition(config: Config, on: unknown): boolean;
+/** Borrowed conditions need a consumer modifier with the same name and category, unless the pin
+ *  excludes that modifier. */
 declare function unstatableConditions(config: Config): UnstatableCondition[];
 /** A token of ours whose conditional value names another system's modifier. */
 interface UnstatableOverride {
@@ -254,4 +261,4 @@ interface UnstatableOverride {
  */
 declare function unstatableOverrides(config: Config): UnstatableOverride[];
 //#endregion
-export { DanglingDirective, DanglingRef, LeafAddress, MisdeclaredOverlay, OverlayVerb, RedundantQualifier, UnadoptedDirective, UnreadableBorrow, UnstatableCondition, UnstatableOverride, classifyOverlay, danglingDirectives, danglingSourcedRefs, leafAddresses, leafVerb, misdeclaredOverlays, overlayVerb, redundantQualifiers, unadoptedDirectives, unreadableBorrows, unstatableConditions, unstatableOverrides, valueAt };
+export { DanglingDirective, DanglingRef, LeafAddress, MisdeclaredOverlay, OverlayVerb, RedundantQualifier, UnadoptedDirective, UnreadableBorrow, UnstatableCondition, UnstatableOverride, classifyOverlay, danglingDirectives, danglingSourcedRefs, excludedCondition, leafAddresses, leafVerb, misdeclaredOverlays, overlayVerb, redundantQualifiers, unadoptedDirectives, unreadableBorrows, unstatableConditions, unstatableOverrides, valueAt };

package/dist/framework/source-integrity.js

@@ -424,7 +424,24 @@ function danglingDirectives(config) {
 	}
 	return found;
 }
-/** Borrowed conditions need a consumer modifier with the same name and category. */
+/**
+* Whether an override's condition names a modifier this config doesn't hold because a pin excludes
+* it ({@link Config.sourceExcludes}). Such an override is left out, as the stylesheet leaves out a
+* condition it cannot state, and the build doesn't refuse it.
+*/
+function excludedCondition(config, on) {
+	return (Array.isArray(on) ? on : [on]).some((ref) => {
+		if (!isRef(ref)) return false;
+		const modifier = pathOf(ref);
+		if (config.resolve("modifier", modifier)) return false;
+		return config.sourceSlugs().some((slug) => {
+			const spelled = config.sourceFor(slug)?.resolve("modifier", modifier)?.path ?? modifier;
+			return config.sourceExcludes(slug, "modifier", spelled);
+		});
+	});
+}
+/** Borrowed conditions need a consumer modifier with the same name and category, unless the pin
+*  excludes that modifier. */
 function unstatableConditions(config) {
 	const found = [];
 	for (const slug of config.sourceSlugs()) {
@@ -443,6 +460,8 @@ function unstatableConditions(config) {
 					if (!isRef(ref)) continue;
 					const modifier = pathOf(ref);
 					if (!config.resolve("modifier", modifier)) {
+						const spelled = source.resolve("modifier", modifier)?.path ?? modifier;
+						if (config.sourceExcludes(slug, "modifier", spelled)) continue;
 						found.push({
 							slug,
 							token,
@@ -575,4 +594,4 @@ function borrowedSlug(body) {
 	return isRef(body) ? sourceOf(body) : void 0;
 }
 //#endregion
-export { borrowedSlug, classifyOverlay, danglingDirectives, danglingSourcedRefs, leafAddresses, leafVerb, misdeclaredOverlays, overlayVerb, redundantQualifiers, sourceSlugs, unadoptedDirectives, unreadableBorrows, unstatableConditions, unstatableOverrides, valueAt };
+export { borrowedSlug, classifyOverlay, danglingDirectives, danglingSourcedRefs, excludedCondition, leafAddresses, leafVerb, misdeclaredOverlays, overlayVerb, redundantQualifiers, sourceSlugs, unadoptedDirectives, unreadableBorrows, unstatableConditions, unstatableOverrides, valueAt };

package/dist/framework/utils/refs.d.ts

@@ -57,12 +57,24 @@ interface ExtendedRef<Delta extends Record<string, unknown> = Record<string, unk
  * `if (!source) return ''` escape and the declaration vanishes), reports a false dangling ref naming a
  * source that does not exist, and marks the item borrowed on every provenance surface. Nothing throws.
  *
+ * The rest of the grammar a path is read in is refused the same way, since each misreads as silently:
+ * - `#` anywhere: the ref grammar splits on the first `#` before anything else, so `token:size/a#b`
+ *   is a member ref (`b`) into `size/a`.
+ * - An empty segment (`''`, `a//b`, `/a`, `a/`): `/` is what makes a folder, and a pin's `link` covers
+ *   a folder's members as the paths under `<folder>/`.
+ * - A segment starting with `!`: a `link` list entry `'!text'` leaves `text` out, so a path of that
+ *   name couldn't be linked by name.
+ * - A segment that is `*`: in a `link` list, `'*'` is every path.
+ *
  * Checked where a path becomes an identity — a create, a rename's target, an authored entry — and
  * deliberately not on reads, so an existing bad path stays addressable and, more to the point,
  * deletable.
  */
+declare function entityPathProblem(path: string): string | undefined;
+/** Whether `path` can be an entity's own path: {@link entityPathProblem} finds nothing wrong with it. */
 declare function isEntityPath(path: string): boolean;
-/** What a refused path should say, in one place, so a create, a rename and a register word it alike. */
+/** What a path carrying a misplaced `@` should say, so a create, a rename and a register word it
+ *  alike. {@link entityPathProblem} says it for every rule. */
 declare const ENTITY_PATH_MESSAGE = "An entity path may not contain \"@\" except as a leading npm scope \u2014 \"@\" marks the source a ref is drawn from, so a path carrying one cannot be told apart from a borrowed address.";
 /**
  * A reference to another entity: `ref('token', 'color/brand')`. Resolution is prefix-or-leaf against
@@ -200,4 +212,4 @@ declare function rewriteRefNamespace(value: unknown, kind: string, from: string,
  */
 declare function rewriteRefSource(value: unknown, from: string, to: string | undefined): unknown;
 //#endregion
-export { ENTITY_PATH_MESSAGE, ExtendableRef, ExtendedRef, MINTED, Ref, collectRefs, declarationText, entityRefOf, isEntityPath, isExtendedRef, isMintedRow, isRef, kindOf, memberOf, memberRef, orRef, pathOf, ref, refKey, refLeaf, refOfKey, refSchema, refTo, replaceRefMarkers, rewriteRefNamespace, rewriteRefSource, rewriteRefs, routedSource, sourceHops, sourceOf, splitRef, splitRefMarkers };
+export { ENTITY_PATH_MESSAGE, ExtendableRef, ExtendedRef, MINTED, Ref, collectRefs, declarationText, entityPathProblem, entityRefOf, isEntityPath, isExtendedRef, isMintedRow, isRef, kindOf, memberOf, memberRef, orRef, pathOf, ref, refKey, refLeaf, refOfKey, refSchema, refTo, replaceRefMarkers, rewriteRefNamespace, rewriteRefSource, rewriteRefs, routedSource, sourceHops, sourceOf, splitRef, splitRefMarkers };

package/dist/framework/utils/refs.js

@@ -59,14 +59,33 @@ function memberOf(target) {
 * `if (!source) return ''` escape and the declaration vanishes), reports a false dangling ref naming a
 * source that does not exist, and marks the item borrowed on every provenance surface. Nothing throws.
 *
+* The rest of the grammar a path is read in is refused the same way, since each misreads as silently:
+* - `#` anywhere: the ref grammar splits on the first `#` before anything else, so `token:size/a#b`
+*   is a member ref (`b`) into `size/a`.
+* - An empty segment (`''`, `a//b`, `/a`, `a/`): `/` is what makes a folder, and a pin's `link` covers
+*   a folder's members as the paths under `<folder>/`.
+* - A segment starting with `!`: a `link` list entry `'!text'` leaves `text` out, so a path of that
+*   name couldn't be linked by name.
+* - A segment that is `*`: in a `link` list, `'*'` is every path.
+*
 * Checked where a path becomes an identity — a create, a rename's target, an authored entry — and
 * deliberately not on reads, so an existing bad path stays addressable and, more to the point,
 * deletable.
 */
+function entityPathProblem(path) {
+	if (path.lastIndexOf("@") > 0) return ENTITY_PATH_MESSAGE;
+	if (path.includes("#")) return "An entity path may not contain \"#\" — \"#\" marks the member a ref points into, so a path carrying one reads as a member of a shorter path.";
+	const segments = path.split("/");
+	if (segments.some((segment) => segment === "")) return "An entity path may not have an empty segment — \"/\" separates a folder from its members, so \"\", \"a//b\", \"/a\" and \"a/\" name no folder a link or a ref can address.";
+	if (segments.some((segment) => segment.startsWith("!"))) return "An entity path segment may not start with \"!\" — a link's \"!path\" entry leaves that path out, so a path named that way could not be linked by name.";
+	if (segments.some((segment) => segment === "*")) return "An entity path segment may not be \"*\" — in a link, \"*\" stands for every path.";
+}
+/** Whether `path` can be an entity's own path: {@link entityPathProblem} finds nothing wrong with it. */
 function isEntityPath(path) {
-	return path.lastIndexOf("@") <= 0;
+	return entityPathProblem(path) === void 0;
 }
-/** What a refused path should say, in one place, so a create, a rename and a register word it alike. */
+/** What a path carrying a misplaced `@` should say, so a create, a rename and a register word it
+*  alike. {@link entityPathProblem} says it for every rule. */
 const ENTITY_PATH_MESSAGE = "An entity path may not contain \"@\" except as a leading npm scope — \"@\" marks the source a ref is drawn from, so a path carrying one cannot be told apart from a borrowed address.";
 /**
 * A reference to another entity: `ref('token', 'color/brand')`. Resolution is prefix-or-leaf against
@@ -455,4 +474,4 @@ function canonicalCondition(when) {
 	return entries.length === 0 ? "*" : entries.map(([k, v]) => `${k}=${String(refLeaf(v))}`).join("&");
 }
 //#endregion
-export { ENTITY_PATH_MESSAGE, MINTED, canonicalCondition, collectRefs, declarationText, entityRefOf, hasRefMarker, isEntityPath, isExtendedRef, isMintedRow, isRef, kindOf, memberOf, memberRef, orRef, pathOf, qualifyRefs, ref, refKey, refLeaf, refOfKey, refSchema, refTo, replaceRefMarkers, rewriteRefNamespace, rewriteRefSource, rewriteRefs, routedSource, singletonRef, sourceHops, sourceOf, splitRef, splitRefMarkers };
+export { ENTITY_PATH_MESSAGE, MINTED, canonicalCondition, collectRefs, declarationText, entityPathProblem, entityRefOf, hasRefMarker, isEntityPath, isExtendedRef, isMintedRow, isRef, kindOf, memberOf, memberRef, orRef, pathOf, qualifyRefs, ref, refKey, refLeaf, refOfKey, refSchema, refTo, replaceRefMarkers, rewriteRefNamespace, rewriteRefSource, rewriteRefs, routedSource, singletonRef, sourceHops, sourceOf, splitRef, splitRefMarkers };