@unson/brainbase-mcp 0.25.0 → 0.26.1

package/dist/graph-embedding-provider.d.ts

@@ -0,0 +1,38 @@
+export declare const GRAPH_EMBEDDING_MODEL_ID = "gemini-embedding-001:768:v2";
+export declare const GRAPH_EMBEDDING_DIMENSIONS = 768;
+export type GraphEmbeddingKind = 'query' | 'passage';
+export type GraphEmbeddingFetchResponse = {
+    readonly ok?: boolean;
+    readonly status?: number;
+    json(): Promise<unknown>;
+};
+export type GraphEmbeddingFetch = (input: string, init: {
+    method: 'POST';
+    headers: Record<string, string>;
+    body: string;
+    signal: AbortSignal;
+}) => Promise<GraphEmbeddingFetchResponse> | GraphEmbeddingFetchResponse;
+export interface GraphEmbeddingProviderOptions {
+    apiKey?: string;
+    fetchImpl?: GraphEmbeddingFetch;
+    timeoutMs?: number;
+    queueTimeoutMs?: number;
+    queryCacheTtlMs?: number;
+    queryCacheMaxEntries?: number;
+}
+export interface GraphEmbeddingProvider {
+    readonly modelId: string;
+    readonly dimensions: number;
+    embed(texts: string[], kind: GraphEmbeddingKind): Promise<number[][]>;
+}
+export declare class GraphEmbeddingProviderError extends Error {
+    readonly code: string;
+    status?: number;
+    constructor(code: string, message: string, status?: number);
+}
+/**
+ * Create the server-side Gemini embedding boundary used by Graph vector
+ * indexing and query retrieval. The queue and cache belong to this provider
+ * instance, which should be shared by the server process.
+ */
+export declare function createGraphEmbeddingProvider({ apiKey, fetchImpl, timeoutMs, queueTimeoutMs, queryCacheTtlMs, queryCacheMaxEntries, }?: GraphEmbeddingProviderOptions): GraphEmbeddingProvider;

package/dist/graph-embedding-provider.js

@@ -0,0 +1,374 @@
+/**
+ * Gemini embedding boundary for Graph vector indexing and query retrieval.
+ *
+ * This is an opt-in hosted adapter. Brainbase does not bundle a model and does
+ * not call this provider unless a host constructs it with an API key. The model
+ * id is part of the stored index identity: vectors written under
+ * GRAPH_EMBEDDING_MODEL_ID must keep the same request shape, chunking and
+ * pooling, so changing any of them requires a new model id.
+ */
+const GEMINI_API_URL = 'https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:batchEmbedContents';
+const GEMINI_MODEL = 'models/gemini-embedding-001';
+// v2 includes UTF-8 chunking and mean-pooling for the provider input limit.
+export const GRAPH_EMBEDDING_MODEL_ID = 'gemini-embedding-001:768:v2';
+export const GRAPH_EMBEDDING_DIMENSIONS = 768;
+const MAX_BATCH_SIZE = 16;
+const MAX_TEXT_LENGTH = 6_000;
+// Gemini embedding-001 accepts at most 2,048 input tokens. Keep each passage
+// chunk below that limit without silently relying on provider truncation. A
+// UTF-8 byte boundary is conservative for the multilingual corpus we index.
+const MAX_CHUNK_UTF8_BYTES = 1_800;
+const MAX_REQUEST_TIMEOUT_MS = 15_000;
+const MAX_QUEUE_SIZE = 16;
+const MAX_CACHE_ENTRIES = 256;
+const DEFAULT_CACHE_TTL_MS = 60_000;
+export class GraphEmbeddingProviderError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.name = 'GraphEmbeddingProviderError';
+        this.code = code;
+        if (Number.isInteger(status))
+            this.status = status;
+    }
+}
+function providerError(code, message, status) {
+    return new GraphEmbeddingProviderError(code, message, status);
+}
+function boundedInteger(value, fallback, minimum, maximum, code) {
+    if (value === undefined)
+        return fallback;
+    const number = Number(value);
+    if (!Number.isInteger(number) || number < minimum) {
+        throw providerError(code, 'Embedding provider configuration is invalid');
+    }
+    return Math.min(number, maximum);
+}
+function copyVector(values) {
+    return values.slice();
+}
+function utf8ByteLength(text) {
+    return Buffer.byteLength(text, 'utf8');
+}
+function splitPassage(text) {
+    if (text.length === 0)
+        return [''];
+    const chunks = [];
+    let chunk = '';
+    let chunkBytes = 0;
+    for (const character of text) {
+        const characterBytes = utf8ByteLength(character);
+        if (chunk && chunkBytes + characterBytes > MAX_CHUNK_UTF8_BYTES) {
+            chunks.push(chunk);
+            chunk = '';
+            chunkBytes = 0;
+        }
+        chunk += character;
+        chunkBytes += characterBytes;
+    }
+    if (chunk || chunks.length === 0)
+        chunks.push(chunk);
+    return chunks;
+}
+function meanPoolVectors(vectors) {
+    if (!Array.isArray(vectors) || vectors.length === 0) {
+        throw providerError('embedding_provider_invalid_response', 'Embedding provider returned no vectors');
+    }
+    const pooled = Array(GRAPH_EMBEDDING_DIMENSIONS).fill(0);
+    for (const vector of vectors) {
+        for (let index = 0; index < pooled.length; index += 1)
+            pooled[index] += vector[index];
+    }
+    return normalizeVector(pooled.map(value => value / vectors.length));
+}
+function normalizeVector(values) {
+    if (!Array.isArray(values) || values.length !== GRAPH_EMBEDDING_DIMENSIONS) {
+        throw providerError('embedding_provider_invalid_response', 'Embedding provider returned an invalid vector');
+    }
+    let squaredNorm = 0;
+    for (const value of values) {
+        if (typeof value !== 'number' || !Number.isFinite(value)) {
+            throw providerError('embedding_provider_invalid_response', 'Embedding provider returned an invalid vector');
+        }
+        squaredNorm += value * value;
+    }
+    const norm = Math.sqrt(squaredNorm);
+    if (!Number.isFinite(norm) || norm <= 0) {
+        throw providerError('embedding_provider_invalid_response', 'Embedding provider returned an invalid vector');
+    }
+    return values.map(value => value / norm);
+}
+function parseEmbeddings(payload, expectedCount) {
+    const embeddings = payload?.embeddings;
+    if (!payload || !Array.isArray(embeddings) || embeddings.length !== expectedCount) {
+        throw providerError('embedding_provider_invalid_response', 'Embedding provider returned an invalid response');
+    }
+    return embeddings.map(embedding => normalizeVector(embedding?.values));
+}
+function createAbortSignal(timeoutMs) {
+    if (typeof AbortSignal?.timeout === 'function') {
+        return {
+            signal: AbortSignal.timeout(timeoutMs),
+            cleanup() { },
+        };
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    return {
+        signal: controller.signal,
+        cleanup() {
+            clearTimeout(timer);
+        },
+    };
+}
+function createBoundedQueue({ concurrency, maxQueue, timeoutMs }) {
+    let active = 0;
+    const pending = [];
+    function start(item) {
+        active += 1;
+        Promise.resolve()
+            .then(item.task)
+            .then(item.resolve, item.reject)
+            .finally(() => {
+            active -= 1;
+            pump();
+        });
+    }
+    function pump() {
+        while (active < concurrency && pending.length > 0) {
+            const item = pending.shift();
+            clearTimeout(item.timer);
+            start(item);
+        }
+    }
+    function enqueue(task) {
+        if (active < concurrency) {
+            return new Promise((resolve, reject) => start({ task, resolve, reject, timer: undefined }));
+        }
+        if (pending.length >= maxQueue) {
+            return Promise.reject(providerError('embedding_provider_queue_full', 'Embedding provider queue is full'));
+        }
+        return new Promise((resolve, reject) => {
+            const item = { task, resolve, reject, timer: undefined };
+            item.timer = setTimeout(() => {
+                const index = pending.indexOf(item);
+                if (index === -1)
+                    return;
+                pending.splice(index, 1);
+                reject(providerError('embedding_provider_queue_timeout', 'Embedding provider queue timed out'));
+            }, timeoutMs);
+            item.timer.unref?.();
+            pending.push(item);
+        });
+    }
+    return { enqueue };
+}
+/**
+ * Create the server-side Gemini embedding boundary used by Graph vector
+ * indexing and query retrieval. The queue and cache belong to this provider
+ * instance, which should be shared by the server process.
+ */
+export function createGraphEmbeddingProvider({ apiKey = process.env.BRAINBASE_EMBEDDING_API_KEY, fetchImpl = globalThis.fetch, timeoutMs = MAX_REQUEST_TIMEOUT_MS, queueTimeoutMs = MAX_REQUEST_TIMEOUT_MS, queryCacheTtlMs = DEFAULT_CACHE_TTL_MS, queryCacheMaxEntries = MAX_CACHE_ENTRIES, } = {}) {
+    const normalizedApiKey = typeof apiKey === 'string' ? apiKey.trim() : '';
+    if (!normalizedApiKey) {
+        throw providerError('embedding_provider_api_key_missing', 'Embedding provider API key is not configured');
+    }
+    if (typeof fetchImpl !== 'function') {
+        throw providerError('embedding_provider_fetch_unavailable', 'Embedding provider fetch is unavailable');
+    }
+    const requestTimeoutMs = boundedInteger(timeoutMs, MAX_REQUEST_TIMEOUT_MS, 1, MAX_REQUEST_TIMEOUT_MS, 'embedding_provider_timeout_invalid');
+    const queueWaitTimeoutMs = boundedInteger(queueTimeoutMs, MAX_REQUEST_TIMEOUT_MS, 1, MAX_REQUEST_TIMEOUT_MS, 'embedding_provider_queue_timeout_invalid');
+    const cacheTtlMs = boundedInteger(queryCacheTtlMs, DEFAULT_CACHE_TTL_MS, 1, 24 * 60 * 60 * 1000, 'embedding_provider_cache_ttl_invalid');
+    const cacheMaxEntries = boundedInteger(queryCacheMaxEntries, MAX_CACHE_ENTRIES, 1, MAX_CACHE_ENTRIES, 'embedding_provider_cache_size_invalid');
+    const queue = createBoundedQueue({
+        concurrency: 2,
+        maxQueue: MAX_QUEUE_SIZE,
+        timeoutMs: queueWaitTimeoutMs,
+    });
+    const queryCache = new Map();
+    const queryFlights = new Map();
+    function readQueryCache(text) {
+        const entry = queryCache.get(text);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt <= Date.now()) {
+            queryCache.delete(text);
+            return undefined;
+        }
+        // Refresh insertion order for LRU behavior.
+        queryCache.delete(text);
+        queryCache.set(text, entry);
+        return copyVector(entry.values);
+    }
+    function writeQueryCache(text, values) {
+        queryCache.delete(text);
+        queryCache.set(text, { values: copyVector(values), expiresAt: Date.now() + cacheTtlMs });
+        while (queryCache.size > cacheMaxEntries) {
+            queryCache.delete(queryCache.keys().next().value);
+        }
+    }
+    async function requestBatch(texts, kind) {
+        const signalState = createAbortSignal(requestTimeoutMs);
+        let aborted = signalState.signal.aborted;
+        let timeoutTimer;
+        let removeAbortListener = () => { };
+        const timeoutPromise = new Promise((_, reject) => {
+            timeoutTimer = setTimeout(() => {
+                aborted = true;
+                reject(providerError('embedding_provider_timeout', 'Embedding provider request timed out'));
+            }, requestTimeoutMs);
+            const onAbort = () => {
+                aborted = true;
+                reject(providerError('embedding_provider_timeout', 'Embedding provider request timed out'));
+            };
+            if (signalState.signal.aborted) {
+                onAbort();
+                return;
+            }
+            signalState.signal.addEventListener('abort', onAbort, { once: true });
+            removeAbortListener = () => signalState.signal.removeEventListener('abort', onAbort);
+        });
+        const payload = {
+            requests: texts.map(text => ({
+                model: GEMINI_MODEL,
+                content: { parts: [{ text }] },
+                taskType: kind === 'query' ? 'RETRIEVAL_QUERY' : 'RETRIEVAL_DOCUMENT',
+                outputDimensionality: GRAPH_EMBEDDING_DIMENSIONS,
+            })),
+        };
+        let response;
+        try {
+            response = await Promise.race([
+                Promise.resolve(fetchImpl(GEMINI_API_URL, {
+                    method: 'POST',
+                    headers: {
+                        'content-type': 'application/json',
+                        'x-goog-api-key': normalizedApiKey,
+                    },
+                    body: JSON.stringify(payload),
+                    signal: signalState.signal,
+                })),
+                timeoutPromise,
+            ]);
+        }
+        catch (error) {
+            if (aborted || signalState.signal.aborted) {
+                throw providerError('embedding_provider_timeout', 'Embedding provider request timed out');
+            }
+            if (error instanceof GraphEmbeddingProviderError)
+                throw error;
+            throw providerError('embedding_provider_request_failed', 'Embedding provider request failed');
+        }
+        finally {
+            removeAbortListener();
+            clearTimeout(timeoutTimer);
+            signalState.cleanup();
+        }
+        if (!response || response.ok !== true) {
+            throw providerError('embedding_provider_http_error', `Embedding provider request failed (HTTP ${Number.isInteger(response?.status) ? response?.status : 0})`, Number.isInteger(response?.status) ? response?.status : undefined);
+        }
+        let result;
+        try {
+            result = await response.json();
+        }
+        catch {
+            throw providerError('embedding_provider_invalid_response', 'Embedding provider returned an invalid response');
+        }
+        return parseEmbeddings(result, texts.length);
+    }
+    async function embedPassages(texts) {
+        const chunks = texts.flatMap((text, textIndex) => splitPassage(text).map(chunk => ({ chunk, textIndex })));
+        const chunkVectors = texts.map(() => []);
+        for (let offset = 0; offset < chunks.length; offset += MAX_BATCH_SIZE) {
+            const batch = chunks.slice(offset, offset + MAX_BATCH_SIZE);
+            const result = await queue.enqueue(() => requestBatch(batch.map(item => item.chunk), 'passage'));
+            result.forEach((values, index) => {
+                chunkVectors[batch[index].textIndex].push(values);
+            });
+        }
+        return chunkVectors.map(meanPoolVectors);
+    }
+    async function embedQueryBatch(texts) {
+        const promisesByText = new Map();
+        const newFlights = [];
+        for (const text of texts) {
+            if (promisesByText.has(text))
+                continue;
+            const chunkPromises = [];
+            for (const chunk of splitPassage(text)) {
+                const cached = readQueryCache(chunk);
+                if (cached) {
+                    chunkPromises.push(Promise.resolve(cached));
+                    continue;
+                }
+                const existing = queryFlights.get(chunk);
+                if (existing) {
+                    chunkPromises.push(existing.promise);
+                    continue;
+                }
+                let resolveFlight;
+                let rejectFlight;
+                const promise = new Promise((resolve, reject) => {
+                    resolveFlight = resolve;
+                    rejectFlight = reject;
+                });
+                const flight = { promise, resolve: resolveFlight, reject: rejectFlight };
+                queryFlights.set(chunk, flight);
+                chunkPromises.push(promise);
+                newFlights.push({ text: chunk, flight });
+            }
+            promisesByText.set(text, Promise.all(chunkPromises).then(meanPoolVectors));
+        }
+        if (newFlights.length > 0) {
+            for (let offset = 0; offset < newFlights.length; offset += MAX_BATCH_SIZE) {
+                const batch = newFlights.slice(offset, offset + MAX_BATCH_SIZE);
+                void queue.enqueue(() => requestBatch(batch.map(item => item.text), 'query')).then(vectors => {
+                    vectors.forEach((values, index) => {
+                        const { text, flight } = batch[index];
+                        writeQueryCache(text, values);
+                        if (queryFlights.get(text) === flight)
+                            queryFlights.delete(text);
+                        flight.resolve(copyVector(values));
+                    });
+                }).catch(error => {
+                    const safeError = error instanceof GraphEmbeddingProviderError
+                        ? error
+                        : providerError('embedding_provider_request_failed', 'Embedding provider request failed');
+                    for (const { text, flight } of batch) {
+                        if (queryFlights.get(text) === flight)
+                            queryFlights.delete(text);
+                        flight.reject(safeError);
+                    }
+                });
+            }
+        }
+        const vectors = await Promise.all(texts.map(text => promisesByText.get(text)));
+        return vectors.map(copyVector);
+    }
+    async function embed(texts, kind) {
+        if (kind !== 'query' && kind !== 'passage') {
+            throw providerError('embedding_provider_invalid_kind', 'Embedding kind is invalid');
+        }
+        if (!Array.isArray(texts) || !texts.every(text => typeof text === 'string')) {
+            throw providerError('embedding_provider_invalid_texts', 'Embedding texts are invalid');
+        }
+        if (texts.some(text => text.length > MAX_TEXT_LENGTH)) {
+            throw providerError('embedding_provider_text_too_long', 'Embedding text exceeds the maximum length');
+        }
+        if (texts.length === 0)
+            return [];
+        if (kind === 'passage')
+            return embedPassages(texts);
+        const vectors = [];
+        for (let offset = 0; offset < texts.length; offset += MAX_BATCH_SIZE) {
+            vectors.push(...await embedQueryBatch(texts.slice(offset, offset + MAX_BATCH_SIZE)));
+        }
+        return vectors;
+    }
+    return {
+        modelId: GRAPH_EMBEDDING_MODEL_ID,
+        dimensions: GRAPH_EMBEDDING_DIMENSIONS,
+        embed,
+    };
+}

package/dist/judgment-frame.d.ts

@@ -63,12 +63,26 @@ export interface JudgmentFrameSelection {
     readonly kind: JudgmentFrameKind;
     readonly why: string;
 }
+export type JudgmentFramePredictionCheckStatus = 'held' | 'failed' | 'unchecked';
+/**
+ * How a world-model prediction was checked against data (ADR-014). The check is
+ * structural: whether the evidence really shows the result is not judged.
+ */
+export interface JudgmentFramePredictionCheck {
+    /** What observation would show the prediction wrong. */
+    readonly falsified_if: string;
+    readonly status: JudgmentFramePredictionCheckStatus;
+    /** Where the check was done. Required for held and failed. */
+    readonly evidence?: string;
+}
 export interface JudgmentFrameUse {
     readonly ref: string;
     readonly role: JudgmentFrameRole;
     readonly note: string;
     /** Required for constraint uses: how the option stands against the philosophy. */
     readonly verdict?: JudgmentFrameConstraintVerdict;
+    /** Optional for prediction uses only. */
+    readonly check?: JudgmentFramePredictionCheck;
 }
 export interface JudgmentFrameOption {
     readonly label: string;
@@ -85,7 +99,7 @@ export interface JudgmentFrameRecord {
     /** Explicit opt-in for the future owner-only public projection. */
     readonly public_frame?: JudgmentFramePublicFrame;
 }
-export type JudgmentFrameIssueCode = 'frame_record_invalid' | 'frame_catalog_mismatch' | 'frame_ref_unknown' | 'frame_kind_mismatch' | 'frame_selection_duplicate' | 'frame_kind_unaddressed' | 'frame_kind_contradiction' | 'frame_use_unselected' | 'frame_role_mismatch' | 'frame_verdict_missing' | 'frame_selection_unused' | 'frame_chosen_unknown' | 'frame_public_invalid';
+export type JudgmentFrameIssueCode = 'frame_record_invalid' | 'frame_catalog_mismatch' | 'frame_ref_unknown' | 'frame_kind_mismatch' | 'frame_selection_duplicate' | 'frame_kind_unaddressed' | 'frame_kind_contradiction' | 'frame_use_unselected' | 'frame_role_mismatch' | 'frame_verdict_missing' | 'frame_selection_unused' | 'frame_chosen_unknown' | 'frame_public_invalid' | 'frame_check_invalid';
 export interface JudgmentFrameIssue {
     readonly code: JudgmentFrameIssueCode;
     readonly path: string;
@@ -94,7 +108,9 @@ export interface JudgmentFrameIssue {
 /** Exceptions that ADR-014 F5 returns to a human. The host decides when they block. */
 export type JudgmentFrameEscalationCode = 'objective_unanchored' | 'chosen_violates_philosophy' | 'chosen_philosophy_tension'
 /** The chosen option predicts with a world model refuted at its current revision (F5, F6). */
- | 'chosen_uses_refuted_model';
+ | 'chosen_uses_refuted_model'
+/** The chosen option relies on a prediction that was checked against data and failed. */
+ | 'chosen_relies_on_failed_prediction';
 export interface JudgmentFrameEscalation {
     readonly code: JudgmentFrameEscalationCode;
     readonly refs: readonly string[];
@@ -128,6 +144,12 @@ export declare function buildJudgmentFrameCatalog(records: readonly JudgmentFram
  * summaries, when given, annotate world models; they are not part of the digest.
  */
 export declare function renderJudgmentFrameCatalog(catalog: JudgmentFrameCatalog, outcomes?: ReadonlyMap<string, JudgmentModelOutcomeSummary>): string;
+/** Counts of the chosen option's predictions by check status. A prediction without a check is unchecked. */
+export declare function judgmentFramePredictionCheckCounts(record: JudgmentFrameRecord): {
+    held: number;
+    failed: number;
+    unchecked: number;
+};
 /**
  * Check that a frame record only uses catalog references and that every
  * selection is used in at least one option with the role of its kind.

package/dist/judgment-frame.js

@@ -188,6 +188,42 @@ export function renderJudgmentFrameCatalog(catalog, outcomes = new Map()) {
     }
     return lines.join('\n');
 }
+const PREDICTION_CHECK_STATUSES = ['held', 'failed', 'unchecked'];
+const MAX_CHECK_EVIDENCE = 800;
+function predictionCheckProblem(value, role) {
+    if (role !== 'prediction')
+        return 'check is only for prediction uses';
+    if (!isRecord(value) || Object.keys(value).some((key) => !['falsified_if', 'status', 'evidence'].includes(key))) {
+        return 'check takes falsified_if, status, and evidence';
+    }
+    if (!nonEmpty(value.falsified_if, MAX_NOTE))
+        return 'check.falsified_if must say what observation would show the prediction wrong';
+    if (!PREDICTION_CHECK_STATUSES.includes(value.status)) {
+        return 'check.status must be held, failed, or unchecked';
+    }
+    if (value.evidence === undefined) {
+        return value.status === 'unchecked' ? null : 'a held or failed check needs evidence of where it was checked';
+    }
+    if (!nonEmpty(value.evidence, MAX_CHECK_EVIDENCE))
+        return `check.evidence must be at most ${MAX_CHECK_EVIDENCE} characters`;
+    for (const text of [value.falsified_if, value.evidence]) {
+        if (typeof text === 'string' && (PUBLIC_FRAME_CONTROL_CHARACTERS.test(text) || containsJudgmentFrameCredential(text))) {
+            return 'check contains control characters or a credential-like value';
+        }
+    }
+    return null;
+}
+/** Counts of the chosen option's predictions by check status. A prediction without a check is unchecked. */
+export function judgmentFramePredictionCheckCounts(record) {
+    const chosen = record.options.find((option) => option.label === record.chosen_option);
+    const predictions = (chosen?.uses ?? []).filter((use) => use.role === 'prediction');
+    const status = (use) => use.check?.status ?? 'unchecked';
+    return {
+        held: predictions.filter((use) => status(use) === 'held').length,
+        failed: predictions.filter((use) => status(use) === 'failed').length,
+        unchecked: predictions.filter((use) => status(use) === 'unchecked').length,
+    };
+}
 /**
  * Check that a frame record only uses catalog references and that every
  * selection is used in at least one option with the role of its kind.
@@ -298,6 +334,13 @@ export function validateJudgmentFrameRecord(value, catalog, outcomes = new Map()
                 issue('frame_verdict_missing', `${usePath}.verdict`, 'a constraint use needs verdict satisfied, violated, or tension');
                 return;
             }
+            if (use.check !== undefined) {
+                const problem = predictionCheckProblem(use.check, use.role);
+                if (problem) {
+                    issue('frame_check_invalid', `${usePath}.check`, problem);
+                    return;
+                }
+            }
             used.add(use.ref);
         });
     });
@@ -330,6 +373,12 @@ export function validateJudgmentFrameRecord(value, catalog, outcomes = new Map()
                 .map((use) => String(use.ref)))];
         if (refuted.length > 0)
             escalations.push({ code: 'chosen_uses_refuted_model', refs: refuted });
+        const failed = [...new Set(chosenUses
+                .filter((use) => isRecord(use) && use.role === 'prediction'
+                && isRecord(use.check) && use.check.status === 'failed')
+                .map((use) => String(use.ref)))];
+        if (failed.length > 0)
+            escalations.push({ code: 'chosen_relies_on_failed_prediction', refs: failed });
     }
     return { valid: issues.length === 0, issues, escalations };
 }
@@ -345,6 +394,17 @@ const frameUseSchema = {
         role: { type: 'string', enum: ['constraint', 'criterion', 'prediction'] },
         note: { type: 'string', minLength: 1, maxLength: MAX_NOTE },
         verdict: { type: 'string', enum: ['satisfied', 'violated', 'tension'], description: 'Required when role is constraint.' },
+        check: {
+            type: 'object',
+            additionalProperties: false,
+            description: 'Only for prediction uses: what observation would show the prediction wrong, and whether it was checked against data. held and failed need evidence. A chosen option that relies on a failed prediction returns the choice to the human.',
+            properties: {
+                falsified_if: { type: 'string', minLength: 1, maxLength: MAX_NOTE },
+                status: { type: 'string', enum: ['held', 'failed', 'unchecked'] },
+                evidence: { type: 'string', minLength: 1, maxLength: 800 },
+            },
+            required: ['falsified_if', 'status'],
+        },
     },
     required: ['ref', 'role', 'note'],
 };
@@ -494,6 +554,7 @@ export async function handleJudgmentFrameToolCall(name, args, dependencies) {
             option_count: args.options.length,
             chosen_option: args.chosen_option,
             escalations: validation.escalations,
+            prediction_checks: judgmentFramePredictionCheckCounts(args),
             ...(args.public_frame === undefined ? {} : {
                 public_frame: {
                     ...args.public_frame,

package/dist/world-extension.d.ts

@@ -35,7 +35,14 @@ export interface WorldVocabularyConfig {
         readonly label?: string;
         readonly phase?: WorldLifecyclePhase;
     }>>;
+    /** The owner's words for the states of a business's tools (story-world-business-exits-v1 AC-04). */
+    readonly exit_states?: Readonly<Partial<Record<WorldExitState, {
+        readonly label?: string;
+    }>>>;
 }
+declare const EXIT_STATES: readonly ["available", "restricted", "unknown", "unavailable"];
+/** The state a host gives a tool of a business (`businessExits` in the world view). */
+export type WorldExitState = (typeof EXIT_STATES)[number];
 export interface WorldVocabulary {
     readonly kinds: readonly {
         readonly key: string | null;
@@ -54,6 +61,11 @@ export interface WorldVocabulary {
         readonly label: string;
         readonly phase: WorldLifecyclePhase;
     }[];
+    /** The words for the four tool states, the owner's over the defaults, in a fixed order. */
+    readonly exit_states: readonly {
+        readonly key: WorldExitState;
+        readonly label: string;
+    }[];
 }
 export interface WorldEngagement {
     readonly id: string;

package/dist/world-extension.js

@@ -20,6 +20,7 @@ export const WORLD_EXTENSION_ID = 'world';
 export const WORLD_EXTENSION_VERSION = 'world-extension.v1';
 const LIFECYCLE_PHASES = ['active', 'maintenance', 'finished', 'concept'];
 const BUILDING_FORMS = ['tower', 'hall', 'dome', 'office'];
+const EXIT_STATES = ['available', 'restricted', 'unknown', 'unavailable'];
 /** Lifecycle words common to any Graph; a host vocabulary may relabel or add to them. */
 const DEFAULT_STATUSES = Object.freeze({
     active: { label: '進行中', phase: 'active' },
@@ -29,6 +30,13 @@ const DEFAULT_STATUSES = Object.freeze({
     archived: { label: '保管', phase: 'finished' },
     concept: { label: '構想', phase: 'concept' },
 });
+/** The words for the states of a business's tools when the owner gives none. */
+const DEFAULT_EXIT_STATES = Object.freeze({
+    available: '使える',
+    restricted: '権限が必要',
+    unknown: '未確認',
+    unavailable: '読めない',
+});
 const KIND_PALETTE = ['#1261ad', '#b07a1f', '#35684c', '#6b4fa0', '#a8433a', '#2f7d86', '#7a6a2b', '#5b6470'];
 const UNCLASSIFIED_COLOR = '#69746d';
 const HEX_COLOR = /^#[0-9a-f]{6}$/iu;
@@ -197,7 +205,8 @@ export function resolveWorldVocabulary(config, businesses, terms = undefined) {
             phase: entry.phase && LIFECYCLE_PHASES.includes(entry.phase) ? entry.phase : base?.phase ?? 'active',
         });
     }
-    return { kinds, statuses: [...statuses].map(([key, entry]) => ({ key, ...entry })), terms: terms === undefined ? 'none' : terms === null ? 'unavailable' : 'read' };
+    const exitStates = EXIT_STATES.map((key) => ({ key, label: text(config?.exit_states?.[key]?.label) ?? DEFAULT_EXIT_STATES[key] }));
+    return { kinds, statuses: [...statuses].map(([key, entry]) => ({ key, ...entry })), exit_states: exitStates, terms: terms === undefined ? 'none' : terms === null ? 'unavailable' : 'read' };
 }
 /** Reads and checks a vocabulary file; an invalid file is an error, never silently ignored. */
 export async function readWorldVocabulary(path) {
@@ -222,7 +231,19 @@ export async function readWorldVocabulary(path) {
             throw new Error(`world vocabulary status ${key} has an unknown phase`);
         statuses[key] = { ...(text(entry.label) ? { label: text(entry.label) } : {}), ...(entry.phase ? { phase: entry.phase } : {}) };
     }
-    return { kinds, statuses };
+    if (parsed.exit_states === undefined)
+        return { kinds, statuses };
+    if (!isRecord(parsed.exit_states))
+        throw new Error('world vocabulary exit_states must be an object');
+    const exitStates = {};
+    for (const [key, entry] of Object.entries(parsed.exit_states)) {
+        if (!EXIT_STATES.includes(key))
+            throw new Error(`world vocabulary has an unknown exit state ${key}`);
+        if (!isRecord(entry))
+            throw new Error(`world vocabulary exit state ${key} must be an object`);
+        exitStates[key] = text(entry.label) ? { label: text(entry.label) } : {};
+    }
+    return { kinds, statuses, exit_states: exitStates };
 }
 /**
  * The businesses from the same Graph the other screens read (this Mac's Graph).
@@ -347,7 +368,7 @@ export function createWorldExtension(options = {}) {
     return {
         id: WORLD_EXTENSION_ID,
         uiDir: fileURLToPath(new URL('../ui/world/', import.meta.url)),
-        uiFiles: ['world-view.js', 'world-view.css', 'world-canvas-ui.js', 'world-canvas-ui.css', 'world-canvas-notes.js', 'world-vendor.js', 'world-placement.js', 'world-work-rail.js', 'world-district.js', 'world-scenery.js'],
+        uiFiles: ['world-view.js', 'world-view.css', 'world-canvas-ui.js', 'world-canvas-ui.css', 'world-canvas-notes.js', 'world-vendor.js', 'world-placement.js', 'world-work-rail.js', 'world-district.js', 'world-scenery.js', 'world-exits.js'],
         screenEntry: 'world-view.js',
         // P17: the world sits above the home and opens first.
         navPosition: 'first',