@docupace/ihub-config 1.1.25 → 1.1.26-sync.0

package/dist/config-service.js

@@ -7,12 +7,299 @@ import { fileExists } from './lib/file-system.js';
 import replaceDotsOutsideExpressions from './lib/replace-dots-outside-expressions.js';
 import { createHash } from 'node:crypto';
 import { injectConfigValue, } from './injector-resolvers/config-injector.js';
-import { builtInProviders } from './providers/index.js';
+import { builtInProviders, builtInWholePatchMergers, } from './providers/index.js';
 import { deepMergeResolvers, } from './resolvers/index.js';
 import { dump, load } from 'js-yaml';
 import { buildQuery } from '@docupace/ihub-core/query';
+import { isNamedObjectArray, mergeNamedObjectArray, } from './lib/named-array-merge.js';
+import jp from 'jsonpath';
 const FULL_OBJECT_EXPRESSION_PATTERN = /^\${(.*?)}$/;
 const INLINE_OBJECT_EXPRESSION_PATTERN = /\${(.*?)}/g;
+// An override element counts as "self-contained" when it carries enough of
+// its own definition to render on its own — a real attribute path (or paths)
+// or a computed expression — as opposed to a thin `{ name, visible }`-style
+// reference that only makes sense resolved against a base/predefined
+// counterpart of the same name. `paths` (plural) is `Column`'s shape;
+// `path` (singular) is `TableCriteria`'s — both must count, or a resolved
+// filter-criterion `$ref` (which only ever has a singular `path`) is wrongly
+// treated as a dangling reference and silently dropped, even though it just
+// resolved successfully.
+function isSelfContainedOverrideElement(item) {
+    const paths = item.paths;
+    return ((Array.isArray(paths) && paths.length > 0) ||
+        (typeof item.path === 'string' && item.path.length > 0) ||
+        (typeof item.expression === 'string' && item.expression.length > 0));
+}
+/**
+ * Merge semantics for a config sub-path override against the value already at that
+ * JSONPath. Generic — used for any typename/sub-path the configPath/subPath mechanism
+ * resolves, not just `Table.columns` — a thin wrapper over the shared
+ * `mergeNamedObjectArray` (see `named-array-merge.ts` for the full algorithm), fixed to
+ * this call site's own definition of "self-contained" (`isSelfContainedOverrideElement`).
+ * Any other shape (scalars, plain objects, arrays without a `name` key) is returned
+ * untouched, so the caller's plain whole-value replace applies exactly as it did before
+ * this merge existed.
+ */
+function mergeSubPathOverrideValue(base, override) {
+    if (!isNamedObjectArray(override) || !isNamedObjectArray(base)) {
+        return override;
+    }
+    return mergeNamedObjectArray(base, override, isSelfContainedOverrideElement);
+}
+// Marks each element of a fully-folded named-object array with whether it
+// would still show up — present *and* not hidden — without the layer stored
+// at the identity's own scope tier (`withoutOwnScope`, the same
+// broadest-to-narrowest fold as `mergedValue` minus that one layer; see
+// `applyConfigPathOverride`, where both folds are computed).
+//
+// This drives two decisions in the editing client, both about what its own
+// scope's override has to say explicitly to get the effect the user asked
+// for:
+// - Removing an entry: `inherited` means hiding it (`visible: false`) is
+//   required, since deleting it from this scope's override would just have
+//   the next resolution fold bring it back from a broader layer. Not
+//   inherited means a plain delete suffices.
+// - Adding/re-showing an entry: not inherited means the client must pin
+//   `visible: true` on it, since the broader fold either doesn't have it at
+//   all or has it hidden — and per-attribute merge semantics would otherwise
+//   inherit that `visible: false` straight through this scope's own
+//   override, leaving the entry invisible no matter how it's re-added.
+// Hidden-ness is folded into `inherited` (rather than reported as a separate
+// flag) precisely because both decisions only ever care whether the entry
+// would be *there*, and a broader-hidden entry is exactly as absent from the
+// user's view as a missing one.
+//
+// Only stamps when both values are named-object arrays; any other shape
+// (scalar, plain object, unnamed array) is returned unchanged, mirroring
+// `mergeSubPathOverrideValue`'s own shape guard.
+function stampInherited(mergedValue, withoutOwnScope) {
+    if (!isNamedObjectArray(mergedValue) ||
+        !isNamedObjectArray(withoutOwnScope)) {
+        return mergedValue;
+    }
+    const inheritedByName = new Map(withoutOwnScope.map((item) => [item.name, item]));
+    return mergedValue.map((item) => {
+        const counterpart = inheritedByName.get(item.name);
+        return {
+            ...item,
+            inherited: !!counterpart && counterpart.visible !== false,
+        };
+    });
+}
+function isRefElement(item) {
+    return (item !== null &&
+        typeof item === 'object' &&
+        typeof item.$ref === 'string');
+}
+// Resolves a config-path override array element's fragment-only `$ref`
+// (e.g. `"#$.predefinedColumns[?(@.name=='email')]"`) against `refRoot` —
+// the config-path's own sibling fields, not another file. This is
+// deliberately narrower than `template`'s YAML `$ref` (processed by
+// `processReferencedObject`/`getRefConfig`, which loads another config
+// file): an override-array `$ref` only ever supports the `#<jsonpath>`
+// self-reference form, resolved with the already-vendored `jsonpath`
+// package (the same one `applyConfigPathOverride` uses for `subPath`
+// strings). A ref that doesn't start with `#`, resolves to nothing, or
+// resolves to a non-object is treated the same as any other unresolved
+// override reference elsewhere in this module — silently dropped rather
+// than thrown, so a stale reference just doesn't round-trip into the next
+// save. Multiple matches take the first, in JSONPath document order.
+//
+// The resolved object keeps the original fragment string under `ref` (not
+// `$ref` — GraphQL field names can't start with `$`) rather than dropping
+// it once resolved. Without this, a client re-saving the array unchanged
+// (e.g. reordering a different column) would have no way to tell this
+// element apart from a plain inline column and would flatten it back into
+// a frozen copy on that save — exactly the staleness problem `$ref` exists
+// to avoid. `Column.ref` (the GraphQL field) surfaces it back to the client
+// so `docupace-ui-main` can keep re-emitting the same `$ref` indefinitely.
+function resolveOverrideElementRef(item, refRoot) {
+    const ref = item.$ref;
+    if (!ref.startsWith('#')) {
+        return undefined;
+    }
+    const [match] = jp.query(refRoot, ref.slice(1));
+    if (match === null || typeof match !== 'object') {
+        return undefined;
+    }
+    const { $ref: _unusedRef, ...localOverrides } = item;
+    return {
+        ...match,
+        ...localOverrides,
+        ref,
+    };
+}
+// Expands any `$ref` elements of a config-path override array into the
+// full object they point at (merged with whatever local attributes the
+// element carries alongside `$ref`, e.g. `visible`) before the array is
+// handed to `mergeSubPathOverrideValue`. Runs first so that a `{ $ref,
+// visible }` stub — which has no `name` of its own — always arrives at the
+// name-keyed merge as a proper named object; `mergeSubPathOverrideValue`
+// itself needs no `$ref` awareness.
+function expandRefOverrideElements(value, refRoot) {
+    if (!Array.isArray(value)) {
+        return value;
+    }
+    return value
+        .map((item) => isRefElement(item) ? resolveOverrideElementRef(item, refRoot) : item)
+        .filter((item) => item !== undefined);
+}
+// Builds the object a config-path override's `$ref` fragments resolve
+// against: the config being overridden, overlaid with the *raw* (not yet
+// merged) override value of every other simple top-level subPath in this
+// same patch (e.g. `$.predefinedColumns`). Using the raw override value
+// rather than depending on loop order elsewhere in
+// `applyConfigPathOverride` means a `$.columns` override's `$ref` into
+// `$.predefinedColumns` resolves correctly regardless of which subPath
+// happens to be processed first. Only single-segment paths (`$.foo`) are
+// overlaid — nested subPaths (`$.filter.criteria`) fall back to whatever
+// value is already on `config`, which is fine since nothing currently
+// needs to `$ref` into a nested subPath.
+//
+// `subPathPatch` (the `all` half of `SubPathOverrideLayers`) carries an
+// *ordered* array of layers per jsonPath
+// (broadest to narrowest — see `ConfigurationOverrideResult.subPaths`), not
+// a single already-resolved value. The overlay uses only the narrowest
+// (last) layer, same approximation as before cascading existed: a catalog
+// like `$.predefinedColumns`/`$.predefinedFilters` is always saved as a full
+// replacement at a single scope in practice (never a partial patch spread
+// across tiers), so the narrowest present layer already *is* effectively
+// the whole value — exactly what this overlay used before this function
+// took an array at all.
+function buildRefResolutionRoot(config, subPathPatch) {
+    const overlay = {};
+    for (const [jsonPath, layers] of Object.entries(subPathPatch)) {
+        const topLevelMatch = /^\$\.([^.[]+)$/.exec(jsonPath);
+        if (topLevelMatch && layers.length) {
+            overlay[topLevelMatch[1]] = layers[layers.length - 1];
+        }
+    }
+    return { ...config, ...overlay };
+}
+// Normalizes a provider's resolve() result into the pair of folds
+// `applyConfigPathOverride` works with. `inherited` stays `null` (rather
+// than defaulting to `{}`) when the provider doesn't report it, so the
+// fallback there stays distinguishable from "reported, but this path has no
+// broader layer".
+function toSubPathOverrideLayers(override) {
+    if (!override.subPaths) {
+        return null;
+    }
+    return {
+        all: override.subPaths,
+        inherited: override.inheritedSubPaths ?? null,
+    };
+}
+// Folds one jsonPath's override layers onto the value currently at that
+// location in `target`, and writes the result back in place.
+//
+// `layers` is ordered broadest to narrowest (general, tenant, role, user —
+// see `ConfigurationOverrideResult.subPaths`), so folding them in order onto
+// the current value cascades correctly: each layer only patches what it
+// mentions, inheriting everything else from the fold so far.
+//
+// `inherited` drives the second fold — the same one minus the identity's
+// own-scope layer, i.e. "what this identity would see with no override of
+// its own", which is what `inherited` is stamped against. The provider
+// reports those layers explicitly (`inheritedSubPaths`) because the tier a
+// layer is stored at isn't recoverable from the values alone; dropping the
+// last layer is only a fallback for a provider that doesn't, and is wrong
+// whenever the identity has no row of its own yet (the layer dropped is then
+// a broader one that very much still applies).
+//
+// Throws when `jsonPath` doesn't resolve to a settable location; the caller
+// decides what to do with that.
+function applySubPathOverrideLayers(target, jsonPath, layers, inherited, refRoot) {
+    const currentValue = jp.value(target, jsonPath);
+    const mergedValue = layers
+        .map((layer) => expandRefOverrideElements(layer, refRoot))
+        .reduce((base, override) => mergeSubPathOverrideValue(base, override), currentValue);
+    const inheritedLayers = inherited
+        ? (inherited[jsonPath] ?? [])
+        : layers.slice(0, -1);
+    const withoutOwnScope = inheritedLayers
+        .map((layer) => expandRefOverrideElements(layer, refRoot))
+        .reduce((base, override) => mergeSubPathOverrideValue(base, override), currentValue);
+    const finalValue = stampInherited(mergedValue, withoutOwnScope);
+    const applied = jp.value(target, jsonPath, finalValue);
+    if (applied === undefined) {
+        throw new Error(`does not resolve to a settable location: "${jsonPath}"`);
+    }
+}
+// Deep-sets every stored sub-path override of `subPathPatch` onto a clone of
+// `config`, returning the clone. `config` itself is never mutated.
+function applySubPathOverrides(config, subPathPatch) {
+    // Built from the pre-clone config on purpose: `$ref` fragments resolve
+    // against the config as it was handed in, not against whatever earlier
+    // jsonPaths in this same loop have already written.
+    const refRoot = buildRefResolutionRoot(config, subPathPatch.all);
+    // Deep-clone once, up front — `jp.value` mutates its target in place, and
+    // a shallow `{ ...config }` per jsonPath only protects the top level. A
+    // nested subPath (e.g. `$.filter.criteria`) would otherwise still mutate
+    // `config.filter`, which is the *same* object reference as the original,
+    // potentially-shared config (e.g. reused across tables via
+    // `extend`/fragment composition). Config values are always plain JSON
+    // (from YAML/domain storage), so a JSON round-trip clone is sufficient and
+    // avoids `structuredClone`'s cross-realm `instanceof` pitfalls (its output
+    // fails `instanceof Object` checks — e.g. inside the `jsonpath` package —
+    // when the calling code runs in a different VM realm/context, as test
+    // sandboxes commonly do).
+    const result = JSON.parse(JSON.stringify(config));
+    for (const [jsonPath, layers] of Object.entries(subPathPatch.all)) {
+        // A single malformed override (an unparseable `$ref` JSONPath, or a
+        // jsonPath that doesn't resolve to a settable location) must not abort
+        // resolution of the rest of this config tree — that would take down the
+        // page for every user over one bad admin-authored row. Log and skip just
+        // this jsonPath instead.
+        try {
+            applySubPathOverrideLayers(result, jsonPath, layers, subPathPatch.inherited, refRoot);
+        }
+        catch (error) {
+            log.warn(`Skipping configuration override for "${result.configPath}" at "${jsonPath}": ${error.message}`);
+        }
+    }
+    return result;
+}
+// Domain 735 rows scoped to a Role sync under a `roles/<roleName>/**` tree
+// that mirrors the existing `global/**` tree, instead of a filename suffix —
+// keeps the sibling sub-path convention below identical regardless of scope.
+// Keyed by the role's name rather than its id so the path is human-readable
+// in the site repo; callers are responsible for keeping writes (Config
+// Sync) and reads (`configuration-override-service.ts`'s `resolve()`)
+// pointed at the same role name — renaming a role orphans its previously
+// synced file, and two roles sharing a name would collide on this path.
+function sanitizeSubPathSegment(subPath) {
+    return subPath.replace(/[^A-Za-z0-9_.$()[\]'@=<> -]/g, '_');
+}
+// Role names are admin-entered free text (unlike a role id) — strip
+// anything that isn't safe as a single flat directory segment (notably
+// `/`, which would otherwise nest into subdirectories).
+function sanitizeRoleNameSegment(roleName) {
+    return roleName.replace(/[^A-Za-z0-9_.-]/g, '_');
+}
+// The sub-path sibling-file convention: a JSONPath override (e.g. `$.columns`)
+// on `dataTypes/IContact/tabs/employmentTab/fields` lives at
+// `dataTypes/IContact/tabs/employmentTab/fields.$.columns`, next to the base
+// config it patches, rather than inside it.
+function siblingConfigPath(basePath, subPath) {
+    const dir = path.dirname(basePath);
+    const siblingName = `${path.basename(basePath)}.${sanitizeSubPathSegment(subPath)}`;
+    return dir === '.' ? siblingName : path.join(dir, siblingName);
+}
+// Builds the repo-relative path a (configPath, roleName?, subPath?) tuple
+// resolves to under a `ConfigFileStore`'s root — `global/<configPath>` (or
+// its `roles/<roleName>/<configPath>` sibling), with the sub-path suffix
+// applied first when present. Exported as a pure function so callers that
+// only need the path (e.g. computing a sync target path for a diff) don't
+// need a `ConfigFileStore` instance to do the math.
+export function buildScopedConfigPath(configPath, { roleName, subPath } = {}) {
+    const effectivePath = subPath
+        ? siblingConfigPath(configPath, subPath)
+        : configPath;
+    return roleName
+        ? path.join('roles', sanitizeRoleNameSegment(roleName), effectivePath)
+        : path.join('global', effectivePath);
+}
 export class ConfigFileStore {
     localPath;
     remotePath;
@@ -109,8 +396,43 @@ export class ConfigFileStore {
         const fullPath = path.join(this.localPath, configPath);
         const finalPath = await this.getFinalPath(fullPath);
         const yamlOutput = dump(config);
+        // A role-scoped (`roles/<roleName>/...`) or sub-path sibling file may be
+        // the first file ever written under its directory — unlike the
+        // pre-existing `global/**` tree, that directory isn't guaranteed to
+        // exist yet.
+        await fsPromises.mkdir(path.dirname(finalPath), { recursive: true });
         await fsPromises.writeFile(finalPath, yamlOutput, 'utf8');
     }
+    // Role-aware, sub-path-aware lookup on top of this store's plain
+    // `hasConfig`/`getConfig`/`updateConfig` — resolves a role-scoped file
+    // first when `roleName` is given, falling back to the global path when no
+    // role-scoped file exists yet (mirrors domain 735's GENERAL→ROLE cascade).
+    async hasScopedConfig(configPath, lookup = {}) {
+        if (lookup.roleName) {
+            const rolePath = buildScopedConfigPath(configPath, lookup);
+            if (await this.hasConfig(rolePath)) {
+                return true;
+            }
+        }
+        return this.hasConfig(buildScopedConfigPath(configPath, { subPath: lookup.subPath }));
+    }
+    async getScopedConfig(configPath, lookup = {}) {
+        if (lookup.roleName) {
+            const rolePath = buildScopedConfigPath(configPath, lookup);
+            if (await this.hasConfig(rolePath)) {
+                return this.getConfig(rolePath);
+            }
+        }
+        const globalPath = buildScopedConfigPath(configPath, {
+            subPath: lookup.subPath,
+        });
+        return (await this.hasConfig(globalPath))
+            ? this.getConfig(globalPath)
+            : undefined;
+    }
+    async updateScopedConfig(configPath, config, lookup = {}) {
+        await this.updateConfig(buildScopedConfigPath(configPath, lookup), config);
+    }
     async init() {
         if (this.remotePath) {
             try {
@@ -154,7 +476,9 @@ class ConfigService {
     model;
     configInjectorResolvers;
     providers;
+    wholePatchMergers;
     resolvers;
+    configurationOverrideProvider;
     constructor(model, configStores, extensionOptions = {}) {
         this.configStores = configStores;
         this.model = model;
@@ -164,9 +488,14 @@ class ConfigService {
         this.providers = extensionOptions.providers
             ? { ...builtInProviders, ...extensionOptions.providers }
             : { ...builtInProviders };
+        this.wholePatchMergers = extensionOptions.wholePatchMergers
+            ? { ...builtInWholePatchMergers, ...extensionOptions.wholePatchMergers }
+            : { ...builtInWholePatchMergers };
         this.resolvers = extensionOptions.resolvers
             ? { ...extensionOptions.resolvers }
             : {};
+        this.configurationOverrideProvider =
+            extensionOptions.configurationOverrideProvider;
         if (this.model) {
             this.generateResolvers();
         }
@@ -232,12 +561,34 @@ class ConfigService {
         }
         return processedData;
     }
+    applyReferenceExtensions(processedData, referenceConfig) {
+        if (typeof referenceConfig?.extend !== 'object') {
+            return processedData;
+        }
+        const { extend } = referenceConfig;
+        for (const key in extend) {
+            const extensionValue = extend[key];
+            if (!Array.isArray(extensionValue)) {
+                throw new GraphQLError(`$ref.extend.${key} must be an array; received ${typeof extensionValue}`);
+            }
+            const baseValue = processedData[key];
+            if (baseValue === undefined) {
+                processedData[key] = extensionValue;
+                continue;
+            }
+            if (!Array.isArray(baseValue)) {
+                throw new GraphQLError(`$ref.extend.${key} can only extend an array property; "${key}" resolved to ${typeof baseValue}`);
+            }
+            processedData[key] = [...baseValue, ...extensionValue];
+        }
+        return processedData;
+    }
     async processReferencedObject(configPath, obj, context, values) {
         const referenceConfig = obj.$ref;
         const refConfigPath = typeof referenceConfig === 'object' && referenceConfig.refPath
             ? referenceConfig.refPath
             : referenceConfig;
-        const imageData = await this.processImageReference(refConfigPath);
+        const imageData = await this.processImageReference(refConfigPath, context);
         if (imageData) {
             return imageData;
         }
@@ -246,6 +597,7 @@ class ConfigService {
             ? this.updatePathValues(referencedData, referenceConfig.path)
             : referencedData;
         processedData = this.applyReferenceOverrides(processedData, referenceConfig);
+        processedData = this.applyReferenceExtensions(processedData, referenceConfig);
         processedData = await this.processObjectExpressions(processedData, values, context);
         return this.processObject(configPath, processedData, context, values);
     }
@@ -262,7 +614,16 @@ class ConfigService {
             const builtInQueryResolvers = {
                 pages: () => ({
                     getPageConfig: async (obj, context) => {
-                        const pageConfig = await this.getPageConfig(obj.path, context, true, obj.context);
+                        // `impersonateRoleId`/`impersonateGeneral` are a plain
+                        // pass-through onto context here — this engine never inspects
+                        // identity itself; the host's resolveCurrentIdentity is what
+                        // interprets them and enforces the admin-only restriction.
+                        const impersonation = obj.impersonateRoleId
+                            ? { impersonateRoleId: obj.impersonateRoleId }
+                            : obj.impersonateGeneral
+                                ? { impersonateGeneral: true }
+                                : null;
+                        const pageConfig = await this.getPageConfig(obj.path, impersonation ? { ...context, ...impersonation } : context, true, obj.context);
                         return pageConfig;
                     },
                     getAIConfig: async (obj, context) => {
@@ -346,29 +707,37 @@ class ConfigService {
             return deepMergeResolvers(builtInMutationResolvers, hostMutationResolvers);
         };
     }
-    async processConfig(config, context, processProviders) {
+    // Applies any stored config-path sub-path overrides across the whole
+    // config tree before processConfig's own recursive walk runs, so that
+    // overridden values (which may introduce new sub-config) still go
+    // through provider injection/__typename dispatch below.
+    //
+    // rootSubPathOverrides lets a caller that already resolved overrides for
+    // the root config (e.g. getConfigFromStore, which fetches the whole-object
+    // and sub-path overrides together in one round trip) hand them in directly
+    // instead of having the root node re-resolved a second time below; nested
+    // nodes discovered deeper in the tree are still resolved individually,
+    // since their configPaths aren't known until the tree has been loaded.
+    async processConfig(config, context, processProviders, rootSubPathOverrides) {
+        const overriddenConfig = await this.applyConfigPathOverride(config, context, processProviders, rootSubPathOverrides);
+        return this.processConfigTree(overriddenConfig, context, processProviders);
+    }
+    async processConfigTree(config, context, processProviders) {
         if (!config) {
             return config;
         }
         // Handle arrays
         if (Array.isArray(config)) {
-            return Promise.all(config.map((item) => this.processConfig(item, context, processProviders)));
+            return Promise.all(config.map((item) => this.processConfigTree(item, context, processProviders)));
         }
         // Handle objects
         if (typeof config === 'object') {
             // Recursively process all properties of config
             let processedConfig = { ...config };
             for (const key in processedConfig) {
-                processedConfig[key] = await this.processConfig(processedConfig[key], context, processProviders);
-            }
-            // First process the current object if it has __typename
-            if (processedConfig?.__typename && processProviders) {
-                const providerClass = this.providers[processedConfig.__typename];
-                if (providerClass) {
-                    const provider = new providerClass();
-                    processedConfig = await provider.processConfig(processedConfig, this, context);
-                }
+                processedConfig[key] = await this.processConfigTree(processedConfig[key], context, processProviders);
             }
+            processedConfig = await this.applyTypenameProvider(processedConfig, context, processProviders);
             return processedConfig;
         }
         if (processProviders) {
@@ -376,6 +745,59 @@ class ConfigService {
         }
         return config;
     }
+    // Walks the whole config tree up front (pre-order) and, for every object
+    // that declares a configPath, deep-sets any stored sub-path overrides
+    // (JSONPath-addressed, e.g. "$.columns" or "$.filter.criteria").
+    //
+    // preFetchedSubPaths is only honored for the root node of the walk (the
+    // one being called with a defined third argument); nested calls always
+    // omit it so their own configPath gets resolved fresh.
+    async applyConfigPathOverride(config, context, processProviders, preFetchedSubPaths) {
+        if (!config) {
+            return config;
+        }
+        if (Array.isArray(config)) {
+            return Promise.all(config.map((item) => this.applyConfigPathOverride(item, context, processProviders)));
+        }
+        if (typeof config !== 'object') {
+            return config;
+        }
+        let result = config;
+        if (processProviders) {
+            const subPathPatch = await this.resolveSubPathOverrideLayers(result, context, preFetchedSubPaths);
+            if (subPathPatch) {
+                result = applySubPathOverrides(result, subPathPatch);
+            }
+        }
+        const overriddenEntries = await Promise.all(Object.entries(result).map(async ([key, value]) => [
+            key,
+            await this.applyConfigPathOverride(value, context, processProviders),
+        ]));
+        return Object.fromEntries(overriddenEntries);
+    }
+    // Resolves the sub-path override layers that apply to `config`, unless the
+    // caller already fetched them (`preFetchedSubPaths`, honored for the root
+    // node of a walk — including when it is explicitly `null`).
+    async resolveSubPathOverrideLayers(config, context, preFetchedSubPaths) {
+        if (preFetchedSubPaths !== undefined) {
+            return preFetchedSubPaths;
+        }
+        if (!config.configPath || !this.configurationOverrideProvider) {
+            return null;
+        }
+        return toSubPathOverrideLayers(await this.configurationOverrideProvider.resolve(config.configPath, context));
+    }
+    async applyTypenameProvider(processedConfig, context, processProviders) {
+        if (!processedConfig?.__typename || !processProviders) {
+            return processedConfig;
+        }
+        const providerClass = this.providers[processedConfig.__typename];
+        if (!providerClass) {
+            return processedConfig;
+        }
+        const provider = new providerClass();
+        return await provider.processConfig(processedConfig, this, context);
+    }
     async getRefConfig(configPath, refConfigPath, context, values) {
         let fullPath;
         if (refConfigPath.startsWith('.')) {
@@ -462,13 +884,25 @@ class ConfigService {
         };
         return await processValue(object);
     }
-    async processImageReference(refConfigPath) {
+    async processImageReference(refConfigPath, context) {
         const SUPPORTED_IMAGE_FORMATS = ['.jpg', '.jpeg', '.png', '.svg'];
         // Check if the reference is an image file
         const ext = path.extname(refConfigPath).toLowerCase();
         if (!SUPPORTED_IMAGE_FORMATS.includes(ext)) {
             return null;
         }
+        const override = await this.configurationOverrideProvider?.resolve(refConfigPath, context);
+        if (override?.whole?.contentType) {
+            // A real-MIME-type asset override (image/svg+xml, etc.) is always base64 text, never the
+            // JSON-shaped value the CLOB/JSON attribute mismatch affects — see the screen-layout-patch
+            // branch below for that case.
+            const data = override.whole.value;
+            return {
+                data,
+                mimeType: override.whole.contentType,
+                hash: createHash('sha256').update(data).digest('hex'),
+            };
+        }
         let standardStore;
         for (const store of this.configStores) {
             if (store instanceof ConfigFileStore) {
@@ -520,19 +954,37 @@ class ConfigService {
                 return 'application/octet-stream';
         }
     }
-    async getConfigFromStore(path) {
+    // Resolves the whole-object override and any sub-path overrides for
+    // configPath together, in one provider round trip, instead of fetching
+    // them separately at different points of the processing pipeline. The
+    // sub-path overrides are handed back alongside the config so callers can
+    // thread them into processConfig rather than re-resolving them later; the
+    // whole override is handed back too so a screen-layout-patch (a whole
+    // override distinguished by its contentType) can be applied later in the
+    // pipeline without a second resolve() call.
+    async getConfigFromStore(configPath, context) {
+        const override = await this.configurationOverrideProvider?.resolve(configPath, context);
+        const subPathOverrides = override
+            ? toSubPathOverrideLayers(override)
+            : null;
+        const whole = override?.whole ?? null;
+        if (whole && !whole.contentType) {
+            return { config: load(whole.value), subPathOverrides, whole };
+        }
         const exceptions = [];
         for (const [index, configStore] of this.configStores.entries()) {
             try {
-                return await configStore.getConfig(path);
+                const config = await configStore.getConfig(configPath);
+                return { config, subPathOverrides, whole };
             }
             catch (e) {
                 exceptions.push(e);
                 if (index == this.configStores.length - 1) {
-                    throw new GraphQLError(`Config not found in path in any store: ${path}`, { originalError: exceptions });
+                    throw new GraphQLError(`Config not found in path in any store: ${configPath}`, { originalError: exceptions });
                 }
             }
         }
+        return { config: undefined, subPathOverrides, whole };
     }
     async hasConfig(configPath) {
         return (await Promise.all(this.configStores.map((configStore) => configStore.hasConfig(configPath)))).some(Boolean);
@@ -542,10 +994,40 @@ class ConfigService {
         return this.getDirectConfig(globalPath, context, values, processProviders);
     }
     async getDirectConfig(configPath, context, values, processProviders) {
-        const obj = await this.getConfigFromStore(configPath);
+        const { config: obj, subPathOverrides, whole, } = await this.getConfigFromStore(configPath, context);
         const fullObj = await this.processObject(configPath, obj, context, values);
-        const processedObj = await this.processConfig(fullObj, context, processProviders);
-        return processedObj;
+        const processedObj = await this.processConfig(fullObj, context, processProviders, subPathOverrides);
+        // A whole-object patch override needs the fully $ref/rules-resolved config to merge
+        // onto (its own document is name-keyed against that resolved shape), so it's applied
+        // last — after the whole-file-replacement branch in getConfigFromStore (which this is
+        // mutually exclusive with; that branch short-circuits before $ref resolution) and
+        // after processConfig, not folded into either.
+        return this.applyWholePatchIfPresent(processedObj, whole);
+    }
+    // Shared by getDirectConfig and getPageConfig — both resolve a fully $ref/rules-processed
+    // config that a whole-object patch override (if any exists for this path) needs to merge
+    // onto, so both need this as their final step. `whole` is the same whole-override already
+    // resolved once by getConfigFromStore — no second resolve() call needed.
+    //
+    // This has no knowledge of what any particular contentType's patch document looks like —
+    // it only knows how to look up a WholePatchMerger by contentType and delegate to it. A
+    // `whole` override with no contentType is a full-file replacement, already substituted in
+    // by getConfigFromStore, so there's nothing left to merge here; a contentType with no
+    // registered merger is left untouched rather than guessed at.
+    applyWholePatchIfPresent(processedObj, whole) {
+        const merger = whole?.contentType
+            ? this.wholePatchMergers[whole.contentType]
+            : undefined;
+        if (!merger) {
+            return processedObj;
+        }
+        // `Configuration.value` is typed CLOB, but the underlying attribute is JSON — for a
+        // JSON-shaped value like a whole patch, it can come back already parsed as an object
+        // rather than as the JSON string it was saved as. Handle both shapes.
+        const patch = whole.value && typeof whole.value === 'object'
+            ? whole.value
+            : JSON.parse(whole.value);
+        return merger.merge(processedObj, patch);
     }
     async listDirectConfigs(configPath) {
         const configs = await Promise.all(this.configStores.map((configStore) => configStore.listConfigs(configPath)));
@@ -895,21 +1377,28 @@ class ConfigService {
     }
     async getPageConfig(pagePath, context, processConfig, rulesContext) {
         const globalPath = path.join('global', 'pages', pagePath);
-        const obj = await this.getConfigFromStore(globalPath);
+        const { config: obj, subPathOverrides, whole, } = await this.getConfigFromStore(globalPath, context);
         const fullObj = await this.processObject(globalPath, obj, context, null);
         const matchingRuleGroups = await this.getRuleGroups(rulesContext, context);
         const configToProcess = this.applyFieldRuleOverrides(fullObj, matchingRuleGroups);
-        return await this.processConfig(configToProcess, context, processConfig);
+        const processedObj = await this.processConfig(configToProcess, context, processConfig, subPathOverrides);
+        // Keyed by globalPath — the same `global/pages/<pagePath>` path a whole-patch save
+        // (e.g. the Screen Designer's, see toPageConfigOverridePath in docupace-ui-main) writes
+        // under, so a patch saved against a route like `contacts/{id}/details` is found here
+        // too, not just in getDirectConfig.
+        return this.applyWholePatchIfPresent(processedObj, whole);
     }
     async init() {
         return Promise.all(this.configStores.map((configStore) => configStore.init()));
     }
 }
-export const defaultConfigService = ({ model, configStores, configInjectorResolvers, providers, resolvers, }) => {
+export const defaultConfigService = ({ model, configStores, configInjectorResolvers, providers, wholePatchMergers, resolvers, configurationOverrideProvider, }) => {
     const extensionOptions = {
         configInjectorResolvers,
         providers,
+        wholePatchMergers,
         resolvers,
+        configurationOverrideProvider,
     };
     return new ConfigService(model, configStores.map((configStore) => new ConfigFileStore(configStore)), extensionOptions);
 };