dotdo 0.0.1 → 0.1.0

package/dist/objects/DOBase.js

@@ -0,0 +1,2309 @@
+/**
+ * DO - Core Durable Object with WorkflowContext
+ *
+ * Extends DOTiny (~80KB) with:
+ * - WorkflowContext ($)
+ * - Event handlers ($.on)
+ * - Stores (things, rels, actions, events, search, objects, dlq)
+ * - Scheduling ($.every, alarm)
+ * - Actor context
+ * - Collection accessors
+ * - Event emission and dispatch
+ *
+ * Does NOT include (see DOFull for these):
+ * - Lifecycle (fork, clone, compact, move)
+ * - Sharding (shard, unshard, routing)
+ * - Branching (branch, checkout, merge)
+ * - Promotion (promote, demote)
+ *
+ * @example
+ * ```typescript
+ * import { DO } from 'dotdo'
+ *
+ * class MyDO extends DO {
+ *   async onStart() {
+ *     // Use workflow context
+ *     this.$.on.Customer.created(async (event) => {
+ *       console.log('Customer created:', event)
+ *     })
+ *
+ *     this.$.every.hour(async () => {
+ *       // Hourly task
+ *     })
+ *   }
+ * }
+ * ```
+ */
+import { DO as DOTiny } from './DOTiny';
+import { eq, sql } from 'drizzle-orm';
+import * as schema from '../db';
+import { isValidNounName } from '../db/nouns';
+import { createMcpHandler, } from './transport/mcp-server';
+import { RPCServer } from './transport/rpc-server';
+import { SyncEngine } from './transport/sync-engine';
+import { handleCapnWebRpc, isCapnWebRequest, } from './transport/capnweb-target';
+import { handleRestRequest, handleGetIndex, } from './transport/rest-router';
+import { createScheduleBuilderProxy } from '../workflows/schedule-builder';
+import { ScheduleManager } from '../workflows/ScheduleManager';
+import { ThingsStore, RelationshipsStore, ActionsStore, EventsStore, SearchStore, ObjectsStore, DLQStore, } from '../db/stores';
+import { logBestEffortError } from '../lib/logging/error-logger';
+import { parseNounId } from '../lib/noun-id';
+import { ai as aiFunc, write as writeFunc, summarize as summarizeFunc, list as listFunc, extract as extractFunc, is as isFunc, decide as decideFunc, } from '../ai';
+import { STORE_VISIBILITY, canAccessVisibility, getHighestRole, } from '../types/introspect';
+import { codeToCity, coloRegion, regionToCF } from '../types/Location';
+import { LOCATION_STORAGE_KEY } from '../lib/colo/caching';
+// ============================================================================
+// CROSS-DO ERROR CLASS
+// ============================================================================
+/**
+ * Custom error class for cross-DO call failures with rich context
+ */
+export class CrossDOError extends Error {
+    code;
+    context;
+    constructor(code, message, context = {}) {
+        super(message);
+        this.name = 'CrossDOError';
+        this.code = code;
+        this.context = context;
+        // Preserve stack trace in V8
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, CrossDOError);
+        }
+    }
+    toJSON() {
+        return {
+            error: {
+                code: this.code,
+                message: this.message,
+                context: this.context,
+            },
+        };
+    }
+}
+// ============================================================================
+// DO - Core Durable Object with WorkflowContext
+// ============================================================================
+export class DO extends DOTiny {
+    // ═══════════════════════════════════════════════════════════════════════════
+    // STATIC MCP CONFIGURATION
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Static MCP configuration for exposing methods as MCP tools and data as resources.
+     * Override in subclasses to expose tools and resources.
+     *
+     * @example
+     * ```typescript
+     * static $mcp = {
+     *   tools: {
+     *     search: {
+     *       description: 'Search items',
+     *       inputSchema: { query: { type: 'string' } },
+     *       required: ['query'],
+     *     },
+     *   },
+     *   resources: ['items', 'users'],
+     * }
+     * ```
+     */
+    static $mcp;
+    // ═══════════════════════════════════════════════════════════════════════════
+    // CAPABILITY MIXIN INFRASTRUCTURE
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Static array of capability names supported by this class.
+     * Populated by capability mixins (e.g., withFS, withGit, withBash).
+     * Empty by default in base DO class.
+     */
+    static capabilities = [];
+    /**
+     * Check if this DO instance has a specific capability.
+     * Capabilities are added via mixins and registered in the static capabilities array.
+     *
+     * @param name - Capability name to check (e.g., 'fs', 'git', 'bash')
+     * @returns true if the capability is registered on this class
+     *
+     * @example
+     * ```typescript
+     * if (this.hasCapability('fs')) {
+     *   await this.$.fs.read('/config.json')
+     * }
+     * ```
+     */
+    hasCapability(name) {
+        return this.constructor.capabilities?.includes(name) ?? false;
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // HONO APP (for HTTP routing)
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Optional Hono app for HTTP routing.
+     * Subclasses can create and configure this for custom routes.
+     */
+    app;
+    // ═══════════════════════════════════════════════════════════════════════════
+    // MCP SESSION STORAGE
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * MCP session storage for this DO instance.
+     */
+    _mcpSessions = new Map();
+    /**
+     * Cached MCP handler for this class.
+     */
+    _mcpHandler;
+    // ═══════════════════════════════════════════════════════════════════════════
+    // RPC SERVER
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * RPC Server instance for Cap'n Web RPC protocol support.
+     * Lazy-initialized on first access.
+     */
+    _rpcServer;
+    /**
+     * Get the RPC server instance.
+     * Creates the server on first access.
+     */
+    get rpcServer() {
+        if (!this._rpcServer) {
+            this._rpcServer = new RPCServer(this);
+        }
+        return this._rpcServer;
+    }
+    /**
+     * Check if a method is exposed via RPC.
+     * Note: This method is bound in the constructor to ensure `this` is always correct.
+     */
+    isRpcExposed = (method) => {
+        return this.rpcServer.isRpcExposed(method);
+    };
+    // ═══════════════════════════════════════════════════════════════════════════
+    // SYNC ENGINE
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * SyncEngine instance for WebSocket sync protocol support.
+     * Lazy-initialized on first access.
+     */
+    _syncEngine;
+    /**
+     * Get the SyncEngine instance.
+     * Creates the engine on first access.
+     */
+    get syncEngine() {
+        if (!this._syncEngine) {
+            this._syncEngine = new SyncEngine(this.things);
+        }
+        return this._syncEngine;
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ACTOR CONTEXT
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Current actor for action logging.
+     * Format: 'Type/id' (e.g., 'Human/nathan', 'Agent/support')
+     */
+    _currentActor = '';
+    /**
+     * Set the current actor for subsequent action logging.
+     */
+    setActor(actor) {
+        this._currentActor = actor;
+    }
+    /**
+     * Clear the current actor.
+     */
+    clearActor() {
+        this._currentActor = '';
+    }
+    /**
+     * Get the current actor for action logging.
+     */
+    getCurrentActor() {
+        return this._currentActor;
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // STORE ACCESSORS (lazy-loaded)
+    // ═══════════════════════════════════════════════════════════════════════════
+    _things;
+    _rels;
+    _actions;
+    _events;
+    _search;
+    _objects;
+    _dlq;
+    _typeCache = new Map();
+    // Event handler registry for $.on.Noun.verb() registration
+    _eventHandlers = new Map();
+    _handlerCounter = 0;
+    // Schedule handler registry for $.every scheduling
+    _scheduleHandlers = new Map();
+    _scheduleManager;
+    /**
+     * Get the schedule manager (lazy initialized)
+     */
+    get scheduleManager() {
+        if (!this._scheduleManager) {
+            this._scheduleManager = new ScheduleManager(this.ctx);
+            this._scheduleManager.onScheduleTrigger(async (schedule) => {
+                const handler = this._scheduleHandlers.get(schedule.name);
+                if (handler) {
+                    await handler();
+                }
+            });
+        }
+        return this._scheduleManager;
+    }
+    /**
+     * ThingsStore - CRUD operations for Things
+     */
+    get things() {
+        if (!this._things) {
+            this._things = new ThingsStore(this.getStoreContext());
+        }
+        return this._things;
+    }
+    /**
+     * RelationshipsStore - Relationship management
+     */
+    get rels() {
+        if (!this._rels) {
+            this._rels = new RelationshipsStore(this.getStoreContext());
+        }
+        return this._rels;
+    }
+    /**
+     * ActionsStore - Action logging and lifecycle
+     */
+    get actions() {
+        if (!this._actions) {
+            this._actions = new ActionsStore(this.getStoreContext());
+        }
+        return this._actions;
+    }
+    /**
+     * EventsStore - Event emission and streaming
+     */
+    get events() {
+        if (!this._events) {
+            this._events = new EventsStore(this.getStoreContext());
+        }
+        return this._events;
+    }
+    /**
+     * SearchStore - Full-text and semantic search
+     */
+    get search() {
+        if (!this._search) {
+            this._search = new SearchStore(this.getStoreContext());
+        }
+        return this._search;
+    }
+    /**
+     * ObjectsStore - DO registry and resolution
+     */
+    get objects() {
+        if (!this._objects) {
+            this._objects = new ObjectsStore(this.getStoreContext());
+        }
+        return this._objects;
+    }
+    /**
+     * DLQStore - Dead Letter Queue for failed events
+     */
+    get dlq() {
+        if (!this._dlq) {
+            const handlerMap = new Map();
+            for (const [eventKey, registrations] of this._eventHandlers) {
+                if (registrations.length > 0) {
+                    handlerMap.set(eventKey, async (data) => {
+                        const event = {
+                            id: `dlq-replay-${crypto.randomUUID()}`,
+                            verb: eventKey.split('.')[1] || '',
+                            source: `https://${this.ns}/${eventKey.split('.')[0]}/replay`,
+                            data,
+                            timestamp: new Date(),
+                        };
+                        await this.dispatchEventToHandlers(event);
+                    });
+                }
+            }
+            this._dlq = new DLQStore(this.getStoreContext(), handlerMap);
+        }
+        return this._dlq;
+    }
+    /**
+     * Get the store context for initializing stores
+     */
+    getStoreContext() {
+        return {
+            db: this.db,
+            ns: this.ns,
+            currentBranch: this.currentBranch,
+            env: this.env,
+            typeCache: this._typeCache,
+        };
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // LOCATION DETECTION & CACHING
+    // ═══════════════════════════════════════════════════════════════════════════
+    /** Cached location instance (in-memory) */
+    _cachedLocation;
+    /** Flag to track if location hook was already called */
+    _locationHookCalled = false;
+    /** Coordinates extracted from CF request headers */
+    _extractedCoordinates;
+    /**
+     * Get the DO's location (with caching).
+     *
+     * On first call, detects location via Cloudflare's trace endpoint,
+     * caches it in storage, and calls the onLocationDetected hook.
+     * Subsequent calls return the cached location immediately.
+     *
+     * @returns Promise resolving to the DO's location
+     */
+    async getLocation() {
+        // Return cached location if available
+        if (this._cachedLocation) {
+            return this._cachedLocation;
+        }
+        // Check DO storage for persisted location
+        // Note: Storage may have legacy format with latitude/longitude or new format with lat/lng
+        const cached = await this.ctx.storage.get(LOCATION_STORAGE_KEY);
+        if (cached) {
+            // Restore from storage, converting coordinates to canonical format if needed
+            const coords = cached.coordinates
+                ? {
+                    lat: cached.coordinates.lat ?? cached.coordinates.latitude ?? 0,
+                    lng: cached.coordinates.lng ?? cached.coordinates.longitude ?? 0,
+                }
+                : undefined;
+            this._cachedLocation = Object.freeze({
+                colo: cached.colo,
+                city: cached.city,
+                region: cached.region,
+                cfHint: cached.cfHint,
+                detectedAt: cached.detectedAt instanceof Date
+                    ? cached.detectedAt
+                    : new Date(cached.detectedAt),
+                coordinates: coords,
+            });
+            return this._cachedLocation;
+        }
+        // Detect fresh location
+        const location = await this._detectLocation();
+        // Cache in memory (frozen for immutability)
+        this._cachedLocation = Object.freeze(location);
+        // Persist to storage
+        await this.ctx.storage.put(LOCATION_STORAGE_KEY, {
+            colo: location.colo,
+            city: location.city,
+            region: location.region,
+            cfHint: location.cfHint,
+            detectedAt: location.detectedAt.toISOString(),
+            coordinates: location.coordinates,
+        });
+        // Call lifecycle hook (only once)
+        if (!this._locationHookCalled) {
+            this._locationHookCalled = true;
+            try {
+                await this.onLocationDetected(this._cachedLocation);
+            }
+            catch (error) {
+                // Log but don't propagate hook errors
+                console.error('Error in onLocationDetected hook:', error);
+            }
+        }
+        return this._cachedLocation;
+    }
+    /**
+     * Internal method to detect location from Cloudflare's trace endpoint.
+     * Override in tests to provide mock location data.
+     *
+     * @returns Promise resolving to detected DOLocation
+     */
+    async _detectLocation() {
+        try {
+            // Fetch from Cloudflare's trace endpoint
+            const response = await fetch('https://cloudflare.com/cdn-cgi/trace');
+            if (!response.ok) {
+                throw new Error(`Trace endpoint returned ${response.status}`);
+            }
+            const text = await response.text();
+            const lines = text.split('\n');
+            const data = {};
+            for (const line of lines) {
+                const [key, value] = line.split('=');
+                if (key && value) {
+                    data[key.trim()] = value.trim();
+                }
+            }
+            const coloCode = (data.colo || 'lax').toLowerCase();
+            const city = (codeToCity[coloCode] || 'LosAngeles');
+            const region = (coloRegion[coloCode] || 'us-west');
+            const cfHint = (regionToCF[region] || 'wnam');
+            const location = {
+                colo: coloCode,
+                city,
+                region,
+                cfHint,
+                detectedAt: new Date(),
+            };
+            // Add coordinates if extracted from request
+            if (this._extractedCoordinates) {
+                location.coordinates = this._extractedCoordinates;
+            }
+            return location;
+        }
+        catch (error) {
+            // Fallback to default location on error
+            console.error('Failed to detect location:', error);
+            const location = {
+                colo: 'lax',
+                city: 'LosAngeles',
+                region: 'us-west',
+                cfHint: 'wnam',
+                detectedAt: new Date(),
+            };
+            if (this._extractedCoordinates) {
+                location.coordinates = this._extractedCoordinates;
+            }
+            return location;
+        }
+    }
+    /**
+     * Lifecycle hook called when location is first detected.
+     * Override in subclasses to perform custom actions.
+     *
+     * @param location - The detected DO location
+     */
+    async onLocationDetected(location) {
+        // Default implementation does nothing
+        // Subclasses can override to react to location detection
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // WORKFLOW CONTEXT ($)
+    // ═══════════════════════════════════════════════════════════════════════════
+    $;
+    // ═══════════════════════════════════════════════════════════════════════════
+    // CONSTRUCTOR
+    // ═══════════════════════════════════════════════════════════════════════════
+    constructor(ctx, env) {
+        super(ctx, env);
+        // Initialize workflow context
+        this.$ = this.createWorkflowContext();
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // WORKFLOW CONTEXT FACTORY
+    // ═══════════════════════════════════════════════════════════════════════════
+    createWorkflowContext() {
+        const self = this;
+        // List of known properties for hasOwnProperty checks
+        const knownProperties = new Set([
+            'send', 'try', 'do', 'on', 'every', 'log', 'state', 'location',
+            'ai', 'write', 'summarize', 'list', 'extract', 'is', 'decide',
+        ]);
+        return new Proxy({}, {
+            get(_, prop) {
+                switch (prop) {
+                    // Execution modes
+                    case 'send':
+                        return self.send.bind(self);
+                    case 'try':
+                        return self.try.bind(self);
+                    case 'do':
+                        return self.do.bind(self);
+                    // Event subscriptions and scheduling
+                    case 'on':
+                        return self.createOnProxy();
+                    case 'every':
+                        return self.createScheduleBuilder();
+                    // Utilities
+                    case 'log':
+                        return self.log.bind(self);
+                    case 'state':
+                        return {};
+                    // Location access (lazy, returns Promise)
+                    case 'location':
+                        return self.getLocation();
+                    // AI Functions - Generation
+                    case 'ai':
+                        return aiFunc;
+                    case 'write':
+                        return writeFunc;
+                    case 'summarize':
+                        return summarizeFunc;
+                    case 'list':
+                        return listFunc;
+                    case 'extract':
+                        return extractFunc;
+                    // AI Functions - Classification
+                    case 'is':
+                        return isFunc;
+                    case 'decide':
+                        return decideFunc;
+                    default:
+                        // Domain resolution: $.Noun(id)
+                        return (id) => self.createDomainProxy(prop, id);
+                }
+            },
+            has(_, prop) {
+                // Support `in` operator and hasOwnProperty checks for known properties
+                return knownProperties.has(String(prop));
+            },
+        });
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // EXECUTION MODES
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Default retry policy for durable execution
+     */
+    static DEFAULT_RETRY_POLICY = {
+        maxAttempts: 3,
+        initialDelayMs: 100,
+        maxDelayMs: 30000,
+        backoffMultiplier: 2,
+        jitter: true,
+    };
+    static DEFAULT_TRY_TIMEOUT = 30000;
+    _stepCache = new Map();
+    /**
+     * Fire-and-forget event emission (non-blocking, non-durable)
+     * Errors are logged but don't propagate (by design for fire-and-forget)
+     */
+    send(event, data) {
+        queueMicrotask(() => {
+            this.logAction('send', event, data).catch((error) => {
+                console.error(`[send] Failed to log action for ${event}:`, error);
+                this.emitSystemError('send.logAction.failed', event, error);
+            });
+            this.emitEvent(event, data).catch((error) => {
+                console.error(`[send] Failed to emit event ${event}:`, error);
+                this.emitSystemError('send.emitEvent.failed', event, error);
+            });
+            this.executeAction(event, data).catch((error) => {
+                console.error(`[send] Failed to execute action ${event}:`, error);
+                this.emitSystemError('send.executeAction.failed', event, error);
+            });
+        });
+    }
+    /**
+     * Emit a system error event for monitoring/observability
+     * This is a best-effort operation that should never throw
+     */
+    emitSystemError(errorType, originalEvent, error) {
+        try {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const errorStack = error instanceof Error ? error.stack : undefined;
+            // Log to console for immediate visibility
+            console.error(`[system.${errorType}]`, {
+                ns: this.ns,
+                originalEvent,
+                error: errorMessage,
+                stack: errorStack,
+            });
+            // Try to persist to DLQ for later replay
+            this.dlq.add({
+                eventId: `system-error-${crypto.randomUUID()}`,
+                verb: errorType,
+                source: this.ns,
+                data: { originalEvent, error: errorMessage },
+                error: errorMessage,
+                errorStack,
+                maxRetries: 3,
+            }).catch(() => {
+                // Absolute last resort - can't even log to DLQ
+                console.error(`[CRITICAL] Failed to add system error to DLQ: ${errorType}`);
+            });
+        }
+        catch (catchError) {
+            // Never throw from error handler, but log the failure
+            logBestEffortError(catchError, {
+                operation: 'emitSystemError',
+                source: 'DOBase.emitSystemError',
+                context: { errorType, originalEvent, ns: this.ns },
+            });
+        }
+    }
+    /**
+     * Quick attempt without durability (blocking, non-durable)
+     */
+    async try(action, data, options) {
+        const timeout = options?.timeout ?? DO.DEFAULT_TRY_TIMEOUT;
+        const startedAt = new Date();
+        const actionRecord = await this.logAction('try', action, data);
+        await this.updateActionStatus(actionRecord.id, 'running', { startedAt });
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => {
+                reject(new Error(`Action '${action}' timed out after ${timeout}ms`));
+            }, timeout);
+        });
+        try {
+            const result = await Promise.race([
+                this.executeAction(action, data),
+                timeoutPromise,
+            ]);
+            const completedAt = new Date();
+            const duration = completedAt.getTime() - startedAt.getTime();
+            await this.completeAction(actionRecord.id, result, { completedAt, duration });
+            await this.emitEvent(`${action}.completed`, { result });
+            return result;
+        }
+        catch (error) {
+            const completedAt = new Date();
+            const duration = completedAt.getTime() - startedAt.getTime();
+            const actionError = {
+                message: error.message,
+                name: error.name,
+                stack: error.stack,
+            };
+            await this.failAction(actionRecord.id, actionError, { completedAt, duration });
+            await this.emitEvent(`${action}.failed`, { error: actionError }).catch(() => { });
+            throw error;
+        }
+    }
+    /**
+     * Durable execution with retries (blocking, durable)
+     */
+    async do(action, data, options) {
+        const retryPolicy = {
+            ...DO.DEFAULT_RETRY_POLICY,
+            ...options?.retry,
+        };
+        const stepId = options?.stepId ?? this.generateStepId(action, data);
+        const cachedResult = this._stepCache.get(stepId);
+        if (cachedResult) {
+            return cachedResult.result;
+        }
+        const startedAt = new Date();
+        const actionRecord = await this.logAction('do', action, data);
+        let lastError;
+        let attempts = 0;
+        for (let attempt = 1; attempt <= retryPolicy.maxAttempts; attempt++) {
+            attempts = attempt;
+            const status = attempt === 1 ? 'running' : 'retrying';
+            await this.updateActionStatus(actionRecord.id, status, { startedAt, attempts });
+            try {
+                const result = await this.executeAction(action, data);
+                const completedAt = new Date();
+                const duration = completedAt.getTime() - startedAt.getTime();
+                await this.completeAction(actionRecord.id, result, { completedAt, duration, attempts });
+                this._stepCache.set(stepId, { result, completedAt: completedAt.getTime() });
+                await this.persistStepResult(stepId, result);
+                await this.emitEvent(`${action}.completed`, { result });
+                return result;
+            }
+            catch (error) {
+                lastError = error;
+                await this.updateActionAttempts(actionRecord.id, attempts);
+                if (attempt < retryPolicy.maxAttempts) {
+                    const delay = this.calculateBackoffDelay(attempt, retryPolicy);
+                    await this.sleep(delay);
+                }
+            }
+        }
+        const completedAt = new Date();
+        const duration = completedAt.getTime() - startedAt.getTime();
+        const actionError = {
+            message: lastError.message,
+            name: lastError.name,
+            stack: lastError.stack,
+        };
+        await this.failAction(actionRecord.id, actionError, { completedAt, duration, attempts });
+        await this.emitEvent(`${action}.failed`, { error: actionError });
+        throw lastError;
+    }
+    calculateBackoffDelay(attempt, policy) {
+        let delay = policy.initialDelayMs * Math.pow(policy.backoffMultiplier, attempt - 1);
+        delay = Math.min(delay, policy.maxDelayMs);
+        if (policy.jitter) {
+            const jitterRange = delay * 0.25;
+            delay += Math.random() * jitterRange;
+        }
+        return Math.floor(delay);
+    }
+    generateStepId(action, data) {
+        const content = JSON.stringify({ action, data });
+        let hash = 0;
+        for (let i = 0; i < content.length; i++) {
+            const char = content.charCodeAt(i);
+            hash = ((hash << 5) - hash) + char;
+            hash = hash & hash;
+        }
+        return `${action}:${Math.abs(hash).toString(36)}`;
+    }
+    async persistStepResult(stepId, result) {
+        try {
+            await this.ctx.storage.put(`step:${stepId}`, { result, completedAt: Date.now() });
+        }
+        catch (error) {
+            logBestEffortError(error, {
+                operation: 'persistStepResult',
+                source: 'DOBase.persistStepResult',
+                context: { stepId, ns: this.ns },
+            });
+        }
+    }
+    async loadPersistedSteps() {
+        try {
+            const steps = await this.ctx.storage.list({ prefix: 'step:' });
+            for (const [key, value] of steps) {
+                const stepId = key.replace('step:', '');
+                const data = value;
+                this._stepCache.set(stepId, data);
+            }
+        }
+        catch (error) {
+            logBestEffortError(error, {
+                operation: 'loadPersistedSteps',
+                source: 'DOBase.loadPersistedSteps',
+                context: { ns: this.ns },
+            });
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ACTION LOGGING (append-only)
+    // ═══════════════════════════════════════════════════════════════════════════
+    async logAction(durability, verb, input) {
+        const id = crypto.randomUUID();
+        await this.db
+            .insert(schema.actions)
+            // @ts-expect-error - Schema field names may differ
+            .values({
+            id,
+            verb,
+            target: this.ns,
+            actor: this._currentActor,
+            input: input,
+            durability,
+            status: 'pending',
+            createdAt: new Date(),
+        });
+        return { id, rowid: 0 };
+    }
+    async updateActionStatus(actionId, status, fields) {
+        try {
+            const updateData = { status };
+            if (fields?.startedAt) {
+                updateData.startedAt = fields.startedAt;
+            }
+            if (fields?.attempts !== undefined) {
+                updateData.options = JSON.stringify({ attempts: fields.attempts });
+            }
+            await this.db
+                .update(schema.actions)
+                .set(updateData)
+                .where(eq(schema.actions.id, actionId));
+        }
+        catch (error) {
+            logBestEffortError(error, {
+                operation: 'updateActionStatus',
+                source: 'DOBase.updateActionStatus',
+                context: { actionId, status, ns: this.ns },
+            });
+        }
+    }
+    async updateActionAttempts(actionId, attempts) {
+        try {
+            await this.db
+                .update(schema.actions)
+                .set({ options: JSON.stringify({ attempts }) })
+                .where(eq(schema.actions.id, actionId));
+        }
+        catch (error) {
+            logBestEffortError(error, {
+                operation: 'updateActionAttempts',
+                source: 'DOBase.updateActionAttempts',
+                context: { actionId, attempts, ns: this.ns },
+            });
+        }
+    }
+    async completeAction(actionId, output, fields) {
+        try {
+            const updateData = {
+                status: 'completed',
+                output: output,
+            };
+            if (fields?.completedAt) {
+                updateData.completedAt = fields.completedAt;
+            }
+            if (fields?.duration !== undefined) {
+                updateData.duration = fields.duration;
+            }
+            if (fields?.attempts !== undefined) {
+                updateData.options = JSON.stringify({ attempts: fields.attempts });
+            }
+            await this.db
+                .update(schema.actions)
+                .set(updateData)
+                .where(eq(schema.actions.id, actionId));
+        }
+        catch (error) {
+            logBestEffortError(error, {
+                operation: 'completeAction',
+                source: 'DOBase.completeAction',
+                context: { actionId, ns: this.ns },
+            });
+        }
+    }
+    async failAction(actionId, error, fields) {
+        try {
+            const updateData = {
+                status: 'failed',
+                error: error,
+            };
+            if (fields?.completedAt) {
+                updateData.completedAt = fields.completedAt;
+            }
+            if (fields?.duration !== undefined) {
+                updateData.duration = fields.duration;
+            }
+            if (fields?.attempts !== undefined) {
+                updateData.options = JSON.stringify({ attempts: fields.attempts });
+            }
+            await this.db
+                .update(schema.actions)
+                .set(updateData)
+                .where(eq(schema.actions.id, actionId));
+        }
+        catch (catchError) {
+            logBestEffortError(catchError, {
+                operation: 'failAction',
+                source: 'DOBase.failAction',
+                context: { actionId, errorMessage: error.message, ns: this.ns },
+            });
+        }
+    }
+    /**
+     * Execute an action - override in subclasses to handle specific actions
+     */
+    async executeAction(action, data) {
+        throw new Error(`Unknown action: ${action}`);
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // EVENT EMISSION
+    // ═══════════════════════════════════════════════════════════════════════════
+    async emitEvent(verb, data) {
+        const eventId = crypto.randomUUID();
+        let dbError = null;
+        let pipelineError = null;
+        // Attempt database insert with error capture
+        try {
+            await this.db.insert(schema.events).values({
+                id: eventId,
+                verb,
+                source: this.ns,
+                data: data,
+                sequence: 0,
+                streamed: false,
+                createdAt: new Date(),
+            });
+        }
+        catch (error) {
+            dbError = error instanceof Error ? error : new Error(String(error));
+            console.error(`[emitEvent] Database insert failed for ${verb}:`, dbError.message);
+            // Add to DLQ for retry
+            try {
+                await this.dlq.add({
+                    eventId,
+                    verb,
+                    source: this.ns,
+                    data: data,
+                    error: dbError.message,
+                    errorStack: dbError.stack,
+                    maxRetries: 3,
+                });
+            }
+            catch (dlqError) {
+                console.error(`[emitEvent] Failed to add to DLQ:`, dlqError);
+            }
+        }
+        // Attempt pipeline send with error capture and retry
+        if (this.env.PIPELINE) {
+            const maxPipelineRetries = 3;
+            const baseDelay = 100;
+            for (let attempt = 1; attempt <= maxPipelineRetries; attempt++) {
+                try {
+                    await this.env.PIPELINE.send([{
+                            verb,
+                            source: this.ns,
+                            $context: this.ns,
+                            data,
+                            timestamp: new Date().toISOString(),
+                        }]);
+                    pipelineError = null; // Success - clear any previous error
+                    break;
+                }
+                catch (error) {
+                    pipelineError = error instanceof Error ? error : new Error(String(error));
+                    console.error(`[emitEvent] Pipeline send attempt ${attempt}/${maxPipelineRetries} failed for ${verb}:`, pipelineError.message);
+                    if (attempt < maxPipelineRetries) {
+                        // Exponential backoff
+                        const delay = baseDelay * Math.pow(2, attempt - 1);
+                        await this.sleep(delay);
+                    }
+                }
+            }
+            // If all pipeline retries failed, log for metrics
+            if (pipelineError) {
+                console.error(`[emitEvent] Pipeline send failed after ${maxPipelineRetries} attempts for ${verb}`);
+            }
+        }
+        // Emit system error event if either operation failed (for observability)
+        if (dbError || pipelineError) {
+            try {
+                // Use console for metrics visibility (can be scraped by log aggregators)
+                console.error('[metrics.event.emission.failure]', {
+                    ns: this.ns,
+                    verb,
+                    dbError: dbError?.message ?? null,
+                    pipelineError: pipelineError?.message ?? null,
+                });
+            }
+            catch {
+                // Never throw from error reporting
+            }
+        }
+    }
+    /**
+     * Emit an event (public wrapper for emitEvent)
+     */
+    async emit(verb, data) {
+        return this.emitEvent(verb, data);
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // NOUN FK RESOLUTION
+    // ═══════════════════════════════════════════════════════════════════════════
+    async resolveNounToFK(noun) {
+        if (!noun || noun.trim() === '') {
+            throw new Error('Noun name cannot be empty');
+        }
+        if (!isValidNounName(noun)) {
+            throw new Error(`Invalid noun '${noun}': must be PascalCase`);
+        }
+        const cached = this._typeCache.get(noun);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const results = await this.db
+            .select({
+            noun: schema.nouns.noun,
+            rowid: sql `rowid`,
+        })
+            .from(schema.nouns)
+            .where(eq(schema.nouns.noun, noun));
+        if (results.length === 0) {
+            throw new Error(`Noun '${noun}' not found in nouns table. Register it first with registerNoun().`);
+        }
+        const fk = results[0].rowid;
+        this._typeCache.set(noun, fk);
+        return fk;
+    }
+    async registerNoun(noun, config) {
+        if (!noun || noun.trim() === '') {
+            throw new Error('Noun name cannot be empty');
+        }
+        if (!isValidNounName(noun)) {
+            throw new Error(`Invalid noun '${noun}': must be PascalCase`);
+        }
+        const cached = this._typeCache.get(noun);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const existing = await this.db
+            .select({
+            noun: schema.nouns.noun,
+            rowid: sql `rowid`,
+        })
+            .from(schema.nouns)
+            .where(eq(schema.nouns.noun, noun));
+        if (existing.length > 0) {
+            const fk = existing[0].rowid;
+            this._typeCache.set(noun, fk);
+            return fk;
+        }
+        await this.db.insert(schema.nouns).values({
+            noun,
+            plural: config?.plural ?? `${noun}s`,
+            description: config?.description ?? null,
+            schema: config?.schema ? JSON.stringify(config.schema) : null,
+            doClass: config?.doClass ?? null,
+        });
+        const inserted = await this.db
+            .select({
+            noun: schema.nouns.noun,
+            rowid: sql `rowid`,
+        })
+            .from(schema.nouns)
+            .where(eq(schema.nouns.noun, noun));
+        if (inserted.length === 0) {
+            throw new Error(`Failed to register noun '${noun}'`);
+        }
+        const fk = inserted[0].rowid;
+        this._typeCache.set(noun, fk);
+        return fk;
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // TYPED COLLECTION ACCESSORS
+    // ═══════════════════════════════════════════════════════════════════════════
+    collection(noun) {
+        if (!noun || noun.trim() === '') {
+            throw new Error('Noun name cannot be empty');
+        }
+        if (!isValidNounName(noun)) {
+            throw new Error(`Invalid noun '${noun}': must be PascalCase`);
+        }
+        const self = this;
+        return {
+            get: async (id) => {
+                const typeFK = await self.resolveNounToFK(noun);
+                const results = await self.db.select().from(schema.things);
+                const result = results.find((r) => r.id === id && r.type === typeFK && !r.deleted);
+                if (!result)
+                    return null;
+                const data = result.data;
+                return { $id: result.id, $type: noun, ...data };
+            },
+            list: async () => {
+                const typeFK = await self.resolveNounToFK(noun);
+                const results = await self.db.select().from(schema.things);
+                return results
+                    .filter((r) => r.type === typeFK && !r.deleted)
+                    .map((r) => {
+                    const data = r.data;
+                    return { $id: r.id, $type: noun, ...data };
+                });
+            },
+            find: async (query) => {
+                const typeFK = await self.resolveNounToFK(noun);
+                const results = await self.db.select().from(schema.things);
+                return results
+                    .filter((r) => {
+                    if (r.type !== typeFK || r.deleted)
+                        return false;
+                    const data = r.data;
+                    if (!data)
+                        return false;
+                    return Object.entries(query).every(([key, value]) => data[key] === value);
+                })
+                    .map((r) => {
+                    const data = r.data;
+                    return { $id: r.id, $type: noun, ...data };
+                });
+            },
+            create: async (data) => {
+                const typeFK = await self.resolveNounToFK(noun);
+                const id = data.$id || crypto.randomUUID();
+                await self.db.insert(schema.things).values({
+                    id,
+                    type: typeFK,
+                    branch: self.currentBranch,
+                    data: data,
+                    deleted: false,
+                });
+                self._typeCache.set(noun, typeFK);
+                return { ...data, $id: id, $type: noun };
+            },
+            update: async (id, data) => {
+                const result = await self.things.update(id, {
+                    data: data,
+                });
+                return {
+                    $id: result.$id,
+                    $type: noun,
+                    ...result.data,
+                    $rowid: result.version ?? 0,
+                };
+            },
+            delete: async (id) => {
+                const result = await self.things.delete(id);
+                return {
+                    $id: result.$id,
+                    $type: noun,
+                    ...result.data,
+                    $rowid: result.version ?? 0,
+                };
+            },
+        };
+    }
+    /**
+     * Relationships table accessor
+     */
+    get relationships() {
+        return {
+            create: async (data) => {
+                const id = crypto.randomUUID();
+                await this.db.insert(schema.relationships).values({
+                    id,
+                    verb: data.verb,
+                    from: data.from,
+                    to: data.to,
+                    data: data.data,
+                    createdAt: new Date(),
+                });
+                return { id };
+            },
+            list: async (query) => {
+                const results = await this.db.select().from(schema.relationships);
+                return results
+                    .filter((r) => {
+                    if (query?.from && r.from !== query.from)
+                        return false;
+                    if (query?.to && r.to !== query.to)
+                        return false;
+                    if (query?.verb && r.verb !== query.verb)
+                        return false;
+                    return true;
+                })
+                    .map((r) => ({
+                    id: r.id,
+                    verb: r.verb,
+                    from: r.from,
+                    to: r.to,
+                    data: r.data,
+                    createdAt: r.createdAt,
+                }));
+            },
+        };
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // PROXY FACTORIES
+    // ═══════════════════════════════════════════════════════════════════════════
+    createOnProxy() {
+        const self = this;
+        return new Proxy({}, {
+            get: (_, noun) => {
+                return new Proxy({}, {
+                    get: (_, verb) => {
+                        return (handler, options) => {
+                            const eventKey = `${noun}.${verb}`;
+                            const registrations = self._eventHandlers.get(eventKey) ?? [];
+                            const handlerName = options?.name
+                                || handler.name
+                                || `handler_${++self._handlerCounter}`;
+                            const registration = {
+                                name: handlerName,
+                                priority: options?.priority ?? 0,
+                                registeredAt: Date.now(),
+                                sourceNs: self.ns,
+                                handler,
+                                filter: options?.filter,
+                                maxRetries: options?.maxRetries ?? 3,
+                                executionCount: 0,
+                                successCount: 0,
+                                failureCount: 0,
+                            };
+                            registrations.push(registration);
+                            registrations.sort((a, b) => {
+                                if (b.priority !== a.priority) {
+                                    return b.priority - a.priority;
+                                }
+                                return a.registeredAt - b.registeredAt;
+                            });
+                            self._eventHandlers.set(eventKey, registrations);
+                        };
+                    },
+                });
+            },
+        });
+    }
+    createScheduleBuilder() {
+        const self = this;
+        const config = {
+            state: this.ctx,
+            onScheduleRegistered: (cron, name, handler) => {
+                self._scheduleHandlers.set(name, handler);
+                self.scheduleManager.schedule(cron, name).catch((error) => {
+                    console.error(`Failed to register schedule ${name}:`, error);
+                });
+            },
+        };
+        return createScheduleBuilderProxy(config);
+    }
+    createDomainProxy(noun, id) {
+        const self = this;
+        return new Proxy({}, {
+            get(_, method) {
+                if (method === 'then' || method === 'catch' || method === 'finally') {
+                    return undefined;
+                }
+                return (...args) => {
+                    return self.invokeDomainMethod(noun, id, method, args);
+                };
+            },
+        });
+    }
+    async invokeDomainMethod(noun, id, method, args) {
+        const localMethod = this[method];
+        if (typeof localMethod === 'function') {
+            try {
+                return await localMethod.apply(this, args);
+            }
+            catch (error) {
+                throw error;
+            }
+        }
+        return this.invokeCrossDOMethod(noun, id, method, args);
+    }
+    // Circuit breaker state for cross-DO calls (per target DO)
+    static _circuitBreakers = new Map();
+    // Circuit breaker configuration
+    static CIRCUIT_BREAKER_CONFIG = {
+        failureThreshold: 5,
+        resetTimeoutMs: 30000,
+        halfOpenRequests: 1,
+    };
+    // Cross-DO retry configuration
+    static CROSS_DO_RETRY_CONFIG = {
+        maxAttempts: 3,
+        initialDelayMs: 100,
+        maxDelayMs: 5000,
+        backoffMultiplier: 2,
+        retryableStatuses: [500, 502, 503, 504],
+        retryableErrors: ['ECONNRESET', 'ETIMEDOUT', 'ECONNREFUSED'],
+    };
+    // Default timeout for cross-DO calls
+    static CROSS_DO_TIMEOUT_MS = 30000;
+    async invokeCrossDOMethod(noun, id, method, args, options) {
+        if (!this.env.DO) {
+            throw new Error(`Method '${method}' not found and DO namespace not configured for cross-DO calls`);
+        }
+        const targetNs = `${noun}/${id}`;
+        const timeout = options?.timeout ?? DO.CROSS_DO_TIMEOUT_MS;
+        // Check circuit breaker
+        const circuitState = this.checkCircuitBreaker(targetNs);
+        if (circuitState === 'open') {
+            throw new CrossDOError('CIRCUIT_BREAKER_OPEN', `Circuit breaker open for ${targetNs}`, { targetDO: targetNs, source: this.ns });
+        }
+        const doNamespace = this.env.DO;
+        const doId = doNamespace.idFromName(targetNs);
+        const stub = doNamespace.get(doId);
+        const { maxAttempts, initialDelayMs, maxDelayMs, backoffMultiplier, retryableStatuses } = DO.CROSS_DO_RETRY_CONFIG;
+        let lastError;
+        let attempts = 0;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            attempts = attempt;
+            try {
+                const response = await this.fetchWithCrossDOTimeout(stub, `https://${targetNs}/rpc/${method}`, { args }, timeout);
+                // Check for rate limiting
+                if (response.status === 429) {
+                    const retryAfter = response.headers.get('Retry-After');
+                    const delay = retryAfter ? parseInt(retryAfter, 10) * 1000 : initialDelayMs * Math.pow(backoffMultiplier, attempt - 1);
+                    if (attempt < maxAttempts) {
+                        await this.sleep(Math.min(delay, maxDelayMs));
+                        continue;
+                    }
+                }
+                // Non-retryable client errors
+                if (response.status >= 400 && response.status < 500 && response.status !== 429) {
+                    const errorText = await response.text();
+                    this.recordCircuitBreakerSuccess(targetNs);
+                    throw new CrossDOError('CROSS_DO_CLIENT_ERROR', `Cross-DO RPC failed: ${response.status} - ${errorText}`, { targetDO: targetNs, method, source: this.ns });
+                }
+                // Retryable server errors
+                if (!response.ok && retryableStatuses.includes(response.status)) {
+                    const errorText = await response.text();
+                    lastError = new Error(`Cross-DO RPC failed: ${response.status} - ${errorText}`);
+                    if (attempt < maxAttempts) {
+                        const delay = Math.min(initialDelayMs * Math.pow(backoffMultiplier, attempt - 1), maxDelayMs);
+                        await this.sleep(delay);
+                        continue;
+                    }
+                }
+                if (!response.ok) {
+                    const errorText = await response.text();
+                    this.recordCircuitBreakerFailure(targetNs);
+                    throw new CrossDOError('CROSS_DO_ERROR', `Cross-DO RPC failed: ${response.status} - ${errorText}`, { targetDO: targetNs, method, attempts, source: this.ns });
+                }
+                const result = await response.json();
+                if (result.error) {
+                    this.recordCircuitBreakerFailure(targetNs);
+                    throw new CrossDOError('CROSS_DO_ERROR', result.error, { targetDO: targetNs, method, source: this.ns });
+                }
+                // Success - record and return
+                this.recordCircuitBreakerSuccess(targetNs);
+                return result.result;
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                // Check for timeout
+                if (lastError.name === 'AbortError' || lastError.message.includes('timeout')) {
+                    this.recordCircuitBreakerFailure(targetNs);
+                    throw new CrossDOError('CROSS_DO_TIMEOUT', `Cross-DO call to ${targetNs}.${method}() timed out after ${timeout}ms`, { targetDO: targetNs, method, source: this.ns });
+                }
+                // Check if error is retryable
+                const isRetryable = DO.CROSS_DO_RETRY_CONFIG.retryableErrors.some(errType => lastError.message.includes(errType));
+                if (isRetryable && attempt < maxAttempts) {
+                    const delay = Math.min(initialDelayMs * Math.pow(backoffMultiplier, attempt - 1), maxDelayMs);
+                    await this.sleep(delay);
+                    continue;
+                }
+                // Not retryable or exhausted retries
+                this.recordCircuitBreakerFailure(targetNs);
+                throw lastError;
+            }
+        }
+        // Exhausted all retries
+        this.recordCircuitBreakerFailure(targetNs);
+        throw new CrossDOError('CROSS_DO_ERROR', `Cross-DO call failed after ${attempts} attempts`, {
+            targetDO: targetNs,
+            method,
+            attempts,
+            source: this.ns,
+            originalError: lastError?.message,
+        });
+    }
+    /**
+     * Fetch with timeout for cross-DO calls
+     */
+    async fetchWithCrossDOTimeout(stub, url, body, timeoutMs) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            return await stub.fetch(new Request(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            }));
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Check circuit breaker state for a target DO
+     */
+    checkCircuitBreaker(targetNs) {
+        const breaker = DO._circuitBreakers.get(targetNs);
+        if (!breaker)
+            return 'closed';
+        const { failureThreshold, resetTimeoutMs } = DO.CIRCUIT_BREAKER_CONFIG;
+        if (breaker.state === 'open') {
+            // Check if enough time has passed to try half-open
+            if (Date.now() - breaker.lastFailure >= resetTimeoutMs) {
+                breaker.state = 'half-open';
+                return 'half-open';
+            }
+            return 'open';
+        }
+        if (breaker.failures >= failureThreshold) {
+            breaker.state = 'open';
+            return 'open';
+        }
+        return breaker.state;
+    }
+    /**
+     * Record a successful cross-DO call (reset circuit breaker)
+     */
+    recordCircuitBreakerSuccess(targetNs) {
+        DO._circuitBreakers.set(targetNs, {
+            failures: 0,
+            lastFailure: 0,
+            state: 'closed',
+        });
+    }
+    /**
+     * Record a failed cross-DO call
+     */
+    recordCircuitBreakerFailure(targetNs) {
+        const breaker = DO._circuitBreakers.get(targetNs) ?? {
+            failures: 0,
+            lastFailure: 0,
+            state: 'closed',
+        };
+        breaker.failures++;
+        breaker.lastFailure = Date.now();
+        if (breaker.failures >= DO.CIRCUIT_BREAKER_CONFIG.failureThreshold) {
+            breaker.state = 'open';
+        }
+        DO._circuitBreakers.set(targetNs, breaker);
+    }
+    /**
+     * Reset all static state - ONLY for testing.
+     * This clears accumulated static Maps that persist across test runs.
+     */
+    static _resetTestState() {
+        DO._circuitBreakers.clear();
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // EVENT HANDLER MANAGEMENT
+    // ═══════════════════════════════════════════════════════════════════════════
+    getEventHandlers(eventKey) {
+        const registrations = this._eventHandlers.get(eventKey) ?? [];
+        return registrations.map((r) => r.handler);
+    }
+    getHandlersByPriority(eventKey) {
+        const registrations = this._eventHandlers.get(eventKey) ?? [];
+        return registrations.map((r) => ({ handler: r.handler, priority: r.priority }));
+    }
+    getHandlerMetadata(eventKey, handlerName) {
+        const registrations = this._eventHandlers.get(eventKey) ?? [];
+        return registrations.find((r) => r.name === handlerName);
+    }
+    getHandlerRegistrations(eventKey) {
+        return this._eventHandlers.get(eventKey) ?? [];
+    }
+    listAllHandlers() {
+        return new Map(this._eventHandlers);
+    }
+    collectMatchingHandlers(noun, verb) {
+        const matchingHandlers = [];
+        const exactKey = `${noun}.${verb}`;
+        for (const reg of this._eventHandlers.get(exactKey) ?? []) {
+            matchingHandlers.push({ registration: reg, isWildcard: false });
+        }
+        for (const reg of this._eventHandlers.get(`*.${verb}`) ?? []) {
+            matchingHandlers.push({ registration: reg, isWildcard: true });
+        }
+        for (const reg of this._eventHandlers.get(`${noun}.*`) ?? []) {
+            matchingHandlers.push({ registration: reg, isWildcard: true });
+        }
+        for (const reg of this._eventHandlers.get('*.*') ?? []) {
+            matchingHandlers.push({ registration: reg, isWildcard: true });
+        }
+        matchingHandlers.sort((a, b) => {
+            if (b.registration.priority !== a.registration.priority) {
+                return b.registration.priority - a.registration.priority;
+            }
+            if (a.isWildcard !== b.isWildcard) {
+                return a.isWildcard ? 1 : -1;
+            }
+            return a.registration.registeredAt - b.registration.registeredAt;
+        });
+        return matchingHandlers.map((h) => h.registration);
+    }
+    async dispatchEventToHandlers(event) {
+        const sourceParts = event.source.split('/');
+        const noun = sourceParts[sourceParts.length - 2] || '';
+        const registrations = this.collectMatchingHandlers(noun, event.verb);
+        let handled = 0;
+        let filtered = 0;
+        let wildcardMatches = 0;
+        const errors = [];
+        const dlqEntries = [];
+        const exactKey = `${noun}.${event.verb}`;
+        const exactRegistrations = new Set((this._eventHandlers.get(exactKey) ?? []).map((r) => r.name));
+        for (const registration of registrations) {
+            if (!exactRegistrations.has(registration.name)) {
+                wildcardMatches++;
+            }
+            if (registration.filter) {
+                try {
+                    const shouldExecute = await registration.filter(event);
+                    if (!shouldExecute) {
+                        filtered++;
+                        continue;
+                    }
+                }
+                catch {
+                    filtered++;
+                    continue;
+                }
+            }
+            registration.executionCount++;
+            registration.lastExecutedAt = Date.now();
+            try {
+                await registration.handler(event);
+                registration.successCount++;
+                handled++;
+            }
+            catch (e) {
+                registration.failureCount++;
+                const error = e instanceof Error ? e : new Error(String(e));
+                errors.push(error);
+                try {
+                    const dlqEntry = await this.dlq.add({
+                        eventId: event.id,
+                        verb: `${noun}.${event.verb}`,
+                        source: event.source,
+                        data: event.data,
+                        error: error.message,
+                        errorStack: error.stack,
+                        maxRetries: registration.maxRetries,
+                    });
+                    dlqEntries.push(dlqEntry.id);
+                }
+                catch {
+                    console.error('Failed to add event to DLQ');
+                }
+            }
+        }
+        return { handled, errors, dlqEntries, filtered, wildcardMatches };
+    }
+    unregisterEventHandler(eventKey, handler) {
+        const registrations = this._eventHandlers.get(eventKey);
+        if (!registrations) {
+            return false;
+        }
+        const index = registrations.findIndex((r) => r.handler === handler);
+        if (index > -1) {
+            registrations.splice(index, 1);
+            return true;
+        }
+        return false;
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // RESOLUTION
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Resolve any URL to a Thing (local, cross-DO, or external)
+     */
+    async resolve(url) {
+        const parsed = new URL(url);
+        const ns = `${parsed.protocol}//${parsed.host}`;
+        const path = parsed.pathname.slice(1);
+        const ref = parsed.hash.slice(1) || 'main';
+        if (ns === this.ns) {
+            return this.resolveLocal(path, ref);
+        }
+        else {
+            return this.resolveCrossDO(ns, path, ref);
+        }
+    }
+    async resolveLocal(path, ref) {
+        const parsed = parseNounId(path);
+        const branch = parsed.branch ?? (ref || this.currentBranch);
+        const thingId = parsed.id;
+        if (parsed.version !== undefined || parsed.relativeVersion !== undefined) {
+            const versions = await this.things.versions(thingId);
+            if (versions.length === 0) {
+                throw new Error(`Thing not found: ${path}`);
+            }
+            let targetVersion;
+            if (parsed.version !== undefined) {
+                const versionIndex = parsed.version - 1;
+                if (versionIndex < 0 || versionIndex >= versions.length) {
+                    throw new Error(`Thing not found: ${path}`);
+                }
+                targetVersion = versions[versionIndex];
+            }
+            else if (parsed.relativeVersion !== undefined) {
+                const targetIndex = versions.length - 1 - parsed.relativeVersion;
+                if (targetIndex < 0) {
+                    throw new Error(`Relative version @~${parsed.relativeVersion} exceeds available versions (${versions.length} total)`);
+                }
+                targetVersion = versions[targetIndex];
+            }
+            if (!targetVersion) {
+                throw new Error(`Version not found for path: ${path}`);
+            }
+            const fullId = this.ns ? `${this.ns}/${parsed.noun}/${parsed.id}` : `${parsed.noun}/${parsed.id}`;
+            return {
+                $id: fullId,
+                $type: parsed.noun,
+                name: targetVersion.name ?? undefined,
+                data: targetVersion.data ?? undefined,
+            };
+        }
+        const options = {};
+        if (branch && branch !== 'main') {
+            options.branch = branch;
+        }
+        const thing = await this.things.get(thingId, options);
+        if (!thing) {
+            throw new Error(`Thing not found: ${path}`);
+        }
+        const fullId = this.ns ? `${this.ns}/${parsed.noun}/${parsed.id}` : `${parsed.noun}/${parsed.id}`;
+        return {
+            $id: fullId,
+            $type: parsed.noun,
+            name: thing.name ?? undefined,
+            data: thing.data ?? undefined,
+        };
+    }
+    async resolveCrossDO(ns, path, ref) {
+        const obj = await this.objects.get(ns);
+        if (!obj) {
+            throw new Error(`Unknown namespace: ${ns}`);
+        }
+        if (!this.env.DO) {
+            throw new Error('DO namespace binding not configured');
+        }
+        const doNamespace = this.env.DO;
+        const id = doNamespace.idFromString(obj.id);
+        const stub = doNamespace.get(id);
+        const resolveUrl = new URL(`${ns}/resolve`);
+        resolveUrl.searchParams.set('path', path);
+        resolveUrl.searchParams.set('ref', ref);
+        const response = await stub.fetch(new Request(resolveUrl.toString(), {
+            method: 'GET',
+            headers: { 'Content-Type': 'application/json' },
+        }));
+        if (!response.ok) {
+            throw new Error(`Cross-DO resolution failed: ${response.status}`);
+        }
+        let thing;
+        try {
+            thing = await response.json();
+        }
+        catch {
+            throw new Error('Invalid response from remote DO');
+        }
+        return thing;
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // RELATIONSHIPS
+    // ═══════════════════════════════════════════════════════════════════════════
+    parent;
+    async link(target, relationType = 'related') {
+        const targetNs = typeof target === 'string' ? target : target.doId;
+        const metadata = typeof target === 'string' ? undefined : target;
+        await this.db.insert(schema.relationships).values({
+            id: crypto.randomUUID(),
+            verb: typeof target === 'string' ? relationType : target.role || relationType,
+            from: this.ns,
+            to: targetNs,
+            data: metadata,
+            createdAt: new Date(),
+        });
+    }
+    async getLinkedObjects(relationType) {
+        const results = await this.db.select().from(schema.relationships);
+        return results
+            .filter((r) => r.from === this.ns && (!relationType || r.verb === relationType))
+            .map((r) => ({
+            ns: r.to,
+            relationType: r.verb,
+            doId: r.to,
+            doClass: r.data?.doClass,
+            data: r.data,
+        }));
+    }
+    async createThing(data) {
+        const id = crypto.randomUUID();
+        // @ts-expect-error - Drizzle schema types may differ slightly
+        await this.db.insert(schema.things).values({
+            id,
+            ns: this.ns,
+            type: data.type,
+            data: { name: data.name, ...data.data },
+            version: 1,
+            branch: this.currentBranch,
+            createdAt: new Date(),
+            updatedAt: new Date(),
+        });
+        return { id };
+    }
+    async createAction(data) {
+        const id = crypto.randomUUID();
+        // @ts-expect-error - Schema field names may differ
+        await this.db.insert(schema.actions).values({
+            id,
+            verb: data.type,
+            target: data.target,
+            actor: data.actor,
+            input: data.data,
+            status: 'pending',
+            createdAt: new Date(),
+        });
+        return { id };
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // VISIBILITY HELPERS
+    // ═══════════════════════════════════════════════════════════════════════════
+    _currentActorContext = {};
+    setActorContext(actor) {
+        this._currentActorContext = actor;
+    }
+    getActorContext() {
+        return this._currentActorContext;
+    }
+    clearActorContext() {
+        this._currentActorContext = {};
+    }
+    canViewThing(thing) {
+        if (!thing) {
+            return false;
+        }
+        const visibility = thing.data?.visibility ?? 'user';
+        const actor = this._currentActorContext;
+        if (visibility === 'public' || visibility === 'unlisted') {
+            return true;
+        }
+        if (visibility === 'org') {
+            const dataObj = thing.data;
+            const metaObj = dataObj?.meta;
+            const thingOrgId = metaObj?.orgId ?? dataObj?.orgId;
+            return !!actor.orgId && actor.orgId === thingOrgId;
+        }
+        const dataObj = thing.data;
+        const metaObj = dataObj?.meta;
+        const thingOwnerId = metaObj?.ownerId ?? dataObj?.ownerId;
+        return !!actor.userId && actor.userId === thingOwnerId;
+    }
+    assertCanView(thing, message) {
+        if (!thing) {
+            throw new Error(message ?? 'Thing not found');
+        }
+        if (!this.canViewThing(thing)) {
+            const visibility = thing.data?.visibility ?? 'user';
+            let reason;
+            switch (visibility) {
+                case 'org':
+                    reason = 'Organization membership required';
+                    break;
+                case 'user':
+                    reason = 'Owner access required';
+                    break;
+                default:
+                    reason = 'Access denied';
+            }
+            throw new Error(message ?? reason);
+        }
+    }
+    filterVisibleThings(things) {
+        return things.filter((thing) => this.canViewThing(thing));
+    }
+    async getVisibleThing(id) {
+        const thing = await this.things.get(id);
+        if (!thing) {
+            return null;
+        }
+        return this.canViewThing(thing) ? thing : null;
+    }
+    getVisibility(thing) {
+        if (!thing) {
+            return 'user';
+        }
+        return thing.data?.visibility ?? 'user';
+    }
+    isOwner(thing) {
+        if (!thing) {
+            return false;
+        }
+        const dataObj = thing.data;
+        const metaObj = dataObj?.meta;
+        const thingOwnerId = metaObj?.ownerId ?? dataObj?.ownerId;
+        const actor = this._currentActorContext;
+        return !!actor.userId && actor.userId === thingOwnerId;
+    }
+    isInThingOrg(thing) {
+        if (!thing) {
+            return false;
+        }
+        const dataObj = thing.data;
+        const metaObj = dataObj?.meta;
+        const thingOrgId = metaObj?.orgId ?? dataObj?.orgId;
+        const actor = this._currentActorContext;
+        return !!actor.orgId && actor.orgId === thingOrgId;
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // REST ROUTER CONTEXT
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Get REST router context for handling REST API requests.
+     * Provides the things store and namespace for CRUD operations.
+     */
+    getRestRouterContext() {
+        // Get the DO class type from static $type or constructor name
+        const DOClass = this.constructor;
+        const doType = DOClass.$type || this.constructor.name;
+        return {
+            things: this.things,
+            ns: this.ns,
+            contextUrl: 'https://dotdo.dev/context',
+            nouns: this.getRegisteredNouns(),
+            doType,
+        };
+    }
+    /**
+     * Get list of registered nouns for the index.
+     * Override in subclasses to provide custom noun list.
+     */
+    getRegisteredNouns() {
+        // Return cached nouns from typeCache
+        // This is populated as types are used
+        const nouns = [];
+        for (const [noun] of this._typeCache) {
+            // Simple pluralization (subclasses can override for complex cases)
+            const plural = noun.endsWith('y')
+                ? noun.slice(0, -1) + 'ies'
+                : noun.endsWith('s') || noun.endsWith('x') || noun.endsWith('ch') || noun.endsWith('sh')
+                    ? noun + 'es'
+                    : noun + 's';
+            nouns.push({ noun, plural });
+        }
+        return nouns;
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // MCP HANDLER
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Handle MCP (Model Context Protocol) requests.
+     * This method is exposed for direct MCP access and is also routed from /mcp path.
+     *
+     * @param request - The incoming HTTP request
+     * @returns Response with JSON-RPC 2.0 formatted result
+     */
+    async handleMcp(request) {
+        const DOClass = this.constructor;
+        // Initialize MCP handler if not already done
+        if (!this._mcpHandler) {
+            this._mcpHandler = createMcpHandler(DOClass);
+        }
+        return this._mcpHandler(this, request, this._mcpSessions);
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // SYNC WEBSOCKET HANDLER
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Handle WebSocket sync requests for TanStack DB integration.
+     * Returns 426 Upgrade Required for non-WebSocket requests.
+     *
+     * @param request - The incoming HTTP request
+     * @returns Response (101 for WebSocket upgrade, 426 for non-WebSocket)
+     */
+    handleSyncWebSocket(request) {
+        // Check for WebSocket upgrade
+        const upgradeHeader = request.headers.get('upgrade');
+        if (upgradeHeader?.toLowerCase() !== 'websocket') {
+            return Response.json({ error: 'WebSocket upgrade required for /sync endpoint' }, {
+                status: 426,
+                headers: { 'Upgrade': 'websocket' },
+            });
+        }
+        // Create WebSocket pair
+        const pair = new WebSocketPair();
+        const [client, server] = Object.values(pair);
+        // Accept the server side
+        server.accept();
+        // Register with sync engine
+        this.syncEngine.accept(server);
+        // Return the client side to the caller
+        return new Response(null, {
+            status: 101,
+            webSocket: client,
+        });
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // HTTP HANDLER (Extended from DOTiny)
+    // ═══════════════════════════════════════════════════════════════════════════
+    async handleFetch(request) {
+        const url = new URL(request.url);
+        // Extract coordinates from CF request headers if available
+        const cf = request.cf;
+        if (cf?.latitude && cf?.longitude && !this._extractedCoordinates) {
+            const lat = parseFloat(cf.latitude);
+            const lng = parseFloat(cf.longitude);
+            if (!isNaN(lat) && !isNaN(lng)) {
+                this._extractedCoordinates = { lat, lng };
+            }
+        }
+        // Built-in routes
+        if (url.pathname === '/health') {
+            return Response.json({ status: 'ok', ns: this.ns });
+        }
+        // ═══════════════════════════════════════════════════════════════════════════
+        // ROOT ENDPOINT (/) - Cap'n Web RPC
+        // ═══════════════════════════════════════════════════════════════════════════
+        // POST / → capnweb RPC (HTTP batch)
+        // WebSocket / → capnweb RPC (persistent connection)
+        // GET / → info/discovery
+        if (url.pathname === '/') {
+            // Handle Cap'n Web RPC (POST or WebSocket upgrade)
+            if (isCapnWebRequest(request)) {
+                return this.#handleCapnWebRpc(request);
+            }
+            // GET request - return JSON-LD index with collections
+            if (request.method === 'GET') {
+                // Build REST router context for index generation
+                const restCtx = this.getRestRouterContext();
+                return handleGetIndex(restCtx, request);
+            }
+            // Other methods not supported at root
+            return new Response('Method Not Allowed', {
+                status: 405,
+                headers: { 'Allow': 'GET, POST' },
+            });
+        }
+        // Handle /$introspect endpoint for schema discovery
+        if (url.pathname === '/$introspect') {
+            return this.handleIntrospectRoute(request);
+        }
+        // Handle /mcp endpoint for MCP transport
+        if (url.pathname === '/mcp') {
+            return this.handleMcp(request);
+        }
+        // Handle /rpc endpoint for RPC protocol (JSON-RPC 2.0 + Chain RPC)
+        if (url.pathname === '/rpc') {
+            // Check for WebSocket upgrade
+            const upgradeHeader = request.headers.get('upgrade');
+            const connectionHeader = request.headers.get('connection')?.toLowerCase() || '';
+            const hasConnectionUpgrade = connectionHeader.includes('upgrade');
+            if (upgradeHeader?.toLowerCase() === 'websocket' && hasConnectionUpgrade) {
+                return this.rpcServer.handleWebSocketRpc();
+            }
+            // HTTP RPC request
+            if (request.method === 'POST') {
+                return this.rpcServer.handleRpcRequest(request);
+            }
+            // GET request - return RPC info
+            return Response.json({
+                message: 'RPC endpoint - use POST for HTTP batch mode or WebSocket for streaming',
+                methods: this.rpcServer.methods,
+            }, { headers: { 'Content-Type': 'application/json' } });
+        }
+        // Handle /sync endpoint for WebSocket sync protocol (TanStack DB)
+        if (url.pathname === '/sync') {
+            return this.handleSyncWebSocket(request);
+        }
+        // Handle /resolve endpoint for cross-DO resolution
+        if (url.pathname === '/resolve') {
+            const path = url.searchParams.get('path');
+            const ref = url.searchParams.get('ref') || 'main';
+            if (!path) {
+                return Response.json({ error: 'Missing path parameter' }, { status: 400 });
+            }
+            try {
+                const thing = await this.resolveLocal(path, ref);
+                return Response.json(thing);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : 'Resolution failed';
+                return Response.json({ error: message }, { status: 404 });
+            }
+        }
+        // Delegate to Hono app if configured
+        if (this.app) {
+            const response = await this.app.fetch(request, this.env);
+            return response;
+        }
+        // ═══════════════════════════════════════════════════════════════════════════
+        // REST API ROUTES (/:type and /:type/:id)
+        // ═══════════════════════════════════════════════════════════════════════════
+        // Handle REST routes for Things CRUD operations
+        // GET /customers → list customers
+        // GET /customers/cust-1 → get customer by id
+        // POST /customers → create customer
+        // PUT /customers/cust-1 → replace customer
+        // PATCH /customers/cust-1 → update customer (merge)
+        // DELETE /customers/cust-1 → delete customer
+        const restCtx = this.getRestRouterContext();
+        const restResponse = await handleRestRequest(request, restCtx);
+        if (restResponse) {
+            return restResponse;
+        }
+        // Default: 404 Not Found
+        return new Response('Not Found', { status: 404 });
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // CAP'N WEB RPC HANDLER
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Cap'n Web RPC options. Override in subclasses to customize.
+     */
+    get capnWebOptions() {
+        return {
+            includeStackTraces: this.env.ENVIRONMENT !== 'production',
+        };
+    }
+    /**
+     * Handle Cap'n Web RPC requests (POST or WebSocket upgrade at root endpoint).
+     *
+     * This is marked with # prefix to indicate it's internal and should not
+     * be exposed via RPC itself.
+     */
+    async #handleCapnWebRpc(request) {
+        return handleCapnWebRpc(request, this, this.capnWebOptions);
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ALARM HANDLER (for scheduled tasks)
+    // ═══════════════════════════════════════════════════════════════════════════
+    async alarm() {
+        // Delegate to schedule manager to handle scheduled tasks
+        if (this._scheduleManager) {
+            await this._scheduleManager.handleAlarm();
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // INTROSPECTION HTTP HANDLER
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Handle the /$introspect HTTP route.
+     * Requires authentication and returns the DOSchema.
+     */
+    async handleIntrospectRoute(request) {
+        // Only allow GET requests
+        if (request.method !== 'GET') {
+            return Response.json({ error: 'Method not allowed' }, { status: 405 });
+        }
+        // Check for Authorization header
+        const authHeader = request.headers.get('Authorization');
+        if (!authHeader) {
+            return Response.json({ error: 'Authentication required' }, { status: 401 });
+        }
+        // Parse JWT from Bearer token
+        if (!authHeader.startsWith('Bearer ')) {
+            return Response.json({ error: 'Invalid authorization header' }, { status: 401 });
+        }
+        const token = authHeader.slice(7);
+        // Parse and verify the JWT
+        try {
+            const parts = token.split('.');
+            if (parts.length !== 3) {
+                return Response.json({ error: 'Invalid token format' }, { status: 401 });
+            }
+            // Verify JWT signature if JWT_SECRET is configured
+            const jwtSecret = this.env.JWT_SECRET;
+            if (jwtSecret) {
+                const isValid = await this.verifyJwtSignature(token, jwtSecret);
+                if (!isValid) {
+                    return Response.json({ error: 'Invalid token signature' }, { status: 401 });
+                }
+            }
+            else {
+                // In development without JWT_SECRET, log warning but allow request
+                console.warn('JWT_SECRET not configured - skipping signature verification');
+            }
+            const payload = JSON.parse(atob(parts[1]));
+            // Check expiration
+            const now = Math.floor(Date.now() / 1000);
+            if (payload.exp && payload.exp < now) {
+                return Response.json({ error: 'Token expired' }, { status: 401 });
+            }
+            // Build auth context from JWT claims
+            const authContext = {
+                authenticated: true,
+                user: {
+                    id: payload.sub || 'anonymous',
+                    email: payload.email,
+                    name: payload.name,
+                    roles: payload.roles || [],
+                    permissions: payload.permissions || [],
+                },
+                token: {
+                    type: 'jwt',
+                    expiresAt: payload.exp ? new Date(payload.exp * 1000) : new Date(Date.now() + 3600000),
+                },
+            };
+            // Call $introspect with auth context
+            const schema = await this.$introspect(authContext);
+            return Response.json(schema);
+        }
+        catch (error) {
+            return Response.json({ error: 'Invalid token' }, { status: 401 });
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // INTROSPECTION ($introspect)
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Introspect the DO schema, filtered by user role.
+     *
+     * Returns information about:
+     * - Available classes and their methods
+     * - MCP tools from static $mcp config
+     * - REST endpoints from static $rest config
+     * - Available stores (filtered by role)
+     * - Storage capabilities (filtered by role)
+     * - Registered nouns and verbs
+     *
+     * @param authContext - Optional auth context for role-based filtering
+     * @returns DOSchema object with introspection data
+     */
+    async $introspect(authContext) {
+        // Determine role from auth context
+        const role = this.determineRole(authContext);
+        const scopes = authContext?.user?.permissions || [];
+        // Build the schema response
+        const schema = {
+            ns: this.ns,
+            permissions: {
+                role,
+                scopes,
+            },
+            classes: this.introspectClasses(role),
+            nouns: await this.introspectNouns(),
+            verbs: await this.introspectVerbs(),
+            stores: this.introspectStores(role),
+            storage: this.introspectStorage(role),
+        };
+        return schema;
+    }
+    /**
+     * Determine the effective role from auth context
+     */
+    determineRole(authContext) {
+        if (!authContext || !authContext.authenticated) {
+            return 'public';
+        }
+        const roles = authContext.user?.roles || [];
+        if (roles.length === 0) {
+            // Authenticated but no specific roles - default to 'user'
+            return 'user';
+        }
+        return getHighestRole(roles);
+    }
+    /**
+     * Introspect available classes
+     */
+    introspectClasses(role) {
+        const classes = [];
+        // Get class info from constructor
+        const DOClass = this.constructor;
+        const className = DOClass.$type || this.constructor.name;
+        // Determine class visibility based on config
+        // Default to 'user' visibility for the class itself
+        const classVisibility = 'user';
+        // Only include class if caller can access it
+        if (!canAccessVisibility(role, classVisibility)) {
+            return classes;
+        }
+        // Build tools list from $mcp config, filtered by role
+        const tools = [];
+        if (DOClass.$mcp?.tools) {
+            for (const [name, config] of Object.entries(DOClass.$mcp.tools)) {
+                const toolVisibility = config.visibility || 'user';
+                if (canAccessVisibility(role, toolVisibility)) {
+                    tools.push({
+                        name,
+                        description: config.description,
+                        inputSchema: config.inputSchema,
+                    });
+                }
+            }
+        }
+        // Build endpoints list from $rest config, filtered by role
+        const endpoints = [];
+        if (DOClass.$rest?.endpoints) {
+            for (const endpoint of DOClass.$rest.endpoints) {
+                const endpointVisibility = endpoint.visibility || 'user';
+                if (canAccessVisibility(role, endpointVisibility)) {
+                    endpoints.push({
+                        method: endpoint.method,
+                        path: endpoint.path,
+                        description: endpoint.description,
+                    });
+                }
+            }
+        }
+        // Build class schema
+        classes.push({
+            name: className,
+            type: 'thing', // Default to 'thing', could be 'collection' for collection DOs
+            pattern: `/:type/:id`,
+            visibility: classVisibility,
+            tools,
+            endpoints,
+            properties: [], // Could be populated from static schema
+            actions: [], // Could be populated from method decorators
+        });
+        return classes;
+    }
+    /**
+     * Introspect available stores, filtered by role
+     */
+    introspectStores(role) {
+        const stores = [];
+        const storeDefinitions = [
+            { name: 'things', type: 'things' },
+            { name: 'relationships', type: 'relationships' },
+            { name: 'actions', type: 'actions' },
+            { name: 'events', type: 'events' },
+            { name: 'search', type: 'search' },
+            { name: 'objects', type: 'objects' },
+            { name: 'dlq', type: 'dlq' },
+        ];
+        for (const store of storeDefinitions) {
+            const storeVisibility = STORE_VISIBILITY[store.type];
+            if (canAccessVisibility(role, storeVisibility)) {
+                stores.push({
+                    name: store.name,
+                    type: store.type,
+                    visibility: storeVisibility,
+                });
+            }
+        }
+        return stores;
+    }
+    /**
+     * Introspect storage capabilities, filtered by role
+     */
+    introspectStorage(role) {
+        // Capability visibility levels:
+        // - fsx, gitx: user and above
+        // - bashx, r2, sql: admin and above
+        // - iceberg, edgevec: system only
+        const isUser = canAccessVisibility(role, 'user');
+        const isAdmin = canAccessVisibility(role, 'admin');
+        const isSystem = canAccessVisibility(role, 'system');
+        return {
+            fsx: isUser,
+            gitx: isUser,
+            bashx: isAdmin,
+            r2: {
+                enabled: isAdmin,
+                buckets: isAdmin ? [] : undefined, // Would list actual buckets from env
+            },
+            sql: {
+                enabled: isAdmin,
+                tables: isAdmin ? [] : undefined, // Would list actual tables from schema
+            },
+            iceberg: isSystem,
+            edgevec: isSystem,
+        };
+    }
+    /**
+     * Introspect registered nouns
+     */
+    async introspectNouns() {
+        // Query nouns from the database (simplified for now)
+        // In full implementation, would query from db.nouns table
+        return [];
+    }
+    /**
+     * Introspect registered verbs
+     */
+    async introspectVerbs() {
+        // TODO: Query verbs from the database
+        // In full implementation, would query from db.verbs table
+        return [];
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // JWT VERIFICATION HELPERS
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Verify JWT signature using HMAC-SHA256.
+     *
+     * @param token - The full JWT token string
+     * @param secret - The secret key for verification
+     * @returns true if signature is valid, false otherwise
+     */
+    async verifyJwtSignature(token, secret) {
+        try {
+            const parts = token.split('.');
+            if (parts.length !== 3)
+                return false;
+            const signatureInput = `${parts[0]}.${parts[1]}`;
+            const signature = parts[2];
+            const encoder = new TextEncoder();
+            const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+            // Base64url decode the signature
+            const signatureBytes = this.base64UrlDecode(signature);
+            return await crypto.subtle.verify('HMAC', key, signatureBytes, encoder.encode(signatureInput));
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Decode a base64url-encoded string to Uint8Array.
+     */
+    base64UrlDecode(str) {
+        // Replace base64url chars with base64 chars
+        let base64 = str.replace(/-/g, '+').replace(/_/g, '/');
+        // Pad with '=' to make it valid base64
+        while (base64.length % 4) {
+            base64 += '=';
+        }
+        const binary = atob(base64);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++) {
+            bytes[i] = binary.charCodeAt(i);
+        }
+        return bytes;
+    }
+}
+export default DO;
+//# sourceMappingURL=DOBase.js.map