@unson/brainbase-mcp 0.43.0 → 0.44.1

package/dist/durable-waits.js

@@ -1,4 +1,4 @@
-import { createHash, randomUUID } from 'node:crypto';
+import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
 import { defaultJudgmentProblemSnapshotAccessProvider } from './judgment-problem-snapshot.js';
 import { initializePersonalOs, loadPersonalOs, mutatePersonalOsWithSidecar, readPersonalOsSidecar } from './ssot.js';
 /** Story13's persisted contract. The ledger is deliberately separate from the
@@ -26,7 +26,7 @@ class DurableWaitPreflightConflict extends DurableWaitError {
 const SNAPSHOT_ID_PATTERN = /^sha256:[0-9a-f]{64}$/u;
 const DEFAULT_LEASE_MS = 5 * 60 * 1000;
 const WAIT_STATES = [
-    'waiting', 'claimed', 'resumed', 'handoff_required', 'reconciliation_wait', 'failed', 'cancelled'
+    'waiting', 'claimed', 'resumed', 'handoff_required', 'reconciliation_wait', 'effect_confirmed', 'failed', 'cancelled'
 ];
 const RESUME_METHODS = [
     'resume_run', 'new_problem', 'reconcile_external_effect', 'manual_review'
@@ -35,6 +35,43 @@ const FAILURE_POLICIES = [
     'handoff', 'new_problem', 'reconciliation_wait', 'fail'
 ];
 const TRIGGERS = ['event', 'timer', 'manual'];
+const DUE_CURSOR_KEY = randomBytes(32);
+function earliestDueAt(deadline) {
+    const values = [deadline?.due_at, deadline?.next_review_at].filter((value) => value !== undefined);
+    return values.sort((a, b) => Date.parse(a) - Date.parse(b))[0];
+}
+function encodeDueCursor(after, tenantId, principal, scopeType, scopeId) {
+    const payload = Buffer.from(JSON.stringify({ v: 1, after, tenantId, principal, scopeType, scopeId }), 'utf8').toString('base64url');
+    const signature = createHmac('sha256', DUE_CURSOR_KEY).update(payload).digest('base64url');
+    return `${payload}.${signature}`;
+}
+function decodeDueCursor(cursor, tenantId, principal, scopeType, scopeId) {
+    if (cursor === undefined)
+        return '';
+    if (typeof cursor !== 'string' || cursor.length === 0 || cursor.length > 4096 || !/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/u.test(cursor)) {
+        throw new DurableWaitError('invalid_request', 'cursor is invalid');
+    }
+    try {
+        const [payload, signature] = cursor.split('.');
+        const expected = createHmac('sha256', DUE_CURSOR_KEY).update(payload).digest();
+        const received = Buffer.from(signature, 'base64url');
+        if (expected.length !== received.length || !timingSafeEqual(expected, received))
+            throw new Error('cursor signature is invalid');
+        const decoded = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+        if (decoded === null || typeof decoded !== 'object' || Array.isArray(decoded))
+            throw new Error('cursor is not an object');
+        const value = decoded;
+        if (value.v !== 1 || value.tenantId !== tenantId || value.principal !== principal
+            || value.scopeType !== scopeType || value.scopeId !== scopeId
+            || typeof value.after !== 'string' || value.after.length === 0 || value.after.length > 512) {
+            throw new Error('cursor binding is invalid');
+        }
+        return value.after;
+    }
+    catch {
+        throw new DurableWaitError('invalid_request', 'cursor is invalid for this principal and scope');
+    }
+}
 export const defaultDurableWaitAccessProvider = {
     authorize({ action, principal, acl }) {
         return defaultJudgmentProblemSnapshotAccessProvider.authorize({
@@ -48,6 +85,8 @@ export class DurableWaitStore {
     dataDir;
     problemSnapshot;
     access;
+    externalEffect;
+    unknownEffect;
     clock;
     sidecarPath;
     defaultLeaseMs;
@@ -59,6 +98,8 @@ export class DurableWaitStore {
         this.dataDir = options.dataDir;
         this.problemSnapshot = options.problemSnapshot;
         this.access = options.access ?? defaultDurableWaitAccessProvider;
+        this.externalEffect = options.externalEffect;
+        this.unknownEffect = options.unknownEffect;
         this.clock = options.clock ?? (() => new Date());
         this.sidecarPath = options.sidecarPath ?? DURABLE_WAIT_SIDECAR_PATH;
         assertSidecarPath(this.sidecarPath);
@@ -84,6 +125,7 @@ export class DurableWaitStore {
             const record = freezeClone({
                 wait_id: normalized.wait_id,
                 version: DURABLE_WAIT_VERSION,
+                ...(normalized.tenant_id === undefined ? {} : { tenant_id: normalized.tenant_id }),
                 owner_scope: normalized.owner_scope,
                 read_policy: normalized.read_policy,
                 problem_snapshot: normalized.problem_snapshot,
@@ -141,6 +183,56 @@ export class DurableWaitStore {
         }
         return result;
     }
+    /** Discovery only: claim repeats all live authorization and trigger checks. */
+    async listDueCandidates(input) {
+        assertText(input?.tenant_id, 'tenant_id');
+        assertText(input?.principal, 'principal');
+        if (!['personal', 'project', 'organization'].includes(input?.owner_scope_type)) {
+            throw new DurableWaitError('invalid_request', 'owner_scope_type is invalid');
+        }
+        assertText(input?.owner_scope_id, 'owner_scope_id');
+        const limit = input.limit ?? 50;
+        if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+            throw new DurableWaitError('invalid_request', 'limit must be an integer from 1 to 100');
+        }
+        const after = decodeDueCursor(input.cursor, input.tenant_id, input.principal, input.owner_scope_type, input.owner_scope_id);
+        const nowMs = this.now().getTime();
+        await this.initialize();
+        const ledger = parseLedger(await readPersonalOsSidecar(this.dataDir, this.sidecarPath));
+        const candidates = [];
+        let hasMore = false;
+        for (const record of [...ledger.waits].sort((a, b) => a.wait_id < b.wait_id ? -1 : a.wait_id > b.wait_id ? 1 : 0)) {
+            if (record.wait_id <= after || record.tenant_id !== input.tenant_id
+                || record.owner_scope.type !== input.owner_scope_type
+                || record.owner_scope.id !== input.owner_scope_id || record.state !== 'waiting')
+                continue;
+            const dueAt = earliestDueAt(record.deadline);
+            if (dueAt === undefined || Date.parse(dueAt) > nowMs)
+                continue;
+            let allowed;
+            try {
+                allowed = await this.access.authorize({ action: 'claim', principal: input.principal, acl: record.read_policy, wait: record });
+            }
+            catch {
+                throw new DurableWaitError('authorization_provider_failed', 'Claim access could not be verified');
+            }
+            if (allowed === false)
+                continue;
+            await this.verifyProblem(input.principal, record.problem_snapshot);
+            if (candidates.length === limit) {
+                hasMore = true;
+                break;
+            }
+            candidates.push({ wait_id: record.wait_id, due_at: dueAt });
+        }
+        const last = candidates.at(-1);
+        return {
+            candidates,
+            ...(hasMore && last !== undefined
+                ? { next_cursor: encodeDueCursor(last.wait_id, input.tenant_id, input.principal, input.owner_scope_type, input.owner_scope_id) }
+                : {})
+        };
+    }
     async claim(input) {
         const normalized = normalizeClaimInput(input, this.now(), this.defaultLeaseMs);
         await this.initialize();
@@ -155,9 +247,12 @@ export class DurableWaitStore {
                 if (record.state === 'reconciliation_wait') {
                     throw new DurableWaitError('reconciliation_required', `Wait ${record.wait_id} requires external-effect reconciliation`, record.wait_id);
                 }
-                if (record.state === 'handoff_required' || record.state === 'resumed' || record.state === 'failed' || record.state === 'cancelled') {
+                if (record.state === 'handoff_required' || record.state === 'resumed' || record.state === 'effect_confirmed' || record.state === 'failed' || record.state === 'cancelled') {
                     throw new DurableWaitError('state_conflict', `Wait ${record.wait_id} is ${record.state}`, record.wait_id);
                 }
+                if (record.reconciliation_receipts?.some((receipt) => receipt.previous_claim_request_id === normalized.request_id)) {
+                    throw new DurableWaitError('state_conflict', 'A reconciled effect requires a fresh claim request_id', record.wait_id);
+                }
                 // Validate the incoming event/timer before treating an existing claim as
                 // a duplicate. A different, not-yet-ready trigger must not receive a
                 // claim it cannot legitimately resume.
@@ -319,7 +414,10 @@ export class DurableWaitStore {
         return mutatePersonalOsWithSidecar(this.dataDir, this.sidecarPath, (current, content) => {
             const ledger = this.assertMutationPreflight(current, content, preflight, normalized.wait_id);
             const record = findWait(ledger, normalized.wait_id);
-            if (record.state === 'resumed' || record.state === 'cancelled' || record.state === 'failed') {
+            if (record.state === 'reconciliation_wait') {
+                throw new DurableWaitError('reconciliation_required', `Wait ${record.wait_id} requires external-effect reconciliation`, record.wait_id);
+            }
+            if (record.state === 'resumed' || record.state === 'effect_confirmed' || record.state === 'cancelled' || record.state === 'failed') {
                 throw new DurableWaitError('state_conflict', `Wait ${record.wait_id} is ${record.state}`, record.wait_id);
             }
             const now = this.now().toISOString();
@@ -344,6 +442,67 @@ export class DurableWaitStore {
     }
     async markEffectUnknown(input) {
         const normalized = normalizeEffectUnknownInput(input);
+        const externalOperationId = normalized.external_operation_id;
+        if (externalOperationId === undefined)
+            return this.markEffectUnknownUnbound(normalized);
+        await this.initialize();
+        const preflight = await this.captureMutationPreflight(normalized.wait_id);
+        const preflightRecord = requireMutationRecord(preflight, normalized.wait_id);
+        await this.authorize('write', normalized.principal, preflightRecord.read_policy, preflightRecord);
+        await this.verifyProblem(normalized.principal, preflightRecord.problem_snapshot);
+        if ((preflightRecord.state !== 'claimed' && preflightRecord.state !== 'handoff_required') || preflightRecord.claim === undefined) {
+            throw new DurableWaitError('state_conflict', `Wait ${normalized.wait_id} has no claim to bind the uncertain effect`, normalized.wait_id);
+        }
+        let bindingVerification;
+        if (this.unknownEffect && typeof this.unknownEffect.verify === 'function') {
+            try {
+                bindingVerification = await this.unknownEffect.verify({
+                    principal: normalized.principal,
+                    wait: freezeClone(preflightRecord),
+                    claim_id: preflightRecord.claim.claim_id,
+                    external_operation_id: externalOperationId
+                });
+            }
+            catch {
+                // The effect is still uncertain. Persist a quarantine rather than
+                // leaving a claimed lease eligible for handoff and duplicate execution.
+            }
+        }
+        const bindingVerified = !!bindingVerification && bindingVerification.wait_id === normalized.wait_id
+            && bindingVerification.claim_id === preflightRecord.claim.claim_id
+            && bindingVerification.run_id === preflightRecord.run_ref.run_id
+            && bindingVerification.external_operation_id === externalOperationId
+            && bindingVerification.status === 'unknown';
+        await this.authorize('write', normalized.principal, preflightRecord.read_policy, preflightRecord);
+        return mutatePersonalOsWithSidecar(this.dataDir, this.sidecarPath, (current, content) => {
+            const ledger = this.assertMutationPreflight(current, content, preflight, normalized.wait_id);
+            const record = findWait(ledger, normalized.wait_id);
+            if ((record.state !== 'claimed' && record.state !== 'handoff_required') || record.claim === undefined) {
+                throw new DurableWaitError('state_conflict', `Wait ${record.wait_id} has no claim to bind the uncertain effect`, record.wait_id);
+            }
+            const now = this.now().toISOString();
+            const responsible = normalized.responsible ?? record.responsible;
+            const updated = updateRecord(record, {
+                state: 'reconciliation_wait',
+                responsible,
+                reconciliation: { reason: normalized.reason, recorded_at: now, responsible, external_operation_id: externalOperationId, claim_id: record.claim.claim_id, binding_status: bindingVerified ? 'verified' : 'unverified' },
+                updated_at: now,
+                history: appendHistory(record, {
+                    action: 'effect_unknown',
+                    occurred_at: now,
+                    principal: normalized.principal,
+                    from_state: record.state,
+                    to_state: 'reconciliation_wait',
+                    detail: `${normalized.reason}:${externalOperationId}`,
+                    responsible
+                })
+            });
+            replaceWait(ledger, updated);
+            return { next: current, sidecarContent: serializeLedger(ledger), result: freezeClone(updated) };
+        });
+    }
+    /** Previous behavior, kept for callers that do not send external_operation_id. */
+    async markEffectUnknownUnbound(normalized) {
         await this.initialize();
         const preflight = await this.captureMutationPreflight(normalized.wait_id);
         const preflightRecord = requireMutationRecord(preflight, normalized.wait_id);
@@ -352,7 +511,7 @@ export class DurableWaitStore {
         return mutatePersonalOsWithSidecar(this.dataDir, this.sidecarPath, (current, content) => {
             const ledger = this.assertMutationPreflight(current, content, preflight, normalized.wait_id);
             const record = findWait(ledger, normalized.wait_id);
-            if (record.state === 'resumed' || record.state === 'cancelled' || record.state === 'failed') {
+            if (record.state === 'resumed' || record.state === 'cancelled' || record.state === 'failed' || record.state === 'effect_confirmed') {
                 throw new DurableWaitError('state_conflict', `Wait ${record.wait_id} is ${record.state}`, record.wait_id);
             }
             const now = this.now().toISOString();
@@ -376,6 +535,103 @@ export class DurableWaitStore {
             return { next: current, sidecarContent: serializeLedger(ledger), result: freezeClone(updated) };
         });
     }
+    async reconcileExternalEffect(input) {
+        const normalized = normalizeReconcileExternalEffectInput(input);
+        await this.initialize();
+        const preflight = await this.captureMutationPreflight(normalized.wait_id);
+        const preflightRecord = requireMutationRecord(preflight, normalized.wait_id);
+        await this.authorize('write', normalized.principal, preflightRecord.read_policy, preflightRecord);
+        await this.verifyProblem(normalized.principal, preflightRecord.problem_snapshot);
+        const prior = preflightRecord.reconciliation_receipts?.find((receipt) => receipt.request_id === normalized.request_id);
+        if (prior !== undefined) {
+            assertReconciliationReplay(prior, normalized);
+            return freezeClone(preflightRecord);
+        }
+        if (preflightRecord.state !== 'reconciliation_wait') {
+            throw new DurableWaitError('state_conflict', `Wait ${normalized.wait_id} is ${preflightRecord.state}`, normalized.wait_id);
+        }
+        const binding = preflightRecord.reconciliation;
+        if (!binding?.external_operation_id || !binding.claim_id || binding.binding_status !== 'verified' || !preflightRecord.claim || binding.claim_id !== preflightRecord.claim.claim_id) {
+            throw new DurableWaitError('reconciliation_required', 'The uncertain effect has no bound operation and claim identity', normalized.wait_id);
+        }
+        if (normalized.external_operation_id !== binding.external_operation_id) {
+            throw new DurableWaitError('state_conflict', 'Evidence targets a different external operation', normalized.wait_id);
+        }
+        if (!this.externalEffect || typeof this.externalEffect.verify !== 'function') {
+            throw new DurableWaitError('reconciliation_required', 'An authoritative external-effect verifier is required', normalized.wait_id);
+        }
+        let verification;
+        try {
+            verification = await this.externalEffect.verify({
+                principal: normalized.principal,
+                wait: freezeClone(preflightRecord),
+                claim_id: binding.claim_id,
+                external_operation_id: normalized.external_operation_id,
+                evidence_ref: normalized.evidence_ref
+            });
+        }
+        catch {
+            throw new DurableWaitError('reconciliation_required', 'External-effect evidence could not be verified', normalized.wait_id);
+        }
+        if (!verification || verification.wait_id !== normalized.wait_id
+            || verification.claim_id !== binding.claim_id
+            || verification.external_operation_id !== binding.external_operation_id
+            || verification.evidence_ref !== normalized.evidence_ref
+            || !['performed', 'not_performed', 'unknown'].includes(verification.outcome)) {
+            throw new DurableWaitError('reconciliation_required', 'External-effect verifier returned mismatched evidence', normalized.wait_id);
+        }
+        const outcome = verification.outcome;
+        // The evidence lookup may be slow; do not commit under permission that
+        // disappeared while it was running. The ledger CAS covers SSOT changes.
+        await this.authorize('write', normalized.principal, preflightRecord.read_policy, preflightRecord);
+        try {
+            return await mutatePersonalOsWithSidecar(this.dataDir, this.sidecarPath, (current, content) => {
+                const ledger = this.assertMutationPreflight(current, content, preflight, normalized.wait_id);
+                const record = findWait(ledger, normalized.wait_id);
+                if (record.state !== 'reconciliation_wait') {
+                    throw new DurableWaitError('state_conflict', `Wait ${record.wait_id} is ${record.state}`, record.wait_id);
+                }
+                const now = this.now().toISOString();
+                const receipt = {
+                    request_id: normalized.request_id,
+                    external_operation_id: normalized.external_operation_id,
+                    evidence_ref: normalized.evidence_ref,
+                    outcome,
+                    principal: normalized.principal,
+                    recorded_at: now,
+                    previous_claim_request_id: record.claim.request_id,
+                    claim_id: binding.claim_id
+                };
+                const state = outcome === 'performed' ? 'effect_confirmed' : outcome === 'not_performed' ? 'waiting' : 'reconciliation_wait';
+                const updated = updateRecord(record, {
+                    state,
+                    updated_at: now,
+                    reconciliation_receipts: [...(record.reconciliation_receipts ?? []), receipt],
+                    history: appendHistory(record, {
+                        action: 'effect_reconciled', occurred_at: now, principal: normalized.principal,
+                        from_state: 'reconciliation_wait', to_state: state, detail: `${outcome}:${normalized.external_operation_id}`
+                    })
+                });
+                // A proven non-effect can be claimed again, but never with the old lease.
+                if (outcome === 'not_performed')
+                    delete updated.claim;
+                replaceWait(ledger, updated);
+                return { next: current, sidecarContent: serializeLedger(ledger), result: freezeClone(updated) };
+            });
+        }
+        catch (error) {
+            if (!(error instanceof DurableWaitPreflightConflict))
+                throw error;
+            const current = await this.readStored(normalized.wait_id);
+            await this.authorize('write', normalized.principal, current.read_policy, current);
+            await this.verifyProblem(normalized.principal, current.problem_snapshot);
+            const winner = current.reconciliation_receipts?.find((receipt) => receipt.request_id === normalized.request_id);
+            if (winner === undefined)
+                throw error;
+            assertReconciliationReplay(winner, normalized);
+            return freezeClone(current);
+        }
+    }
     async captureMutationPreflight(waitId) {
         // These reads intentionally happen outside mutatePersonalOsWithSidecar's
         // lock. A trusted provider may use GraphFoundationRevisionStore or read
@@ -482,6 +738,8 @@ export function createDurableWaitStore(options) {
 }
 function normalizeCreateInput(input, now) {
     assertText(input?.principal, 'principal');
+    if (input.tenant_id !== undefined)
+        assertText(input.tenant_id, 'tenant_id');
     const waitId = input.wait_id ?? `wait-${randomUUID()}`;
     assertText(waitId, 'wait_id');
     const ownerScope = normalizeScope(input.owner_scope, 'owner_scope');
@@ -506,6 +764,7 @@ function normalizeCreateInput(input, now) {
     assertTimestamp(createdAt, 'created_at');
     return {
         wait_id: waitId,
+        ...(input.tenant_id === undefined ? {} : { tenant_id: input.tenant_id }),
         principal: input.principal,
         owner_scope: ownerScope,
         read_policy: readPolicy,
@@ -577,7 +836,28 @@ function normalizeEffectUnknownInput(input) {
     const base = normalizeReadInput(input);
     assertText(input.reason, 'reason');
     const responsible = input.responsible === undefined ? undefined : normalizeResponsible(input.responsible, 'responsible');
-    return { ...base, reason: input.reason, ...(responsible === undefined ? {} : { responsible }) };
+    return {
+        ...base,
+        reason: input.reason,
+        ...(input.external_operation_id === undefined ? {} : { external_operation_id: boundedText(input.external_operation_id, 'external_operation_id') }),
+        ...(responsible === undefined ? {} : { responsible })
+    };
+}
+function normalizeReconcileExternalEffectInput(input) {
+    const base = normalizeReadInput(input);
+    return {
+        ...base,
+        request_id: boundedText(input.request_id, 'request_id'),
+        external_operation_id: boundedText(input.external_operation_id, 'external_operation_id'),
+        evidence_ref: boundedText(input.evidence_ref, 'evidence_ref')
+    };
+}
+function assertReconciliationReplay(receipt, input) {
+    if (receipt.principal !== input.principal
+        || receipt.external_operation_id !== input.external_operation_id
+        || receipt.evidence_ref !== input.evidence_ref) {
+        throw new DurableWaitError('state_conflict', 'Reconciliation request_id was already used with different evidence', input.wait_id);
+    }
 }
 function normalizeCondition(value) {
     if (value === undefined || value === null || typeof value !== 'object')
@@ -755,6 +1035,8 @@ function validateStoredRecord(value) {
     if (value.version !== DURABLE_WAIT_VERSION)
         throw new Error('wait.version is unsupported');
     assertText(value.wait_id, 'wait.wait_id');
+    if (value.tenant_id !== undefined)
+        assertText(value.tenant_id, 'wait.tenant_id');
     const ownerScope = normalizeScope(value.owner_scope, 'wait.owner_scope');
     const acl = normalizeAcl(value.read_policy, 'wait.read_policy');
     const problem = normalizeProblemReference(value.problem_snapshot, 'wait.problem_snapshot');
@@ -773,9 +1055,11 @@ function validateStoredRecord(value) {
     const resumeReceipt = value.resume_receipt === undefined ? undefined : validateResumeReceipt(value.resume_receipt);
     const nextProblem = value.next_problem === undefined ? undefined : normalizeProblemReference(value.next_problem, 'wait.next_problem');
     const reconciliation = value.reconciliation === undefined ? undefined : validateReconciliation(value.reconciliation);
+    const reconciliationReceipts = value.reconciliation_receipts === undefined ? undefined : validateReconciliationReceipts(value.reconciliation_receipts);
     return {
         wait_id: value.wait_id,
         version: DURABLE_WAIT_VERSION,
+        ...(value.tenant_id === undefined ? {} : { tenant_id: value.tenant_id }),
         owner_scope: ownerScope,
         read_policy: acl,
         problem_snapshot: problem,
@@ -792,6 +1076,7 @@ function validateStoredRecord(value) {
         ...(resumeReceipt === undefined ? {} : { resume_receipt: resumeReceipt }),
         ...(nextProblem === undefined ? {} : { next_problem: nextProblem }),
         ...(reconciliation === undefined ? {} : { reconciliation }),
+        ...(reconciliationReceipts === undefined ? {} : { reconciliation_receipts: reconciliationReceipts }),
         history
     };
 }
@@ -846,7 +1131,7 @@ function validateResumeReceipt(value) {
 function validateHistory(value) {
     if (!isRecord(value))
         throw new Error('wait.history entry must be an object');
-    const action = enumValue(value.action, ['create', 'claim', 'handoff', 'premise_changed', 'effect_unknown', 'resume'], 'wait.history.action');
+    const action = enumValue(value.action, ['create', 'claim', 'handoff', 'premise_changed', 'effect_unknown', 'effect_reconciled', 'resume'], 'wait.history.action');
     assertTimestamp(value.occurred_at, 'wait.history.occurred_at');
     assertText(value.principal, 'wait.history.principal');
     const toState = enumValue(value.to_state, WAIT_STATES, 'wait.history.to_state');
@@ -862,7 +1147,34 @@ function validateReconciliation(value) {
     const recordedAt = boundedText(value.recorded_at, 'wait.reconciliation.recorded_at');
     assertTimestamp(recordedAt, 'wait.reconciliation.recorded_at');
     const responsible = normalizeResponsible(value.responsible, 'wait.reconciliation.responsible');
-    return { reason, recorded_at: recordedAt, responsible };
+    const externalOperationId = value.external_operation_id === undefined ? undefined : boundedText(value.external_operation_id, 'wait.reconciliation.external_operation_id');
+    const claimId = value.claim_id === undefined ? undefined : boundedText(value.claim_id, 'wait.reconciliation.claim_id');
+    const bindingStatus = value.binding_status === undefined ? undefined : enumValue(value.binding_status, ['verified', 'unverified'], 'wait.reconciliation.binding_status');
+    if ((externalOperationId === undefined) !== (claimId === undefined))
+        throw new Error('wait.reconciliation binding is incomplete');
+    if (bindingStatus !== undefined && externalOperationId === undefined)
+        throw new Error('wait.reconciliation binding status has no operation');
+    return { reason, recorded_at: recordedAt, responsible, ...(externalOperationId === undefined ? {} : { external_operation_id: externalOperationId, claim_id: claimId }), ...(bindingStatus === undefined ? {} : { binding_status: bindingStatus }) };
+}
+function validateReconciliationReceipts(value) {
+    if (!Array.isArray(value))
+        throw new Error('wait.reconciliation_receipts must be an array');
+    const receipts = value.map((item) => {
+        if (!isRecord(item))
+            throw new Error('wait.reconciliation_receipt must be an object');
+        const requestId = boundedText(item.request_id, 'wait.reconciliation_receipt.request_id');
+        const externalOperationId = boundedText(item.external_operation_id, 'wait.reconciliation_receipt.external_operation_id');
+        const evidenceRef = boundedText(item.evidence_ref, 'wait.reconciliation_receipt.evidence_ref');
+        const outcome = enumValue(item.outcome, ['performed', 'not_performed', 'unknown'], 'wait.reconciliation_receipt.outcome');
+        const principal = boundedText(item.principal, 'wait.reconciliation_receipt.principal');
+        assertTimestamp(item.recorded_at, 'wait.reconciliation_receipt.recorded_at');
+        const previousClaimRequestId = item.previous_claim_request_id === undefined ? undefined : boundedText(item.previous_claim_request_id, 'wait.reconciliation_receipt.previous_claim_request_id');
+        const claimId = item.claim_id === undefined ? undefined : boundedText(item.claim_id, 'wait.reconciliation_receipt.claim_id');
+        return { request_id: requestId, external_operation_id: externalOperationId, evidence_ref: evidenceRef, outcome, principal, recorded_at: item.recorded_at, ...(previousClaimRequestId === undefined ? {} : { previous_claim_request_id: previousClaimRequestId }), ...(claimId === undefined ? {} : { claim_id: claimId }) };
+    });
+    if (new Set(receipts.map((receipt) => receipt.request_id)).size !== receipts.length)
+        throw new Error('duplicate reconciliation request_id');
+    return receipts;
 }
 function serializeLedger(ledger) {
     const sorted = {

package/dist/honcho.d.ts

@@ -0,0 +1,25 @@
+/** Portable Honcho v3 HTTP boundary. Credentials and identity are host ports. */
+export declare const HONCHO_CONTRACT_VERSION: "honcho.v1";
+export interface HonchoConfig {
+    apiUrl: string;
+    workspaceId: string;
+}
+export interface HonchoRequest {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    query?: Record<string, string | number | boolean>;
+    body?: Record<string, unknown> | unknown[] | null;
+}
+export declare class HonchoContractError extends Error {
+    readonly code = "honcho_contract_invalid";
+    constructor(field: string, message?: string);
+}
+export declare function normalizeHonchoConfig(value: unknown): HonchoConfig;
+export declare function honchoWorkspacePath(workspaceId: string): string;
+export declare function createHonchoRequest(input: HonchoRequest): HonchoRequest;
+export declare function honchoRequestUrl(config: HonchoConfig, request: HonchoRequest): string;
+export interface HonchoMessageInput {
+    peer: string;
+    content: string;
+}
+export declare function normalizeHonchoMessages(value: unknown): HonchoMessageInput[];

package/dist/honcho.js

@@ -0,0 +1,81 @@
+/** Portable Honcho v3 HTTP boundary. Credentials and identity are host ports. */
+export const HONCHO_CONTRACT_VERSION = 'honcho.v1';
+export class HonchoContractError extends Error {
+    code = 'honcho_contract_invalid';
+    constructor(field, message = `Honcho field is invalid: ${field}`) {
+        super(message);
+        this.name = 'HonchoContractError';
+    }
+}
+function requiredText(value, field) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new HonchoContractError(field);
+    return value.trim();
+}
+export function normalizeHonchoConfig(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new HonchoContractError('config');
+    const candidate = value;
+    const rawUrl = requiredText(candidate.apiUrl, 'apiUrl');
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new HonchoContractError('apiUrl', 'apiUrl must be an absolute URL');
+    }
+    if (!['http:', 'https:'].includes(url.protocol))
+        throw new HonchoContractError('apiUrl', 'apiUrl must use http or https');
+    if (url.username || url.password || url.search || url.hash) {
+        throw new HonchoContractError('apiUrl', 'apiUrl must not contain credentials, query, or hash components');
+    }
+    return {
+        apiUrl: url.toString().replace(/\/+$/u, ''),
+        workspaceId: requiredText(candidate.workspaceId ?? 'brainbase', 'workspaceId')
+    };
+}
+export function honchoWorkspacePath(workspaceId) {
+    return `/v3/workspaces/${encodeURIComponent(requiredText(workspaceId, 'workspaceId'))}`;
+}
+export function createHonchoRequest(input) {
+    if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(input.method)) {
+        throw new HonchoContractError('method');
+    }
+    const path = requiredText(input.path, 'path');
+    if (!path.startsWith('/') || path.includes('://') || path.includes('\n') || path.includes('\r')) {
+        throw new HonchoContractError('path');
+    }
+    if (input.query) {
+        for (const [key, value] of Object.entries(input.query)) {
+            if (!key || value === undefined || value === null)
+                throw new HonchoContractError('query');
+        }
+    }
+    return {
+        method: input.method,
+        path,
+        query: input.query ? { ...input.query } : undefined,
+        body: input.body === undefined ? undefined : input.body === null ? null : structuredClone(input.body)
+    };
+}
+export function honchoRequestUrl(config, request) {
+    const normalized = normalizeHonchoConfig(config);
+    const safeRequest = createHonchoRequest(request);
+    const url = new URL(`${normalized.apiUrl}${safeRequest.path}`);
+    for (const [key, value] of Object.entries(safeRequest.query ?? {}))
+        url.searchParams.set(key, String(value));
+    return url.toString();
+}
+export function normalizeHonchoMessages(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        throw new HonchoContractError('messages');
+    return value.map((item, index) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            throw new HonchoContractError(`messages.${index}`);
+        const candidate = item;
+        return {
+            peer: requiredText(candidate.peer, `messages.${index}.peer`),
+            content: requiredText(candidate.content, `messages.${index}.content`)
+        };
+    });
+}

package/dist/judgment-event-adapter.d.ts

@@ -0,0 +1,72 @@
+import { type JudgmentExecutionOutcome } from './judgment-execution-outcome.js';
+/** Input boundary for a completed Host episode. Private runtime fields are ignored. */
+export interface JudgmentEpisode {
+    episode_id?: unknown;
+    session_id?: unknown;
+    turn_id?: unknown;
+    finalized_at?: unknown;
+    answer_digest?: unknown;
+    completion_status?: unknown;
+    final_summary?: unknown;
+    final_answer?: unknown;
+    summary?: unknown;
+    payload?: unknown;
+    redaction_status?: unknown;
+    execution_outcome?: unknown;
+    [key: string]: unknown;
+}
+export interface JudgmentKnowledgeEventPayload {
+    summary?: string;
+    redaction_status?: 'needs_redaction';
+    execution_outcome?: JudgmentExecutionOutcome;
+}
+export interface JudgmentKnowledgeEvent {
+    schema_version: 'knowledge_event.v1';
+    contract_version: 'knowledge_event.v1';
+    event_id: string;
+    occurred_at: string;
+    captured_at: string;
+    source: {
+        type: 'agent_judgment' | 'codex_judgment';
+        ref: string;
+    };
+    subject: {
+        type: 'judgment_episode';
+        id: string;
+    };
+    decision_authority: {
+        kind: 'judgment_receipt';
+        authorized: false;
+        graph_promotion_allowed: false;
+    };
+    applicability_scope: {
+        scope: 'judgment_episode';
+        project_code: 'brainbase';
+    };
+    permission_snapshot: {
+        knowledge_registration: true;
+        external_action: false;
+    };
+    source_pointer: {
+        uri: string;
+    };
+    body_hash: string;
+    parent_episode_id: string;
+    semantic_state?: 'quarantined';
+    payload: JudgmentKnowledgeEventPayload;
+}
+/** Remove audit lines and quarantine likely secrets from a judgment answer. */
+export declare function sanitizeJudgmentAnswer(value: unknown): {
+    sensitive: true;
+    redaction_status: 'needs_redaction';
+} | {
+    sensitive: false;
+    summary: string;
+} | null;
+/**
+ * Project a completed Host episode into a non-authoritative knowledge event.
+ *
+ * This is a portable projection only. Organization identity, Task binding,
+ * transcript storage, and delivery/outbox behavior remain adapter concerns.
+ */
+export declare function toKnowledgeEventFromJudgmentEpisode(episode: JudgmentEpisode | null | undefined): JudgmentKnowledgeEvent | null;