@yahoo/uds-create-config 2.45.0 → 3.0.0

package/dist/framework/sources.d.ts

@@ -0,0 +1,211 @@
+import { Entity } from "./Entity.js";
+import { Config, SerializedConfig } from "./Config.js";
+import { z } from "zod";
+
+//#region src/framework/sources.d.ts
+/**
+ * The two schemas a source kind declares its resolutions against — see {@link EntityKind.sourceResolution}.
+ *
+ * `resolved` describes where an attached source came from, carrying the identity that origin actually
+ * has. `unavailable` describes why a declared one could not be met — a code plus the data that case
+ * needs, never prose, because the fix is surface-specific: a build tells you to run `uds install`, a
+ * browser paints an update button, and baking one string per code would put CLI instructions into
+ * Studio.
+ *
+ * Both are normally `z.discriminatedUnion`s, so a surface switches exhaustively and adding a case is a
+ * compile error at every consumer. Nothing here requires that, because it is the kind's call.
+ */
+interface SourceResolutionSchemas<Resolved extends z.ZodTypeAny = z.ZodTypeAny, Unavailable extends z.ZodTypeAny = z.ZodTypeAny> {
+  readonly resolved: Resolved;
+  readonly unavailable: Unavailable;
+}
+/** What a declared source lays over one of its entities, and whether it still offers it. */
+interface SourceOverlay {
+  /** Fields changing a value the source defines. */
+  readonly override?: Record<string, unknown>;
+  /** Fields covering a case the source does not. */
+  readonly extend?: Record<string, unknown>;
+  /** Kept and resolving, but not offered by authoring surfaces. */
+  readonly hidden: boolean;
+}
+/**
+ * What a source kind is asked when the framework wants to know whether one of its declarations still
+ * covers a borrowed entity — the argument to {@link EntityKind.bulkAdopts}, and to the two directive
+ * reads beside it.
+ *
+ * Both names for the borrowed kind are handed over because the two vocabularies are both real and
+ * neither side can map between them alone: ops and refs are keyed by kind (`token:color/brand`) while
+ * anything written in a config file — which a stored declaration is — is keyed by accessor (`tokens`).
+ * Only the config type's manifest knows the pair, so the framework resolves it and the kind reads
+ * whichever it recorded under. `accessor` is `undefined` for a config with no manifest.
+ */
+interface BulkQuery {
+  /** The declared source's stored body — the declaration is one of its fields. */
+  readonly body: Record<string, unknown>;
+  /** The borrowed entity's kind, and the accessor that kind is registered under. */
+  readonly kind: string;
+  readonly accessor: string | undefined;
+  /** The borrowed entity's path as the source spells it — what a declaration names. */
+  readonly path: string;
+}
+/**
+ * What a source kind is asked to lay a `SourceOverlay` over one path — the write counterpart to
+ * {@link EntityKind.bulkOverlay}, for the same reason that one exists: the field the directive is
+ * stored under is the kind's own, and the framework does not know it.
+ *
+ * Narrower than {@link BulkQuery} — a write does not need the OLD stored body, since a field-path
+ * `update` already merges rather than replaces.
+ */
+interface BulkOverlayWrite {
+  readonly accessor: string | undefined;
+  readonly path: string;
+  /** Sparse, unlike a read `SourceOverlay` — `hidden` is worth writing only when true, so a leaf that
+   *  changed nothing about visibility does not gain a field just for having been touched. */
+  readonly overlay: (Pick<SourceOverlay, 'override' | 'extend'> & {
+    readonly hidden?: boolean;
+  }) | null;
+}
+/**
+ * What this config lays over one borrowed item, and the body it lays it on — `Config.localOverlay`.
+ *
+ * `fields` is the stored delta at top level, the merge being one level deep: a record field here holds
+ * the whole record as this config now spells it, members it changed beside members it only carried
+ * along. `override` and `extend` are that delta judged leaf by leaf against `source`, in the pin's
+ * vocabulary, with the carried-along leaves left out; `overlayVerb` reads one leaf of them.
+ */
+interface LocalOverlay {
+  /** The link the item is borrowed through. */
+  readonly slug: string;
+  /** The fields this config wrote over the source's, as stored. */
+  readonly fields: Readonly<Record<string, unknown>>;
+  /** The source's body as it reads from here; `undefined` while the source is unavailable. */
+  readonly source: Readonly<Record<string, unknown>> | undefined;
+  /** The leaves of `fields` the source defines differently. Absent when there are none. */
+  readonly override?: Readonly<Record<string, unknown>>;
+  /** The leaves of `fields` the source has nothing at. Absent when there are none. */
+  readonly extend?: Readonly<Record<string, unknown>>;
+}
+/**
+ * The one refusal the framework owns, rather than a source kind.
+ *
+ * Every other `unavailable` reason is a verdict about the source — never published, out of date,
+ * found and unreadable — and only the kind can enumerate those. This one is a fact about the attempt:
+ * something looked, and the look did not finish. A load path that raced the resolve against a
+ * deadline, a request that threw, a walk abandoned mid-flight; the declaration may be perfectly fine.
+ *
+ * It exists because the alternative is worse. Reporting nothing for a resolve that failed collapses
+ * it into {@link Config.sourceStatus}'s `undefined` — "nobody looked" — which is the third state that
+ * distinction exists to preserve, and a surface reading it says "the values arrive when the project
+ * builds" about a source it just failed to reach.
+ *
+ * A kind unions this into its own `unavailable` schema so its inferred type carries the case and
+ * every exhaustive consumer has to answer for it — `LinkedSystem.sourceUnavailable` does.
+ */
+declare const sourceUnreachable: z.ZodObject<{
+  code: z.ZodLiteral<"unreachable">;
+}, z.core.$strip>;
+/** {@link sourceUnreachable} as a value, so a caller reporting a failed attempt states no kind's own
+ *  vocabulary to do it. */
+declare const UNREACHABLE: {
+  readonly code: "unreachable";
+};
+/**
+ * What a resolver answers with — the framework's tag over the kind's own two payloads.
+ *
+ * Tagged rather than structurally discriminated: `status` is what makes this a discriminated union,
+ * and it is the same tag {@link Config.sourceStatus} reports — so the state a resolver returns is the
+ * state the config exposes, and nothing can disagree about which state a source is in.
+ *
+ * Parameterized on the inferred payloads rather than on the schemas, so a kind can hand its consumers
+ * one concrete alias (`LinkedSystemState`) without them touching zod. Both default to `unknown`, which
+ * is what generic framework code genuinely knows: {@link Config.sources} spans every source kind a
+ * Config declares, and only the kind can say what its payloads are.
+ */
+type SourceResolution<Resolved = unknown, Unavailable = unknown> = {
+  readonly status: 'attached';
+  readonly resolved: Resolved;
+} | {
+  readonly status: 'unavailable';
+  readonly reason: Unavailable;
+};
+/**
+ * One source's state, as a config reports it — the resolution plus which source it answers for.
+ *
+ * Both halves of the address, so {@link Config.sources} is self-describing: `source` is the declared
+ * source's accessor name (`linkedSystems`), `slug` is the item's path within it (`ds`). A surface
+ * listing states can group them by collection without holding the declaration alongside, and can pick
+ * the kind whose payload types it knows how to read.
+ *
+ * Lookup is by slug alone ({@link Config.sourceStatus}), and that is not an inconsistency — a ref
+ * spells `@ds` with no room for a collection, so the slug namespace is flat and every other reader
+ * (`sourceFor`, `liveSourceFor`, the `sources` key `toJSON` writes) is keyed the same way. Flat is
+ * enforced, not assumed: `Config.assertDistinctSourceSlugs` refuses two source kinds claiming one
+ * slug, because nothing else could tell which of them `@ds` meant.
+ */
+type SourceState<Resolved = unknown, Unavailable = unknown> = SourceResolution<Resolved, Unavailable> & {
+  /** The declared source this answers for — the accessor name, as `Config.sourceAccessors` reports it. */readonly source: string;
+  readonly slug: string;
+};
+/**
+ * One declared source kind's resolver. It is handed the entity stored at that kind — so `entity.path`
+ * is the slug and every other field is the kind's own, typed.
+ *
+ * Taking the entity is what keeps this total over kinds nobody has written yet: there is no fixed
+ * declaration shape in the signature, so a config declaring `linkedPackages` needs nothing added to
+ * the framework — its resolver is handed a `LinkedPackage` and reads `packageName`/`range`, because
+ * that is what that kind declares. The answer is the kind's too, which is why the payloads are
+ * parameters here: a kind
+ * exports `SourceResolver<Source, ResolvedSource, SourceUnavailable>` under one name and its
+ * implementers get both halves typed.
+ *
+ * `source` rides alongside the validated resolution rather than inside it: a `Config` is not a zod
+ * value, and a `SerializedConfig` validates itself on hydrate through its own type's schema. Two
+ * validators over one payload is how they drift.
+ *
+ * Answering is mandatory; answering `unavailable` is legal. No answer at all is the failure — it reads
+ * identically to "this config borrows nothing", which is the confusion this whole model removes.
+ */
+type SourceResolver<E extends Entity = Entity, Resolved = unknown, Unavailable = unknown> = (entity: E) => Promise<SourceAnswer<Resolved, Unavailable>>;
+/**
+ * One answer about one source — the resolution, plus the source itself when there is one.
+ *
+ * Named because it crosses seams a resolver signature cannot describe: a server action hands one back
+ * for a slug a panel asked about, and {@link Config.attachResolved} takes one. Spelling it inline at
+ * each of those would be three statements of the same shape, and the app-side copy is the one that
+ * would go stale when a kind adds a payload.
+ */
+type SourceAnswer<Resolved = unknown, Unavailable = unknown> = SourceResolution<Resolved, Unavailable> & {
+  /** Rides alongside the validated resolution — a `Config` is not a zod value, and a
+   *  `SerializedConfig` validates itself on hydrate through its own type's schema. */
+  readonly source?: SerializedConfig | Config;
+};
+/**
+ * An answer that has to cross a wire — the source as an artifact, never as a live class.
+ *
+ * The distinction is not pedantry: a `Config` is a class with methods, so a server action returning
+ * one either fails to serialize or arrives as a shape-alike with nothing on it. Narrowing the carrier
+ * in the type is what makes that a compile error at the boundary rather than a runtime surprise in a
+ * browser.
+ *
+ * Assignable to {@link SourceAnswer} in the direction that matters, so
+ * {@link Config.attachResolved} takes one unchanged.
+ */
+type SerializedSourceAnswer<Resolved = unknown, Unavailable = unknown> = SourceResolution<Resolved, Unavailable> & {
+  readonly source?: SerializedConfig;
+};
+/**
+ * The schema a kind's resolutions validate against — its two payloads under the framework's tag.
+ *
+ * Built here rather than by each kind so the tag is stated once: a kind that composed its own union
+ * could spell `status` differently, or omit a branch, and the value would still typecheck as far as
+ * Zod is concerned while {@link Config.sourceStatus} could no longer read it.
+ *
+ * Cache the result per kind rather than calling this per item — it allocates a union, and a resolve
+ * walk validates every slug of a kind against the same one.
+ */
+declare function resolutionSchema({
+  resolved,
+  unavailable
+}: SourceResolutionSchemas): z.ZodTypeAny;
+//#endregion
+export { BulkOverlayWrite, BulkQuery, LocalOverlay, SerializedSourceAnswer, SourceAnswer, SourceOverlay, SourceResolution, SourceResolutionSchemas, SourceResolver, SourceState, UNREACHABLE, resolutionSchema, sourceUnreachable };

package/dist/framework/sources.js

@@ -0,0 +1,89 @@
+import { z } from "zod";
+//#region src/framework/sources.ts
+/**
+* What a declared source resolved to — the vocabulary a resolver answers in and a config reports in,
+* which is one vocabulary because there is no mapping layer between them.
+*
+* A source declaration is a request, and it may be moving: a repo-local one tracks whatever the sibling
+* currently is, and a published one names a version someone may not have installed. These types are the
+* answer, recorded per slug so a receipt can be judged stale and a build can say what it built against.
+*
+* **The framework owns the tag and nothing else.** `attached` against `unavailable` is structural, the
+* same distinction {@link Config.sourceStatus} reports, and every source kind has it. What each branch
+* carries is not: a linked system resolves from disk, a registry entry or Create, and fails as
+* `unbuilt`/`stale`/`not-installed`/`not-found`, where a `linkedPackages` kind would resolve from a
+* lockfile and fail as a range matching nothing. Naming either vocabulary here would be the framework
+* naming a kind (`.claude/rules/config-framework-kind-agnostic.md`), in a shape no second source kind
+* could fill.
+*
+* So the kind declares the pair, `defineEntity({ sourceResolution: { resolved, unavailable } })`, and
+* {@link resolutionSchema} composes it with the tag. Validated with zod because this is the seam where
+* arbitrary environment code hands a value to the framework: a resolver returning a half-filled object
+* fails here and names the source, rather than hydrating into a config that reads as "borrows nothing".
+*/
+/**
+* The one refusal the framework owns, rather than a source kind.
+*
+* Every other `unavailable` reason is a verdict about the source — never published, out of date,
+* found and unreadable — and only the kind can enumerate those. This one is a fact about the attempt:
+* something looked, and the look did not finish. A load path that raced the resolve against a
+* deadline, a request that threw, a walk abandoned mid-flight; the declaration may be perfectly fine.
+*
+* It exists because the alternative is worse. Reporting nothing for a resolve that failed collapses
+* it into {@link Config.sourceStatus}'s `undefined` — "nobody looked" — which is the third state that
+* distinction exists to preserve, and a surface reading it says "the values arrive when the project
+* builds" about a source it just failed to reach.
+*
+* A kind unions this into its own `unavailable` schema so its inferred type carries the case and
+* every exhaustive consumer has to answer for it — `LinkedSystem.sourceUnavailable` does.
+*/
+const sourceUnreachable = z.object({ code: z.literal("unreachable") });
+/** {@link sourceUnreachable} as a value, so a caller reporting a failed attempt states no kind's own
+*  vocabulary to do it. */
+const UNREACHABLE = { code: "unreachable" };
+/**
+* The schema a kind's resolutions validate against — its two payloads under the framework's tag.
+*
+* Built here rather than by each kind so the tag is stated once: a kind that composed its own union
+* could spell `status` differently, or omit a branch, and the value would still typecheck as far as
+* Zod is concerned while {@link Config.sourceStatus} could no longer read it.
+*
+* Cache the result per kind rather than calling this per item — it allocates a union, and a resolve
+* walk validates every slug of a kind against the same one.
+*/
+function resolutionSchema({ resolved, unavailable }) {
+	return z.discriminatedUnion("status", [z.object({
+		status: z.literal("attached"),
+		resolved
+	}), z.object({
+		status: z.literal("unavailable"),
+		reason: unavailable
+	})]);
+}
+/**
+* Parse what a resolver returned, refusing a malformed answer at the seam and naming the source.
+*
+* Takes the schema rather than looking one up, because the caller resolving a kind already holds it
+* (`Config.load` reads it off `entityOf(kind)` once and reuses it for every slug) and because this
+* function must not know which kinds exist.
+*
+* The resolver's `source` — the config itself — is stripped before validation and handed back as
+* `config` beside the parsed resolution, for the reason {@link SourceResolver} states: it is not a zod
+* value. Renamed on the way out because `source` in a {@link SourceState} is the declared source's
+* name, and one word cannot be both.
+*/
+function parseResolution({ source, slug, schema, answer }) {
+	const named = `${source}/${slug}`;
+	if (answer === null || typeof answer !== "object") throw new Error(`The resolver for source "${named}" answered ${answer === null ? "null" : typeof answer} rather than a resolution. Answering is mandatory — \`unavailable\` is a legal answer, no answer is not.`);
+	const { source: config, ...resolution } = answer;
+	const parsed = schema.safeParse(resolution);
+	if (!parsed.success) throw new Error(`The resolver for source "${named}" answered a value this is not: ${parsed.error.issues.map((issue) => `${issue.path.join(".") || "(root)"} — ${issue.message}`).join("; ")}`);
+	return {
+		source,
+		slug,
+		...parsed.data,
+		...config === void 0 ? {} : { config }
+	};
+}
+//#endregion
+export { UNREACHABLE, parseResolution, resolutionSchema, sourceUnreachable };

package/dist/framework/utils/compiled-schema.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+/**
+ * A schema that generates its parser ahead of time on first use, in place.
+ *
+ * The returned value IS the schema passed in — same class, `shape`, `parse`/`safeParse` and JSON
+ * Schema — with its parse entry swapped for one that compiles on the first parse and routes every
+ * later parse through the generated fast path. A schema nested inside another (a create body inside
+ * its `{ path, data }` op input) is compiled the same way, so the fast path applies wherever the
+ * schema is reached.
+ *
+ * Compiling is deferred rather than run here because `z.compile` walks the schema to check for a
+ * reference cycle, and that walk resolves a `z.lazy(...)`. A self-referential kind declares
+ * `z.lazy(() => Token)` in `Token`'s own body, so compiling during `defineEntity` would resolve the
+ * reference while `Token`'s binding is still in its dead zone — the getter throws and zod caches the
+ * lazy's inner type as undefined for the life of the process, and every later token parse then fails.
+ * By the first parse the module has finished initializing, so the reference resolves and zod either
+ * generates a fast path or, for a schema whose subtree is a cycle, hands it back on the runtime. The
+ * compile also runs once per schema this way, not on every ad hoc schema, and off the module-load path.
+ *
+ * Where a runtime cannot generate code — `new Function` refused by a CSP — `z.compile` returns the
+ * schema uncompiled and it parses on the runtime as before.
+ */
+export declare function compileSchema<T extends z.ZodTypeAny>(schema: T): T;

package/dist/framework/utils/compiled-schema.js

@@ -0,0 +1,46 @@
+import { z } from "zod";
+//#region src/framework/utils/compiled-schema.ts
+const internalsOf = (schema) => schema._zod;
+/**
+* A schema that generates its parser ahead of time on first use, in place.
+*
+* The returned value IS the schema passed in — same class, `shape`, `parse`/`safeParse` and JSON
+* Schema — with its parse entry swapped for one that compiles on the first parse and routes every
+* later parse through the generated fast path. A schema nested inside another (a create body inside
+* its `{ path, data }` op input) is compiled the same way, so the fast path applies wherever the
+* schema is reached.
+*
+* Compiling is deferred rather than run here because `z.compile` walks the schema to check for a
+* reference cycle, and that walk resolves a `z.lazy(...)`. A self-referential kind declares
+* `z.lazy(() => Token)` in `Token`'s own body, so compiling during `defineEntity` would resolve the
+* reference while `Token`'s binding is still in its dead zone — the getter throws and zod caches the
+* lazy's inner type as undefined for the life of the process, and every later token parse then fails.
+* By the first parse the module has finished initializing, so the reference resolves and zod either
+* generates a fast path or, for a schema whose subtree is a cycle, hands it back on the runtime. The
+* compile also runs once per schema this way, not on every ad hoc schema, and off the module-load path.
+*
+* Where a runtime cannot generate code — `new Function` refused by a CSP — `z.compile` returns the
+* schema uncompiled and it parses on the runtime as before.
+*/
+function compileSchema(schema) {
+	const internals = internalsOf(schema);
+	const runtimeRun = internals.run;
+	let compiled = false;
+	const compileOnFirstRun = (payload, ctx) => {
+		if (!compiled) {
+			compiled = true;
+			internals.run = runtimeRun;
+			const fastPath = internalsOf(z.compile(schema));
+			internals.run = fastPath.run;
+			if (fastPath.bag.validator !== void 0) {
+				internals.bag.validator = fastPath.bag.validator;
+				internals.bag.fallbackRun = fastPath.bag.fallbackRun;
+			}
+		}
+		return internals.run(payload, ctx);
+	};
+	internals.run = compileOnFirstRun;
+	return schema;
+}
+//#endregion
+export { compileSchema };

package/dist/framework/utils/content-key.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A stable content key over JSON-shaped values — what names a derived artifact after the state it
+ * was derived from, so "did this change" is a string comparison and a cache is addressed by it.
+ *
+ * FNV-1a over a key-sorted serialization: portable (a config runs in the browser, so no
+ * `node:crypto`), synchronous (`crypto.subtle` is not), and collision-resistant enough for a cache
+ * key whose worst miss is one redundant rebuild. Not a security hash; nothing may treat it as one.
+ */
+/** JSON serialization with every object's keys sorted, so two spellings of one value are one
+ *  string. Arrays keep their order — order is meaning there. */
+export declare function stableStringify(value: unknown): string;
+/** A 64-bit FNV-1a digest of `text`, as 16 hex chars. */
+export declare function fnv1a64(text: string): string;
+/** The content key of a JSON-shaped value. */
+export declare function contentKey(value: unknown): string;

package/dist/framework/utils/content-key.js

@@ -0,0 +1,33 @@
+//#region src/framework/utils/content-key.ts
+/**
+* A stable content key over JSON-shaped values — what names a derived artifact after the state it
+* was derived from, so "did this change" is a string comparison and a cache is addressed by it.
+*
+* FNV-1a over a key-sorted serialization: portable (a config runs in the browser, so no
+* `node:crypto`), synchronous (`crypto.subtle` is not), and collision-resistant enough for a cache
+* key whose worst miss is one redundant rebuild. Not a security hash; nothing may treat it as one.
+*/
+/** JSON serialization with every object's keys sorted, so two spellings of one value are one
+*  string. Arrays keep their order — order is meaning there. */
+function stableStringify(value) {
+	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+	if (typeof value === "object" && value !== null) return `{${Object.entries(value).filter(([, entry]) => entry !== void 0).sort(([a], [b]) => a < b ? -1 : 1).map(([key, entry]) => `${JSON.stringify(key)}:${stableStringify(entry)}`).join(",")}}`;
+	return JSON.stringify(value) ?? "null";
+}
+/** A 64-bit FNV-1a digest of `text`, as 16 hex chars. */
+function fnv1a64(text) {
+	let hash = 14695981039346656037n;
+	const prime = 1099511628211n;
+	const mask = 18446744073709551615n;
+	for (let i = 0; i < text.length; i++) {
+		hash ^= BigInt(text.charCodeAt(i));
+		hash = hash * prime & mask;
+	}
+	return hash.toString(16).padStart(16, "0");
+}
+/** The content key of a JSON-shaped value. */
+function contentKey(value) {
+	return fnv1a64(stableStringify(value));
+}
+//#endregion
+export { contentKey, stableStringify };

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

@@ -0,0 +1,13 @@
+/**
+ * The values a domain ENUMERATES, in declaration order — or `undefined` when it doesn't enumerate.
+ *
+ * Two forms mean the same thing. A KEYED COLLECTION is how an enumerated domain is STORED: each
+ * value is a member with a name, an order and a body of its own (a component's variant values,
+ * which carry a label and can be renamed by the ordinary cascade). A LIST is the same statement
+ * from a source with no bodies to carry — an author's shorthand, a style property's keywords.
+ *
+ * Its own module because both readers of a domain need the same answer and neither can import the
+ * other: `value-domain` turns it into a schema, and `projections` turns it into the leaves a picker
+ * offers, while `value-domain` already reads `projections` for the ref case.
+ */
+export declare function listedIn(domain: unknown): string[] | undefined;

package/dist/framework/utils/enumerated.js

@@ -0,0 +1,19 @@
+//#region src/framework/utils/enumerated.ts
+/**
+* The values a domain ENUMERATES, in declaration order — or `undefined` when it doesn't enumerate.
+*
+* Two forms mean the same thing. A KEYED COLLECTION is how an enumerated domain is STORED: each
+* value is a member with a name, an order and a body of its own (a component's variant values,
+* which carry a label and can be renamed by the ordinary cascade). A LIST is the same statement
+* from a source with no bodies to carry — an author's shorthand, a style property's keywords.
+*
+* Its own module because both readers of a domain need the same answer and neither can import the
+* other: `value-domain` turns it into a schema, and `projections` turns it into the leaves a picker
+* offers, while `value-domain` already reads `projections` for the ref case.
+*/
+function listedIn(domain) {
+	if (Array.isArray(domain)) return domain.filter((value) => typeof value === "string");
+	return typeof domain === "object" && domain !== null ? Object.keys(domain) : void 0;
+}
+//#endregion
+export { listedIn };

package/dist/framework/utils/field-path.d.ts

@@ -0,0 +1,95 @@
+//#region src/framework/utils/field-path.d.ts
+/**
+ * A write's ADDRESS, carried in the delta's KEY.
+ *
+ * `update` / `sub-update` take a partial whose keys are FIELD PATHS. One rule covers every depth:
+ * **the value replaces whatever the key addresses**, and `null` removes it.
+ *
+ *   { layers: {…} }                 →  replaces the whole `layers` field
+ *   { 'layers.root.bg': 'hover' }   →  replaces one leaf, touching nothing else
+ *   { 'layers.root.bg': null }      →  removes that leaf
+ *   { 'layers.root': null }         →  removes the whole bag
+ *
+ * So depth is something the CALLER states rather than something the verb implies — Firestore's
+ * `update()` rule, and the reason there is no second "deep" verb. A deep write and a whole-field
+ * write differ only in how many segments the key has.
+ *
+ * The nested-object delta this replaces could not tell those two apart. Merged recursively,
+ * `{ value: { warning: {} } }` is both "add a value called `warning`" and "empty the one that is
+ * already there", and the merge had to GUESS — it pruned, so adding a variant value applied cleanly
+ * and stored nothing: a silent no-op with no rejection to explain it. Under an address there is
+ * nothing to guess, because setting and removing are different calls rather than different-looking
+ * data.
+ *
+ * The one thing an address cannot spell is a member key that itself contains a dot (`spacing.2`,
+ * which nothing names today — paths separate with `/`). Such a key is reachable by `sub-upsert`,
+ * which addresses it whole.
+ */
+/** A JSON object — not an array, not a class instance. */
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * The segments a delta key addresses.
+ *
+ * A key is a PATH when it contains a `.` AND its first segment names a field of the thing being
+ * written — decidable off the target's own schema, so it is a rule rather than a guess. A key that
+ * fails either test addresses one field, dot and all, which is what keeps a literal dotted key
+ * writable at the depth it lives at.
+ */
+declare function pathSegments(key: string, isField: (name: string) => boolean): string[];
+/**
+ * `body` with `value` at `segments` — assigned, or REMOVED when `value` is `null`. Neither input is
+ * mutated.
+ *
+ * Two rules about containers along the way, and both follow from "the value replaces what the key
+ * addresses":
+ *
+ *  - An intermediate that is missing, or is a scalar, becomes a container. The caller addressed
+ *    something inside it, which is a caller saying one belongs there.
+ *  - A removal that EMPTIES a container takes the container with it, except at the first segment —
+ *    those are the target's own declared fields, and a rule whose `layers` bag has been cleared is
+ *    still a rule with an empty bag, not a rule missing a required field. Removing the field itself
+ *    is what `null` AT that segment says. A SET never prunes: an empty object a caller wrote is a
+ *    value.
+ */
+declare function setAtPath(body: Record<string, unknown>, segments: readonly string[], value: unknown, depth?: number): Record<string, unknown>;
+/**
+ * A path-keyed delta applied to a body, entry by entry in the order the caller wrote them.
+ *
+ * Order matters and is the caller's: two entries may address the same subtree, and the second is
+ * meant to win. That is also what makes one batch safe where a read-merge-write pair was not.
+ */
+declare function applyPathDelta(current: Record<string, unknown>, delta: Record<string, unknown>, isField: (name: string) => boolean): Record<string, unknown>;
+/**
+ * The inverse of {@link applyPathDelta}: the path-keyed delta that turns `existing` into `desired`,
+ * over `fields` — one entry per changed member (`null` removes), nothing restated. This is what
+ * makes a reconciling writer produce patches that SAY what the gesture did: a prop edit reads back
+ * as `props.bg`, not as a whole-body replace.
+ *
+ * Descent stops exactly where addressing stops, so applying the delta always reproduces `desired`:
+ * both sides must be plain records (an array, a ref, a scalar replaces at its own address), every
+ * member key must be dot-free (a dotted key can't be addressed — the record writes whole), and a
+ * NESTED record emptied of members writes whole, since {@link setAtPath} prunes a container a
+ * removal empties. A declared field is never pruned there, so at the field level the same
+ * emptying stays addressed.
+ *
+ * `same` is the caller's structural equality — bodies hold refs, and whether two spellings of one
+ * are equal is the caller's to say.
+ */
+declare function pathDelta({
+  existing,
+  desired,
+  fields,
+  same
+}: {
+  existing: Record<string, unknown>;
+  desired: Record<string, unknown>;
+  fields: readonly string[];
+  same: (a: unknown, b: unknown) => boolean;
+}): Record<string, unknown>;
+/** A field predicate over a known list of names — an entity's `fieldKeys`, straight off the kind. */
+declare function namedFields(names: readonly string[]): (name: string) => boolean;
+/** The FIELDS a delta touched — every key's first segment. What a write reports as changed, so work
+ *  scoped to written fields (member coercion) covers the same set the delta reached. */
+declare function touchedFields(delta: Record<string, unknown>, isField: (name: string) => boolean): Set<string>;
+//#endregion
+export { applyPathDelta, isPlainObject, namedFields, pathDelta, pathSegments, setAtPath, touchedFields };