@skanl/brambo-session 0.1.1

package/dist/executors.js

@@ -0,0 +1,342 @@
+import { lstat, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { DEFAULT_EXECUTOR_ID, EXECUTOR_CATALOGUE, EXECUTOR_CONFIG_KEY, availableExecutorIds, createExecutorAdapter, unknownExecutor, } from '@skanl/brambo-adapter-cli';
+import { METHOD_CONFIG_KEY, BRAMBO_ERROR_CODES, BramboError, isRecord } from '@skanl/brambo-contracts';
+import { createLayeredConfig, deepMerge } from '@skanl/brambo-kernel';
+// Executor SELECTION: which shipped adapter this run uses, decided through the
+// layered configuration brambo already owns.
+//
+// The catalogue itself moved to `@skanl/brambo-adapter-cli` with Story M3.B — the
+// package that ships the three adapters is the one whose kernel plugin has to
+// turn a configured id into one. It is re-exported here unchanged, because
+// `@skanl/brambo-session` is the FR-29 surface: a consumer that installed only this
+// package still gets the whole selection vocabulary from one import.
+export { DEFAULT_EXECUTOR_ID, EXECUTOR_CATALOGUE, 
+// Re-exported, never re-declared. A second `const EXECUTOR_CONFIG_KEY` lived
+// here and a third literal lived in `run-session.ts`, so the REPORTED
+// selection and the MOUNTED adapter were derived independently from the same
+// document: renaming one produced `executor: codex (selected by the 'project'
+// layer)` on stderr while `claude` was spawned, exit 0. This package's whole
+// catalogue design exists because a second spelling drifted from the thing it
+// named; the key gets the same treatment.
+EXECUTOR_CONFIG_KEY, availableExecutorIds, createExecutorAdapter, };
+// ponytail: `.brambo/config.json` is spelled here rather than imported from
+// `@skanl/brambo-environment`, which owns the same `<scope>/.brambo` convention. That
+// package is CONSUMER tier and so is this one, and `packages/session/test/
+// guard.test.ts` pins @skanl/brambo-session's dependency set to exactly four packages —
+// so reaching for it would be an AD-2 violation the gate rejects, not a reuse.
+// Upgrade path: move the scope-directory convention down into `@skanl/brambo-contracts`
+// (shared tier) and have both consumers read it from there. Recorded in the
+// spec's Spec Change Log.
+const BRAMBO_STATE_DIR = '.brambo';
+const CONFIG_FILE = 'config.json';
+// The two errnos that mean "there is no such document", including a parent that
+// is not a directory (win32 reports that as ENOENT, POSIX as ENOTDIR). Every
+// other errno means something IS there and brambo could not read it, which is an
+// error rather than an absent layer.
+const ABSENT_ERRNOS = new Set(['ENOENT', 'ENOTDIR']);
+// A UTF-8 byte order mark, written as an escape. `readFile(path, 'utf8')` does
+// not strip one and `JSON.parse` rejects it, so three invisible bytes brick a
+// document whose visible contents are correct — and PowerShell 5.1's `>` and
+// `Set-Content`, Notepad, and VS Code's "UTF-8 with BOM" all emit one by default
+// on the platform this repo is developed on. `packages/adapter-cli/src/traits.ts`
+// strips the same mark off executor stdout for the same reason.
+const BYTE_ORDER_MARK = '\uFEFF';
+/** Brambo's own configuration document for a scope root. */
+export function executorConfigPath(scopeDir) {
+    return join(scopeDir, BRAMBO_STATE_DIR, CONFIG_FILE);
+}
+function unusable(filePath, detail, cause) {
+    return new BramboError(BRAMBO_ERROR_CODES.configurationUnusable, `brambo's configuration at '${filePath}' cannot be used: ${detail}`, cause === undefined ? undefined : { cause });
+}
+function blankExecutor() {
+    return new BramboError(BRAMBO_ERROR_CODES.executorNotFound, `an executor id must name one of: ${availableExecutorIds().join(', ')}, but it is blank`);
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * A caller-supplied scope root, absolute and non-empty.
+ *
+ * `homeDir: ''` — which is exactly `process.env.HOME ?? ''` in a consumer, and
+ * the shape Story 2.7a was bitten by — makes `join('', '.brambo', …)` RELATIVE,
+ * so the machine scope silently relocates into the working directory and the
+ * PROJECT's own document is then reported as the `global` layer. That is a false
+ * claim on the one output this story exists to make trustworthy, so it is
+ * refused with the same code `@skanl/brambo-environment` refuses it with.
+ */
+function scopeRoot(label, value) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new BramboError(BRAMBO_ERROR_CODES.environmentScopeUnavailable, `${label} must be a non-empty path, but brambo was given ${JSON.stringify(value)}`);
+    }
+    return resolve(value);
+}
+/** True when SOMETHING is at this path, target reachable or not. */
+async function entryExists(filePath) {
+    try {
+        await lstat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** What a JSON value IS, for a message that tells the user what to fix. */
+function describeJson(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'an array';
+    return `a ${typeof value}`;
+}
+/**
+ * One configuration document, or `undefined` when there is none.
+ *
+ * The distinction this draws is the whole feature: a MISSING document is an
+ * absent layer, and a document that exists but cannot be used is a coded error.
+ * Reading a corrupt file and shrugging back to the default runs a different
+ * agent than the user configured, silently — which is the failure executor
+ * selection exists to remove, not a robustness feature.
+ *
+ * The `executor` key is type-checked here rather than after composition because
+ * the layer that CARRIES the bad value is the one whose path the user has to be
+ * told; once merged, the offending document is no longer identifiable.
+ */
+async function readConfigDocument(filePath) {
+    let text;
+    try {
+        text = await readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code !== undefined && ABSENT_ERRNOS.has(code)) {
+            // `readFile` FOLLOWS symlinks, so a DANGLING link reports ENOENT exactly
+            // like a file that was never there — and every dotfile manager (stow,
+            // chezmoi, dotbot) materialises brambo's config as a symlink, whose
+            // canonical failure is a broken target. `lstat` looks at the ENTRY rather
+            // than at the target, which is the one thing that tells the two apart.
+            // This is the only present-but-unusable state that would otherwise fall
+            // back to a different agent in silence.
+            if (await entryExists(filePath)) {
+                throw unusable(filePath, 'it exists but its target cannot be read (a dangling symbolic link, or it was removed mid-read)', error);
+            }
+            return undefined;
+        }
+        throw unusable(filePath, `it could not be read (${code ?? 'unknown error'})`, error);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text.startsWith(BYTE_ORDER_MARK) ? text.slice(BYTE_ORDER_MARK.length) : text);
+    }
+    catch (error) {
+        throw unusable(filePath, 'it is not valid JSON', error);
+    }
+    if (!isRecord(parsed)) {
+        throw unusable(filePath, `it must hold a JSON object, but it holds ${describeJson(parsed)}`);
+    }
+    const selected = parsed[EXECUTOR_CONFIG_KEY];
+    if (selected !== undefined && typeof selected !== 'string') {
+        throw unusable(filePath, `'${EXECUTOR_CONFIG_KEY}' must be a string naming one of: ${availableExecutorIds().join(', ')}, but it is ${describeJson(selected)}`);
+    }
+    if (typeof selected === 'string') {
+        // Normalised here so a value an editor appended a newline to still works,
+        // and so a blank one is named for what it is instead of reaching the
+        // catalogue as `'   '` and being reported as a missing ADAPTER — which sends
+        // the user looking for an installation rather than for a typo.
+        const trimmed = selected.trim();
+        if (trimmed.length === 0) {
+            throw unusable(filePath, `'${EXECUTOR_CONFIG_KEY}' is blank; it must name one of: ${availableExecutorIds().join(', ')}`);
+        }
+        parsed[EXECUTOR_CONFIG_KEY] = trimmed;
+    }
+    return parsed;
+}
+/**
+ * Marks a document `readExecutorConfigLayers` actually read off disk.
+ *
+ * Module-private and unforgeable from outside this file. The layer a selection
+ * is reported under is the one printed on stderr — "a swap you cannot see is not
+ * one you can trust" — and without this brand a caller could hand `runSession` a
+ * document it invented, name it `project`, and have `brambo run` print
+ * `selected by the 'project' layer` for a file that does not exist. A supplied
+ * document is composed into the `agent` layer instead: still narrower than the
+ * project document, still reported honestly as coming from the running host.
+ */
+const READ_FROM_DISK = Symbol('brambo.executor-config.read-from-disk');
+function readDocument(filePath, document) {
+    return { filePath, document, [READ_FROM_DISK]: true };
+}
+function wasReadFromDisk(entry) {
+    return entry[READ_FROM_DISK] === true;
+}
+/**
+ * Reads brambo's own documents into layer snapshots. The ONLY filesystem access
+ * in executor selection.
+ *
+ * A MISSING document is an absent layer. A document that exists and cannot be
+ * used is a coded error — reading a corrupt file and shrugging back to the
+ * default runs a different agent than the user configured, silently, which is
+ * the failure this selection exists to remove.
+ */
+export async function readExecutorConfigLayers(options = {}) {
+    // Every field read ONCE, before the first await, for the same reason
+    // `runSession` does it: a live read after control has returned to the caller's
+    // event loop lets an accessor answer with a temp directory now and the real
+    // home directory later.
+    const { executorId, homeDir = homedir(), projectDir = process.cwd() } = options;
+    const home = scopeRoot('the home directory', homeDir);
+    const project = scopeRoot('the project directory', projectDir);
+    const layers = {};
+    // Documents go in whole, not just their `executor` key: `setLayer` is what
+    // rejects a prototype-polluting document, and it can only reject what it sees.
+    const globalPath = executorConfigPath(home);
+    const globalDocument = await readConfigDocument(globalPath);
+    if (globalDocument !== undefined)
+        layers.global = readDocument(globalPath, globalDocument);
+    // Running brambo FROM your home directory is ONE document, not two. Loading it
+    // into both layers reported `project` as the deciding layer for a project that
+    // does not exist — a false provenance on the one line this story adds.
+    if (project !== home) {
+        const projectPath = executorConfigPath(project);
+        const projectDocument = await readConfigDocument(projectPath);
+        if (projectDocument !== undefined)
+            layers.project = readDocument(projectPath, projectDocument);
+    }
+    if (executorId !== undefined) {
+        const requested = executorId.trim();
+        if (requested.length === 0)
+            throw blankExecutor();
+        layers.invocation = { [EXECUTOR_CONFIG_KEY]: requested };
+    }
+    return layers;
+}
+export function seedExecutorConfig(config, layers = {}) {
+    // Brambo's built-in default is a LAYER, never a constructor fallback. That is
+    // what makes "nothing configured" a reportable provenance rather than an
+    // invisible branch. Caller-supplied defaults compose UNDER it, so a document
+    // still wins over both.
+    config.setLayer('defaults', deepMerge(layers.defaults ?? {}, { [EXECUTOR_CONFIG_KEY]: DEFAULT_EXECUTOR_ID }));
+    // A document brambo READ goes into the layer its file belongs to. A document a
+    // caller merely handed over goes into `agent` — the layer for "the running
+    // host supplied this" — so the provenance brambo reports can never be a claim
+    // the caller made up. Two supplied documents compose in the same order.
+    let supplied;
+    let recommendation;
+    for (const layer of ['global', 'project']) {
+        const entry = layers[layer];
+        if (entry === undefined)
+            continue;
+        if (!wasReadFromDisk(entry)) {
+            supplied = supplied === undefined ? entry.document : deepMerge(supplied, entry.document);
+            continue;
+        }
+        // A PROJECT RECOMMENDS A METHOD; IT DOES NOT SELECT ONE, so the key never
+        // becomes part of this layer.
+        //
+        // `assertMethodMayMount` refuses a project-layer method because importing it
+        // is running a cloned repository's code. That refusal was FATAL, and driven
+        // at 220f288 it was wider than the threat: the run stopped whatever else was
+        // configured, so a clone carrying the key denied service to a method the
+        // MACHINE's owner had selected, with hand-editing JSON as the only exit --
+        // the one answer `config-write.ts:10-12` says the product exists to remove.
+        //
+        // DROPPED HERE RATHER THAN AT SELECTION, and that was measured. The obvious
+        // shape is `selectMethod` falling back through `snapshot('global')`, but
+        // `snapshot()` has ZERO production consumers outside the kernel's own
+        // definition, so that would make the method selection the product's only
+        // layer-by-layer reader. Dropping before composition costs no new resolution
+        // rule at all -- and it keeps `dump()` honest, which is the real prize: the
+        // composed view says what brambo ACTED ON, and a gate pins that no entry ever
+        // reports `method` decided by `project`.
+        //
+        // Only a document READ FROM DISK reaches here; one a host supplied composes
+        // into `agent`, which is that host's own code and stays mountable.
+        let document = entry.document;
+        if (layer === 'project' && isRecord(document) && typeof document[METHOD_CONFIG_KEY] === 'string') {
+            const { [METHOD_CONFIG_KEY]: recommended, ...rest } = document;
+            document = rest;
+            recommendation = { specifier: recommended, filePath: entry.filePath };
+        }
+        try {
+            config.setLayer(layer, document);
+        }
+        catch (error) {
+            throw unusable(entry.filePath, `the '${layer}' configuration layer rejected it: ${describeError(error)}`, error);
+        }
+    }
+    if (supplied !== undefined) {
+        try {
+            config.setLayer('agent', supplied);
+        }
+        catch (error) {
+            throw new BramboError(BRAMBO_ERROR_CODES.configurationUnusable, `the configuration this host supplied cannot be used: the 'agent' layer rejected it: ${describeError(error)}`, { cause: error });
+        }
+    }
+    if (layers.invocation !== undefined)
+        config.setLayer('invocation', layers.invocation);
+    if (recommendation === undefined)
+        return undefined;
+    // WHAT IS USED INSTEAD IS READ FROM THE COMPOSED VIEW, NOT GUESSED. Reading
+    // `layers.global` would be a second answer to "which layer decides", and two
+    // answers is how the notice ends up naming a value the run does not use -- the
+    // exact failure `selectExecutor` takes value and provenance from ONE entry to
+    // avoid.
+    const decided = config.dump().find((entry) => entry.path.length === 1 && entry.path[0] === METHOD_CONFIG_KEY);
+    const using = typeof decided?.value === 'string' ? decided.value : undefined;
+    // FOLLOWING THE ADVICE HAS TO SILENCE THE NOTICE.
+    // `brambo swap method ./mine.mjs` run from the project stores the RESOLVED
+    // absolute path, so a user who adopted the recommendation would otherwise be
+    // told it was declined on every run, forever. Advice that nags after being
+    // taken is the same defect class as advice that does nothing, and this
+    // milestone found that one twice.
+    //
+    // `dirname` twice because the project document is `<projectDir>/.brambo/config.json`.
+    if (using !== undefined && resolve(dirname(dirname(recommendation.filePath)), recommendation.specifier) === using) {
+        return undefined;
+    }
+    return { key: METHOD_CONFIG_KEY, specifier: recommendation.specifier, filePath: recommendation.filePath, using };
+}
+/**
+ * The selection an already-seeded configuration decides, with the layer that
+ * decided it. Pure: it reads the composed view and touches no file.
+ */
+export function selectExecutor(config) {
+    // The value AND its provenance from ONE dump entry, so the two cannot disagree.
+    const decided = config
+        .dump()
+        .find((entry) => entry.path.length === 1 && entry.path[0] === EXECUTOR_CONFIG_KEY);
+    if (decided === undefined || typeof decided.value !== 'string') {
+        // Unreachable while `defaults` supplies a string at this path and every
+        // narrower layer was type-checked at its OWN file. Coded rather than
+        // asserted, because the alternative to a message here is `undefined`
+        // reaching the catalogue — and it names NO path, because the one it used to
+        // guess was the project's, which told the user to fix a file that was fine.
+        throw new BramboError(BRAMBO_ERROR_CODES.configurationUnusable, `brambo could not resolve an '${EXECUTOR_CONFIG_KEY}' selection through its configuration layers`);
+    }
+    if (!EXECUTOR_CATALOGUE.has(decided.value))
+        throw unknownExecutor(decided.value);
+    return { executorId: decided.value, layer: decided.layer, available: availableExecutorIds() };
+}
+/**
+ * Which executor this run uses, resolved through the kernel's layered
+ * configuration: `defaults` -> `global` -> `project` -> `invocation`.
+ *
+ * This — not `runSession` — is what reads the filesystem. A session primitive
+ * whose behaviour depends on files under the running user's home is not usable
+ * from a host that already knows what it wants, and it would make every existing
+ * `brambo run` test depend on the `~/.brambo` of whoever ran the suite.
+ *
+ * Ships from `@skanl/brambo-session` beside `runSession`, so FR-29 holds: a third party
+ * imports this package and gets the selection AND the run, with no CLI involved.
+ *
+ * `brambo run` does NOT call this: it reads the layers once and hands them to
+ * `runSession`, which seeds the KERNEL's configuration and selects from that one
+ * composed document. The three steps are exactly the three this function performs.
+ */
+export async function resolveExecutor(options = {}) {
+    const layers = await readExecutorConfigLayers(options);
+    const config = createLayeredConfig();
+    seedExecutorConfig(config, layers);
+    return selectExecutor(config);
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { createSessionKernel, runSession, executeTool, SESSION_ACTION_COST, SESSION_ACTION_ID, type SandboxEvent, type ToolApproval, type ToolApprovalRequest, type ToolCompositionOptions, type ToolExecutionEvent, type ExecuteToolOptions, type SessionKernelOptions, type SessionOptions, } from './run-session.ts';
+export { resolveExecutor, readExecutorConfigLayers, type ExecutorConfigDocument, type ExecutorConfigLayers, type ExecutorSelection, type ResolveExecutorOptions, } from './executors.ts';
+export { resolveMethod, swapMethod } from './methods.ts';
+export { createToolExecutor } from './tool-executor.ts';
+export { createRemoteMcpClient, RemoteMcpError } from './remote-mcp.ts';
+export type { RemoteMcpClient, RemoteMcpClientOptions, RemoteMcpResponse, StreamableHttpTransport } from './remote-mcp.ts';
+export { selectWorkspaceProvider, worktreeStateDir, type WorkspaceProviderSelection } from './workspaces.ts';
+export { inspectWorktrees, removeWorktree, type ClaimedWorktree, type InterruptedRemoval, type UnclaimedDirectory, type WorktreeInspection, type WorktreeOutcome, type WorktreeOutcomeKind, } from '@skanl/brambo-workspace-git-worktree';
+export { inspectLocalWorkspaces, removeLocalWorkspace, type ClaimedLocalWorkspace, type InspectLocalWorkspacesOptions, type LocalWorkspaceInspection, type LocalWorkspaceOutcome, type LocalWorkspaceOutcomeKind, type UnclaimedLocalDirectory, } from '@skanl/brambo-workspace-local';
+export { readUsageReports, recordUsageObservation, usageObservationsPath, type UsageStoreOptions, } from './usage.ts';
+export type { ChildProcessSpawner, CliExecutorAdapterOptions, SpawnedChild, SpawnOptions, SpawnOutcome, } from '@skanl/brambo-adapter-cli';
+export type { ExecutorAdapter, ResultEnvelope, SandboxCapabilityFacts, SandboxPolicy, SandboxProvider, RunRequest, UsageAbsence, UsageObservation, UsageReport, UsageWindow, WorkspaceHandle, WorkspaceProvider, ToolExecutionContext, ToolExecutor, ToolInvocation, ToolResult, } from '@skanl/brambo-contracts';
+export { USAGE_ABSENCE_REASONS } from '@skanl/brambo-contracts';
+export { createLogSink, createMemoryLogSink } from '@skanl/brambo-kernel';
+export type { ActionPolicy, LogRecord, LogSink, MemoryLogSink, BramboKernel } from '@skanl/brambo-kernel';

package/dist/index.js

@@ -0,0 +1,73 @@
+export { createSessionKernel, runSession, executeTool, SESSION_ACTION_COST, SESSION_ACTION_ID, } from './run-session.js';
+// The selection, beside the run it feeds (FR-29). A consumer that imports this
+// package gets BOTH halves of `brambo run` — which executor, and the session —
+// without `@skanl/brambo-cli`. `ExecutorSelection.available` carries the id list, so
+// nothing else of the catalogue has to be on the surface to print alternatives.
+export { resolveExecutor, readExecutorConfigLayers, } from './executors.js';
+// `selectMethod` is deliberately NOT exported: `runSession` is its only caller,
+// and publishing a surface nothing outside consumes is the defect the handoff
+// records for four kernel exports that nothing reads.
+//
+// `swapMethod` IS exported although brambo's own CLI never passes an outgoing
+// method — one CLI process has nothing mounted to unmount. FR-28's ordered swap
+// is delivered to the audience the PRD names first ("brambo ships as an SDK
+// first"): a host with a long-lived kernel. Unexported, the guarantee this story
+// exists to provide would be reachable only from this package's own tests.
+export { resolveMethod, swapMethod } from './methods.js';
+export { createToolExecutor } from './tool-executor.js';
+export { createRemoteMcpClient, RemoteMcpError } from './remote-mcp.js';
+// The workspace selection, beside the executor one and for the same FR-29
+// reason: a consumer that imports only this package can ask which provider a
+// composed configuration names, without `@skanl/brambo-cli`.
+//
+// ONE value, and the trimming is the same call `resolveExecutor`'s block above
+// records: `WorkspaceProviderSelection.available` carries the closed catalogue,
+// so `availableWorkspaceProviderIds` and the id constants would be surface
+// nothing outside consumes. `createSelectedWorkspacePlugin` stays unexported for
+// the harder reason — it hands back a `PluginFactory`, and a factory a caller
+// can invoke with an `ActivationContext` of its own is exactly the bypass
+// surface the block below records five withdrawn exports for.
+export { selectWorkspaceProvider, worktreeStateDir } from './workspaces.js';
+// Taking a worktree back, beside the run that creates one (Story 4.3 / spec
+// M16.A). `brambo run` under the git-worktree provider cuts a real worktree and
+// nothing removed one; these are the two halves of the exit, and they are
+// re-exported for the same FR-29 reason as everything above — a host that
+// installed only this package can look at what brambo holds and take it back,
+// without `@skanl/brambo-cli`. `worktreeStateDir` is what turns a project directory
+// into the argument they take, so the three travel together.
+//
+// `WorktreeLedger` is deliberately NOT here. It is the store these two functions
+// operate through, and publishing it would hand a caller `retire()` and
+// `claimRemoval()` with none of the checks around them — the "no factory a
+// caller can invoke" rule the block below records five withdrawn exports for,
+// pointed at a destructive operation instead of a kernel.
+export { inspectWorktrees, removeWorktree, } from '@skanl/brambo-workspace-git-worktree';
+// The SAME pair for the DEFAULT provider (spec M27.A). `brambo run` under
+// `local` — which is what runs when nothing selects otherwise — creates a
+// directory per session and nothing removed one; these are the two halves of
+// that exit, re-exported for the same FR-29 reason as the worktree pair above.
+//
+// BOTH pairs are on the surface, and that is D4 rather than duplication: a
+// project that switched `workspace.provider` has leftovers of both kinds, so a
+// verb that asked only the currently selected store would strand the other
+// forever. `worktreeStateDir` is the argument both pairs take — `runSession`
+// seeds it as `workspace.rootDir` for whichever provider is mounted — so the
+// two stores are read out of one path and cannot look in different places.
+export { inspectLocalWorkspaces, removeLocalWorkspace, } from '@skanl/brambo-workspace-local';
+// The recorded quota reading, beside the run that produces it (Story M15.A,
+// D7): `brambo run` records, `brambo status` reads, and nothing here invokes an
+// executor. Both halves are exported for the same FR-29 reason as the two
+// selections above — a host that installed only this package gets the whole
+// pair without `@skanl/brambo-cli`.
+export { readUsageReports, recordUsageObservation, usageObservationsPath, } from './usage.js';
+// A VALUE, not a type: `UsageAbsence.reason` is routed on (AD-7), and a consumer
+// that cannot name the codes would have to compare the strings by hand.
+export { USAGE_ABSENCE_REASONS } from '@skanl/brambo-contracts';
+// Two sink constructors, and neither is a factory in the sense the note below
+// withdraws. `createMemoryLogSink` retains; `createLogSink` takes the caller's
+// own write function and retains nothing — it is the bring-your-own-exporter
+// door, and `SessionOptions.log` is the only thing either one is for. What was
+// withdrawn was a factory a caller could invoke with an `ActivationContext` to
+// get back a wired vendor adapter; a function from `LogWrite` to `LogSink`
+// composes nothing and reaches no adapter.
+export { createLogSink, createMemoryLogSink } from '@skanl/brambo-kernel';

package/dist/methods.d.ts

@@ -0,0 +1,137 @@
+import { type MethodActivation, type MethodPlugin } from '@skanl/brambo-contracts';
+/**
+ * Loads a MethodPlugin from a module specifier and validates it against the
+ * published contract.
+ *
+ * The specifier is STORED verbatim — it may be a relative path or a bare package
+ * name, and normalising it would corrupt the second kind — but it is RESOLVED
+ * against `baseDir` before `import()` sees it (see {@link resolveFrom}), because
+ * a specifier the user wrote means what it means where the user is standing.
+ * `baseDir` defaults to `process.cwd()`; every caller in brambo passes the
+ * directory it was pointed at explicitly.
+ *
+ * Validation goes through `validateMethodPlugin` rather than a second copy of
+ * the rules, which is what makes M5.B's "every violation, not the first"
+ * guarantee reach an author here.
+ *
+ * A specifier that will not resolve is a CODED refusal, never an empty result:
+ * a broken selection that behaved like "no method selected" would run a
+ * different methodology than the one configured without saying so, which is the
+ * failure story 2.7c removed for `executor`.
+ */
+export declare function resolveMethod(specifier: string, baseDir?: string): Promise<MethodPlugin>;
+/**
+ * Refuses to MOUNT a selection the `project` layer decided.
+ *
+ * `brambo run` used to import and EXECUTE a module named by the
+ * `.brambo/config.json` of the directory it was run in. Driven against a temp
+ * project holding a `hostile.mjs` whose only statement is a `writeFileSync`:
+ * the run exited 2 and the file existed, while the same project with no
+ * `method` key left it unwritten. Clone a repository, run brambo inside it, and
+ * you have run its author's code.
+ *
+ * A module cannot be inspected without being LOADED, so neither validation nor
+ * reordering can prevent this — `validateMethodPlugin` already refuses the
+ * manifest, and the top-level statements have run by then. The deciding LAYER is
+ * the only fact available before the import, and it is enough to separate a
+ * choice from an arrival: `global` is the machine owner's own document, `agent`
+ * is one a host handed over programmatically and is therefore that host's own
+ * code, and `project` is the one that travels with a clone.
+ *
+ * SECOND LINE OF DEFENCE SINCE M30.D, AND STILL LOAD-BEARING. The ordinary path
+ * no longer reaches this clause: `seedExecutorConfig` drops a `method` key from
+ * a project document READ FROM DISK, so composition yields the next layer and
+ * the run says what it declined. That was the fix for a refusal wider than its
+ * threat — driven, a project key stopped the run whatever else was configured,
+ * so a clone denied service to the machine owner's own selection.
+ *
+ * But a SUPPLIED kernel owns its configuration (`run-session.ts:51`) and never
+ * reaches admission, so a host that seeds its own `project` layer arrives here.
+ * Driven, not assumed: with this clause deleted that path RESOLVES — the module
+ * is imported and the run returns ok. `kernel-composition.test.ts` pins it by
+ * the side effect, because the first version of that clause asserted only the
+ * error code and stayed green with the guard deleted.
+ *
+ * AND AD-5 DOES NOT SAY WHAT THIS COMMENT USED TO SAY IT SAID. It read "REFUSED
+ * rather than ignored, per AD-5", treating the rule as a binary. AD-5 is typed
+ * absence over silence — unavailable is not failed — so its opposite of IGNORED
+ * is TYPED AND REPORTED, not FATAL. Only the silent skip would violate it, which
+ * is why admission reports what it dropped instead of dropping it quietly.
+ *
+ * THE PLACEMENT IS THE GUARANTEE. This must be called between `selectMethod`
+ * and `resolveMethod`. After the import there is nothing left to prevent, and a
+ * check moved there would still pass its own test — which is why the test for
+ * it is falsified by moving it, not only by deleting it.
+ *
+ * WHAT THIS DOES NOT DO, AND THE REASON CHANGED AFTER IT WAS DRIVEN: honour a
+ * project selection brambo ITSELF wrote via `project swap method`. That was
+ * recorded here as merely deferred — "needs ownership tracking on config writes"
+ * — and the roadmap ordered it first because it "removes a restriction rather
+ * than adding a mechanism". Both sentences are wrong.
+ *
+ * An ownership record would prove brambo wrote the NAME. The danger is the module
+ * BYTES, which no record covers and which any `git pull` replaces — and AD-6's
+ * records authorise REMOVAL (`ownedPaths` is "what makes a record authority for a
+ * removal"), never EXECUTION. Reading one here would also need
+ * `@skanl/brambo-session -> @skanl/brambo-projection`, an edge `packages/session/test/guard.test.ts`
+ * pins closed. So it is a mechanism, and it is a trust store wearing an ownership
+ * record's clothes; the honest version of it is the deferred per-directory trust
+ * decision, not a rider on this guard.
+ *
+ * What IS still open, and it is smaller and realer: this refusal is fatal, so a
+ * cloned repository carrying a `method` key denies service to a method the
+ * machine's owner selected for themselves. Falling back to the next layer and
+ * SAYING so would fix that — it renegotiates E1's frozen exit code, which is a
+ * story rather than a rider. Recorded in `deferred-work.md`.
+ */
+export declare function assertMethodMayMount(selected: {
+    readonly specifier: string;
+    readonly layer: string;
+}): void;
+/**
+ * The method a composed configuration selects, with the layer that decided it —
+ * the same shape and the same `dump()` read `selectExecutor` uses, so the two
+ * selections cannot disagree about what a layer means.
+ *
+ * THIS BLOCK USED TO SIT ABOVE `assertMethodMayMount`'s OWN JSDoc, so it bound to
+ * nothing: measured on the emitted surface, `dist/methods.d.ts` declared
+ * `selectMethod` with no documentation at all, and the guard's text cited "`selectMethod`'s
+ * own rule right below" for a rule that documented nothing and did not ship.
+ *
+ * `undefined` is the ORDINARY state in v1 and is not a failure: PRD §6.2 places
+ * methodologies post-v1, so most runs select none and must cost nothing. A
+ * selection that is present but not a usable string IS a failure, because a
+ * `method: 42` silently ignored is a run using a different methodology than the
+ * document names.
+ *
+ * It never sees a `project` layer from a document brambo read: `seedExecutorConfig`
+ * drops that key before composition, which is what keeps `dump()` honest about
+ * the layer brambo acted on.
+ */
+export declare function selectMethod(config: {
+    dump(): readonly {
+        readonly path: readonly string[];
+        readonly value: unknown;
+        readonly layer: string;
+    }[];
+}): {
+    readonly specifier: string;
+    readonly layer: string;
+} | undefined;
+/**
+ * Mounts `incoming`, unmounting `outgoing` first — FR-28's ordering, and the
+ * only place it is provable.
+ *
+ * The outgoing teardown is AWAITED TO SETTLEMENT before the incoming hook is
+ * called. Not "started before": a swap that overlapped them would let a
+ * methodology's templates be removed while the next one's were being written,
+ * and the two orders are indistinguishable from the outside until they collide.
+ *
+ * A failed teardown REFUSES the swap instead of mounting the incoming anyway.
+ * A half-swapped environment is worse than a refused one, because nothing
+ * reports it: the outgoing believes it is unmounted, the incoming was never
+ * asked, and the next run inherits both beliefs.
+ *
+ * `outgoing` is `undefined` at a session start, which is the ordinary case.
+ */
+export declare function swapMethod(outgoing: MethodActivation | undefined, incoming: MethodPlugin): Promise<MethodActivation>;