mellos-mapping 0.20.3 → 0.23.0

package/lib/store/channels.js

@@ -0,0 +1,135 @@
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { makePageId } from './format.js';
+import { isRecord, stripBom } from './json-text.js';
+import { viewersDirPath } from './viewers.js';
+// ---------------------------------------------------------------------------
+// focus requests — "show this page" messages from pane openers to the watcher
+// ---------------------------------------------------------------------------
+//
+// State files flow one way, MCP server → watcher; a launcher that wants an
+// ALREADY-RUNNING pane to show a particular page has no channel to it. The
+// focus file is that channel, one-shot on purpose: the watcher consumes the
+// request AND DELETES the file, so a request lives about one poll tick —
+// nothing stale survives to misdirect tomorrow's pane, and the project's git
+// status barely ever sees the file exist.
+/** Sibling of the default file carrying a one-shot "show this page" request. */
+export const FOCUS_FILE_NAME = 'focus';
+export function focusFilePath(defaultFile, pid) {
+    return paneChannelPath(defaultFile, FOCUS_FILE_NAME, pid);
+}
+/** A targeted message cannot be consumed by another pane of the same project. */
+function paneChannelPath(defaultFile, channel, pid) {
+    if (pid === undefined)
+        return join(dirname(defaultFile), channel);
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        throw new Error('Invalid pane process id');
+    return join(viewersDirPath(defaultFile), `${pid}.${channel}`);
+}
+/**
+ * Consume a pending focus request: read it, delete the file, return it.
+ * Absent file — the overwhelmingly common case — or junk content means no
+ * request; the channel is best-effort and junk is swept by the same delete.
+ */
+export function takeFocusRequest(defaultFile, pid) {
+    const targeted = pid === undefined ? undefined : focusFilePath(defaultFile, pid);
+    const path = targeted !== undefined && existsSync(targeted) ? targeted : focusFilePath(defaultFile);
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        rmSync(path, { force: true });
+    }
+    catch {
+        // deletion is a courtesy: re-consuming next tick is harmless because
+        // switching to the already-shown page is a no-op
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const page = parsed.page;
+    if (page === undefined || page === null)
+        return { page: undefined };
+    if (typeof page !== 'string')
+        return undefined;
+    const id = makePageId(page);
+    return id.ok ? { page: id.value } : undefined;
+}
+// ---------------------------------------------------------------------------
+// quit requests — "close yourself" messages from the toggle to the watcher
+// ---------------------------------------------------------------------------
+//
+// The mirror of the focus file, and there for the same reason: a human who
+// types `mmap` in some OTHER terminal has no channel to the pane that is
+// already running. The quit file is that channel, one-shot on purpose — the
+// watcher consumes the request AND DELETES the file, so a request lives about
+// one poll tick and nothing stale survives to close tomorrow's pane.
+//
+// The request carries no payload. A pane belongs to one store, so "close the
+// pane watching this store" has nothing to say beyond being asked.
+/** Sibling of the default file carrying a one-shot "close the pane" request. */
+export const QUIT_FILE_NAME = 'quit';
+export function quitFilePath(defaultFile, pid) {
+    return paneChannelPath(defaultFile, QUIT_FILE_NAME, pid);
+}
+/**
+ * Consume a pending quit request: read it, delete the file, say whether there
+ * was one. Absent file — the overwhelmingly common case — or content that is
+ * not a JSON object means NO request; the channel is best-effort and junk is
+ * swept by the same delete.
+ *
+ * The empty JSON object is the whole grammar. It exists so that a stray file
+ * of this name — an editor backup, a half-written write from a foreign tool —
+ * cannot take a live pane down by accident; a pane closing is the one thing
+ * in this channel a user cannot undo by waiting.
+ */
+export function takeQuitRequest(defaultFile, pid) {
+    const targeted = pid === undefined ? undefined : quitFilePath(defaultFile, pid);
+    const path = targeted !== undefined && existsSync(targeted) ? targeted : quitFilePath(defaultFile);
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    sweepQuitRequest(defaultFile, path === targeted ? pid : undefined);
+    let parsed;
+    try {
+        parsed = JSON.parse(stripBom(raw));
+    }
+    catch {
+        return false;
+    }
+    return isRecord(parsed);
+}
+/**
+ * Delete a quit request WITHOUT acting on it — the same file, read as a
+ * leftover rather than as a message.
+ *
+ * A toggle that wrote the request and then lost its watcher (a crash, a
+ * closed window, a `taskkill`) leaves the file behind, and the next pane to
+ * open would consume it on its first tick and close instantly. The watcher
+ * sweeps at STARTUP for exactly that: a request that predates the pane cannot
+ * have been addressed to it. Best-effort, like every delete in this channel.
+ */
+export function sweepQuitRequest(defaultFile, pid) {
+    try {
+        rmSync(quitFilePath(defaultFile, pid), { force: true });
+    }
+    catch {
+        // The file is unreachable for some reason the next tick will meet again;
+        // re-consuming a request we cannot delete only closes a pane the user
+        // asked to close.
+    }
+}

package/lib/store/format.js

@@ -21,6 +21,8 @@
  * ./store.ts, the Node-side half.
  */
 import { declareGroup, declareLane, declareLayer, declareNode, linkNodes, setKind, setTitle, updateNode } from '../domain/ops.js';
+import { mapTextError } from '../domain/text.js';
+import { sourceError, contextError } from '../domain/context.js';
 import { EMPTY_MAP, ID_RULE, ID_RULE_TEXT, describeMapError, err, makeGroupId, makeLaneId, makeLayerId, makeMapKind, makeNodeId, makeNodeKind, makeNodeStatus, makeRank, makeSubmapRef, ok, } from '../domain/types.js';
 /** On-disk format version. Bump only with a documented migration. */
 export const STATE_FILE_VERSION = 1;
@@ -98,8 +100,8 @@ function optionalString(rec, key, where, path) {
 export function parseMap(raw, path) {
     if (!isRecord(raw))
         return err({ kind: 'bad-shape', path, detail: 'root is not an object' });
-    if (raw['version'] !== STATE_FILE_VERSION) {
-        return err({ kind: 'bad-shape', path, detail: `version is ${String(raw['version'])}, expected ${STATE_FILE_VERSION}` });
+    if (raw['version'] !== STATE_FILE_VERSION && raw['version'] !== 2) {
+        return err({ kind: 'bad-shape', path, detail: `version is ${String(raw['version'])}, expected ${STATE_FILE_VERSION} or 2` });
     }
     const layers = arrayField(raw, 'layers', path, 'required');
     if (!layers.ok)
@@ -117,6 +119,12 @@ export function parseMap(raw, path) {
     if (!groups.ok)
         return groups;
     let map = EMPTY_MAP;
+    if (raw['context'] !== undefined) {
+        const error = contextError(raw['context']);
+        if (error)
+            return err({ kind: 'bad-shape', path, detail: error });
+        map = { ...map, context: raw['context'] };
+    }
     const title = optionalString(raw, 'title', 'map', path);
     if (!title.ok)
         return title;
@@ -291,6 +299,12 @@ export function parseMap(raw, path) {
                 return err({ kind: 'invariant-violation', path, violation: updated.error });
             map = updated.value;
         }
+        if (rawNode['sources'] !== undefined) {
+            const error = sourceError(rawNode['sources']);
+            if (error)
+                return err({ kind: 'bad-shape', path, detail: `${where}: ${error}` });
+            map = { ...map, nodes: map.nodes.map(n => n.id === id.value ? { ...n, sources: rawNode['sources'] } : n) };
+        }
     }
     for (const [i, rawEdge] of edges.value.entries()) {
         const where = `edges[${i}]`;
@@ -316,12 +330,15 @@ export function parseMap(raw, path) {
             return err({ kind: 'invariant-violation', path, violation: linked.error });
         map = linked.value;
     }
-    return ok(map);
+    const textError = mapTextError(map);
+    return textError ? err({ kind: 'bad-shape', path, detail: textError }) : ok(map);
 }
 /** Serialize a map into the on-disk shape. Inverse of parseMap for valid maps (F1). */
 export function serializeMap(map) {
     const body = {
-        version: STATE_FILE_VERSION,
+        // Older runtimes must refuse maps with provenance rather than silently erasing it.
+        version: map.context !== undefined || map.nodes.some(n => n.sources !== undefined) ? 2 : STATE_FILE_VERSION,
+        ...(map.context !== undefined ? { context: map.context } : {}),
         ...(map.title !== undefined ? { title: map.title } : {}),
         ...(map.kind !== undefined ? { kind: map.kind } : {}),
         layers: map.layers,

package/lib/store/json-text.d.ts

@@ -0,0 +1,9 @@
+export declare function isRecord(v: unknown): v is Record<string, unknown>;
+/**
+ * Drop a leading UTF-8 byte-order mark. Windows editors (Notepad, some
+ * PowerShell redirections) add one when a human edits a state file by hand,
+ * and JSON.parse refuses the result — an invisible character would otherwise
+ * read as "your map is corrupt". The BOM carries no meaning for us: the
+ * files are UTF-8 by contract.
+ */
+export declare function stripBom(text: string): string;

package/lib/store/json-text.js

@@ -0,0 +1,16 @@
+// ---------------------------------------------------------------------------
+// reading text that a human may have touched — shared by every load below
+// ---------------------------------------------------------------------------
+export function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Drop a leading UTF-8 byte-order mark. Windows editors (Notepad, some
+ * PowerShell redirections) add one when a human edits a state file by hand,
+ * and JSON.parse refuses the result — an invisible character would otherwise
+ * read as "your map is corrupt". The BOM carries no meaning for us: the
+ * files are UTF-8 by contract.
+ */
+export function stripBom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}

package/lib/store/maps.d.ts

@@ -0,0 +1,12 @@
+import { type MellosMap, type Result } from '../domain/types.js';
+import { type StoreError } from './format.js';
+/** Load and validate the map file at `path`. */
+export declare function loadMapFile(path: string): Result<MellosMap, StoreError>;
+/**
+ * Write the map to `path` atomically (P2): serialize to a private sibling
+ * temp file, then rename it over the target, retrying a rename the OS
+ * refuses transiently. Creates the parent directory if missing.
+ * @returns ok when the file holds the new map; save-failed when it does not,
+ *   in which case the previous content is intact and the call may be retried.
+ */
+export declare function saveMapFile(path: string, map: MellosMap): Result<void, StoreError>;

package/lib/store/maps.js

@@ -0,0 +1,42 @@
+import { readFileSync } from 'node:fs';
+import { err } from '../domain/types.js';
+import { mapTextError } from '../domain/text.js';
+import { parseMap, serializeMap } from './format.js';
+import { writeFileAtomic } from './atomic.js';
+import { stripBom } from './json-text.js';
+/** Load and validate the map file at `path`. */
+export function loadMapFile(path) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 'ENOENT')
+            return err({ kind: 'not-found', path });
+        throw e; // unexpected I/O fault: fail fast, nothing meaningful to recover here
+    }
+    let raw;
+    try {
+        raw = JSON.parse(stripBom(text));
+    }
+    catch (e) {
+        // Expected at this boundary: hand-edited files, or a reader racing a
+        // non-atomic writer from a foreign tool.
+        return err({ kind: 'malformed-json', path, detail: e.message });
+    }
+    return parseMap(raw, path);
+}
+/**
+ * Write the map to `path` atomically (P2): serialize to a private sibling
+ * temp file, then rename it over the target, retrying a rename the OS
+ * refuses transiently. Creates the parent directory if missing.
+ * @returns ok when the file holds the new map; save-failed when it does not,
+ *   in which case the previous content is intact and the call may be retried.
+ */
+export function saveMapFile(path, map) {
+    const textError = mapTextError(map);
+    if (textError)
+        return err({ kind: 'save-failed', path, detail: textError });
+    return writeFileAtomic(path, serializeMap(map));
+}

package/lib/store/migration.d.ts

@@ -0,0 +1,12 @@
+/** Project-relative location of the pre-0.20 default page file. */
+export declare const LEGACY_STATE_FILE_RELATIVE_PATH: string;
+/**
+ * Move a legacy `.claude` store — map, pages, and mapping-policy config —
+ * into the tool-owned `.mellos` location. Never merges: a project whose new
+ * store already holds anything keeps it untouched, whatever the legacy
+ * directory still contains.
+ * @param defaultFile - the NEW default page path (`<root>/.mellos/map.json`);
+ *   the legacy store is looked up relative to `<root>`.
+ * @returns whether a legacy store was moved.
+ */
+export declare function migrateLegacyStore(defaultFile: string): boolean;

package/lib/store/migration.js

@@ -0,0 +1,46 @@
+import { existsSync, mkdirSync, renameSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { PAGES_DIR_NAME } from './pages.js';
+import { configFilePath } from './policy.js';
+// ---------------------------------------------------------------------------
+// legacy migration — stores written under the old host-coupled location
+// ---------------------------------------------------------------------------
+//
+// Up to 0.19 the store lived in `.claude/mellos-mapping.*`: the map's home
+// was coupled to one host brand, which turned absurd the moment another host
+// (a harness, Codex) drove the same server. The move is one-time and
+// explicit — entry points call it before touching the store; nothing here
+// runs as a hidden side effect of ordinary loads.
+/** Project-relative location of the pre-0.20 default page file. */
+export const LEGACY_STATE_FILE_RELATIVE_PATH = join('.claude', 'mellos-mapping.json');
+const LEGACY_PAGES_DIR_NAME = 'mellos-mapping.pages';
+const LEGACY_CONFIG_FILE_NAME = 'mellos-mapping.config.json';
+/**
+ * Move a legacy `.claude` store — map, pages, and mapping-policy config —
+ * into the tool-owned `.mellos` location. Never merges: a project whose new
+ * store already holds anything keeps it untouched, whatever the legacy
+ * directory still contains.
+ * @param defaultFile - the NEW default page path (`<root>/.mellos/map.json`);
+ *   the legacy store is looked up relative to `<root>`.
+ * @returns whether a legacy store was moved.
+ */
+export function migrateLegacyStore(defaultFile) {
+    const projectRoot = dirname(dirname(defaultFile));
+    const legacyDefault = join(projectRoot, LEGACY_STATE_FILE_RELATIVE_PATH);
+    const legacyPages = join(dirname(legacyDefault), LEGACY_PAGES_DIR_NAME);
+    const legacyConfig = join(dirname(legacyDefault), LEGACY_CONFIG_FILE_NAME);
+    const hasLegacy = existsSync(legacyDefault) || existsSync(legacyPages) || existsSync(legacyConfig);
+    const hasCurrent = existsSync(defaultFile)
+        || existsSync(join(dirname(defaultFile), PAGES_DIR_NAME))
+        || existsSync(configFilePath(defaultFile));
+    if (!hasLegacy || hasCurrent)
+        return false;
+    mkdirSync(dirname(defaultFile), { recursive: true });
+    if (existsSync(legacyDefault))
+        renameSync(legacyDefault, defaultFile);
+    if (existsSync(legacyPages))
+        renameSync(legacyPages, join(dirname(defaultFile), PAGES_DIR_NAME));
+    if (existsSync(legacyConfig))
+        renameSync(legacyConfig, configFilePath(defaultFile));
+    return true;
+}

package/lib/store/pages.d.ts

@@ -0,0 +1,46 @@
+import { type Result } from '../domain/types.js';
+import { type StoreError } from './format.js';
+import { type PageId } from './format.js';
+/**
+ * The directory a store lives in, under a project root or under a user's home.
+ * It is tool-owned: the map belongs to mellos-mapping, not to whichever host
+ * (Claude Code, Codex, a harness) happens to drive the server, so no host
+ * brand appears in the path. Pre-0.20 stores under `.claude/` are moved once
+ * by {@link migrateLegacyStore}.
+ */
+export declare const STORE_DIR_NAME = ".mellos";
+/** Project-relative location of the DEFAULT page's state file. */
+export declare const STATE_FILE_RELATIVE_PATH: string;
+/** Directory (next to the default file) holding the named pages. */
+export declare const PAGES_DIR_NAME = "pages";
+/** Where a page's map file lives, given the default page's file path. */
+export declare function pageFilePath(defaultFile: string, page?: PageId): string;
+/** The page id a file path denotes; undefined = the default page. */
+export declare function pageIdOfFile(defaultFile: string, path: string): PageId | undefined;
+/** Existing page files: the default page first (when present), then named pages sorted by slug. */
+export declare function listPageFiles(defaultFile: string): string[];
+/**
+ * Delete one page's file — a named page, or the DEFAULT page (whose file is
+ * optional by design, so removing it is a legal state, not a mutilation).
+ *
+ * Preconditions: none. Postcondition on ok: no file at `path` — an already
+ * absent one is ok too, because the goal state is what is promised, not the
+ * act. Postcondition on error: the file is still there and the caller may
+ * retry or report; the errno is carried in the detail.
+ *
+ * Concurrency, stated plainly: deletion races a concurrent writer and THE
+ * WRITER WINS. A server saving that page while this runs simply recreates the
+ * file (its rename is atomic and needs no existing target), so the page comes
+ * back. That is accepted rather than defended against — the store has no
+ * lost-update protection anywhere (see the module header), and locking one
+ * operation would only make the race rarer, never absent, while claiming
+ * otherwise. Pages are the isolation unit: nobody deletes a page another
+ * session is writing.
+ *
+ * What it deliberately does NOT do: sweep `<path>.<pid>.<random>.tmp`
+ * siblings. Those temps are private to a save IN FLIGHT, and a live writer
+ * whose temp vanished would fail its rename — turning a harmless leftover
+ * into a broken save. A stray temp only exists when a write failed AND its
+ * own cleanup failed; it is inert, and the README documents it.
+ */
+export declare function deletePageFile(path: string): Result<void, StoreError>;

package/lib/store/pages.js

@@ -0,0 +1,89 @@
+import { existsSync, readdirSync, rmSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { err, ok } from '../domain/types.js';
+import { errnoOf } from './atomic.js';
+/**
+ * The directory a store lives in, under a project root or under a user's home.
+ * It is tool-owned: the map belongs to mellos-mapping, not to whichever host
+ * (Claude Code, Codex, a harness) happens to drive the server, so no host
+ * brand appears in the path. Pre-0.20 stores under `.claude/` are moved once
+ * by {@link migrateLegacyStore}.
+ */
+export const STORE_DIR_NAME = '.mellos';
+/** Project-relative location of the DEFAULT page's state file. */
+export const STATE_FILE_RELATIVE_PATH = join(STORE_DIR_NAME, 'map.json');
+// ---------------------------------------------------------------------------
+// pages — a project may keep several maps side by side (one effort = one page)
+// ---------------------------------------------------------------------------
+//
+// The default page IS the classic map.json. Named pages live in a sibling
+// directory, one file each: file-per-page keeps concurrent sessions isolated —
+// two writers on two pages can never clobber each other, because every save
+// renames a whole file.
+/** Directory (next to the default file) holding the named pages. */
+export const PAGES_DIR_NAME = 'pages';
+/** Where a page's map file lives, given the default page's file path. */
+export function pageFilePath(defaultFile, page) {
+    return page === undefined ? defaultFile : join(dirname(defaultFile), PAGES_DIR_NAME, `${page}.json`);
+}
+/** The page id a file path denotes; undefined = the default page. */
+export function pageIdOfFile(defaultFile, path) {
+    if (path === defaultFile)
+        return undefined;
+    const name = basename(path);
+    return name.endsWith('.json') ? name.slice(0, -'.json'.length) : name;
+}
+/** Existing page files: the default page first (when present), then named pages sorted by slug. */
+export function listPageFiles(defaultFile) {
+    const out = [];
+    if (existsSync(defaultFile))
+        out.push(defaultFile);
+    let entries = [];
+    try {
+        entries = readdirSync(join(dirname(defaultFile), PAGES_DIR_NAME));
+    }
+    catch {
+        // no pages directory — a single-page project, the common case
+    }
+    for (const e of entries.sort()) {
+        if (e.endsWith('.json'))
+            out.push(join(dirname(defaultFile), PAGES_DIR_NAME, e));
+    }
+    return out;
+}
+/**
+ * Delete one page's file — a named page, or the DEFAULT page (whose file is
+ * optional by design, so removing it is a legal state, not a mutilation).
+ *
+ * Preconditions: none. Postcondition on ok: no file at `path` — an already
+ * absent one is ok too, because the goal state is what is promised, not the
+ * act. Postcondition on error: the file is still there and the caller may
+ * retry or report; the errno is carried in the detail.
+ *
+ * Concurrency, stated plainly: deletion races a concurrent writer and THE
+ * WRITER WINS. A server saving that page while this runs simply recreates the
+ * file (its rename is atomic and needs no existing target), so the page comes
+ * back. That is accepted rather than defended against — the store has no
+ * lost-update protection anywhere (see the module header), and locking one
+ * operation would only make the race rarer, never absent, while claiming
+ * otherwise. Pages are the isolation unit: nobody deletes a page another
+ * session is writing.
+ *
+ * What it deliberately does NOT do: sweep `<path>.<pid>.<random>.tmp`
+ * siblings. Those temps are private to a save IN FLIGHT, and a live writer
+ * whose temp vanished would fail its rename — turning a harmless leftover
+ * into a broken save. A stray temp only exists when a write failed AND its
+ * own cleanup failed; it is inert, and the README documents it.
+ */
+export function deletePageFile(path) {
+    try {
+        // force: an absent file is the goal state already, not a failure.
+        // No `recursive`: a DIRECTORY where a page file belongs is a fault to
+        // report, never a tree to erase.
+        rmSync(path, { force: true });
+        return ok(undefined);
+    }
+    catch (e) {
+        return err({ kind: 'delete-failed', path, detail: errnoOf(e) });
+    }
+}

package/lib/store/policy.d.ts

@@ -0,0 +1,74 @@
+import { type Result } from '../domain/types.js';
+import { type StoreError } from './format.js';
+/** Name of the file holding a mapping-policy configuration, in either scope. */
+export declare const CONFIG_FILE_NAME = "config.json";
+/** On-disk config format version. Bump only with a documented migration. */
+export declare const CONFIG_FILE_VERSION = 1;
+/** The PROJECT-scope configuration file: sibling of the default page. */
+export declare function configFilePath(defaultFile: string): string;
+/**
+ * The USER-scope configuration file: the same store directory name, under the
+ * user's own base directory.
+ *
+ * @param userBase - the user's home directory. Always passed in, never read
+ *   from the environment down here: a function that reached for os.homedir()
+ *   itself would make every spec a gamble on the developer's real
+ *   configuration, and one of them would eventually write it. Entry points
+ *   resolve the home once and hand it down.
+ */
+export declare function userConfigFilePath(userBase: string): string;
+export declare const MAPPING_POLICIES: readonly ["always", "complex", "on-request"];
+/** How eagerly maps are opened; 'complex' is the behavior of an unconfigured project. */
+export type MappingPolicy = (typeof MAPPING_POLICIES)[number];
+export interface InvalidPolicy {
+    readonly kind: 'invalid-policy';
+    readonly raw: string;
+    readonly allowed: readonly string[];
+}
+export declare function makeMappingPolicy(raw: string): Result<MappingPolicy, InvalidPolicy>;
+/** One line of meaning per policy — the wording every surface repeats. */
+export declare function describeMappingPolicy(policy: MappingPolicy): string;
+/**
+ * The policy recorded in ONE configuration file, or ok(undefined) when nobody
+ * has chosen there (missing file or missing key — both mean the same thing).
+ * A file that exists but does not parse is an error, never silently ignored.
+ *
+ * @param path - the configuration file itself: {@link configFilePath} for a
+ *   project, {@link userConfigFilePath} for the user. One loader, two scopes.
+ */
+export declare function loadMappingPolicy(path: string): Result<MappingPolicy | undefined, StoreError>;
+/**
+ * Persist the policy atomically (P2), same write as the map files.
+ * @param path - the configuration file to write; see {@link loadMappingPolicy}.
+ * @returns ok when the file holds the policy; save-failed leaves the previous
+ *   configuration in place.
+ */
+export declare function saveMappingPolicy(path: string, policy: MappingPolicy): Result<void, StoreError>;
+/** The two places a mapping policy can be recorded, in override order. */
+export declare const POLICY_SCOPES: readonly ["user", "project"];
+export type PolicyScope = (typeof POLICY_SCOPES)[number];
+/** What both scopes say, and which of them actually governs. */
+export interface MappingPolicyScopes {
+    readonly project: MappingPolicy | undefined;
+    readonly user: MappingPolicy | undefined;
+    /** What to act on. undefined = nobody has chosen yet, anywhere. */
+    readonly effective: MappingPolicy | undefined;
+    /** Where `effective` came from; undefined exactly when `effective` is. */
+    readonly source: PolicyScope | undefined;
+}
+/**
+ * Resolve the policy that governs this project: the PROJECT file if it names
+ * one, otherwise the USER file, otherwise nothing.
+ *
+ * Both scopes are reported, not just the winner — a surface that says "always"
+ * without saying where it came from cannot tell a user why changing their
+ * user-level choice did nothing here.
+ *
+ * @param projectConfigFile - see {@link configFilePath}.
+ * @param userConfigFile - see {@link userConfigFilePath}.
+ * @returns err as soon as EITHER file exists and is broken, project first: a
+ *   configuration nobody can read is not the same as a configuration nobody
+ *   wrote, and silently falling through to the other scope would act on a
+ *   choice the user did not make.
+ */
+export declare function effectiveMappingPolicy(projectConfigFile: string, userConfigFile: string): Result<MappingPolicyScopes, StoreError>;