@unson/brainbase-mcp 0.5.0 → 0.7.0

package/dist/durable-waits.d.ts

@@ -0,0 +1,234 @@
+import { type JudgmentProblemScope, type JudgmentProblemReferenceResolutionPhase } from './judgment-problem-snapshot.js';
+import type { FoundationAcl } from './ontology-foundation.js';
+/** Story13's persisted contract. The ledger is deliberately separate from the
+ * canonical graph but is committed by the same Personal OS sidecar transaction.
+ */
+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 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';
+export interface DurableWaitEventCondition {
+    readonly event_type: string;
+    readonly event_id?: string;
+    readonly predicate?: string;
+}
+export interface DurableWaitCondition {
+    readonly event?: DurableWaitEventCondition;
+    readonly expression?: string;
+}
+export interface DurableWaitDeadline {
+    readonly due_at?: string;
+    readonly review_interval_ms?: number;
+    /** The next periodic review is persisted so a restarted worker does not lose it. */
+    readonly next_review_at?: string;
+}
+export interface DurableWaitResponsible {
+    readonly principal: string;
+    readonly scope?: string;
+}
+export interface DurableWaitRunReference {
+    readonly run_id: string;
+    readonly node_id?: string;
+}
+/** Structural alias compatible with JudgmentDAG's snapshot locator. */
+export interface DurableWaitProblemReference {
+    readonly snapshot_id: `sha256:${string}` | string;
+    readonly problem_id: string;
+    readonly revision: string;
+}
+export interface DurableWaitLease {
+    readonly lease_id: string;
+    readonly holder: string;
+    readonly token: string;
+    readonly expires_at: string;
+}
+export interface DurableWaitClaim {
+    readonly claim_id: string;
+    /** Idempotency key for the scheduler/worker claim request. */
+    readonly request_id: string;
+    readonly trigger: DurableWaitTrigger;
+    readonly claimed_by: string;
+    readonly claimed_at: string;
+    readonly lease: DurableWaitLease;
+    readonly event_id?: string;
+}
+export interface DurableWaitResumeReceipt {
+    readonly resume_id: string;
+    readonly wait_id: string;
+    readonly claim_id: string;
+    readonly run_ref: DurableWaitRunReference;
+    readonly recorded_at: string;
+}
+export type DurableWaitHistoryAction = 'create' | 'claim' | 'handoff' | 'premise_changed' | 'effect_unknown' | 'resume';
+export interface DurableWaitHistoryEntry {
+    readonly action: DurableWaitHistoryAction;
+    readonly occurred_at: string;
+    readonly principal: string;
+    readonly from_state?: DurableWaitState;
+    readonly to_state: DurableWaitState;
+    readonly detail?: string;
+    readonly responsible?: DurableWaitResponsible;
+}
+export interface DurableWaitReconciliation {
+    readonly reason: string;
+    readonly recorded_at: string;
+    readonly responsible: DurableWaitResponsible;
+}
+export interface DurableWaitRecord {
+    readonly wait_id: string;
+    readonly version: typeof DURABLE_WAIT_VERSION;
+    readonly owner_scope: JudgmentProblemScope;
+    readonly read_policy: FoundationAcl;
+    readonly problem_snapshot: DurableWaitProblemReference;
+    readonly condition: DurableWaitCondition;
+    readonly deadline?: DurableWaitDeadline;
+    readonly responsible: DurableWaitResponsible;
+    readonly resume_method: DurableWaitResumeMethod;
+    readonly failure_policy: DurableWaitFailurePolicy;
+    readonly run_ref: DurableWaitRunReference;
+    readonly state: DurableWaitState;
+    readonly created_at: string;
+    readonly updated_at: string;
+    readonly claim?: DurableWaitClaim;
+    readonly resume_receipt?: DurableWaitResumeReceipt;
+    readonly next_problem?: DurableWaitProblemReference;
+    readonly reconciliation?: DurableWaitReconciliation;
+    readonly history: readonly DurableWaitHistoryEntry[];
+}
+export interface DurableWaitCreateInput {
+    readonly wait_id?: string;
+    readonly principal: string;
+    readonly owner_scope: JudgmentProblemScope;
+    readonly read_policy: FoundationAcl;
+    readonly problem_snapshot?: DurableWaitProblemReference;
+    /** `problem` is an ergonomic alias for adapters using existing run vocabulary. */
+    readonly problem?: DurableWaitProblemReference;
+    readonly condition: DurableWaitCondition;
+    readonly deadline?: DurableWaitDeadline;
+    readonly responsible: DurableWaitResponsible;
+    readonly resume_method: DurableWaitResumeMethod;
+    readonly failure_policy: DurableWaitFailurePolicy;
+    readonly run_ref: DurableWaitRunReference;
+    readonly created_at?: string;
+}
+export interface DurableWaitReadInput {
+    readonly wait_id: string;
+    readonly principal: string;
+}
+export interface DurableWaitClaimInput extends DurableWaitReadInput {
+    /** Binds the returned lease/token to this particular claim attempt. */
+    readonly request_id: string;
+    readonly trigger: DurableWaitTrigger;
+    readonly event_type?: string;
+    readonly event_id?: string;
+    readonly occurred_at?: string;
+    readonly lease_ms?: number;
+}
+export interface DurableWaitClaimResult {
+    readonly wait: DurableWaitRecord;
+    readonly claim: DurableWaitClaim;
+    /** True when an event/timer observed an already claimed wait. */
+    readonly duplicate: boolean;
+    /** Only this request may call resume with the returned claim credentials. */
+    readonly claimed_by_this_request: boolean;
+}
+export interface DurableWaitHandoffInput extends DurableWaitReadInput {
+    /** New idempotency key bound to the replacement lease. */
+    readonly request_id: string;
+    readonly responsible: DurableWaitResponsible;
+    readonly lease_ms?: number;
+    readonly now?: string;
+    readonly reason?: string;
+}
+export interface DurableWaitPremiseChangedInput extends DurableWaitReadInput {
+    readonly new_problem_snapshot?: DurableWaitProblemReference;
+    readonly new_problem?: DurableWaitProblemReference;
+    readonly responsible?: DurableWaitResponsible;
+    readonly reason: string;
+}
+export interface DurableWaitEffectUnknownInput extends DurableWaitReadInput {
+    readonly reason: string;
+    readonly responsible?: DurableWaitResponsible;
+}
+export interface DurableWaitResumeInput extends DurableWaitReadInput {
+    /** Must match the request that won the claim (or the replacement handoff). */
+    readonly request_id: string;
+    readonly claim_id: string;
+    readonly lease_id: string;
+    readonly lease_token: string;
+}
+export interface DurableWaitProblemSnapshotPort {
+    /**
+     * The adapter owns immutable snapshot lookup, exact identity/digest checks,
+     * and current read ACL. It must fail closed when the reference is missing or
+     * not readable. `historical_read` is intentionally not accepted here because
+     * a live wait is a new continuation, never an audit replay.
+     */
+    verify(input: {
+        readonly principal: string;
+        readonly reference: DurableWaitProblemReference;
+        readonly phase: Extract<JudgmentProblemReferenceResolutionPhase, 'save' | 'read'>;
+    }): void | boolean | Promise<void | boolean>;
+}
+export type DurableWaitAccessAction = 'read' | 'write' | 'claim';
+export interface DurableWaitAccessPort {
+    authorize(input: {
+        readonly action: DurableWaitAccessAction;
+        readonly principal: string;
+        readonly acl: FoundationAcl;
+        readonly wait?: DurableWaitRecord;
+    }): void | boolean | Promise<void | boolean>;
+}
+export interface DurableWaitStoreOptions {
+    readonly dataDir: string;
+    readonly problemSnapshot: DurableWaitProblemSnapshotPort;
+    readonly access?: DurableWaitAccessPort;
+    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 declare class DurableWaitError extends Error {
+    readonly code: DurableWaitErrorCode;
+    readonly wait_id?: string;
+    constructor(code: DurableWaitErrorCode, message: string, wait_id?: string);
+}
+export declare const defaultDurableWaitAccessProvider: DurableWaitAccessPort;
+export declare class DurableWaitStore {
+    private readonly dataDir;
+    private readonly problemSnapshot;
+    private readonly access;
+    private readonly clock;
+    private readonly sidecarPath;
+    private readonly defaultLeaseMs;
+    constructor(options: DurableWaitStoreOptions);
+    initialize(): Promise<void>;
+    create(input: DurableWaitCreateInput): Promise<DurableWaitRecord>;
+    get(input: DurableWaitReadInput): Promise<DurableWaitRecord>;
+    /** Alias used by adapters that model stores as read operations. */
+    read(input: DurableWaitReadInput): Promise<DurableWaitRecord>;
+    list(input: {
+        readonly principal: string;
+        readonly owner_scope_id?: string;
+    }): Promise<readonly DurableWaitRecord[]>;
+    claim(input: DurableWaitClaimInput): Promise<DurableWaitClaimResult>;
+    handoff(input: DurableWaitHandoffInput): Promise<DurableWaitRecord>;
+    /** Explicit name for scheduler adapters that only hand off expired leases. */
+    handoffExpired(input: DurableWaitHandoffInput): Promise<DurableWaitRecord>;
+    resume(input: DurableWaitResumeInput): Promise<DurableWaitResumeReceipt>;
+    markPremiseChanged(input: DurableWaitPremiseChangedInput): Promise<DurableWaitRecord>;
+    markEffectUnknown(input: DurableWaitEffectUnknownInput): Promise<DurableWaitRecord>;
+    private captureMutationPreflight;
+    private assertMutationPreflight;
+    private readStored;
+    private reconcileClaimAfterPreflightConflict;
+    private authorize;
+    private verifyProblem;
+    private now;
+    private nowFromMillis;
+    private timestamp;
+}
+export declare function createDurableWaitStore(options: DurableWaitStoreOptions): DurableWaitStore;