@herbertgao/pi-extensions 2026.9.0 → 2026.9.1

package/node_modules/pi-lens/dist/clients/config-core/deny.js

@@ -0,0 +1,221 @@
+/**
+ * Monotonic deny precedence (#2425, scope item 4; #2415 AC 3).
+ *
+ * Ordinary config values are last-tier-wins. Denials are not. A denial is a
+ * SECURITY decision, and the tier that made it is usually the tier the user
+ * actually controls, so the ordinary rule is exactly backwards for it: today a
+ * repository can hand pi-lens a `.pi-lens.json` that re-enables a server the
+ * user disabled globally, and nothing notices.
+ *
+ * The rule, in one sentence: a denial from an OPERATOR tier is never lifted, and
+ * a denial from any other tier is lifted only by an explicit operator allow of
+ * higher precedence. `provenance.ts` owns the three-way tier classification;
+ * this module owns what it means.
+ *
+ * The third class is why the sentence says "any other tier" rather than "a repo
+ * tier" (#2440 review finding F3). `builtin` is `default`, not `operator`: a
+ * denial pi-lens itself ships is liftable by the person running pi-lens — their
+ * global config, their environment, their command line — and remains unliftable
+ * by anything that arrived with a checkout. Treating a shipped default as an
+ * operator decision made it permanent for everyone, which is a hard-coded
+ * decision rather than a default.
+ *
+ * The two shapes a denial takes (`schema.ts`'s `x-deny`):
+ *
+ * - `boolean-false` — `enabled: false`. Resolution below.
+ * - `array-union` — `disabledServers: ["x"]`. The union of every tier's
+ *   members, always. There is no vocabulary for UN-denying a member, so a
+ *   nearer tier that omits one is expressing nothing, not an allow. This is the
+ *   one place `x-merge-strategy` does not decide the outcome: a `replace`
+ *   strategy still governs how the array is SPELLED across tiers, and the deny
+ *   union still governs which members survive. A deny that a merge strategy
+ *   could erase would not be monotonic.
+ *
+ * Pure functions over their arguments. No state, no ledger writes: a denial
+ * being honored is the normal case, not a degradation.
+ */
+import { isOperatorTier, tierPrecedence, } from "./provenance.js";
+function provenanceOfContribution(source, key) {
+    if (!source)
+        return undefined;
+    return {
+        tier: source.tier,
+        key,
+        ...(source.file === undefined ? {} : { file: source.file }),
+        ...(source.trust === undefined ? {} : { trust: source.trust }),
+    };
+}
+/** Build a provenance entry for a resolved deny leaf. */
+export function denyProvenance(contributions, resolution, key) {
+    return provenanceOfContribution(contributions[resolution.winner], key);
+}
+/**
+ * One provenance entry per SURVIVING member of an `array-union`, keyed by the
+ * member's own JSON pointer.
+ *
+ * The array's own entry still exists and still names the first denying tier;
+ * these are strictly additional, so a consumer that asks about the array is
+ * unaffected and a consumer that asks about a member gets the tier that
+ * actually denied it (#2427 review round 2, F2).
+ */
+export function denyMemberProvenance(contributions, resolution, key) {
+    const entries = [];
+    resolution.memberWinners.forEach((index, position) => {
+        const pointer = `${key}/${position}`;
+        const entry = provenanceOfContribution(contributions[index], pointer);
+        if (entry)
+            entries.push(entry);
+    });
+    return entries;
+}
+/** The `memberWinners` of a leaf with no members. One shared frozen empty. */
+const EMPTY_MEMBER_WINNERS = Object.freeze([]);
+/** Contributions sorted by tier precedence, lowest first, ties in caller order. */
+function byPrecedence(contributions) {
+    return contributions
+        .map((contribution, index) => ({ contribution, index }))
+        .sort((left, right) => tierPrecedence(left.contribution.tier) -
+        tierPrecedence(right.contribution.tier));
+}
+/**
+ * Resolve a `boolean-false` deny.
+ *
+ * - No `false` anywhere: ordinary last-tier-wins.
+ * - An OPERATOR tier said `false`: DENIED, pinned, unliftable by anything. The
+ *   winner is the LOWEST-precedence operator denial, because that is the answer
+ *   to "who denied this" — the first authority to say no, not the last tier to
+ *   repeat it. This holds even for a nearer operator tier: `cli: true` does not
+ *   lift `global: false`. The escape hatch for an operator who changes their
+ *   mind is to change the operator-tier config that denied, not to out-rank it
+ *   from another operator tier.
+ * - Otherwise every denial came from `default` or `repo` tiers, and an OPERATOR
+ *   tier ranked above the FIRST such denial lifts it by saying `true` outright.
+ *   That is what makes a built-in default a default (`builtin: false` +
+ *   `global: true` -> `true`) while keeping repository content out of the
+ *   decision (`builtin: false` + `project: true` -> `false`). A repo tier never
+ *   lifts anything, its own class included.
+ *
+ * The lift test asks `isOperatorTier`, NOT `!isRepoTier`. The negative spelling
+ * is what silently swept `builtin` into the operator class and made every
+ * shipped default permanent; the affirmative one cannot.
+ *
+ * Non-boolean contributions are ignored here: `normalize.ts` has already
+ * dropped values that failed the schema, so anything left is a boolean.
+ */
+export function resolveBooleanDeny(contributions) {
+    const ordered = byPrecedence(contributions);
+    if (ordered.length === 0)
+        return {
+            value: undefined,
+            winner: -1,
+            denied: false,
+            memberWinners: EMPTY_MEMBER_WINNERS,
+        };
+    const denials = ordered.filter((entry) => entry.contribution.value === false);
+    if (denials.length === 0) {
+        const last = ordered[ordered.length - 1];
+        return {
+            value: last.contribution.value,
+            winner: last.index,
+            denied: false,
+            memberWinners: EMPTY_MEMBER_WINNERS,
+        };
+    }
+    const operatorDenial = denials.find((entry) => isOperatorTier(entry.contribution.tier));
+    if (operatorDenial) {
+        return {
+            value: false,
+            winner: operatorDenial.index,
+            denied: true,
+            memberWinners: EMPTY_MEMBER_WINNERS,
+        };
+    }
+    // Every denial came from a shipped default or from repo content. An operator
+    // tier ranked above the FIRST such denial may lift it by saying `true`.
+    const firstDenial = denials[0];
+    const lift = ordered.find((entry) => entry.contribution.value === true &&
+        isOperatorTier(entry.contribution.tier) &&
+        tierPrecedence(entry.contribution.tier) >
+            tierPrecedence(firstDenial.contribution.tier));
+    if (lift) {
+        return {
+            value: true,
+            winner: lift.index,
+            denied: false,
+            memberWinners: EMPTY_MEMBER_WINNERS,
+        };
+    }
+    return {
+        value: false,
+        winner: firstDenial.index,
+        denied: true,
+        memberWinners: EMPTY_MEMBER_WINNERS,
+    };
+}
+/**
+ * Resolve an `array-union` deny: the union of every tier's members.
+ *
+ * Members keep first-contribution order, lowest precedence first, so the
+ * resolved list reads oldest-authority-first and is stable across runs.
+ * Duplicates are folded by their JSON encoding, which is exact for the
+ * primitives a deny list holds and conservative (keeps both) for anything else.
+ *
+ * The winner is the FIRST tier that contributed a surviving member: the tier
+ * that answers "why can I not turn this back on".
+ */
+export function resolveArrayDeny(contributions) {
+    const ordered = byPrecedence(contributions);
+    const seen = new Set();
+    const members = [];
+    // Positionally parallel to `members`: the contribution that introduced each
+    // surviving member, which is the per-member answer to "who denied this"
+    // (#2427 review round 2, F2).
+    const memberWinners = [];
+    let winner = -1;
+    for (const entry of ordered) {
+        const value = entry.contribution.value;
+        if (!Array.isArray(value))
+            continue;
+        for (const member of value) {
+            const identity = primitiveIdentity(member);
+            if (identity !== undefined) {
+                if (seen.has(identity))
+                    continue;
+                seen.add(identity);
+            }
+            members.push(member);
+            memberWinners.push(entry.index);
+            if (winner === -1)
+                winner = entry.index;
+        }
+    }
+    if (winner === -1) {
+        // Nothing denied. Still report the array so a consumer sees an empty list
+        // rather than an absent field, and attribute it to the last contributor.
+        const last = ordered[ordered.length - 1];
+        return {
+            value: members,
+            winner: last ? last.index : -1,
+            denied: false,
+            memberWinners,
+        };
+    }
+    return { value: members, winner, denied: members.length > 0, memberWinners };
+}
+/**
+ * A fold key for a primitive member, or `undefined` for anything else.
+ *
+ * Only primitives are de-duplicated. Two structurally equal objects can carry
+ * different meaning, and keeping both is the conservative half of a deny list —
+ * a union that dropped one would be un-denying something.
+ */
+function primitiveIdentity(member) {
+    if (typeof member === "string")
+        return `s:${member}`;
+    if (typeof member === "number" || typeof member === "boolean") {
+        return `p:${String(member)}`;
+    }
+    if (member === null)
+        return "null";
+    return undefined;
+}

package/node_modules/pi-lens/dist/clients/config-core/index.js

@@ -0,0 +1,47 @@
+/**
+ * THE shared config core (#2425). Every future config loader, catalog, and
+ * selector resolves through this module rather than growing a fourth merge
+ * semantics of its own.
+ *
+ * The pipeline, in one line:
+ *
+ *   RawConfig -> validate(schema) -> NormalizedConfig -> merge(sources) -> Resolved<T>
+ *
+ * `resolveConfig` runs both halves and is the front door. It is a pure function
+ * of its arguments: no file reads, no ledger writes, no logging. Reporting is a
+ * separate, explicit step — `reportPiLensConfigRecords` in
+ * `clients/config-resolve.ts` — so a caller decides when a user gets warned and
+ * under which subsystem; a library that warns on its own would fragment the
+ * warn-once latch across every consumer.
+ *
+ * That step used to live HERE, in `records.ts`, which meant this "pure" library
+ * imported `config-warn.js` and the degradation ledger (#2426). Purity was the
+ * claim and the import graph disagreed: it broke every suite that `vi.mock`s the
+ * ledger wholesale, and it closed seven import cycles the moment the first
+ * loader — all of which sit downstream of `file-utils.ts` — resolved through the
+ * core. The reporting function moved to the module that owns the loaders'
+ * subsystem vocabulary, and the one constant records needs from the ledger
+ * (`DEGRADATION_ENTRIES_PER_KIND`) moved to the `ledger-bounds.js` leaf that
+ * exists for exactly this. Nothing under `config-core/` imports a sink now.
+ *
+ * ALL THREE LOADERS ARE WIRED as of #2426, through `clients/config-resolve.ts`
+ * and the canonical schema in `clients/config-schema.ts`:
+ * `clients/lsp/config.ts` (`loadLSPConfig`), `clients/lens-config.ts`
+ * (`loadPiLensGlobalConfig`), and `clients/project-lens-config.ts`
+ * (`loadPiLensProjectConfig`) are now projections of one resolution. #2416
+ * brings the `lsp.servers.<id>` shape the schema currently only reserves.
+ */
+export { additionalPropertyPolicy, DEFAULT_MERGE_STRATEGY, DENY_KEY, DENY_POLICIES, denyPolicyOf, isDenyPolicy, isConfigObject, isKnownSchemaType, isMergeStrategy, isPlainObject, isSchemaNode, itemsSchema, keyedField, MERGE_STRATEGY_KEY, mergeStrategyOf, propertySchema, SCHEMA_TYPES, schemaType, STABILITY_TIER_KEY, } from "./schema.js";
+export { compareKeys, isOperatorTier, isRepoTier, provenanceFor, provenanceView, SOURCE_TIERS, TIER_CLASS, TIER_PRECEDENCE, tierPrecedence, } from "./provenance.js";
+export { isUnsafeConfigKey, MAX_CONFIG_DEPTH, safeAssign, UNSAFE_CONFIG_KEYS, UNSAFE_KEY_REASON, } from "./safe-object.js";
+export { denyProvenance, resolveArrayDeny, resolveBooleanDeny, } from "./deny.js";
+export { validate, } from "./normalize.js";
+export { boundedKeyLabel, jsonTypeName, MAX_MIGRATION_RECORDS, MAX_RECORD_KEY_LENGTH, MigrationRecordCollector, migrationSubject, } from "./records.js";
+export { buildProcessSpec, MAX_ARGV_BYTES, MAX_ARGV_ENTRIES, MAX_ENV_BYTES, MAX_ENV_ENTRIES, MAX_TIMEOUT_MS, redactProcessSpec, toSpawnArgs, } from "./process-spec.js";
+// `resolveConfig` and its types live in `./resolve.js` (#2426) so a caller can
+// import the front door without also importing this barrel's width — in
+// particular `process-spec.js` -> `project-trust.js`, which closed three
+// import cycles once the config loaders (all downstream of `file-utils.ts`)
+// started resolving through the core. The public surface is unchanged: this is
+// still where the supported entry point is exported from.
+export { resolveConfig, } from "./resolve.js";

package/node_modules/pi-lens/dist/clients/config-core/merge.js

@@ -0,0 +1,357 @@
+/**
+ * Field-wise merge with per-leaf provenance (#2425, scope items 2 and 3).
+ *
+ * The three loaders this replaces each merge differently: `lsp/config.ts`
+ * spreads two objects and hand-patches four keys, `lens-config.ts` projects
+ * field by field, and `project-lens-config.ts` never merges with the global
+ * config at all. One merger with a per-node strategy expresses all three, and
+ * — unlike any of them — it can say afterwards where each value came from.
+ *
+ * Rules:
+ *
+ * - OBJECTS ARE ALWAYS FIELD-WISE. A nearer tier that sets one key of an object
+ *   does not erase the rest. This is #2415's "never whole-object replacement".
+ * - ARRAYS follow the node's `x-merge-strategy`: `replace` by default, or
+ *   `append`, or `keyed:<field>`.
+ * - DENY-ANNOTATED NODES go to `deny.ts` instead, whatever the merge strategy
+ *   says. Monotonic deny outranks precedence by construction.
+ * - EVERY LEAF GETS PROVENANCE, keyed by its JSON-pointer path in the RESOLVED
+ *   value, so a consumer navigates from an entry to the value it describes.
+ *
+ * Sources are sorted by tier precedence rather than trusted in caller order, so
+ * assembling them in a different order cannot silently invert precedence. Ties
+ * keep caller order, which is how several `nested-project` files stay ordered
+ * from outermost to innermost.
+ *
+ * `merge()`'S CONTRACT IS NARROWER THAN "IT ENFORCES THE TWO BOUNDS TOO", which
+ * an earlier version of this comment claimed (#2440 review round 3, finding
+ * F8). It required
+ * every source's `value` to already be `validate()`'s output — a sentence on
+ * `ConfigSource`, not a compiler check — and does NOT independently re-walk a
+ * value to confirm that. Five arms hand a contributor's value back BY
+ * REFERENCE, never walked: the leaf fall-through in `mergeNode`, the
+ * no-object arm in `mergeObject`, the no-array arm in `mergeArray`, `replace`,
+ * and `appendArrays`. Any of those can be reached with an opaque schema node
+ * whose tiers disagree on shape (one contributes an array, another a deeply
+ * nested object at the same key) — `isObjectNode`/`isArrayNode` both answer
+ * "no" for a mixed-shape node, the recursion falls through to the leaf arm,
+ * and whatever depth or hostile keys live inside that value ride along
+ * unexamined and unrecorded. Closing those five arms would mean re-deriving
+ * `normalize.ts`'s walk a second time here — the "half-enforcement" this
+ * function used to attempt and get half right.
+ *
+ * The fix is the CONTRACT, not a second walk: `merge()` is exported from this
+ * file (`@internal`) for `resolveConfig` and for tests that probe it
+ * directly, but it is not part of `index.ts`'s public surface. `resolveConfig`
+ * is the one supported way in, and it validates every source before merging —
+ * a mutation test in `hostile-input.test.ts` proves that by skipping
+ * `validate()` on one source and watching the suite go red.
+ *
+ * The depth counter (`mergeNode`) and the prototype-key check (`mergeObject`,
+ * over the KEYS an already-validated object's field-wise merge is about to
+ * combine) still run. They are a backstop for the common, well-typed
+ * recursion — a value `validate()` already bounded and sanitized, or a
+ * same-shape hand-built value in a direct `merge()` test — not an
+ * independent enforcement boundary; the paragraph above is what they do NOT
+ * cover. The key check also still matters for one real case even after
+ * `validate()`: a hostile key one tier introduces at a node the OTHER tier
+ * also contributes to is a key `mergeObject` discovers only when it unions
+ * that node's field names across contributions, so it is the one place that
+ * can still name and record it, even though `safeAssign` alone would already
+ * have refused the write.
+ *
+ * Pure: no state, no I/O, no ledger writes. Records, when the caller supplies a
+ * collector, describe what the two backstops refused.
+ */
+import { denyMemberProvenance, denyProvenance, resolveArrayDeny, resolveBooleanDeny, } from "./deny.js";
+import { isUnsafeConfigKey, MAX_CONFIG_DEPTH, safeAssign, UNSAFE_KEY_REASON, } from "./safe-object.js";
+import { boundedKeyLabel, MigrationRecordCollector, migrationSubject, } from "./records.js";
+import { tierPrecedence, } from "./provenance.js";
+import { denyPolicyOf, isConfigObject, isKnownSchemaType, isPlainObject, isSchemaNode, itemsSchema, keyedField, mergeStrategyOf, propertySchema, schemaType, } from "./schema.js";
+/**
+ * Merge normalized sources into one resolved config with per-leaf provenance.
+ *
+ * Sources whose value is `undefined` contribute nothing — that is how a config
+ * file that failed validation drops out without a special case.
+ *
+ * @internal Requires every source's `value` to already be `validate()`'s
+ * output. Not part of `clients/config-core/index.ts`'s public surface —
+ * `resolveConfig` is. See this module's doc comment for what merging a
+ * hand-built value can still get past.
+ */
+export function merge(sources, schema, options = {}) {
+    const ordered = [...sources]
+        .map((source, order) => ({ source, order }))
+        .sort((left, right) => {
+        const byTier = tierPrecedence(left.source.tier) - tierPrecedence(right.source.tier);
+        return byTier !== 0 ? byTier : left.order - right.order;
+    })
+        .map((entry, rank) => ({ source: entry.source, rank }));
+    const contributions = [];
+    for (const entry of ordered) {
+        // A source whose value is `undefined` contributes nothing. Filtering with
+        // a narrowing loop rather than `.filter()` keeps the element type exact:
+        // `Array.filter` cannot drop `undefined` from the value's type on its own.
+        const value = entry.source.value;
+        if (value === undefined)
+            continue;
+        contributions.push({ source: entry.source, value, rank: entry.rank });
+    }
+    const provenance = new Map();
+    const context = {
+        provenance,
+        collector: options.collector ?? new MigrationRecordCollector(),
+        file: options.file ?? "",
+    };
+    const value = mergeNode(contributions, schema, "", context, 0);
+    return { value: value, provenance };
+}
+/** Record one node the merger's own bounds refused. Never carries a value. */
+function record(context, entry) {
+    const key = boundedKeyLabel(entry.key);
+    context.collector.add({
+        code: entry.code,
+        file: context.file,
+        key,
+        subject: migrationSubject(context.file, key),
+        reason: entry.reason,
+    });
+}
+function provenanceOf(contribution, key) {
+    const { source } = contribution;
+    return {
+        tier: source.tier,
+        key,
+        ...(source.file === undefined ? {} : { file: source.file }),
+        ...(source.trust === undefined ? {} : { trust: source.trust }),
+    };
+}
+function stamp(context, contribution, key) {
+    context.provenance.set(key, provenanceOf(contribution, key));
+}
+function mergeNode(contributions, schema, key, context, depth) {
+    if (contributions.length === 0)
+        return undefined;
+    // The merger's own depth bound. `validate()` already truncated anything it
+    // walked, so this fires only for a value that reached `merge()` without it —
+    // which the exported signature permits and a review probe demonstrated.
+    if (depth > MAX_CONFIG_DEPTH) {
+        record(context, {
+            code: "PILENS_CFG_0005",
+            key,
+            reason: `config nesting exceeds ${MAX_CONFIG_DEPTH} levels; ignored`,
+        });
+        return undefined;
+    }
+    const denyPolicy = denyPolicyOf(schema);
+    if (denyPolicy)
+        return mergeDeny(contributions, denyPolicy, key, context);
+    if (isObjectNode(schema, contributions)) {
+        return mergeObject(contributions, schema, key, context, depth);
+    }
+    if (isArrayNode(schema, contributions)) {
+        return mergeArray(contributions, schema, key, context, depth);
+    }
+    const winner = contributions[contributions.length - 1];
+    stamp(context, winner, key);
+    return winner.value;
+}
+/**
+ * An object node: either the schema says so, or every contribution IS a plain
+ * object. The second arm matters because a schema may be opaque about a
+ * sub-object, and merging two objects whole would drop the field-wise rule the
+ * moment a schema is incomplete.
+ */
+function isObjectNode(schema, contributions) {
+    const declared = schemaType(schema);
+    if (declared === "object")
+        return true;
+    // Only a RECOGNIZED non-object type rules object-ness out. An unrecognized
+    // keyword leaves the node opaque, and an opaque node is decided by the
+    // value's shape — the same rule `normalize.ts` walks by, so one schema typo
+    // cannot give the two halves different merge semantics.
+    if (isKnownSchemaType(declared))
+        return false;
+    if (schema && isSchemaNode(schema.properties))
+        return true;
+    return contributions.every((entry) => isPlainObject(entry.value));
+}
+function isArrayNode(schema, contributions) {
+    const declared = schemaType(schema);
+    if (declared === "array")
+        return true;
+    if (isKnownSchemaType(declared))
+        return false;
+    return contributions.every((entry) => Array.isArray(entry.value));
+}
+function mergeDeny(contributions, policy, key, context) {
+    const denyContributions = contributions.map((entry) => ({
+        tier: entry.source.tier,
+        value: entry.value,
+        ...(entry.source.file === undefined ? {} : { file: entry.source.file }),
+        ...(entry.source.trust === undefined ? {} : { trust: entry.source.trust }),
+    }));
+    const resolution = policy === "boolean-false"
+        ? resolveBooleanDeny(denyContributions)
+        : resolveArrayDeny(denyContributions);
+    const entry = denyProvenance(denyContributions, resolution, key);
+    if (entry)
+        context.provenance.set(key, entry);
+    // Plus one entry per surviving MEMBER of a union (#2427 review round 2,
+    // F2). The array's own entry answers "which tier denied first"; a caller
+    // asking about one member — "why is THIS server off" — needs the tier that
+    // contributed that member, and reading the array entry for it reported the
+    // wrong tier for every member after the first.
+    for (const member of denyMemberProvenance(denyContributions, resolution, key)) {
+        context.provenance.set(member.key, member);
+    }
+    return resolution.value;
+}
+function mergeObject(contributions, schema, key, context, depth) {
+    const objects = contributions.filter((entry) => isConfigObject(entry.value));
+    if (objects.length === 0) {
+        const winner = contributions[contributions.length - 1];
+        stamp(context, winner, key);
+        return winner.value;
+    }
+    // Field order: lowest tier's keys first, each nearer tier appending only the
+    // keys it introduces. A resolved config therefore reads in the order the
+    // user's own files introduced things.
+    //
+    // A prototype-modifying name is refused HERE, before it can become a child
+    // key: dropping it at the assignment alone would still have walked it and
+    // stamped provenance at a pointer no resolved value can be read from.
+    const names = [];
+    for (const entry of objects) {
+        for (const name of Object.keys(entry.value)) {
+            if (names.includes(name))
+                continue;
+            if (isUnsafeConfigKey(name)) {
+                record(context, {
+                    code: "PILENS_CFG_0006",
+                    key: `${key}/${name}`,
+                    reason: UNSAFE_KEY_REASON,
+                });
+                continue;
+            }
+            names.push(name);
+        }
+    }
+    const out = {};
+    for (const name of names) {
+        const childKey = `${key}/${name}`;
+        const childContributions = [];
+        for (const entry of objects) {
+            const parent = entry.value;
+            if (!Object.hasOwn(parent, name))
+                continue;
+            childContributions.push({
+                source: entry.source,
+                value: parent[name],
+                rank: entry.rank,
+            });
+        }
+        const merged = mergeNode(childContributions, propertySchema(schema, name), childKey, context, depth + 1);
+        if (merged !== undefined)
+            safeAssign(out, name, merged);
+    }
+    return out;
+}
+function mergeArray(contributions, schema, key, context, depth) {
+    const arrays = contributions.filter((entry) => Array.isArray(entry.value));
+    if (arrays.length === 0) {
+        const winner = contributions[contributions.length - 1];
+        stamp(context, winner, key);
+        return winner.value;
+    }
+    const strategy = mergeStrategyOf(schema);
+    const keyed = keyedField(strategy);
+    if (keyed !== undefined) {
+        return mergeKeyedArray(arrays, schema, keyed, key, context, depth);
+    }
+    if (strategy === "append")
+        return appendArrays(arrays, key, context);
+    // `replace`: the highest-precedence contributor supplies the whole array,
+    // and one provenance entry at the array's own pointer says who. Per-element
+    // entries would be noise: every element has the same answer.
+    const winner = arrays[arrays.length - 1];
+    stamp(context, winner, key);
+    return [...winner.value];
+}
+function appendArrays(arrays, key, context) {
+    const out = [];
+    for (const entry of arrays) {
+        for (const member of entry.value) {
+            stamp(context, entry, `${key}/${out.length}`);
+            out.push(member);
+        }
+    }
+    // The array itself is attributed to its lowest-precedence contributor: with
+    // `append`, that is the tier the list STARTED at.
+    stamp(context, arrays[0], key);
+    return out;
+}
+/**
+ * `keyed:<field>` — match entries across tiers by `<field>` and merge them
+ * field-wise, so a project file can override one server's `command` without
+ * restating the whole catalog entry, and without erasing the sibling entries.
+ *
+ * Entries missing the key field cannot be matched, so they are appended in
+ * contribution order and attributed to their own source. Dropping them would be
+ * silent data loss; matching them together would merge unrelated entries.
+ */
+function mergeKeyedArray(arrays, schema, field, key, context, depth) {
+    const items = itemsSchema(schema);
+    const order = [];
+    const groups = new Map();
+    const unkeyed = [];
+    for (const entry of arrays) {
+        for (const member of entry.value) {
+            const identity = keyIdentity(member, field);
+            const memberContribution = {
+                source: entry.source,
+                value: member,
+                rank: entry.rank,
+            };
+            if (identity === undefined) {
+                unkeyed.push(memberContribution);
+                continue;
+            }
+            const group = groups.get(identity);
+            if (group) {
+                group.push(memberContribution);
+                continue;
+            }
+            order.push(identity);
+            groups.set(identity, [memberContribution]);
+        }
+    }
+    const out = [];
+    const pushMerged = (group) => {
+        const merged = mergeNode(group, items, `${key}/${out.length}`, context, depth + 1);
+        // An entry can only merge to `undefined` when its group is empty, which
+        // the construction above cannot produce; dropping it keeps the resolved
+        // list free of holes either way.
+        if (merged !== undefined)
+            out.push(merged);
+    };
+    for (const identity of order)
+        pushMerged(groups.get(identity) ?? []);
+    for (const entry of unkeyed)
+        pushMerged([entry]);
+    // Attribute the list itself to its lowest-precedence contributor, matching
+    // `append`: a keyed list is a list every tier extends, not one a tier owns.
+    stamp(context, arrays[0], key);
+    return out;
+}
+function keyIdentity(member, field) {
+    if (!isConfigObject(member))
+        return undefined;
+    const value = member[field];
+    if (typeof value === "string")
+        return `s:${value}`;
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return `n:${String(value)}`;
+    }
+    return undefined;
+}