@unson/brainbase-mcp 0.13.0 → 0.15.0

package/dist/foundation-authenticated-tools.d.ts

@@ -53,4 +53,14 @@ export type FoundationPublicToolDependencies = FoundationAuthenticatedToolDepend
 export declare const foundationPublicTools: Tool[];
 export declare function isFoundationPublicToolName(name: string): name is FoundationPublicToolName;
 export declare function handleFoundationPublicToolCall(name: string, args: Record<string, unknown>, dependencies: FoundationPublicToolDependencies): Promise<FoundationAuthenticatedToolResult | null>;
+/**
+ * brainbase-project ADR-015: adopt a Foundation draft for judgment and
+ * evaluation through the canonical API. The caller passes the revision and
+ * digest they reviewed (for example with foundation_read); the API refuses a
+ * draft that changed since, the draft's own owner, a caller without a gm or
+ * above grant for the project, and a definition not ready for judgment.
+ */
+export declare const foundationAdoptionTools: Tool[];
+export declare function isFoundationAdoptionToolName(name: string): boolean;
+export declare function handleFoundationAdoptionToolCall(name: string, args: Record<string, unknown>, dependencies: FoundationAuthenticatedToolDependencies): Promise<FoundationAuthenticatedToolResult | null>;
 export {};

package/dist/foundation-authenticated-tools.js

@@ -345,3 +345,89 @@ export async function handleFoundationPublicToolCall(name, args, dependencies) {
     }
     return { status: 'ok', scope: { project_codes: context.scope }, data: fetched.payload };
 }
+const FOUNDATION_ADOPTION_TYPES = new Set(['objective', 'variable', 'model', 'constraint']);
+const FOUNDATION_ADOPTION_PATH = '/api/company-os/foundation-adoptions';
+/**
+ * brainbase-project ADR-015: adopt a Foundation draft for judgment and
+ * evaluation through the canonical API. The caller passes the revision and
+ * digest they reviewed (for example with foundation_read); the API refuses a
+ * draft that changed since, the draft's own owner, a caller without a gm or
+ * above grant for the project, and a definition not ready for judgment.
+ */
+export const foundationAdoptionTools = [{
+        name: 'foundation_adopt',
+        description: [
+            'Adopt a Foundation draft (objective, variable, model or constraint) so it can be used for judgment and evaluation, never execution.',
+            'Read the draft first with foundation_read and pass the exact revision and digest you reviewed; the content is adopted unchanged as the next revision.',
+            'Only a gm or above of the project who is not the owner of the draft can adopt. This is a write: confirm with the person before calling it.',
+        ].join(' '),
+        inputSchema: {
+            type: 'object',
+            properties: {
+                scope_id: { type: 'string', minLength: 1, maxLength: MAX_SCOPE_ID_LENGTH, description: 'Project code the draft belongs to.' },
+                type: { type: 'string', enum: ['objective', 'variable', 'model', 'constraint'] },
+                id: { type: 'string', minLength: 1, maxLength: 256 },
+                revision: { type: 'string', pattern: '^[1-9][0-9]*$', description: 'The draft revision you reviewed.' },
+                digest: { type: 'string', pattern: '^sha256:[0-9a-f]{64}$', description: 'The digest of the reviewed revision, as foundation_read returned it.' },
+            },
+            required: ['scope_id', 'type', 'id', 'revision', 'digest'],
+            additionalProperties: false,
+        },
+    }];
+export function isFoundationAdoptionToolName(name) {
+    return name === 'foundation_adopt';
+}
+function isValidAdoptionPayload(args, payload) {
+    if (!isRecord(payload) || payload.action !== 'adopt' || !isRecord(payload.result))
+        return false;
+    const result = payload.result;
+    return result.id === args.id
+        && result.type === args.type
+        && result.revision === String(Number(args.revision) + 1)
+        && isNonEmptyString(result.digest)
+        && DIGEST_PATTERN.test(result.digest);
+}
+export async function handleFoundationAdoptionToolCall(name, args, dependencies) {
+    if (!isFoundationAdoptionToolName(name))
+        return null;
+    const scopeId = readScopeId(args);
+    if (!scopeId)
+        return invalidInput('scope_id is required and must be a safe project identifier', dependencies);
+    const unexpected = rejectUnexpectedKeys(args, ['scope_id', 'type', 'id', 'revision', 'digest'], dependencies);
+    if (unexpected)
+        return unexpected;
+    const type = readRequiredString(args, 'type');
+    const id = readRequiredString(args, 'id');
+    const revision = readRequiredString(args, 'revision');
+    const digest = readRequiredString(args, 'digest');
+    if (!type || !FOUNDATION_ADOPTION_TYPES.has(type))
+        return invalidInput('foundation type must be objective, variable, model or constraint', dependencies);
+    if (!id)
+        return invalidInput('foundation id is required', dependencies);
+    if (!revision || !REVISION_PATTERN.test(revision))
+        return invalidInput('foundation revision is invalid', dependencies);
+    if (!digest || !DIGEST_PATTERN.test(digest))
+        return invalidInput('foundation digest is invalid', dependencies);
+    const authenticated = await dependencies.auth.authenticateProject({ project_code: scopeId }, { requireProject: true });
+    if ('status' in authenticated)
+        return authenticated;
+    const context = selectedContext(authenticated, scopeId);
+    const csrf = await fetchFoundationCsrfToken(dependencies, context);
+    if (!csrf.ok)
+        return csrf.result;
+    const fetched = await dependencies.auth.fetchAuthenticatedJson(context, {
+        path: FOUNDATION_ADOPTION_PATH,
+        method: 'POST',
+        body: { id, type, revision, digest },
+        headers: { 'x-brainbase-scope': scopeId, 'x-session-id': csrf.sessionId, 'x-csrf-token': csrf.token },
+    });
+    if (!fetched.ok)
+        return fetched.result;
+    if (!fetched.response.ok)
+        return errorFromResponse(fetched.response, fetched.payload, context.scope, dependencies);
+    const normalizedArgs = { id, type, revision };
+    if (!fetched.payloadParsed || !isValidAdoptionPayload(normalizedArgs, fetched.payload)) {
+        return dependencies.auth.toolError('error', 'foundation_api_response_invalid', 'Brainbase API returned an invalid adoption response', context.scope, fetched.response.status);
+    }
+    return { status: 'ok', scope: { project_codes: context.scope }, data: fetched.payload };
+}

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

@@ -8,8 +8,9 @@ import type { FoundationDefinition, FoundationScope, FoundationType } from './on
  * principal, selected project, and current revision.
  */
 export declare const FOUNDATION_GRAPH_WRITE_CONTRACT_VERSION: "foundation-graph-draft-write.v1";
+export declare const FOUNDATION_GRAPH_ADOPTION_CONTRACT_VERSION: "foundation-graph-adoption.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 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' | 'ADOPTION_TARGET_CHANGED' | 'ADOPTER_IS_OWNER' | 'ALREADY_ADOPTED' | 'DEFINITION_NOT_READY' | 'AUTHORITY_REQUIRED';
 export interface FoundationGraphWriteIssue {
     readonly code: FoundationGraphWriteIssueCode;
     readonly path: string;
@@ -88,3 +89,62 @@ export declare function validateFoundationGraphWrite(input: unknown): Foundation
 export declare function normalizeFoundationGraphWrite(input: unknown): FoundationGraphWriteResult;
 /** Descriptive alias for callers that use the validation/normalization pair. */
 export declare const validateAndNormalizeFoundationGraphWrite: typeof normalizeFoundationGraphWrite;
+/**
+ * ADR-015: adopt the current Foundation draft for judgment and evaluation.
+ *
+ * The adopter names the revision and digest they reviewed. The contract only
+ * succeeds when that is the current Graph revision, the adopter is not the
+ * draft's owner, and the unchanged definition passes the judgment and
+ * evaluation checks. The adopted definition is the next revision with the same
+ * content; only the adoption state, authorized uses, storage class and an
+ * appended decision provenance entry change. Whether the adopter holds the
+ * required organization authority is decided by the host before this call and
+ * passed in as `adoption.authorityRef`.
+ */
+export interface FoundationGraphAdoptionInput {
+    readonly context: FoundationGraphWriteContext;
+    /** The current Graph row, as read under the adopter's access in the same transaction. */
+    readonly row: FoundationGraphWriteRow;
+    /** What the adopter reviewed. */
+    readonly expected: {
+        readonly revision: string;
+        readonly digest: string;
+    };
+    readonly adoption: {
+        readonly authorityRef: string;
+        readonly adoptedAt: string;
+    };
+}
+export interface FoundationGraphAdoptionRecord {
+    readonly adoptedBy: string;
+    readonly authorityRef: string;
+    readonly adoptedRevision: string;
+    readonly adoptedDigest: string;
+    readonly adoptedAt: string;
+}
+export interface FoundationGraphAdoptionResult {
+    readonly contractVersion: typeof FOUNDATION_GRAPH_ADOPTION_CONTRACT_VERSION;
+    readonly operation: 'adopt';
+    readonly projectCode: string;
+    readonly row: {
+        readonly id: string;
+        readonly type: FoundationType;
+        readonly revision: string;
+        readonly projectCode: string;
+        readonly payload: {
+            readonly foundation: FoundationDefinition;
+            readonly adoption: FoundationGraphAdoptionRecord;
+        };
+    };
+    readonly definition: FoundationDefinition;
+    readonly adoption: FoundationGraphAdoptionRecord;
+}
+export interface FoundationGraphAdoptionValidationResult {
+    readonly valid: boolean;
+    readonly status: 'valid' | 'invalid';
+    readonly issues: readonly FoundationGraphWriteIssue[];
+    readonly normalized?: FoundationGraphAdoptionResult;
+}
+export declare function validateFoundationGraphAdoption(input: unknown): FoundationGraphAdoptionValidationResult;
+/** Normalize a valid adoption or throw with the complete validation issues. */
+export declare function normalizeFoundationGraphAdoption(input: unknown): FoundationGraphAdoptionResult;

package/dist/foundation-graph-write.js

@@ -1,4 +1,4 @@
-import { cloneFoundationDefinition, nextFoundationRevision } from './foundation-catalog.js';
+import { cloneFoundationDefinition, digestFoundationDefinition, nextFoundationRevision } from './foundation-catalog.js';
 import { validateFoundationDefinition } from './ontology-foundation.js';
 /**
  * Contract for preparing a Foundation draft for the canonical Graph writer.
@@ -12,6 +12,10 @@ export const FOUNDATION_GRAPH_WRITE_CONTRACT_VERSION = 'foundation-graph-draft-w
 const FOUNDATION_TYPES = ['objective', 'variable', 'model', 'constraint'];
 const REVISION_PATTERN = /^[1-9]\d*$/u;
 const FOUNDATION_USES_DRAFT = ['draft'];
+/** ADR-015 F2: an adopted definition may be used for judgment and evaluation, never execution. */
+const FOUNDATION_USES_ADOPTED = ['draft', 'judgment', 'evaluation'];
+const DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/u;
+export const FOUNDATION_GRAPH_ADOPTION_CONTRACT_VERSION = 'foundation-graph-adoption.v1';
 /**
  * Error thrown by the throwing normalizer. The non-throwing validator should
  * be used at HTTP/MCP boundaries when callers need to render all issues.
@@ -207,6 +211,117 @@ export function normalizeFoundationGraphWrite(input) {
 }
 /** Descriptive alias for callers that use the validation/normalization pair. */
 export const validateAndNormalizeFoundationGraphWrite = normalizeFoundationGraphWrite;
+export function validateFoundationGraphAdoption(input) {
+    const issues = [];
+    const fail = () => ({ valid: false, status: 'invalid', issues });
+    if (!isRecord(input) || !isRecord(input.context) || !isRecord(input.row) || !isRecord(input.expected) || !isRecord(input.adoption)) {
+        issues.push({ code: 'INVALID_INPUT', path: 'input', message: 'Adoption needs context, row, expected and adoption objects.' });
+        return fail();
+    }
+    const context = input.context;
+    const row = input.row;
+    const expected = input.expected;
+    const adoption = input.adoption;
+    validateContext(context, issues);
+    validateGraphRow(row, issues);
+    if (isNonEmptyString(row.projectCode) && isNonEmptyString(context.projectCode) && row.projectCode !== context.projectCode) {
+        issues.push({ code: 'PROJECT_MISMATCH', path: 'row.projectCode', message: 'Graph row projectCode must match the trusted selected project.' });
+    }
+    if (!isCanonicalRevision(expected.revision) || typeof expected.digest !== 'string' || !DIGEST_PATTERN.test(expected.digest)) {
+        issues.push({ code: 'INVALID_INPUT', path: 'expected', message: 'expected needs the reviewed revision and its sha256 digest.' });
+    }
+    if (!isNonEmptyString(adoption.authorityRef)) {
+        issues.push({ code: 'AUTHORITY_REQUIRED', path: 'adoption.authorityRef', message: 'Adoption requires the evidence of the adopter\'s organization authority.' });
+    }
+    if (typeof adoption.adoptedAt !== 'string' || !isRfc3339(adoption.adoptedAt)) {
+        issues.push({ code: 'INVALID_INPUT', path: 'adoption.adoptedAt', message: 'adoption.adoptedAt must be an RFC 3339 timestamp.' });
+    }
+    if (issues.length > 0)
+        return fail();
+    const rowType = resolveRowType(row);
+    const current = unwrapFoundation(row.payload.foundation);
+    const currentResult = validateFoundationDefinition(current, { use: 'draft' });
+    appendDefinitionIssues(issues, 'row.payload.foundation', currentResult.issues);
+    if (!currentResult.valid || !isFoundationDefinitionRecord(current) || !rowType)
+        return fail();
+    if (current.id !== row.id || current.type !== rowType || current.revision !== row.revision) {
+        issues.push({ code: 'ROW_DEFINITION_MISMATCH', path: 'row.payload.foundation', message: 'The current definition must match the Graph row identity and revision.' });
+        return fail();
+    }
+    const currentDefinition = current;
+    const currentDigest = digestFoundationDefinition(currentDefinition);
+    if (expected.revision !== current.revision || expected.digest !== currentDigest) {
+        issues.push({
+            code: 'ADOPTION_TARGET_CHANGED',
+            path: 'expected',
+            message: `The reviewed revision ${String(expected.revision)} is not the current revision ${current.revision} with the same content.`
+        });
+    }
+    if (current.adoptionState !== 'draft') {
+        issues.push({ code: 'ALREADY_ADOPTED', path: 'row.payload.foundation.adoptionState', message: `Only a draft can be adopted; the current revision is ${String(current.adoptionState)}.` });
+    }
+    if (current.acl.ownerId === context.principal) {
+        issues.push({ code: 'ADOPTER_IS_OWNER', path: 'context.principal', message: 'The owner of a draft cannot adopt it.' });
+    }
+    validateCandidateScope(current, context, issues);
+    if (issues.length > 0)
+        return fail();
+    let revision;
+    try {
+        revision = nextFoundationRevision(current.revision);
+    }
+    catch {
+        issues.push({ code: 'REVISION_CONFLICT', path: 'row.revision', message: 'The next revision cannot be derived from the current revision.' });
+        return fail();
+    }
+    const authorityRef = String(adoption.authorityRef);
+    const adopted = cloneFoundationDefinition(currentDefinition);
+    adopted.revision = revision;
+    adopted.adoptionState = 'approved';
+    adopted.storage = 'ontology';
+    adopted.authorizedUses = [...FOUNDATION_USES_ADOPTED];
+    adopted.provenance = [
+        ...adopted.provenance,
+        { sourceId: `foundation-adoption:${current.id}@${current.revision}`, sourceKind: 'decision', evidenceIds: [authorityRef] }
+    ];
+    for (const use of ['judgment', 'evaluation']) {
+        const ready = validateFoundationDefinition(adopted, { use });
+        if (!ready.valid) {
+            for (const issue of ready.issues) {
+                issues.push({ code: 'DEFINITION_NOT_READY', path: `row.payload.foundation.${issue.path}`, message: `Not ready for ${use}: ${issue.message}` });
+            }
+        }
+    }
+    if (issues.length > 0)
+        return fail();
+    const record = {
+        adoptedBy: context.principal,
+        authorityRef,
+        adoptedRevision: current.revision,
+        adoptedDigest: currentDigest,
+        adoptedAt: String(adoption.adoptedAt)
+    };
+    return {
+        valid: true,
+        status: 'valid',
+        issues: [],
+        normalized: {
+            contractVersion: FOUNDATION_GRAPH_ADOPTION_CONTRACT_VERSION,
+            operation: 'adopt',
+            projectCode: context.projectCode,
+            row: { id: current.id, type: rowType, revision, projectCode: context.projectCode, payload: { foundation: adopted, adoption: record } },
+            definition: adopted,
+            adoption: record
+        }
+    };
+}
+/** Normalize a valid adoption or throw with the complete validation issues. */
+export function normalizeFoundationGraphAdoption(input) {
+    const result = validateFoundationGraphAdoption(input);
+    if (!result.valid || !result.normalized)
+        throw new FoundationGraphWriteError(result.issues);
+    return result.normalized;
+}
 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.' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unson/brainbase-mcp",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Local-first Brainbase judgment OS that lets supported AI agents reuse a user's approved goals, priorities, decisions, and judgment criteria.",
   "type": "module",
   "license": "MIT",
@@ -352,5 +352,5 @@
   "engines": {
     "node": ">=20"
   },
-  "gitHead": "c9b9adbff2dd409f77ed868d9c3939b3269f2d4f"
+  "gitHead": "2d242e478ef24937acfaf02363995d445974ed8e"
 }