@unson/brainbase-mcp 0.4.0 → 0.5.0

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;

package/dist/portable-graph.js

@@ -0,0 +1,240 @@
+import { createHash } from 'node:crypto';
+import { validateCanonicalGraph } from './canonical-graph.js';
+import { retrieveGraph } from './graph-retrieval.js';
+/** The public, read-only interchange format for a canonical Graph v2 snapshot. */
+export const PORTABLE_GRAPH_SCHEMA_VERSION = 1;
+/** Bounds keep an imported snapshot finite before it reaches a runtime or model. */
+export const PORTABLE_GRAPH_MAX_ENTITIES = 10_000;
+export const PORTABLE_GRAPH_MAX_EDGES = 25_000;
+export const PORTABLE_GRAPH_MAX_DECISIONS = 10_000;
+export const PORTABLE_GRAPH_MAX_JSON_BYTES = 8_000_000;
+export const PORTABLE_GRAPH_MAX_JSON_DEPTH = 64;
+/**
+ * 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 function createPortableGraph(os) {
+    if (!os || typeof os !== 'object' || !('graph' in os) || !('decisions' in os)) {
+        throw new Error('PORTABLE-GRAPH-SOURCE: a PersonalOs with graph and decisions is required');
+    }
+    validateCanonicalGraph(os.graph);
+    if (os.graph.version !== 2) {
+        throw new Error('PORTABLE-GRAPH-V1-REJECTED: only Graph v2 can be exported');
+    }
+    if (!Array.isArray(os.decisions)) {
+        throw new Error('PORTABLE-GRAPH-DECISIONS: decisions must be an array');
+    }
+    const decisionIds = new Set(os.graph.entities.filter((entity) => entity.type === 'decision').map((entity) => entity.id));
+    const decisions = os.decisions
+        .filter((decision) => decisionIds.has(decision.id))
+        .map((decision) => structuredClone(decision))
+        .sort((left, right) => left.id.localeCompare(right.id, 'en'));
+    const bundle = {
+        schemaVersion: PORTABLE_GRAPH_SCHEMA_VERSION,
+        graph: structuredClone(os.graph),
+        decisions
+    };
+    validatePortableGraph(bundle);
+    return bundle;
+}
+/**
+ * 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 function validatePortableGraph(value) {
+    assertJsonValue(value, '$', new WeakSet(), 0);
+    if (!isPlainRecord(value))
+        throw new Error('PORTABLE-GRAPH-SHAPE: bundle must be a plain JSON object');
+    const topLevelKeys = Object.getOwnPropertyNames(value).sort();
+    const expected = ['decisions', 'graph', 'schemaVersion'];
+    const unknownKeys = topLevelKeys.filter((key) => !expected.includes(key));
+    if (unknownKeys.length > 0) {
+        throw new Error(`PORTABLE-GRAPH-SHAPE: unknown top-level field ${unknownKeys[0]}`);
+    }
+    if (value.schemaVersion !== PORTABLE_GRAPH_SCHEMA_VERSION) {
+        throw new Error(`PORTABLE-GRAPH-VERSION: unsupported portable schema version ${String(value.schemaVersion)}`);
+    }
+    if (!isPlainRecord(value.graph)) {
+        throw new Error('PORTABLE-GRAPH-SHAPE: graph must be a plain JSON object');
+    }
+    if (value.graph.version === 1) {
+        throw new Error('PORTABLE-GRAPH-V1-REJECTED: portable bundles require Graph v2');
+    }
+    if (!Array.isArray(value.decisions)) {
+        throw new Error('PORTABLE-GRAPH-DECISIONS: decisions must be an array');
+    }
+    const graph = value.graph;
+    if (graph.version !== 2) {
+        // Keep the canonical validator's explicit version error for other future
+        // versions while still making the portable boundary clear to callers.
+        validateCanonicalGraph(graph);
+    }
+    validateCanonicalGraph(graph);
+    if (graph.entities.length > PORTABLE_GRAPH_MAX_ENTITIES) {
+        throw new Error(`PORTABLE-GRAPH-BOUND: graph.entities exceeds ${PORTABLE_GRAPH_MAX_ENTITIES}`);
+    }
+    if (graph.edges.length > PORTABLE_GRAPH_MAX_EDGES) {
+        throw new Error(`PORTABLE-GRAPH-BOUND: graph.edges exceeds ${PORTABLE_GRAPH_MAX_EDGES}`);
+    }
+    if (value.decisions.length > PORTABLE_GRAPH_MAX_DECISIONS) {
+        throw new Error(`PORTABLE-GRAPH-BOUND: decisions exceeds ${PORTABLE_GRAPH_MAX_DECISIONS}`);
+    }
+    validateDecisionRecords(graph, value.decisions);
+    const bytes = Buffer.byteLength(canonicalPortableJson(value), 'utf8');
+    if (bytes > PORTABLE_GRAPH_MAX_JSON_BYTES) {
+        throw new Error(`PORTABLE-GRAPH-BOUND: JSON payload exceeds ${PORTABLE_GRAPH_MAX_JSON_BYTES} bytes`);
+    }
+}
+/** Rehydrate a validated bundle into the shared retrieval input shape. */
+export function hydratePortableGraph(bundle) {
+    validatePortableGraph(bundle);
+    return {
+        dataDir: '',
+        graph: structuredClone(bundle.graph),
+        personalKg: [],
+        relationships: { version: 1, relationships: [] },
+        decisions: structuredClone(bundle.decisions),
+        // sourceCount counts imported source files in the local SSOT. A portable
+        // Graph bundle contains no source files, so zero is the truthful value.
+        sourceCount: 0
+    };
+}
+/** Use exactly the OSS retrieval implementation against a portable bundle. */
+export function retrievePortableGraph(bundle, input, provider) {
+    return retrieveGraph(hydratePortableGraph(bundle), input, provider);
+}
+/** Canonical JSON with recursively sorted object keys and preserved array order. */
+export function canonicalPortableJson(value) {
+    assertJsonValue(value, '$', new WeakSet(), 0);
+    return stableJson(value, 0);
+}
+/** Stable content identity for a portable Graph bundle. */
+export function portableGraphDigest(value) {
+    validatePortableGraph(value);
+    return `sha256:${createHash('sha256').update(canonicalPortableJson(value), 'utf8').digest('hex')}`;
+}
+/** Descriptive alias for callers that prefer the content-identity wording. */
+export const digestPortableGraph = portableGraphDigest;
+function validateDecisionRecords(graph, decisions) {
+    const decisionEntities = new Set(graph.entities.filter((entity) => entity.type === 'decision').map((entity) => entity.id));
+    const records = new Map();
+    decisions.forEach((value, index) => {
+        if (!isPlainRecord(value))
+            throw new Error(`PORTABLE-GRAPH-DECISION-SHAPE at decisions[${index}]`);
+        requireNonEmptyString(value.id, `decisions[${index}].id`);
+        requireNonEmptyString(value.title, `decisions[${index}].title`);
+        requireNonEmptyString(value.decision, `decisions[${index}].decision`);
+        if (records.has(value.id))
+            throw new Error(`PORTABLE-GRAPH-DECISION-ID-UNIQUE: duplicate decision ID ${value.id}`);
+        records.set(value.id, value);
+        optionalString(value.topic, `decisions[${index}].topic`);
+        optionalString(value.rationale, `decisions[${index}].rationale`);
+        optionalString(value.updatedAt, `decisions[${index}].updatedAt`);
+        if (value.effectiveAt !== undefined) {
+            if (typeof value.effectiveAt !== 'string' || !isRfc3339(value.effectiveAt)) {
+                throw new Error(`PORTABLE-GRAPH-DECISION-DATE at decisions[${index}].effectiveAt`);
+            }
+        }
+        if (value.tags !== undefined && (!Array.isArray(value.tags) || value.tags.some((tag) => typeof tag !== 'string'))) {
+            throw new Error(`PORTABLE-GRAPH-DECISION-TAGS at decisions[${index}].tags`);
+        }
+        if (value.supersedes !== undefined) {
+            if (!Array.isArray(value.supersedes) || value.supersedes.some((id) => typeof id !== 'string' || id.trim() === '')) {
+                throw new Error(`PORTABLE-GRAPH-DECISION-SUPERSEDES at decisions[${index}].supersedes`);
+            }
+            const refs = new Set();
+            for (const target of value.supersedes) {
+                if (refs.has(target))
+                    throw new Error(`PORTABLE-GRAPH-DECISION-REFERENCE: duplicate supersedes reference ${target}`);
+                refs.add(target);
+            }
+        }
+    });
+    for (const id of decisionEntities) {
+        if (!records.has(id))
+            throw new Error(`PORTABLE-GRAPH-DECISION-REFERENCE: missing decision record for Graph entity ${id}`);
+    }
+    for (const [id, decision] of records) {
+        const entity = graph.entities.find((candidate) => candidate.id === id);
+        if (!entity || entity.type !== 'decision') {
+            throw new Error(`PORTABLE-GRAPH-DECISION-REFERENCE: decision record ${id} has no Graph decision entity`);
+        }
+        for (const target of decision.supersedes ?? []) {
+            if (!records.has(target)) {
+                throw new Error(`PORTABLE-GRAPH-DECISION-REFERENCE: decision ${id} supersedes missing decision ${target}`);
+            }
+        }
+    }
+}
+function requireNonEmptyString(value, path) {
+    if (typeof value !== 'string' || value.trim() === '')
+        throw new Error(`PORTABLE-GRAPH-STRING at ${path}`);
+}
+function optionalString(value, path) {
+    if (value !== undefined && typeof value !== 'string')
+        throw new Error(`PORTABLE-GRAPH-STRING at ${path}`);
+}
+function isRfc3339(value) {
+    return /^(?:\d{4})-(?:\d{2})-(?:\d{2})T(?:\d{2}):(?:\d{2}):(?:\d{2})(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/u.test(value) && Number.isFinite(Date.parse(value));
+}
+function isPlainRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function assertJsonValue(value, path, active, depth) {
+    if (depth > PORTABLE_GRAPH_MAX_JSON_DEPTH)
+        throw new Error(`PORTABLE-GRAPH-BOUND: JSON depth exceeds ${PORTABLE_GRAPH_MAX_JSON_DEPTH} at ${path}`);
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new Error(`PORTABLE-GRAPH-JSON: non-finite number at ${path}`);
+        return;
+    }
+    if (typeof value !== 'object')
+        throw new Error(`PORTABLE-GRAPH-JSON: non-JSON value at ${path}`);
+    if (active.has(value))
+        throw new Error(`PORTABLE-GRAPH-JSON: cyclic value at ${path}`);
+    active.add(value);
+    try {
+        if (Array.isArray(value)) {
+            for (let index = 0; index < value.length; index += 1) {
+                if (!(index in value))
+                    throw new Error(`PORTABLE-GRAPH-JSON: sparse array at ${path}[${index}]`);
+                assertJsonValue(value[index], `${path}[${index}]`, active, depth + 1);
+            }
+            return;
+        }
+        if (!isPlainRecord(value))
+            throw new Error(`PORTABLE-GRAPH-JSON: value at ${path} must be a plain JSON object`);
+        for (const key of Object.getOwnPropertyNames(value)) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor || !('value' in descriptor))
+                throw new Error(`PORTABLE-GRAPH-JSON: accessor at ${path}.${key}`);
+            assertJsonValue(descriptor.value, `${path}.${key}`, active, depth + 1);
+        }
+        if (Object.getOwnPropertySymbols(value).length > 0)
+            throw new Error(`PORTABLE-GRAPH-JSON: symbol key at ${path}`);
+    }
+    finally {
+        active.delete(value);
+    }
+}
+function stableJson(value, depth) {
+    if (depth > PORTABLE_GRAPH_MAX_JSON_DEPTH)
+        throw new Error(`PORTABLE-GRAPH-BOUND: JSON depth exceeds ${PORTABLE_GRAPH_MAX_JSON_DEPTH}`);
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string' || typeof value === 'boolean' || typeof value === 'number')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map((item) => stableJson(item, depth + 1)).join(',')}]`;
+    const record = value;
+    const pairs = Object.getOwnPropertyNames(record).sort().map((key) => `${JSON.stringify(key)}:${stableJson(record[key], depth + 1)}`);
+    return `{${pairs.join(',')}}`;
+}