@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/marketplace-overrides.d.ts

@@ -0,0 +1,271 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type ResolvedProvenance } from './marketplace-provenance';
+/**
+ * The override layer (AGL-1019) — own the patch, never the copy.
+ *
+ * Customising a marketplace artifact and updating it are only compatible if
+ * they are two different documents. Today they are one: you change a theme's
+ * primary colour and that edits the theme, so the publisher's v2 can be taken
+ * only by discarding your colour, or refused only by missing their fix.
+ *
+ * Here the publisher's version stays untouched as the **base** — AGL-1015
+ * already stores it, content-addressed and immutable, in
+ * `marketplaceArtifactBases/{sha256}` — the user's changes are a **sparse
+ * patch** stored beside it, and readers resolve `base ⊕ patch`. Then:
+ *
+ * * updating replaces the base wholesale and the patch still applies;
+ * * "what did I change" IS the patch, with no diffing at read time;
+ * * "reset to the publisher's version" is deleting the patch;
+ * * a conflict is narrow: only where the patch touches a path the update also
+ *   changed, which the marketplace plugin's three-way update plan already names.
+ *
+ * Pure and content-shaped, exactly like the merge module it sits next to: it
+ * knows nothing about Firestore or artifact types, so one resolver serves a
+ * theme, a node tree and a plugin settings map, and every rule below is
+ * testable without a database.
+ *
+ * ## Which "base" a reader resolves against
+ *
+ * The installed document's OWN content fields — whatever the install route
+ * wrote — are the base at read time, and {@link resolveArtifactContent} takes
+ * them directly. `marketplaceArtifactBases` is not that: it is closed to
+ * clients in both directions (a base can hold paid content, and its key is on
+ * the installed document, so a readable collection would hand out any listing's
+ * content by hash). It is the immutable snapshot the server diffs and resets
+ * against, nothing more.
+ *
+ * The two agree because an update writes the publisher's new version onto the
+ * document and stamps a base at that same hash in one operation — which is the
+ * property that makes "never mutate the vendored artifact" enforceable rather
+ * than merely intended. The moment a user edit lands in those content fields
+ * instead of in the override, both the diff and this resolver are wrong.
+ *
+ * ## Two rules that are load-bearing
+ *
+ * **Deletion needs a sentinel, and it is not `null`.** A sparse patch says
+ * nothing about paths it omits, so "omit it to remove it" is unavailable —
+ * omission already means "inherit". `null` cannot serve either: it is a real
+ * value in this codebase's content, and the besigner's `null`-means-cleared
+ * convention is what took every `/product/*` page down in AGL-1226. So removal
+ * is spelled with {@link OVERRIDE_DELETE}, a value nothing else produces.
+ *
+ * **Arrays are never merged by index.** An insert at position 0 shifts every
+ * element after it, so index-wise merging reports — and then writes — a change
+ * to every one of them. Arrays therefore replace wholesale by default, which is
+ * also how {@link planArtifactUpdate} compares them. Where elements carry a
+ * stable identity the patch may instead use the keyed form
+ * ({@link keyedArrayPatch}) and edit one element by key, so a publisher who
+ * inserts an element does not collide with a user who edited a different one.
+ */
+/**
+ * The removal sentinel: a patch value of exactly this string removes the path
+ * from the resolved output.
+ *
+ * A string rather than a wrapper object because a patch travels through
+ * Firestore, JSON responses and React state unchanged, and a scalar survives
+ * all three without anyone needing to know it is special. The cost is that an
+ * artifact whose real content is this exact string cannot be expressed; that is
+ * a deliberate trade for a sentinel that cannot be produced by accident, and
+ * {@link diffOverride} is the only thing that emits it.
+ *
+ * Note this is a field *value*, never a field *name* — Firestore rejects field
+ * names matching `__.*__`, and this deliberately has no trailing underscores so
+ * that a careless refactor into a key still fails loudly rather than silently.
+ */
+export declare const OVERRIDE_DELETE = "__aglynOverrideDelete";
+/**
+ * The field on an installed artifact document that holds its override.
+ *
+ * Beside the base, never inside it. The document's content fields keep holding
+ * the publisher's version verbatim, which is what makes an update a wholesale
+ * replacement of those fields and nothing else. Writing the user's edits into
+ * the content instead is precisely the state this issue exists to leave.
+ */
+export declare const ARTIFACT_OVERRIDE_FIELD = "overrides";
+/** The stored override, as written under {@link ARTIFACT_OVERRIDE_FIELD}. */
+export interface ArtifactOverride {
+    /** The sparse patch. Resolved over the artifact's content at read time. */
+    patch: unknown;
+    /**
+     * The base the patch was authored against — `installedFrom.sha256`.
+     *
+     * Recorded, not enforced: a patch stays valid across an update by design, and
+     * the only thing this answers is "which publisher version was on screen when
+     * these edits were made", which is what a conflict report needs to be honest.
+     */
+    baseSha256: string | null;
+    updatedAt?: unknown;
+    updatedBy?: string | null;
+}
+/**
+ * A patch node that edits an array BY KEY instead of replacing it.
+ *
+ * Only ever produced for arrays whose elements are objects carrying a unique
+ * value under one identity field, because that is the only case where "the
+ * third element" and "the element the publisher shipped third" are different
+ * questions with the same answer.
+ */
+export interface KeyedArrayPatch {
+    /** Discriminator. Present only on this form. */
+    keyedBy: string;
+    /** Per-key sub-patches; a value of {@link OVERRIDE_DELETE} removes the element. */
+    entries: Record<string, unknown>;
+    /**
+     * The full key order, when the user reordered the array.
+     *
+     * Absent when they did not — and absence is the point: an array with no
+     * `order` lets a publisher insert an element and have it appear, while an
+     * array with one pins the order the user chose. Keys present in the base but
+     * missing from `order` keep their relative position at the end, so a stale
+     * `order` never drops an element.
+     */
+    order?: string[];
+}
+export declare const isDeleteSentinel: (value: unknown) => boolean;
+export declare function isKeyedArrayPatch(value: unknown): value is KeyedArrayPatch;
+/**
+ * The identity field this array is keyed by, or null when it is not keyed.
+ *
+ * Every element must be a plain object carrying the same field, and every value
+ * must be a non-empty string that appears once. A single duplicate or missing
+ * key makes the whole array unkeyed rather than partly keyed — a patch that can
+ * address only some elements is worse than one that addresses none, because the
+ * gaps are invisible at the call site.
+ */
+export declare function arrayKeyField(value: unknown): string | null;
+/**
+ * `base ⊕ patch` — the resolved view every reader sees.
+ *
+ * Deep-merges plain objects; everything else the patch names replaces what the
+ * base holds. The base is never mutated: each level is copied on write, so a
+ * caller can resolve the same base against two patches and get two answers.
+ *
+ * A patch that names a path the base does not have simply adds it. That is what
+ * makes the same function serve "override a publisher's field" and "set a field
+ * the publisher never shipped", and it is why a resolved artifact can be richer
+ * than its base rather than only a recolouring of it.
+ */
+export declare function resolveOverride<T = unknown>(base: unknown, patch: unknown): T;
+/**
+ * "What did I change" — the sparse patch that turns `base` into `edited`.
+ *
+ * The inverse of {@link resolveOverride}, and held to it:
+ * `resolveOverride(base, diffOverride(base, edited))` equals `edited` for every
+ * shape this codebase stores. That round trip is the module's central property
+ * and the thing its tests exist to defend, because every consumer downstream —
+ * themes, theme overrides, host variables, plugin settings — inherits it.
+ *
+ * Returns `undefined` when nothing changed, so an unedited artifact stores no
+ * override at all rather than an empty husk that reads as "customised".
+ */
+export declare function diffOverride(base: unknown, edited: unknown): unknown;
+/**
+ * Every path the patch touches, dotted, for "what did I change" in a UI and for
+ * pairing an override against an update plan's conflicts — whose paths
+ * {@link planArtifactUpdate} spells the same way.
+ *
+ * A keyed array contributes `field[key]` segments rather than indices, because
+ * an index is exactly the thing that stops meaning the same element the moment
+ * the publisher inserts one.
+ */
+export declare function overridePaths(patch: unknown, prefix?: string): string[];
+/**
+ * True when the patch says nothing — the artifact is the publisher's, as shipped.
+ *
+ * `undefined` is the only absence. A `null` is a VALUE the user chose, and
+ * calling it empty here would silently discard "set this field to null" on
+ * every save — the same conflation between "cleared" and "absent" that took
+ * every `/product/*` page down in AGL-1226.
+ */
+export declare function isEmptyOverride(patch: unknown): boolean;
+export interface OverrideEligibility {
+    ok: boolean;
+    /** Why not, in the words the surface refusing it should use. */
+    reason?: string;
+}
+/**
+ * Can this artifact hold an override at all? (AGL-1015's provenance, answered.)
+ *
+ * An override is a patch over the publisher's version, so an artifact with no
+ * recorded base has nothing to be a patch *of*. Storing one anyway would
+ * produce a patch against whatever the document happened to hold — including
+ * the user's own earlier edits — and the first update would resolve it against
+ * a base it was never written for. Saying so plainly is the whole point of the
+ * `updatable` flag; this is the sentence to put next to the disabled control.
+ */
+export declare function canOverrideArtifact(provenance: ResolvedProvenance | null | undefined): OverrideEligibility;
+/**
+ * The value to write under {@link ARTIFACT_OVERRIDE_FIELD} — or `null`, meaning
+ * "reset to the publisher's version", when the patch says nothing.
+ *
+ * ## Write this WHOLESALE. Never with `merge: true`.
+ *
+ * Firestore's `merge: true` deep-merges maps, and a patch is a map, so merging
+ * a new patch onto an old one takes their union: every path the user has ever
+ * overridden stays overridden, and removing an override becomes impossible
+ * through the one write that looks like it should do it. `merge: true` on the
+ * *document* is fine and expected — it is this *field* that must be replaced,
+ * which is what passing this value under a `FieldPath` to `update`, or under
+ * `set(..., {mergeFields})`, does:
+ *
+ * ```ts
+ * await ref.set(
+ *   { [ARTIFACT_OVERRIDE_FIELD]: overrideWriteValue(patch, sha256), updatedAt },
+ *   { mergeFields: [ARTIFACT_OVERRIDE_FIELD, 'updatedAt'] },
+ * )
+ * ```
+ *
+ * The `null` for an empty patch is deliberate over a field delete: a reader
+ * that sees `null` knows the override was considered and is empty, which reads
+ * the same as absent and needs no second code path.
+ */
+export declare function overrideWriteValue(patch: unknown, baseSha256: string | null, meta?: {
+    updatedAt?: unknown;
+    updatedBy?: string | null;
+}): ArtifactOverride | null;
+/**
+ * Reads a stored override off a document, tolerating the junk a client-writable
+ * field can hold.
+ *
+ * Returns `undefined` for anything that is not a well-formed override, so a
+ * corrupt field resolves to the publisher's version rather than throwing on a
+ * page that would otherwise render.
+ */
+export declare function readArtifactOverride(doc: Record<string, unknown> | null | undefined): ArtifactOverride | undefined;
+/**
+ * The one call a reader makes: the publisher's content with this document's
+ * override resolved over it.
+ *
+ * `content` is the artifact's own fields — whatever shape the install route
+ * wrote, unchanged — so a caller never has to know whether an override exists.
+ */
+export declare function resolveArtifactContent<T = unknown>(content: unknown, doc: Record<string, unknown> | null | undefined): T;
+/**
+ * The paths where an incoming update collides with what the user overrode.
+ *
+ * Narrow by construction, which is the payoff the whole layer was built for: a
+ * patch touching four paths can conflict in at most four places no matter how
+ * much of the artifact the publisher rewrote, so the question put to the user is
+ * "the publisher also changed your heading colour — whose wins?" rather than
+ * "this update rewrites 300 nodes, continue?".
+ *
+ * A path whose incoming value already equals what the override sets is not a
+ * conflict — the publisher adopted the user's change, and there is nothing to
+ * ask about.
+ */
+export declare function overrideConflicts(base: unknown, patch: unknown, incoming: unknown): string[];