@herbertgao/pi-extensions 2026.9.0 → 2026.9.2

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

@@ -0,0 +1,164 @@
+/**
+ * Source tiers, per-leaf provenance, and the redacted provenance projection
+ * (#2425; scope items 2 and 3 of #2415).
+ *
+ * Three config loaders answer "which file won" three different ways today, and
+ * none of them can answer "why". This module fixes the vocabulary once: a
+ * resolved config carries, for every leaf, the tier that produced it, the file
+ * it came from, and the trust decision that applied to that file. #2427's
+ * introspection surface reads exactly this, so "why is server X running" stops
+ * being a log-forensics question.
+ *
+ * Two orderings live here, and they are NOT the same ordering:
+ *
+ * - `SOURCE_TIERS` decides who wins a plain value. Later beats earlier, so a
+ *   CLI flag beats a project file beats a global file beats a built-in default.
+ * - `TIER_CLASS` decides who may LIFT a deny. `deny.ts` builds monotonic deny
+ *   precedence on this split, and nothing else re-derives it.
+ *
+ * Deliberately free of module state: every export is a pure function over its
+ * arguments, so there is no latch here to re-arm at `session_start`.
+ */
+import { homeRelativePath } from "../path-utils.js";
+/**
+ * Where a configuration value came from. A closed union: a tier becomes public
+ * API the moment it appears in a provenance projection, so new members arrive
+ * through the stability policy in `docs/public-api-stability.md`.
+ */
+export const SOURCE_TIERS = [
+    "builtin",
+    "global",
+    "project",
+    "nested-project",
+    "env",
+    "cli",
+    "host",
+];
+/**
+ * Who each tier speaks for. THREE classes, not two (#2440 review finding F3).
+ *
+ * - `repo` — content that arrives with a checkout, which is exactly the content
+ *   a user may never have read. `project` and `nested-project`, for the same
+ *   reason: both are files inside the checkout.
+ * - `operator` — a deliberate act by the person running pi-lens: their global
+ *   config, the environment, the command line, the host application. (`host` is
+ *   operator content because the host is the thing that decided the project's
+ *   trust in the first place.)
+ * - `default` — pi-lens's OWN shipped defaults. Nobody chose them.
+ *
+ * `builtin` was `operator` until this review round, and that conflation had a
+ * consequence nobody would have chosen deliberately: because `deny.ts` never
+ * lifts an operator denial, a built-in `enabled: false` — or any member pi-lens
+ * ships in a built-in deny list — became permanently unliftable BY ANYONE. Not
+ * by a project file, which is correct, but also not by the user's own global
+ * config, their environment, or an explicit command-line flag. A default the
+ * operator cannot override is not a default; it is a hard-coded decision
+ * wearing a config field's clothes, and the only escape would have been editing
+ * pi-lens's source.
+ *
+ * Splitting the class fixes it without weakening anything: a `default` denial
+ * is liftable by an OPERATOR tier and still unliftable by a `repo` tier, so
+ * shipping a conservative default stays safe against repository content while
+ * remaining a default to the person who installed the thing.
+ */
+export const TIER_CLASS = {
+    builtin: "default",
+    global: "operator",
+    project: "repo",
+    "nested-project": "repo",
+    env: "operator",
+    cli: "operator",
+    host: "operator",
+};
+/** Numeric precedence of a tier. Higher wins. */
+export function tierPrecedence(tier) {
+    return SOURCE_TIERS.indexOf(tier);
+}
+/** True for tiers whose content arrives with the checkout. */
+export function isRepoTier(tier) {
+    return TIER_CLASS[tier] === "repo";
+}
+/**
+ * True for tiers the person running pi-lens set deliberately.
+ *
+ * NOT the complement of `isRepoTier`: `builtin` is neither. Asking this question
+ * with `!isRepoTier(tier)` is the exact bug F3 reported, so the affirmative
+ * predicate exists to make the third class impossible to overlook at a call
+ * site.
+ */
+export function isOperatorTier(tier) {
+    return TIER_CLASS[tier] === "operator";
+}
+/**
+ * Project a resolution to its provenance, sorted by key.
+ *
+ * Redacted BY CONSTRUCTION, and that is the whole design: the projection is
+ * built from the provenance map alone and never reads `resolved.value`, so
+ * there is no value here for a later edit to include by accident. An
+ * un-redacted view does not exist, because the un-redacted data is the resolved
+ * config the caller already holds. #2415 AC 4 asks that the DIAGNOSTIC surface
+ * leak nothing, and the way to guarantee that is to make the diagnostic surface
+ * structurally incapable of carrying a value.
+ *
+ * `file` is rewritten home-relative (#2440 review finding F5). A global config
+ * path is `$HOME`-anchored by construction, so the un-rewritten projection put
+ * the operator's account name into every diagnostic that named it — a value the
+ * projection was never asked to carry and the one piece of environment a shared
+ * log reliably leaks.
+ *
+ * `homeDir` is a test seam only, matching `loadLSPConfig`'s: production passes
+ * nothing and gets `os.homedir()`. Without it a redaction test can only prove
+ * the rewrite against the machine's REAL home, which means either writing
+ * fixtures into the operator's home directory or asserting nothing at all
+ * (#2427).
+ */
+export function provenanceView(resolved, homeDir) {
+    const entries = [...resolved.provenance.values()]
+        .map((entry) => ({
+        key: entry.key,
+        tier: entry.tier,
+        ...(entry.file === undefined
+            ? {}
+            : { file: homeRelativePath(entry.file, homeDir) }),
+        ...(entry.trust === undefined ? {} : { trust: entry.trust }),
+    }))
+        .sort((left, right) => compareKeys(left.key, right.key));
+    return { entries };
+}
+/**
+ * The provenance governing a pointer: its own entry, else the nearest ancestor's.
+ *
+ * Not every leaf carries its own entry. An array merged with the `replace`
+ * strategy comes from ONE source, so one entry at the array's own pointer
+ * answers for every element inside it, and per-element copies would be noise
+ * that all say the same thing. Consumers ask this function rather than reading
+ * the map directly, so "which tier decided this" has one answer at every depth.
+ */
+export function provenanceFor(resolved, pointer) {
+    let candidate = pointer;
+    for (;;) {
+        const entry = resolved.provenance.get(candidate);
+        if (entry)
+            return entry;
+        if (candidate === "")
+            return undefined;
+        const cut = candidate.lastIndexOf("/");
+        candidate = cut <= 0 ? "" : candidate.slice(0, cut);
+    }
+}
+/**
+ * Code-unit ordering for any key a diagnostic or telemetry surface sorts.
+ *
+ * Exported so `process-spec.ts` sorts env names with it rather than with a bare
+ * `.sort()` (Sonar S2871) or with `localeCompare`. `localeCompare` would be the
+ * obvious substitute and the wrong one: its answer depends on the machine's
+ * locale and ICU build, so two runs of the same resolution could order the same
+ * env names differently and a telemetry diff would show a change that is not
+ * one. A projection meant to be compared across machines must be
+ * locale-independent.
+ */
+export function compareKeys(left, right) {
+    if (left < right)
+        return -1;
+    return left > right ? 1 : 0;
+}

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

@@ -0,0 +1,218 @@
+/**
+ * Bounded, redacted validation/migration records (#2425, scope item 6).
+ *
+ * A malformed config produces one record per rejected key, and a config file
+ * can hold arbitrarily many keys, so the collection is bounded at the source
+ * rather than at the sink. The bound reuses the degradation ledger's own
+ * `ENTRIES_PER_KIND` discipline — the same number, imported rather than
+ * re-typed, because a record that survives collection only to be dropped by the
+ * ledger is memory spent for nothing.
+ *
+ * REASONS NEVER EMBED FILE CONTENT. Every reason on this surface is assembled
+ * from a fixed template plus structural facts: a key name, a type name, a
+ * count. No value, no snippet, no parser echo. #2431 is the sibling defect on
+ * the existing loaders (a parse error carrying a source snippet); this module
+ * does not fix it, and it does not repeat it. Key names are user text, so they
+ * are stripped of control characters, length-bounded, and run through the
+ * repo's existing `redactSecrets` before they reach a record.
+ *
+ * No module state: the collector is an instance a caller owns for the length of
+ * one resolution, so there is no latch here to re-arm at `session_start`.
+ */
+import { DEGRADATION_ENTRIES_PER_KIND } from "../ledger-bounds.js";
+import { redactSecrets } from "../redact/secrets.js";
+/**
+ * Records retained per resolution. The same value and the same reasoning as the
+ * ledger's per-kind bound: everything past it is counted, not kept.
+ */
+export const MAX_MIGRATION_RECORDS = DEGRADATION_ENTRIES_PER_KIND;
+/** Longest key label a record carries. A key is a name, not a document. */
+export const MAX_RECORD_KEY_LENGTH = 120;
+/**
+ * Codes whose record is a VERDICT ON THE WHOLE CONFIGURATION rather than one
+ * more notice about one key. They are kept however full the collector is, and
+ * are never counted as suppressed (#2426 review round 7, F1).
+ *
+ * The bound exists so that a file with 500 bad keys cannot put 500 notices on
+ * screen: past 20, the rest are worth a count. That reasoning holds for every
+ * PER-KEY record and inverts for this one. "Nothing in this file is in effect"
+ * is not more of the same information — it is the statement that the notices
+ * above it are no longer the whole story, and dropping it leaves the user
+ * reading "19 keys rejected, N more suppressed" about a configuration that
+ * applied nothing at all.
+ *
+ * Enforced in `add`, which is the single choke point BOTH bounds go through:
+ * `resolveConfig`'s own collector and the second `finalizeRecords` pass that
+ * `config-resolve.ts` runs over what the first one returned. A call site that
+ * appended the record itself would be re-bounded by the second pass.
+ *
+ * `PILENS_CFG_0007` is deliberately NOT here: it is produced by `finalize`
+ * after the bound has already been applied, so it can never meet it.
+ */
+const UNBOUNDED_RECORD_CODES = new Set(["PILENS_CFG_0008"]);
+/**
+ * The NUL separator `warnIgnoredConfigOnce` puts between file and key. Built
+ * from its code point rather than written literally, so a literal NUL never
+ * enters this source file.
+ */
+const SUBJECT_SEPARATOR = String.fromCharCode(0);
+/** The ledger subject for a (file, key) pair; a bare file when there is no key. */
+export function migrationSubject(file, key) {
+    return key.length > 0 ? `${file}${SUBJECT_SEPARATOR}${key}` : file;
+}
+/**
+ * Replace every control character with a space.
+ *
+ * Written as a code-point scan rather than a character-class regex so this
+ * source file contains no literal control byte of its own.
+ */
+function stripControlCharacters(text) {
+    let out = "";
+    for (const character of text) {
+        const code = character.codePointAt(0) ?? 0;
+        out += code < 0x20 || code === 0x7f ? " " : character;
+    }
+    return out;
+}
+/**
+ * Make a user-supplied key safe to quote in a diagnostic: strip control
+ * characters (a config key can hold a newline, which would split one warning
+ * across two log lines), bound the length, and run the result through the
+ * repo's secret redactor in case the key itself spells one.
+ */
+export function boundedKeyLabel(key) {
+    const printable = stripControlCharacters(key).trim();
+    const bounded = printable.length > MAX_RECORD_KEY_LENGTH
+        ? `${printable.slice(0, MAX_RECORD_KEY_LENGTH)}...`
+        : printable;
+    return redactSecrets(bounded);
+}
+/** A JSON type name for a value. Structural only: never the value itself. */
+export function jsonTypeName(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+/**
+ * The file a finalized list names when its producer can anchor it to none.
+ *
+ * A list with no records cannot overflow, so this is the floor under an
+ * anchorless producer rather than a case production reaches.
+ */
+const UNANCHORED_RECORD_LABEL = "(config resolution)";
+/**
+ * A bounded collector for one resolution.
+ *
+ * Deliberately an instance rather than a module singleton: a resolution is a
+ * call, not a session, so the collector's lifetime is the call's lifetime and
+ * nothing has to reset it on a session boundary (defect shape 17).
+ */
+export class MigrationRecordCollector {
+    kept = [];
+    dropped;
+    limit;
+    /**
+     * `priorDropped` SEEDS the drop count with records an EARLIER bound already
+     * discarded before this collector saw the list (#2426 review round 6, F1).
+     *
+     * The shared resolution is bounded twice by construction: `resolveConfig`
+     * runs its own collector across every source, and the loader then finalizes
+     * what survived plus the deprecation records it composes itself. Only the
+     * second bound used to be counted, so a `.pi-lens.json` whose 40 refused
+     * keys were truncated to 19 told the user ONE notice had been suppressed
+     * when 21 had. A suppression count that undercounts is worse than no count:
+     * it tells the user the list they were shown is almost complete.
+     */
+    constructor(limit = MAX_MIGRATION_RECORDS, priorDropped = 0) {
+        this.limit = Math.max(0, Math.trunc(limit));
+        this.dropped = Math.max(0, Math.trunc(priorDropped));
+    }
+    add(record) {
+        if (this.kept.length >= this.limit) {
+            // A whole-config verdict outranks the bound — see
+            // `UNBOUNDED_RECORD_CODES`. It is kept AND not counted as suppressed,
+            // so `droppedCount` stays the number of per-key notices the user is
+            // not seeing.
+            if (UNBOUNDED_RECORD_CODES.has(record.code)) {
+                this.kept.push(record);
+                return;
+            }
+            this.dropped += 1;
+            return;
+        }
+        this.kept.push(record);
+    }
+    /** The retained records, oldest first. */
+    get records() {
+        return this.kept;
+    }
+    /** How many records the bound discarded. Counted, never silently zero. */
+    get droppedCount() {
+        return this.dropped;
+    }
+    /**
+     * The retained records plus, when the bound discarded any, ONE record
+     * counting them.
+     *
+     * The whole of "bound a record list and say so when it truncates" lives
+     * here, and nowhere else (#2426 review round 5, F-A/F-B/S-A). Three
+     * producers had grown their own copy of it — the shared resolution, the
+     * project loader's unknown-key scan, and (by omission, which is how the
+     * defect showed) the project loader's legacy-document enumeration, which
+     * shipped its records raw and let one file's key count set the
+     * notification count. A fourth producer must not have to remember any of
+     * this: it calls `finalizeRecords` and is bounded.
+     *
+     * Two finalized lists that anchor to the SAME file and suppress the SAME
+     * number of records render one notice, not two. That is the warn-once
+     * latch doing its documented job: both records state the identical fact
+     * about the identical file, and the user has one thing to do about it.
+     */
+    finalize(anchor) {
+        if (this.dropped === 0)
+            return this.kept;
+        const file = anchor?.file ?? UNANCHORED_RECORD_LABEL;
+        return [
+            ...this.kept,
+            {
+                code: "PILENS_CFG_0007",
+                file,
+                key: "",
+                subject: migrationSubject(file, ""),
+                reason: `${this.dropped} further config notices were suppressed by the bound of ${MAX_MIGRATION_RECORDS}`,
+                ...(anchor?.tier === undefined ? {} : { tier: anchor.tier }),
+            },
+        ];
+    }
+}
+/**
+ * Bound a record list and append the suppression count when it truncates.
+ *
+ * The ONE exported shape every producer uses (#2426 review round 6, S2). It
+ * used to have a twin — `finalizableCollector()`, a pre-subtracted collector a
+ * streaming producer filled key by key — and two shapes for one policy is the
+ * thing round 5 collapsed three copies of this bound to avoid. A push-based
+ * producer buffers into an array and calls this; the array it builds is bounded
+ * by the parsed document already in memory, which is a smaller cost than a
+ * second public entry point onto the same arithmetic.
+ *
+ * One slot of the bound is held back for the overflow record, so a finalized
+ * list is never LONGER than `MAX_MIGRATION_RECORDS` however many records went
+ * in. That subtraction is written here and at no call site. The one exception
+ * is a whole-config verdict (`UNBOUNDED_RECORD_CODES`), which is kept past the
+ * limit by `add` and can therefore make a finalized list one entry longer —
+ * deliberately, because that entry is what makes the other entries readable.
+ *
+ * `priorDropped` is what an earlier bound already discarded — see the
+ * collector's constructor. A caller that finalizes a list some other bound has
+ * already truncated MUST pass it, or the count it publishes is the tail of the
+ * truncation rather than the whole of it.
+ */
+export function finalizeRecords(records, anchor, priorDropped = 0) {
+    const collector = new MigrationRecordCollector(MAX_MIGRATION_RECORDS - 1, priorDropped);
+    for (const record of records)
+        collector.add(record);
+    return collector.finalize(anchor);
+}

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

@@ -0,0 +1,125 @@
+/**
+ * The front door of the config pipeline: validate every source, then merge.
+ *
+ * It lives in its OWN module rather than in `index.ts` (#2426). `index.ts` is
+ * the barrel, so anything importing it also pulls `process-spec.js` and, with
+ * it, `project-trust.js` and the degradation ledger. That was harmless while
+ * nothing downstream of `file-utils.ts` imported the core — and #2426 wires
+ * three loaders that all sit downstream of it, which turned the barrel's width
+ * into three extra import cycles that had nothing to do with what the loaders
+ * actually use. A caller that only needs to resolve a config now imports only
+ * the halves that resolve one.
+ *
+ * `index.ts` re-exports everything here, so the PUBLIC surface is unchanged and
+ * `resolveConfig` is still the one supported way in.
+ */
+import { errorClassName } from "../error-class.js";
+import { merge } from "./merge.js";
+import { validate } from "./normalize.js";
+import { MigrationRecordCollector, migrationSubject, } from "./records.js";
+/**
+ * Validate every source, then merge them.
+ *
+ * One collector spans the whole resolution, so the record bound is per
+ * resolution rather than per file. Sources are handed to `merge` in the order
+ * given; `merge` sorts them by tier precedence itself.
+ *
+ * NEVER THROWS, and that is a contract rather than an observation (#2440
+ * review). `validate` already promised it and enforced it with its own guard,
+ * but the front door called `merge` outside any guard, so a value that reached
+ * the merger in a shape it could not survive — the review's probe was a
+ * 4000-deep blob under an opaque schema node — turned a config load into a
+ * `RangeError` that took the session with it. The bounds inside both halves are
+ * the real fix; this guard is the floor under them, so a future bug in either
+ * half degrades a config to absent instead of failing a session.
+ */
+/**
+ * The highest-precedence source's file and tier — the one whose values would
+ * have won, and so the file a user looking at a failed resolution should open.
+ *
+ * Read DEFENSIVELY because its only caller is a catch block: whatever made the
+ * resolution throw may equally make reading a source's own fields throw, and a
+ * guard that throws while explaining a throw is no guard at all.
+ */
+function anchorSource(sources) {
+    try {
+        const last = sources?.[sources.length - 1];
+        return last === undefined || typeof last.file !== "string"
+            ? undefined
+            : { file: last.file, tier: last.tier };
+    }
+    catch {
+        // pi-lens-ignore: missing-error-propagation — the anchor is best-effort
+        return undefined;
+    }
+}
+export function resolveConfig(options) {
+    const collector = new MigrationRecordCollector(options.maxRecords);
+    try {
+        const normalized = options.sources.map((source) => ({
+            tier: source.tier,
+            ...(source.file === undefined ? {} : { file: source.file }),
+            ...(source.trust === undefined ? {} : { trust: source.trust }),
+            value: validate(source.value, options.schema, {
+                file: source.file ?? "",
+                tier: source.tier,
+                collector,
+            }).value,
+        }));
+        return {
+            resolved: merge(normalized, options.schema, { collector }),
+            records: collector.records,
+            droppedRecordCount: collector.droppedCount,
+        };
+    }
+    catch (error) {
+        // The error CLASS only, never its message, which could quote the file.
+        // `errorClassName` (#2451) — never `config-warn.ts`'s own
+        // `normalizeParseErrorReason`, which this module must not import: that
+        // would reopen the sink-import cycle #2426 removed from `config-core/`.
+        //
+        // ANCHORED to the resolution's highest-precedence source (#2426 review
+        // round 4, S1). This record used to carry `file: ""` and no tier, which
+        // rendered as `ignoring invalid LSP config : …` — no path for the user to
+        // open — and, naming neither a key nor a tier, was reported by every
+        // config subsystem at once, so one internal failure became three notices.
+        // The sources are right here; nothing downstream can recover them.
+        //
+        // `PILENS_CFG_0008`, not `0005` (#2426 review round 6, S1): 0005 is
+        // registered and documented as a per-FIELD rejection, so a user matching
+        // on it expects to have lost one setting. This record means the WHOLE
+        // configuration was dropped, which is a different thing to do about it.
+        //
+        // SURVIVES THE BOUND (#2426 review round 7, F1). The per-field records
+        // fill this same bounded collector, so a resolution that had already
+        // produced `MAX_MIGRATION_RECORDS` of them used to swallow this record
+        // into the anonymous suppression count — and the user then read "19 keys
+        // rejected, 11 further notices suppressed" about a resolution that
+        // applied NOTHING. That is the round-6 inversion arriving through the
+        // bound rather than through the prose round 6 fixed.
+        //
+        // The rule that keeps it lives in `MigrationRecordCollector.add`
+        // (`UNBOUNDED_RECORD_CODES`), not here, because appending it at THIS call
+        // site fixes only this call site: `config-resolve.ts` re-bounds the very
+        // list this function returns through `finalizeRecords`, whose collector
+        // would drop it a second time. One rule at the one choke point covers
+        // both bounds.
+        const anchor = anchorSource(options.sources);
+        const file = anchor?.file ?? "";
+        collector.add({
+            code: "PILENS_CFG_0008",
+            file,
+            key: "",
+            subject: migrationSubject(file, ""),
+            reason: `config resolution failed internally (${errorClassName(error)}); configuration ignored`,
+            ...(anchor ? { tier: anchor.tier } : {}),
+        });
+        return {
+            // The empty resolution, built by the merger from no sources rather than
+            // asserted into existence: `merge([])` is already "nothing resolved".
+            resolved: merge([], options.schema),
+            records: collector.records,
+            droppedRecordCount: collector.droppedCount,
+        };
+    }
+}

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

@@ -0,0 +1,78 @@
+/**
+ * The two structural bounds every walk in the config core obeys (#2425).
+ *
+ * `normalize.ts` and `merge.ts` both build objects out of KEYS THE USER CHOSE.
+ * That makes plain assignment (`out[name] = value`) unsafe in a way that is
+ * invisible at the call site: `out["__proto__"] = x` does not create a property,
+ * it invokes the inherited `__proto__` SETTER and re-parents `out`. The result
+ * serializes as `{}` while `out.injected` answers with the attacker's value, so
+ * every downstream check that reads a field rather than enumerating one is
+ * answered by the hijacked prototype. `constructor` and `prototype` are the same
+ * family: an own property that shadows a name the rest of the runtime reads.
+ *
+ * The rule is REJECT, not sanitize-and-keep. A config file that spells
+ * `__proto__` is never expressing a setting pi-lens has, so there is nothing to
+ * preserve; a record naming the key is the whole of the useful outcome. Both
+ * builders route every key through `safeAssign`, and the assignment itself uses
+ * `Object.defineProperty`, so even a key that somehow reached it could only ever
+ * become an own data property.
+ *
+ * `MAX_CONFIG_DEPTH` lives here rather than in `normalize.ts` because BOTH
+ * halves of the pipeline need it. The validator bounds the walk it performs;
+ * the merger bounds the walk it performs over already-validated values, because
+ * `merge()` is exported and a caller can hand it a value `validate()` never saw.
+ * One constant, two enforcement points, no second number to drift.
+ *
+ * Pure and dependency-free apart from the domain types. No state, no I/O.
+ */
+/**
+ * Deepest nesting either half of the pipeline walks. A config is a settings
+ * document, not a tree; 32 levels is far past anything a human writes and far
+ * short of a stack overflow. Deeper nodes are dropped with a record rather than
+ * truncated silently.
+ */
+export const MAX_CONFIG_DEPTH = 32;
+/**
+ * Keys that change an object's BEHAVIOR rather than its contents when assigned.
+ *
+ * A closed list rather than a heuristic (`/^__/`, "anything with `proto` in
+ * it"): a heuristic silently claims keys a user legitimately meant and silently
+ * misses the next name the runtime gives meaning to. These three are the names
+ * `Object.prototype` actually defines a setter or a read for.
+ */
+export const UNSAFE_CONFIG_KEYS = [
+    "__proto__",
+    "constructor",
+    "prototype",
+];
+const UNSAFE_KEY_SET = new Set(UNSAFE_CONFIG_KEYS);
+/** True for a key no config object may carry. */
+export function isUnsafeConfigKey(name) {
+    return UNSAFE_KEY_SET.has(name);
+}
+/**
+ * The reason text a rejected key produces. One template, shared by both
+ * builders, so the two halves of the pipeline cannot describe the same defect
+ * two ways. The KEY is supplied by the caller's own bounded/redacted label; this
+ * function never sees a value.
+ */
+export const UNSAFE_KEY_REASON = "config key would modify the object prototype; ignored";
+/**
+ * Assign one validated value under one user-chosen key, or refuse.
+ *
+ * Returns `false` when the key was refused, so the caller can record it. The
+ * write is a `defineProperty` rather than a `=` so no inherited setter can run,
+ * which makes the refusal the policy and the mechanism the backstop rather than
+ * the other way round.
+ */
+export function safeAssign(target, name, value) {
+    if (isUnsafeConfigKey(name))
+        return false;
+    Object.defineProperty(target, name, {
+        value,
+        writable: true,
+        enumerable: true,
+        configurable: true,
+    });
+    return true;
+}