mellos-mapping 0.22.1 → 0.23.0

package/lib/domain/context.js

@@ -0,0 +1,27 @@
+export function sourceError(raw) {
+    if (!Array.isArray(raw) || raw.length > 100)
+        return 'sources must be an array of at most 100 file references';
+    for (const item of raw) {
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            return 'source must be an object';
+        const s = item;
+        if (Object.keys(s).some(k => k !== 'path' && k !== 'sha256'))
+            return 'unknown source field';
+        if (typeof s.path !== 'string' || s.path.length > 1024 || !s.path || /[\u0000-\u001f\u007f-\u009f\\:]/.test(s.path) || s.path.startsWith('/') || s.path.split('/').some(p => !p || p === '.' || p === '..'))
+            return 'source path must be relative to the project, with forward slashes and no traversal';
+        if (s.sha256 !== undefined && (typeof s.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(s.sha256)))
+            return 'source sha256 must be a lowercase SHA256 hash';
+    }
+    return undefined;
+}
+export function contextError(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return 'context must be an object';
+    for (const [key, value] of Object.entries(raw)) {
+        if (key !== 'summary' && key !== 'next')
+            return 'unknown context field';
+        if (typeof value !== 'string' || value.length > 2000 || /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/.test(value))
+            return 'context fields must be text of at most 2000 characters';
+    }
+    return undefined;
+}

package/lib/domain/text.js

@@ -1,9 +1,15 @@
+import { contextError, sourceError } from './context.js';
 // Explicit ranges also work in the JSON Schema published by the MCP adapter.
 export const NO_CONTROLS = /^[^\u0000-\u001f\u007f-\u009f]*$/;
 export const NO_CONTROLS_TEXT = 'one line of text; control characters (ESC, newline, tab) are not allowed';
 export const NO_CONTROLS_BUT_BREAKS = /^[^\u0000-\u0008\u000b-\u001f\u007f-\u009f]*$/;
 export const NO_CONTROLS_BUT_BREAKS_TEXT = 'text with optional newlines (\\n) and tabs; other control characters (ESC, BEL, CR) are not allowed';
 export function mapTextError(map) {
+    if (map.context !== undefined) {
+        const error = contextError(map.context);
+        if (error)
+            return error;
+    }
     const check = (field, value, multiline = false) => value === undefined || (multiline ? NO_CONTROLS_BUT_BREAKS : NO_CONTROLS).test(value)
         ? undefined : `${field}: ${multiline ? NO_CONTROLS_BUT_BREAKS_TEXT : NO_CONTROLS_TEXT}`;
     let error = check('title', map.title);
@@ -22,6 +28,11 @@ export function mapTextError(map) {
         }
     }
     for (const [i, node] of map.nodes.entries()) {
+        if (node.sources !== undefined) {
+            const error = sourceError(node.sources);
+            if (error)
+                return `nodes[${i}]: ${error}`;
+        }
         for (const name of ['label', 'evidence', 'detail']) {
             // Version-1 files and document exports also support multiline evidence.
             // MCP keeps its narrower one-line evidence input for concise updates.

package/lib/domain/types.d.ts

@@ -171,7 +171,9 @@ export interface MapLane {
     readonly label: string;
 }
 /** A unit of work living in exactly one band. */
+export type { SourceRef, MapContext } from './context.js';
 export interface MapNode {
+    readonly sources?: readonly import('./context.js').SourceRef[];
     readonly id: NodeId;
     readonly label: string;
     readonly layer: LayerId;
@@ -198,6 +200,7 @@ export interface DepEdge {
 }
 /** The whole map. A plain immutable value — operations return new maps. */
 export interface MellosMap {
+    readonly context?: import('./context.js').MapContext;
     readonly title?: string;
     /** Presentation intent; absent means 'dev' (the progress ledger). */
     readonly kind?: MapKind;

package/lib/store/format.js

@@ -22,6 +22,7 @@
  */
 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;
@@ -99,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)
@@ -118,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;
@@ -292,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}]`;
@@ -323,7 +336,9 @@ export function parseMap(raw, path) {
 /** 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/project.d.ts

@@ -0,0 +1,2 @@
+/** Nearest existing store or Git root; never cross a nested repository/worktree boundary. */
+export declare function resolveProjectDirectory(cwd: string, stopAt?: readonly string[]): string;

package/lib/store/project.js

@@ -0,0 +1,29 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { homedir, tmpdir } from 'node:os';
+/** Nearest existing store or Git root; never cross a nested repository/worktree boundary. */
+export function resolveProjectDirectory(cwd, stopAt = [homedir(), tmpdir()]) {
+    let start = resolve(cwd);
+    try {
+        start = realpathSync(start);
+    }
+    catch { /* Explicit test/manual paths may not exist yet. */ }
+    let dir = start;
+    const boundaries = new Set(stopAt.map(path => { try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    } }));
+    while (true) {
+        // A user's global .mellos directory is not an ancestor project's store.
+        if (dir !== start && boundaries.has(dir))
+            return start;
+        if (existsSync(join(dir, '.git')) || existsSync(join(dir, '.mellos', 'map.json')) || existsSync(join(dir, '.mellos', 'pages')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return start;
+        dir = parent;
+    }
+}

package/lib/store/store.d.ts

@@ -16,10 +16,13 @@
  * 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
+ *     lost-update protection in this low-level save API: two saves 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.
+ *     Current MCP/viewer writers additionally use transaction.ts to lock the
+ *     complete read/modify/write operation, with optional revision checks.
+ *     Direct library saves and older processes do not acquire that lock.
  *   - 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.
@@ -47,3 +50,5 @@ export { VIEWERS_DIR_NAME, VIEWER_FILE_VERSION, VIEWER_HEARTBEAT_MS, VIEWER_STAL
 export { CONFIG_FILE_NAME, CONFIG_FILE_VERSION, configFilePath, userConfigFilePath, MAPPING_POLICIES, type MappingPolicy, type InvalidPolicy, makeMappingPolicy, describeMappingPolicy, loadMappingPolicy, saveMappingPolicy, POLICY_SCOPES, type PolicyScope, type MappingPolicyScopes, effectiveMappingPolicy } from './policy.js';
 export { LEGACY_STATE_FILE_RELATIVE_PATH, migrateLegacyStore } from './migration.js';
 export { loadMapFile, saveMapFile } from './maps.js';
+export { withStoreLock, revisionOf, assertRevision, LedgerError } from './transaction.js';
+export { resolveProjectDirectory } from './project.js';

package/lib/store/store.js

@@ -16,10 +16,13 @@
  * 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
+ *     lost-update protection in this low-level save API: two saves 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.
+ *     Current MCP/viewer writers additionally use transaction.ts to lock the
+ *     complete read/modify/write operation, with optional revision checks.
+ *     Direct library saves and older processes do not acquire that lock.
  *   - 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.
@@ -48,3 +51,5 @@ export { VIEWERS_DIR_NAME, VIEWER_FILE_VERSION, VIEWER_HEARTBEAT_MS, VIEWER_STAL
 export { CONFIG_FILE_NAME, CONFIG_FILE_VERSION, configFilePath, userConfigFilePath, MAPPING_POLICIES, makeMappingPolicy, describeMappingPolicy, loadMappingPolicy, saveMappingPolicy, POLICY_SCOPES, effectiveMappingPolicy } from './policy.js';
 export { LEGACY_STATE_FILE_RELATIVE_PATH, migrateLegacyStore } from './migration.js';
 export { loadMapFile, saveMapFile } from './maps.js';
+export { withStoreLock, revisionOf, assertRevision, LedgerError } from './transaction.js';
+export { resolveProjectDirectory } from './project.js';

package/lib/store/transaction.d.ts

@@ -0,0 +1,12 @@
+import type { MellosMap } from '../domain/types.js';
+export declare class LedgerError extends Error {
+    readonly code: string;
+    readonly details: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>);
+}
+export declare const revisionOf: (map: MellosMap) => string;
+export declare function assertRevision(actual: string, expected?: string): void;
+/** A named page and the default page share the same project lock. */
+export declare function storeDirectory(file: string): string;
+/** No timed polling: contention is an explicit retryable BUSY result. Never steal a live lock. */
+export declare function withStoreLock<T>(file: string, action: () => T): T;

package/lib/store/transaction.js

@@ -0,0 +1,91 @@
+/** Cooperative, cross-process transactions for MCP and HTTP writers. */
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { randomUUID, createHash } from 'node:crypto';
+import { serializeMap } from './format.js';
+export class LedgerError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.code = code;
+        this.details = details;
+    }
+}
+export const revisionOf = (map) => createHash('sha256').update(serializeMap(map)).digest('hex');
+export function assertRevision(actual, expected) {
+    if (expected !== undefined && expected !== actual)
+        throw new LedgerError('CONFLICT', 'Map changed; read the current revision before retrying.', { expectedRevision: expected, actualRevision: actual });
+}
+/** A named page and the default page share the same project lock. */
+export function storeDirectory(file) {
+    const dir = dirname(file);
+    return dir.endsWith('/pages') || dir.endsWith('\\pages') ? dirname(dir) : dir;
+}
+function deadOwner(lock) {
+    try {
+        const owner = JSON.parse(readFileSync(join(lock, 'owner.json'), 'utf8'));
+        if (!Number.isSafeInteger(owner.pid) || owner.pid <= 0)
+            return false;
+        try {
+            process.kill(owner.pid, 0);
+            return false;
+        }
+        catch (e) {
+            return e.code === 'ESRCH';
+        }
+    }
+    catch {
+        return false;
+    }
+}
+/** No timed polling: contention is an explicit retryable BUSY result. Never steal a live lock. */
+export function withStoreLock(file, action) {
+    const dir = storeDirectory(file);
+    mkdirSync(dir, { recursive: true });
+    const lock = join(dir, '.write-lock');
+    const owner = join(lock, 'owner.json');
+    const token = randomUUID();
+    try {
+        mkdirSync(lock);
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        // Reapers serialize inside the old directory and recheck its owner after acquiring.
+        // Missing/invalid owners are deliberately not reclaimed on an age heuristic.
+        if (!deadOwner(lock))
+            throw new LedgerError('BUSY', `Another writer owns ${lock}; retry after it completes. An orphan without owner metadata needs manual inspection.`);
+        try {
+            mkdirSync(join(lock, '.reap'));
+        }
+        catch {
+            throw new LedgerError('BUSY', 'Another process is recovering the writer lock.');
+        }
+        if (!deadOwner(lock)) {
+            rmSync(join(lock, '.reap'), { recursive: true, force: true });
+            throw new LedgerError('BUSY', 'Writer ownership changed.');
+        }
+        rmSync(lock, { recursive: true });
+        try {
+            mkdirSync(lock);
+        }
+        catch {
+            throw new LedgerError('BUSY', 'Another writer acquired the recovered lock.');
+        }
+    }
+    let initialized = false;
+    try {
+        writeFileSync(owner, JSON.stringify({ pid: process.pid, token }), { flag: 'wx' });
+        initialized = true;
+        return action();
+    }
+    finally {
+        // Only remove the directory still owned by this invocation.
+        try {
+            if (!initialized || JSON.parse(readFileSync(owner, 'utf8')).token === token)
+                rmSync(lock, { recursive: true });
+        }
+        catch { /* A cleanup error must not misreport a successfully committed map as unsaved. */ }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mellos-mapping",
-  "version": "0.22.1",
+  "version": "0.23.0",
   "mcpName": "io.github.GuangminJu/mellos-mapping",
   "description": "A live layered dependency map for bottom-up development — MCP server + terminal pane. Ghost the design first, then light nodes up from the bottom as they are built and verified.",
   "type": "module",
@@ -70,6 +70,7 @@
     "lib",
     "README.zh-CN.md",
     "docs/codex.md",
+    "docs/map-api.md",
     "scripts/codex-register.mjs",
     "scripts/codex-cli.mjs",
     "scripts/install-mmap-command.mjs",
@@ -92,9 +93,10 @@
     "check:release": "node scripts/check-release.mjs",
     "check:package": "node scripts/check-package-surface.mjs",
     "check:codex": "node scripts/check-codex-package.mjs",
+    "check:reuse": "node scripts/check-reuse.mjs",
     "benchmark:render": "node scripts/benchmark-render.mjs",
     "prepack": "npm run build",
-    "verify": "npm run typecheck && npm run test && npm run build && npm run check:package && npm run check:codex && npm run check:release"
+    "verify": "npm run typecheck && npm run test && npm run build && npm run check:reuse && npm run check:package && npm run check:codex && npm run check:release"
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",

package/scripts/codex-register.mjs

@@ -42,7 +42,7 @@ if (launchedAsEntry(import.meta.url)) {
     const installed = registerServer(dirname(dirname(fileURLToPath(import.meta.url))));
     console.log(`mellos-mapping MCP registered with Codex: ${installed.nodePath} ${installed.serverPath}`);
     console.log('State files resolve to each session’s working directory (.mellos/map.json).');
-    console.log('Start a new Codex conversation to load the skills and six mmap tools.');
+    console.log('Start a new Codex conversation to load the skills and eight mmap tools.');
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error));
     process.exitCode = 1;

package/scripts/mmap.mjs

@@ -170,7 +170,7 @@ async function main() {
     console.error(parsed.error);
     process.exit(1);
   }
-  const candidates = storeSearchPath(process.cwd());
+  const candidates = [store.resolveProjectDirectory(process.cwd())];
   const marker = storeMarkerOf(store.STATE_FILE_RELATIVE_PATH);
   const project = nearestProject(candidates, candidates.map((dir) => existsSync(join(dir, marker))));
   const cfg = { ...parsed.value, projectDir: project.root };