@unson/brainbase-mcp 0.10.15 → 0.12.0

package/contracts/judgment-value-proof/schema.json

@@ -154,7 +154,25 @@
         "entity_id": { "type": "string", "minLength": 1 },
         "application": { "type": "string", "minLength": 1 },
         "layer": { "enum": ["philosophy", "objective", "world_model", "method", "constraint", "other"] },
-        "version": { "type": ["string", "null"] }
+        "version": { "type": ["string", "null"] },
+        "source": {
+          "oneOf": [
+            { "type": "null" },
+            { "$ref": "#/$defs/basis_source" }
+          ]
+        }
+      }
+    },
+    "basis_source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "entity_id", "entity_type"],
+      "properties": {
+        "kind": { "const": "local_graph" },
+        "entity_id": { "type": "string", "minLength": 1 },
+        "entity_type": { "enum": ["person", "org", "project", "decision"] },
+        "version": { "type": ["string", "null"] },
+        "digest": { "type": ["string", "null"] }
       }
     },
     "inheritance_source": {

package/dist/execution-authority-http.d.ts

@@ -1,5 +1,5 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import { ExecutionAuthorityService, type ExecutionProblemReference } from './execution-authority.js';
+import { ExecutionAuthorityService, type ExecutionAttribution, type ExecutionProblemReference } from './execution-authority.js';
 type MaybePromise<T> = T | Promise<T>;
 /** Context resolved by the host after authentication and tenant selection. */
 export interface TrustedExecutionAuthorityRequestContext {
@@ -8,9 +8,11 @@ export interface TrustedExecutionAuthorityRequestContext {
     scopeId: string;
     /** A non-empty value means that the host already verified the mutation origin. */
     verifiedMutationOrigin?: string;
+    /** Resolved by the host from authentication. Request bodies cannot supply it. */
+    attribution?: ExecutionAttribution;
 }
 /** The factory is the boundary where a host binds a service to its trusted context. */
-export type ExecutionAuthorityServiceFactory = (context: TrustedExecutionAuthorityRequestContext) => MaybePromise<Pick<ExecutionAuthorityService, 'start' | 'readIntent'>>;
+export type ExecutionAuthorityServiceFactory = (context: TrustedExecutionAuthorityRequestContext) => MaybePromise<Pick<ExecutionAuthorityService, 'start' | 'readIntent'> & Partial<Pick<ExecutionAuthorityService, 'register' | 'reportEffect'>>>;
 export interface ExecutionAuthorityMutationVerificationInput {
     request: IncomingMessage;
     context: TrustedExecutionAuthorityRequestContext;

package/dist/execution-authority-http.js

@@ -21,6 +21,19 @@ const startRequestSchema = z.object({
     constraintRefs: z.array(boundedText).max(128),
     problem: problemSchema,
 }).strict();
+const attributionSchema = z.object({
+    mode: z.enum(['person', 'delegated_service', 'service']),
+    servicePrincipal: boundedText.optional(),
+    delegationRef: boundedText.optional(),
+    correlationId: boundedText.optional(),
+}).strict();
+const effectReportSchema = z.object({
+    tenantId: boundedText,
+    principal: boundedText,
+    scopeId: boundedText,
+    status: z.enum(['started', 'unknown']),
+    capabilityDigest: boundedText,
+}).strict();
 class HttpInputError extends Error {
     constructor(message) {
         super(message);
@@ -141,16 +154,21 @@ function matchRoute(path, basePath) {
     const suffix = normalized.slice(prefix.length);
     if (suffix === 'start')
         return { operation: 'start' };
+    if (suffix === 'register')
+        return { operation: 'register' };
     const intentPrefix = 'intents/';
     if (suffix.startsWith(intentPrefix)) {
-        const encodedOperationId = suffix.slice(intentPrefix.length);
+        const rest = suffix.slice(intentPrefix.length);
+        const reportSuffix = '/effect';
+        const operation = rest.endsWith(reportSuffix) ? 'report_effect' : 'read';
+        const encodedOperationId = operation === 'report_effect' ? rest.slice(0, -reportSuffix.length) : rest;
         if (encodedOperationId.length === 0 || encodedOperationId.includes('/'))
             return { operation: 'unknown' };
         try {
-            return { operation: 'read', operationId: decodeURIComponent(encodedOperationId) };
+            return { operation, operationId: decodeURIComponent(encodedOperationId) };
         }
         catch {
-            return { operation: 'read', operationId: undefined };
+            return { operation, operationId: undefined };
         }
     }
     return { operation: 'unknown' };
@@ -168,6 +186,21 @@ function assertContext(context) {
         || !boundedText.safeParse(context.scopeId).success) {
         throw new HttpInputError('Authenticated execution authority context is required');
     }
+    if (context.attribution !== undefined && !attributionIsConsistent(context.attribution, context.principal)) {
+        throw new HttpInputError('Authenticated execution attribution is inconsistent');
+    }
+}
+/** Mirrors the service rules so an inconsistent host context is an authentication failure. */
+function attributionIsConsistent(value, principal) {
+    const parsed = attributionSchema.safeParse(value);
+    if (!parsed.success)
+        return false;
+    const { mode, servicePrincipal, delegationRef } = parsed.data;
+    if (mode === 'person')
+        return servicePrincipal === undefined && delegationRef === undefined;
+    if (servicePrincipal === undefined || delegationRef === undefined)
+        return false;
+    return mode === 'delegated_service' ? servicePrincipal !== principal : servicePrincipal === principal;
 }
 function bindTrustedIdentity(body, context) {
     if (!isRecord(body))
@@ -201,6 +234,18 @@ function parseStartBody(body, context) {
         throw new HttpInputError(parsed.error.issues[0]?.message ?? 'Request body is invalid');
     return parsed.data;
 }
+function parseEffectReportBody(body, context, operationId) {
+    const bound = bindTrustedIdentity(body, context);
+    if (hasOwn(bound, 'operationId')) {
+        if (bound.operationId !== operationId)
+            throw new HttpInputError('operationId does not match the request path');
+        delete bound.operationId;
+    }
+    const parsed = effectReportSchema.safeParse(bound);
+    if (!parsed.success)
+        throw new HttpInputError(parsed.error.issues[0]?.message ?? 'Request body is invalid');
+    return { ...parsed.data, operationId };
+}
 function serviceError(error) {
     if (!(error instanceof ExecutionAuthorityError)) {
         return { status: 500, code: 'internal_error', message: 'Execution authority operation failed' };
@@ -208,6 +253,7 @@ function serviceError(error) {
     const status = (() => {
         switch (error.code) {
             case 'scope_mismatch':
+            case 'capability_mismatch':
             case 'authority_revoked':
             case 'authority_expired':
             case 'approval_revoked':
@@ -224,7 +270,12 @@ function serviceError(error) {
             case 'approval_unknown':
             case 'constraint_unknown':
             case 'reservation_unknown':
+            case 'store_unavailable':
                 return 503;
+            case 'intent_not_found':
+                return 404;
+            case 'effect_unconfigured':
+                return 501;
             case 'operation_conflict':
             case 'revision_conflict':
             case 'fencing_unsupported':
@@ -247,7 +298,9 @@ function writeError(response, status, code, message, headers = {}) {
     writeJson(response, status, { error: { code, message } }, headers);
 }
 function methodAllowed(operation, method) {
-    return operation === 'read' ? method === 'GET' : operation === 'start' ? method === 'POST' : false;
+    if (operation === 'read')
+        return method === 'GET';
+    return operation === 'unknown' ? false : method === 'POST';
 }
 async function verifyMutationRequest(options, request, context) {
     if (typeof context.verifiedMutationOrigin === 'string' && context.verifiedMutationOrigin.trim().length > 0)
@@ -333,6 +386,38 @@ export function createExecutionAuthorityHttpHandler(options) {
             }
             return true;
         }
+        const requestOptions = context.attribution ? { attribution: context.attribution } : {};
+        if (route.operation === 'report_effect') {
+            const parsedOperationId = boundedText.safeParse(route.operationId);
+            let report;
+            try {
+                if (!parsedOperationId.success)
+                    throw new HttpInputError('operationId is invalid');
+                report = parseEffectReportBody(body, context, parsedOperationId.data);
+            }
+            catch (error) {
+                writeError(response, 400, 'invalid_request', error instanceof Error ? error.message : 'Request body is invalid');
+                return true;
+            }
+            if (!await verifyMutationRequest(options, request, context)) {
+                writeError(response, 403, 'mutation_origin_unverified', 'Mutation origin could not be verified');
+                return true;
+            }
+            try {
+                const service = await options.serviceFactory(context);
+                if (typeof service.reportEffect !== 'function') {
+                    writeError(response, 501, 'operation_unconfigured', 'This host does not accept effect reports');
+                    return true;
+                }
+                const intent = await service.reportEffect(report);
+                writeJson(response, 200, { action: 'report_effect', operationId: report.operationId, result: { intent } });
+            }
+            catch (error) {
+                const failure = serviceError(error);
+                writeError(response, failure.status, failure.code, failure.message);
+            }
+            return true;
+        }
         let parsed;
         try {
             parsed = parseStartBody(body, context);
@@ -347,8 +432,18 @@ export function createExecutionAuthorityHttpHandler(options) {
         }
         try {
             const service = await options.serviceFactory(context);
-            const result = await service.start(parsed);
-            writeJson(response, 200, { action: 'start', operationId: parsed.operationId, result });
+            if (route.operation === 'register') {
+                if (typeof service.register !== 'function') {
+                    writeError(response, 501, 'operation_unconfigured', 'This host does not register executions');
+                    return true;
+                }
+                const result = await service.register(parsed, requestOptions);
+                writeJson(response, 200, { action: 'register', operationId: parsed.operationId, result });
+            }
+            else {
+                const result = await service.start(parsed, requestOptions);
+                writeJson(response, 200, { action: 'start', operationId: parsed.operationId, result });
+            }
         }
         catch (error) {
             const failure = serviceError(error);

package/dist/execution-authority.d.ts

@@ -14,6 +14,23 @@ export interface ExecutionStartInput {
     /** Evidence reference only. It never grants execution permission. */
     problem: ExecutionProblemReference;
 }
+/**
+ * Who started the execution, as resolved by the host from authenticated
+ * context. Request bodies never supply it.
+ */
+export type ExecutionAttributionMode = 'person' | 'delegated_service' | 'service';
+export interface ExecutionAttribution {
+    /** person: the principal acted directly. delegated_service: a service acted for the principal. service: an automated job acted on its own authority. */
+    mode: ExecutionAttributionMode;
+    /** Authenticated service principal. Required unless mode is person. */
+    servicePrincipal?: string;
+    /** Verified delegation, or for mode service the authority grant that the job relies on. */
+    delegationRef?: string;
+    correlationId?: string;
+}
+export interface ExecutionRequestOptions {
+    attribution?: ExecutionAttribution;
+}
 export type ExecutionCheckKind = 'authority' | 'approval' | 'constraint' | 'reservation';
 export type ExecutionVerificationPhase = 'initial' | 'final';
 export type ExecutionCheckStatus = 'approved' | 'revoked' | 'expired' | 'unknown';
@@ -23,6 +40,8 @@ export interface ExecutionCheckRequest extends ExecutionStartInput {
     phase: ExecutionVerificationPhase;
     /** The revision returned by the first check. Providers may fence on it. */
     expectedRevision?: string;
+    /** Present when the host resolved an attribution; providers verify delegation with it. */
+    attribution?: ExecutionAttribution;
 }
 export interface ExecutionCheckResult {
     status: ExecutionCheckStatus;
@@ -82,6 +101,7 @@ export interface ExecutionStartCapability {
     scopeId: string;
     issuedAt: string;
     expiresAt: string;
+    attribution?: ExecutionAttribution;
     checks: Record<ExecutionCheckKind, {
         revision: string;
         fencingToken: string;
@@ -91,7 +111,8 @@ export interface ExecutionStartCapability {
 export interface ExecutionEffectResult {
     status: 'started' | 'unknown';
 }
-export type ExecutionIntentPhase = 'recovery_required' | 'reservation_marked' | 'started' | 'unknown' | 'rejected';
+/** registered: checks passed and a permit was issued; the effect owner has not reported yet. */
+export type ExecutionIntentPhase = 'recovery_required' | 'reservation_marked' | 'registered' | 'started' | 'unknown' | 'rejected';
 export type ExecutionIntentEffectStatus = 'not_started' | 'started' | 'unknown';
 export type ExecutionIntentReservationMarkStatus = 'not_started' | 'started' | 'unknown';
 export interface ExecutionCheckRecord {
@@ -102,7 +123,7 @@ export interface ExecutionCheckRecord {
     expiresAt?: string;
     evidence: Record<string, string>;
 }
-export type ExecutionAuthorityErrorCode = 'validation_error' | 'authority_revoked' | 'authority_expired' | 'authority_unknown' | 'approval_revoked' | 'approval_expired' | 'approval_unknown' | 'constraint_revoked' | 'constraint_expired' | 'constraint_unknown' | 'reservation_revoked' | 'reservation_expired' | 'reservation_unknown' | 'read_revoked' | 'read_expired' | 'read_unknown' | 'revision_conflict' | 'fencing_unsupported' | 'capability_expired' | 'operation_conflict' | 'scope_mismatch' | 'recovery_required' | 'reservation_mark_unknown' | 'effect_unknown' | 'ledger_invalid';
+export type ExecutionAuthorityErrorCode = 'validation_error' | 'authority_revoked' | 'authority_expired' | 'authority_unknown' | 'approval_revoked' | 'approval_expired' | 'approval_unknown' | 'constraint_revoked' | 'constraint_expired' | 'constraint_unknown' | 'reservation_revoked' | 'reservation_expired' | 'reservation_unknown' | 'read_revoked' | 'read_expired' | 'read_unknown' | 'revision_conflict' | 'fencing_unsupported' | 'capability_expired' | 'operation_conflict' | 'scope_mismatch' | 'recovery_required' | 'reservation_mark_unknown' | 'effect_unknown' | 'effect_unconfigured' | 'capability_mismatch' | 'intent_not_found' | 'store_unavailable' | 'ledger_invalid';
 export interface ExecutionIntentFailure {
     code: ExecutionAuthorityErrorCode;
     reason: string;
@@ -120,6 +141,7 @@ export interface ExecutionIntentRecord {
     constraintRefs: string[];
     problem: ExecutionProblemReference;
     payloadDigest: string;
+    attribution?: ExecutionAttribution;
     phase: ExecutionIntentPhase;
     reservationMark: ExecutionIntentReservationMarkStatus;
     effect: {
@@ -133,6 +155,8 @@ export interface ExecutionIntentRecord {
     capability?: {
         expiresAt: string;
         digest: string;
+        /** Stored only for registrations so a lost response can be replayed. Never returned to readers. */
+        grant?: ExecutionStartCapability;
     };
     failure?: ExecutionIntentFailure;
     createdAt: string;
@@ -146,14 +170,51 @@ export interface ExecutionStartResult {
     };
     replayed: boolean;
 }
+export interface ExecutionRegistrationResult {
+    intent: ExecutionIntentRecord;
+    capability: ExecutionStartCapability;
+    capabilityDigest: string;
+    replayed: boolean;
+}
+export interface ExecutionEffectReport {
+    operationId: string;
+    tenantId: string;
+    principal: string;
+    scopeId: string;
+    /** Binds the report to the issued permit. It is not a secret. */
+    capabilityDigest: string;
+    status: 'started' | 'unknown';
+}
+export interface ExecutionIntentKey {
+    tenantId: string;
+    operationId: string;
+}
+/**
+ * Durable intent storage. A host injects a database adapter here; the default
+ * is the local sidecar. insert and update must each be atomic per key.
+ */
+export interface ExecutionIntentStore {
+    initialize?(): Promise<void>;
+    read(key: ExecutionIntentKey): Promise<ExecutionIntentRecord | undefined>;
+    /** Stores the intent when the key is absent; otherwise returns the existing record with created false. */
+    insert(intent: ExecutionIntentRecord): Promise<{
+        intent: ExecutionIntentRecord;
+        created: boolean;
+    }>;
+    /** Writes mutate(current) atomically. Returns undefined when absent. A throwing mutate writes nothing and rethrows. */
+    update(key: ExecutionIntentKey, mutate: (current: ExecutionIntentRecord) => ExecutionIntentRecord): Promise<ExecutionIntentRecord | undefined>;
+}
 export interface ExecutionAuthorityServiceOptions {
-    dataDir: string;
+    /** Used for the default sidecar store when store is omitted. */
+    dataDir?: string;
+    store?: ExecutionIntentStore;
     authority: ExecutionAuthorityPort;
     approval: ExecutionApprovalPort;
     constraint: ExecutionConstraintPort;
     reservation: ExecutionReservationPort;
     readAccess: ExecutionReadAccessPort;
-    effect: ExecutionEffectPort;
+    /** Required for start. Registration-only hosts leave the effect to its owner. */
+    effect?: ExecutionEffectPort;
     clock?: () => Date;
     sidecarPath?: string;
 }
@@ -163,11 +224,11 @@ export declare class ExecutionAuthorityError extends Error {
 }
 /**
  * Persists the execution intent before crossing either the reservation or
- * external-effect boundary. The reservation and intent sidecars are separate
+ * external-effect boundary. The reservation and intent stores are separate
  * transactions; callers must reconcile recovery_required/unknown states.
  */
 export declare class ExecutionAuthorityService {
-    private readonly dataDir;
+    private readonly store;
     private readonly authority;
     private readonly approval;
     private readonly constraint;
@@ -175,11 +236,23 @@ export declare class ExecutionAuthorityService {
     private readonly readAccess;
     private readonly effect;
     private readonly clock;
-    private readonly sidecarPath;
     constructor(options: ExecutionAuthorityServiceOptions);
     initialize(): Promise<void>;
-    start(input: ExecutionStartInput): Promise<ExecutionStartResult>;
+    /** Runs the checks, marks the reservation, and calls the in-process effect port. */
+    start(input: ExecutionStartInput, options?: ExecutionRequestOptions): Promise<ExecutionStartResult>;
+    /**
+     * Registers the execution: runs the checks, marks the reservation, and
+     * issues the permit. The effect owner reports the outcome with reportEffect.
+     */
+    register(input: ExecutionStartInput, options?: ExecutionRequestOptions): Promise<ExecutionRegistrationResult>;
+    /** Records the effect owner's outcome for a registered execution. */
+    reportEffect(report: ExecutionEffectReport): Promise<ExecutionIntentRecord>;
     readIntent(input: Pick<ExecutionStartInput, 'operationId' | 'tenantId' | 'principal' | 'scopeId'>): Promise<ExecutionIntentRecord | undefined>;
+    /**
+     * Shared path for start and register: initial checks, durable intent,
+     * fenced final checks, permit, and the reservation mark.
+     */
+    private prepare;
     private findIntent;
     private verifyReadAccess;
     private recordIntent;
@@ -188,8 +261,16 @@ export declare class ExecutionAuthorityService {
     private persistRecovery;
     private verifyAll;
     private handleExisting;
+    private replayRegistration;
+    /** Store failures are never success and never switch to another ledger. */
+    private storeCall;
     private now;
 }
+/** The default store: a JSON sidecar under the local SSOT lock. */
+export declare function createSidecarExecutionIntentStore(options: {
+    dataDir: string;
+    sidecarPath?: string;
+}): ExecutionIntentStore;
 /**
  * Binds the existing reservation store to the execution port without calling
  * it from inside the execution sidecar transaction. The store remains the