@stoneforge/quarry 0.1.0

package/dist/api/types.d.ts

@@ -0,0 +1,1359 @@
+/**
+ * Query API Type Definitions
+ *
+ * This module defines all types, interfaces, and filters for the Stoneforge Query API.
+ * The Query API provides the primary programmatic interface to Stoneforge, enabling
+ * CRUD operations, queries, dependency management, and system administration.
+ */
+import type { Element, ElementId, ElementType, EntityId, Timestamp, Task, TaskStatus, Priority, Complexity, TaskTypeValue, CreateTaskInput, Document, DocumentId, ContentType, DocumentCategory, DocumentStatus, Dependency, DependencyType, Event, EventFilter, PlanProgress, Message, MessageId, ChannelId, Team, WorkflowStatus } from '@stoneforge/core';
+import type { EmbeddingService } from '../services/embeddings/service.js';
+export type { PlanProgress };
+/**
+ * Sort direction for query results
+ */
+export type SortDirection = 'asc' | 'desc';
+/**
+ * Base pagination options for list queries
+ */
+export interface PaginationOptions {
+    /** Maximum number of results to return */
+    limit?: number;
+    /** Number of results to skip */
+    offset?: number;
+}
+/**
+ * Base sorting options for list queries
+ */
+export interface SortOptions {
+    /** Field to sort by */
+    orderBy?: string;
+    /** Sort direction */
+    orderDir?: SortDirection;
+}
+/**
+ * Base filter for all element queries.
+ * All filters are optional and are combined with AND logic.
+ */
+export interface ElementFilter extends PaginationOptions, SortOptions {
+    /** Filter by element type(s) */
+    type?: ElementType | ElementType[];
+    /** Must have ALL specified tags */
+    tags?: string[];
+    /** Must have ANY of the specified tags */
+    tagsAny?: string[];
+    /** Filter by creator */
+    createdBy?: EntityId;
+    /** Created after this timestamp (inclusive) */
+    createdAfter?: Timestamp;
+    /** Created before this timestamp (exclusive) */
+    createdBefore?: Timestamp;
+    /** Updated after this timestamp (inclusive) */
+    updatedAfter?: Timestamp;
+    /** Updated before this timestamp (exclusive) */
+    updatedBefore?: Timestamp;
+    /** Include soft-deleted elements (tombstones) */
+    includeDeleted?: boolean;
+    /** Hydration options for resolving document references */
+    hydrate?: HydrationOptions;
+}
+/**
+ * Extended filter for task queries.
+ * Includes all ElementFilter options plus task-specific filters.
+ */
+export interface TaskFilter extends ElementFilter {
+    /** Filter by status(es) */
+    status?: TaskStatus | TaskStatus[];
+    /** Filter by priority level(s) */
+    priority?: Priority | Priority[];
+    /** Filter by complexity level(s) */
+    complexity?: Complexity | Complexity[];
+    /** Filter by assignee */
+    assignee?: EntityId;
+    /** Filter by owner */
+    owner?: EntityId;
+    /** Filter by task type classification(s) */
+    taskType?: TaskTypeValue | TaskTypeValue[];
+    /** Filter tasks that have a deadline set */
+    hasDeadline?: boolean;
+    /** Filter tasks with deadline before this timestamp */
+    deadlineBefore?: Timestamp;
+    /**
+     * Include tasks belonging to ephemeral workflows.
+     * By default, tasks from ephemeral workflows are excluded from ready() queries.
+     */
+    includeEphemeral?: boolean;
+}
+/**
+ * Extended filter for document queries.
+ * Includes all ElementFilter options plus document-specific filters.
+ */
+export interface DocumentFilter extends ElementFilter {
+    /** Filter by content type(s) */
+    contentType?: ContentType | ContentType[];
+    /** Filter by exact version number */
+    version?: number;
+    /** Filter by minimum version (inclusive) */
+    minVersion?: number;
+    /** Filter by maximum version (inclusive) */
+    maxVersion?: number;
+    /** Filter by document category(ies) */
+    category?: DocumentCategory | DocumentCategory[];
+    /** Filter by document status(es) */
+    status?: DocumentStatus | DocumentStatus[];
+}
+/**
+ * Options for FTS5 full-text search.
+ */
+export interface FTSSearchOptions {
+    /** Filter by document category(ies) */
+    category?: DocumentCategory | DocumentCategory[];
+    /** Filter by document status(es) (default: active only) */
+    status?: DocumentStatus | DocumentStatus[];
+    /** Hard cap on results before adaptive filtering. Default: 50 */
+    hardCap?: number;
+    /** Sensitivity for elbow detection (higher = more aggressive cutoff). Default: 1.5 */
+    elbowSensitivity?: number;
+    /** Minimum results to return. Default: 1 */
+    minResults?: number;
+}
+/**
+ * A single FTS search result with score and snippet.
+ */
+export interface FTSSearchResult {
+    /** The matched document */
+    document: Document;
+    /** BM25 relevance score (lower = more relevant in SQLite FTS5) */
+    score: number;
+    /** Highlighted snippet from content */
+    snippet: string;
+}
+/**
+ * Extended filter for message queries.
+ * Includes all ElementFilter options plus message-specific filters.
+ */
+export interface MessageFilter extends ElementFilter {
+    /** Filter by channel(s) */
+    channelId?: ChannelId | ChannelId[];
+    /** Filter by sender entity(ies) */
+    sender?: EntityId | EntityId[];
+    /** Filter by thread (null for root messages only, specific ID for thread replies) */
+    threadId?: MessageId | null;
+    /** Filter by presence of attachments */
+    hasAttachments?: boolean;
+}
+/**
+ * Options for hydrating document references on elements.
+ * When enabled, the corresponding Ref field will be resolved
+ * and its content will be included in the hydrated result.
+ */
+export interface HydrationOptions {
+    /** Hydrate descriptionRef -> description */
+    description?: boolean;
+    /** Hydrate contentRef -> content */
+    content?: boolean;
+    /** Hydrate attachment references */
+    attachments?: boolean;
+}
+/**
+ * Options for get operations
+ */
+export interface GetOptions {
+    /** References to hydrate */
+    hydrate?: HydrationOptions;
+}
+/**
+ * A task that is blocked with details about why.
+ * Extends Task with blocking information.
+ */
+export interface BlockedTask extends Task {
+    /** ID of the element blocking this task */
+    blockedBy: ElementId;
+    /** Human-readable explanation of why this task is blocked */
+    blockReason: string;
+}
+/**
+ * Result of recording an approval
+ */
+export interface ApprovalResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Current number of approvals */
+    currentCount: number;
+    /** Required number of approvals */
+    requiredCount: number;
+    /** Whether the gate is now satisfied */
+    satisfied: boolean;
+}
+/**
+ * A node in the dependency tree.
+ * Represents an element with its incoming and outgoing dependencies.
+ */
+export interface DependencyTreeNode<T extends Element = Element> {
+    /** The element at this node */
+    element: T;
+    /** Outgoing dependencies (elements this element depends on) */
+    dependencies: DependencyTreeNode[];
+    /** Incoming dependencies (elements that depend on this element) */
+    dependents: DependencyTreeNode[];
+}
+/**
+ * Complete dependency tree for an element.
+ * Contains the full graph of dependencies in both directions.
+ */
+export interface DependencyTree<T extends Element = Element> {
+    /** Root element of the tree */
+    root: DependencyTreeNode<T>;
+    /** Maximum depth traversed in dependencies direction */
+    dependencyDepth: number;
+    /** Maximum depth traversed in dependents direction */
+    dependentDepth: number;
+    /** Total number of nodes in the tree */
+    nodeCount: number;
+}
+/**
+ * Input for creating a new dependency via the API.
+ */
+export interface DependencyInput {
+    /** Element that is waiting/blocked */
+    blockedId: ElementId;
+    /** Element doing the blocking/being depended on */
+    blockerId: ElementId;
+    /** Type of dependency relationship */
+    type: DependencyType;
+    /** Type-specific metadata */
+    metadata?: Record<string, unknown>;
+    /** Actor creating the dependency (optional, falls back to blocked element's createdBy) */
+    actor?: EntityId;
+}
+/**
+ * Options for operations that support actor specification
+ */
+export interface OperationOptions {
+    /** Actor performing the operation (for audit trail) */
+    actor?: EntityId;
+}
+/**
+ * Options for update operations
+ */
+export interface UpdateOptions extends OperationOptions {
+    /**
+     * Expected updatedAt timestamp for optimistic concurrency control.
+     * If provided, the update will fail with CONFLICT error if the element's
+     * current updatedAt doesn't match this value, indicating another process
+     * modified the element since it was read.
+     */
+    expectedUpdatedAt?: string;
+}
+/**
+ * Options for delete operations
+ */
+export interface DeleteOptions extends OperationOptions {
+    /** Reason for deletion (stored in audit trail) */
+    reason?: string;
+}
+/**
+ * Options for adding a task to a plan
+ */
+export interface AddTaskToPlanOptions extends OperationOptions {
+    /** Use hierarchical ID (el-planid.n) - only valid for newly created tasks */
+    useHierarchicalId?: boolean;
+}
+/**
+ * Options for creating a task within a plan
+ */
+export interface CreateTaskInPlanOptions extends OperationOptions {
+    /** Use hierarchical ID (el-planid.n) - default true */
+    useHierarchicalId?: boolean;
+}
+/**
+ * Options for bulk close operation
+ */
+export interface BulkCloseOptions extends OperationOptions {
+    /** Reason for closing all tasks */
+    closeReason?: string;
+    /** Only close tasks matching this filter */
+    filter?: TaskFilter;
+}
+/**
+ * Options for bulk defer operation
+ */
+export interface BulkDeferOptions extends OperationOptions {
+    /** Only defer tasks matching this filter */
+    filter?: TaskFilter;
+}
+/**
+ * Options for bulk reassign operation
+ */
+export interface BulkReassignOptions extends OperationOptions {
+    /** Only reassign tasks matching this filter */
+    filter?: TaskFilter;
+}
+/**
+ * Options for bulk tag operation
+ */
+export interface BulkTagOptions extends OperationOptions {
+    /** Tags to add to all tasks */
+    addTags?: string[];
+    /** Tags to remove from all tasks */
+    removeTags?: string[];
+    /** Only tag tasks matching this filter */
+    filter?: TaskFilter;
+}
+/**
+ * Result of a bulk operation on plan tasks
+ */
+export interface BulkOperationResult {
+    /** Number of tasks successfully updated */
+    updated: number;
+    /** Number of tasks skipped (didn't match filter or status) */
+    skipped: number;
+    /** IDs of tasks that were updated */
+    updatedIds: ElementId[];
+    /** IDs of tasks that were skipped */
+    skippedIds: ElementId[];
+    /** Errors encountered during the operation */
+    errors: Array<{
+        taskId: ElementId;
+        message: string;
+    }>;
+}
+/**
+ * Options for deleting a workflow
+ */
+export interface DeleteWorkflowOptions {
+    /** Actor performing the delete operation */
+    actor?: EntityId;
+}
+/**
+ * Result of deleting a workflow
+ */
+export interface DeleteWorkflowResult {
+    /** ID of the workflow that was deleted */
+    workflowId: ElementId;
+    /** Number of tasks that were deleted */
+    tasksDeleted: number;
+    /** Number of dependencies that were deleted */
+    dependenciesDeleted: number;
+    /** Whether the workflow was ephemeral */
+    wasEphemeral: boolean;
+}
+/**
+ * Options for garbage collection
+ */
+export interface GarbageCollectionOptions {
+    /** Maximum age in milliseconds for workflows to be eligible */
+    maxAgeMs: number;
+    /** Whether to run in dry-run mode (no actual deletion) */
+    dryRun?: boolean;
+    /** Maximum number of workflows to delete in one run */
+    limit?: number;
+}
+/**
+ * Result of garbage collection
+ */
+export interface GarbageCollectionResult {
+    /** Number of workflows that were deleted */
+    workflowsDeleted: number;
+    /** Number of tasks that were deleted */
+    tasksDeleted: number;
+    /** Number of dependencies that were deleted */
+    dependenciesDeleted: number;
+    /** IDs of workflows that were deleted */
+    deletedWorkflowIds: ElementId[];
+}
+/**
+ * Options for task garbage collection
+ */
+export interface TaskGarbageCollectionOptions {
+    /** Maximum age in milliseconds for tasks to be eligible (since closedAt/deletedAt) */
+    maxAgeMs: number;
+    /** Whether to run in dry-run mode (no actual deletion) */
+    dryRun?: boolean;
+    /** Maximum number of tasks to delete in one run */
+    limit?: number;
+}
+/**
+ * Result of task garbage collection
+ */
+export interface TaskGarbageCollectionResult {
+    /** Number of tasks that were deleted */
+    tasksDeleted: number;
+    /** Number of dependencies that were deleted */
+    dependenciesDeleted: number;
+    /** IDs of tasks that were deleted */
+    deletedTaskIds: ElementId[];
+}
+/**
+ * Extended filter for workflow queries.
+ * Includes all ElementFilter options plus workflow-specific filters.
+ */
+export interface WorkflowFilter extends ElementFilter {
+    /** Filter by status(es) */
+    status?: WorkflowStatus | WorkflowStatus[];
+    /** Filter by ephemeral state */
+    ephemeral?: boolean;
+    /** Filter by playbook ID */
+    playbookId?: string;
+}
+/**
+ * Progress metrics for a workflow
+ */
+export interface WorkflowProgress {
+    /** Workflow identifier */
+    workflowId: ElementId;
+    /** Total number of tasks in the workflow */
+    totalTasks: number;
+    /** Task counts by status */
+    statusCounts: Record<string, number>;
+    /** Completion percentage (0-100) */
+    completionPercentage: number;
+    /** Number of ready tasks */
+    readyTasks: number;
+    /** Number of blocked tasks */
+    blockedTasks: number;
+}
+/**
+ * Export format options
+ */
+export type ExportFormat = 'jsonl';
+/**
+ * Options for exporting elements
+ */
+export interface ExportOptions {
+    /** Export format (default: jsonl) */
+    format?: ExportFormat;
+    /** Element types to export (default: all) */
+    types?: ElementType[];
+    /** Export only elements modified after this timestamp */
+    modifiedAfter?: Timestamp;
+    /** Include soft-deleted elements */
+    includeDeleted?: boolean;
+    /** Export dependencies */
+    includeDependencies?: boolean;
+    /** Export events */
+    includeEvents?: boolean;
+    /** Output file path (if not provided, returns string) */
+    outputPath?: string;
+}
+/**
+ * Options for importing elements
+ */
+export interface ImportOptions {
+    /** Input file path */
+    inputPath?: string;
+    /** Raw JSONL data (alternative to inputPath) */
+    data?: string;
+    /** How to handle conflicts */
+    conflictStrategy?: ConflictStrategy;
+    /** Whether to validate all data before importing */
+    validateFirst?: boolean;
+    /** Whether to run in dry-run mode (validate but don't import) */
+    dryRun?: boolean;
+}
+/**
+ * Strategy for handling import conflicts
+ */
+export type ConflictStrategy = 'skip' | 'overwrite' | 'error';
+/**
+ * A conflict encountered during import
+ */
+export interface ImportConflict {
+    /** ID of the conflicting element */
+    elementId: ElementId;
+    /** Type of conflict */
+    conflictType: 'exists' | 'type_mismatch' | 'validation_failed';
+    /** Additional details about the conflict */
+    details: string;
+}
+/**
+ * Result of an import operation
+ */
+export interface ImportResult {
+    /** Whether the import succeeded */
+    success: boolean;
+    /** Number of elements imported */
+    elementsImported: number;
+    /** Number of dependencies imported */
+    dependenciesImported: number;
+    /** Number of events imported */
+    eventsImported: number;
+    /** Conflicts encountered */
+    conflicts: ImportConflict[];
+    /** Errors that occurred */
+    errors: string[];
+    /** Whether this was a dry run */
+    dryRun: boolean;
+}
+/**
+ * Count of elements by type
+ */
+export type ElementCountByType = {
+    [K in ElementType]?: number;
+};
+/**
+ * System-wide statistics
+ */
+export interface SystemStats {
+    /** Total number of elements */
+    totalElements: number;
+    /** Element count broken down by type */
+    elementsByType: ElementCountByType;
+    /** Total number of dependencies */
+    totalDependencies: number;
+    /** Total number of events */
+    totalEvents: number;
+    /** Number of tasks in ready state (open/in_progress, not blocked) */
+    readyTasks: number;
+    /** Number of blocked tasks */
+    blockedTasks: number;
+    /** Database file size in bytes */
+    databaseSize: number;
+    /** When stats were computed */
+    computedAt: Timestamp;
+}
+/**
+ * Paginated list result
+ */
+export interface ListResult<T> {
+    /** Items in this page */
+    items: T[];
+    /** Total count of matching items (before pagination) */
+    total: number;
+    /** Offset used for this page */
+    offset: number;
+    /** Limit used for this page */
+    limit: number;
+    /** Whether there are more results */
+    hasMore: boolean;
+}
+/**
+ * Result of point-in-time state reconstruction.
+ */
+export interface ReconstructedState<T extends Element = Element> {
+    /** The reconstructed element state at the target timestamp */
+    element: T;
+    /** The timestamp at which the state was reconstructed */
+    asOf: Timestamp;
+    /** Number of events applied to reconstruct this state */
+    eventsApplied: number;
+    /** Whether the element existed at this timestamp */
+    exists: boolean;
+}
+/**
+ * A snapshot in an element's history timeline.
+ */
+export interface TimelineSnapshot {
+    /** The event that caused this state change */
+    event: Event;
+    /** The element state after this event was applied */
+    state: Record<string, unknown> | null;
+    /** Human-readable description of the change */
+    summary: string;
+}
+/**
+ * Complete timeline of an element's history.
+ */
+export interface ElementTimeline {
+    /** The element ID */
+    elementId: ElementId;
+    /** The current state (or null if deleted) */
+    currentState: Element | null;
+    /** Timeline of all state changes (oldest first) */
+    snapshots: TimelineSnapshot[];
+    /** Total number of events in the element's history */
+    totalEvents: number;
+}
+/**
+ * Base input for creating any element.
+ * Type-specific create functions will extend this.
+ */
+export interface ElementInput {
+    /** Optional: Specific ID (if not provided, one will be generated) */
+    id?: ElementId;
+    /** Entity creating the element */
+    createdBy: EntityId;
+    /** Initial tags */
+    tags?: string[];
+    /** Initial metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * The main Stoneforge API interface.
+ *
+ * Provides type-safe CRUD operations, queries, dependency management,
+ * and system administration capabilities.
+ *
+ * @example
+ * ```typescript
+ * const api = createQuarryAPI(storage);
+ *
+ * // Get a task by ID
+ * const task = await api.get<Task>(taskId);
+ *
+ * // List open tasks
+ * const tasks = await api.list<Task>({ type: 'task', status: 'open' });
+ *
+ * // Get ready tasks
+ * const ready = await api.ready({ assignee: myEntityId });
+ * ```
+ */
+export interface QuarryAPI {
+    /**
+     * Retrieve a single element by ID.
+     *
+     * @param id - Element identifier
+     * @param options - Hydration options
+     * @returns The element or null if not found
+     */
+    get<T extends Element>(id: ElementId, options?: GetOptions): Promise<T | null>;
+    /**
+     * Retrieve multiple elements matching a filter.
+     *
+     * @param filter - Query constraints
+     * @returns Array of matching elements
+     */
+    list<T extends Element>(filter?: ElementFilter): Promise<T[]>;
+    /**
+     * Retrieve multiple elements with pagination info.
+     *
+     * @param filter - Query constraints
+     * @returns Paginated result with items and metadata
+     */
+    listPaginated<T extends Element>(filter?: ElementFilter): Promise<ListResult<T>>;
+    /**
+     * Create a new element.
+     *
+     * @param input - Element data (type-specific)
+     * @returns The created element
+     */
+    create<T extends Element>(input: ElementInput & Record<string, unknown>): Promise<T>;
+    /**
+     * Update an existing element.
+     *
+     * @param id - Element identifier
+     * @param updates - Fields to update
+     * @param options - Operation options including actor
+     * @returns The updated element
+     * @throws NotFoundError if element doesn't exist
+     * @throws ConstraintError if element is immutable (e.g., Message)
+     */
+    update<T extends Element>(id: ElementId, updates: Partial<T>, options?: UpdateOptions): Promise<T>;
+    /**
+     * Soft-delete an element.
+     *
+     * @param id - Element identifier
+     * @param options - Delete options including reason and actor
+     * @throws NotFoundError if element doesn't exist
+     * @throws ConstraintError if element is immutable
+     */
+    delete(id: ElementId, options?: DeleteOptions): Promise<void>;
+    /**
+     * Look up an entity by name.
+     *
+     * @param name - Entity name to look up
+     * @returns The entity if found, null otherwise
+     */
+    lookupEntityByName(name: string): Promise<Element | null>;
+    /**
+     * Sets the manager (reportsTo) for an entity.
+     *
+     * @param entityId - The entity to set the manager for
+     * @param managerId - The manager entity ID
+     * @param actor - Entity performing this action (for audit trail)
+     * @returns The updated entity
+     * @throws NotFoundError if entity or manager doesn't exist
+     * @throws ValidationError if self-reference or manager is deactivated
+     * @throws ConflictError if circular chain would be created
+     */
+    setEntityManager(entityId: EntityId, managerId: EntityId, actor: EntityId): Promise<Element>;
+    /**
+     * Clears the manager (reportsTo) for an entity.
+     *
+     * @param entityId - The entity to clear the manager for
+     * @param actor - Entity performing this action (for audit trail)
+     * @returns The updated entity
+     * @throws NotFoundError if entity doesn't exist
+     */
+    clearEntityManager(entityId: EntityId, actor: EntityId): Promise<Element>;
+    /**
+     * Gets all entities that report directly to a manager.
+     *
+     * @param managerId - The manager entity ID
+     * @returns Array of entities that report to the manager
+     */
+    getDirectReports(managerId: EntityId): Promise<Element[]>;
+    /**
+     * Gets the management chain for an entity (from entity up to root).
+     *
+     * @param entityId - The entity to get the management chain for
+     * @returns Array of entities in the management chain (empty if no manager)
+     * @throws NotFoundError if entity doesn't exist
+     */
+    getManagementChain(entityId: EntityId): Promise<Element[]>;
+    /**
+     * Add an existing task to a plan.
+     * Creates a parent-child dependency from the task to the plan.
+     *
+     * @param taskId - The task to add
+     * @param planId - The plan to add the task to
+     * @param options - Operation options
+     * @returns The created dependency
+     * @throws NotFoundError if task or plan doesn't exist
+     * @throws ConstraintError if task is already in a plan
+     */
+    addTaskToPlan(taskId: ElementId, planId: ElementId, options?: AddTaskToPlanOptions): Promise<Dependency>;
+    /**
+     * Remove a task from a plan.
+     * Removes the parent-child dependency.
+     *
+     * @param taskId - The task to remove
+     * @param planId - The plan to remove the task from
+     * @param actor - Optional actor for audit trail
+     * @throws NotFoundError if task-plan relationship doesn't exist
+     */
+    removeTaskFromPlan(taskId: ElementId, planId: ElementId, actor?: EntityId): Promise<void>;
+    /**
+     * Get all tasks in a plan.
+     * Returns tasks with parent-child dependency to the plan.
+     *
+     * @param planId - The plan ID
+     * @param filter - Optional task filter constraints
+     * @returns Array of tasks in the plan
+     * @throws NotFoundError if plan doesn't exist
+     */
+    getTasksInPlan(planId: ElementId, filter?: TaskFilter): Promise<Task[]>;
+    /**
+     * Get progress metrics for a plan.
+     * Computes task status counts and completion percentage.
+     *
+     * @param planId - The plan ID
+     * @returns Progress metrics for the plan
+     * @throws NotFoundError if plan doesn't exist
+     */
+    getPlanProgress(planId: ElementId): Promise<PlanProgress>;
+    /**
+     * Create a new task directly in a plan.
+     * Automatically creates the task with a hierarchical ID and parent-child dependency.
+     *
+     * @param planId - The plan to create the task in
+     * @param taskInput - Task creation input (without ID - it will be generated)
+     * @param options - Operation options
+     * @returns The created task with hierarchical ID
+     * @throws NotFoundError if plan doesn't exist
+     * @throws ConstraintError if plan is not in draft or active status
+     */
+    createTaskInPlan<T extends Task = Task>(planId: ElementId, taskInput: Omit<CreateTaskInput, 'id'>, options?: CreateTaskInPlanOptions): Promise<T>;
+    /**
+     * Close all tasks in a plan.
+     * Only closes tasks that are not already closed or tombstoned.
+     *
+     * @param planId - The plan containing the tasks
+     * @param options - Bulk operation options including optional filter and close reason
+     * @returns Result with counts of updated/skipped tasks
+     * @throws NotFoundError if plan doesn't exist
+     */
+    bulkClosePlanTasks(planId: ElementId, options?: BulkCloseOptions): Promise<BulkOperationResult>;
+    /**
+     * Defer all tasks in a plan.
+     * Only defers tasks that are in open, in_progress, or blocked status.
+     *
+     * @param planId - The plan containing the tasks
+     * @param options - Bulk operation options including optional filter
+     * @returns Result with counts of updated/skipped tasks
+     * @throws NotFoundError if plan doesn't exist
+     */
+    bulkDeferPlanTasks(planId: ElementId, options?: BulkDeferOptions): Promise<BulkOperationResult>;
+    /**
+     * Reassign all tasks in a plan to a new entity.
+     *
+     * @param planId - The plan containing the tasks
+     * @param newAssignee - The entity to assign all tasks to (undefined to unassign)
+     * @param options - Bulk operation options including optional filter
+     * @returns Result with counts of updated/skipped tasks
+     * @throws NotFoundError if plan doesn't exist
+     */
+    bulkReassignPlanTasks(planId: ElementId, newAssignee: EntityId | undefined, options?: BulkReassignOptions): Promise<BulkOperationResult>;
+    /**
+     * Add or remove tags from all tasks in a plan.
+     *
+     * @param planId - The plan containing the tasks
+     * @param options - Options including tags to add/remove and optional filter
+     * @returns Result with counts of updated/skipped tasks
+     * @throws NotFoundError if plan doesn't exist
+     */
+    bulkTagPlanTasks(planId: ElementId, options: BulkTagOptions): Promise<BulkOperationResult>;
+    /**
+     * Get tasks that are ready for work.
+     *
+     * Ready criteria:
+     * - Status is 'open' or 'in_progress'
+     * - Not blocked by any dependency
+     * - scheduledFor is null or in the past
+     * - Not ephemeral (unless includeEphemeral is true)
+     *
+     * @param filter - Optional task filter constraints
+     * @returns Array of ready tasks
+     */
+    ready(filter?: TaskFilter): Promise<Task[]>;
+    /**
+     * Get tasks in backlog (not ready for work, needs triage)
+     *
+     * @param filter - Optional task filter constraints
+     * @returns Array of backlog tasks
+     */
+    backlog(filter?: TaskFilter): Promise<Task[]>;
+    /**
+     * Get blocked tasks with blocking details.
+     *
+     * @param filter - Optional task filter constraints
+     * @returns Array of blocked tasks with block reasons
+     */
+    blocked(filter?: TaskFilter): Promise<BlockedTask[]>;
+    /**
+     * Create a new dependency between elements.
+     *
+     * @param dep - Dependency data
+     * @returns The created dependency
+     * @throws NotFoundError if source element doesn't exist
+     * @throws ConflictError if dependency would create a cycle
+     * @throws ConflictError if dependency already exists
+     */
+    addDependency(dep: DependencyInput): Promise<Dependency>;
+    /**
+     * Remove a dependency.
+     *
+     * @param blockedId - Blocked element
+     * @param blockerId - Blocker element
+     * @param type - Dependency type
+     * @param actor - Optional actor for the event (defaults to dependency creator)
+     * @throws NotFoundError if dependency doesn't exist
+     */
+    removeDependency(blockedId: ElementId, blockerId: ElementId, type: DependencyType, actor?: EntityId): Promise<void>;
+    /**
+     * Get dependencies of an element (outgoing edges).
+     *
+     * @param id - Element ID
+     * @param types - Optional filter by dependency type(s)
+     * @returns Array of dependencies
+     */
+    getDependencies(id: ElementId, types?: DependencyType[]): Promise<Dependency[]>;
+    /**
+     * Get dependents of an element (incoming edges).
+     *
+     * @param id - Element ID
+     * @param types - Optional filter by dependency type(s)
+     * @returns Array of dependencies where this element is the target
+     */
+    getDependents(id: ElementId, types?: DependencyType[]): Promise<Dependency[]>;
+    /**
+     * Get the full dependency tree for an element.
+     *
+     * @param id - Root element ID
+     * @returns Complete dependency tree in both directions
+     */
+    getDependencyTree(id: ElementId): Promise<DependencyTree>;
+    /**
+     * Mark an external or webhook gate as satisfied.
+     * Used to indicate that an external system or webhook has completed.
+     *
+     * @param blockedId - Element that has the awaits dependency
+     * @param blockerId - Blocker element ID of the awaits dependency
+     * @param actor - Entity marking the gate as satisfied
+     * @returns True if gate was found and satisfied, false if not found or wrong type
+     */
+    satisfyGate(blockedId: ElementId, blockerId: ElementId, actor: EntityId): Promise<boolean>;
+    /**
+     * Record an approval for an approval gate.
+     * Updates the dependency metadata with the new approver.
+     *
+     * @param blockedId - Element that has the awaits dependency
+     * @param blockerId - Blocker element ID of the awaits dependency
+     * @param approver - Entity recording their approval
+     * @returns Result indicating success and current approval status
+     */
+    recordApproval(blockedId: ElementId, blockerId: ElementId, approver: EntityId): Promise<ApprovalResult>;
+    /**
+     * Remove an approval from an approval gate.
+     *
+     * @param blockedId - Element that has the awaits dependency
+     * @param blockerId - Blocker element ID of the awaits dependency
+     * @param approver - Entity removing their approval
+     * @returns Result indicating success and current approval status
+     */
+    removeApproval(blockedId: ElementId, blockerId: ElementId, approver: EntityId): Promise<ApprovalResult>;
+    /**
+     * Full-text search across elements.
+     *
+     * Searches:
+     * - Element titles (Tasks, Plans, etc.)
+     * - Element content (via Documents)
+     * - Tags
+     *
+     * @param query - Search text
+     * @param filter - Additional filter constraints
+     * @returns Array of matching elements
+     */
+    search(query: string, filter?: ElementFilter): Promise<Element[]>;
+    /**
+     * Full-text search documents using FTS5 with adaptive top-K.
+     *
+     * Uses the FTS5 virtual table for BM25-ranked search with snippet generation.
+     * Applies adaptive elbow detection to return a natural number of results.
+     *
+     * @param query - Search query text
+     * @param options - Search options (category, status, limits, sensitivity)
+     * @returns Array of search results with scores and snippets
+     */
+    searchDocumentsFTS(query: string, options?: FTSSearchOptions): Promise<FTSSearchResult[]>;
+    /**
+     * Archive a document (sets status to 'archived').
+     *
+     * @param id - Document ID
+     * @returns The updated document
+     * @throws NotFoundError if document doesn't exist or element is not a document
+     */
+    archiveDocument(id: ElementId): Promise<Document>;
+    /**
+     * Unarchive a document (sets status back to 'active').
+     *
+     * @param id - Document ID
+     * @returns The updated document
+     * @throws NotFoundError if document doesn't exist or element is not a document
+     */
+    unarchiveDocument(id: ElementId): Promise<Document>;
+    /**
+     * Register an EmbeddingService for automatic document embedding on create/update/delete.
+     * This is opt-in: embeddings are only generated when a service is registered.
+     *
+     * @param service - The embedding service to use for auto-indexing
+     */
+    registerEmbeddingService(service: EmbeddingService): void;
+    /**
+     * Rebuild FTS index for all documents without creating version history entries.
+     * Use after import/sync or when search results seem stale.
+     *
+     * @returns Count of indexed documents and errors
+     */
+    reindexAllDocumentsFTS(): {
+        indexed: number;
+        errors: number;
+    };
+    /**
+     * Get audit events for an element.
+     *
+     * @param id - Element ID
+     * @param filter - Optional event filter
+     * @returns Array of events (newest first)
+     */
+    getEvents(id: ElementId, filter?: EventFilter): Promise<Event[]>;
+    /**
+     * List all events across all elements.
+     *
+     * @param filter - Optional event filter (including elementId filter, event types, actor, time range)
+     * @returns Array of events (newest first)
+     */
+    listEvents(filter?: EventFilter): Promise<Event[]>;
+    /**
+     * Count events matching a filter.
+     *
+     * @param filter - Optional event filter (including elementId filter, event types, actor, time range)
+     * @returns Total count of matching events
+     */
+    countEvents(filter?: EventFilter): Promise<number>;
+    /**
+     * Get a specific version of a document.
+     *
+     * @param id - Document ID
+     * @param version - Version number
+     * @returns The document at that version, or null if not found
+     */
+    getDocumentVersion(id: DocumentId, version: number): Promise<Document | null>;
+    /**
+     * Get the full version history of a document.
+     *
+     * @param id - Document ID
+     * @returns Array of document versions (newest first)
+     */
+    getDocumentHistory(id: DocumentId): Promise<Document[]>;
+    /**
+     * Reconstruct an element's state at a specific point in time.
+     *
+     * Algorithm:
+     * 1. Find the creation event for the element
+     * 2. Apply all events up to the target timestamp
+     * 3. Return the reconstructed state
+     *
+     * @param id - Element ID
+     * @param asOf - Target timestamp to reconstruct state at
+     * @returns Reconstructed state, or null if element didn't exist at that time
+     * @throws NotFoundError if element has no events (never existed)
+     */
+    reconstructAtTime<T extends Element = Element>(id: ElementId, asOf: Timestamp): Promise<ReconstructedState<T> | null>;
+    /**
+     * Generate a complete timeline of an element's history.
+     *
+     * Shows the evolution of the element through all its events,
+     * with state snapshots after each event.
+     *
+     * @param id - Element ID
+     * @param filter - Optional event filter (e.g., limit to certain event types)
+     * @returns Element timeline with snapshots
+     * @throws NotFoundError if element has no events (never existed)
+     */
+    getElementTimeline(id: ElementId, filter?: EventFilter): Promise<ElementTimeline>;
+    /**
+     * Find an existing direct channel between two entities, or create one if it doesn't exist.
+     *
+     * @param entityA - First entity
+     * @param entityB - Second entity
+     * @param actor - Actor performing the operation (must be one of the entities)
+     * @returns The channel (existing or newly created) and whether it was created
+     */
+    findOrCreateDirectChannel(entityA: EntityId, entityB: EntityId, actor: EntityId): Promise<FindOrCreateDirectChannelResult>;
+    /**
+     * Add a member to a channel.
+     *
+     * @param channelId - The channel to add the member to
+     * @param entityId - The entity to add as a member
+     * @param options - Operation options including actor
+     * @returns The result of the operation
+     * @throws NotFoundError if channel doesn't exist
+     * @throws ConstraintError if channel is a direct channel (immutable membership)
+     * @throws ConstraintError if actor doesn't have permission to modify members
+     */
+    addChannelMember(channelId: ElementId, entityId: EntityId, options?: AddMemberOptions): Promise<MembershipResult>;
+    /**
+     * Remove a member from a channel.
+     *
+     * @param channelId - The channel to remove the member from
+     * @param entityId - The entity to remove
+     * @param options - Operation options including actor and reason
+     * @returns The result of the operation
+     * @throws NotFoundError if channel doesn't exist
+     * @throws ConstraintError if channel is a direct channel (immutable membership)
+     * @throws ConstraintError if actor doesn't have permission to modify members
+     * @throws ConstraintError if entity is not a member
+     */
+    removeChannelMember(channelId: ElementId, entityId: EntityId, options?: RemoveMemberOptions): Promise<MembershipResult>;
+    /**
+     * Leave a channel (remove self from members).
+     *
+     * @param channelId - The channel to leave
+     * @param actor - The entity leaving the channel
+     * @returns The result of the operation
+     * @throws NotFoundError if channel doesn't exist
+     * @throws ConstraintError if channel is a direct channel (cannot leave)
+     * @throws ConstraintError if actor is not a member
+     */
+    leaveChannel(channelId: ElementId, actor: EntityId): Promise<MembershipResult>;
+    /**
+     * Search for channels by name, with optional filtering.
+     *
+     * Searches channel names using pattern matching and allows filtering by
+     * channel type, visibility, join policy, and membership.
+     *
+     * @param query - Search text to match against channel names
+     * @param filter - Optional filter constraints (channelType, visibility, joinPolicy, member)
+     * @returns Array of matching channels (up to 100 results, newest first)
+     */
+    searchChannels(query: string, filter?: ChannelFilter): Promise<Channel[]>;
+    /**
+     * Merge two group channels: move all messages from source to target,
+     * merge member lists, and archive the source channel.
+     */
+    mergeChannels(sourceId: ElementId, targetId: ElementId, options?: {
+        newName?: string;
+        actor?: EntityId;
+    }): Promise<{
+        target: Channel;
+        sourceArchived: boolean;
+        messagesMoved: number;
+    }>;
+    /**
+     * Add a member to a team with event recording.
+     *
+     * @param teamId - The team to add the member to
+     * @param entityId - The entity to add as a member
+     * @param options - Operation options including actor
+     * @returns The result of the operation
+     * @throws NotFoundError if team doesn't exist
+     * @throws ConstraintError if team is deleted
+     * @throws ConstraintError if entity is already a member
+     */
+    addTeamMember(teamId: ElementId, entityId: EntityId, options?: AddMemberOptions): Promise<TeamMembershipResult>;
+    /**
+     * Remove a member from a team with event recording.
+     *
+     * @param teamId - The team to remove the member from
+     * @param entityId - The entity to remove
+     * @param options - Operation options including actor and reason
+     * @returns The result of the operation
+     * @throws NotFoundError if team doesn't exist
+     * @throws ConstraintError if team is deleted
+     * @throws ConstraintError if entity is not a member
+     */
+    removeTeamMember(teamId: ElementId, entityId: EntityId, options?: RemoveMemberOptions): Promise<TeamMembershipResult>;
+    /**
+     * Get tasks assigned to a team or its members.
+     *
+     * @param teamId - The team identifier
+     * @param options - Filter options
+     * @returns Tasks assigned to the team or its members
+     * @throws NotFoundError if team doesn't exist
+     */
+    getTasksForTeam(teamId: ElementId, options?: TaskFilter): Promise<Task[]>;
+    /**
+     * Claim a team-assigned task for an individual member.
+     * Updates the task's assignee from the team to the claiming entity.
+     *
+     * @param taskId - The task to claim
+     * @param entityId - The entity claiming the task
+     * @param options - Operation options including actor
+     * @returns The updated task
+     * @throws NotFoundError if task doesn't exist
+     * @throws ConstraintError if task is not assigned to a team
+     * @throws ConstraintError if entity is not a member of the team
+     */
+    claimTaskFromTeam(taskId: ElementId, entityId: EntityId, options?: OperationOptions): Promise<Task>;
+    /**
+     * Get aggregated metrics for a team.
+     *
+     * @param teamId - The team identifier
+     * @returns Team metrics
+     * @throws NotFoundError if team doesn't exist
+     */
+    getTeamMetrics(teamId: ElementId): Promise<TeamMetrics>;
+    /**
+     * Delete a workflow and all its child tasks.
+     * This is a hard delete that removes the workflow, all its tasks, and their dependencies.
+     *
+     * @param workflowId - The workflow to delete
+     * @param options - Operation options including actor
+     * @returns Result with counts of deleted elements
+     * @throws NotFoundError if workflow doesn't exist
+     */
+    deleteWorkflow(workflowId: ElementId, options?: DeleteWorkflowOptions): Promise<DeleteWorkflowResult>;
+    /**
+     * Run garbage collection on ephemeral workflows.
+     * Deletes ephemeral workflows that are in terminal state and older than maxAgeMs.
+     *
+     * @param options - GC configuration including maxAgeMs
+     * @returns Result with counts of deleted elements
+     */
+    garbageCollectWorkflows(options: GarbageCollectionOptions): Promise<GarbageCollectionResult>;
+    /**
+     * Garbage collect ephemeral tasks.
+     * Deletes ephemeral tasks that are in terminal state (closed or tombstone) and older than maxAgeMs.
+     * Only affects standalone ephemeral tasks - tasks belonging to workflows should be cleaned up via
+     * garbageCollectWorkflows() instead.
+     *
+     * @param options - GC configuration including maxAgeMs
+     * @returns Result with counts of deleted elements
+     */
+    garbageCollectTasks(options: TaskGarbageCollectionOptions): Promise<TaskGarbageCollectionResult>;
+    /**
+     * Get all tasks in a workflow.
+     * Returns tasks with parent-child dependency to the workflow.
+     *
+     * @param workflowId - The workflow ID
+     * @param filter - Optional task filter constraints
+     * @returns Array of tasks in the workflow
+     * @throws NotFoundError if workflow doesn't exist
+     */
+    getTasksInWorkflow(workflowId: ElementId, filter?: TaskFilter): Promise<Task[]>;
+    /**
+     * Get ready tasks in a workflow.
+     * Returns tasks that are ready for work (open/in_progress, not blocked, not scheduled for future).
+     *
+     * @param workflowId - The workflow ID
+     * @param filter - Optional task filter constraints
+     * @returns Array of ready tasks in the workflow
+     * @throws NotFoundError if workflow doesn't exist
+     */
+    getReadyTasksInWorkflow(workflowId: ElementId, filter?: TaskFilter): Promise<Task[]>;
+    /**
+     * Get progress metrics for a workflow.
+     * Computes task status counts and completion percentage.
+     *
+     * @param workflowId - The workflow ID
+     * @returns Progress metrics for the workflow
+     * @throws NotFoundError if workflow doesn't exist
+     */
+    getWorkflowProgress(workflowId: ElementId): Promise<WorkflowProgress>;
+    /**
+     * Get tasks in a workflow ordered by execution order (topological sort).
+     * Tasks are ordered such that blockers come before the tasks they block.
+     * This represents the order in which tasks should be executed.
+     *
+     * @param workflowId - The workflow ID
+     * @param filter - Optional task filter constraints
+     * @returns Tasks in execution order (topological sort based on blocks dependencies)
+     * @throws NotFoundError if workflow doesn't exist
+     */
+    getOrderedTasksInWorkflow(workflowId: ElementId, filter?: TaskFilter): Promise<Task[]>;
+    /**
+     * Export elements to JSONL format.
+     *
+     * @param options - Export configuration
+     * @returns JSONL string if no outputPath specified
+     */
+    export(options?: ExportOptions): Promise<string | void>;
+    /**
+     * Import elements from JSONL format.
+     *
+     * @param options - Import configuration
+     * @returns Import result with counts and any errors
+     */
+    import(options: ImportOptions): Promise<ImportResult>;
+    /**
+     * Get system statistics.
+     *
+     * @returns Current system statistics
+     */
+    stats(): Promise<SystemStats>;
+}
+/**
+ * Check if a value is a valid SortDirection
+ */
+export declare function isSortDirection(value: unknown): value is SortDirection;
+/**
+ * Check if a value is a valid ConflictStrategy
+ */
+export declare function isConflictStrategy(value: unknown): value is ConflictStrategy;
+/**
+ * Check if a value is a valid ExportFormat
+ */
+export declare function isExportFormat(value: unknown): value is ExportFormat;
+/**
+ * Validate an ElementFilter object
+ */
+export declare function isValidElementFilter(value: unknown): value is ElementFilter;
+/**
+ * Validate a TaskFilter object
+ */
+export declare function isValidTaskFilter(value: unknown): value is TaskFilter;
+/**
+ * Validate a DocumentFilter object
+ */
+export declare function isValidDocumentFilter(value: unknown): value is DocumentFilter;
+/**
+ * Validate a GetOptions object
+ */
+export declare function isValidGetOptions(value: unknown): value is GetOptions;
+/**
+ * Validate ExportOptions
+ */
+export declare function isValidExportOptions(value: unknown): value is ExportOptions;
+/**
+ * Validate ImportOptions
+ */
+export declare function isValidImportOptions(value: unknown): value is ImportOptions;
+import type { Channel, ChannelType, Visibility, JoinPolicy } from '@stoneforge/core';
+/**
+ * Filter for channel queries
+ */
+export interface ChannelFilter extends ElementFilter {
+    /** Filter by channel type (direct or group) */
+    channelType?: ChannelType;
+    /** Filter by visibility */
+    visibility?: Visibility;
+    /** Filter by join policy */
+    joinPolicy?: JoinPolicy;
+    /** Filter channels containing a specific member */
+    member?: EntityId;
+}
+/**
+ * Options for adding a member to a channel
+ */
+export interface AddMemberOptions extends OperationOptions {
+}
+/**
+ * Options for removing a member from a channel
+ */
+export interface RemoveMemberOptions extends OperationOptions {
+    /** Reason for removal */
+    reason?: string;
+}
+/**
+ * Result of a channel membership operation
+ */
+export interface MembershipResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** The updated channel */
+    channel: Channel;
+    /** The entity that was added/removed */
+    entityId: EntityId;
+}
+/**
+ * Result of find-or-create direct channel operation
+ */
+export interface FindOrCreateDirectChannelResult {
+    /** The channel (existing or newly created) */
+    channel: Channel;
+    /** Whether a new channel was created */
+    created: boolean;
+}
+/**
+ * Input for sending a direct message
+ */
+export interface SendDirectMessageInput {
+    /** The recipient entity ID */
+    recipient: EntityId;
+    /** Reference to content Document (must be created first) */
+    contentRef: DocumentId;
+    /** Optional: References to attachment Documents */
+    attachments?: DocumentId[];
+    /** Optional: tags */
+    tags?: string[];
+    /** Optional: metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of sending a direct message
+ */
+export interface SendDirectMessageResult {
+    /** The created message */
+    message: Message;
+    /** The channel used (existing or newly created) */
+    channel: Channel;
+    /** Whether a new channel was created for this message */
+    channelCreated: boolean;
+}
+/**
+ * Result of a team membership operation
+ */
+export interface TeamMembershipResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** The updated team */
+    team: Team;
+    /** The entity that was added/removed */
+    entityId: EntityId;
+}
+/**
+ * Team metrics aggregation
+ */
+export interface TeamMetrics {
+    /** Team identifier */
+    teamId: ElementId;
+    /** Number of tasks completed by team members */
+    tasksCompleted: number;
+    /** Number of tasks currently in progress */
+    tasksInProgress: number;
+    /** Number of tasks assigned to team or members */
+    totalTasks: number;
+    /** Tasks assigned directly to the team */
+    tasksAssignedToTeam: number;
+    /** Average time from task open to close (ms) */
+    averageCycleTimeMs: number | null;
+}
+/** Default page size for list queries */
+export declare const DEFAULT_PAGE_SIZE = 10000;
+/** Maximum page size for list queries */
+export declare const MAX_PAGE_SIZE = 10000;
+/** Default conflict strategy for imports */
+export declare const DEFAULT_CONFLICT_STRATEGY: ConflictStrategy;
+/** Default export format */
+export declare const DEFAULT_EXPORT_FORMAT: ExportFormat;
+//# sourceMappingURL=types.d.ts.map