@unson/brainbase-mcp 0.44.0 → 0.44.1

package/dist/durable-wait-http.d.ts

@@ -1,5 +1,5 @@
 import { type IncomingMessage, type Server, type ServerResponse } from 'node:http';
-import { type DurableWaitStore } from './durable-waits.js';
+import { type DurableWaitDueCandidatesInput, type DurableWaitStore } from './durable-waits.js';
 /** Version of the HTTP boundary. The store version is returned separately. */
 export declare const DURABLE_WAIT_HTTP_VERSION: "durable-wait-http.v1";
 type MaybePromise<T> = T | Promise<T>;
@@ -8,6 +8,8 @@ export interface TrustedDurableWaitRequestContext {
     readonly tenantId: string;
     readonly principal: string;
     readonly scopeId: string;
+    /** Required for tenant-tagged waits and due discovery; resolved by the host, never from the request. */
+    readonly scopeType?: DurableWaitDueCandidatesInput['owner_scope_type'];
     /** A non-empty value means that the host already verified the mutation origin. */
     readonly verifiedMutationOrigin?: string;
 }

package/dist/durable-wait-http.js

@@ -96,8 +96,15 @@ const premiseChangedSchema = identitySchema.extend({
 const effectUnknownSchema = identitySchema.extend({
     wait_id: boundedText,
     reason: boundedText,
+    external_operation_id: boundedText.optional(),
     responsible: responsibleSchema.optional(),
 }).strict();
+const reconcileExternalEffectSchema = identitySchema.extend({
+    wait_id: boundedText,
+    request_id: boundedText,
+    external_operation_id: boundedText,
+    evidence_ref: boundedText,
+}).strict();
 class HttpInputError extends Error {
     constructor(message) {
         super(message);
@@ -209,6 +216,8 @@ function normalizePath(path) {
 }
 function matchRoute(path, basePath) {
     const normalized = normalizePath(path);
+    if (normalized === `${basePath}:due`)
+        return { operation: 'due' };
     if (normalized === basePath)
         return { operation: null };
     const prefix = `${basePath}/`;
@@ -216,7 +225,7 @@ function matchRoute(path, basePath) {
         return null;
     const suffix = normalized.slice(prefix.length);
     const operationNames = [
-        'create', 'claim', 'resume', 'handoff', 'premise-changed', 'effect-unknown',
+        'create', 'claim', 'resume', 'handoff', 'premise-changed', 'effect-unknown', 'reconcile-external-effect',
     ];
     if (operationNames.includes(suffix))
         return { operation: suffix };
@@ -273,8 +282,11 @@ function bindTrustedIdentity(body, context) {
     return input;
 }
 function assertOwnerScope(result, context) {
-    if (!isRecord(result) || !isRecord(result.owner_scope) || result.owner_scope.id !== context.scopeId) {
-        throw new DurableWaitError('unauthorized', 'Durable wait scope does not match the trusted request context');
+    if (!isRecord(result) || !isRecord(result.owner_scope)
+        || result.owner_scope.id !== context.scopeId
+        || (result.tenant_id !== undefined
+            && (result.tenant_id !== context.tenantId || result.owner_scope.type !== context.scopeType))) {
+        throw new DurableWaitError('unauthorized', 'Durable wait tenant or scope type and ID do not match the trusted request context');
     }
 }
 function serviceError(error) {
@@ -305,7 +317,30 @@ function writeError(response, status, code, message) {
     });
 }
 function methodAllowed(operation, method) {
-    return operation === 'read' ? method === 'GET' : operation !== null && method === 'POST';
+    return operation === 'read' || operation === 'due' ? method === 'GET' : operation !== null && method === 'POST';
+}
+function parseDueQuery(request) {
+    let url;
+    try {
+        url = new URL(request.url ?? '/', 'http://localhost');
+    }
+    catch {
+        throw new HttpInputError('Request URL is invalid');
+    }
+    for (const key of url.searchParams.keys()) {
+        if ((key !== 'limit' && key !== 'cursor') || url.searchParams.getAll(key).length !== 1) {
+            throw new HttpInputError('Due candidate query is invalid');
+        }
+    }
+    const rawLimit = url.searchParams.get('limit');
+    if (rawLimit !== null && !/^(?:[1-9]|[1-9][0-9]|100)$/u.test(rawLimit)) {
+        throw new HttpInputError('limit must be an integer from 1 to 100');
+    }
+    const cursor = url.searchParams.get('cursor');
+    return {
+        ...(rawLimit === null ? {} : { limit: Number(rawLimit) }),
+        ...(cursor === null ? {} : { cursor })
+    };
 }
 async function verifyMutationRequest(options, request, context) {
     if (typeof context.verifiedMutationOrigin === 'string' && context.verifiedMutationOrigin.trim().length > 0)
@@ -339,12 +374,14 @@ function parseBody(operation, body, context) {
             case 'handoff': return handoffSchema.safeParse(bound);
             case 'premise-changed': return premiseChangedSchema.safeParse(bound);
             case 'effect-unknown': return effectUnknownSchema.safeParse(bound);
+            case 'reconcile-external-effect': return reconcileExternalEffectSchema.safeParse(bound);
         }
     })();
     if (!parsed.success)
         throw new HttpInputError(parsed.error.issues[0]?.message ?? 'Request body is invalid');
     const value = parsed.data;
-    if ('owner_scope' in value && isRecord(value.owner_scope) && value.owner_scope.id !== context.scopeId) {
+    if ('owner_scope' in value && isRecord(value.owner_scope)
+        && (value.owner_scope.id !== context.scopeId || value.owner_scope.type !== context.scopeType)) {
         throw new HttpInputError('owner_scope does not match the trusted request context');
     }
     const { tenantId: _tenantId, scopeId: _scopeId, ...storeInput } = value;
@@ -396,6 +433,32 @@ export function createDurableWaitHttpHandler(options) {
             }
             return true;
         }
+        if (route.operation === 'due') {
+            try {
+                if (!context.scopeType || !['personal', 'project', 'organization'].includes(context.scopeType)) {
+                    throw new HttpInputError('Trusted scope type is required for due discovery');
+                }
+                const query = parseDueQuery(request);
+                const store = await options.storeFactory(context);
+                const result = await store.listDueCandidates({
+                    tenant_id: context.tenantId,
+                    principal: context.principal,
+                    owner_scope_type: context.scopeType,
+                    owner_scope_id: context.scopeId,
+                    ...query,
+                });
+                writeJson(response, 200, success(context, route.operation, result));
+            }
+            catch (error) {
+                if (error instanceof HttpInputError)
+                    writeError(response, 400, 'invalid_request', error.message);
+                else {
+                    const failure = serviceError(error);
+                    writeError(response, failure.status, failure.code, failure.message);
+                }
+            }
+            return true;
+        }
         let body;
         try {
             body = await readJsonBody(request, bodyLimitBytes);
@@ -434,7 +497,7 @@ export function createDurableWaitHttpHandler(options) {
             let result;
             switch (route.operation) {
                 case 'create':
-                    result = await store.create(parsed);
+                    result = await store.create({ ...parsed, tenant_id: context.tenantId });
                     assertOwnerScope(result, context);
                     break;
                 case 'claim': {
@@ -457,6 +520,10 @@ export function createDurableWaitHttpHandler(options) {
                     result = await store.markEffectUnknown(parsed);
                     assertOwnerScope(result, context);
                     break;
+                case 'reconcile-external-effect':
+                    result = await store.reconcileExternalEffect(parsed);
+                    assertOwnerScope(result, context);
+                    break;
             }
             writeJson(response, 200, success(context, route.operation, result));
         }

package/dist/durable-waits.d.ts

@@ -6,7 +6,7 @@ import type { FoundationAcl } from './ontology-foundation.js';
 export declare const DURABLE_WAIT_VERSION: "durable-wait.v1";
 export declare const DURABLE_WAIT_SIDECAR_PATH: "durable-waits/ledger.json";
 export declare const DURABLE_WAIT_LEDGER_VERSION: "durable-wait.v1";
-export type DurableWaitState = 'waiting' | 'claimed' | 'resumed' | 'handoff_required' | 'reconciliation_wait' | 'failed' | 'cancelled';
+export type DurableWaitState = 'waiting' | 'claimed' | 'resumed' | 'handoff_required' | 'reconciliation_wait' | 'effect_confirmed' | 'failed' | 'cancelled';
 export type DurableWaitTrigger = 'event' | 'timer' | 'manual';
 export type DurableWaitResumeMethod = 'resume_run' | 'new_problem' | 'reconcile_external_effect' | 'manual_review';
 export type DurableWaitFailurePolicy = 'handoff' | 'new_problem' | 'reconciliation_wait' | 'fail';
@@ -62,7 +62,7 @@ export interface DurableWaitResumeReceipt {
     readonly run_ref: DurableWaitRunReference;
     readonly recorded_at: string;
 }
-export type DurableWaitHistoryAction = 'create' | 'claim' | 'handoff' | 'premise_changed' | 'effect_unknown' | 'resume';
+export type DurableWaitHistoryAction = 'create' | 'claim' | 'handoff' | 'premise_changed' | 'effect_unknown' | 'effect_reconciled' | 'resume';
 export interface DurableWaitHistoryEntry {
     readonly action: DurableWaitHistoryAction;
     readonly occurred_at: string;
@@ -76,10 +76,28 @@ export interface DurableWaitReconciliation {
     readonly reason: string;
     readonly recorded_at: string;
     readonly responsible: DurableWaitResponsible;
+    /** Absent only in legacy records, which cannot be released by reconciliation. */
+    readonly external_operation_id?: string;
+    readonly claim_id?: string;
+    /** Only a trusted execution-intent lookup can set this to verified. */
+    readonly binding_status?: 'verified' | 'unverified';
+}
+export type DurableWaitExternalEffectOutcome = 'performed' | 'not_performed' | 'unknown';
+export interface DurableWaitReconciliationReceipt {
+    readonly request_id: string;
+    readonly external_operation_id: string;
+    readonly evidence_ref: string;
+    readonly outcome: DurableWaitExternalEffectOutcome;
+    readonly principal: string;
+    readonly recorded_at: string;
+    readonly previous_claim_request_id?: string;
+    readonly claim_id?: string;
 }
 export interface DurableWaitRecord {
     readonly wait_id: string;
     readonly version: typeof DURABLE_WAIT_VERSION;
+    /** Absent on legacy records; due enumeration never infers a tenant for them. */
+    readonly tenant_id?: string;
     readonly owner_scope: JudgmentProblemScope;
     readonly read_policy: FoundationAcl;
     readonly problem_snapshot: DurableWaitProblemReference;
@@ -96,10 +114,13 @@ export interface DurableWaitRecord {
     readonly resume_receipt?: DurableWaitResumeReceipt;
     readonly next_problem?: DurableWaitProblemReference;
     readonly reconciliation?: DurableWaitReconciliation;
+    readonly reconciliation_receipts?: readonly DurableWaitReconciliationReceipt[];
     readonly history: readonly DurableWaitHistoryEntry[];
 }
 export interface DurableWaitCreateInput {
     readonly wait_id?: string;
+    /** Host-authenticated tenant; callers must not copy this from an untrusted body. */
+    readonly tenant_id?: string;
     readonly principal: string;
     readonly owner_scope: JudgmentProblemScope;
     readonly read_policy: FoundationAcl;
@@ -118,6 +139,22 @@ export interface DurableWaitReadInput {
     readonly wait_id: string;
     readonly principal: string;
 }
+export interface DurableWaitDueCandidatesInput {
+    readonly tenant_id: string;
+    readonly principal: string;
+    readonly owner_scope_type: JudgmentProblemScope['type'];
+    readonly owner_scope_id: string;
+    readonly limit?: number;
+    readonly cursor?: string;
+}
+export interface DurableWaitDueCandidate {
+    readonly wait_id: string;
+    readonly due_at: string;
+}
+export interface DurableWaitDueCandidatesPage {
+    readonly candidates: readonly DurableWaitDueCandidate[];
+    readonly next_cursor?: string;
+}
 export interface DurableWaitClaimInput extends DurableWaitReadInput {
     /** Binds the returned lease/token to this particular claim attempt. */
     readonly request_id: string;
@@ -151,8 +188,52 @@ export interface DurableWaitPremiseChangedInput extends DurableWaitReadInput {
 }
 export interface DurableWaitEffectUnknownInput extends DurableWaitReadInput {
     readonly reason: string;
+    /**
+     * Optional for compatibility. When absent, the wait moves to
+     * `reconciliation_wait` with the previous (unbound) behavior; such a record
+     * is never released by reconcileExternalEffect and needs manual reconciliation.
+     */
+    readonly external_operation_id?: string;
     readonly responsible?: DurableWaitResponsible;
 }
+export interface DurableWaitReconcileExternalEffectInput extends DurableWaitReadInput {
+    readonly request_id: string;
+    readonly external_operation_id: string;
+    readonly evidence_ref: string;
+}
+/** A host-owned verifier must look up authoritative effect evidence, not trust a body verdict. */
+export interface DurableWaitExternalEffectPort {
+    verify(input: {
+        readonly principal: string;
+        readonly wait: DurableWaitRecord;
+        readonly claim_id: string;
+        readonly external_operation_id: string;
+        readonly evidence_ref: string;
+    }): DurableWaitExternalEffectVerification | Promise<DurableWaitExternalEffectVerification>;
+}
+export interface DurableWaitExternalEffectVerification {
+    readonly wait_id: string;
+    readonly claim_id: string;
+    readonly external_operation_id: string;
+    readonly evidence_ref: string;
+    readonly outcome: DurableWaitExternalEffectOutcome;
+}
+/** A host must bind the uncertain operation to its persisted execution intent. */
+export interface DurableWaitUnknownEffectPort {
+    verify(input: {
+        readonly principal: string;
+        readonly wait: DurableWaitRecord;
+        readonly claim_id: string;
+        readonly external_operation_id: string;
+    }): DurableWaitUnknownEffectVerification | Promise<DurableWaitUnknownEffectVerification>;
+}
+export interface DurableWaitUnknownEffectVerification {
+    readonly wait_id: string;
+    readonly claim_id: string;
+    readonly run_id: string;
+    readonly external_operation_id: string;
+    readonly status: 'unknown';
+}
 export interface DurableWaitResumeInput extends DurableWaitReadInput {
     /** Must match the request that won the claim (or the replacement handoff). */
     readonly request_id: string;
@@ -186,11 +267,13 @@ export interface DurableWaitStoreOptions {
     readonly dataDir: string;
     readonly problemSnapshot: DurableWaitProblemSnapshotPort;
     readonly access?: DurableWaitAccessPort;
+    readonly externalEffect?: DurableWaitExternalEffectPort;
+    readonly unknownEffect?: DurableWaitUnknownEffectPort;
     readonly clock?: () => Date;
     readonly sidecarPath?: string;
     readonly defaultLeaseMs?: number;
 }
-export type DurableWaitErrorCode = 'invalid_request' | 'not_found' | 'unauthorized' | 'ledger_invalid' | 'problem_snapshot_invalid' | 'condition_unmet' | 'lease_active' | 'lease_expired' | 'state_conflict' | 'reconciliation_required';
+export type DurableWaitErrorCode = 'invalid_request' | 'not_found' | 'unauthorized' | 'authorization_provider_failed' | 'ledger_invalid' | 'problem_snapshot_invalid' | 'condition_unmet' | 'lease_active' | 'lease_expired' | 'state_conflict' | 'reconciliation_required';
 export declare class DurableWaitError extends Error {
     readonly code: DurableWaitErrorCode;
     readonly wait_id?: string;
@@ -201,6 +284,8 @@ export declare class DurableWaitStore {
     private readonly dataDir;
     private readonly problemSnapshot;
     private readonly access;
+    private readonly externalEffect?;
+    private readonly unknownEffect?;
     private readonly clock;
     private readonly sidecarPath;
     private readonly defaultLeaseMs;
@@ -214,6 +299,8 @@ export declare class DurableWaitStore {
         readonly principal: string;
         readonly owner_scope_id?: string;
     }): Promise<readonly DurableWaitRecord[]>;
+    /** Discovery only: claim repeats all live authorization and trigger checks. */
+    listDueCandidates(input: DurableWaitDueCandidatesInput): Promise<DurableWaitDueCandidatesPage>;
     claim(input: DurableWaitClaimInput): Promise<DurableWaitClaimResult>;
     handoff(input: DurableWaitHandoffInput): Promise<DurableWaitRecord>;
     /** Explicit name for scheduler adapters that only hand off expired leases. */
@@ -221,6 +308,9 @@ export declare class DurableWaitStore {
     resume(input: DurableWaitResumeInput): Promise<DurableWaitResumeReceipt>;
     markPremiseChanged(input: DurableWaitPremiseChangedInput): Promise<DurableWaitRecord>;
     markEffectUnknown(input: DurableWaitEffectUnknownInput): Promise<DurableWaitRecord>;
+    /** Previous behavior, kept for callers that do not send external_operation_id. */
+    private markEffectUnknownUnbound;
+    reconcileExternalEffect(input: DurableWaitReconcileExternalEffectInput): Promise<DurableWaitRecord>;
     private captureMutationPreflight;
     private assertMutationPreflight;
     private readStored;