@unson/brainbase-mcp 0.7.0 → 0.9.0

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;

package/dist/foundation-graph-write.js

@@ -0,0 +1,447 @@
+import { cloneFoundationDefinition, nextFoundationRevision } from './foundation-catalog.js';
+import { validateFoundationDefinition } 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 const FOUNDATION_GRAPH_WRITE_CONTRACT_VERSION = 'foundation-graph-draft-write.v1';
+const FOUNDATION_TYPES = ['objective', 'variable', 'model', 'constraint'];
+const REVISION_PATTERN = /^[1-9]\d*$/u;
+const FOUNDATION_USES_DRAFT = ['draft'];
+/**
+ * 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 class FoundationGraphWriteError extends Error {
+    code;
+    issues;
+    constructor(issues) {
+        const first = issues[0] ?? {
+            code: 'INVALID_INPUT',
+            path: 'input',
+            message: 'Foundation Graph write input is invalid.'
+        };
+        super(first.message);
+        this.name = 'FoundationGraphWriteError';
+        this.code = first.code;
+        this.issues = issues;
+    }
+}
+/**
+ * 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 function validateFoundationGraphWrite(input) {
+    const issues = [];
+    if (!isRecord(input)) {
+        return invalid(issues, {
+            code: 'INVALID_INPUT',
+            path: 'input',
+            message: 'Foundation Graph write input must be an object.'
+        });
+    }
+    const context = input.context;
+    const row = input.row;
+    if (!isRecord(context)) {
+        issues.push({ code: 'INVALID_INPUT', path: 'context', message: 'A trusted write context is required.' });
+    }
+    if (!isRecord(row)) {
+        issues.push({ code: 'INVALID_INPUT', path: 'row', message: 'A Graph row is required.' });
+    }
+    if (issues.length > 0)
+        return invalid(issues);
+    const trustedContext = context;
+    const graphRow = row;
+    validateContext(trustedContext, issues);
+    validateGraphRow(graphRow, issues);
+    if (isNonEmptyString(graphRow.projectCode)
+        && isNonEmptyString(trustedContext.projectCode)
+        && graphRow.projectCode !== trustedContext.projectCode) {
+        issues.push({
+            code: 'PROJECT_MISMATCH',
+            path: 'row.projectCode',
+            message: 'Graph row projectCode must match the trusted selected project.'
+        });
+    }
+    const expectedNextRevision = input.expectedNextRevision;
+    if (!isCanonicalRevision(expectedNextRevision)) {
+        issues.push({
+            code: 'INVALID_IDENTITY',
+            path: 'expectedNextRevision',
+            message: 'expectedNextRevision must be a positive canonical decimal revision.'
+        });
+    }
+    if (issues.length > 0)
+        return invalid(issues);
+    const rowType = resolveRowType(graphRow);
+    const rowId = graphRow.id;
+    const rowRevision = graphRow.revision;
+    const candidate = unwrapFoundation(graphRow.payload.foundation);
+    const definitionResult = validateFoundationDefinition(candidate, { use: 'draft' });
+    appendDefinitionIssues(issues, 'row.payload.foundation', definitionResult.issues);
+    if (!definitionResult.valid)
+        return invalid(issues);
+    if (!isFoundationDefinitionRecord(candidate)) {
+        issues.push({
+            code: 'DEFINITION_INVALID',
+            path: 'row.payload.foundation',
+            message: 'payload.foundation must be an object containing a registered Foundation definition.'
+        });
+    }
+    if (rowType !== undefined && isFoundationDefinitionRecord(candidate)) {
+        if (candidate.type !== rowType) {
+            issues.push({
+                code: 'ROW_DEFINITION_MISMATCH',
+                path: 'row.type',
+                message: `Graph row type ${rowType} does not match payload.foundation.type ${String(candidate.type)}.`
+            });
+        }
+    }
+    if (isFoundationDefinitionRecord(candidate)) {
+        if (candidate.id !== rowId) {
+            issues.push({
+                code: 'ROW_DEFINITION_MISMATCH',
+                path: 'row.id',
+                message: `Graph row id ${rowId} does not match payload.foundation.id ${String(candidate.id)}.`
+            });
+        }
+        if (candidate.revision !== rowRevision) {
+            issues.push({
+                code: 'ROW_DEFINITION_MISMATCH',
+                path: 'row.revision',
+                message: `Graph row revision ${rowRevision} does not match payload.foundation.revision ${String(candidate.revision)}.`
+            });
+        }
+        if (expectedNextRevision !== rowRevision) {
+            issues.push({
+                code: 'REVISION_CONFLICT',
+                path: 'expectedNextRevision',
+                message: `expectedNextRevision ${expectedNextRevision} must equal row.revision ${rowRevision}.`
+            });
+        }
+        validateDraftWriteInvariants(candidate, issues);
+        validateCandidateScope(candidate, trustedContext, issues);
+    }
+    const hasCurrentDefinition = input.currentDefinition !== undefined;
+    const operation = hasCurrentDefinition ? 'update' : 'create';
+    if (hasCurrentDefinition) {
+        const current = unwrapFoundation(input.currentDefinition);
+        validateCurrentDefinition(current, candidate, rowId, rowType, trustedContext, issues);
+        if (isFoundationDefinitionRecord(current) && isCanonicalRevision(current.revision) && isCanonicalRevision(rowRevision)) {
+            let expectedRevision;
+            try {
+                expectedRevision = nextFoundationRevision(current.revision);
+            }
+            catch {
+                expectedRevision = '';
+            }
+            if (expectedRevision !== rowRevision || expectedNextRevision !== expectedRevision) {
+                issues.push({
+                    code: 'REVISION_CONFLICT',
+                    path: 'row.revision',
+                    message: `An update must append revision ${expectedRevision}; received row ${rowRevision} and expectedNextRevision ${expectedNextRevision}.`
+                });
+            }
+        }
+    }
+    else {
+        if (rowRevision !== '1' || expectedNextRevision !== '1') {
+            issues.push({
+                code: 'REVISION_CONFLICT',
+                path: 'row.revision',
+                message: 'A new Foundation Graph row must start at revision 1.'
+            });
+        }
+        if (isFoundationDefinitionRecord(candidate) && candidate.acl.ownerId !== trustedContext.principal) {
+            issues.push({
+                code: 'OWNER_MISMATCH',
+                path: 'row.payload.foundation.acl.ownerId',
+                message: 'A new draft must be owned by the trusted principal.'
+            });
+        }
+    }
+    if (issues.length > 0 || !isFoundationDefinitionRecord(candidate) || !rowType) {
+        return invalid(issues, undefined, operation);
+    }
+    const normalizedDefinition = cloneFoundationDefinition(candidate);
+    // These assignments are intentionally explicit even after validation. They
+    // make the invariant visible in the object handed to the Host writer.
+    normalizedDefinition.adoptionState = 'draft';
+    normalizedDefinition.storage = 'candidate';
+    normalizedDefinition.authorizedUses = [...FOUNDATION_USES_DRAFT];
+    const normalized = {
+        contractVersion: FOUNDATION_GRAPH_WRITE_CONTRACT_VERSION,
+        operation,
+        projectCode: trustedContext.projectCode,
+        row: {
+            id: rowId,
+            type: rowType,
+            revision: rowRevision,
+            projectCode: trustedContext.projectCode,
+            payload: { foundation: normalizedDefinition }
+        },
+        definition: normalizedDefinition
+    };
+    return {
+        valid: true,
+        status: 'valid',
+        operation,
+        issues: [],
+        normalized
+    };
+}
+/** Normalize a valid candidate or throw with the complete validation issues. */
+export function normalizeFoundationGraphWrite(input) {
+    const result = validateFoundationGraphWrite(input);
+    if (!result.valid || !result.normalized)
+        throw new FoundationGraphWriteError(result.issues);
+    return result.normalized;
+}
+/** Descriptive alias for callers that use the validation/normalization pair. */
+export const validateAndNormalizeFoundationGraphWrite = normalizeFoundationGraphWrite;
+function validateContext(context, issues) {
+    if (!isNonEmptyString(context.principal)) {
+        issues.push({ code: 'INVALID_INPUT', path: 'context.principal', message: 'context.principal must be a non-empty trusted identifier.' });
+    }
+    if (!isNonEmptyString(context.projectCode)) {
+        issues.push({ code: 'INVALID_INPUT', path: 'context.projectCode', message: 'context.projectCode must be a non-empty selected project code.' });
+    }
+    if (context.scope !== undefined && !isScope(context.scope)) {
+        issues.push({ code: 'INVALID_INPUT', path: 'context.scope', message: 'context.scope must be a valid trusted scope.' });
+    }
+    else if (context.scope !== undefined && context.scope.subjectIds.length === 0) {
+        issues.push({ code: 'INVALID_INPUT', path: 'context.scope.subjectIds', message: 'context.scope must contain at least one trusted subject.' });
+    }
+}
+function validateGraphRow(row, issues) {
+    if (!isNonEmptyString(row.id)) {
+        issues.push({ code: 'INVALID_IDENTITY', path: 'row.id', message: 'Graph row id must be a non-empty string.' });
+    }
+    const rowType = resolveRowType(row);
+    if (!rowType || !isFoundationType(rowType)) {
+        issues.push({ code: 'INVALID_IDENTITY', path: 'row.type', message: 'Graph row type must be one of objective, variable, model, or constraint.' });
+    }
+    if (row.type !== undefined && row.entityType !== undefined && row.type !== row.entityType) {
+        issues.push({ code: 'ROW_DEFINITION_MISMATCH', path: 'row.type', message: 'row.type and row.entityType must identify the same type.' });
+    }
+    if (!isCanonicalRevision(row.revision)) {
+        issues.push({ code: 'INVALID_IDENTITY', path: 'row.revision', message: 'Graph row revision must be a positive canonical decimal.' });
+    }
+    if (!isNonEmptyString(row.projectCode)) {
+        issues.push({ code: 'INVALID_INPUT', path: 'row.projectCode', message: 'Graph row projectCode must be a non-empty string.' });
+    }
+    if (!isRecord(row.payload) || !('foundation' in row.payload)) {
+        issues.push({ code: 'INVALID_INPUT', path: 'row.payload.foundation', message: 'Graph row payload.foundation is required.' });
+    }
+}
+function validateDraftWriteInvariants(definition, issues) {
+    if (definition.adoptionState !== 'draft') {
+        issues.push({ code: 'DRAFT_ADOPTION_REQUIRED', path: 'row.payload.foundation.adoptionState', message: 'Foundation Graph write accepts draft definitions only.' });
+    }
+    if (definition.storage !== 'candidate') {
+        issues.push({ code: 'CANDIDATE_STORAGE_REQUIRED', path: 'row.payload.foundation.storage', message: 'Foundation Graph draft writes require storage=candidate.' });
+    }
+    if (!sameStringArray(definition.authorizedUses, FOUNDATION_USES_DRAFT)) {
+        issues.push({ code: 'DRAFT_AUTHORIZATION_REQUIRED', path: 'row.payload.foundation.authorizedUses', message: 'Foundation Graph draft writes require authorizedUses=[draft].' });
+    }
+    if (!Array.isArray(definition.provenance) || definition.provenance.length === 0) {
+        issues.push({ code: 'PROVENANCE_REQUIRED', path: 'row.payload.foundation.provenance', message: 'At least one non-empty source provenance entry is required.' });
+    }
+    else {
+        for (const [index, item] of definition.provenance.entries()) {
+            if (!isRecord(item) || !isNonEmptyString(item.sourceId)) {
+                issues.push({ code: 'PROVENANCE_REQUIRED', path: `row.payload.foundation.provenance[${index}].sourceId`, message: 'Each provenance entry requires a non-empty sourceId.' });
+            }
+        }
+    }
+}
+function validateCandidateScope(definition, context, issues) {
+    const scope = definition.scope;
+    if (!isScope(scope) || scope.subjectIds.length === 0) {
+        issues.push({ code: 'SCOPE_VIOLATION', path: 'row.payload.foundation.scope.subjectIds', message: 'A draft Graph write must identify at least one scoped subject.' });
+        return;
+    }
+    if (context.scope !== undefined) {
+        if (!isScope(context.scope) || context.scope.subjectIds.length === 0 || !scopeWithin(scope, context.scope)) {
+            issues.push({ code: 'SCOPE_VIOLATION', path: 'row.payload.foundation.scope', message: 'Foundation scope exceeds the trusted principal/project scope.' });
+        }
+        return;
+    }
+    if (!scope.subjectIds.every((subject) => subject === context.projectCode)) {
+        issues.push({ code: 'SCOPE_VIOLATION', path: 'row.payload.foundation.scope.subjectIds', message: 'Without a trusted scope, the draft scope must contain only the selected projectCode.' });
+    }
+}
+function validateCurrentDefinition(current, candidate, rowId, rowType, context, issues) {
+    if (!isFoundationDefinitionRecord(current)) {
+        issues.push({ code: 'CURRENT_DEFINITION_REQUIRED', path: 'currentDefinition', message: 'An update requires the current Foundation definition.' });
+        return;
+    }
+    const currentValidation = validateFoundationDefinition(current, { use: 'draft' });
+    appendDefinitionIssues(issues, 'currentDefinition', currentValidation.issues);
+    if (!currentValidation.valid)
+        return;
+    if (current.id !== rowId || (rowType !== undefined && current.type !== rowType)) {
+        issues.push({ code: 'ROW_DEFINITION_MISMATCH', path: 'currentDefinition', message: 'currentDefinition identity must match the Graph row.' });
+    }
+    if (isFoundationDefinitionRecord(candidate) && (current.id !== candidate.id || current.type !== candidate.type)) {
+        issues.push({ code: 'ROW_DEFINITION_MISMATCH', path: 'currentDefinition', message: 'currentDefinition identity must match the candidate definition.' });
+    }
+    if (current.acl.ownerId !== candidateAclOwner(candidate)) {
+        issues.push({ code: 'OWNER_MISMATCH', path: 'row.payload.foundation.acl.ownerId', message: 'An update must preserve the current owner.' });
+    }
+    const canWrite = current.acl.ownerId === context.principal || current.acl.writerIds.includes(context.principal);
+    if (!canWrite) {
+        issues.push({ code: 'WRITER_NOT_AUTHORIZED', path: 'currentDefinition.acl', message: 'The trusted principal is not an owner or writer in the current ACL.' });
+    }
+    if (isFoundationDefinitionRecord(candidate) && candidate.acl.ownerId !== current.acl.ownerId) {
+        issues.push({ code: 'OWNER_MISMATCH', path: 'row.payload.foundation.acl.ownerId', message: 'An update cannot transfer ownership through a draft write.' });
+    }
+    if (isFoundationDefinitionRecord(candidate) && isFoundationAcl(candidate.acl)
+        && !sameAcl(current.acl, candidate.acl)
+        && current.acl.ownerId !== context.principal) {
+        issues.push({
+            code: 'ACL_CHANGE_FORBIDDEN',
+            path: 'row.payload.foundation.acl',
+            message: 'Only the current owner may change ACL fields during a draft update.'
+        });
+    }
+    validateCandidateScope(current, context, issues);
+}
+function candidateAclOwner(value) {
+    return isRecord(value) && isRecord(value.acl) && typeof value.acl.ownerId === 'string'
+        ? value.acl.ownerId
+        : undefined;
+}
+function isFoundationAcl(value) {
+    return isRecord(value)
+        && isNonEmptyString(value.ownerId)
+        && (value.visibility === 'private'
+            || value.visibility === 'project'
+            || value.visibility === 'organization'
+            || value.visibility === 'public')
+        && Array.isArray(value.readerIds)
+        && value.readerIds.every(isNonEmptyString)
+        && Array.isArray(value.writerIds)
+        && value.writerIds.every(isNonEmptyString);
+}
+function sameAcl(left, right) {
+    return left.ownerId === right.ownerId
+        && left.visibility === right.visibility
+        && sameStringArray(left.readerIds, right.readerIds)
+        && sameStringArray(left.writerIds, right.writerIds);
+}
+function appendDefinitionIssues(issues, prefix, validationIssues) {
+    for (const issue of validationIssues) {
+        issues.push({
+            code: 'DEFINITION_INVALID',
+            path: `${prefix}.${issue.path}`,
+            message: issue.message
+        });
+    }
+}
+function invalid(issues, first, operation) {
+    if (first)
+        issues.unshift(first);
+    return {
+        valid: false,
+        status: 'invalid',
+        ...(operation === undefined ? {} : { operation }),
+        issues
+    };
+}
+function resolveRowType(row) {
+    const candidate = row.type ?? row.entityType;
+    return isFoundationType(candidate) ? candidate : undefined;
+}
+function isFoundationDefinitionRecord(value) {
+    return isRecord(value)
+        && isNonEmptyString(value.id)
+        && isFoundationType(value.type)
+        && isNonEmptyString(value.revision);
+}
+function unwrapFoundation(value) {
+    if (isRecord(value) && isRecord(value.foundation))
+        return value.foundation;
+    return value;
+}
+function isFoundationType(value) {
+    return typeof value === 'string' && FOUNDATION_TYPES.includes(value);
+}
+function isCanonicalRevision(value) {
+    return typeof value === 'string' && REVISION_PATTERN.test(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isScope(value) {
+    if (!isRecord(value) || !Array.isArray(value.subjectIds) || !value.subjectIds.every(isNonEmptyString))
+        return false;
+    if (!isNonEmptyString(value.validFrom) || !isRfc3339(value.validFrom))
+        return false;
+    if (value.validUntil !== undefined && (!isNonEmptyString(value.validUntil) || !isRfc3339(value.validUntil)))
+        return false;
+    if (value.validUntil === undefined)
+        return true;
+    return parseRfc3339(value.validUntil) > parseRfc3339(value.validFrom);
+}
+function scopeWithin(inner, outer) {
+    if (!inner.subjectIds.every((subject) => outer.subjectIds.includes(subject)))
+        return false;
+    const innerFrom = parseRfc3339(inner.validFrom);
+    const outerFrom = parseRfc3339(outer.validFrom);
+    if (innerFrom === undefined || outerFrom === undefined || innerFrom < outerFrom)
+        return false;
+    if (inner.validUntil === undefined)
+        return outer.validUntil === undefined;
+    const innerUntil = parseRfc3339(inner.validUntil);
+    if (innerUntil === undefined || outer.validUntil === undefined)
+        return innerUntil !== undefined && outer.validUntil === undefined;
+    const outerUntil = parseRfc3339(outer.validUntil);
+    return outerUntil !== undefined && innerUntil <= outerUntil;
+}
+function sameStringArray(left, right) {
+    return Array.isArray(left) && left.length === right.length && left.every((item, index) => item === right[index]);
+}
+function isRfc3339(value) {
+    return parseRfc3339(value) !== undefined;
+}
+function parseRfc3339(value) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?(Z|[+-]\d{2}:\d{2})$/u.exec(value);
+    if (!match)
+        return undefined;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const hour = Number(match[4]);
+    const minute = Number(match[5]);
+    const second = Number(match[6]);
+    if (month < 1 || month > 12 || day < 1 || day > daysInMonth(year, month) || hour > 23 || minute > 59 || second > 59)
+        return undefined;
+    const zone = match[8];
+    let offsetMinutes = 0;
+    if (zone !== 'Z') {
+        const offsetHour = Number(zone.slice(1, 3));
+        const offsetMinute = Number(zone.slice(4, 6));
+        if (offsetHour > 23 || offsetMinute > 59)
+            return undefined;
+        offsetMinutes = (zone[0] === '-' ? -1 : 1) * (offsetHour * 60 + offsetMinute);
+    }
+    const milliseconds = Number(((match[7] ?? '') + '000').slice(0, 3));
+    return Date.UTC(year, month - 1, day, hour, minute, second, milliseconds) - offsetMinutes * 60_000;
+}
+function daysInMonth(year, month) {
+    if (month === 2)
+        return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0) ? 29 : 28;
+    return [4, 6, 9, 11].includes(month) ? 30 : 31;
+}

package/dist/foundation-public-provider.d.ts

@@ -0,0 +1,140 @@
+import { type PhilosophyRevisionReader } from './philosophy-revision-reader.js';
+import type { FoundationRevisionStore, FoundationStoreContext } from './foundation-store.js';
+import { type JudgmentProblemReferenceProvider } from './judgment-problem-snapshot.js';
+import type { FoundationHttpRoute } from './foundation-http.js';
+export declare const FOUNDATION_PUBLIC_CONTRACT_VERSION: "foundation-public.v1";
+/** The host owns canonical storage and authentication. No body can supply either. */
+export declare function createFoundationPublicProvider(options: {
+    store: Pick<FoundationRevisionStore, 'read'>;
+    philosophyReader?: PhilosophyRevisionReader;
+    /** Canonical Observation/authority/etc. ports; cannot override Foundation or philosophy. */
+    resolveOther?: JudgmentProblemReferenceProvider['resolve'];
+}): {
+    describe(): {
+        contractVersion: "foundation-public.v1";
+        foundation: import("./ontology-foundation.js").JudgmentFoundationContract;
+        connection: string;
+        storage: string;
+        philosophy: {
+            kind: string;
+            canonicalSource: string;
+            connected: boolean;
+            immutableRevisionRequired: boolean;
+        };
+        historicalRead: string;
+        executionPermission: string;
+    };
+    read(raw: unknown, context: FoundationStoreContext): Promise<import("./types.js").FoundationCatalogRecord | import("./philosophy-revision-reader.js").PhilosophyRevisionRecord>;
+    validate(raw: unknown, context: FoundationStoreContext): Promise<import("./judgment-problem-snapshot.js").JudgmentProblemReferenceResolution>;
+    validateProblem(raw: unknown, context: FoundationStoreContext): Promise<{
+        status: "resolved";
+        executionPermission: "none";
+    }>;
+};
+export type FoundationPublicProvider = ReturnType<typeof createFoundationPublicProvider>;
+export interface FoundationPublicConnection {
+    provider: FoundationPublicProvider;
+    resolveContext(): FoundationStoreContext | null | Promise<FoundationStoreContext | null>;
+}
+export declare const foundationPublicToolDefinitions: readonly [{
+    readonly name: "foundation_describe";
+    readonly description: "Describe the connected versioned judgment foundation contract.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+        readonly additionalProperties: false;
+    };
+}, {
+    readonly name: "foundation_read";
+    readonly description: "Read an exact canonical foundation revision under current access rights.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["type", "id", "revision"];
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly type: {
+                readonly type: "string";
+                readonly enum: readonly ["objective", "variable", "model", "constraint", "philosophy"];
+            };
+            readonly id: {
+                readonly type: "string";
+            };
+            readonly revision: {
+                readonly type: "string";
+            };
+            readonly digest: {
+                readonly type: "string";
+            };
+        };
+    };
+}, {
+    readonly name: "foundation_validate_reference";
+    readonly description: "Validate an exact foundation or philosophy reference for judgment, including its dependencies.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["reference"];
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly reference: {
+                readonly type: "object";
+                readonly required: readonly ["kind", "id", "revision", "digest", "scope", "valid_from"];
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly kind: {
+                        readonly type: "string";
+                        readonly enum: readonly ["objective", "variable", "model", "constraint", "philosophy"];
+                    };
+                    readonly id: {
+                        readonly type: "string";
+                    };
+                    readonly revision: {
+                        readonly type: "string";
+                    };
+                    readonly digest: {
+                        readonly type: "string";
+                    };
+                    readonly scope: {
+                        readonly type: "object";
+                        readonly required: readonly ["type", "id"];
+                        readonly additionalProperties: false;
+                        readonly properties: {
+                            readonly type: {
+                                readonly type: "string";
+                                readonly enum: readonly ["personal", "project", "organization"];
+                            };
+                            readonly id: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                    readonly valid_from: {
+                        readonly type: "string";
+                    };
+                    readonly valid_to: {
+                        readonly type: readonly ["string", "null"];
+                    };
+                };
+            };
+            readonly phase: {
+                readonly type: "string";
+                readonly enum: readonly ["read", "historical_read"];
+            };
+        };
+    };
+}, {
+    readonly name: "foundation_validate_problem";
+    readonly description: "Validate a complete judgment snapshot and canonical observation measurement conditions. Grants no execution permission.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["snapshot"];
+        readonly properties: {
+            readonly snapshot: {
+                readonly type: "object";
+            };
+        };
+        readonly additionalProperties: false;
+    };
+}];
+export declare function callFoundationPublicTool(name: string, args: unknown, connection?: FoundationPublicConnection): Promise<unknown>;
+/** Mounted with createFoundationHttpRouter, whose host resolves auth and CSRF. */
+export declare function createFoundationPublicRoute(provider: FoundationPublicProvider): FoundationHttpRoute;