mellos-mapping 0.20.0 → 0.20.2

package/lib/store/format.js

@@ -9,6 +9,11 @@
  *       operations, so a hand-edited or corrupted file can never smuggle an
  *       invariant violation into the process (validate at the boundary,
  *       trust internal code afterwards).
+ *       The shape is read STRICTLY: a wrong type is refused, never coerced
+ *       and never quietly dropped. The reason is that the store round-trips —
+ *       a lenient read of `{"nodes": {...}}` as "no nodes" would be written
+ *       back by the next save, so leniency here does not tolerate a damaged
+ *       file, it destroys one.
  *   F1. serializeMap is the inverse of parseMap for valid maps.
  *
  * No node:* imports — this module must load in a browser as-is. Filesystem
@@ -16,7 +21,7 @@
  * ./store.ts, the Node-side half.
  */
 import { declareGroup, declareLane, declareLayer, declareNode, linkNodes, setKind, setTitle, updateNode } from '../domain/ops.js';
-import { EMPTY_MAP, ID_RULE, ID_RULE_TEXT, describeMapError, err, makeGroupId, makeLaneId, makeLayerId, makeMapKind, makeNodeId, makeNodeKind, makeNodeStatus, makeSubmapRef, ok, } from '../domain/types.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;
 export function makePageId(raw) {
@@ -32,16 +37,57 @@ export function describeStoreError(e) {
             return `map file ${e.path} has an unexpected shape: ${e.detail}`;
         case 'invariant-violation':
             return `map file ${e.path} violates a structural invariant: ${describeMapError(e.violation)}`;
+        case 'save-failed':
+            return `could not write ${e.path}: ${e.detail}`;
+        case 'delete-failed':
+            return `could not delete ${e.path}: ${e.detail}`;
     }
 }
 function isRecord(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
-function asArray(v) {
-    return Array.isArray(v) ? v : [];
+/** How a refused value is named in a bad-shape detail. */
+function describeValue(v) {
+    if (v === undefined)
+        return 'missing';
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'an array';
+    return `a ${typeof v}`;
 }
-function optionalString(v) {
-    return typeof v === 'string' ? v : undefined;
+function badShape(path, where, expected, got) {
+    return err({ kind: 'bad-shape', path, detail: `${where} is ${describeValue(got)}, expected ${expected}` });
+}
+/**
+ * A list field of the file.
+ * @param presence - 'optional' lets the KEY be absent (an unused feature
+ *   writes no key at all); a present non-array is refused either way.
+ *
+ * Coercing a non-array to an empty list is the one shape mistake this
+ * boundary must never make: `{"nodes": {...}}` would parse as a map with no
+ * nodes, and the next save would write that empty interpretation over the
+ * file — the boundary erasing the data it exists to protect.
+ */
+function arrayField(raw, key, path, presence) {
+    const v = raw[key];
+    if (Array.isArray(v))
+        return ok(v);
+    if (v === undefined && presence === 'optional')
+        return ok([]);
+    return badShape(path, `"${key}"`, 'an array', v);
+}
+/** A field that must be a string. Numbers and booleans are refused, never coerced. */
+function requiredString(rec, key, where, path) {
+    const v = rec[key];
+    return typeof v === 'string' ? ok(v) : badShape(path, `${where}.${key}`, 'a string', v);
+}
+/** A field that may be absent, but must be a string when present — never dropped for being the wrong type. */
+function optionalString(rec, key, where, path) {
+    const v = rec[key];
+    if (v === undefined)
+        return ok(undefined);
+    return typeof v === 'string' ? ok(v) : badShape(path, `${where}.${key}`, 'a string', v);
 }
 /**
  * Rebuild a MellosMap from untrusted raw data by replaying it through the
@@ -55,118 +101,179 @@ export function parseMap(raw, path) {
     if (raw['version'] !== STATE_FILE_VERSION) {
         return err({ kind: 'bad-shape', path, detail: `version is ${String(raw['version'])}, expected ${STATE_FILE_VERSION}` });
     }
+    const layers = arrayField(raw, 'layers', path, 'required');
+    if (!layers.ok)
+        return layers;
+    const nodes = arrayField(raw, 'nodes', path, 'required');
+    if (!nodes.ok)
+        return nodes;
+    const edges = arrayField(raw, 'edges', path, 'required');
+    if (!edges.ok)
+        return edges;
+    const lanes = arrayField(raw, 'lanes', path, 'optional');
+    if (!lanes.ok)
+        return lanes;
+    const groups = arrayField(raw, 'groups', path, 'optional');
+    if (!groups.ok)
+        return groups;
     let map = EMPTY_MAP;
-    const title = optionalString(raw['title']);
-    if (title !== undefined)
-        map = setTitle(map, title);
-    const rawKind = optionalString(raw['kind']);
-    if (rawKind !== undefined) {
-        const kind = makeMapKind(rawKind);
+    const title = optionalString(raw, 'title', 'map', path);
+    if (!title.ok)
+        return title;
+    if (title.value !== undefined)
+        map = setTitle(map, title.value);
+    const rawKind = optionalString(raw, 'kind', 'map', path);
+    if (!rawKind.ok)
+        return rawKind;
+    if (rawKind.value !== undefined) {
+        const kind = makeMapKind(rawKind.value);
         if (!kind.ok)
             return err({ kind: 'invariant-violation', path, violation: kind.error });
         map = setKind(map, kind.value);
     }
-    for (const [i, rawLayer] of asArray(raw['layers']).entries()) {
+    for (const [i, rawLayer] of layers.value.entries()) {
+        const where = `layers[${i}]`;
         if (!isRecord(rawLayer))
-            return err({ kind: 'bad-shape', path, detail: `layers[${i}] is not an object` });
-        const id = makeLayerId(String(rawLayer['id'] ?? ''));
+            return badShape(path, where, 'an object', rawLayer);
+        const rawId = requiredString(rawLayer, 'id', where, path);
+        if (!rawId.ok)
+            return rawId;
+        const id = makeLayerId(rawId.value);
         if (!id.ok)
             return err({ kind: 'invariant-violation', path, violation: id.error });
-        const name = optionalString(rawLayer['name']);
-        const rank = rawLayer['rank'];
-        if (name === undefined || typeof rank !== 'number' || !Number.isInteger(rank)) {
-            return err({ kind: 'bad-shape', path, detail: `layers[${i}] needs a string name and an integer rank` });
-        }
-        const next = declareLayer(map, { id: id.value, name, rank });
+        const name = requiredString(rawLayer, 'name', where, path);
+        if (!name.ok)
+            return name;
+        const rawRank = rawLayer['rank'];
+        if (typeof rawRank !== 'number')
+            return badShape(path, `${where}.rank`, 'a number', rawRank);
+        // The RANGE and integrality of a rank are the domain's rule (makeRank),
+        // never restated here: a file the format accepted but the domain refuses
+        // is exactly the drift this boundary exists to prevent.
+        const rank = makeRank(rawRank);
+        if (!rank.ok)
+            return err({ kind: 'invariant-violation', path, violation: rank.error });
+        const next = declareLayer(map, { id: id.value, name: name.value, rank: rank.value });
         if (!next.ok)
             return err({ kind: 'invariant-violation', path, violation: next.error });
         map = next.value;
     }
-    for (const [i, rawLane] of asArray(raw['lanes']).entries()) {
+    for (const [i, rawLane] of lanes.value.entries()) {
+        const where = `lanes[${i}]`;
         if (!isRecord(rawLane))
-            return err({ kind: 'bad-shape', path, detail: `lanes[${i}] is not an object` });
-        const id = makeLaneId(String(rawLane['id'] ?? ''));
+            return badShape(path, where, 'an object', rawLane);
+        const rawId = requiredString(rawLane, 'id', where, path);
+        if (!rawId.ok)
+            return rawId;
+        const id = makeLaneId(rawId.value);
         if (!id.ok)
             return err({ kind: 'invariant-violation', path, violation: id.error });
-        const label = optionalString(rawLane['label']);
-        if (label === undefined)
-            return err({ kind: 'bad-shape', path, detail: `lanes[${i}] needs a string label` });
-        const declared = declareLane(map, { id: id.value, label });
+        const label = requiredString(rawLane, 'label', where, path);
+        if (!label.ok)
+            return label;
+        const declared = declareLane(map, { id: id.value, label: label.value });
         if (!declared.ok)
             return err({ kind: 'invariant-violation', path, violation: declared.error });
         map = declared.value;
     }
-    for (const [i, rawGroup] of asArray(raw['groups']).entries()) {
+    for (const [i, rawGroup] of groups.value.entries()) {
+        const where = `groups[${i}]`;
         if (!isRecord(rawGroup))
-            return err({ kind: 'bad-shape', path, detail: `groups[${i}] is not an object` });
-        const id = makeGroupId(String(rawGroup['id'] ?? ''));
+            return badShape(path, where, 'an object', rawGroup);
+        const rawId = requiredString(rawGroup, 'id', where, path);
+        if (!rawId.ok)
+            return rawId;
+        const id = makeGroupId(rawId.value);
         if (!id.ok)
             return err({ kind: 'invariant-violation', path, violation: id.error });
-        const layer = makeLayerId(String(rawGroup['layer'] ?? ''));
+        const rawLayer = requiredString(rawGroup, 'layer', where, path);
+        if (!rawLayer.ok)
+            return rawLayer;
+        const layer = makeLayerId(rawLayer.value);
         if (!layer.ok)
             return err({ kind: 'invariant-violation', path, violation: layer.error });
-        const label = optionalString(rawGroup['label']);
-        if (label === undefined)
-            return err({ kind: 'bad-shape', path, detail: `groups[${i}] needs a string label` });
-        const declared = declareGroup(map, { id: id.value, label, layer: layer.value });
+        const label = requiredString(rawGroup, 'label', where, path);
+        if (!label.ok)
+            return label;
+        const declared = declareGroup(map, { id: id.value, label: label.value, layer: layer.value });
         if (!declared.ok)
             return err({ kind: 'invariant-violation', path, violation: declared.error });
         map = declared.value;
     }
-    for (const [i, rawNode] of asArray(raw['nodes']).entries()) {
+    for (const [i, rawNode] of nodes.value.entries()) {
+        const where = `nodes[${i}]`;
         if (!isRecord(rawNode))
-            return err({ kind: 'bad-shape', path, detail: `nodes[${i}] is not an object` });
-        const id = makeNodeId(String(rawNode['id'] ?? ''));
+            return badShape(path, where, 'an object', rawNode);
+        const rawId = requiredString(rawNode, 'id', where, path);
+        if (!rawId.ok)
+            return rawId;
+        const id = makeNodeId(rawId.value);
         if (!id.ok)
             return err({ kind: 'invariant-violation', path, violation: id.error });
-        const layer = makeLayerId(String(rawNode['layer'] ?? ''));
+        const rawLayer = requiredString(rawNode, 'layer', where, path);
+        if (!rawLayer.ok)
+            return rawLayer;
+        const layer = makeLayerId(rawLayer.value);
         if (!layer.ok)
             return err({ kind: 'invariant-violation', path, violation: layer.error });
-        const status = makeNodeStatus(String(rawNode['status'] ?? ''));
+        const rawStatus = requiredString(rawNode, 'status', where, path);
+        if (!rawStatus.ok)
+            return rawStatus;
+        const status = makeNodeStatus(rawStatus.value);
         if (!status.ok)
             return err({ kind: 'invariant-violation', path, violation: status.error });
-        const label = optionalString(rawNode['label']);
-        if (label === undefined)
-            return err({ kind: 'bad-shape', path, detail: `nodes[${i}] needs a string label` });
-        const detail = optionalString(rawNode['detail']);
-        const rawGroup = optionalString(rawNode['group']);
+        const label = requiredString(rawNode, 'label', where, path);
+        if (!label.ok)
+            return label;
+        const detail = optionalString(rawNode, 'detail', where, path);
+        if (!detail.ok)
+            return detail;
+        const rawGroup = optionalString(rawNode, 'group', where, path);
+        if (!rawGroup.ok)
+            return rawGroup;
         let group;
-        if (rawGroup !== undefined) {
-            const made = makeGroupId(rawGroup);
+        if (rawGroup.value !== undefined) {
+            const made = makeGroupId(rawGroup.value);
             if (!made.ok)
                 return err({ kind: 'invariant-violation', path, violation: made.error });
             group = made.value;
         }
-        const rawNodeKind = optionalString(rawNode['kind']);
+        const rawNodeKind = optionalString(rawNode, 'kind', where, path);
+        if (!rawNodeKind.ok)
+            return rawNodeKind;
         let nodeKind;
-        if (rawNodeKind !== undefined) {
-            const made = makeNodeKind(rawNodeKind);
+        if (rawNodeKind.value !== undefined) {
+            const made = makeNodeKind(rawNodeKind.value);
             if (!made.ok)
                 return err({ kind: 'invariant-violation', path, violation: made.error });
             nodeKind = made.value;
         }
-        const rawLane = optionalString(rawNode['lane']);
+        const rawLane = optionalString(rawNode, 'lane', where, path);
+        if (!rawLane.ok)
+            return rawLane;
         let lane;
-        if (rawLane !== undefined) {
-            const made = makeLaneId(rawLane);
+        if (rawLane.value !== undefined) {
+            const made = makeLaneId(rawLane.value);
             if (!made.ok)
                 return err({ kind: 'invariant-violation', path, violation: made.error });
             lane = made.value;
         }
-        const rawSubmap = optionalString(rawNode['submap']);
+        const rawSubmap = optionalString(rawNode, 'submap', where, path);
+        if (!rawSubmap.ok)
+            return rawSubmap;
         let submap;
-        if (rawSubmap !== undefined) {
-            const made = makeSubmapRef(rawSubmap);
+        if (rawSubmap.value !== undefined) {
+            const made = makeSubmapRef(rawSubmap.value);
             if (!made.ok)
                 return err({ kind: 'invariant-violation', path, violation: made.error });
             submap = made.value;
         }
         const declared = declareNode(map, {
             id: id.value,
-            label,
+            label: label.value,
             layer: layer.value,
             status: status.value,
-            ...(detail !== undefined ? { detail } : {}),
+            ...(detail.value !== undefined ? { detail: detail.value } : {}),
             ...(group !== undefined ? { group } : {}),
             ...(nodeKind !== undefined ? { kind: nodeKind } : {}),
             ...(lane !== undefined ? { lane } : {}),
@@ -175,24 +282,36 @@ export function parseMap(raw, path) {
         if (!declared.ok)
             return err({ kind: 'invariant-violation', path, violation: declared.error });
         map = declared.value;
-        const evidence = optionalString(rawNode['evidence']);
-        if (evidence !== undefined) {
-            const updated = updateNode(map, { id: id.value, evidence });
+        const evidence = optionalString(rawNode, 'evidence', where, path);
+        if (!evidence.ok)
+            return evidence;
+        if (evidence.value !== undefined) {
+            const updated = updateNode(map, { id: id.value, evidence: evidence.value });
             if (!updated.ok)
                 return err({ kind: 'invariant-violation', path, violation: updated.error });
             map = updated.value;
         }
     }
-    for (const [i, rawEdge] of asArray(raw['edges']).entries()) {
+    for (const [i, rawEdge] of edges.value.entries()) {
+        const where = `edges[${i}]`;
         if (!isRecord(rawEdge))
-            return err({ kind: 'bad-shape', path, detail: `edges[${i}] is not an object` });
-        const from = makeNodeId(String(rawEdge['from'] ?? ''));
+            return badShape(path, where, 'an object', rawEdge);
+        const rawFrom = requiredString(rawEdge, 'from', where, path);
+        if (!rawFrom.ok)
+            return rawFrom;
+        const from = makeNodeId(rawFrom.value);
         if (!from.ok)
             return err({ kind: 'invariant-violation', path, violation: from.error });
-        const to = makeNodeId(String(rawEdge['to'] ?? ''));
+        const rawTo = requiredString(rawEdge, 'to', where, path);
+        if (!rawTo.ok)
+            return rawTo;
+        const to = makeNodeId(rawTo.value);
         if (!to.ok)
             return err({ kind: 'invariant-violation', path, violation: to.error });
-        const linked = linkNodes(map, from.value, to.value, optionalString(rawEdge['label']));
+        const label = optionalString(rawEdge, 'label', where, path);
+        if (!label.ok)
+            return label;
+        const linked = linkNodes(map, from.value, to.value, label.value);
         if (!linked.ok)
             return err({ kind: 'invariant-violation', path, violation: linked.error });
         map = linked.value;

package/lib/store/store.d.ts

@@ -2,18 +2,39 @@
  * Layer 1b — Node-side persistence for a MellosMap.
  *
  * The state file IS the event bus of the whole plugin: the MCP server writes
- * it, the terminal watcher polls it. The file FORMAT (version, page-id
+ * it, the terminal watcher polls it — and the watcher reports back what it is
+ * showing (see viewers below), which is how a writer can tell whether anybody
+ * is actually SEEING the map it is updating. The file FORMAT (version, page-id
  * grammar, parse/serialize with boundary validation) lives in ./format.ts,
  * pure of I/O so browsers can consume it; this module owns everything that
  * touches the filesystem, and one promise:
  *
  *   P2. Writes are atomic: a reader polling the file either sees the previous
  *       complete map or the new complete map, never a torn write. Achieved by
- *       writing a sibling temp file and renaming it over the target.
+ *       writing a PRIVATE sibling temp file and renaming it over the target.
  *
- * Expected failures (missing file, malformed JSON, invariant violations) are
- * Result values. Only truly unexpected I/O faults (permissions, disk) are
- * allowed to propagate as exceptions.
+ * The concurrency model P2 buys, stated plainly:
+ *   - Several writers may target one project at once. Each save is atomic and
+ *     lands whole, so a reader never sees half a map — but there is NO
+ *     lost-update protection: two saves of the same page race, and the last
+ *     rename wins, silently discarding what the other writer computed from an
+ *     older read. Pages are the isolation unit (one effort = one page); two
+ *     sessions that must not clobber each other belong on two pages.
+ *   - The temp file carries the writer's pid and a random suffix, so
+ *     concurrent writers never share one and never install each other's
+ *     half-written content.
+ *   - A rename can transiently fail while a reader holds the target open
+ *     (EPERM/EBUSY on Windows), so it is retried with a short backoff before
+ *     the save is reported as failed.
+ *   - A page can also be DELETED (deletePageFile). Deletion races a writer
+ *     the same way a save does, and the WRITER WINS: a save landing after it
+ *     recreates the page. Stated at the function, not defended against.
+ *
+ * Expected failures (missing file, malformed JSON, invariant violations, a
+ * write that would not land) are Result values. A failed save changed
+ * nothing: the previous file content is intact and the caller may retry.
+ * Only truly unexpected I/O faults on the READ path are allowed to propagate
+ * as exceptions.
  *
  * Node consumers import everything from here; the format surface is
  * re-exported so persistence has one import site per runtime.
@@ -22,12 +43,14 @@ import { type MellosMap, type Result } from '../domain/types.js';
 import { type PageId, type StoreError } from './format.js';
 export { STATE_FILE_VERSION, type PageId, makePageId, type StoreError, describeStoreError, parseMap, serializeMap, } from './format.js';
 /**
- * Project-relative location of the DEFAULT page's state file. The store lives
- * in the tool-owned `.mellos/` directory: 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.19 stores under
- * `.claude/` are moved once by {@link migrateLegacyStore}.
+ * 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";
@@ -37,6 +60,31 @@ export declare function pageFilePath(defaultFile: string, page?: PageId): string
 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>;
 /** Sibling of the default file carrying a one-shot "show this page" request. */
 export declare const FOCUS_FILE_NAME = "focus";
 export declare function focusFilePath(defaultFile: string): string;
@@ -50,11 +98,125 @@ export interface FocusRequest {
  * request; the channel is best-effort and junk is swept by the same delete.
  */
 export declare function takeFocusRequest(defaultFile: string): FocusRequest | undefined;
-/** Sibling of the default file holding the project's plugin configuration. */
+/** Sibling of the default file carrying a one-shot "close the pane" request. */
+export declare const QUIT_FILE_NAME = "quit";
+export declare function quitFilePath(defaultFile: string): string;
+/**
+ * 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 declare function takeQuitRequest(defaultFile: string): boolean;
+/**
+ * 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 declare function sweepQuitRequest(defaultFile: string): void;
+/** Directory (next to the default file) holding one report per live pane. */
+export declare const VIEWERS_DIR_NAME = "viewers";
+/** On-disk report format version. Bump only with a documented migration. */
+export declare const VIEWER_FILE_VERSION = 1;
+/**
+ * How often a pane refreshes its report — the pane's timer, and the unit the
+ * two thresholds below are counted in.
+ */
+export declare const VIEWER_HEARTBEAT_MS = 1000;
+/**
+ * A report older than this is not a pane, it is a pane's remains. Five missed
+ * heartbeats: long enough to survive a garbage collection, a slow repaint or
+ * a busy disk, short enough that a closed pane is known closed before anyone
+ * asks twice.
+ */
+export declare const VIEWER_STALE_MS = 5000;
+/**
+ * A report this old is deleted on sight by whoever reads it. A pane that was
+ * killed leaves its file behind forever, and a file that outlives every pane
+ * would keep answering for one. The gap to VIEWER_STALE_MS is deliberate
+ * slack: a machine that just woke from sleep has stale reports whose panes
+ * are alive and about to beat again, and there is no reason to make them pay
+ * for the sleep with a deleted file.
+ */
+export declare const VIEWER_SWEEP_MS = 60000;
+/** Where a store's viewer reports live, given the default page's file path. */
+export declare function viewersDirPath(defaultFile: string): string;
+/** Where ONE pane's report lives. The pid in the name is the pane's identity. */
+export declare function viewerFilePath(defaultFile: string, pid: number): string;
+/** What a pane says about itself while it is up. */
+export interface ViewerReport {
+    /** The page on screen right now; undefined = the default page. */
+    readonly page: PageId | undefined;
+    /** Auto-follow: whether the pane will switch to whatever page is written next. */
+    readonly follow: boolean;
+}
+/** A report fresh enough to be a pane, with whose it is and how old. */
+export interface LiveViewer extends ViewerReport {
+    readonly pid: number;
+    /** Age of the report in ms — how long ago that pane last said anything. */
+    readonly ageMs: number;
+}
+/**
+ * Publish this pane's report, atomically (P2) — a reader polling the file
+ * sees the previous whole report or the new one, never half of one.
+ *
+ * Preconditions: none; the viewers directory is created if missing.
+ * Postcondition on ok: the pane's file holds `report` and its mtime is now,
+ * which is what says the pane is alive. On error nothing about the pane is
+ * claimed, and the next heartbeat is the whole recovery — so a caller reports
+ * a failed beat at most once and keeps beating.
+ */
+export declare function publishViewer(defaultFile: string, pid: number, report: ViewerReport): Result<void, StoreError>;
+/**
+ * Take this pane's report back — the pane is going away and says so, rather
+ * than leaving readers to wait out VIEWER_STALE_MS for the same conclusion.
+ *
+ * Best-effort by contract: an exit path is the worst place to raise, and a
+ * report nobody could delete goes stale on its own within seconds.
+ */
+export declare function retireViewer(defaultFile: string, pid: number): void;
+/**
+ * Every pane currently showing this store, youngest report first.
+ *
+ * @param nowMs - the caller's clock (Date.now()), passed in so the ageing
+ *   rules can be tested without waiting for real seconds to pass.
+ * @returns the live reports; an EMPTY array means nobody is seeing this map.
+ *
+ * Reading sweeps: a report past VIEWER_SWEEP_MS is deleted here, because the
+ * pane that would have refreshed it is provably gone and no other code runs
+ * often enough to notice. A report between stale and sweep is ignored but
+ * kept — see VIEWER_SWEEP_MS. Nothing here has an opinion about WHOSE pane a
+ * report is: a viewer started by hand counts exactly like one the launcher
+ * opened, because the user can see both.
+ */
+export declare function readLiveViewers(defaultFile: string, nowMs: number): readonly LiveViewer[];
+/** 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];
@@ -67,13 +229,49 @@ export declare function makeMappingPolicy(raw: string): Result<MappingPolicy, In
 /** One line of meaning per policy — the wording every surface repeats. */
 export declare function describeMappingPolicy(policy: MappingPolicy): string;
 /**
- * The configured policy, or ok(undefined) when the project has never been
- * set up (missing file or missing key — both mean "nobody chose yet").
+ * 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 loadMappingPolicy(defaultFile: string): Result<MappingPolicy | undefined, StoreError>;
-/** Persist the policy atomically (P2), same temp-and-rename as the map files. */
-export declare function saveMappingPolicy(defaultFile: string, policy: MappingPolicy): void;
+export declare function effectiveMappingPolicy(projectConfigFile: string, userConfigFile: string): Result<MappingPolicyScopes, StoreError>;
 /** Project-relative location of the pre-0.20 default page file. */
 export declare const LEGACY_STATE_FILE_RELATIVE_PATH: string;
 /**
@@ -89,8 +287,10 @@ export declare function migrateLegacyStore(defaultFile: string): boolean;
 /** 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 `<path>.tmp` in the
- * same directory, then rename over the target. Creates the parent directory
- * if missing.
+ * 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): void;
+export declare function saveMapFile(path: string, map: MellosMap): Result<void, StoreError>;