@unson/brainbase-mcp 0.4.1 → 0.5.0

package/dist/judgment-value-proof.js

@@ -0,0 +1,229 @@
+function requiredText(value, field) {
+    const normalized = value.trim();
+    if (!normalized)
+        throw new TypeError(`${field} must be a non-empty string`);
+    return normalized;
+}
+function optionalText(value) {
+    if (value === null)
+        return null;
+    const normalized = value.trim();
+    return normalized || null;
+}
+function outcomeStatusLabel(status) {
+    if (status === 'outcome_verified')
+        return '成果確認済み';
+    if (status === 'unconfirmed')
+        return '結果未確認';
+    return '成果確認の対象外';
+}
+function evidenceLabel(evidence) {
+    const label = evidence.label?.trim() || evidence.kind;
+    return `${label} (${evidence.status === 'verified' ? '確認済み' : '未確認'})`;
+}
+export function validateJudgmentValueProof(proof) {
+    if (proof?.schema_version !== 'brainbase-judgment-value-proof-v1') {
+        throw new TypeError('unsupported judgment value proof schema');
+    }
+    requiredText(proof.intent_id, 'intent_id');
+    requiredText(proof.decision_attempt_id, 'decision_attempt_id');
+    requiredText(proof.recorded_at, 'recorded_at');
+    if (proof.interruption.resolution === 'continued_without_human') {
+        if (!optionalText(proof.decision.summary)) {
+            throw new TypeError('continued_without_human requires decision.summary');
+        }
+        if (!optionalText(proof.interruption.question_display_text)
+            && !optionalText(proof.interruption.question_digest)) {
+            throw new TypeError('continued_without_human requires a redacted question or digest');
+        }
+    }
+    if (proof.interruption.resolution === 'human_required') {
+        if (!proof.human_decision) {
+            throw new TypeError('human_required requires human_decision');
+        }
+        requiredText(proof.human_decision.question, 'human_decision.question');
+        requiredText(proof.human_decision.why_human, 'human_decision.why_human');
+        for (const option of proof.human_decision.options) {
+            requiredText(option.id, 'human_decision.options[].id');
+            requiredText(option.label, 'human_decision.options[].label');
+            requiredText(option.impact, 'human_decision.options[].impact');
+        }
+    }
+    if (proof.outcome.status === 'outcome_verified') {
+        if (!optionalText(proof.outcome.summary)) {
+            throw new TypeError('outcome_verified requires outcome.summary');
+        }
+        if (!proof.outcome.evidence_refs.some((entry) => entry.status === 'verified')) {
+            throw new TypeError('outcome_verified requires verified evidence');
+        }
+    }
+    if (proof.feedback.status !== 'none' && proof.feedback.status !== 'pending'
+        && !proof.feedback.evidence_ref) {
+        throw new TypeError('recorded feedback requires evidence_ref');
+    }
+    return proof;
+}
+export function placeJudgmentValueProof(proof) {
+    validateJudgmentValueProof(proof);
+    let companionAttention = 'none';
+    if (proof.interruption.resolution === 'human_required') {
+        companionAttention = 'human_decision';
+    }
+    else if (proof.state === 'blocked' || proof.execution.status === 'blocked') {
+        companionAttention = 'blocked';
+    }
+    else if (proof.outcome.status === 'unconfirmed' && proof.execution.status === 'completed') {
+        companionAttention = 'outcome_unconfirmed';
+    }
+    else if (proof.feedback.status === 'pending') {
+        companionAttention = 'feedback_requested';
+    }
+    const behaviorChanged = proof.interruption.resolution === 'continued_without_human';
+    const completed = proof.execution.status === 'completed';
+    return {
+        agent_progress: behaviorChanged && proof.execution.status === 'executing' ? 'show' : 'silent',
+        agent_completion: behaviorChanged && completed ? 'show' : 'silent',
+        companion_attention: companionAttention,
+        web_surface: 'none',
+        weekly_digest: proof.interruption.resolution === 'not_applicable'
+            && proof.feedback.status === 'none'
+            && proof.state !== 'blocked'
+            && proof.outcome.status === 'not_applicable'
+            ? 'exclude'
+            : 'include'
+    };
+}
+export function renderJudgmentValueProofProgress(proof) {
+    const placement = placeJudgmentValueProof(proof);
+    if (placement.agent_progress === 'silent')
+        return null;
+    const decision = requiredText(proof.decision.summary ?? '', 'decision.summary');
+    const execution = optionalText(proof.execution.summary) ?? '作業を続行しています';
+    return `Brainbaseが判断を代行：${decision}。確認で止めず、${execution}。`;
+}
+export function renderJudgmentValueProofCompletion(proof) {
+    const placement = placeJudgmentValueProof(proof);
+    if (placement.agent_completion === 'silent')
+        return null;
+    const result = optionalText(proof.outcome.summary)
+        ?? optionalText(proof.execution.summary)
+        ?? '実行は完了しましたが、結果の要約はありません';
+    const decision = requiredText(proof.decision.summary ?? '', 'decision.summary');
+    const impact = optionalText(proof.decision.work_impact) ?? '確認による中断を避けて作業を継続';
+    const basis = proof.decision.basis.length > 0
+        ? proof.decision.basis.map((entry) => entry.application).join(' / ')
+        : '適用根拠は未確認';
+    const evidence = proof.outcome.evidence_refs.length > 0
+        ? proof.outcome.evidence_refs.map(evidenceLabel).join(' / ')
+        : '成果証跡なし';
+    return [
+        'Brainbase判断レシート',
+        `結果: ${result}`,
+        `判断: ${decision}`,
+        `仕事への影響: ${impact}`,
+        `根拠: ${basis}`,
+        `状態: ${outcomeStatusLabel(proof.outcome.status)}`,
+        `証拠: ${evidence}`,
+        '修正する場合: 「判断を修正: …」または「次回は確認」と返信'
+    ].join('\n');
+}
+export function renderJudgmentHumanDecisionRequest(proof) {
+    validateJudgmentValueProof(proof);
+    if (proof.interruption.resolution !== 'human_required' || !proof.human_decision)
+        return null;
+    const options = proof.human_decision.options.length > 0
+        ? proof.human_decision.options.map((option) => (`${option.id}. ${option.label}\n   影響: ${option.impact}`)).join('\n')
+        : '選択肢はまだ整理できていません';
+    return [
+        '人間判断が必要です',
+        `判断: ${proof.human_decision.question}`,
+        `AIで決めない理由: ${proof.human_decision.why_human}`,
+        '選択肢:',
+        options
+    ].join('\n');
+}
+export function projectJudgmentValueProofAttention(proof) {
+    const placement = placeJudgmentValueProof(proof);
+    const kind = placement.companion_attention;
+    if (kind === 'none')
+        return null;
+    if (kind === 'human_decision' && proof.human_decision) {
+        return {
+            schema_version: 'brainbase-judgment-value-proof-attention-v1',
+            intent_id: proof.intent_id,
+            decision_attempt_id: proof.decision_attempt_id,
+            kind,
+            title: '人間判断が必要',
+            summary: `${proof.human_decision.question} — ${proof.human_decision.why_human}`,
+            suggested_actions: proof.human_decision.options.map((option) => `${option.id}: ${option.label}`)
+        };
+    }
+    if (kind === 'blocked') {
+        return {
+            schema_version: 'brainbase-judgment-value-proof-attention-v1',
+            intent_id: proof.intent_id,
+            decision_attempt_id: proof.decision_attempt_id,
+            kind,
+            title: '作業が停止しています',
+            summary: optionalText(proof.execution.summary) ?? '停止理由は未確認です',
+            suggested_actions: ['停止理由を確認', '再実行条件を決める']
+        };
+    }
+    if (kind === 'outcome_unconfirmed') {
+        return {
+            schema_version: 'brainbase-judgment-value-proof-attention-v1',
+            intent_id: proof.intent_id,
+            decision_attempt_id: proof.decision_attempt_id,
+            kind,
+            title: '実行結果を確認できていません',
+            summary: optionalText(proof.execution.summary) ?? '実行は完了しました',
+            suggested_actions: ['正本を読み戻す', '結果未確認のまま保持']
+        };
+    }
+    return {
+        schema_version: 'brainbase-judgment-value-proof-attention-v1',
+        intent_id: proof.intent_id,
+        decision_attempt_id: proof.decision_attempt_id,
+        kind: 'feedback_requested',
+        title: '判断へのフィードバックが必要',
+        summary: optionalText(proof.decision.summary) ?? '判断内容を確認してください',
+        suggested_actions: ['正しい', '判断を修正', '次回は確認']
+    };
+}
+export function renderJudgmentValueProofWeeklyDigest(input) {
+    const periodLabel = requiredText(input.period_label, 'period_label');
+    if (input.coverage === 'unavailable') {
+        return `${periodLabel}のBrainbase判断実績は取得できませんでした。0件としては扱いません。`;
+    }
+    const proofs = input.proofs.map(validateJudgmentValueProof);
+    const included = proofs.filter((proof) => placeJudgmentValueProof(proof).weekly_digest === 'include');
+    const verified = included.filter((proof) => proof.outcome.status === 'outcome_verified').length;
+    const humanRequired = included.filter((proof) => proof.interruption.resolution === 'human_required').length;
+    const corrected = included.filter((proof) => proof.feedback.status === 'corrected'
+        || proof.feedback.status === 'reverted'
+        || proof.feedback.status === 'next_time_ask').length;
+    const unconfirmed = included.filter((proof) => proof.outcome.status === 'unconfirmed').length;
+    const blocked = included.filter((proof) => proof.state === 'blocked'
+        || proof.execution.status === 'blocked').length;
+    const continued = included.filter((proof) => proof.interruption.resolution === 'continued_without_human').length;
+    const coverage = input.coverage === 'partial' ? '（一部データのみ）' : '';
+    const representativeLimit = Math.max(0, Math.floor(input.representative_limit ?? 3));
+    const examples = included
+        .filter((proof) => proof.decision.summary || proof.outcome.summary)
+        .slice(0, representativeLimit)
+        .map((proof, index) => {
+        const decision = optionalText(proof.decision.summary) ?? '人間判断';
+        const result = optionalText(proof.outcome.summary) ?? outcomeStatusLabel(proof.outcome.status);
+        return `${index + 1}. ${decision}\n   → ${result}`;
+    });
+    return [
+        `${periodLabel}、Brainbaseが仕事をどう前に進めたか${coverage}`,
+        `確認せず続行した判断: ${continued}件`,
+        `成果確認まで完了: ${verified}件`,
+        `人間判断が必要: ${humanRequired}件`,
+        `判断の訂正・取消: ${corrected}件`,
+        `結果未確認: ${unconfirmed}件`,
+        `停止中: ${blocked}件`,
+        ...(examples.length > 0 ? ['', '代表例', ...examples] : [])
+    ].join('\n');
+}

package/dist/organization-graph.d.ts

@@ -0,0 +1,76 @@
+import { type PortableGraphBundle } from './portable-graph.js';
+import type { GraphRetrievalInput, GraphRetrievalResponse } from './graph-retrieval.js';
+/** The organization adapter is opt-in and never falls back after configuration. */
+export declare const ORGANIZATION_GRAPH_DEFAULT_TIMEOUT_MS = 10000;
+export declare const ORGANIZATION_GRAPH_MAX_RESPONSE_BYTES = 9000000;
+export interface OrganizationGraphConfig {
+    /** Organization service base URL, without credentials or query parameters. */
+    readonly url: string;
+    /** Bearer token. Never include this value in a returned error or receipt. */
+    readonly token: string;
+    readonly projectCode: string;
+    readonly graphId: string;
+    readonly fetch?: OrganizationGraphFetch;
+    readonly timeoutMs?: number;
+}
+export interface OrganizationGraphFetchResponse {
+    readonly status: number;
+    readonly headers?: {
+        get(name: string): string | null;
+    } | Map<string, string> | Record<string, string | undefined>;
+    readonly body?: {
+        getReader(): {
+            read(): Promise<{
+                done: boolean;
+                value?: Uint8Array;
+            }>;
+            cancel?(reason?: unknown): Promise<void>;
+        };
+    } | null;
+    text?(): Promise<string>;
+    json?(): Promise<unknown>;
+}
+export type OrganizationGraphFetch = (input: string, init: {
+    method: 'GET' | 'POST';
+    headers: Record<string, string>;
+    body?: string;
+    redirect: 'error';
+    signal: AbortSignal;
+}) => Promise<OrganizationGraphFetchResponse>;
+export interface PortableGraphReadback {
+    readonly bundle: unknown;
+    readonly digest: string;
+}
+export interface PortableGraphImportResult {
+    readonly status: 'imported' | 'unchanged';
+    readonly digest: string;
+}
+export declare class OrganizationGraphConfigError extends Error {
+    readonly code = "organization_config_invalid";
+    constructor(message: string);
+}
+export declare class OrganizationGraphError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Read the four organization settings as one all-or-nothing configuration.
+ * With no settings, OSS keeps its existing local-first behavior. A partial
+ * configuration is an error so a typo cannot silently select another store.
+ */
+export declare function createOrganizationGraphConfig(env?: Record<string, string | undefined>): OrganizationGraphConfig | undefined;
+/** Create a client without making a network request. */
+export declare function createOrganizationGraphClient(config: OrganizationGraphConfig): OrganizationGraphClient;
+export interface OrganizationGraphClient {
+    search(input: GraphRetrievalInput): Promise<GraphRetrievalResponse>;
+    importPortableGraph(bundle: unknown): Promise<PortableGraphImportResult>;
+    readPortableGraph(): Promise<PortableGraphReadback>;
+}
+/** Forward the existing Graph retrieval input unchanged inside the request envelope. */
+export declare function searchOrganizationGraph(config: OrganizationGraphConfig, input: GraphRetrievalInput): Promise<GraphRetrievalResponse>;
+/** Import is explicit; merely configuring the remote backend never uploads data. */
+export declare function importPortableGraph(config: OrganizationGraphConfig, bundle: unknown): Promise<PortableGraphImportResult>;
+/** Read and verify the complete organization-side bundle and its digest. */
+export declare function readPortableGraph(config: OrganizationGraphConfig): Promise<PortableGraphReadback>;
+/** Validate the privacy boundary before any upload leaves the local process. */
+export declare function assertPortableGraphBundle(bundle: unknown): asserts bundle is PortableGraphBundle;

package/dist/organization-graph.js

@@ -0,0 +1,331 @@
+import { portableGraphDigest, validatePortableGraph } from './portable-graph.js';
+/** The organization adapter is opt-in and never falls back after configuration. */
+export const ORGANIZATION_GRAPH_DEFAULT_TIMEOUT_MS = 10_000;
+export const ORGANIZATION_GRAPH_MAX_RESPONSE_BYTES = 9_000_000;
+const MAX_URL_LENGTH = 2_048;
+const MAX_TOKEN_LENGTH = 4_096;
+const MAX_PROJECT_CODE_LENGTH = 256;
+const MAX_GRAPH_ID_LENGTH = 128;
+const CONTROL_CHARACTER = /[\u0000-\u001f\u007f]/u;
+export class OrganizationGraphConfigError extends Error {
+    code = 'organization_config_invalid';
+    constructor(message) {
+        super(`${'organization_config_invalid'}: ${message}`);
+        this.name = 'OrganizationGraphConfigError';
+    }
+}
+export class OrganizationGraphError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.name = 'OrganizationGraphError';
+        this.code = code;
+    }
+}
+/**
+ * Read the four organization settings as one all-or-nothing configuration.
+ * With no settings, OSS keeps its existing local-first behavior. A partial
+ * configuration is an error so a typo cannot silently select another store.
+ */
+export function createOrganizationGraphConfig(env = process.env) {
+    const rawUrl = env.BRAINBASE_ORGANIZATION_URL;
+    const rawToken = env.BRAINBASE_ORGANIZATION_TOKEN;
+    const rawProjectCode = env.BRAINBASE_ORGANIZATION_PROJECT;
+    const rawGraphId = env.BRAINBASE_ORGANIZATION_GRAPH_ID;
+    const configured = [rawUrl, rawToken, rawProjectCode, rawGraphId].some((value) => value !== undefined);
+    if (!configured)
+        return undefined;
+    const missing = [
+        ['BRAINBASE_ORGANIZATION_URL', rawUrl],
+        ['BRAINBASE_ORGANIZATION_TOKEN', rawToken],
+        ['BRAINBASE_ORGANIZATION_PROJECT', rawProjectCode],
+        ['BRAINBASE_ORGANIZATION_GRAPH_ID', rawGraphId]
+    ].filter(([, value]) => typeof value !== 'string' || value.trim() === '').map(([name]) => name);
+    if (missing.length > 0) {
+        throw new OrganizationGraphConfigError(`all organization settings must be set together; missing ${missing.join(', ')}`);
+    }
+    return {
+        url: validateOrganizationUrl(rawUrl),
+        token: validateToken(rawToken),
+        projectCode: validateProjectCode(rawProjectCode),
+        graphId: validateGraphId(rawGraphId)
+    };
+}
+/** Create a client without making a network request. */
+export function createOrganizationGraphClient(config) {
+    // Validate injected configurations as well as environment-derived ones.
+    const normalized = {
+        ...config,
+        url: validateOrganizationUrl(config.url),
+        token: validateToken(config.token),
+        projectCode: validateProjectCode(config.projectCode),
+        graphId: validateGraphId(config.graphId)
+    };
+    return {
+        search: (input) => searchOrganizationGraph(normalized, input),
+        importPortableGraph: (bundle) => importPortableGraph(normalized, bundle),
+        readPortableGraph: () => readPortableGraph(normalized)
+    };
+}
+/** Forward the existing Graph retrieval input unchanged inside the request envelope. */
+export async function searchOrganizationGraph(config, input) {
+    const payload = await requestJson(config, 'POST', route(config, 'search'), {
+        project_code: config.projectCode,
+        input
+    });
+    return parseGraphRetrievalResponse(payload);
+}
+/** Import is explicit; merely configuring the remote backend never uploads data. */
+export async function importPortableGraph(config, bundle) {
+    assertPortableGraphBundle(bundle);
+    const expectedDigest = await portableGraphDigest(bundle);
+    const payload = await requestJson(config, 'POST', route(config, 'import'), {
+        project_code: config.projectCode,
+        bundle
+    });
+    const result = parseImportResult(payload);
+    if (result.digest !== expectedDigest) {
+        throw new OrganizationGraphError('organization_graph_digest_mismatch', 'organization service returned an import digest that does not match the uploaded bundle');
+    }
+    return result;
+}
+/** Read and verify the complete organization-side bundle and its digest. */
+export async function readPortableGraph(config) {
+    const payload = await requestJson(config, 'GET', route(config, undefined, { project_code: config.projectCode }));
+    const readback = parsePortableGraphReadback(payload);
+    assertPortableGraphBundle(readback.bundle);
+    const computedDigest = await portableGraphDigest(readback.bundle);
+    if (computedDigest !== readback.digest) {
+        throw new OrganizationGraphError('organization_graph_readback_mismatch', 'organization service returned a bundle whose digest does not match its contents');
+    }
+    return readback;
+}
+/** Validate the privacy boundary before any upload leaves the local process. */
+export function assertPortableGraphBundle(bundle) {
+    validatePortableGraph(bundle);
+}
+function parseGraphRetrievalResponse(value) {
+    if (!isRecord(value)
+        || (value.graphVersion !== 1 && value.graphVersion !== 2)
+        || (value.schemaVersion !== 1 && value.schemaVersion !== 2)
+        || (value.status !== 'ok' && value.status !== 'migration_required')
+        || typeof value.migrationRequired !== 'boolean'
+        || value.authority !== 'organization_graph'
+        || typeof value.query !== 'string'
+        || typeof value.asOf !== 'string'
+        || !['semantic', 'lexical', 'seed'].includes(String(value.method))
+        || !isRecord(value.semantic)
+        || typeof value.semantic.available !== 'boolean'
+        || !['semantic', 'lexical', 'seed'].includes(String(value.semantic.method))
+        || !Array.isArray(value.candidates)
+        || !Array.isArray(value.results)
+        || !Array.isArray(value.observedRelations)
+        || !Array.isArray(value.observedRelationCatalog)
+        || !isRecord(value.traversal)
+        || !Array.isArray(value.traversal.seedIds)
+        || !Array.isArray(value.traversal.steps)
+        || !Number.isInteger(value.traversal.maxSeeds)
+        || !Number.isInteger(value.traversal.maxSteps)
+        || !Number.isInteger(value.traversal.maxLimit)
+        || !['complete', 'partial', 'unknown'].includes(String(value.coverage))
+        || !Array.isArray(value.partialReasons)
+        || !Array.isArray(value.missingEvidence)
+        || !Array.isArray(value.evidence)
+        || !['needs_model_verification', 'insufficient'].includes(String(value.sufficiency))
+        || value.absenceConfirmed !== false) {
+        throw new OrganizationGraphError('organization_graph_response_invalid', 'organization service returned a response outside the OSS GraphRetrievalResponse contract');
+    }
+    return value;
+}
+function parseImportResult(value) {
+    if (!isRecord(value)
+        || (value.status !== 'imported' && value.status !== 'unchanged')
+        || typeof value.digest !== 'string'
+        || value.digest.trim() === '') {
+        throw new OrganizationGraphError('organization_graph_response_invalid', 'organization service returned an invalid import response');
+    }
+    return { status: value.status, digest: value.digest };
+}
+function parsePortableGraphReadback(value) {
+    if (!isRecord(value) || !('bundle' in value) || typeof value.digest !== 'string' || value.digest.trim() === '') {
+        throw new OrganizationGraphError('organization_graph_response_invalid', 'organization service returned an invalid Graph readback');
+    }
+    return { bundle: value.bundle, digest: value.digest };
+}
+async function requestJson(config, method, url, body) {
+    const fetchImpl = config.fetch ?? defaultFetch;
+    const startedAt = Date.now();
+    const controller = new AbortController();
+    const timeoutMs = validateTimeout(config.timeoutMs ?? ORGANIZATION_GRAPH_DEFAULT_TIMEOUT_MS);
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    if (typeof timer === 'object' && timer !== null && 'unref' in timer && typeof timer.unref === 'function')
+        timer.unref();
+    const headers = {
+        accept: 'application/json',
+        authorization: `Bearer ${config.token}`
+    };
+    if (body !== undefined)
+        headers['content-type'] = 'application/json';
+    let response;
+    try {
+        response = await withTimeout(fetchImpl(url, {
+            method,
+            headers,
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            redirect: 'error',
+            signal: controller.signal
+        }), controller, timeoutMs);
+    }
+    catch (error) {
+        clearTimeout(timer);
+        if (error instanceof OrganizationGraphError)
+            throw error;
+        if (controller.signal.aborted) {
+            throw new OrganizationGraphError('organization_graph_timeout', `organization service did not respond within ${timeoutMs}ms`);
+        }
+        throw new OrganizationGraphError('organization_graph_unavailable', 'organization service request failed');
+    }
+    clearTimeout(timer);
+    if (!Number.isInteger(response.status)) {
+        throw new OrganizationGraphError('organization_graph_unavailable', 'organization service returned an invalid HTTP status');
+    }
+    if (response.status >= 300 && response.status < 400) {
+        throw new OrganizationGraphError('organization_graph_redirect_rejected', 'organization service redirects are not accepted');
+    }
+    if (response.status === 401 || response.status === 403) {
+        throw new OrganizationGraphError('organization_graph_unauthorized', 'organization service rejected the configured credentials');
+    }
+    if (response.status < 200 || response.status >= 300) {
+        throw new OrganizationGraphError('organization_graph_request_failed', `organization service returned HTTP ${response.status}`);
+    }
+    let raw;
+    try {
+        raw = await withTimeout(readResponseText(response, controller, timeoutMs), controller, Math.max(1, timeoutMs - (Date.now() - startedAt)));
+    }
+    catch (error) {
+        if (error instanceof OrganizationGraphError)
+            throw error;
+        throw new OrganizationGraphError('organization_graph_response_invalid', 'organization service response could not be read');
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new OrganizationGraphError('organization_graph_response_invalid', 'organization service returned invalid JSON');
+    }
+}
+async function readResponseText(response, controller, timeoutMs) {
+    if (response.body) {
+        const reader = response.body.getReader();
+        const chunks = [];
+        let bytes = 0;
+        while (true) {
+            const part = await withTimeout(reader.read(), controller, timeoutMs);
+            if (part.done)
+                break;
+            const chunk = Buffer.from(part.value ?? new Uint8Array());
+            bytes += chunk.byteLength;
+            if (bytes > ORGANIZATION_GRAPH_MAX_RESPONSE_BYTES) {
+                await reader.cancel?.('response too large');
+                throw new OrganizationGraphError('organization_graph_response_too_large', 'organization service response exceeds the maximum size');
+            }
+            chunks.push(chunk);
+        }
+        return Buffer.concat(chunks).toString('utf8');
+    }
+    if (response.text) {
+        const raw = await withTimeout(response.text(), controller, timeoutMs);
+        if (Buffer.byteLength(raw, 'utf8') > ORGANIZATION_GRAPH_MAX_RESPONSE_BYTES) {
+            throw new OrganizationGraphError('organization_graph_response_too_large', 'organization service response exceeds the maximum size');
+        }
+        return raw;
+    }
+    if (response.json) {
+        const value = await withTimeout(response.json(), controller, timeoutMs);
+        const raw = JSON.stringify(value);
+        if (Buffer.byteLength(raw, 'utf8') > ORGANIZATION_GRAPH_MAX_RESPONSE_BYTES) {
+            throw new OrganizationGraphError('organization_graph_response_too_large', 'organization service response exceeds the maximum size');
+        }
+        return raw;
+    }
+    throw new OrganizationGraphError('organization_graph_response_invalid', 'organization service response has no readable body');
+}
+async function withTimeout(operation, controller, timeoutMs) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            reject(new OrganizationGraphError('organization_graph_timeout', `organization service did not respond within ${timeoutMs}ms`));
+        }, timeoutMs);
+        if (typeof timer === 'object' && timer !== null && 'unref' in timer && typeof timer.unref === 'function')
+            timer.unref();
+    });
+    try {
+        return await Promise.race([operation, timeout]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+function route(config, suffix, query) {
+    const base = new URL(config.url);
+    const prefix = base.pathname.replace(/\/+$/u, '');
+    const routePath = `${prefix}/api/info/graph/portable/${encodeURIComponent(config.graphId)}${suffix ? `/${suffix}` : ''}`;
+    const endpoint = new URL(routePath || '/', base.origin);
+    for (const [key, value] of Object.entries(query ?? {}))
+        endpoint.searchParams.set(key, value);
+    return endpoint.href;
+}
+function validateOrganizationUrl(raw) {
+    if (typeof raw !== 'string' || raw.trim() === '' || raw.length > MAX_URL_LENGTH) {
+        throw new OrganizationGraphConfigError('BRAINBASE_ORGANIZATION_URL must be a valid base URL');
+    }
+    let endpoint;
+    try {
+        endpoint = new URL(raw.trim());
+    }
+    catch {
+        throw new OrganizationGraphConfigError('BRAINBASE_ORGANIZATION_URL must be a valid base URL');
+    }
+    if (endpoint.username || endpoint.password || endpoint.search || endpoint.hash) {
+        throw new OrganizationGraphConfigError('BRAINBASE_ORGANIZATION_URL must not contain credentials, query parameters, or a fragment');
+    }
+    const host = endpoint.hostname.toLowerCase().replace(/^\[|\]$/gu, '');
+    const loopback = host === 'localhost' || host === '127.0.0.1' || host === '::1';
+    if (endpoint.protocol !== 'https:' && !(endpoint.protocol === 'http:' && loopback)) {
+        throw new OrganizationGraphConfigError('BRAINBASE_ORGANIZATION_URL must use HTTPS; HTTP is allowed only for loopback services');
+    }
+    endpoint.pathname = endpoint.pathname.replace(/\/+$/u, '') || '/';
+    return endpoint.href;
+}
+function validateToken(raw) {
+    if (typeof raw !== 'string' || raw.trim() === '' || raw.length > MAX_TOKEN_LENGTH || CONTROL_CHARACTER.test(raw)) {
+        throw new OrganizationGraphConfigError('BRAINBASE_ORGANIZATION_TOKEN is invalid');
+    }
+    return raw;
+}
+function validateProjectCode(raw) {
+    if (typeof raw !== 'string' || raw.trim() === '' || raw.length > MAX_PROJECT_CODE_LENGTH || CONTROL_CHARACTER.test(raw)) {
+        throw new OrganizationGraphConfigError('BRAINBASE_ORGANIZATION_PROJECT is invalid');
+    }
+    return raw.trim();
+}
+function validateGraphId(raw) {
+    if (typeof raw !== 'string' || raw.trim() === '' || raw.length > MAX_GRAPH_ID_LENGTH || !/^[A-Za-z0-9][A-Za-z0-9._~-]*$/u.test(raw)) {
+        throw new OrganizationGraphConfigError('BRAINBASE_ORGANIZATION_GRAPH_ID must be an opaque path-safe ID');
+    }
+    return raw;
+}
+function validateTimeout(value) {
+    if (!Number.isInteger(value) || value < 1 || value > 60_000) {
+        throw new OrganizationGraphConfigError('organization graph timeout must be an integer between 1 and 60000 milliseconds');
+    }
+    return value;
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+function defaultFetch(input, init) {
+    return fetch(input, init);
+}

package/dist/portable-graph.d.ts

@@ -0,0 +1,39 @@
+import { type GraphRetrievalInput, type GraphRetrievalResponse } from './graph-retrieval.js';
+import type { EmbeddingProvider } from './embedding-provider.js';
+import type { DecisionRecord, GraphFileV2, PersonalOs } from './types.js';
+/** The public, read-only interchange format for a canonical Graph v2 snapshot. */
+export declare const PORTABLE_GRAPH_SCHEMA_VERSION: 1;
+/** Bounds keep an imported snapshot finite before it reaches a runtime or model. */
+export declare const PORTABLE_GRAPH_MAX_ENTITIES = 10000;
+export declare const PORTABLE_GRAPH_MAX_EDGES = 25000;
+export declare const PORTABLE_GRAPH_MAX_DECISIONS = 10000;
+export declare const PORTABLE_GRAPH_MAX_JSON_BYTES = 8000000;
+export declare const PORTABLE_GRAPH_MAX_JSON_DEPTH = 64;
+export interface PortableGraphBundle {
+    schemaVersion: typeof PORTABLE_GRAPH_SCHEMA_VERSION;
+    graph: GraphFileV2;
+    decisions: DecisionRecord[];
+}
+/**
+ * Create a detached Graph v2 bundle for transfer between the OSS and
+ * organization runtimes. Personal KG, legacy relationships, source files, and
+ * the local data directory are deliberately outside this contract.
+ */
+export declare function createPortableGraph(os: PersonalOs): PortableGraphBundle;
+/**
+ * Validate the exact portable contract. Unknown top-level fields are rejected
+ * so an organization runtime cannot silently ignore a new capability. Unknown
+ * fields inside Graph records are retained after the canonical Graph validator
+ * accepts them, which keeps forward-compatible metadata lossless.
+ */
+export declare function validatePortableGraph(value: unknown): asserts value is PortableGraphBundle;
+/** Rehydrate a validated bundle into the shared retrieval input shape. */
+export declare function hydratePortableGraph(bundle: PortableGraphBundle): PersonalOs;
+/** Use exactly the OSS retrieval implementation against a portable bundle. */
+export declare function retrievePortableGraph(bundle: PortableGraphBundle, input: GraphRetrievalInput, provider?: EmbeddingProvider): Promise<GraphRetrievalResponse>;
+/** Canonical JSON with recursively sorted object keys and preserved array order. */
+export declare function canonicalPortableJson(value: unknown): string;
+/** Stable content identity for a portable Graph bundle. */
+export declare function portableGraphDigest(value: PortableGraphBundle): string;
+/** Descriptive alias for callers that prefer the content-identity wording. */
+export declare const digestPortableGraph: typeof portableGraphDigest;