mellos-mapping 0.19.0 → 0.20.2

package/lib/store/format.js

@@ -0,0 +1,334 @@
+/**
+ * Layer 1a — the state-file FORMAT of a MellosMap, pure of any I/O.
+ *
+ * This module owns the on-disk vocabulary (version, page-id grammar) and the
+ * two format promises every consumer relies on:
+ *
+ *   P1. Whatever parseMap accepts satisfies the structural invariants of
+ *       Layer 0. Parsing is done by REPLAYING the raw data through the domain
+ *       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
+ * concerns (atomic writes, page file listing, focus requests) live in
+ * ./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, 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) {
+    return ID_RULE.test(raw) ? ok(raw) : err({ kind: 'invalid-id', raw, rule: ID_RULE_TEXT });
+}
+export function describeStoreError(e) {
+    switch (e.kind) {
+        case 'not-found':
+            return `no map file at ${e.path}`;
+        case 'malformed-json':
+            return `map file ${e.path} is not valid JSON: ${e.detail}`;
+        case 'bad-shape':
+            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);
+}
+/** 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 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
+ * Layer 0 operations (P1). Field order in the file does not matter; replay
+ * order (layers -> lanes -> groups -> nodes -> edges) supplies the required
+ * declaration order.
+ */
+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}` });
+    }
+    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', '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 layers.value.entries()) {
+        const where = `layers[${i}]`;
+        if (!isRecord(rawLayer))
+            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 = 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 lanes.value.entries()) {
+        const where = `lanes[${i}]`;
+        if (!isRecord(rawLane))
+            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 = 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 groups.value.entries()) {
+        const where = `groups[${i}]`;
+        if (!isRecord(rawGroup))
+            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 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 = 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 nodes.value.entries()) {
+        const where = `nodes[${i}]`;
+        if (!isRecord(rawNode))
+            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 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 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 = 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.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', where, path);
+        if (!rawNodeKind.ok)
+            return rawNodeKind;
+        let nodeKind;
+        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', where, path);
+        if (!rawLane.ok)
+            return rawLane;
+        let lane;
+        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', where, path);
+        if (!rawSubmap.ok)
+            return rawSubmap;
+        let submap;
+        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.value,
+            layer: layer.value,
+            status: status.value,
+            ...(detail.value !== undefined ? { detail: detail.value } : {}),
+            ...(group !== undefined ? { group } : {}),
+            ...(nodeKind !== undefined ? { kind: nodeKind } : {}),
+            ...(lane !== undefined ? { lane } : {}),
+            ...(submap !== undefined ? { submap } : {}),
+        });
+        if (!declared.ok)
+            return err({ kind: 'invariant-violation', path, violation: declared.error });
+        map = declared.value;
+        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 edges.value.entries()) {
+        const where = `edges[${i}]`;
+        if (!isRecord(rawEdge))
+            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 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 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;
+    }
+    return 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,
+        ...(map.title !== undefined ? { title: map.title } : {}),
+        ...(map.kind !== undefined ? { kind: map.kind } : {}),
+        layers: map.layers,
+        ...(map.lanes.length > 0 ? { lanes: map.lanes } : {}),
+        ...(map.groups.length > 0 ? { groups: map.groups } : {}),
+        nodes: map.nodes,
+        edges: map.edges,
+    };
+    return JSON.stringify(body, null, 2) + '\n';
+}

package/lib/store/store.d.ts

@@ -0,0 +1,296 @@
+/**
+ * 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 — 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 PRIVATE sibling temp file and renaming it over the target.
+ *
+ * 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.
+ */
+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';
+/**
+ * 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>;
+/** 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;
+/** A consumed focus request: the page to show (undefined = the default page). */
+export interface FocusRequest {
+    readonly page: PageId | undefined;
+}
+/**
+ * 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 declare function takeFocusRequest(defaultFile: string): FocusRequest | undefined;
+/** 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];
+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>;
+/** 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;
+/** 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>;