@unson/brainbase-mcp 0.6.0 → 0.8.0

package/dist/foundation-constraint-store.js

@@ -0,0 +1,215 @@
+import { FoundationStoreError } from './foundation-store.js';
+import { ConstraintError, validateConstraintExceptionRecord, } from './constraint-resolution.js';
+/**
+ * Adapts the Objective Story's GraphFoundationRevisionStore to the resolver's
+ * ConstraintStore port.  Definitions are persisted in the existing PersonalOs
+ * aggregate through FoundationRevisionStore; no second Graph or file is
+ * created here.
+ */
+export class FoundationConstraintStore {
+    foundationStore;
+    exceptionStore;
+    constructor(options) {
+        this.foundationStore = options.foundationStore;
+        this.exceptionStore = options.exceptionStore;
+    }
+    async append(input, context) {
+        const storeContext = toFoundationContext(context);
+        let reference;
+        try {
+            if (input.expectedPreviousRevision === null) {
+                reference = await this.foundationStore.create(input.record, storeContext);
+            }
+            else if (input.expectedPreviousRevision !== undefined) {
+                reference = await this.foundationStore.update({
+                    reference: {
+                        id: input.record.id,
+                        type: 'constraint',
+                        revision: input.expectedPreviousRevision,
+                    },
+                    next: input.record,
+                    expectedRevision: input.expectedPreviousRevision,
+                }, storeContext);
+            }
+            else {
+                throw new ConstraintError('revision_conflict', 'Foundation constraint append requires an explicit previous revision or null for create', 409);
+            }
+        }
+        catch (error) {
+            throw normalizeFoundationError(error, input.record.id);
+        }
+        if (reference.id !== input.record.id || reference.type !== 'constraint' || reference.revision !== input.record.revision) {
+            throw new ConstraintError('constraint_store_corrupt', 'Foundation store returned a different constraint revision than requested', 500, {
+                id: input.record.id,
+                requestedRevision: input.record.revision,
+                storedRevision: reference.revision,
+            });
+        }
+        const readback = await this.get({ id: reference.id, revision: reference.revision }, context);
+        if (!readback) {
+            throw new ConstraintError('constraint_store_corrupt', 'Foundation constraint readback was empty', 500, {
+                id: reference.id,
+                revision: reference.revision,
+            });
+        }
+        return readback;
+    }
+    async get(ref, context) {
+        const storeContext = toFoundationContext(context);
+        try {
+            const record = await this.foundationStore.read({ id: ref.id, type: 'constraint', revision: ref.revision }, storeContext);
+            return record?.definition.type === 'constraint' ? record.definition : null;
+        }
+        catch (error) {
+            throw normalizeFoundationError(error, ref.id);
+        }
+    }
+    async getLatest(id, context) {
+        const storeContext = toFoundationContext(context);
+        try {
+            const record = await this.foundationStore.readLatest('constraint', id, storeContext);
+            return record?.definition.type === 'constraint' ? record.definition : null;
+        }
+        catch (error) {
+            throw normalizeFoundationError(error, id);
+        }
+    }
+    async list(query, context) {
+        const storeContext = toFoundationContext(context);
+        try {
+            if (query.revision !== undefined && query.id !== undefined) {
+                const exact = await this.get({ id: query.id, revision: query.revision }, context);
+                return exact && (query.ownerId === undefined || exact.acl.ownerId === query.ownerId) ? [exact] : [];
+            }
+            const records = await this.foundationStore.list('constraint', storeContext);
+            return records
+                .map((record) => record.definition)
+                .filter((definition) => definition.type === 'constraint')
+                .filter((definition) => query.id === undefined || definition.id === query.id)
+                .filter((definition) => query.ownerId === undefined || definition.acl.ownerId === query.ownerId)
+                .map((definition) => definition);
+        }
+        catch (error) {
+            throw normalizeFoundationError(error);
+        }
+    }
+    async appendException(exception, context) {
+        const resolvedContext = context ?? missingContext();
+        try {
+            validateConstraintExceptionRecord(exception);
+            await this.authorizeExceptionTarget(exception.constraintRef.id, exception.constraintRef.revision, resolvedContext, 'write');
+            return await this.exceptionStore.append(exception, resolvedContext);
+        }
+        catch (error) {
+            throw normalizeFoundationError(error, exceptionConstraintId(exception));
+        }
+    }
+    async listExceptions(query, context) {
+        const resolvedContext = context ?? missingContext();
+        try {
+            if (query.constraintId !== undefined) {
+                await this.authorizeExceptionTarget(query.constraintId, query.constraintRevision, resolvedContext, 'read');
+            }
+            const exceptions = await this.exceptionStore.list(query, resolvedContext);
+            for (const exception of exceptions) {
+                validateConstraintExceptionRecord(exception);
+                await this.authorizeExceptionTarget(exception.constraintRef.id, exception.constraintRef.revision, resolvedContext, 'read');
+            }
+            return exceptions;
+        }
+        catch (error) {
+            throw normalizeFoundationError(error, query.constraintId);
+        }
+    }
+    /**
+     * The injected exception boundary is intentionally persistence-only and may
+     * not enforce Foundation ACLs itself.  Resolve the referenced Constraint at
+     * this adapter boundary before allowing exception evidence to cross it.
+     * Current ACL controls access even when an exception points at an older
+     * revision; the exact revision is still read to reject dangling references.
+     */
+    async authorizeExceptionTarget(constraintId, constraintRevision, context, access) {
+        const storeContext = toFoundationContext(context);
+        const current = await this.foundationStore.readLatest('constraint', constraintId, storeContext);
+        if (!current || current.definition.type !== 'constraint') {
+            throw new ConstraintError('constraint_not_found', 'exception target constraint was not found', 404, { id: constraintId });
+        }
+        if (constraintRevision !== undefined) {
+            const referenced = await this.foundationStore.read({
+                id: constraintId,
+                type: 'constraint',
+                revision: constraintRevision,
+            }, storeContext);
+            if (!referenced || referenced.definition.type !== 'constraint') {
+                throw new ConstraintError('constraint_not_found', 'exception target constraint revision was not found', 404, { id: constraintId, revision: constraintRevision });
+            }
+        }
+        const target = current.definition;
+        if (target.acl.ownerId !== context.ownerId) {
+            throw new ConstraintError('scope_violation', 'exception target constraint is outside the authorization context', 403, { id: target.id, ownerId: target.acl.ownerId });
+        }
+        const canRead = target.acl.visibility === 'public'
+            || target.acl.ownerId === context.actorId
+            || target.acl.readerIds.includes(context.actorId)
+            || target.acl.writerIds.includes(context.actorId);
+        if (!canRead) {
+            throw new ConstraintError('authorization_denied', 'actor cannot read the exception target constraint', 403, { id: target.id });
+        }
+        if (access === 'write') {
+            const canWrite = target.acl.ownerId === context.actorId || target.acl.writerIds.includes(context.actorId);
+            if (!canWrite) {
+                throw new ConstraintError('authorization_denied', 'actor cannot write exceptions for the target constraint', 403, { id: target.id });
+            }
+        }
+    }
+}
+function exceptionConstraintId(exception) {
+    if (!exception || typeof exception !== 'object')
+        return undefined;
+    const reference = exception.constraintRef;
+    if (!reference || typeof reference !== 'object')
+        return undefined;
+    const id = reference.id;
+    return typeof id === 'string' ? id : undefined;
+}
+export function createFoundationConstraintStore(options) {
+    return new FoundationConstraintStore(options);
+}
+function toFoundationContext(context) {
+    // `ownerId` identifies the target scope.  It is caller supplied request
+    // data and must never be promoted to an authenticated principal.  The
+    // principal is the actor identity established by the trusted auth boundary.
+    if (!context?.actorId)
+        return missingContext();
+    return { principal: context.actorId };
+}
+function missingContext() {
+    throw new ConstraintError('authorization_denied', 'Foundation constraint persistence requires an authenticated actor context', 403);
+}
+function normalizeFoundationError(error, id) {
+    if (error instanceof ConstraintError)
+        return error;
+    if (error instanceof FoundationStoreError) {
+        switch (error.code) {
+            case 'invalid_input':
+                return new ConstraintError('invalid_constraint', error.message, 400, { id });
+            case 'not_found':
+                return new ConstraintError('constraint_not_found', error.message, 404, { id });
+            case 'revision_conflict':
+                return new ConstraintError('revision_conflict', error.message, 409, {
+                    id,
+                    currentRevision: error.currentRevision,
+                });
+            case 'authorization_denied':
+                return new ConstraintError('authorization_denied', error.message, 403, { id });
+            case 'scope_violation':
+                return new ConstraintError('scope_violation', error.message, 403, { id });
+            case 'corrupt_catalog':
+            case 'readback_mismatch':
+                return new ConstraintError('constraint_store_corrupt', error.message, 500, { id });
+            case 'unsupported_graph':
+                return new ConstraintError('constraint_store_unavailable', error.message, 503, { id });
+        }
+    }
+    return new ConstraintError('constraint_store_unavailable', 'Foundation constraint store failed', 503, { id });
+}

package/dist/foundation-graph-http.d.ts

@@ -0,0 +1,43 @@
+import { type FoundationHttpCsrfVerifier, type FoundationHttpRouter } from './foundation-http.js';
+/**
+ * Readiness probe for the Graph history contract used by the public adapter.
+ *
+ * The query is deliberately kept in the reusable adapter.  Hosts provide the
+ * transaction-bound query port, while the migration remains the authority for
+ * RLS and immutable-history trigger state.
+ */
+export declare const FOUNDATION_GRAPH_READY_SQL = "SELECT\n    EXISTS (SELECT 1 FROM pg_class WHERE oid = to_regclass('public.graph_foundation_revisions') AND relrowsecurity)\n    AND EXISTS (SELECT 1 FROM pg_trigger WHERE tgrelid = to_regclass('public.graph_entities')\n        AND tgname = 'graph_entities_foundation_history_capture' AND tgenabled = 'O' AND tgtype = 21\n        AND tgfoid = to_regprocedure('public.capture_graph_foundation_revision()'))\n    AND EXISTS (SELECT 1 FROM pg_trigger WHERE tgrelid = to_regclass('public.graph_foundation_revisions')\n        AND tgname = 'graph_foundation_revisions_guard' AND tgenabled = 'O' AND tgtype = 31\n        AND tgfoid = to_regprocedure('public.guard_graph_foundation_revision_mutation()'))\n    AND EXISTS (SELECT 1 FROM pg_trigger WHERE tgrelid = to_regclass('public.graph_foundation_revisions')\n        AND tgname = 'graph_foundation_revisions_truncate_guard' AND tgenabled = 'O' AND tgtype = 34\n        AND tgfoid = to_regprocedure('public.guard_graph_foundation_revision_mutation()')) AS ready";
+export declare const FOUNDATION_GRAPH_CONTRACT_VERSION: "foundation-graph-http.v1";
+type MaybePromise<T> = T | Promise<T>;
+export interface FoundationGraphTrustedIdentity {
+    /** Canonical principal supplied by the host authentication boundary. */
+    readonly principal: string;
+    /** Canonical organization scope supplied by the host authentication boundary. */
+    readonly organizationId: string;
+    /** Project scopes the authenticated principal may select. `*` is supported by hosts. */
+    readonly projectScopeIds: readonly string[];
+}
+export interface FoundationGraphQueryResult {
+    readonly rows: readonly Record<string, unknown>[];
+}
+export interface FoundationGraphQueryClient {
+    query(text: string, values?: readonly unknown[]): FoundationGraphQueryResult | Promise<FoundationGraphQueryResult>;
+}
+export interface FoundationGraphHttpOptions {
+    /** Resolve only trusted identity; request body and query values are never used for identity. */
+    readonly resolveTrustedIdentity: (request: Request) => MaybePromise<FoundationGraphTrustedIdentity | null>;
+    /** Run the shared provider inside the host's authenticated transaction/context. */
+    readonly withAccessContext: <T>(identity: FoundationGraphTrustedIdentity, callback: (client: FoundationGraphQueryClient) => Promise<T>) => Promise<T>;
+    /** Host-owned CSRF verification port for mutation requests. */
+    readonly csrf?: FoundationHttpCsrfVerifier;
+    readonly bodyLimitBytes?: number;
+}
+/**
+ * Create the reusable Graph-backed public Foundation handler.
+ *
+ * This is a native Fetch-style adapter. It has no Express, authentication, or
+ * organization dependency: a host injects a trusted identity resolver, an
+ * already-authenticated transaction port, and its CSRF verifier.
+ */
+export declare function createFoundationGraphHttpHandler(options: FoundationGraphHttpOptions): FoundationHttpRouter;
+export {};

package/dist/foundation-graph-http.js

@@ -0,0 +1,243 @@
+import { FOUNDATION_HTTP_CONTRACT_VERSION, createFoundationHttpRouter } from './foundation-http.js';
+import { createFoundationPublicProvider, createFoundationPublicRoute } from './foundation-public-provider.js';
+import { createGraphFoundationReaders } from './graph-foundation-reader.js';
+/**
+ * Readiness probe for the Graph history contract used by the public adapter.
+ *
+ * The query is deliberately kept in the reusable adapter.  Hosts provide the
+ * transaction-bound query port, while the migration remains the authority for
+ * RLS and immutable-history trigger state.
+ */
+export const FOUNDATION_GRAPH_READY_SQL = `SELECT
+    EXISTS (SELECT 1 FROM pg_class WHERE oid = to_regclass('public.graph_foundation_revisions') AND relrowsecurity)
+    AND EXISTS (SELECT 1 FROM pg_trigger WHERE tgrelid = to_regclass('public.graph_entities')
+        AND tgname = 'graph_entities_foundation_history_capture' AND tgenabled = 'O' AND tgtype = 21
+        AND tgfoid = to_regprocedure('public.capture_graph_foundation_revision()'))
+    AND EXISTS (SELECT 1 FROM pg_trigger WHERE tgrelid = to_regclass('public.graph_foundation_revisions')
+        AND tgname = 'graph_foundation_revisions_guard' AND tgenabled = 'O' AND tgtype = 31
+        AND tgfoid = to_regprocedure('public.guard_graph_foundation_revision_mutation()'))
+    AND EXISTS (SELECT 1 FROM pg_trigger WHERE tgrelid = to_regclass('public.graph_foundation_revisions')
+        AND tgname = 'graph_foundation_revisions_truncate_guard' AND tgenabled = 'O' AND tgtype = 34
+        AND tgfoid = to_regprocedure('public.guard_graph_foundation_revision_mutation()')) AS ready`;
+export const FOUNDATION_GRAPH_CONTRACT_VERSION = 'foundation-graph-http.v1';
+const DEFAULT_BODY_LIMIT_BYTES = 65_536;
+const DIRECT_FOUNDATION_REFERENCE_KINDS = new Set(['objective', 'variable', 'model', 'constraint', 'philosophy']);
+const SNAPSHOT_REFERENCE_KINDS = new Set([
+    'entity', 'edge', 'objective', 'criterion', 'variable', 'observation', 'model', 'constraint',
+    'philosophy', 'authority', 'resource', 'deadline', 'dag', 'evidence'
+]);
+const FOUNDATION_SCOPE_TYPES = new Set(['personal', 'project', 'organization']);
+function jsonResponse(status, value) {
+    return new Response(JSON.stringify(value), {
+        status,
+        headers: { 'content-type': 'application/json' }
+    });
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Return true only for the canonical scope shape. Incomplete or extended
+ * shapes stay on the shared validator path so it remains the source of
+ * malformed-input errors.
+ */
+function isCanonicalFoundationScope(value) {
+    return isRecord(value)
+        && Object.keys(value).length === 2
+        && typeof value.type === 'string'
+        && typeof value.id === 'string'
+        && value.type.length > 0
+        && value.id.length > 0
+        && value.type === value.type.trim()
+        && value.id === value.id.trim();
+}
+function isSelectedProjectScope(value, scopeId) {
+    return isCanonicalFoundationScope(value) && value.type === 'project' && value.id === scopeId;
+}
+function isAllowedFoundationReference(reference, scopeId, organizationId, knownKinds) {
+    if (!isRecord(reference) || !isCanonicalFoundationScope(reference.scope))
+        return true;
+    // Let the common validator report a missing/non-string kind as malformed;
+    // every present non-philosophy kind remains project-scoped.
+    if (typeof reference.kind !== 'string' || reference.kind.length === 0 || reference.kind !== reference.kind.trim())
+        return true;
+    // Unknown kinds and scope types remain the shared validator's responsibility.
+    // This boundary only narrows otherwise valid references.
+    if (!knownKinds.has(reference.kind) || !FOUNDATION_SCOPE_TYPES.has(reference.scope.type))
+        return true;
+    return isSelectedProjectScope(reference.scope, scopeId)
+        || (reference.kind === 'philosophy'
+            && reference.scope.type === 'organization'
+            && reference.scope.id === organizationId);
+}
+/**
+ * Reject scope widening before the common provider sees a request. The
+ * provider receives both the selected project and trusted organization so an
+ * organization philosophy can resolve, but all other foundation references
+ * remain project-scoped and measurements remain project-only.
+ */
+function hasFoundationScopeOverride(request, body, scopeId, organizationId) {
+    const method = (request.method || 'GET').toUpperCase();
+    if (!['POST', 'PUT', 'PATCH'].includes(method) || !isRecord(body))
+        return false;
+    const pathname = new URL(request.url).pathname;
+    if (pathname.endsWith('/judgment-references/validate')) {
+        return isRecord(body.reference)
+            && !isAllowedFoundationReference(body.reference, scopeId, organizationId, DIRECT_FOUNDATION_REFERENCE_KINDS);
+    }
+    if (!pathname.endsWith('/judgment-problems/validate'))
+        return false;
+    const snapshot = body.snapshot;
+    if (!isRecord(snapshot))
+        return false;
+    if (Object.hasOwn(snapshot, 'owner_scope')
+        && isCanonicalFoundationScope(snapshot.owner_scope)
+        && FOUNDATION_SCOPE_TYPES.has(snapshot.owner_scope.type)
+        && !isSelectedProjectScope(snapshot.owner_scope, scopeId)) {
+        return true;
+    }
+    if (!Array.isArray(snapshot.references))
+        return false;
+    return snapshot.references.some((reference) => {
+        if (!isRecord(reference))
+            return false;
+        if (Object.hasOwn(reference, 'scope')
+            && !isAllowedFoundationReference(reference, scopeId, organizationId, SNAPSHOT_REFERENCE_KINDS)) {
+            return true;
+        }
+        const measurement = reference.measurement;
+        const measurementScope = isRecord(measurement) ? measurement.scope : undefined;
+        const subjectIds = isRecord(measurementScope) ? measurementScope.subjectIds : undefined;
+        // Incomplete subjectIds remain the shared validator's responsibility.
+        return Array.isArray(subjectIds)
+            && subjectIds.length > 0
+            && subjectIds.every((subjectId) => typeof subjectId === 'string'
+                && subjectId === subjectId.trim()
+                && subjectId.length > 0)
+            && subjectIds.some((subjectId) => subjectId !== scopeId);
+    });
+}
+async function readJsonForScopeCheck(request, bodyLimitBytes) {
+    const method = (request.method || 'GET').toUpperCase();
+    const pathname = new URL(request.url).pathname;
+    if (!['POST', 'PUT', 'PATCH'].includes(method)
+        || (!pathname.endsWith('/judgment-references/validate') && !pathname.endsWith('/judgment-problems/validate'))) {
+        return null;
+    }
+    try {
+        const body = await request.clone().text();
+        if (new TextEncoder().encode(body).byteLength > bodyLimitBytes)
+            return null;
+        return JSON.parse(body);
+    }
+    catch {
+        // The shared route owns malformed JSON errors. A failed preflight must not
+        // turn malformed input into an authorization decision.
+        return null;
+    }
+}
+function identityIsValid(identity) {
+    if (!identity)
+        return false;
+    return typeof identity.principal === 'string'
+        && identity.principal.trim().length > 0
+        && typeof identity.organizationId === 'string'
+        && identity.organizationId.trim().length > 0
+        && Array.isArray(identity.projectScopeIds);
+}
+function selectedScopeIsAllowed(identity, scopeId) {
+    return identity.projectScopeIds.includes('*') || identity.projectScopeIds.includes(scopeId);
+}
+function readyResult(result) {
+    return result.rows[0]?.ready === true;
+}
+/**
+ * Create the reusable Graph-backed public Foundation handler.
+ *
+ * This is a native Fetch-style adapter. It has no Express, authentication, or
+ * organization dependency: a host injects a trusted identity resolver, an
+ * already-authenticated transaction port, and its CSRF verifier.
+ */
+export function createFoundationGraphHttpHandler(options) {
+    if (!options || typeof options.resolveTrustedIdentity !== 'function') {
+        throw new TypeError('resolveTrustedIdentity is required');
+    }
+    if (typeof options.withAccessContext !== 'function') {
+        throw new TypeError('withAccessContext is required');
+    }
+    const bodyLimitBytes = options.bodyLimitBytes ?? DEFAULT_BODY_LIMIT_BYTES;
+    if (!Number.isInteger(bodyLimitBytes) || bodyLimitBytes <= 0) {
+        throw new TypeError('bodyLimitBytes must be a positive integer');
+    }
+    return {
+        contractVersion: FOUNDATION_HTTP_CONTRACT_VERSION,
+        routes: [],
+        async handle(request) {
+            let identity;
+            try {
+                identity = await options.resolveTrustedIdentity(request);
+            }
+            catch {
+                identity = null;
+            }
+            if (!identityIsValid(identity)) {
+                return jsonResponse(403, { error: { code: 'foundation_trusted_context_required' } });
+            }
+            const url = new URL(request.url);
+            const scopeIds = url.searchParams.getAll('scope_id');
+            if (scopeIds.length !== 1 || !scopeIds[0]?.trim() || scopeIds[0] !== scopeIds[0].trim()) {
+                return jsonResponse(400, { error: { code: 'scope_id_required' } });
+            }
+            const scopeId = scopeIds[0];
+            if (!selectedScopeIsAllowed(identity, scopeId)) {
+                return jsonResponse(403, { error: { code: 'scope_not_allowed' } });
+            }
+            const body = await readJsonForScopeCheck(request, bodyLimitBytes);
+            if (hasFoundationScopeOverride(request, body, scopeId, identity.organizationId)) {
+                return jsonResponse(403, { error: { code: 'scope_not_allowed' } });
+            }
+            const context = {
+                principal: identity.principal,
+                scope: {
+                    subjectIds: [scopeId, identity.organizationId],
+                    validFrom: '1970-01-01T00:00:00Z'
+                }
+            };
+            try {
+                const response = await options.withAccessContext(identity, async (client) => {
+                    let ready;
+                    try {
+                        ready = await client.query(FOUNDATION_GRAPH_READY_SQL);
+                    }
+                    catch {
+                        return jsonResponse(503, { error: { code: 'foundation_provider_unavailable' } });
+                    }
+                    if (!readyResult(ready)) {
+                        return jsonResponse(503, { error: { code: 'foundation_migration_required' } });
+                    }
+                    const readers = createGraphFoundationReaders({
+                        context,
+                        query: async (text, values) => ({
+                            rows: (await client.query(text, values ?? [])).rows
+                        })
+                    });
+                    const provider = createFoundationPublicProvider(readers);
+                    const route = createFoundationPublicRoute(provider);
+                    const handler = createFoundationHttpRouter({
+                        resolveContext: () => context,
+                        csrf: options.csrf,
+                        routes: [route],
+                        bodyLimitBytes
+                    });
+                    return handler.handle(request);
+                });
+                return response instanceof Response
+                    ? response
+                    : jsonResponse(503, { error: { code: 'foundation_provider_unavailable' } });
+            }
+            catch {
+                return jsonResponse(503, { error: { code: 'foundation_provider_unavailable' } });
+            }
+        }
+    };
+}

package/dist/foundation-graph-write.d.ts

@@ -0,0 +1,90 @@
+import type { FoundationDefinition, FoundationScope, FoundationType } from './ontology-foundation.js';
+/**
+ * Contract for preparing a Foundation draft for the canonical Graph writer.
+ *
+ * This module deliberately stops at a pure, fail-closed validation boundary.
+ * It does not issue Graph queries, mutate a catalog, or infer a tenant from
+ * any value in the payload. The host must provide the already-authenticated
+ * principal, selected project, and current revision.
+ */
+export declare const FOUNDATION_GRAPH_WRITE_CONTRACT_VERSION: "foundation-graph-draft-write.v1";
+export type FoundationGraphWriteOperation = 'create' | 'update';
+export type FoundationGraphWriteIssueCode = 'INVALID_INPUT' | 'INVALID_IDENTITY' | 'ROW_DEFINITION_MISMATCH' | 'REVISION_CONFLICT' | 'CURRENT_DEFINITION_REQUIRED' | 'DEFINITION_INVALID' | 'DRAFT_ADOPTION_REQUIRED' | 'CANDIDATE_STORAGE_REQUIRED' | 'DRAFT_AUTHORIZATION_REQUIRED' | 'PROVENANCE_REQUIRED' | 'OWNER_MISMATCH' | 'ACL_CHANGE_FORBIDDEN' | 'WRITER_NOT_AUTHORIZED' | 'SCOPE_VIOLATION' | 'PROJECT_MISMATCH';
+export interface FoundationGraphWriteIssue {
+    readonly code: FoundationGraphWriteIssueCode;
+    readonly path: string;
+    readonly message: string;
+}
+/** Trusted context resolved before this pure contract is called. */
+export interface FoundationGraphWriteContext {
+    /** Host auth boundary value; callers should pass `access.personId`. */
+    readonly principal: string;
+    /** Selected canonical project code, never taken from the candidate payload. */
+    readonly projectCode: string;
+    /** Optional trusted subject/time scope for the selected project. */
+    readonly scope?: FoundationScope;
+}
+/**
+ * The host's Graph row shape. `type` is the canonical API name; `entityType`
+ * is accepted as a compatibility alias for adapters that mirror SQL rows.
+ */
+export interface FoundationGraphWriteRow {
+    readonly id: string;
+    readonly type?: string;
+    readonly entityType?: string;
+    readonly revision: string;
+    readonly projectCode: string;
+    readonly payload: {
+        readonly foundation: unknown;
+    };
+}
+export interface FoundationGraphWriteInput {
+    readonly context: FoundationGraphWriteContext;
+    readonly row: FoundationGraphWriteRow;
+    readonly expectedNextRevision: string;
+    readonly currentDefinition?: unknown;
+}
+export interface FoundationGraphWriteResult {
+    readonly contractVersion: typeof FOUNDATION_GRAPH_WRITE_CONTRACT_VERSION;
+    readonly operation: FoundationGraphWriteOperation;
+    readonly projectCode: string;
+    readonly row: {
+        readonly id: string;
+        readonly type: FoundationType;
+        readonly revision: string;
+        readonly projectCode: string;
+        readonly payload: {
+            readonly foundation: FoundationDefinition;
+        };
+    };
+    readonly definition: FoundationDefinition;
+}
+export interface FoundationGraphWriteValidationResult {
+    readonly valid: boolean;
+    readonly status: 'valid' | 'invalid';
+    readonly operation?: FoundationGraphWriteOperation;
+    readonly issues: readonly FoundationGraphWriteIssue[];
+    readonly normalized?: FoundationGraphWriteResult;
+}
+/**
+ * Error thrown by the throwing normalizer. The non-throwing validator should
+ * be used at HTTP/MCP boundaries when callers need to render all issues.
+ */
+export declare class FoundationGraphWriteError extends Error {
+    readonly code: FoundationGraphWriteIssueCode;
+    readonly issues: readonly FoundationGraphWriteIssue[];
+    constructor(issues: readonly FoundationGraphWriteIssue[]);
+}
+/**
+ * Validate and normalize an untrusted Graph upsert candidate.
+ *
+ * A successful result is safe to hand to a canonical Graph writer only after
+ * that writer also enforces its transaction/RLS boundary. This function proves
+ * the payload contract, identity, current ACL authorization, scope, and
+ * revision identity without performing any I/O.
+ */
+export declare function validateFoundationGraphWrite(input: unknown): FoundationGraphWriteValidationResult;
+/** Normalize a valid candidate or throw with the complete validation issues. */
+export declare function normalizeFoundationGraphWrite(input: unknown): FoundationGraphWriteResult;
+/** Descriptive alias for callers that use the validation/normalization pair. */
+export declare const validateAndNormalizeFoundationGraphWrite: typeof normalizeFoundationGraphWrite;