@skanl/brambo-projection 0.1.1

package/dist/formats.js

@@ -0,0 +1,1301 @@
+import { readFile } from 'node:fs/promises';
+import { BramboError, BRAMBO_ERROR_CODES, REGISTRY_ENTRY_TYPES, UNPROJECTABLE_ENTRY_IDS, isRecord, } from '@skanl/brambo-contracts';
+import { parse, parseTree } from 'jsonc-parser';
+import { FAULT_UNLOCATED, faultDetail, positionOf, strictFaultLocation } from './document-fault.js';
+import { hashOwnedText, resolveOwnedPath, sameOwnedPath } from './ledger.js';
+/**
+ * The keys THIS vendor's renderer emits, which are exactly the keys its reader
+ * consumes — asked of the renderer rather than written down beside it.
+ *
+ * A hand-written list here was a THIRD spelling of the same fact, and a key
+ * added to a renderer and forgotten in that list would be reported to the user
+ * as `dropped` while brambo was writing it. The sample is arbitrary: every
+ * renderer emits a fixed key set, which `vendor-conformance.test.ts` pins.
+ */
+export function renderedKeys(traits) {
+    return Object.keys(traits.renderMcpEntry({ id: 'sample', command: 'sample', args: ['sample'] }));
+}
+/**
+ * The native keys the renderer does not emit, sorted so two runs report the same
+ * list. `REGISTRY_PATH_FIELDS` gives an `mcp-server` a command and its arguments
+ * and nothing else, so a vendor's `env` table or a `url` has no root field to
+ * land in — and D10 says those are REPORTED, never silently lost.
+ */
+function droppedNativeKeys(native, rendered) {
+    return Object.keys(native)
+        .filter((key) => !rendered.includes(key))
+        .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+/**
+ * The reading Claude Code and Codex SHARE: a `command` string beside an optional
+ * `args` array of strings.
+ *
+ * OpenCode deliberately does NOT use it. Its `command` is the whole argv, and
+ * D1 keeps that un-join in `opencode-config.ts` alone; what is shared here is
+ * only the vocabulary the other two already spell identically, so the sentence a
+ * user reads for a missing command cannot differ between two vendors that failed
+ * the same way.
+ */
+export function readNativeCommand(native) {
+    const command = native['command'];
+    if (typeof command !== 'string' || command === '') {
+        return {
+            ok: false,
+            detail: command === undefined
+                ? "it declares no 'command', so there is nothing for brambo to run"
+                : "'command' is not a non-empty string, so there is nothing for brambo to run",
+        };
+    }
+    const args = native['args'];
+    if (args !== undefined && typeof args === 'string') {
+        return { ok: false, detail: "'args' is a string rather than an array, and brambo will not guess how to split it" };
+    }
+    return { ok: true, command, args: args ?? [] };
+}
+// --- shared text helpers ----------------------------------------------------
+const BYTE_ORDER_MARK = '\uFEFF';
+const FALLBACK_INDENT_UNIT = '  ';
+function isSpace(character) {
+    return character === ' ' || character === '\t' || character === '\r' || character === '\n';
+}
+function lineEndingOf(bodyText) {
+    return bodyText.includes('\r\n') ? '\r\n' : '\n';
+}
+/** Leading whitespace of the FIRST indented content line; fallback two spaces. */
+function indentationUnitOf(bodyText) {
+    for (const line of bodyText.split('\n')) {
+        const indented = /^[ \t]+(?=\S)/.exec(line);
+        if (indented)
+            return indented[0];
+    }
+    return FALLBACK_INDENT_UNIT;
+}
+function leadingWhitespaceBefore(text, offset) {
+    let start = offset;
+    while (start > 0 && (text[start - 1] === ' ' || text[start - 1] === '\t'))
+        start -= 1;
+    return text.slice(start, offset);
+}
+function lineIndentAt(text, offset) {
+    const lineStart = text.lastIndexOf('\n', Math.max(0, offset - 1)) + 1;
+    return /^[ \t]*/.exec(text.slice(lineStart, offset))[0];
+}
+function indentLevelOf(whitespace, unit) {
+    let level = 0;
+    let rest = whitespace;
+    while (rest.startsWith(unit)) {
+        rest = rest.slice(unit.length);
+        level += 1;
+    }
+    return level;
+}
+/**
+ * `detail` is a string brambo AUTHORS, never a parser's message and never a
+ * `cause`. `document-fault.ts` holds the rule and why it exists; the `string`
+ * parameter is what enforces it, because an `Error` can no longer be handed in
+ * at all.
+ */
+function nativeMalformed(filePath, detail) {
+    return new BramboError(BRAMBO_ERROR_CODES.projectionNativeMalformed, `native config file '${filePath}' is malformed: ${detail}`);
+}
+function nativeUnclaimable(filePath, detail) {
+    return new BramboError(BRAMBO_ERROR_CODES.projectionNativeUnclaimable, `native config file '${filePath}' is intact but brambo cannot place entries there: ${detail}`);
+}
+/** Sorted-key JSON: two renderings of the same entry hash the same. */
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(',')}]`;
+    if (isRecord(value)) {
+        return `{${Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+// --- JSON family: native key-path splice ------------------------------------
+function memberProperties(objectNode, key) {
+    return (objectNode.children ?? []).filter((property) => property.children?.[0]?.value === key);
+}
+function memberValue(objectNode, key) {
+    return memberProperties(objectNode, key)[0]?.children?.[1];
+}
+function objectRootOf(body, filePath, strictJson) {
+    if (strictJson) {
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            // The error is DISCARDED unread. See `nativeMalformed`: for the shapes
+            // that quote the document there is no position in the message to keep.
+            throw nativeMalformed(filePath, strictFaultLocation(body));
+        }
+        if (!isRecord(parsed))
+            throw nativeMalformed(filePath, 'document root is not an object');
+        // Strict JSON already validated above; the tree exists by construction.
+        return parseTree(body);
+    }
+    // Errors are COLLECTED, and trailing commas are allowed while collecting.
+    // `parseTree` recovers: handed a broken document it returns a tree built from
+    // a guess, and brambo splices by OFFSET into whatever it returns. Without this
+    // out-param a file whose only fault is an unquoted key parsed as an object and
+    // brambo wrote its own block INSIDE one of the user's own server definitions.
+    //
+    // `allowTrailingComma` is not decoration. A trailing comma is legitimate JSONC
+    // that every JSONC-tolerant vendor accepts, and WITHOUT the option it reports
+    // the same `PropertyNameExpected` a genuinely doubled comma does — so
+    // refusing on any error would reject working files. With it, every legitimate
+    // spelling (comments, trailing commas, nested and in arrays) collects zero and
+    // every real fault collects at least one. `canonical()` below already parses
+    // this way; this is the same answer given at both doors.
+    const errors = [];
+    let root;
+    try {
+        root = parseTree(body, errors, { allowTrailingComma: true });
+    }
+    catch {
+        // `parseTree` RECURSES and throws `RangeError` past ~5000 nesting levels
+        // (Spec M17.A, Change Log 2). Refusing coded without a location is the
+        // documented outcome; propagating an uncoded throw is not.
+        throw nativeMalformed(filePath, FAULT_UNLOCATED);
+    }
+    const first = errors[0];
+    if (first !== undefined) {
+        // The FIRST only. A recovering parser cascades — an unquoted key reports
+        // four — and the rest are that one's shadow.
+        //
+        // The parser's OWN code (`InvalidSymbol`, `PropertyNameExpected`), not prose
+        // brambo invents for it. It is terser than a sentence and it is stable,
+        // greppable, and the same word the user's editor and every other
+        // jsonc-parser consumer already shows them for that fault.
+        throw nativeMalformed(filePath, faultDetail(body, first));
+    }
+    if (!root || root.type !== 'object') {
+        throw nativeMalformed(filePath, 'document root is not an object');
+    }
+    return root;
+}
+/**
+ * Deterministic serializer for the VENDOR-shaped entry only — fixed key order
+ * (the trait renderer's insertion order), arrays one element per line. This is
+ * not a general JSON writer: it exists so the same entry always renders to the
+ * same bytes.
+ */
+function serializeJsonValue(value, level, unit, eol) {
+    const at = (depth) => unit.repeat(depth);
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return '[]';
+        const inner = value
+            .map((item) => `${at(level + 1)}${serializeJsonValue(item, level + 1, unit, eol)}`)
+            .join(`,${eol}`);
+        return `[${eol}${inner}${eol}${at(level)}]`;
+    }
+    if (!isRecord(value)) {
+        // Unreachable for a NativeEntryShape; a trait renderer returning anything
+        // else must fail coded instead of emitting invalid JSON.
+        throw new BramboError(BRAMBO_ERROR_CODES.projectionTraitsInvalid, `native entry shape contains a value that cannot be serialized: ${JSON.stringify(value)}`);
+    }
+    const entries = Object.entries(value);
+    if (entries.length === 0)
+        return '{}';
+    const inner = entries
+        .map(([key, child]) => `${at(level + 1)}${JSON.stringify(key)}: ${serializeJsonValue(child, level + 1, unit, eol)}`)
+        .join(`,${eol}`);
+    return `{${eol}${inner}${eol}${at(level)}}`;
+}
+/** The member text WITHOUT its leading indent, matching what parseTree spans. */
+function renderJsonMember(id, shape, level, style) {
+    return `${JSON.stringify(id)}: ${serializeJsonValue(shape, level, style.unit, style.eol)}`;
+}
+/**
+ * Brambo's entry lines up with the container's EXISTING members; only an empty
+ * container falls back to one unit in from its own line. Rendering root members
+ * at column 0 inside a two-space document is how the previous build produced
+ * output no formatter would leave alone.
+ */
+function memberLevelOf(body, objectNode, unit) {
+    const first = objectNode.children?.[0];
+    if (first !== undefined)
+        return indentLevelOf(leadingWhitespaceBefore(body, first.offset), unit);
+    if (objectNode.parent === undefined)
+        return 0;
+    return indentLevelOf(lineIndentAt(body, objectNode.offset), unit) + 1;
+}
+/**
+ * Insertion is purely ADDITIVE: characters are added at exactly one point and
+ * no existing byte is rewritten. With a trailing comma after the last property
+ * we insert right after it; otherwise we contribute the separator comma
+ * ourselves. An empty object owns its interior wholesale.
+ */
+function insertIntoObject(body, objectNode, memberText, style, level) {
+    const indent = style.unit.repeat(level);
+    const properties = objectNode.children ?? [];
+    if (properties.length === 0) {
+        // An empty object owns its interior wholesale, and closes on the
+        // container's own line so nothing reformats it on the next save.
+        const at = objectNode.offset + 1;
+        const closingIndent = style.unit.repeat(Math.max(0, level - 1));
+        return {
+            start: at,
+            end: at,
+            replacement: `${style.eol}${indent}${memberText}${style.eol}${closingIndent}`,
+        };
+    }
+    const last = properties[properties.length - 1];
+    const lastEnd = last.offset + last.length;
+    for (let index = lastEnd; index < body.length; index += 1) {
+        const character = body[index];
+        if (character === ',') {
+            return { start: index + 1, end: index + 1, replacement: `${style.eol}${indent}${memberText}` };
+        }
+        if (!isSpace(character))
+            break;
+    }
+    return { start: lastEnd, end: lastEnd, replacement: `,${style.eol}${indent}${memberText}` };
+}
+/**
+ * Symmetric with insertion: takes back the separator comma and the whitespace
+ * brambo's own line introduced, so removal cannot leave a dangling comma that
+ * strict JSON would reject.
+ */
+function jsonRemovalSpan(body, existing) {
+    let end = existing.end;
+    let scan = end;
+    while (isSpace(body[scan]))
+        scan += 1;
+    const hasTrailingComma = body[scan] === ',';
+    if (hasTrailingComma)
+        end = scan + 1;
+    let start = existing.start;
+    while (start > 0 && isSpace(body[start - 1]))
+        start -= 1;
+    if (!hasTrailingComma && body[start - 1] === ',')
+        start -= 1;
+    if (body[start - 1] === '{') {
+        // We were the object's only member. Inserting into an empty object adds
+        // whitespace on BOTH sides, so emptying one has to take both back —
+        // otherwise every rename leaves another blank line behind.
+        let closing = end;
+        while (isSpace(body[closing]))
+            closing += 1;
+        if (body[closing] === '}')
+            end = closing;
+    }
+    return { start, end };
+}
+/**
+ * A JSON node as a {@link NativeEntryShape} value, or `undefined` when it is
+ * neither a string nor an array of them.
+ *
+ * `undefined` is NOT "absent": it is "brambo has no way to carry this", which the
+ * caller turns into a reported foreign key. A number, a boolean, a nested object
+ * and a mixed array all land here.
+ */
+function nativeValueOf(node) {
+    if (node === undefined)
+        return undefined;
+    if (node.type === 'string')
+        return node.value;
+    if (node.type !== 'array')
+        return undefined;
+    const items = node.children ?? [];
+    if (!items.every((item) => item.type === 'string'))
+        return undefined;
+    return items.map((item) => item.value);
+}
+const JSONC_STRATEGY = {
+    validate(body, filePath, traits) {
+        const root = objectRootOf(body, filePath, traits.strictJson ?? false);
+        if (memberProperties(root, traits.mcpContainerKey).length > 1) {
+            throw nativeMalformed(filePath, `document declares more than one '${traits.mcpContainerKey}' key`);
+        }
+        const container = memberValue(root, traits.mcpContainerKey);
+        if (container !== undefined && container.type !== 'object') {
+            // The vendor's own key holding something brambo cannot place entries in.
+            // The FILE is fine — telling the user it is malformed would be a lie.
+            throw nativeUnclaimable(filePath, `'${traits.mcpContainerKey}' holds a ${container.type}, not an object of servers`);
+        }
+    },
+    containerConflict() {
+        // JSON has no ambiguous container spelling: validate() already rejected the
+        // two shapes that exist (duplicate key, non-object value).
+        return undefined;
+    },
+    entryConflict(body, traits, id) {
+        const root = parseTree(body);
+        const container = root === undefined ? undefined : memberValue(root, traits.mcpContainerKey);
+        if (container === undefined || container.type !== 'object')
+            return undefined;
+        if (memberProperties(container, id).length > 1) {
+            return `'${traits.mcpContainerKey}.${id}' is declared more than once; brambo would edit the first while every vendor reads the last`;
+        }
+        return undefined;
+    },
+    locate(body, traits, id) {
+        const root = parseTree(body);
+        if (!root || root.type !== 'object')
+            return undefined;
+        const container = memberValue(root, traits.mcpContainerKey);
+        if (container === undefined || container.type !== 'object')
+            return undefined;
+        const member = memberProperties(container, id)[0];
+        return member === undefined ? undefined : { start: member.offset, end: member.offset + member.length };
+    },
+    listEntries(body, traits) {
+        const root = parseTree(body);
+        const container = root === undefined || root.type !== 'object' ? undefined : memberValue(root, traits.mcpContainerKey);
+        // An absent container is E2 — a config brambo writes into that holds no
+        // servers yet — and is no more an error on the way in than on the way out.
+        if (container === undefined || container.type !== 'object')
+            return { entries: [], unreadable: [] };
+        const entries = [];
+        const unreadable = [];
+        for (const property of container.children ?? []) {
+            const id = property.children?.[0]?.value;
+            if (typeof id !== 'string')
+                continue;
+            const value = property.children?.[1];
+            if (value === undefined || value.type !== 'object') {
+                unreadable.push({
+                    id,
+                    detail: `'${traits.mcpContainerKey}.${id}' holds a ${value?.type ?? 'nothing'} rather than an object, so brambo cannot read a command out of it`,
+                });
+                continue;
+            }
+            const native = {};
+            const foreignKeys = [];
+            for (const member of value.children ?? []) {
+                const key = member.children?.[0]?.value;
+                if (typeof key !== 'string')
+                    continue;
+                const read = nativeValueOf(member.children?.[1]);
+                if (read === undefined)
+                    foreignKeys.push(key);
+                else
+                    native[key] = read;
+            }
+            entries.push({ id, native, foreignKeys });
+        }
+        return { entries, unreadable };
+    },
+    canonical(ownedText) {
+        // The owned text is one object MEMBER; wrapping it makes a document jsonc
+        // can parse. A member that no longer parses has been edited beyond
+        // recognition, and its raw text is the honest canonical form.
+        const parsed = parse(`{${ownedText}}`, [], { allowTrailingComma: true });
+        return isRecord(parsed) ? stableJson(parsed) : ownedText.trim();
+    },
+    upsert(body, style, traits, entry, existing) {
+        // validate() ran first, so the root is an object and the container is
+        // either absent or an object.
+        const root = parseTree(body);
+        if (existing !== undefined) {
+            const level = indentLevelOf(leadingWhitespaceBefore(body, existing.start), style.unit);
+            const owned = renderJsonMember(entry.id, traits.renderMcpEntry(entry), level, style);
+            return { start: existing.start, end: existing.end, replacement: owned, owned };
+        }
+        const container = memberValue(root, traits.mcpContainerKey);
+        if (container !== undefined) {
+            const level = memberLevelOf(body, container, style.unit);
+            const owned = renderJsonMember(entry.id, traits.renderMcpEntry(entry), level, style);
+            return { ...insertIntoObject(body, container, owned, style, level), owned };
+        }
+        // The vendor's container does not exist yet: brambo creates it holding this
+        // one entry, indented like the document's own root members so nothing
+        // reformats it on the next save.
+        const containerLevel = memberLevelOf(body, root, style.unit);
+        const owned = renderJsonMember(entry.id, traits.renderMcpEntry(entry), containerLevel + 1, style);
+        const containerMember = `${JSON.stringify(traits.mcpContainerKey)}: {${style.eol}${style.unit.repeat(containerLevel + 1)}${owned}${style.eol}${style.unit.repeat(containerLevel)}}`;
+        return { ...insertIntoObject(body, root, containerMember, style, containerLevel), owned };
+    },
+    remove(body, _style, existing) {
+        return jsonRemovalSpan(body, existing);
+    },
+    reclaimContainer(body, traits) {
+        const root = parseTree(body);
+        if (!root || root.type !== 'object')
+            return undefined;
+        const property = memberProperties(root, traits.mcpContainerKey)[0];
+        const container = property?.children?.[1];
+        if (property === undefined || container === undefined || container.type !== 'object')
+            return undefined;
+        if ((container.children ?? []).length > 0)
+            return undefined;
+        // ponytail: brambo cannot tell a container it created from an empty one the
+        // user left behind — but for all three vendors an empty container and an
+        // absent one are the same configuration, so reclaiming it is semantically
+        // free and stops renames from accreting dead scaffolding.
+        return jsonRemovalSpan(body, { start: property.offset, end: property.offset + property.length });
+    },
+};
+// --- TOML family: one native table per entry --------------------------------
+function tomlBareKey(key) {
+    return /^[A-Za-z0-9_-]+$/.test(key) ? key : JSON.stringify(key);
+}
+function tomlValue(value) {
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    return `[${value.map((item) => JSON.stringify(item)).join(', ')}]`;
+}
+/**
+ * Splits a TOML key path into its decoded segments, tolerating the spellings
+ * that mean the same key: bare, basic-quoted, literal-quoted, and whitespace
+ * around the dots. This is key canonicalisation, NOT a TOML parser — anything
+ * it cannot decode returns undefined and is treated as unrecognised.
+ */
+function splitTomlKeyPath(raw) {
+    const segments = [];
+    let rest = raw.trim();
+    if (rest === '')
+        return undefined;
+    for (;;) {
+        const basic = /^"((?:[^"\\]|\\.)*)"/.exec(rest);
+        const literal = /^'([^']*)'/.exec(rest);
+        const bare = /^[A-Za-z0-9_-]+/.exec(rest);
+        if (basic) {
+            const decoded = JSON.parse(basic[0]);
+            segments.push(String(decoded));
+            rest = rest.slice(basic[0].length);
+        }
+        else if (literal) {
+            segments.push(literal[1]);
+            rest = rest.slice(literal[0].length);
+        }
+        else if (bare) {
+            segments.push(bare[0]);
+            rest = rest.slice(bare[0].length);
+        }
+        else {
+            return undefined;
+        }
+        rest = rest.trimStart();
+        if (rest === '')
+            return segments;
+        if (!rest.startsWith('.'))
+            return undefined;
+        rest = rest.slice(1).trimStart();
+    }
+}
+/** The decoded path of a `[a.b]` header line, tolerating spacing and comments. */
+function tomlHeaderPath(line) {
+    const match = /^\s*\[([^[\]]*)\]\s*(?:#.*)?$/.exec(line);
+    return match === undefined || match === null ? undefined : splitTomlKeyPath(match[1]);
+}
+/** The decoded path on the left of a `key = value` line, if it is one. */
+function tomlAssignmentPath(line) {
+    const match = /^\s*([^=#]+?)\s*=/.exec(line);
+    return match === null ? undefined : splitTomlKeyPath(match[1]);
+}
+function startsTable(lineText) {
+    return lineText.trimStart().startsWith('[');
+}
+function tomlHeader(traits, id) {
+    return `[${traits.mcpContainerKey}.${tomlBareKey(id)}]`;
+}
+function renderTomlTable(traits, entry, style) {
+    const lines = [tomlHeader(traits, entry.id)];
+    for (const [key, value] of Object.entries(traits.renderMcpEntry(entry))) {
+        lines.push(`${key} = ${tomlValue(value)}`);
+    }
+    return lines.join(style.eol) + style.eol;
+}
+function splitLines(body) {
+    const lines = [];
+    let start = 0;
+    while (start <= body.length) {
+        const newline = body.indexOf('\n', start);
+        if (newline < 0) {
+            if (start < body.length)
+                lines.push({ start, end: body.length, text: body.slice(start) });
+            break;
+        }
+        lines.push({ start, end: newline + 1, text: body.slice(start, newline) });
+        start = newline + 1;
+    }
+    return lines;
+}
+/** Indices of the header lines that define `[<container>.<id>]`, any spelling. */
+function tomlEntryHeaders(lines, container, id) {
+    const found = [];
+    lines.forEach((line, index) => {
+        const path = tomlHeaderPath(line.text);
+        if (path?.length === 2 && path[0] === container && path[1] === id)
+            found.push(index);
+    });
+    return found;
+}
+const TOML_STRATEGY = {
+    validate() {
+        // Foreign TOML is never parsed, so malformed foreign TOML is undetectable
+        // here by design. Every shape brambo MUST notice is a container conflict,
+        // which fails closed below instead of relying on a parse.
+    },
+    /**
+     * The load-bearing half of "not found is not free". Every one of these
+     * spellings defines servers brambo cannot address; appending its own table
+     * anyway would define the same table twice, which stops the user's entire
+     * config.toml from loading in DEFAULT mode — the exact catastrophe
+     * correction-01 exists to eliminate.
+     */
+    containerConflict(body, traits) {
+        let inRootTable = true;
+        for (const line of splitLines(body)) {
+            const header = tomlHeaderPath(line.text);
+            if (header !== undefined) {
+                inRootTable = false;
+                if (header.length === 1 && header[0] === traits.mcpContainerKey) {
+                    return `'[${traits.mcpContainerKey}]' is defined as a table, so its servers are keys brambo cannot address individually`;
+                }
+                continue;
+            }
+            if (startsTable(line.text)) {
+                // An array-of-tables header or anything else bracketed: no longer root.
+                inRootTable = false;
+                continue;
+            }
+            if (!inRootTable)
+                continue;
+            const assignment = tomlAssignmentPath(line.text);
+            if (assignment !== undefined && assignment[0] === traits.mcpContainerKey) {
+                return `'${assignment.join('.')}' is assigned directly, so '${traits.mcpContainerKey}' is not a set of tables brambo can add to`;
+            }
+        }
+        return undefined;
+    },
+    entryConflict(body, traits, id) {
+        const headers = tomlEntryHeaders(splitLines(body), traits.mcpContainerKey, id);
+        return headers.length > 1
+            ? `'${traits.mcpContainerKey}.${id}' is defined ${headers.length} times; the document does not load as it is and brambo will not add to it`
+            : undefined;
+    },
+    /**
+     * ponytail: line-oriented table locator, not a TOML parser. Brambo renders
+     * every value on one line, so no line inside a table brambo wrote can start
+     * with '[' — a user edit that introduces one ends the region early, the hash
+     * stops matching, and the entry lands as 'edited' drift. That is the safe
+     * direction: brambo reports instead of rewriting.
+     */
+    locate(body, traits, id) {
+        const lines = splitLines(body);
+        const headerIndex = tomlEntryHeaders(lines, traits.mcpContainerKey, id)[0];
+        if (headerIndex === undefined)
+            return undefined;
+        let end = lines[headerIndex].end;
+        for (let index = headerIndex + 1; index < lines.length; index += 1) {
+            const line = lines[index];
+            if (startsTable(line.text))
+                break;
+            // Trailing blank lines after the table are foreign spacing, not ours.
+            if (line.text.trim() !== '')
+                end = line.end;
+        }
+        return { start: lines[headerIndex].start, end };
+    },
+    /**
+     * ponytail: LINE-ORIENTED, exactly like `locate` above and for the same
+     * reason — this is not a TOML parser and does not become one to read. Brambo
+     * renders every value on one line with `JSON.stringify`, so `JSON.parse` on
+     * the value text is that renderer's exact inverse, and anything it cannot
+     * parse is REPORTED as unreadable rather than guessed at: a TOML literal
+     * string (`command = 'uvx'`), a multi-line array, a trailing comment. Ceiling:
+     * brambo ingests only entries spelled the way brambo writes them. Upgrade path:
+     * a real TOML parser, worth it the first time a user reports a legitimate
+     * server brambo declined to read.
+     */
+    listEntries(body, traits) {
+        const lines = splitLines(body);
+        const byId = new Map();
+        const unreadable = [];
+        const order = [];
+        lines.forEach((line, index) => {
+            const path = tomlHeaderPath(line.text);
+            if (path === undefined || path.length !== 2 || path[0] !== traits.mcpContainerKey)
+                return;
+            const id = path[1];
+            // A second `[<container>.<id>]` is the document's own ambiguity, and
+            // `entryConflict` is what names it; reading either copy would be picking.
+            if (byId.has(id))
+                return;
+            const entry = { native: {}, foreignKeys: [] };
+            byId.set(id, entry);
+            order.push(id);
+            for (let scan = index + 1; scan < lines.length; scan += 1) {
+                const text = lines[scan].text;
+                if (startsTable(text))
+                    break;
+                const trimmed = text.trim();
+                if (trimmed === '' || trimmed.startsWith('#'))
+                    continue;
+                const key = tomlAssignmentPath(text);
+                const equals = text.indexOf('=');
+                if (key === undefined || key.length !== 1 || equals < 0) {
+                    // LOCATED, never quoted (`document-fault.ts`). This echoed the line
+                    // itself until M17.A, and a line of a vendor config is a line that can
+                    // hold an API token — the same hazard as a parser message, reached
+                    // through brambo's OWN prose rather than through V8's.
+                    unreadable.push({
+                        id,
+                        detail: `'${traits.mcpContainerKey}.${id}' holds a line brambo cannot read as one 'key = value' assignment, at ${positionOf(body, lines[scan].start)}`,
+                    });
+                    byId.delete(id);
+                    order.splice(order.indexOf(id), 1);
+                    break;
+                }
+                const raw = text.slice(equals + 1).trim();
+                let parsed;
+                try {
+                    parsed = JSON.parse(raw);
+                }
+                catch {
+                    // The value is NAMED by its key, never reproduced — the shape the
+                    // JSONC reporter above already uses ("holds a value brambo cannot
+                    // read…"), and the reason it never leaked while this one did. Measured
+                    // at 4232e9c: `brambo ingest --dry-run` printed a planted credential
+                    // verbatim out of `config.toml` through this interpolation.
+                    unreadable.push({
+                        id,
+                        detail: `'${traits.mcpContainerKey}.${id}.${key[0]}' holds a value brambo cannot read, because it is not spelled the way brambo renders one; brambo reports it rather than guessing what it means, at ${positionOf(body, lines[scan].start + equals + 1)}`,
+                    });
+                    byId.delete(id);
+                    order.splice(order.indexOf(id), 1);
+                    break;
+                }
+                if (typeof parsed === 'string')
+                    entry.native[key[0]] = parsed;
+                else if (Array.isArray(parsed) && parsed.every((item) => typeof item === 'string')) {
+                    entry.native[key[0]] = parsed;
+                }
+                else
+                    entry.foreignKeys.push(key[0]);
+            }
+        });
+        // A `[<container>.<id>.<sub>]` table ends the region scan above, so its keys
+        // would otherwise disappear in silence. It is one of the keys brambo cannot
+        // represent, and D10 says those are reported.
+        for (const line of lines) {
+            const path = tomlHeaderPath(line.text);
+            if (path === undefined || path.length < 3 || path[0] !== traits.mcpContainerKey)
+                continue;
+            byId.get(path[1])?.foreignKeys.push(path.slice(2).join('.'));
+        }
+        return {
+            entries: order.map((id) => ({ id, native: byId.get(id).native, foreignKeys: byId.get(id).foreignKeys })),
+            unreadable,
+        };
+    },
+    canonical(ownedText) {
+        return ownedText
+            .split('\n')
+            .map((line) => {
+            const trimmed = line.trim();
+            const header = tomlHeaderPath(trimmed);
+            // Re-spell the header from its decoded path so `[ a."b" ]` and `[a.b]`
+            // hash the same.
+            return header === undefined ? trimmed : `[${header.map(tomlBareKey).join('.')}]`;
+        })
+            .filter((line) => line !== '')
+            .join('\n');
+    },
+    upsert(body, style, traits, entry, existing) {
+        const owned = renderTomlTable(traits, entry, style);
+        if (existing !== undefined) {
+            return { start: existing.start, end: existing.end, replacement: owned, owned };
+        }
+        // Appended at EOF, after ensuring the foreign tail keeps its own trailing
+        // newline and exactly one blank line separates brambo's table from it.
+        const separator = body === '' ? '' : body.endsWith(style.eol) ? style.eol : `${style.eol}${style.eol}`;
+        return { start: body.length, end: body.length, replacement: `${separator}${owned}`, owned };
+    },
+    remove(body, style, existing) {
+        const separator = style.eol + style.eol;
+        const hasSeparator = existing.start >= separator.length &&
+            body.slice(existing.start - separator.length, existing.start) === separator;
+        return { start: hasSeparator ? existing.start - style.eol.length : existing.start, end: existing.end };
+    },
+    reclaimContainer() {
+        // TOML tables are independent definitions; removing one leaves no container.
+        return undefined;
+    },
+};
+const FORMAT_STRATEGIES = {
+    jsonc: JSONC_STRATEGY,
+    toml: TOML_STRATEGY,
+};
+/**
+ * Every MCP server one vendor's own config file declares, or `undefined` when
+ * there is no such file.
+ *
+ * ABSENCE IS NOT FAILURE (AD-5): an executor is allowed not to be installed, so
+ * a missing `~/.codex/config.toml` contributes nothing and is not an error.
+ * Everything else is coded and names the path — a malformed document, a
+ * container holding something brambo cannot address, a file brambo may not read.
+ */
+export async function readNativeMcpEntries(traits, options = {}) {
+    const filePath = options.filePath ?? traits.defaultPath;
+    let nativeText;
+    try {
+        nativeText = await readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR' || code === 'EISDIR')
+            return undefined;
+        // Reported, not thrown. D2/AD-5 let an executor be unusable, and a file
+        // brambo may not open is closer to absent than to malformed — but it is not
+        // absent either, and silence would tell a user their servers were considered
+        // when they never were.
+        return { filePath, entries: [], unreadable: [], unreadableFile: code ?? String(error) };
+    }
+    const strategy = FORMAT_STRATEGIES[traits.fileFormat];
+    const body = nativeText.startsWith(BYTE_ORDER_MARK) ? nativeText.slice(1) : nativeText;
+    // The merge SEEDS a whitespace-only JSON document to `{}` so entries can be
+    // added to it. There is nothing in one to read, and validating it would call
+    // an empty file malformed — which it is not.
+    if (traits.fileFormat === 'jsonc' && body.trim() === '') {
+        return { filePath, entries: [], unreadable: [] };
+    }
+    strategy.validate(body, filePath, traits);
+    const conflict = strategy.containerConflict(body, traits);
+    if (conflict !== undefined)
+        throw nativeUnclaimable(filePath, conflict);
+    const rendered = renderedKeys(traits);
+    const listing = strategy.listEntries(body, traits);
+    const entries = [];
+    const unreadable = [...listing.unreadable];
+    for (const candidate of listing.entries) {
+        const ambiguous = strategy.entryConflict(body, traits, candidate.id);
+        if (ambiguous !== undefined) {
+            unreadable.push({ id: candidate.id, detail: ambiguous });
+            continue;
+        }
+        // A key the renderer DOES emit, holding a value no `NativeEntryShape` can
+        // carry (`args: ['ok', 7]`), is a value brambo cannot READ — not a key brambo
+        // cannot hold. Reporting it as dropped would silently lose the arguments of
+        // a server brambo then went on to project, and would blame the wrong thing.
+        const unreadableValues = candidate.foreignKeys.filter((key) => rendered.includes(key));
+        if (unreadableValues.length > 0) {
+            unreadable.push({
+                id: candidate.id,
+                detail: `'${unreadableValues.join("', '")}' holds a value brambo cannot read as a string or a list of strings, and brambo will not project a server it read only half of`,
+            });
+            continue;
+        }
+        const read = traits.readMcpEntry(candidate.native);
+        if (!read.ok) {
+            unreadable.push({ id: candidate.id, detail: read.detail });
+            continue;
+        }
+        entries.push({
+            id: candidate.id,
+            command: read.command,
+            args: read.args,
+            // Everything the renderer does not emit, whatever its value type: a user
+            // reading this wants what did not travel, not which layer noticed.
+            dropped: [...new Set([...droppedNativeKeys(candidate.native, rendered), ...candidate.foreignKeys])].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)),
+        });
+    }
+    return { filePath, entries, unreadable };
+}
+// --- correction-01 C6: brambo's own prior output ------------------------------
+//
+// Stories 2.2 and 2.3 wrote brambo's OWN vocabulary into vendor files: a reserved
+// `$.brambo` root key in the JSON family, and a `# BEGIN brambo-managed` block in
+// Codex's TOML. Not one byte of it is read by any executor, and the Codex form
+// is actively harmful — foreign sub-keys inside `[tools]` and `[skills]` make
+// the user's whole `config.toml` fail to load under the documented
+// `--strict-config`. correction-01 C6 makes removing it part of the correction.
+//
+// The corrected build cannot reach that state itself, so this is a LOCATOR, not
+// a drift verdict: it finds brambo's own litter on a machine that ran a previous
+// build, and the `discard` remediation removes exactly the region it names. One
+// function, used by the report and by the act — a second locator could describe
+// a region other than the one removed, which is the whole reason `brambo doctor`
+// is an inspection mode rather than a copy.
+/** The legacy marker the TOML form opens with; also how a reader recognises it. */
+const LEGACY_TOML_BEGIN = '# BEGIN brambo-managed';
+const LEGACY_TOML_END = '# END brambo-managed';
+/** The JSON-family root key a previous build reserved for itself. */
+const LEGACY_JSON_KEY = 'brambo';
+/**
+ * The sub-keys the invalidated builds wrote under the reserved root key, from
+ * correction-01's own evidence table (`$.brambo.{tools,mcpServers,skills,hooks}`,
+ * plus the grammar version those builds stamped).
+ *
+ * This list is what makes the JSON side EVIDENCE rather than a name match. A key
+ * called `brambo` proves nothing — it is a name a user may have chosen, and AD-6
+ * is explicit that ownership is never inferred, with a bare key name weaker than
+ * the path AD-6 already rules out. So brambo claims the key only when its VALUE
+ * is an object whose every member is vocabulary a brambo build wrote. Anything
+ * else is somebody's own configuration: not reported, not removed.
+ */
+const LEGACY_JSON_MEMBERS = new Set(['version', 'tools', 'mcpServers', 'skills', 'hooks']);
+/** Whether this `brambo` value is one a previous brambo build wrote. */
+function isLegacyBramboValue(node) {
+    if (node === undefined || node.type !== 'object')
+        return false;
+    const members = (node.children ?? []).map((property) => property.children?.[0]?.value);
+    if (members.length === 0)
+        return false;
+    return members.every((name) => typeof name === 'string' && LEGACY_JSON_MEMBERS.has(name));
+}
+function scanLegacyJson(body, shift) {
+    const root = parseTree(body);
+    if (root === undefined || root.type !== 'object') {
+        // Not a refusal to report loudly: a file with no object root never held the
+        // reserved key, because the build that wrote it spliced into an object.
+        return {};
+    }
+    const properties = memberProperties(root, LEGACY_JSON_KEY);
+    const property = properties[0];
+    if (property === undefined)
+        return {};
+    // Somebody's own `brambo` key. Silence is the only correct answer: reporting it
+    // would put a `problem` on the exit code for a state brambo invented, and the
+    // detail would assert a provenance brambo cannot know.
+    if (!properties.some((candidate) => isLegacyBramboValue(candidate.children?.[1])))
+        return {};
+    if (properties.length > 1) {
+        return {
+            refusal: `'${LEGACY_JSON_KEY}' is declared ${properties.length} times; brambo will not guess which of them it wrote. Leave one and re-run, or remove the block by hand`,
+        };
+    }
+    const span = jsonRemovalSpan(body, { start: property.offset, end: property.offset + property.length });
+    return {
+        block: {
+            start: span.start + shift,
+            end: span.end + shift,
+            detail: `the reserved '$.${LEGACY_JSON_KEY}' key a previous brambo build wrote — every member of it is brambo's own vocabulary and no executor reads any of it`,
+        },
+    };
+}
+/** The two TOML multi-line string fences, spelled without a literal triple quote. */
+const TOML_FENCES = ['"'.repeat(3), "'".repeat(3)];
+/**
+ * The lines that are real TOML lines rather than the interior of a multi-line
+ * string.
+ *
+ * A `# BEGIN brambo-managed` inside a multi-line value is three of the USER's own
+ * bytes, and matching it deleted them — measured. Brambo never PARSES foreign
+ * TOML and this does not start: it tracks only the two multi-line fences, which
+ * is the whole of what can hide a line-initial `#`. A line inside an open fence
+ * is invisible to the marker scan.
+ *
+ * ponytail: fence counting, not a lexer. A fence sequence inside a single-line
+ * basic string would desynchronise it, and the failure direction is that brambo
+ * stops recognising its OWN block and reports nothing — the safe one. Upgrade
+ * path: a real TOML lexer, worth it only if a legacy block is ever found in a
+ * file shaped like that.
+ */
+function tomlCodeLines(lines) {
+    const code = [];
+    let open;
+    for (const line of lines) {
+        if (open === undefined)
+            code.push(line);
+        let rest = line.text;
+        for (;;) {
+            if (open === undefined) {
+                const found = TOML_FENCES.map((fence) => ({ fence, at: rest.indexOf(fence) }))
+                    .filter((candidate) => candidate.at >= 0)
+                    .sort((a, b) => a.at - b.at)[0];
+                if (found === undefined)
+                    break;
+                open = found.fence;
+                rest = rest.slice(found.at + found.fence.length);
+                continue;
+            }
+            const closes = rest.indexOf(open);
+            if (closes < 0)
+                break;
+            rest = rest.slice(closes + open.length);
+            open = undefined;
+        }
+    }
+    return code;
+}
+function scanLegacyToml(body, shift) {
+    const lines = tomlCodeLines(splitLines(body));
+    const begins = lines.filter((line) => line.text.trimStart().startsWith(LEGACY_TOML_BEGIN));
+    if (begins.length === 0) {
+        // An END with no BEGIN is a hand-edited remnant brambo cannot bound.
+        return lines.some((line) => line.text.trimStart().startsWith(LEGACY_TOML_END))
+            ? { refusal: `'${LEGACY_TOML_END}' appears with no '${LEGACY_TOML_BEGIN}' before it; brambo cannot tell where the block starts. Remove what is left of it by hand` }
+            : {};
+    }
+    if (begins.length > 1) {
+        return { refusal: `'${LEGACY_TOML_BEGIN}' appears ${begins.length} times; brambo will not guess which block is which. Leave one and re-run, or remove them by hand` };
+    }
+    const begin = begins[0];
+    const end = lines.find((line) => line.start >= begin.start && line.text.trimStart().startsWith(LEGACY_TOML_END));
+    if (end === undefined) {
+        return { refusal: `'${LEGACY_TOML_BEGIN}' has no matching '${LEGACY_TOML_END}'; brambo cannot tell where the block ends. Remove what is left of it by hand` };
+    }
+    // Symmetric with how a TOML region brambo owns is taken back today
+    // (`TOML_STRATEGY.remove`): one blank line separated the appended block from
+    // the foreign tail, and removing the block without it leaves that blank behind
+    // in every file a previous build wrote one into.
+    const eol = lineEndingOf(body);
+    const separator = eol + eol;
+    const separated = begin.start >= separator.length &&
+        body.slice(begin.start - separator.length, begin.start) === separator;
+    const start = separated ? begin.start - eol.length : begin.start;
+    return {
+        block: {
+            start: start + shift,
+            end: end.end + shift,
+            detail: `the '${LEGACY_TOML_BEGIN}' block a previous brambo build wrote, whose sub-keys under '[tools]' and '[skills]' make this file fail to load under --strict-config`,
+        },
+    };
+}
+/**
+ * Brambo's own prior output in one vendor file, if any is there.
+ *
+ * READS ONLY. `brambo doctor` calls it to report the state and the `discard`
+ * remediation calls it to remove exactly the region it returns.
+ */
+export function scanLegacyBramboBlock(nativeText, fileFormat) {
+    const hasBom = nativeText.startsWith(BYTE_ORDER_MARK);
+    const body = hasBom ? nativeText.slice(1) : nativeText;
+    const shift = hasBom ? 1 : 0;
+    return fileFormat === 'toml' ? scanLegacyToml(body, shift) : scanLegacyJson(body, shift);
+}
+// --- registry -> native entries ---------------------------------------------
+function byId(a, b) {
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+/**
+ * Reduces the registry to the MCP servers every target can express, in stable
+ * id order. Kinds this story does not project (skills) and MCP
+ * entries with no command are REPORTED through skippedEntryIds rather than
+ * approximated into something no executor reads — Stories 2.9 and 2.10 own
+ * those concepts. `present` is EVERY mcp-server id the registry holds,
+ * including the ones brambo cannot render: removal authority comes from absence
+ * in the registry, never from unprojectability.
+ */
+function collectMcpEntries(entries) {
+    const skipped = [];
+    // Every DECLARED kind this format has no native location for — derived, so a
+    // word added to or removed from `REGISTRY_ENTRY_TYPES` cannot leave a stale
+    // literal here. (A RETIRED kind never arrives: `groupByKind` has no bucket for
+    // one, so it is dropped before any target is asked about it.)
+    for (const kind of REGISTRY_ENTRY_TYPES.filter((candidate) => candidate !== 'mcp-server')) {
+        for (const entry of entries[kind])
+            skipped.push(entry.id);
+    }
+    const mcp = [];
+    const present = new Set();
+    let previousId;
+    for (const entry of [...entries['mcp-server']].sort(byId)) {
+        // Defense in depth: the Registry already rejects duplicate type+id pairs
+        // and unprojectable ids, so reaching either branch means a hand-edited or
+        // corrupted store — which must fail coded, never silently collapse two
+        // entries into one native location or address one through a prototype key.
+        if (UNPROJECTABLE_ENTRY_IDS.has(entry.id)) {
+            throw new BramboError(BRAMBO_ERROR_CODES.registryInvalidEntry, `registry mcp-server entry '${entry.id}' cannot be used as a native config key`);
+        }
+        if (previousId === entry.id) {
+            throw new BramboError(BRAMBO_ERROR_CODES.registryContention, `duplicate registry mcp-server entries '${entry.id}': two entries with the same id cannot both be projected`);
+        }
+        previousId = entry.id;
+        present.add(entry.id);
+        if (entry.command === undefined) {
+            // Reported, and LEFT ALONE on disk. Treating "brambo cannot render this"
+            // as "the user deleted it" would delete a registered server from every
+            // config the moment its command went missing.
+            skipped.push(entry.id);
+            continue;
+        }
+        mcp.push({ id: entry.id, command: entry.command, args: [...(entry.args ?? [])] });
+    }
+    return { mcp, present, skippedEntryIds: skipped.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)) };
+}
+// --- the merge --------------------------------------------------------------
+function drifted(kind, traits, entryId, detail) {
+    return { kind, entryId, location: `${traits.mcpContainerKey}.${entryId}`, detail };
+}
+function nativeLocationOf(traits, entryId) {
+    return `${traits.mcpContainerKey}.${entryId}`;
+}
+function mergeNative(request, filePath, traits) {
+    const strategy = FORMAT_STRATEGIES[traits.fileFormat];
+    // A leading BOM is foreign state: stripped for parsing, re-prepended to the
+    // output so it survives every projection byte-intact.
+    const hasBom = request.nativeText.startsWith(BYTE_ORDER_MARK);
+    const nativeBody = hasBom ? request.nativeText.slice(1) : request.nativeText;
+    // A missing or whitespace-only JSON file has no document to splice into, so
+    // the projection IS the file; TOML needs no seed because a table appends to
+    // anything.
+    const seeded = traits.fileFormat === 'jsonc' && nativeBody.trim() === '';
+    let body = seeded ? '{}' : nativeBody;
+    strategy.validate(body, filePath, traits);
+    const style = { eol: lineEndingOf(nativeBody), unit: indentationUnitOf(nativeBody) };
+    const { mcp, present, skippedEntryIds } = collectMcpEntries(request.entries);
+    // A record is authority ONLY for its own key. A stale record from a build
+    // that used a different container key, another target, or another file must
+    // never authorise an overwrite or a deletion here.
+    const ownedPath = resolveOwnedPath(filePath);
+    const authoritative = request.records.filter((record) => record.targetId === traits.targetId &&
+        sameOwnedPath(resolveOwnedPath(record.filePath), ownedPath) &&
+        record.nativeLocation === nativeLocationOf(traits, record.entryId));
+    const claimed = new Map(authoritative.map((record) => [record.entryId, record]));
+    const unchanged = (drift) => ({
+        text: request.nativeText,
+        drift,
+        skippedEntryIds,
+        records: authoritative,
+        ownedSpans: [],
+    });
+    const conflict = strategy.containerConflict(body, traits);
+    if (conflict !== undefined) {
+        const affected = [...new Set([...mcp.map((entry) => entry.id), ...claimed.keys()])].sort();
+        return unchanged(affected.map((entryId) => drifted('foreign-collision', traits, entryId, `${conflict}; brambo will not touch '${entryId}' in '${filePath}'`)));
+    }
+    const drift = [];
+    const records = [];
+    const spans = [];
+    let removed = 0;
+    const applySplice = (start, end, replacement) => {
+        body = body.slice(0, start) + replacement + body.slice(end);
+        const delta = replacement.length - (end - start);
+        // A later entry can land INSIDE a span brambo already owns — the second
+        // entry going into a container the first one created. Such a splice grows
+        // the enclosing span instead of adding an overlapping one. Only a NON-EMPTY
+        // span can enclose: a removal's zero-width span must never swallow a later
+        // insertion's own span and leave the verification surface empty.
+        const enclosing = spans.find((span) => span[1] > span[0] && span[0] <= start && end <= span[1]);
+        for (const span of spans) {
+            if (span[0] >= end) {
+                span[0] += delta;
+                span[1] += delta;
+            }
+            else if (span === enclosing) {
+                span[1] += delta;
+            }
+        }
+        if (enclosing === undefined && replacement.length > 0) {
+            spans.push([start, start + replacement.length]);
+        }
+    };
+    const stillBrambos = (record, region) => hashOwnedText(strategy.canonical(body.slice(region.start, region.end))) === record.contentHash;
+    // 1. Entries absent from the REGISTRY: remove exactly the ledger-recorded
+    //    region, and only while it still hashes to what brambo wrote.
+    const renderable = new Set(mcp.map((entry) => entry.id));
+    for (const record of [...authoritative].sort((a, b) => (a.entryId < b.entryId ? -1 : 1))) {
+        if (present.has(record.entryId)) {
+            // Still registered but not renderable this run: keep the claim, or the
+            // next run would see its own entry as foreign and never manage it again.
+            if (!renderable.has(record.entryId))
+                records.push(record);
+            continue;
+        }
+        const entryBlocked = strategy.entryConflict(body, traits, record.entryId);
+        if (entryBlocked !== undefined) {
+            drift.push(drifted('foreign-collision', traits, record.entryId, `${entryBlocked} in '${filePath}'`));
+            records.push(record);
+            continue;
+        }
+        const existing = strategy.locate(body, traits, record.entryId);
+        if (existing === undefined)
+            continue;
+        if (!stillBrambos(record, existing)) {
+            drift.push(drifted('edited', traits, record.entryId, `'${record.entryId}' in '${filePath}' has been edited since brambo wrote it; brambo will not remove it`));
+            records.push(record);
+            continue;
+        }
+        const removal = strategy.remove(body, style, existing);
+        applySplice(removal.start, removal.end, '');
+        removed += 1;
+    }
+    // 2. Entries the registry holds. Brambo writes only where it already owns the
+    //    location or where the location is provably free; everything else is
+    //    reported and left alone.
+    for (const entry of mcp) {
+        const record = claimed.get(entry.id);
+        const entryBlocked = strategy.entryConflict(body, traits, entry.id);
+        if (entryBlocked !== undefined) {
+            drift.push(drifted('foreign-collision', traits, entry.id, `${entryBlocked} in '${filePath}'`));
+            if (record !== undefined)
+                records.push(record);
+            continue;
+        }
+        const existing = strategy.locate(body, traits, entry.id);
+        if (record === undefined) {
+            if (existing !== undefined) {
+                // M11.A D4 case (ii): the CONFIG half of the SOURCE-IS-THE-DESTINATION
+                // verdict `materialise.ts` already reaches for a tree.
+                //
+                // Deciding `foreign-collision` from EXISTENCE alone made brambo report a
+                // conflict against a server that already does exactly what the registry
+                // asks, and M4.C's "every state has a way out" then offered two bad
+                // exits: adopt bytes brambo did not write, or delete the user's entry.
+                //
+                // THE QUESTION HERE IS ABOUT MEANING, NOT BYTES, and that is why this
+                // does NOT reuse `stillBrambos`. `stillBrambos` asks "are these the bytes
+                // brambo WROTE?", where a hash is the right instrument. This asks "does
+                // this FOREIGN entry already deliver what the registry says?", and a
+                // hash answers that only when the user happened to spell brambo's exact
+                // key set — measured by driving the binary: `{"command":"npx"}`, a
+                // missing `type`, and an entry carrying `env` each reported a collision
+                // while running precisely the right server. So the comparison is the
+                // trait's own INVERSE: read the native entry back and compare what runs.
+                // Keys brambo cannot represent are ignored rather than counted against
+                // it, which is the same answer the reader gives when it ingests such an
+                // entry and reports the key dropped — the two halves of the story now
+                // agree. Being value-based it is also format-independent by
+                // construction, so key order, spacing and comments stop mattering
+                // without a second canonicaliser to keep in step.
+                //
+                // ponytail: `listEntries` walks the whole container to answer about one
+                // id, so a merge is O(entries^2) in the container size. Vendor configs
+                // hold a handful of servers; upgrade path is a `readEntry(body, id)` on
+                // the strategy if a container ever grows big enough to measure.
+                const native = strategy.listEntries(body, traits).entries.find((item) => item.id === entry.id);
+                const read = native === undefined ? undefined : traits.readMcpEntry(native.native);
+                if (read?.ok === true &&
+                    read.command === entry.command &&
+                    read.args.length === entry.args.length &&
+                    read.args.every((argument, index) => argument === entry.args[index])) {
+                    // ALREADY SATISFIED: nothing written, nothing claimed, no drift.
+                    //
+                    // NOT ADOPTED, and that is the load-bearing half — the reason
+                    // `materialise.ts` gives for its twin holds verbatim here: brambo did
+                    // not write these bytes, so claiming them would hand the release
+                    // remediation an authority to delete a server the user owns. An
+                    // unclaimed entry is also never in the removal path above, which
+                    // needs a ledger record to reach.
+                    //
+                    // Degrades correctly in both directions: change what the entry RUNS
+                    // and it is a foreign collision again, which is true.
+                    continue;
+                }
+                drift.push(drifted('foreign-collision', traits, entry.id, `'${entry.id}' already exists in '${filePath}' and does not run what the registry says it should, and brambo's ledger does not claim it; brambo will not resolve the collision`));
+                continue;
+            }
+        }
+        else if (existing === undefined) {
+            drift.push(drifted('removed-by-user', traits, entry.id, `brambo wrote '${entry.id}' to '${filePath}' and it is gone; brambo will not re-add it`));
+            // The claim is KEPT: dropping it would make the next run treat the entry
+            // as never written and silently re-add what the user deleted.
+            records.push(record);
+            continue;
+        }
+        else if (!stillBrambos(record, existing)) {
+            drift.push(drifted('edited', traits, entry.id, `'${entry.id}' in '${filePath}' has been edited since brambo wrote it; brambo will not overwrite it`));
+            records.push(record);
+            continue;
+        }
+        const splice = strategy.upsert(body, style, traits, entry, existing);
+        applySplice(splice.start, splice.end, splice.replacement);
+        records.push({
+            targetId: traits.targetId,
+            filePath: ownedPath,
+            nativeLocation: nativeLocationOf(traits, entry.id),
+            entryId: entry.id,
+            contentHash: hashOwnedText(strategy.canonical(splice.owned)),
+        });
+    }
+    if (removed > 0) {
+        const reclaimable = strategy.reclaimContainer(body, traits);
+        if (reclaimable !== undefined)
+            applySplice(reclaimable.start, reclaimable.end, '');
+    }
+    // Nothing to write means nothing to create: a run with an empty registry must
+    // not conjure a config file the user never had.
+    if (seeded && spans.length === 0)
+        return unchanged(drift);
+    const text = hasBom ? BYTE_ORDER_MARK + body : body;
+    const bomShift = hasBom ? 1 : 0;
+    const ownedSpans = seeded
+        ? [[0, text.length]]
+        : spans
+            .filter((span) => span[1] > span[0])
+            .sort((a, b) => a[0] - b[0])
+            .map((span) => [span[0] + bomShift, span[1] + bomShift]);
+    return { text, drift, skippedEntryIds, records, ownedSpans };
+}
+/**
+ * What currently occupies ONE entry's native location, expressed as the ledger
+ * record that would claim it — the target's half of `adopt`.
+ *
+ * Every predicate below is the merge's own, called on the same text through the
+ * same strategy: `entryConflict` for a location the document spells twice,
+ * `locate` for the region, and `hashOwnedText(strategy.canonical(...))` for the
+ * hash. That is not tidiness. An adopted record whose hash were computed any
+ * other way would fail `stillBrambos` on the very next run and the entry would
+ * report `edited` forever — the exact state adoption exists to leave.
+ *
+ * Every failure is a REFUSAL rather than a throw. A malformed vendor file, an
+ * unclaimable container, a duplicated key: each is a reason brambo will not take
+ * ownership, and the caller has to be able to print it beside the entry.
+ */
+function claimNative(request, filePath, traits) {
+    const strategy = FORMAT_STRATEGIES[traits.fileFormat];
+    const location = nativeLocationOf(traits, request.entryId);
+    const refuse = (refusal) => ({ location, byteLength: 0, refusal });
+    if (UNPROJECTABLE_ENTRY_IDS.has(request.entryId)) {
+        return refuse(`'${request.entryId}' cannot be used as a native config key`);
+    }
+    const hasBom = request.nativeText.startsWith(BYTE_ORDER_MARK);
+    // NOT seeded to '{}' the way the merge seeds an empty document: seeding
+    // invents a document so entries can be ADDED to it, and there is nothing to
+    // adopt in a file that does not exist.
+    const body = hasBom ? request.nativeText.slice(1) : request.nativeText;
+    try {
+        strategy.validate(body, filePath, traits);
+    }
+    catch (error) {
+        return refuse(error instanceof Error ? error.message : String(error));
+    }
+    const conflict = strategy.containerConflict(body, traits) ?? strategy.entryConflict(body, traits, request.entryId);
+    // The refusal has to be ACTIONABLE. This is the shape where every brambo verb
+    // declines — `adopt` on the ambiguity, `release` because a foreign collision
+    // holds no claim to drop — so the sentence has to name the thing that does
+    // leave it, which is the user's own edit of their own file. Brambo's ledger is
+    // not involved and saying so is half the answer.
+    if (conflict !== undefined) {
+        return refuse(`${conflict}. Brambo holds no claim here, so no remediation applies: resolve the ambiguity in '${filePath}' itself and re-run`);
+    }
+    const existing = strategy.locate(body, traits, request.entryId);
+    if (existing === undefined)
+        return { location, byteLength: 0 };
+    const owned = body.slice(existing.start, existing.end);
+    return {
+        location,
+        byteLength: Buffer.byteLength(owned, 'utf8'),
+        // `ownedPaths` deliberately omitted: a config claim authorises replacing one
+        // REGION inside this file and can never remove the file, so there is no path
+        // a later run gains delete authority over.
+        record: {
+            targetId: traits.targetId,
+            filePath: resolveOwnedPath(filePath),
+            nativeLocation: location,
+            entryId: request.entryId,
+            contentHash: hashOwnedText(strategy.canonical(owned)),
+        },
+    };
+}
+/**
+ * The ONE factory every target flows through: adding a target means writing a
+ * trait record — no engine or strategy code changes. An unknown file format is
+ * a coded configuration error, not a crash at splice time.
+ */
+export function createProjectionTargetFromTraits(traits, options = {}) {
+    if (FORMAT_STRATEGIES[traits.fileFormat] === undefined) {
+        throw new BramboError(BRAMBO_ERROR_CODES.projectionTraitsInvalid, `projection target '${traits.targetId}' declares unknown fileFormat '${traits.fileFormat}'`);
+    }
+    const filePath = options.filePath ?? traits.defaultPath;
+    return {
+        targetId: traits.targetId,
+        filePath,
+        merge(request) {
+            return mergeNative(request, filePath, traits);
+        },
+        claim(request) {
+            return claimNative(request, filePath, traits);
+        },
+    };
+}