@skanl/brambo-environment 0.1.1

package/dist/init.js

@@ -0,0 +1,641 @@
+import { mkdir, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { BRAMBO_ERROR_CODES, BramboError, isRetiredEntryType, projectionTargetLocation, } from '@skanl/brambo-contracts';
+import { createMemoryLogSink } from '@skanl/brambo-kernel';
+import { ProjectionLedger, groupByKind, runProjection, runRemediation } from '@skanl/brambo-projection';
+import { RegistryStore } from '@skanl/brambo-registry';
+import { EXECUTOR_PROFILES, detectExecutors } from './executors.js';
+// The first composed path brambo has: registry -> projection -> a real
+// executor's real configuration file. Everything here is COMPOSITION. The
+// projection engine, its targets and its ownership ledger are Story 2.8's and
+// are used exactly as they ship: this package decides WHICH targets run and
+// reports what happened, and it is the ledger — never this file — that decides
+// what brambo is allowed to modify.
+//
+// Nothing in this package writes into a vendor's file. The only filesystem write
+// it performs itself is `mkdir` of brambo's OWN directory; `test/guard.test.ts`
+// pins that by asserting the whole of `src/` reaches the filesystem module for
+// nothing beyond `mkdir` and `stat`.
+//
+// On the kernel: a projection write is not an executor action, so AD-10's
+// interception pipeline is not forced in here. What IS taken from the kernel is
+// the Story 1.6 record sink (NFR-4), because "what did brambo write into whose
+// configuration" is the kind of thing that has to be reconstructable afterwards.
+// The record shape is closed and has no free-form slot, so the sink carries THAT
+// each target was projected and whether it succeeded, and the durable ledger
+// carries what was written and where. Both halves are needed and neither is a
+// substitute for the other.
+//
+// ponytail: one record per TARGET attempt, not per entry. The closed record
+// shape has room for an event and a bounded subject and nothing else, so
+// per-entry granularity has nowhere to go without a kernel record-shape change
+// (LOG_RECORD_VERSION exists to carry one). Recorded in deferred-work.md.
+/**
+ * Subject PREFIX every projection record is written under. The subject is
+ * `${PROJECTION_ACTION_ID}#${targetId}` — bounded by brambo's own constants, so
+ * it can never be rejected by the sink's identifier rules the way a file path
+ * (unbounded length, arbitrary characters) could be.
+ *
+ * Exported because a reader of the record stream needs the same string brambo
+ * wrote; match with `subject.startsWith(PROJECTION_ACTION_ID + '#')`.
+ */
+export const PROJECTION_ACTION_ID = 'environment.projection';
+/**
+ * True when no executor was found — the caller's non-zero-exit condition.
+ *
+ * Takes the DETECTION, not an `InitResult`: `brambo doctor` has to answer the
+ * same question about the same evidence, and two spellings of "did brambo find
+ * anything" is how the two commands come to disagree about one machine.
+ */
+export function noExecutorsDetected(result) {
+    return result.detected.every((detection) => !detection.present);
+}
+/**
+ * Registry identity is `type:id`, but `ProjectionResult.skippedEntryIds` carries
+ * BARE ids, so one id can arrive matching several entries — a `tool` named `x`
+ * and an `mcp-server` named `x` are two different entries and only the first is
+ * skipped. Reporting both reasons would tell the user that an mcp-server which
+ * was projected successfully in this very run declares no command, and that
+ * reason is the one field a user acts on.
+ *
+ * So the candidates are narrowed by the property that actually makes an entry
+ * skippable, which is the same rule `collectMcpEntries` applies: any kind other
+ * than mcp-server, or an mcp-server with no command. Nothing else can be behind
+ * a skipped id.
+ *
+ * A target that KNOWS why says so itself, through `ProjectionResult.skipped`,
+ * and its reason wins wherever it is present — the skills target is the first
+ * one with reasons of its own ("this skill names a source brambo cannot read"),
+ * which no derivation from the registry entry could ever have produced.
+ *
+ * `skillsHandled` is the other half of the same correction. Once an executor has
+ * a verified skills root, "this executor has no native representation for a
+ * skill" is FALSE for that executor, so skill entries stop being candidates
+ * here; an id left with no candidate at all is dropped from the config row
+ * entirely rather than explained by a sentence that is no longer true.
+ */
+function reasonUnprojectable(entries, executorId, skillsHandled) {
+    const candidates = entries.filter((entry) => (entry.type !== 'mcp-server' || entry.command === undefined) &&
+        !(skillsHandled && entry.type === 'skill'));
+    if (candidates.length === 0) {
+        // Only when this executor materialises skills can an id legitimately have no
+        // candidate left, and then the id belongs to the skills row, not this one.
+        if (skillsHandled && entries.length > 0)
+            return undefined;
+        // Otherwise no entry brambo handed over can explain this id: said plainly
+        // rather than guessed, because a reason brambo cannot establish is still a fact.
+        return `'${executorId}' reported this entry as unprojectable and the registry holds no entry that explains it`;
+    }
+    return candidates
+        .map((entry) => entry.type === 'mcp-server'
+        ? `the mcp-server entry declares no command, so there is nothing to render into '${executorId}'`
+        : // NO SPEC CITATION IN A SENTENCE A USER READS. This carried
+            // `(correction-01 C5)` and doctor printed it verbatim: an internal
+            // document name is a fact about brambo's own history, not about the
+            // reader's machine, and it is the one part of this line nobody can act
+            // on. The citation belongs where the RULE lives, which is the doc
+            // comment above and the `unprojectable` finding kind's own.
+            `'${executorId}' has no native representation for a ${entry.type} entry`)
+        .join('; ');
+}
+/**
+ * The per-entry reasons a target row carries: the target's own words where it
+ * had any, and the registry-derived sentence everywhere else.
+ */
+function unprojectableFor(result, byId, executorId, skillsHandled) {
+    const stated = new Map((result?.skipped ?? []).map((skip) => [skip.entryId, skip.reason]));
+    const rows = [];
+    for (const entryId of result?.skippedEntryIds ?? []) {
+        const reason = stated.get(entryId) ?? reasonUnprojectable(byId.get(entryId) ?? [], executorId, skillsHandled);
+        if (reason !== undefined)
+            rows.push({ entryId, reason });
+    }
+    return rows;
+}
+function scopeUnavailable(detail, cause) {
+    return new BramboError(BRAMBO_ERROR_CODES.environmentScopeUnavailable, detail, { cause });
+}
+/**
+ * The trust boundary. `homeDir` and `projectDir` are caller-supplied paths that
+ * decide where brambo creates directories and which vendor files it writes, so
+ * every one of them is resolved ONCE here and rejected unless it already names a
+ * directory.
+ *
+ * Three failures this closes, all of them observed: `homeDir: ''` — which is
+ * exactly `process.env.HOME ?? ''` in a consumer — resolves to the CWD and
+ * relocates the machine scope into whatever directory the process happens to be
+ * in; `brambo project init ~/typo` built the whole missing tree and wrote a
+ * vendor config into it; and `brambo project init ~/repo/.git` would have done
+ * the same inside a git directory. Brambo BINDS a project, it does not create one.
+ */
+export async function scopeDirectory(label, value) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw scopeUnavailable(`${label} must be a non-empty path, but brambo was given ${JSON.stringify(value)}`);
+    }
+    const resolved = resolve(value);
+    let isDirectory;
+    try {
+        isDirectory = (await stat(resolved)).isDirectory();
+    }
+    catch (error) {
+        throw scopeUnavailable(`${label} '${resolved}' cannot be used (${error?.code ?? 'unknown error'}); brambo binds an existing directory and never creates one`, error);
+    }
+    if (!isDirectory) {
+        throw scopeUnavailable(`${label} '${resolved}' is not a directory`);
+    }
+    return resolved;
+}
+/**
+ * MACHINE SCOPE, AND `'inspect'` HARD-CODED. Two separate deliberate choices:
+ *
+ * Machine scope, because the builds that wrote these locations had no project
+ * scope at all — `brambo project init` arrives in Story 2.7a, after correction-01
+ * — so there is no project-scope file that can hold one.
+ *
+ * `'inspect'` written here rather than threaded from `runScope`'s own `mode`,
+ * because `brambo init` must never remove a legacy block: removal is a decision,
+ * and this story's whole rule is that a decision is a user's, named one at a
+ * time. Passing the caller's mode through would make `brambo init` silently
+ * rewrite a vendor file — pinned by a test in `test/remediate.test.ts`.
+ */
+async function legacyFor(detected, homeDir) {
+    const present = new Set(detected.filter((detection) => detection.present).map((detection) => detection.executorId));
+    const rows = [];
+    for (const profile of EXECUTOR_PROFILES) {
+        if (!present.has(profile.executorId) || profile.legacyConfig === undefined)
+            continue;
+        const location = profile.legacyConfig(homeDir);
+        let outcome;
+        try {
+            outcome = await runRemediation({
+                remediation: 'discard',
+                legacy: { targetId: profile.targetId, rootPath: homeDir, ...location },
+                mode: 'inspect',
+            });
+        }
+        catch {
+            // A file brambo cannot READ is not evidence that litter is in it, and this
+            // finding's only resolution is a removal brambo would then be unable to
+            // perform — which is the false promise `brambo doctor`'s own Never clause
+            // forbids. Silence here, and the two of these three files that a target
+            // owns already report the read failure as `target-failed`.
+            continue;
+        }
+        const change = outcome.changes[0];
+        if (outcome.refusal !== undefined) {
+            rows.push({
+                executorId: profile.executorId,
+                targetId: profile.targetId,
+                filePath: location.filePath,
+                detail: outcome.refusal.message,
+                byteDelta: 0,
+                refusal: outcome.refusal,
+            });
+            continue;
+        }
+        if (change === undefined)
+            continue;
+        rows.push({
+            executorId: profile.executorId,
+            targetId: profile.targetId,
+            filePath: location.filePath,
+            detail: change.detail,
+            byteDelta: change.byteDelta,
+        });
+    }
+    return rows;
+}
+export function targetsFor(scope, detected, homeDir, projectDir) {
+    const planned = [];
+    const skills = [];
+    const skipped = [];
+    const present = new Set(detected.filter((detection) => detection.present).map((detection) => detection.executorId));
+    for (const profile of EXECUTOR_PROFILES) {
+        if (!present.has(profile.executorId))
+            continue;
+        const rootPath = scope === 'machine' ? profile.machineSkills?.(homeDir) : undefined;
+        if (rootPath !== undefined && profile.createSkillsTarget !== undefined) {
+            skills.push({ profile, target: profile.createSkillsTarget(rootPath) });
+        }
+        const filePath = scope === 'machine' ? profile.machineConfig(homeDir) : profile.projectConfig?.(projectDir);
+        if (filePath === undefined) {
+            skipped.push({
+                executorId: profile.executorId,
+                reason: `'${profile.executorId}' has no project-scope configuration file; brambo will not invent a location it does not read`,
+            });
+            continue;
+        }
+        planned.push({ profile, target: profile.createTarget(filePath) });
+    }
+    return { planned, skills, skipped };
+}
+/**
+ * Records without letting a broken sink break the run it is describing — the
+ * same containment rule the kernel applies to its own call sites. Brambo's
+ * subjects are bounded by construction, so the only way this throws is a hostile
+ * sink; the sink's own `dropped` counter remains the loss signal.
+ */
+function recordProjection(log, event, targetId) {
+    // No sink means there is no action to record: `diagnose` passes none, because
+    // an `action.invoked` for a projection that deliberately never ran would put a
+    // projection brambo did not perform into the record stream NFR-4 exists to make
+    // reconstructable. `initMachine`/`initProject` always pass one.
+    if (log === undefined)
+        return;
+    try {
+        log.record({ event, subject: `${PROJECTION_ACTION_ID}#${targetId}` });
+    }
+    catch {
+        // Contained by contract; a diagnostic never aborts what it describes.
+    }
+}
+/**
+ * A thrown error flattened to the two fields a caller acts on. A live `Error`
+ * serialises to `{}` for every caller that prints the result.
+ */
+function toTargetFailure(error) {
+    const code = error?.code;
+    return {
+        // Duck-typed on `code`, like the CLI's own `describe()`: the registry throws
+        // `BramboError`, but a code that arrived some other way is still the fact.
+        code: typeof code === 'string' && code.length > 0
+            ? code
+            : BRAMBO_ERROR_CODES.registryStoreUnavailable,
+        message: error instanceof Error ? error.message : String(error),
+    };
+}
+/** Brambo's own state directory for a scope root. One spelling, two callers. */
+function bramboDirOf(root) {
+    return join(root, '.brambo');
+}
+export function storeFor(scope, homeDir, projectDir) {
+    return new RegistryStore(scope === 'machine' ? { homeDir } : { homeDir, projectDir });
+}
+/**
+ * The command that projects one scope. One spelling, and `doctor.ts` is now a
+ * caller too: it named `brambo init` as the exit from a PROJECT's
+ * `not-initialised` and `out-of-date`, and that command exits 0 leaving the
+ * project exactly as it was.
+ */
+export function projectCommandFor(scope) {
+    return scope === 'machine' ? 'brambo init' : 'brambo project init';
+}
+async function takenBy(entry, detected, scope, homeDir, projectDir) {
+    const { planned, skills } = targetsFor(scope, detected, homeDir, projectDir);
+    const byKind = groupByKind([entry]);
+    const executorIds = [];
+    // DEDUPED, and that was measured rather than tidiness. The derived sentence
+    // names the EXECUTOR, while targets are per-executor-PLUS-surface: with a
+    // `.claude.json` and a `.claude/` skills root both present, the same executor
+    // is asked twice and a naive collection printed the identical sentence twice.
+    // Doctor's rows are per TARGET and can carry two; `EntryDelivery.reasons` is a
+    // flat per-executor list and cannot.
+    const reasons = new Set();
+    // The executors whose skills root brambo VERIFIED at this scope, which is what
+    // makes "this executor has no native representation for a skill" false for
+    // them -- the same input `unprojectableFor` gives `reasonUnprojectable`.
+    const skillsHandled = new Set(skills.map(({ profile }) => profile.executorId));
+    /**
+     * A target skipped this entry and said nothing. Derive the reason the way
+     * doctor already does, from the ONE producer, rather than reporting an absence
+     * brambo never measured.
+     *
+     * `no target said why` at `registry-commands.ts` used to fire here for every
+     * mcp-server with no command -- while `brambo doctor`, on the same fixture,
+     * printed the exact sentence. The verb that CREATED the state sent the user to
+     * a second command for an answer that lives in this module.
+     */
+    const explain = (executorId) => {
+        const derived = reasonUnprojectable([entry], executorId, skillsHandled.has(executorId));
+        // `undefined` is the skills-handled case: the id belongs to another row and
+        // this one has nothing true to say. Left unsaid, so the caller's fallback
+        // still fires -- an absence brambo DID measure.
+        if (derived !== undefined)
+            reasons.add(derived);
+    };
+    for (const { profile, target } of [...planned, ...skills]) {
+        if (target.kind === 'materialise') {
+            const plan = await target.plan({ entries: byKind, records: [], rootPath: target.rootPath });
+            if (plan.entries.some((row) => row.entryId === entry.id)) {
+                executorIds.push(profile.executorId);
+                continue;
+            }
+            // The target's own words win where it had any -- it knows things no
+            // derivation from a registry entry could produce, like a skill whose
+            // source cannot be read. The prefix stays HERE and only here, because that
+            // text was authored by the target and may not name the executor; the
+            // derived sentence already does.
+            const own = (plan.skipped ?? []).filter((skip) => skip.entryId === entry.id);
+            if (own.length > 0) {
+                for (const skip of own)
+                    reasons.add(`${profile.executorId}: ${skip.reason}`);
+                continue;
+            }
+            // AND THIS BRANCH IS THE ONE THE FIRST DIAGNOSIS MISSED. A skills target
+            // iterates `entries.skill` alone, so an mcp-server is dropped by it without
+            // ever producing a `ProjectionSkip`: for that entry BOTH target kinds were
+            // silent, not just merge.
+            explain(profile.executorId);
+            continue;
+        }
+        const outcome = await target.merge({ entries: byKind, records: [], nativeText: '' });
+        if (!(outcome.skippedEntryIds ?? []).includes(entry.id)) {
+            executorIds.push(profile.executorId);
+            continue;
+        }
+        // A merge outcome carries ids alone (`ProjectionMergeOutcome.skippedEntryIds`),
+        // which `contracts/src/projection.ts` names as the defect that forces this
+        // derivation. It is EXACT rather than approximate today: `collectMcpEntries`
+        // skips exactly the two shapes `reasonUnprojectable` derives, and anything
+        // else falls through to its honest "the registry holds no entry that
+        // explains it".
+        explain(profile.executorId);
+    }
+    return { executorIds, reasons: [...reasons] };
+}
+/**
+ * {@link EntryDelivery} for one scope, with the OTHER scope answered too
+ * whenever this one takes the entry nowhere.
+ *
+ * Contained: a target that throws while being asked leaves `undetermined` set
+ * rather than propagating, because the caller has already registered the entry
+ * and a message is not worth losing a completed write over.
+ */
+export async function deliveryFor(entry, scope, homeDir, projectDir) {
+    const command = projectCommandFor(scope);
+    let detected;
+    try {
+        detected = await detectExecutors(homeDir);
+        const here = await takenBy(entry, detected, scope, homeDir, projectDir);
+        if (here.executorIds.length > 0) {
+            return { scope, command, executorIds: here.executorIds, reasons: here.reasons };
+        }
+        const otherScope = scope === 'machine' ? 'project' : 'machine';
+        const there = await takenBy(entry, detected, otherScope, homeDir, projectDir);
+        return {
+            scope,
+            command,
+            executorIds: [],
+            reasons: here.reasons,
+            ...(there.executorIds.length === 0
+                ? {}
+                : {
+                    elsewhere: {
+                        scope: otherScope,
+                        command: projectCommandFor(otherScope),
+                        executorIds: there.executorIds,
+                        reasons: there.reasons,
+                    },
+                }),
+        };
+    }
+    catch (error) {
+        const failure = toTargetFailure(error);
+        return {
+            scope,
+            command,
+            executorIds: [],
+            reasons: [],
+            undetermined: `${failure.code}: ${failure.message}`,
+        };
+    }
+}
+/**
+ * The ONLY two writes into brambo's own state that `brambo init` performs: its
+ * directory, and the registry store document. They live here — OUTSIDE
+ * `runScope`, which `init` and `diagnose` share — so the read-only caller cannot
+ * reach them by construction rather than by remembering not to.
+ * `test/doctor.test.ts` proves the consequence at byte level.
+ */
+async function prepareScope(scope, root, homeDir, projectDir) {
+    const bramboDir = bramboDirOf(root);
+    // Brambo's own directory, created by brambo. `recursive` here means "tolerate an
+    // existing directory", not "build a tree": the parent was validated as an
+    // existing directory above, so the only thing this can still meet is `.brambo`
+    // occupied by a FILE, which arrives as a bare doubled EEXIST naming nothing.
+    try {
+        await mkdir(bramboDir, { recursive: true });
+    }
+    catch (error) {
+        throw scopeUnavailable(`brambo's own state directory '${bramboDir}' cannot be created (${error?.code ?? 'unknown error'})`, error);
+    }
+    const store = storeFor(scope, homeDir, projectDir);
+    try {
+        // Materialised through the store itself, so the document's version and shape
+        // stay the registry's to define. A corrupt store fails coded here rather than
+        // being silently replaced.
+        return await store.ensure(scope === 'machine' ? 'global' : 'project');
+    }
+    finally {
+        await store.dispose();
+    }
+}
+/**
+ * Registry -> detection -> projection engine, for one scope. `brambo init` and
+ * `brambo doctor` are THIS function under the two projection modes and nothing
+ * else: same entries, same detection, same targets, same engine call, same drift
+ * classification. Two code paths could disagree about what applying would do,
+ * and they would disagree exactly when a user is trying to fix something.
+ *
+ * Every line below either reads, or writes through the projection engine — which
+ * under `'inspect'` writes nothing at all.
+ */
+export async function runScope(scope, homeDir, projectDir, log, mode) {
+    const store = storeFor(scope, homeDir, projectDir);
+    const registryPath = store.storePath(scope === 'machine' ? 'global' : 'project');
+    let entries = [];
+    const retired = [];
+    let registryError;
+    try {
+        entries = await store.list();
+        // Read PER SCOPE as well, rather than filtered out of the merged view above:
+        // the merge keeps one row per `type:id` and DROPS the scope that produced
+        // it, which is exactly the fact every message about a retired entry needs.
+        // Same scopes, in the same order, that `brambo list` walks under each
+        // grammar — so `brambo project doctor` reports a global entry against the
+        // global document, with the global verb.
+        const retiredScopes = scope === 'machine' ? ['global'] : ['global', 'project'];
+        for (const candidateScope of retiredScopes) {
+            for (const entry of await store.list(candidateScope)) {
+                if (!isRetiredEntryType(entry.type))
+                    continue;
+                retired.push({ entry, scope: candidateScope, registryPath: store.storePath(candidateScope) });
+            }
+        }
+    }
+    catch (error) {
+        // Brambo's OWN two state files, classified the same way. A corrupt ledger is
+        // already a reported finding; a corrupt registry throwing out of the command
+        // whose job is diagnosing brambo's state would be the opposite treatment for
+        // the same class of fault. `'apply'` still throws: `brambo init` must not
+        // project against a registry it cannot read.
+        if (mode === 'apply')
+            throw error;
+        registryError = toTargetFailure(error);
+    }
+    finally {
+        await store.dispose();
+    }
+    const detected = await detectExecutors(homeDir);
+    const { planned, skills, skipped } = targetsFor(scope, detected, homeDir, projectDir);
+    const ledger = new ProjectionLedger({ homeDir });
+    if (registryError !== undefined) {
+        // No engine call at all: every per-target verdict is derived from the
+        // registry, so reporting rows computed against an empty one would tell the
+        // user brambo is about to delete entries it simply could not read.
+        return {
+            bramboDir: bramboDirOf(scope === 'machine' ? homeDir : projectDir),
+            registryPath,
+            ledgerPath: ledger.filePath,
+            entryCount: 0,
+            detected,
+            targets: [],
+            skills: [],
+            skipped,
+            legacy: scope === 'machine' && mode === 'inspect' ? await legacyFor(detected, homeDir) : [],
+            warnings: [],
+            registryError,
+            retired: [],
+        };
+    }
+    const everyTarget = [...planned, ...skills];
+    for (const { target } of everyTarget)
+        recordProjection(log, 'action.invoked', target.targetId);
+    const run = await runProjection({
+        entries: groupByKind(entries),
+        targets: everyTarget.map((plan) => plan.target),
+        ledger,
+        mode,
+    });
+    // Built from the entries the engine was actually GIVEN: a retired entry is
+    // never handed to a target, so it can never be the explanation for an id a
+    // target skipped — and an id spelled the same in both vocabularies would
+    // otherwise be explained by the entry nobody projected, naming a type brambo no
+    // longer declares. `test/init.test.ts` forces exactly that collision.
+    const byId = new Map();
+    for (const entry of entries) {
+        if (isRetiredEntryType(entry.type))
+            continue;
+        byId.set(entry.id, [...(byId.get(entry.id) ?? []), entry]);
+    }
+    const results = new Map(run.results.map((result) => [result.targetId, result]));
+    const failures = new Map(run.failures.map((failure) => [failure.targetId, failure]));
+    // Walked over `planned`, which is catalogue order, so one executor failing can
+    // never reshuffle the report — and so a target that BOTH wrote and then failed
+    // its ledger update yields ONE row carrying both facts. Two rows, or a row
+    // hardcoding `changed: false` for a failure, is how brambo came to report
+    // `written: false` for bytes it had already landed.
+    const materialising = new Set(skills.map(({ profile }) => profile.executorId));
+    const rowFor = ({ profile, target }) => {
+        const result = results.get(target.targetId);
+        const failure = failures.get(target.targetId);
+        recordProjection(log, failure === undefined ? 'action.completed' : 'action.failed', target.targetId);
+        return {
+            executorId: profile.executorId,
+            targetId: target.targetId,
+            filePath: projectionTargetLocation(target),
+            changed: result?.written ?? false,
+            drift: result?.drift ?? [],
+            // A config row stops claiming an executor cannot express a SKILL once that
+            // executor has a verified skills root: the skills row below is the
+            // authority for those ids, and two rows answering for one entry is how a
+            // user is told a skill was both materialised and impossible.
+            //
+            // KNOWN LOSS OF GRANULARITY, and it is deliberate. When the skills target
+            // FAILS outright, its row carries the coded error and an empty
+            // `unprojectable` list, while this row has already dropped those ids — so
+            // no row names the individual skills. The alternative is worse: the config
+            // row's only sentence is "this executor has no native representation for a
+            // skill", which is false for an executor that has a verified root and
+            // merely could not be written to this run. A per-target failure is loud in
+            // its own right (`error` on the row, `target-failed` in doctor, non-zero
+            // exit), so what is lost is which entries it covered, not the failure.
+            unprojectable: unprojectableFor(result, byId, profile.executorId, target.kind !== 'materialise' && materialising.has(profile.executorId)),
+            ...(failure === undefined
+                ? {}
+                : { error: { code: failure.error.code, message: failure.error.message } }),
+        };
+    };
+    const targets = planned.map(rowFor);
+    const skillRows = skills.map(rowFor);
+    return {
+        bramboDir: bramboDirOf(scope === 'machine' ? homeDir : projectDir),
+        registryPath,
+        ledgerPath: ledger.filePath,
+        entryCount: entries.length,
+        detected,
+        targets,
+        skills: skillRows,
+        skipped,
+        legacy: scope === 'machine' && mode === 'inspect' ? await legacyFor(detected, homeDir) : [],
+        warnings: run.warnings,
+        retired,
+    };
+}
+function toTargetProjection(row) {
+    // Named field by field, NOT spread. A spread rebuilds the row in the spread's
+    // order and silently moved `written` from index 3 to last, after `error`, with
+    // both suites green — and this is a documented payload a caller prints.
+    // `test/init.test.ts` pins the order.
+    return {
+        executorId: row.executorId,
+        targetId: row.targetId,
+        filePath: row.filePath,
+        written: row.changed,
+        drift: row.drift,
+        unprojectable: row.unprojectable,
+        // A row carrying no `error` key keeps carrying none: an `error: undefined`
+        // in the payload reads to every JSON consumer as a field brambo decided to
+        // say nothing about.
+        ...(row.error === undefined ? {} : { error: row.error }),
+    };
+}
+function toInitResult(scope, registryPath, report) {
+    return {
+        scope,
+        bramboDir: report.bramboDir,
+        registryPath,
+        ledgerPath: report.ledgerPath,
+        entryCount: report.entryCount,
+        detected: report.detected,
+        targets: report.targets.map(toTargetProjection),
+        skills: report.skills.map(toTargetProjection),
+        skipped: report.skipped,
+        warnings: report.warnings,
+    };
+}
+/**
+ * Prepares this machine: brambo's own directory and registry store exist
+ * afterwards, and the global registry is projected into every detected
+ * executor's own machine-scope configuration.
+ *
+ * Idempotent. A second run over an unchanged registry writes no vendor byte and
+ * reports every target as unchanged.
+ */
+export async function initMachine(options = {}) {
+    // Every field read ONCE, here, before the first await. A later read of a
+    // caller-controlled object is a TOCTOU hole: an accessor that answers with a
+    // temp directory now and the real home directory later would get the real one
+    // projected into.
+    const { homeDir = homedir(), log } = options;
+    const home = await scopeDirectory('the home directory', homeDir);
+    const registryPath = await prepareScope('machine', home, home, home);
+    const report = await runScope('machine', home, home, log ?? createMemoryLogSink(), 'apply');
+    return toInitResult('machine', registryPath, report);
+}
+/**
+ * Binds a project: brambo's own directory and project registry store exist under
+ * it afterwards, and the registry it can see — the project's entries over the
+ * machine's — is projected into every detected executor that has a project-scope
+ * configuration. An executor without one is reported as skipped, never written
+ * to somewhere it does not read.
+ */
+export async function initProject(options = {}) {
+    const { homeDir = homedir(), projectDir = process.cwd(), log } = options;
+    const home = await scopeDirectory('the home directory', homeDir);
+    const projectRoot = await scopeDirectory('the project directory', projectDir);
+    const registryPath = await prepareScope('project', projectRoot, home, projectRoot);
+    const report = await runScope('project', home, projectRoot, log ?? createMemoryLogSink(), 'apply');
+    return toInitResult('project', registryPath, report);
+}