Skip to main content
Version 0.1.0 · Purity server-only (better-sqlite3 native binding) · Purpose the single SQLite + Drizzle data layer: schema, connection, and every domain repository (board, memory, tools broker, governance, event log, sessions, routines, team-chat). It is the cross-process bus: the Express server and the MCP stdio bins open the same file. Workspace deps @clawboo/board-core, @clawboo/compaction, @clawboo/governance, @clawboo/obs External deps better-sqlite3, drizzle-orm, zod, @noble/ed25519
This is the registry of record. The 28 Drizzle-typed tables + the idempotent CREATE TABLE IF NOT EXISTS bootstrap in ensureSchema (schemaBootstrap.ts) make a fresh file immediately usable; that DDL is the sole schema source; there is no migration ladder (no db:migrate / db:generate scripts). Opening an older file also reconciles it, adding any columns it is missing, derived from the same DDL. SQLite-native columns (team, personality, runtime, capabilities) are never clobbered by a Gateway re-sync.
The package exposes one barrel (src/index.ts). It re-exports schema, db, and eleven domain sub-modules (board, capabilities, memory, tools, governance, events, sessions, routines, teamChat, inbox, chat) via export *. There are no package.json subpath exports; everything is reachable from @clawboo/db. One of those re-exports crosses a package boundary: the board state machine lives in the pure, zero-dep @clawboo/board-core, so the browser UI and the orchestration engine can read the same transition table without pulling this package’s sqlite graph. @clawboo/db re-exports it by name, so the symbols below are reachable from @clawboo/db exactly as before.

Public API

Functions

Connection (db.ts, schemaBootstrap.ts, openStats.ts) Board, repository (board/repository.ts) Board, state machine (re-exported from @clawboo/board-core) Board, contention (board/contention.ts) Board, verification (board/verification.ts) Capabilities (capabilities/repository.ts) Memory, embedding + summary (memory/embedding.ts, memory/summary.ts) Tools broker (tools/*) Governance (governance/*) Events (events/*) Sessions, rotation lineage (sessions/index.ts) Routines, scheduled-runs ledger (routines/*) Team-chat room substrate (teamChat/index.ts) Durable mailbox (inbox.ts) Agent-bound notifications that survive eviction and restarts, delivered by whichever channel touches the agent first. Chat transcript tail (chat/*)

Types & interfaces

  • Drizzle row types (per table, select + insert): DbAgent/DbAgentInsert, DbApprovalHistory(+Insert), DbBooZeroTeamBrief(+Insert), DbBudget(+Insert), DbCapability(+Insert), DbChatMessage(+Insert), DbCostRecord(+Insert), DbExecutionProcess(+Insert), DbGovernanceAudit(+Insert), DbGraphLayout(+Insert), DbMemoryFact(+Insert), DbMemoryProcedure(+Insert), DbOrchestrationEvent(+Insert), DbScheduledRun(+Insert), DbSession(+Insert), DbSetting(+Insert), DbSkill(+Insert), DbTask(+Insert), DbTaskComment(+Insert), DbTaskDep(+Insert), DbTeam(+Insert), DbTeamChat(+Insert), DbTeamProfile(+Insert), DbToolCallApproval(+Insert), DbToolCallAudit(+Insert), DbToolRegistry(+Insert), DbWorkspace(+Insert).
  • Connection, ClawbooDb (the Drizzle instance type).
  • Board, Scope, CreateTaskInput, ListTasksFilter, ClaimReason, ClaimResult, UpdateStatusReason, UpdateStatusResult, UpdateStatusOptions, TaskFields, WorkspaceStatus, CreateExecInput, CompleteExecOutcome, ReconcileResult, BoardTx, TaskStatus.
  • Board, guarded creation — the types behind createCappedSubtask / createCappedRootTask:
    • CreateGuardReason, the refusal vocabulary: 'parent_not_found' | 'child_cap' | 'depth_cap' | 'root_rate_cap'.
    • GuardedCreateResult, a discriminated union rather than the older { ok; task? } shape: { ok: true; task: DbTask } or { ok: false; reason: CreateGuardReason; count?: number; max?: number; windowMs?: number }. ok: true guarantees task and ok: false guarantees reason, so no caller needs a non-null assertion. count is the rows already counted (child_cap, root_rate_cap), max the ceiling measured against, windowMs the rolling window (root_rate_cap only). A depth denial deliberately reports no observed depth — the walk clamps, so the number would be a lie.
    • SubtaskCaps { maxChildren?, maxDepth? } and RootCreateCaps { maxRootCreates?, windowMs? }, the per-call overrides; each field falls back to its DEFAULT_* constant re-exported from this package. Zod body/result types: CreateTaskBody, UpdateTaskBody, ClaimBody, CommentBody, CreateExecutionBody, CompleteExecutionBody, LinkDepBody, ProvisionWorkspaceBody, WorkspaceActionBody, AncestorRow.
  • Capabilities, ListCapabilitiesFilter.
  • Memory, MemoryStore, EmbeddingProvider, Fact, Procedure, MemoryScope, MemorySearchResult, SearchMode, SearchOpts, BrowseOpts, SaveFactInput, SaveProcedureInput, ResolveEmbeddingOpts, StructuredSummaryInput. Zod body types: SaveFactBody, SaveProcedureBody, SaveMemoryBody, SearchMemoryBody, BrowseMemoryBody, MemoryScopeBody.
  • Tools, ToolDescriptor, ToolCall, ToolCallContext, ToolOwner, ToolRisk, ToolProvenance, AvailabilityContext, AvailabilityRequirement, AvailabilityResult, DefaultAvailabilityOpts, Inspector, InspectorDecision, ChainOutcome, InjectionFinding, InjectionSeverity, ProvenanceResult, ProvenanceVerifyOpts, BrokeredResult, BrokerOptions, ApprovalDecision, ApprovalResolution, VisibleTool, ListToolsQuery, ResolveApprovalBody.
  • Governance, BudgetScope, BudgetMode, RecordSpendResult, SetBudgetLimitInput, ResumeBudgetOptions, GovernanceEventType, AppendAuditInput, ListGovernanceAuditFilter, SetBudgetBody.
  • Events, AppendEventInput, ListEventsFilter.
  • Sessions, RecordRotationInput.
  • Routines, ScheduledRunStatus, RegisterScheduledRunInput, RegisterScheduledRunResult, ListScheduledRunsFilter, RoutineScope, RunOutcome, SetStatusResult, UpdateScheduledRunPatch.
  • Team-chat, TeamChatKind, PostToRoomInput, ReadRoomInput.
  • Chat transcript tail, ListChatMessagesSinceFilter, ListRecentChatMessagesFilter.

Classes

  • TaskDependencyCycleError, thrown by linkDep when an edge would close a direct or transitive dependency cycle. Carries code: 'task_dependency_cycle'; the link_task MCP tool maps it to a tool-error.
  • SqliteMemoryStore, the local-first MemoryStore (FTS5 + optional Float32-BLOB vector index + hybrid blend; embedding best-effort, degrades to FTS).
  • DeterministicEmbeddingProvider / OllamaEmbeddingProvider / OpenAiEmbeddingProvider, the three EmbeddingProvider implementations.
  • ToolRegistry, in-memory broker tool registry; createBuiltinRegistry() seeds it.

Constants

  • Schema, the 27 Drizzle table objects the barrel re-exports: agents, approvalHistory, booZeroTeamBriefs, budgets, capabilities, chatMessages, costRecords, executionProcesses, governanceAudit, graphLayouts, memoryFacts, memoryProcedures, orchestrationEvents, scheduledRuns, sessions, settings, skills, taskComments, taskDeps, tasks, teamChat, teams, teamProfiles, toolCallApprovals, toolCallAudit, toolRegistry, workspaces. The 28th table, agent_inbox, is declared in schema.ts but its table object is not re-exported; reach its rows through the inbox accessors instead.
  • Board, TASK_STATUSES, plus the zod schemas taskStatusSchema, createTaskBody, updateTaskBody, claimBody, commentBody, createExecutionBody, completeExecutionBody, linkDepBody, provisionWorkspaceBody, workspaceActionBody, ancestorRowSchema, ancestorRowsSchema.
  • Memory, zod schemas memoryScopeSchema, searchModeSchema, saveFactBody, saveProcedureBody, saveMemoryBody, searchMemoryBody, browseMemoryBody.
  • Tools, BUILTIN_TOOLS, echoTool, memoryNoteTool, webSearchTool, deletePathTool; zod schemas listToolsQuery, resolveApprovalBody.
  • Governance, zod schemas budgetScopeSchema, budgetModeSchema, setBudgetBody, resumeBudgetBody.
  • Routines, SCHEDULED_RUN_STATUSES.

Used by

  • apps/web, the Express server (server/, server/api/, server/lib/**) and three browser sites (src/stores, src/features/approvals, src/features/connection) — all three type-only, since a value import would drag the sqlite graph into the SPA. The board UI reads its status rules from @clawboo/board-core directly for the same reason.
  • @clawboo/mcp, the Tasks / Memory / Tools / TeamChat MCP servers + the stdio bins.
  • @clawboo/evals, the eval harness graders/tasks (throwaway boards).

Source

Barrel: packages/db/src/index.ts. Schema: packages/db/src/schema.ts. Sub-modules: board/, capabilities/, memory/, tools/, governance/, events/, sessions/, routines/, teamChat/, inbox.ts, chat/. Connection: db.ts. Schema bootstrap DDL: schemaBootstrap.ts (the sole schema source; there is no migration ladder). Additive in-place upgrade: schemaReconcile.ts. Open-counters: openStats.ts.

See also

Last modified on August 21, 2026