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.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: trueguaranteestaskandok: falseguaranteesreason, so no caller needs a non-null assertion.countis the rows already counted (child_cap,root_rate_cap),maxthe ceiling measured against,windowMsthe rolling window (root_rate_caponly). A depth denial deliberately reports no observed depth — the walk clamps, so the number would be a lie.SubtaskCaps{ maxChildren?, maxDepth? }andRootCreateCaps{ maxRootCreates?, windowMs? }, the per-call overrides; each field falls back to itsDEFAULT_*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 bylinkDepwhen an edge would close a direct or transitive dependency cycle. Carriescode: 'task_dependency_cycle'; thelink_taskMCP tool maps it to a tool-error.SqliteMemoryStore, the local-firstMemoryStore(FTS5 + optional Float32-BLOB vector index + hybrid blend; embedding best-effort, degrades to FTS).DeterministicEmbeddingProvider/OllamaEmbeddingProvider/OpenAiEmbeddingProvider, the threeEmbeddingProviderimplementations.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 inschema.tsbut its table object is not re-exported; reach its rows through theinboxaccessors instead. - Board,
TASK_STATUSES, plus the zod schemastaskStatusSchema,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 schemaslistToolsQuery,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-coredirectly 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
- Database schema reference, the 28 tables + ERD.
- The board, state machine, atomic claim, deps.
- Memory, shared Memory-MCP tier.
- Governance, budgets, kill-switch, audit.
- Observability, the event log.
@clawboo/governance·@clawboo/obs·@clawboo/mcp, consumers/upstreams of this layer.