@unson/brainbase-mcp 0.15.1 → 0.15.3

package/dist/judgment-value-proof-review.js

@@ -1,13 +1,22 @@
 import { createHash } from 'node:crypto';
 import { appendFile, mkdir, open, readdir, readFile, stat, unlink } from 'node:fs/promises';
-import { dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 import { placeJudgmentValueProof, validateJudgmentValueProof } from './judgment-value-proof.js';
 import { defaultDataDir } from './paths.js';
 export const JUDGMENT_VALUE_PROOF_FILE_SUFFIX = '.value-proof.json';
+/** The judgment Host's per-turn final record, next to the turn's value proof. */
+const JUDGMENT_FINAL_FILE_SUFFIX = '.final.json';
 export const JUDGMENT_VALUE_PROOF_FEEDBACK_SCHEMA = 'brainbase-judgment-value-proof-feedback-v1';
 export const JUDGMENT_VALUE_PROOF_FEEDBACK_FILE = 'judgment-value-proof-feedback.jsonl';
 export const JUDGMENT_VALUE_PROOF_ANSWER_SCHEMA = 'brainbase-judgment-value-proof-answer-v1';
 export const JUDGMENT_VALUE_PROOF_ANSWER_FILE = 'judgment-value-proof-answers.jsonl';
+/** Folders stat'ed or listed at once. Node runs file system calls on a small thread pool; this keeps it fed. */
+const JOURNAL_FOLDER_CONCURRENCY = 16;
+/**
+ * A folder listed this soon after its last change is listed again on the next read: on file systems with
+ * coarse timestamps (HFS+ 1 s, exFAT 2 s) a change right after the listing can keep the same mtime.
+ */
+const JOURNAL_LISTING_SETTLE_NS = 3000000000n;
 const FEEDBACK_SUMMARY_LIMIT = 500;
 const ANSWER_LOCK_TIMEOUT_MS = 2_000;
 /** A lock older than this was left by a write that stopped part way. */
@@ -61,9 +70,96 @@ async function readProofFile(file) {
         return { file, reason: errorMessage(error) };
     }
 }
+/** The `finalized_at` of a turn's final record, or null when it cannot be read as a time. */
+async function readFinalizedAt(file) {
+    try {
+        const value = JSON.parse(await readFile(file, 'utf8')).finalized_at;
+        return typeof value === 'string' && !Number.isNaN(Date.parse(value)) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The judgment Host keeps each conversation in its own folder, one `<turn>.final.json` per finished turn.
+ * Returns when the first later turn of the same conversation was finalized after the waiting turn (compared
+ * with the waiting turn's own final, or the proof's recorded time when that is missing). An unreadable final
+ * is not evidence that the conversation moved on.
+ */
+async function conversationMovedOnAt(file, proof) {
+    const folder = dirname(file);
+    const ownFinal = `${basename(file, JUDGMENT_VALUE_PROOF_FILE_SUFFIX)}${JUDGMENT_FINAL_FILE_SUFFIX}`;
+    const since = Date.parse(await readFinalizedAt(join(folder, ownFinal)) ?? proof.recorded_at);
+    let names;
+    try {
+        names = await readdir(folder);
+    }
+    catch {
+        return null;
+    }
+    let first = null;
+    for (const name of names) {
+        if (!name.endsWith(JUDGMENT_FINAL_FILE_SUFFIX) || name === ownFinal)
+            continue;
+        const at = await readFinalizedAt(join(folder, name));
+        if (at && Date.parse(at) > since && (first === null || Date.parse(at) < Date.parse(first)))
+            first = at;
+    }
+    return first;
+}
+/** Maps with at most `limit` calls in flight; results keep the input order. */
+async function mapConcurrently(items, limit, map) {
+    const results = new Array(items.length);
+    let next = 0;
+    const work = async () => {
+        while (next < items.length) {
+            const index = next++;
+            results[index] = await map(items[index]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, work));
+    return results;
+}
+async function listValueProofFiles(folder) {
+    return (await readdir(folder, { withFileTypes: true }))
+        .filter((child) => child.isFile() && child.name.endsWith(JUDGMENT_VALUE_PROOF_FILE_SUFFIX))
+        .map((child) => join(folder, child.name));
+}
+/**
+ * Remembers which value proofs each folder of a judgment journal held, so that a later read lists only
+ * the folders that changed. A folder is listed again when its inode, mtime or ctime differs from the
+ * listing, or when it was listed within a few seconds of its last change. The judgment Host creates
+ * value proofs and finals by linking a new file and never rewrites them, so every new or removed file
+ * changes the folder's mtime. It keeps no proof contents; every read still reads each proof.
+ * Use one cache per journal.
+ */
+export class JudgmentValueProofJournalCache {
+    #folders = new Map();
+    /** The value proof files in `folder`, reusing the last listing while the folder is unchanged. */
+    async valueProofFiles(folder) {
+        const listedAtNs = BigInt(Date.now()) * 1000000n;
+        const { ino, mtimeNs, ctimeNs } = await stat(folder, { bigint: true });
+        const listing = this.#folders.get(folder);
+        if (listing && listing.ino === ino && listing.mtimeNs === mtimeNs && listing.ctimeNs === ctimeNs
+            && listing.listedAtNs - mtimeNs >= JOURNAL_LISTING_SETTLE_NS) {
+            return listing.files;
+        }
+        const files = await listValueProofFiles(folder);
+        this.#folders.set(folder, { ino, mtimeNs, ctimeNs, listedAtNs, files });
+        return files;
+    }
+    /** Forgets folders that are no longer in the journal. */
+    retainOnly(folders) {
+        for (const folder of this.#folders.keys()) {
+            if (!folders.has(folder))
+                this.#folders.delete(folder);
+        }
+    }
+}
 /**
  * Reads saved judgment value proofs from `<root>/*.value-proof.json` and
  * `<root>/<session>/*.value-proof.json`. The journal is read-only here.
+ * With `cache`, folders unchanged since an earlier read are not listed again; without it every folder is listed.
  */
 export async function readJudgmentValueProofJournal(options = {}) {
     const root = resolve(options.root ?? defaultJudgmentJournalRoot());
@@ -81,23 +177,31 @@ export async function readJudgmentValueProofJournal(options = {}) {
         return { status: 'unavailable', root, reason };
     }
     const files = [];
+    const folders = [];
     for (const entry of topLevel) {
         const path = join(root, entry.name);
         if (entry.isFile() && entry.name.endsWith(JUDGMENT_VALUE_PROOF_FILE_SUFFIX)) {
             files.push(path);
         }
         else if (entry.isDirectory()) {
-            const nested = await readdir(path, { withFileTypes: true });
-            for (const child of nested) {
-                if (child.isFile() && child.name.endsWith(JUDGMENT_VALUE_PROOF_FILE_SUFFIX)) {
-                    files.push(join(path, child.name));
-                }
-            }
+            folders.push(path);
         }
     }
+    const { cache } = options;
+    const nested = await mapConcurrently(folders, JOURNAL_FOLDER_CONCURRENCY, (folder) => cache ? cache.valueProofFiles(folder) : listValueProofFiles(folder));
+    cache?.retainOnly(new Set(folders));
+    for (const folderFiles of nested)
+        files.push(...folderFiles);
     const results = await Promise.all(files.sort().map(readProofFile));
-    const entries = results
+    const entries = (await Promise.all(results
         .filter((result) => 'proof' in result)
+        .map(async (entry) => ({
+        ...entry,
+        // Only a judgment inside a conversation folder can tell whether its conversation moved on.
+        conversation_moved_on_at: entry.proof.state === 'waiting_human' && dirname(entry.file) !== root
+            ? await conversationMovedOnAt(entry.file, entry.proof)
+            : null
+    }))))
         .sort((left, right) => compareRecordedAtDesc(left.proof.recorded_at, right.proof.recorded_at)
         || left.file.localeCompare(right.file));
     const rejected = results.filter((result) => 'reason' in result);
@@ -429,7 +533,14 @@ export function buildJudgmentValueProofReviewHome(journal, feedback, options = {
         const { proof, history } = applyJudgmentValueProofFeedback(entry.proof, feedback);
         const section = classifyJudgmentValueProof(proof);
         const answer = answers.get(`${proof.intent_id}\u0000${proof.decision_attempt_id}`) ?? null;
-        sections[section].push({ file: entry.file, section, proof, feedback_history: history, answer });
+        sections[section].push({
+            file: entry.file,
+            section,
+            proof,
+            feedback_history: history,
+            answer,
+            conversation_moved_on_at: entry.conversation_moved_on_at ?? null
+        });
     }
     const delegationMap = buildJudgmentDelegationMap([...sections.needs_human, ...sections.blocked, ...sections.continued], feedback);
     const now = (options.now ?? new Date()).getTime();

package/dist/local-web-host.d.ts

@@ -1,5 +1,8 @@
 import { type IncomingMessage, type Server, type ServerResponse } from 'node:http';
 import { type ObjectiveDefinitionBuilder } from './foundation-http.js';
+import type { GraphWebAnySource, InMemoryGraphReader } from './graph-web.js';
+import { JudgmentValueProofJournalCache } from './judgment-value-proof-review.js';
+import type { GraphFileV2 } from './types.js';
 /**
  * General local single-owner Web host (`brainbase web:serve`).
  *
@@ -38,6 +41,10 @@ export interface LocalWebModuleContext {
     readonly journalRoot: string;
     readonly token: string;
     readonly now: () => Date;
+    /** Present when the host reads the organization Graph (C1). */
+    readonly organizationGraph?: LocalWebOrganizationGraph;
+    /** The host's one listing cache for the judgment journal, shared by every screen that reads it. */
+    readonly journalCache: JudgmentValueProofJournalCache;
 }
 /**
  * Server side of one screen.  The host has already rejected a non-loopback
@@ -59,6 +66,8 @@ export interface LocalWebExtension {
     readonly uiFiles: readonly string[];
     /** ES module exporting a `screen` compatible with createLocalWebShell. */
     readonly screenEntry: string;
+    /** `first` lists the screen before the public screens and opens it when no screen is named. Defaults to `last`. */
+    readonly navPosition?: 'first' | 'last';
     createModule(context: LocalWebModuleContext): LocalWebModule;
 }
 export interface LocalWebHostOptions {
@@ -71,6 +80,33 @@ export interface LocalWebHostOptions {
     readonly uiDir?: string;
     readonly now?: () => Date;
     readonly extensions?: readonly LocalWebExtension[];
+    /**
+     * Ledger C1: the owner's organization Graph, read only. When given, the Graph
+     * screens read it instead of the data directory and the status reports it.
+     */
+    readonly organizationGraph?: LocalWebOrganizationGraph;
+}
+export interface LocalWebOrganizationGraph {
+    /** Organization server origin shown as the source, without credentials. */
+    readonly server: string;
+    /** The organization's own web (where its records are corrected), when the owner configured it. */
+    readonly webUrl?: string;
+    read(): Promise<InMemoryGraphReader<GraphWebAnySource>>;
+    /** The same Graph as plain records (the world reads project metadata from it). */
+    readGraphFile?(): Promise<GraphFileV2>;
+    /**
+     * The organization's words for field values (glossary terms with `payload.vocabulary`), or null when
+     * they could not be read.  The rest of the Graph is read even when these are not.
+     */
+    readVocabularyTerms?(): Promise<readonly GraphVocabularyTerm[] | null>;
+}
+/** One organization term that names a field value, e.g. project.kind = product → プロダクト. */
+export interface GraphVocabularyTerm {
+    readonly id: string;
+    readonly field: string;
+    readonly value: string;
+    readonly label: string;
+    readonly definition: string | null;
 }
 export interface LocalWebHost {
     readonly server: Server;

package/dist/local-web-host.js

@@ -8,7 +8,7 @@ import { foundationCatalogOrEmpty, foundationKey } from './foundation-catalog.js
 import { createFoundationHttpRouter, createObjectiveFoundationRoute, FOUNDATION_HTTP_PREFIX, FOUNDATION_OBJECTIVE_ROUTE_PREFIX } from './foundation-http.js';
 import { createFoundationRevisionStore, FoundationStoreError } from './foundation-store.js';
 import { createGraphWebHttpHandler } from './graph-web-http.js';
-import { defaultJudgmentJournalRoot } from './judgment-value-proof-review.js';
+import { defaultJudgmentJournalRoot, JudgmentValueProofJournalCache } from './judgment-value-proof-review.js';
 import { nodeRequestToFetch, writeFetchResponse } from './local-web-fetch-bridge.js';
 import { assertSameOrigin, isLoopbackHost, LOCAL_WEB_CONTENT_SECURITY_POLICY, LocalWebHttpError, readJsonObjectBody, requestUrl, tokenMatches, writeHttpError, writeJson } from './local-web-security.js';
 import { resolveDataDir } from './paths.js';
@@ -138,7 +138,9 @@ export function createLocalStatusModule(context) {
                 writeJson(response, 405, { error: { code: 'method_not_allowed', message: 'Use GET' } });
                 return true;
             }
-            const graph = await readLocalGraphState(context.dataDir);
+            const local = await readLocalGraphState(context.dataDir);
+            // Under C1 the Graph screens read the organization Graph, so they are not gated on the local file.
+            const graph = context.organizationGraph ? { ...local, status: 'ready', format: 'v2', message: undefined } : local;
             writeJson(response, 200, {
                 version: LOCAL_WEB_HOST_VERSION,
                 data_dir: context.dataDir,
@@ -149,8 +151,14 @@ export function createLocalStatusModule(context) {
                     ...(graph.message ? { message: graph.message } : {}),
                     commands: graphCommands(graph, context.dataDir)
                 },
-                // This host reads only the local data directory (C1 is not connected here).
-                organization_graph: { status: 'not_connected' }
+                organization_graph: context.organizationGraph
+                    ? {
+                        status: 'connected',
+                        server: context.organizationGraph.server,
+                        mode: 'read_only',
+                        ...(context.organizationGraph.webUrl ? { web_url: context.organizationGraph.webUrl } : {})
+                    }
+                    : { status: 'not_connected' }
             });
             return true;
         }
@@ -161,7 +169,8 @@ export function createValueProofModule(context) {
         journalRoot: context.journalRoot,
         dataDir: context.dataDir,
         token: context.token,
-        now: context.now
+        now: context.now,
+        journalCache: context.journalCache
     });
     return {
         id: 'value-proofs',
@@ -674,6 +683,7 @@ export function createGraphWebModule(context) {
         dataDir: context.dataDir,
         basePath: LOCAL_WEB_GRAPH_PREFIX,
         now: context.now,
+        ...(context.organizationGraph ? { readGraph: context.organizationGraph.read } : {}),
         assertWriteAllowed(request) {
             if (isTrustedLocalWrite(request, context.token))
                 return;
@@ -732,6 +742,8 @@ ${stylesheets.map((path) => `<link rel="stylesheet" href="${escapeAttribute(path
 }
 function bootstrapJs(extensions) {
     const imports = extensions.map((extension, index) => `import { screen as extensionScreen${index} } from '/ui/extensions/${extension.id}/${extension.screenEntry}';`).join('\n');
+    const leading = extensions.flatMap((extension, index) => (extension.navPosition === 'first' ? [`extensionScreen${index}`] : [])).join(', ');
+    const trailing = extensions.flatMap((extension, index) => (extension.navPosition === 'first' ? [] : [`extensionScreen${index}`])).join(', ');
     const screens = extensions.map((_, index) => `extensionScreen${index}`).join(', ');
     const ids = JSON.stringify(extensions.map((extension) => extension.id));
     return `import { createLocalWebShell, LOCAL_WEB_SCREENS } from '/ui/local-web-shell.js';
@@ -749,7 +761,7 @@ const shell = createLocalWebShell({
   root: document.getElementById('brainbase-local-web'),
   token: meta('brainbase-web-token'),
   initialScreen: screenFromHash(),
-  screens: [...LOCAL_WEB_SCREENS, ...extensionScreens]
+  screens: ${leading ? `[${leading}, ...LOCAL_WEB_SCREENS${trailing ? `, ${trailing}` : ''}]` : '[...LOCAL_WEB_SCREENS, ...extensionScreens]'}
 });
 addEventListener('hashchange', () => shell.show(screenFromHash()));
 `;
@@ -765,7 +777,14 @@ export function createLocalWebHost(options = {}) {
     const dataDir = resolveDataDir(options.dataDir);
     const journalRoot = options.journalRoot ?? defaultJudgmentJournalRoot(dataDir);
     const uiDir = options.uiDir ?? fileURLToPath(new URL('../ui/', import.meta.url));
-    const context = { dataDir, journalRoot, token, now: options.now ?? (() => new Date()) };
+    const context = {
+        dataDir,
+        journalRoot,
+        token,
+        now: options.now ?? (() => new Date()),
+        journalCache: new JudgmentValueProofJournalCache(),
+        ...(options.organizationGraph ? { organizationGraph: options.organizationGraph } : {})
+    };
     const modules = defaultLocalWebModules(context);
     const extensions = [...options.extensions ?? []];
     const extensionModules = [];

package/dist/organization-graph-web.d.ts

@@ -0,0 +1,80 @@
+import type { GraphVocabularyTerm, LocalWebOrganizationGraph } from './local-web-host.js';
+import type { CanonicalEntityKind, GraphFileV2 } from './types.js';
+/**
+ * Ledger C1 (adopted 2026-09-24): while the owner validates the Web, the host
+ * reads the owner's organization Graph read only. The records are projected
+ * into an in-memory Graph v2 so the existing Graph screens read them through
+ * the same views as a local Graph. Nothing is written locally or remotely.
+ *
+ * Relations come only from what the organization Graph states:
+ *   - `member_of` person → project       → `participates_in` (role = role_code)
+ *   - RACI `assigned_to` raci → person, with the RACI's project:
+ *       accountable / A / lane decider / decision:*  → `accountable_for`
+ *       any other role                                → `participates_in`
+ * Retired or superseded records are counted, not drawn.
+ */
+export declare const ORGANIZATION_GRAPH_WEB_VERSION: "organization-graph-web.v0";
+interface OrganizationRecord {
+    id: string;
+    entity_type?: string;
+    project_id?: string | null;
+    project_code?: string | null;
+    lifecycle_status?: string;
+    payload?: Record<string, unknown>;
+}
+interface OrganizationEdge {
+    id: string;
+    from_id: string;
+    to_id: string;
+    rel_type: string;
+    project_id?: string | null;
+    lifecycle_status?: string;
+    payload?: Record<string, unknown> | null;
+}
+export interface OrganizationGraphRecords {
+    readonly entities: Readonly<Record<CanonicalEntityKind | 'raci_assignment', readonly OrganizationRecord[]>>;
+    readonly memberOf: readonly OrganizationEdge[];
+    readonly assignedTo: readonly OrganizationEdge[];
+}
+export interface OrganizationGraphProjection {
+    readonly graph: GraphFileV2;
+    readonly excluded: {
+        readonly inactive: number;
+        readonly unnamed: number;
+        readonly danglingRelations: number;
+    };
+}
+/**
+ * The organization's words for field values: active glossary terms that carry
+ * `payload.vocabulary = { field, value }`.  The name is the term's label, else
+ * its term, else the value itself (pure; tested).
+ */
+export declare function projectVocabularyTerms(records: readonly unknown[]): GraphVocabularyTerm[];
+/** Projects organization Graph records into a canonical Graph v2 (pure; tested). */
+export declare function projectOrganizationGraph(records: OrganizationGraphRecords, owner?: {
+    id: string;
+    name?: string;
+}): OrganizationGraphProjection;
+interface OrganizationAccess {
+    readonly server: string;
+    readonly token: string;
+}
+/** The owner's Brainbase server and token, read at request time (tokens rotate hourly). Never logged or returned. */
+export declare function readOrganizationAccess(home?: string): Promise<OrganizationAccess | {
+    readonly reason: string;
+}>;
+export interface OrganizationGraphSourceOptions {
+    readonly home?: string;
+    readonly fetch?: typeof fetch;
+    readonly now?: () => Date;
+    readonly cacheMs?: number;
+}
+/**
+ * The organization Graph for the local host (C1). Reads are cached briefly and
+ * shared while in flight; a failure is reported as `unavailable`, never as an
+ * empty Graph.
+ */
+export declare function createOrganizationGraphSource(options?: OrganizationGraphSourceOptions): Promise<LocalWebOrganizationGraph | {
+    readonly reason: string;
+}>;
+export {};