@skanl/brambo-projection 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SKANL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# @skanl/brambo-projection
+
+Projects Registry entries into executors' native configuration files, in each
+executor's OWN vocabulary at the location that executor actually reads (port
+defined in `@skanl/brambo-contracts`).
+
+- `runProjection` — engine: reads the ownership ledger, then runs each target
+  SEQUENTIALLY with per-target failure containment (a failing target never
+  affects siblings, and failures surface as typed results — the call does not
+  throw). The native file lands before the ledger records it, so a crash
+  between the two under-claims rather than over-claims. Single-writer
+  assumption: concurrent `runProjection` calls over the same projected file are
+  unsupported in v1; a file modified externally between read and write fails
+  that target instead of landing stale content.
+- `runRemediation` — the way OUT of a state projection reports and refuses to
+  resolve. Four verbs, one subject per call, and the SAME call describes and
+  performs (`mode: 'inspect' | 'apply'`, the engine's own switch), so a preview
+  cannot disagree with the act:
+  - `adopt` — brambo takes ownership of what is at its own location, exactly as
+    it is now. It writes only the ledger, and that is not the same as being
+    harmless: owning a location is what lets a LATER `runProjection` replace it,
+    and on a materialisation root REMOVE it. The description names every path
+    that becomes deletable and says which of the two will happen, before the
+    claim is written. A tree that is only partly there is claimed as the subset
+    that exists, so the ordinary run writes the rest back; an entry that has left
+    the registry is claimed from the ledger's own record, and the next run then
+    removes the tree. There is no verb that renders one entry outside the merge.
+  - `release` — brambo stops claiming a location. The file is not opened.
+  - `repair` — brambo rewrites its OWN ledger to hold exactly the records it can
+    read; the only write that does not merge, and the only exit from a ledger
+    carrying records it cannot use.
+  - `discard` — brambo removes its OWN prior output from a vendor file
+    (correction-01 C6): a reserved `$.brambo` key whose members are *all* brambo's
+    own vocabulary (`version`, `tools`, `mcpServers`, `skills`, `hooks`), or a
+    `# BEGIN brambo-managed` block whose sub-keys under `[tools]`/`[skills]` make
+    a Codex `config.toml` fail to load under `--strict-config`. A `brambo` key
+    holding anything else is somebody's own configuration: not reported, not
+    removed. A marker inside a multi-line TOML string is the user's bytes and is
+    invisible to the scan.
+
+  Containment is the materialisation rule unchanged: every path is resolved and
+  proven inside the location brambo owns, a link at any depth disqualifies it, and
+  a path another surviving claim holds is refused. `discard` checks the REAL
+  path, so a junctioned `~/.claude` cannot land the write outside the scope its
+  refusal promises. `adopt` builds its claim from the TARGET's plan of what brambo
+  would write — never from a directory listing — so a file a user put beside
+  brambo's is never swept into a record that could later authorise deleting it,
+  and both ledger verbs write ONE entry through `updateEntry` rather than
+  replacing a scope from a read they took earlier. A remediation brambo will not
+  perform is returned as a coded `BRAMBO_PROJECTION_REMEDIATION_REFUSED`, not
+  thrown, because under inspection the refusal is part of the description.
+
+  `runRemediation` defaults to `mode: 'inspect'` — the opposite of
+  `runProjection`, and the same default `brambo remediate` uses, so the
+  describe-before-act guarantee is true of the SDK surface and of the command.
+- `ProjectionLedger` — brambo's durable record of what it wrote (target, file,
+  native location, content hash), in `~/.brambo/projection-ledger.json`. Brambo
+  never marks a vendor's file to prove ownership: a marker has nowhere to live
+  in some formats and is an unknown field in others. Writes MERGE one target's
+  claims into the on-disk document; an unreadable ledger is reported and left
+  alone, never overwritten.
+- `createClaudeMcpTarget` — `mcpServers` in `~/.claude.json` (or `.mcp.json`
+  for project scope), `{type:'stdio', command, args}`.
+- `createOpenCodeConfigTarget` — `mcp.<id>` in `opencode.json`,
+  `{type:'local', command: argv}`.
+- `createCodexConfigTarget` — `[mcp_servers.<id>]` in `config.toml`, `command`
+  and `args` only, so `--strict-config` has nothing to reject.
+
+Ledger records, native-entry and drift vocabulary live in `@skanl/brambo-contracts`
+(`src/projection.ts`). Drift is a ledger-versus-disk comparison — `edited`,
+`removed-by-user`, `foreign-collision` — and is always reported, never resolved
+by writing.
+
+- `createClaudeSkillsTarget` / `createCodexSkillsTarget` /
+  `createOpenCodeSkillsTarget` — materialisation targets: they own a ROOT and
+  copy each registry skill's `entryPath` to `<root>/<id>/SKILL.md`. Brambo
+  copies; it never authors skill content.
+
+## Where skills land, and what each executor really reads
+
+Verified by EXECUTION against each installed binary under an injected home
+(`test/skills-discovery.live.test.ts`), not by reading a document.
+
+| Executor | Brambo writes | How it was verified |
+| --- | --- | --- |
+| claude-code | `~/.claude/skills/<id>/SKILL.md` | the request claude sends lists it in its own available-skills block |
+| codex | `~/.codex/skills/<id>/SKILL.md` | `codex debug prompt-input` names the file by absolute path |
+| opencode | `~/.config/opencode/skills/<id>/SKILL.md` | `opencode debug skill` reports that exact `location` |
+
+**OpenCode reads four roots, and brambo does not write into the one that wins.**
+Measured: `~/.config/opencode/skills`, `~/.config/opencode/skill`,
+`~/.opencode/skills` and `~/.opencode/skill` are all scanned, and with the same
+skill id present in two of them `~/.opencode/skills` silently takes precedence
+while `brambo init` and `brambo doctor` still report brambo's own write as done.
+Brambo writes one root per executor and claims nothing about precedence between
+them. OpenCode additionally scans `~/.claude/skills` and `~/.agents/skills`, so
+a skill brambo materialises for Claude Code is visible to opencode too.
+
+**Brambo's registry id is not necessarily the name the executor shows.** Claude
+Code takes the skill's name from the DIRECTORY, while codex and opencode take
+it from the source's frontmatter `name:`. A registry entry whose id differs
+from its source's frontmatter therefore appears under two different names, and
+brambo's ledger, `init` and `doctor` all name the registry id.
+
+Entries no target can express are still reported rather than approximated
+(`skippedEntryIds`, plus the target's own reason in `skipped`): a `skill` is not
+expressible by a CONFIG target, and an `mcp-server` with no command has nothing
+to render. A RETIRED type never reaches a target at all — `groupByKind` has no
+bucket for one — so it is neither projected nor reported here; `brambo doctor`
+reports it against the registry document instead. Skills at PROJECT scope are
+reported the same way — materialising into a project is a decision no story has
+taken, so brambo invents no location.

package/dist/atomic-write.d.ts

@@ -0,0 +1,3 @@
+export declare function atomicWriteText(path: string, contents: string): Promise<void>;
+/** The same discipline for a file brambo COPIES rather than renders. */
+export declare function atomicWriteBytes(path: string, contents: Uint8Array): Promise<void>;

package/dist/atomic-write.js

@@ -0,0 +1,90 @@
+import { randomUUID } from 'node:crypto';
+import { chmod, lstat, mkdir, realpath, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { BRAMBO_ERROR_CODES, BramboError } from '@skanl/brambo-contracts';
+// Atomic persistence for target files: temp file in the same directory, then
+// rename over the target. Atomicity here means reader visibility (readers only
+// ever observe a complete document) and crash-safe replacement — NOT
+// durability: like the Registry store, there is a power-loss window after
+// rename with no fsync; that deferral is tracked as deferred work.
+//
+// The previous file's permissions are copied onto the temp file before the
+// rename so a projection never widens or narrows the target's mode.
+//
+// SYMLINKS ARE FOLLOWED, NEVER REPLACED. `~/.claude.json -> ~/dotfiles/claude.json`
+// is the ordinary way people keep these files in a repo, and rename() over a
+// symlink destroys the link and orphans the source: every later edit in the
+// dotfiles repo goes nowhere, `git status` there shows nothing, and brambo exits
+// 0. So the link is resolved first and the rename lands on the real file. A link
+// that cannot be resolved — dangling, a cycle — is a coded refusal, because the
+// only alternative is to materialise a regular file where the user put a link.
+async function priorMode(path) {
+    try {
+        return (await stat(path)).mode;
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * The real file the write must land on. Identity for a regular file or an
+ * absent one; the link's destination for a symlink.
+ */
+async function writeTargetOf(path) {
+    let link;
+    try {
+        link = (await lstat(path)).isSymbolicLink();
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return path;
+        throw error;
+    }
+    if (!link)
+        return path;
+    try {
+        return await realpath(path);
+    }
+    catch (error) {
+        const detail = error?.code ?? String(error);
+        throw new BramboError(BRAMBO_ERROR_CODES.projectionNativeUnclaimable, `native config file '${path}' is a symlink brambo cannot resolve (${detail}); refusing to replace the link with a regular file`, { cause: error });
+    }
+}
+async function atomicWrite(path, contents) {
+    const target = await writeTargetOf(path);
+    const dir = dirname(target);
+    await mkdir(dir, { recursive: true });
+    const mode = await priorMode(target);
+    const tempPath = join(dir, `${basename(target)}.${randomUUID()}.tmp`);
+    try {
+        // `utf8` applies to the string form alone; a Uint8Array is written verbatim,
+        // which is what a materialised file needs — brambo copies bytes it did not
+        // author and must not re-encode them.
+        await writeFile(tempPath, contents, typeof contents === 'string' ? 'utf8' : undefined);
+        if (mode !== undefined)
+            await chmod(tempPath, mode);
+        await rename(tempPath, target);
+    }
+    catch (error) {
+        await unlink(tempPath).catch(() => { });
+        // Rethrown RAW, deliberately. `toTargetFailure` in `engine.ts` wraps a raw
+        // error as `BRAMBO_PROJECTION_TARGET_FAILED` and passes a `BramboError`
+        // through unchanged, so every projection caller already receives a coded
+        // failure and `doctor` classifies this state from that code. Coding it here
+        // was tried and reverted: it changed the code doctor sees, and the "bare
+        // errno reaches a caller" defect it was meant to fix does not exist for any
+        // caller that goes through the engine. A caller that does NOT — brambo's own
+        // config writer — codes it at its own boundary, where the right vocabulary
+        // is a configuration one rather than a projection one.
+        throw error;
+    }
+}
+export async function atomicWriteText(path, contents) {
+    await atomicWrite(path, contents);
+}
+/** The same discipline for a file brambo COPIES rather than renders. */
+export async function atomicWriteBytes(path, contents) {
+    await atomicWrite(path, contents);
+}

package/dist/config-write.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The keys brambo will persist — an ALLOWLIST, not a suggestion.
+ *
+ * The two literals are spelled here rather than imported: this package cannot
+ * reach '@skanl/brambo-adapter-cli' (which owns EXECUTOR_CONFIG_KEY) under AD-2, and
+ * importing '@skanl/brambo-contracts' for METHOD_CONFIG_KEY alone would make one of the
+ * pair look canonical while the other stayed a literal. Both are duplicated, and
+ * this comment is why.
+ *
+ * Key-agnostic is not unconstrained. A key brambo does not read is a value
+ * written once and ignored forever, which is the same defect as a registry type
+ * nothing projects: M4.E's rule, applied to configuration. `method` arrived
+ * with M5.D, in the same change that taught brambo to read and mount one.
+ */
+export declare const WRITABLE_CONFIG_KEYS: readonly ['executor', 'method'];
+export type WritableConfigKey = (typeof WRITABLE_CONFIG_KEYS)[number];
+export interface ConfigWriteOptions {
+    /** `machine` writes the `global` layer's document; `project` writes the project's. */
+    readonly scope: 'machine' | 'project';
+    readonly homeDir: string;
+    /** Required for the project scope; ignored for the machine one. */
+    readonly projectDir?: string;
+    readonly key: WritableConfigKey;
+    readonly value: string;
+}
+export interface ConfigWriteResult {
+    readonly filePath: string;
+    /** What the key said before, so a caller can tell a change from a no-op. */
+    readonly previous: string | undefined;
+    /** True when the document did not exist and this call created it. */
+    readonly created: boolean;
+}
+/** `<root>/.brambo/config.json` for the scope this call names. */
+export declare function configPathFor(options: Pick<ConfigWriteOptions, 'scope' | 'homeDir' | 'projectDir'>): string;
+/**
+ * Sets ONE allowlisted key in brambo's own configuration document.
+ *
+ * Every other key is carried through untouched: these documents hold the
+ * workspace root beside the executor selection, and a writer that serialises
+ * only what it was handed silently deletes the rest.
+ *
+ * The write goes through `@skanl/brambo-projection`'s `atomicWriteText` rather than a
+ * local temp-then-rename, because this exact file is the one dotfile managers
+ * materialise as a symlink and it is the only writer in this repository that
+ * resolves the link instead of replacing it. The cost is that a refusal arrives
+ * as a `BRAMBO_PROJECTION_*` code out of a configuration verb; that is recorded
+ * in `deferred-work.md` and it is cheaper than a second copy of the symlink rule.
+ */
+export declare function setConfigValue(options: ConfigWriteOptions): Promise<ConfigWriteResult>;

package/dist/config-write.js

@@ -0,0 +1,146 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { BRAMBO_ERROR_CODES, BramboError } from '@skanl/brambo-contracts';
+import { atomicWriteText } from './atomic-write.js';
+import { strictFaultLocation } from './document-fault.js';
+// The write half of brambo's OWN configuration. `brambo run --help` has always
+// told the user where the executor selection comes from and never how a value
+// gets there, because nothing in the product wrote one: `packages/session`
+// reads these documents four times and writes them zero. The answer brambo gave
+// a user who wanted a different default was "edit this JSON", which is the one
+// answer the product exists to remove.
+//
+// KEY-AGNOSTIC ON PURPOSE. This is "set one key in brambo's own configuration
+// document", not "set the executor". Story 5.4 persists a `method` selection
+// into the same documents with the same layer semantics and the same symlink
+// hazard, and a second writer is a second place to get the symlink rule wrong.
+// `<homeDir>/.brambo/config.json` is the `global` layer and
+// `<projectDir>/.brambo/config.json` is the `project` layer, resolved by
+// `readExecutorConfigLayers` in `@skanl/brambo-session`.
+//
+// ponytail: `.brambo/config.json` is spelled here rather than imported from
+// `@skanl/brambo-session`, which spells it too and carries the same note. AD-2 forbids
+// the edge, and it would exist only to share two string literals.
+const BRAMBO_STATE_DIR = '.brambo';
+const CONFIG_FILE = 'config.json';
+/**
+ * The keys brambo will persist — an ALLOWLIST, not a suggestion.
+ *
+ * The two literals are spelled here rather than imported: this package cannot
+ * reach '@skanl/brambo-adapter-cli' (which owns EXECUTOR_CONFIG_KEY) under AD-2, and
+ * importing '@skanl/brambo-contracts' for METHOD_CONFIG_KEY alone would make one of the
+ * pair look canonical while the other stayed a literal. Both are duplicated, and
+ * this comment is why.
+ *
+ * Key-agnostic is not unconstrained. A key brambo does not read is a value
+ * written once and ignored forever, which is the same defect as a registry type
+ * nothing projects: M4.E's rule, applied to configuration. `method` arrived
+ * with M5.D, in the same change that taught brambo to read and mount one.
+ */
+export const WRITABLE_CONFIG_KEYS = ['executor', 'method'];
+function unusable(filePath, detail, cause) {
+    return new BramboError(BRAMBO_ERROR_CODES.configurationUnusable, `brambo will not write '${filePath}' because ${detail}`, cause === undefined ? undefined : { cause });
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * The document as it is on disk, or `undefined` when there is none.
+ *
+ * AD-5: absent and unusable are DIFFERENT answers and this is the only place
+ * that can tell them apart. Absent means create; unusable means refuse, and
+ * refuse without writing — the alternative is destroying a document brambo could
+ * not understand, including one a user is halfway through editing.
+ */
+async function readDocument(filePath) {
+    let text;
+    try {
+        text = await readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        const code = error?.code;
+        // ENOENT on a DANGLING symlink too — `readFile` follows links. That case is
+        // not treated as absent here: `atomicWriteText` resolves the link itself and
+        // refuses a dangling one coded, which is the answer that keeps brambo from
+        // materialising a regular file where the user put a link.
+        if (code === 'ENOENT')
+            return undefined;
+        throw unusable(filePath, `it could not be read (${code ?? 'unknown error'})`, error);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        // LOCATED, never quoted (`document-fault.ts`), and no `cause`: passing the
+        // error here put its message on every stack that printed this refusal.
+        throw unusable(filePath, `it is not valid JSON, and brambo does not overwrite a document it cannot read: ${strictFaultLocation(text)}`);
+    }
+    if (!isRecord(parsed)) {
+        throw unusable(filePath, 'it must hold a JSON object, and brambo does not replace one that does not');
+    }
+    return parsed;
+}
+/** `<root>/.brambo/config.json` for the scope this call names. */
+export function configPathFor(options) {
+    const root = options.scope === 'machine' ? options.homeDir : options.projectDir;
+    if (root === undefined || root.trim().length === 0) {
+        throw new BramboError(BRAMBO_ERROR_CODES.environmentScopeUnavailable, "a 'project' scope needs the directory of the project whose configuration is being written");
+    }
+    return join(root, BRAMBO_STATE_DIR, CONFIG_FILE);
+}
+/**
+ * Sets ONE allowlisted key in brambo's own configuration document.
+ *
+ * Every other key is carried through untouched: these documents hold the
+ * workspace root beside the executor selection, and a writer that serialises
+ * only what it was handed silently deletes the rest.
+ *
+ * The write goes through `@skanl/brambo-projection`'s `atomicWriteText` rather than a
+ * local temp-then-rename, because this exact file is the one dotfile managers
+ * materialise as a symlink and it is the only writer in this repository that
+ * resolves the link instead of replacing it. The cost is that a refusal arrives
+ * as a `BRAMBO_PROJECTION_*` code out of a configuration verb; that is recorded
+ * in `deferred-work.md` and it is cheaper than a second copy of the symlink rule.
+ */
+export async function setConfigValue(options) {
+    const { key, value } = options;
+    if (!WRITABLE_CONFIG_KEYS.includes(key)) {
+        // The list is built BEFORE the message rather than interpolated into it: the
+        // printed-command scanner reads backtick strings out of shipped source, and
+        // a nested template literal reached it as raw `${...}` source text.
+        const known = WRITABLE_CONFIG_KEYS.map((writable) => `'${writable}'`).join(', ');
+        throw new BramboError(BRAMBO_ERROR_CODES.configurationUnusable, `brambo does not persist a '${key}' setting; it writes ${known}`);
+    }
+    const filePath = configPathFor(options);
+    const existing = await readDocument(filePath);
+    const previous = existing?.[key];
+    try {
+        await atomicWriteText(filePath, `${JSON.stringify({ ...existing, [key]: value }, undefined, 2)}\n`);
+    }
+    catch (error) {
+        // Coded HERE rather than inside `atomicWriteText` (AD-7). Every OTHER caller
+        // of that writer goes through the projection engine, whose `toTargetFailure`
+        // already wraps a raw error as `BRAMBO_PROJECTION_TARGET_FAILED` and which
+        // `doctor` classifies from — coding it upstream was tried and it changed the
+        // code doctor sees. This caller does not go through the engine, so it codes
+        // its own failure, in configuration vocabulary rather than projection's.
+        //
+        // The commonest cause is a read-only document, and on Windows it is `rename`
+        // that refuses (measured: a 0o444 target gives `EPERM: operation not
+        // permitted, rename` while the temp write succeeds). The mode is NOT relaxed
+        // to get the write through: a file the user made read-only was made
+        // read-only on purpose.
+        const detail = error?.code;
+        // Worded to read after `unusable`'s own "brambo will not write '<path>'
+        // because" prefix, which is also why it does not start with the word brambo:
+        // a printed string that does is treated as a COMMAND by
+        // `packages/cli/test/printed-commands.test.ts` and has to be declared prose.
+        throw unusable(filePath, `it could not be replaced (${detail ?? String(error)}), so it is not writable`, error);
+    }
+    return {
+        filePath,
+        previous: typeof previous === 'string' ? previous : undefined,
+        created: existing === undefined,
+    };
+}

package/dist/document-fault.d.ts

@@ -0,0 +1,59 @@
+import type { ParseError } from 'jsonc-parser';
+/**
+ * ONE rule, in one place, for every document this package parses (Spec M17.A):
+ * **no error brambo raises about a document quotes that document's content.**
+ *
+ * The hazard is not hypothetical and not confined to vendor files. V8's
+ * `JSON.parse` puts a window of the SOURCE TEXT in its message for the shapes it
+ * cannot give a position for — a stray comma before an array element and a `NaN`
+ * literal — and the documents brambo parses are where MCP server arguments live,
+ * which is where an API token lives. Measured through the shipped binary at
+ * `4232e9c`: a credential planted next to the fault reached stdout from
+ * `~/.claude.json` AND from `.brambo/registry.json`.
+ *
+ * The message cannot be TRIMMED to its location, because the shapes that quote
+ * the document are exactly the ones carrying no position. So it is dropped
+ * whole, the `cause` goes with it — a cause is reachable from any printed stack,
+ * so keeping it would move the leak rather than close it — and brambo derives its
+ * own location from `jsonc-parser`'s offsets.
+ *
+ * ponytail: `@skanl/brambo-registry` carries its own copy of this, because AD-2 forbids
+ * the edge that would let it import this one and `@skanl/brambo-contracts` must stay
+ * dependency-free for the third-party promise. Ceiling: two copies to keep in
+ * step. Upgrade path: a shared dependency-free leaf package, worth it the first
+ * time a third package needs it.
+ */
+/** What brambo says when it cannot derive a location — never the parser's text. */
+export declare const FAULT_UNLOCATED = "the fault could not be located";
+/**
+ * A byte offset as the 1-based `line:column` a user's editor shows.
+ *
+ * Offset 0 needs no special case and had one until it was measured: there
+ * `lastIndexOf('\n', -1)` is -1, the +1 makes `lineStart` 0, and `''.split('\n')`
+ * has length 1 — so the general form already answers `line 1, column 1`.
+ */
+export declare function positionOf(text: string, offset: number): string;
+/**
+ * The parser's own CODE plus brambo's `line:column`, from a collected offset.
+ *
+ * The code (`InvalidSymbol`, `PropertyNameExpected`) is the parser's, not prose
+ * brambo invents: it is terser than a sentence, and it is the same word the
+ * user's editor and every other jsonc-parser consumer already shows them. It
+ * names the FAULT; it never carries a byte of the document.
+ */
+export declare function faultDetail(body: string, error: ParseError | undefined): string;
+/**
+ * Re-locates a fault `JSON.parse` refused, using `jsonc-parser`'s OFFSETS — not
+ * a second parser, and not a regex over V8's message.
+ *
+ * The options are strict-JSON semantics exactly: trailing commas are errors (the
+ * default) and so are comments, so nearly every document V8 rejects collects an
+ * offset here. Where none is collected, the caller still refuses; it just cannot
+ * say where.
+ *
+ * `parseTree` RECURSES, and it was measured throwing `RangeError` on a document
+ * nested past ~5000 levels that V8 also rejects — so the throw is reachable from
+ * here. It is caught rather than propagated, because losing the location is the
+ * documented outcome and losing the CODED error is not.
+ */
+export declare function strictFaultLocation(body: string): string;

package/dist/document-fault.js

@@ -0,0 +1,78 @@
+import { parseTree, printParseErrorCode } from 'jsonc-parser';
+/**
+ * ONE rule, in one place, for every document this package parses (Spec M17.A):
+ * **no error brambo raises about a document quotes that document's content.**
+ *
+ * The hazard is not hypothetical and not confined to vendor files. V8's
+ * `JSON.parse` puts a window of the SOURCE TEXT in its message for the shapes it
+ * cannot give a position for — a stray comma before an array element and a `NaN`
+ * literal — and the documents brambo parses are where MCP server arguments live,
+ * which is where an API token lives. Measured through the shipped binary at
+ * `4232e9c`: a credential planted next to the fault reached stdout from
+ * `~/.claude.json` AND from `.brambo/registry.json`.
+ *
+ * The message cannot be TRIMMED to its location, because the shapes that quote
+ * the document are exactly the ones carrying no position. So it is dropped
+ * whole, the `cause` goes with it — a cause is reachable from any printed stack,
+ * so keeping it would move the leak rather than close it — and brambo derives its
+ * own location from `jsonc-parser`'s offsets.
+ *
+ * ponytail: `@skanl/brambo-registry` carries its own copy of this, because AD-2 forbids
+ * the edge that would let it import this one and `@skanl/brambo-contracts` must stay
+ * dependency-free for the third-party promise. Ceiling: two copies to keep in
+ * step. Upgrade path: a shared dependency-free leaf package, worth it the first
+ * time a third package needs it.
+ */
+/** What brambo says when it cannot derive a location — never the parser's text. */
+export const FAULT_UNLOCATED = 'the fault could not be located';
+/**
+ * A byte offset as the 1-based `line:column` a user's editor shows.
+ *
+ * Offset 0 needs no special case and had one until it was measured: there
+ * `lastIndexOf('\n', -1)` is -1, the +1 makes `lineStart` 0, and `''.split('\n')`
+ * has length 1 — so the general form already answers `line 1, column 1`.
+ */
+export function positionOf(text, offset) {
+    const bounded = Math.max(0, Math.min(offset, text.length));
+    const lineStart = text.lastIndexOf('\n', bounded - 1) + 1;
+    return `line ${text.slice(0, lineStart).split('\n').length}, column ${bounded - lineStart + 1}`;
+}
+/**
+ * The parser's own CODE plus brambo's `line:column`, from a collected offset.
+ *
+ * The code (`InvalidSymbol`, `PropertyNameExpected`) is the parser's, not prose
+ * brambo invents: it is terser than a sentence, and it is the same word the
+ * user's editor and every other jsonc-parser consumer already shows them. It
+ * names the FAULT; it never carries a byte of the document.
+ */
+export function faultDetail(body, error) {
+    return error === undefined
+        ? FAULT_UNLOCATED
+        : `${printParseErrorCode(error.error)} at ${positionOf(body, error.offset)}`;
+}
+/**
+ * Re-locates a fault `JSON.parse` refused, using `jsonc-parser`'s OFFSETS — not
+ * a second parser, and not a regex over V8's message.
+ *
+ * The options are strict-JSON semantics exactly: trailing commas are errors (the
+ * default) and so are comments, so nearly every document V8 rejects collects an
+ * offset here. Where none is collected, the caller still refuses; it just cannot
+ * say where.
+ *
+ * `parseTree` RECURSES, and it was measured throwing `RangeError` on a document
+ * nested past ~5000 levels that V8 also rejects — so the throw is reachable from
+ * here. It is caught rather than propagated, because losing the location is the
+ * documented outcome and losing the CODED error is not.
+ */
+export function strictFaultLocation(body) {
+    const errors = [];
+    try {
+        parseTree(body, errors, { disallowComments: true });
+    }
+    catch {
+        return FAULT_UNLOCATED;
+    }
+    // The FIRST only. A recovering parser cascades — an unquoted key reports four
+    // — and the rest are that one's shadow.
+    return faultDetail(body, errors[0]);
+}

package/dist/engine.d.ts

@@ -0,0 +1,69 @@
+import type { ProjectionFailure, ProjectionResult, ProjectionTarget, ProjectionWarning, RegistryEntriesByKind, RegistryEntry } from '@skanl/brambo-contracts';
+import type { ProjectionLedger } from './ledger.ts';
+/**
+ * The registry as the projection engine reads it: one bucket per DECLARED entry
+ * type.
+ *
+ * Derived from `REGISTRY_ENTRY_TYPES` rather than listed — a second table here
+ * is how the engine comes to project a word the contract no longer has, or to
+ * miss one it just gained. It is also the boundary that keeps a RETIRED type out
+ * of projection: an entry whose type is not declared has no bucket, so it is
+ * dropped here and no target is ever asked to express it. The store still reads
+ * it, `brambo list` still shows it and `brambo remove` still takes it out.
+ */
+export declare function groupByKind(entries: readonly RegistryEntry[]): RegistryEntriesByKind;
+/**
+ * Whether the run is allowed to LAND what it computes.
+ *
+ * `'inspect'` is the whole of `brambo doctor`: the identical merge, the identical
+ * drift classification, the identical ledger read — and neither of the two
+ * writes a run performs. A diagnosis computed by a second code path can disagree
+ * with what applying would do, and it would disagree exactly when a user is
+ * trying to fix something.
+ */
+export type ProjectionMode = 'apply' | 'inspect';
+/**
+ * FAIL CLOSED. Not `mode !== 'inspect'`: that writes for `'Inspect'`,
+ * `'inspect '`, `'dry-run'` and `null`, and the one thing this field decides is
+ * whether brambo writes into files it does not own. A no-op run is visible in its
+ * own output; a write into a user's config on the say-so of a typo is not. So
+ * both failures are loud. `=== undefined`, not `??`: `null` is a value a caller
+ * PASSED, not an omission, and coalescing it into the writing default is the
+ * same silent accept this guard exists to remove.
+ *
+ * Shared by `runProjection` and `runRemediation` so the two commands that can
+ * write cannot disagree about what "do not touch this machine" means.
+ */
+export declare function resolveProjectionMode(mode: ProjectionMode | undefined): ProjectionMode;
+export interface RunProjectionOptions {
+    readonly entries: RegistryEntriesByKind;
+    readonly targets: readonly ProjectionTarget[];
+    /** Required: without a ledger brambo cannot know which entries are its own. */
+    readonly ledger: ProjectionLedger;
+    /**
+     * Defaults to `'apply'`. Under `'inspect'` NOTHING is written — not the vendor
+     * file, not the ledger — and `ProjectionResult.written` reads as "these bytes
+     * WOULD have changed", which is the one field whose sentence the mode alters.
+     */
+    readonly mode?: ProjectionMode;
+}
+export interface ProjectionRun {
+    readonly results: ProjectionResult[];
+    readonly failures: ProjectionFailure[];
+    readonly warnings: ProjectionWarning[];
+}
+/** File identity snapshot taken when the native text is read. */
+export interface NativeFileSnapshot {
+    readonly mtimeMs: number;
+    readonly size: number;
+}
+/**
+ * Defense against a read-write race: if the native file changed on disk between
+ * the read and the write, the projection is stale and MUST NOT land. An ABSENT
+ * snapshot is not "nothing to compare": the merge was computed against an empty
+ * document, so the file appearing in the meantime — a vendor CLI creating
+ * `~/.claude.json` — is exactly the case where landing would overwrite it
+ * wholesale.
+ */
+export declare function hasFileChangedSince(filePath: string, snapshot: NativeFileSnapshot | undefined): Promise<boolean>;
+export declare function runProjection(options: RunProjectionOptions): Promise<ProjectionRun>;