Files
kandev/apps/backend/internal/office/repository/sqlite/base_migrations.go
T
2026-09-22 13:21:39 +01:00

986 lines
43 KiB
Go

package sqlite
import (
"context"
"database/sql"
"fmt"
"strings"
"go.uber.org/zap"
"github.com/kandev/kandev/internal/db"
"github.com/kandev/kandev/internal/db/dialect"
"github.com/kandev/kandev/internal/office/models"
)
// runMigrations applies idempotent schema migrations for office tables
// living alongside the canonical task tables. Office is shipping as a
// new feature, so we only carry migrations that mutate state owned by
// the task schema on main (tasks priority TEXT rebuild, FTS triggers,
// checkout columns) plus the routing/settings/dismissal tables created
// from base_migrations. Legacy in-branch reshapes (rename office_runs,
// fold office_agent_instances, drop dead task columns, etc.) have been
// collapsed: those rows never landed on main so the migrations were
// pure no-ops at first boot.
func (r *Repository) runMigrations() error {
if err := r.migrateSchedulerColumns(); err != nil {
return err
}
if err := r.migrateFailureColumns(); err != nil {
return err
}
r.migrateRunPayloadIndexes()
r.migrateCostEventContract()
// These migrations implement SQLite-only task search and table-rebuild
// behavior. PostgreSQL has no rowid or FTS5 virtual tables, and its task
// repository already creates the portable task shape. Keep the branch
// explicit so an office store opened on PostgreSQL never probes SQLite's
// catalog or executes SQLite DDL.
if !dialect.IsPostgres(r.db.DriverName()) {
if err := r.migrateTaskPriorityToText(); err != nil {
return fmt.Errorf("tasks.priority_text_rebuild: %w", err)
}
// Run migrateTaskFTS LAST so its triggers survive any subsequent
// recreate-table migrations (notably migrateTaskPriorityToText, which
// drops + rebuilds `tasks` and would otherwise wipe the FTS triggers).
if err := r.migrateTaskFTS(); err != nil {
return err
}
}
// Provider routing tables and replayable column migrations. Fresh
// schemas include the columns inline; ALTERs converge existing databases.
if err := r.migrateProviderRouting(); err != nil {
return err
}
if err := r.migrateContinuationScope(); err != nil {
return err
}
r.migrateRunOutcome()
if err := r.migrateRunSkillLabels(); err != nil {
return err
}
if err := r.migrateParentWakeIndexes(); err != nil {
return err
}
r.migrateParentWakeReceiptColumns()
r.migrateWakeWaveColumns()
r.migrate.Apply("task_workspace_groups.ownership_generation",
`ALTER TABLE task_workspace_groups ADD COLUMN ownership_generation INTEGER NOT NULL DEFAULT 1`)
r.migrateLaunchSafetyColumns()
r.migrateRoutineCatchUp()
r.migrateBudgetPolicyRevision()
r.migrateWorkspacePauseSkipAttribution()
r.migrateLoopLivenessCausationID()
if err := r.migrateRetentionIndexes(); err != nil {
return err
}
if err := r.migrateAssignmentWakeRateIndexes(); err != nil {
return err
}
if err := r.migrate.Err(); err != nil {
return err
}
if err := r.backfillRoutineTriggerTimezones(); err != nil {
return err
}
return nil
}
// migrateRunSkillLabels adds the captured labels used by run history. The
// snapshot keeps its display identity even if the live skill is renamed or
// deleted later.
func (r *Repository) migrateRunSkillLabels() error {
if err := r.migrate.Apply(
"office_run_skills.display_name",
`ALTER TABLE office_run_skills ADD COLUMN display_name TEXT NOT NULL DEFAULT ''`,
); err != nil {
return err
}
if err := r.migrate.Apply(
"office_run_skills.slug",
`ALTER TABLE office_run_skills ADD COLUMN slug TEXT NOT NULL DEFAULT ''`,
); err != nil {
return err
}
return r.migrate.Apply(
"office_run_skills.label_source",
`ALTER TABLE office_run_skills ADD COLUMN label_source TEXT NOT NULL DEFAULT ''`,
)
}
// backfillRoutineTriggerTimezones sets an explicit "UTC" on cron triggers
// created before the column default changed from empty to 'UTC', so the
// empty string no longer means anything at read time.
func (r *Repository) backfillRoutineTriggerTimezones() error {
if _, err := r.db.Exec(
`UPDATE office_routine_triggers SET timezone = 'UTC' WHERE kind = 'cron' AND timezone = ''`,
); err != nil {
return fmt.Errorf("office_routine_triggers.timezone backfill: %w", err)
}
return nil
}
// migrateBudgetPolicyRevision adds office_budget_policies.revision for
// databases created before REQ-OFFICE-COSTS-003. The DEFAULT 1 backfills
// every existing row exactly like createCostTables' inline column, so a
// fresh database and a migrated one converge. A boot replay is a no-op:
// db.IsDuplicateColumnError is the only local classifier (ADR 0027), reused
// via MigrateLogger.Apply rather than adding a new one.
func (r *Repository) migrateBudgetPolicyRevision() {
_ = r.migrate.Apply("office_budget_policies.revision",
`ALTER TABLE office_budget_policies ADD COLUMN revision INTEGER NOT NULL DEFAULT 1`)
}
// migrateWorkspacePauseSkipAttribution adds the columns a blocked routine
// fire uses to record why it was skipped and which pause blocked it. The
// partial unique index runs after both ADD COLUMNs so it never executes
// against a schema that lacks pause_id.
func (r *Repository) migrateWorkspacePauseSkipAttribution() {
_ = r.migrate.Apply("office_routine_runs.skip_reason",
`ALTER TABLE office_routine_runs ADD COLUMN skip_reason TEXT NOT NULL DEFAULT ''`)
_ = r.migrate.Apply("office_routine_runs.pause_id",
`ALTER TABLE office_routine_runs ADD COLUMN pause_id TEXT NOT NULL DEFAULT ''`)
_ = r.migrate.Apply("idx_office_routine_run_pause_once",
`CREATE UNIQUE INDEX IF NOT EXISTS idx_office_routine_run_pause_once
ON office_routine_runs(routine_id, pause_id) WHERE pause_id != ''`)
}
// migrateLoopLivenessCausationID adds the causation_id correlation
// column to all three rows in the wake-to-run chain
// (REQ-OFFICE-LOOP-LIVENESS-002): the routine fire, the wakeup request
// it produces, and the run the wakeup request produces. "" rather than
// NULL, because every existing row predates this feature and a reader
// must treat "legacy" and "uncorrelated" identically. Each column gets
// its own partial index (excluding "") so a backward correlation walk
// from a run to its originating fire is a direct lookup on every
// dialect, not a table scan — NFR-2 is symmetric with the forward walk.
//
// runs.causation_id here is REQ-OFFICE-LOOP-LIVENESS-002's column, copied
// from the wakeup request that created the run — a distinct column and a
// distinct concept from runs.chain_causation_id below
// (REQ-OFFICE-RUN-CAUSATION-001's launch-safety causation chain). The two
// features were built independently and both reached for the name
// "causation id"; they do not describe the same lineage and must not share
// a column. See docs/decisions/2026-09-17-separate-loop-liveness-and-launch-safety-causation-ids.md.
func (r *Repository) migrateLoopLivenessCausationID() {
_ = r.migrate.Apply("office_routine_runs.causation_id",
`ALTER TABLE office_routine_runs ADD COLUMN causation_id TEXT NOT NULL DEFAULT ''`)
_ = r.migrate.Apply("idx_office_routine_runs_causation_id",
`CREATE INDEX IF NOT EXISTS idx_office_routine_runs_causation_id
ON office_routine_runs(causation_id) WHERE causation_id != ''`)
_ = r.migrate.Apply("agent_wakeup_requests.causation_id",
`ALTER TABLE agent_wakeup_requests ADD COLUMN causation_id TEXT NOT NULL DEFAULT ''`)
_ = r.migrate.Apply("idx_agent_wakeup_requests_causation_id",
`CREATE INDEX IF NOT EXISTS idx_agent_wakeup_requests_causation_id
ON agent_wakeup_requests(causation_id) WHERE causation_id != ''`)
_ = r.migrate.Apply("runs.causation_id",
`ALTER TABLE runs ADD COLUMN causation_id TEXT NOT NULL DEFAULT ''`)
_ = r.migrate.Apply("idx_runs_causation_id",
`CREATE INDEX IF NOT EXISTS idx_runs_causation_id
ON runs(causation_id) WHERE causation_id != ''`)
}
// migrateRetentionIndexes adds the two indexes the run-history retention
// sweep depends on (docs/specs/office/system-design/run-history-retention.md
// "Indexes to add"). Both are expression indexes over the same
// COALESCE(...) the sweep both filters and orders by; a plain-column index
// on the nullable completion column would serve neither the WHERE clause
// nor the ORDER BY the sweep actually issues, on either engine.
func (r *Repository) migrateRetentionIndexes() error {
if err := r.migrate.Apply(
"idx_office_routine_runs_retention",
`CREATE INDEX IF NOT EXISTS idx_office_routine_runs_retention
ON office_routine_runs(routine_id, status, (COALESCE(completed_at, created_at)) DESC, id DESC)`,
); err != nil {
return err
}
return r.migrate.Apply(
"idx_runs_retention",
`CREATE INDEX IF NOT EXISTS idx_runs_retention
ON runs(agent_profile_id, status, (COALESCE(finished_at, requested_at)) DESC, id DESC)`,
)
}
// migrateLaunchSafetyColumns adds the nine chain-causation/priority/actor/
// workspace columns to runs (docs/specs/office/requirements/
// run-causation-chain.md, launch-backpressure.md) for databases created
// before this capability, plus the two new tables it introduces. Every
// ALTER is NOT NULL with a default so existing rows converge in place: an
// empty chain_causation_id is the legacy marker AC-OFFICE-RUN-CAUSATION-001.6
// reads as "its own root at depth 0", and the fresh-install CREATE TABLE
// in base.go carries the identical column set inline.
//
// This column is named chain_causation_id, not causation_id, to stay
// distinct from runs.causation_id above (REQ-OFFICE-LOOP-LIVENESS-002),
// which already occupies that name for an unrelated wakeup-request
// correlation. See the doc comment on migrateLoopLivenessCausationID.
func (r *Repository) migrateLaunchSafetyColumns() {
_ = r.migrate.Apply("runs.chain_causation_id",
`ALTER TABLE runs ADD COLUMN chain_causation_id TEXT NOT NULL DEFAULT ''`)
_ = r.migrate.Apply("runs.parent_run_id",
`ALTER TABLE runs ADD COLUMN parent_run_id TEXT NOT NULL DEFAULT ''`)
_ = r.migrate.Apply("runs.causation_depth",
`ALTER TABLE runs ADD COLUMN causation_depth INTEGER NOT NULL DEFAULT 0`)
_ = r.migrate.Apply("runs.priority_class",
`ALTER TABLE runs ADD COLUMN priority_class INTEGER NOT NULL DEFAULT 2`)
_ = r.migrate.Apply("runs.human_rooted",
`ALTER TABLE runs ADD COLUMN human_rooted INTEGER NOT NULL DEFAULT 0`)
_ = r.migrate.Apply("runs.routine_id",
`ALTER TABLE runs ADD COLUMN routine_id TEXT NOT NULL DEFAULT ''`)
_ = r.migrate.Apply("runs.actor_kind",
`ALTER TABLE runs ADD COLUMN actor_kind TEXT NOT NULL DEFAULT 'system'`)
_ = r.migrate.Apply("runs.actor_id",
`ALTER TABLE runs ADD COLUMN actor_id TEXT NOT NULL DEFAULT ''`)
_ = r.migrate.Apply("runs.workspace_id",
`ALTER TABLE runs ADD COLUMN workspace_id TEXT NOT NULL DEFAULT ''`)
r.backfillLaunchSafetyWorkspaceIDs()
// Indexes reference the new columns, so they run after the ADD
// COLUMN statements above rather than in schema init.
_ = r.migrate.Apply("idx_run_chain_causation_id",
`CREATE INDEX IF NOT EXISTS idx_run_chain_causation_id ON runs(chain_causation_id)`)
_ = r.migrate.Apply("idx_run_claim_order",
`CREATE INDEX IF NOT EXISTS idx_run_claim_order ON runs(status, priority_class, requested_at, id)`)
_ = r.migrate.Apply("idx_run_self_trigger_window",
`CREATE INDEX IF NOT EXISTS idx_run_self_trigger_window ON runs(agent_profile_id, reason, actor_id, requested_at)`)
_ = r.migrate.Apply("idx_run_self_trigger_total_window",
`CREATE INDEX IF NOT EXISTS idx_run_self_trigger_total_window ON runs(agent_profile_id, actor_id, requested_at)`)
_, _ = r.db.Exec(`
CREATE TABLE IF NOT EXISTS office_launch_ledger (
id TEXT PRIMARY KEY,
run_id TEXT NOT NULL,
workspace_id TEXT NOT NULL,
causation_id TEXT NOT NULL DEFAULT '',
routine_id TEXT NOT NULL DEFAULT '',
human_rooted INTEGER NOT NULL DEFAULT 0,
claimed_at TIMESTAMP NOT NULL
)`)
_, _ = r.db.Exec(`CREATE INDEX IF NOT EXISTS idx_launch_ledger_ws_time ON office_launch_ledger(workspace_id, claimed_at)`)
_, _ = r.db.Exec(`CREATE INDEX IF NOT EXISTS idx_launch_ledger_routine_time ON office_launch_ledger(routine_id, claimed_at)`)
_, _ = r.db.Exec(`
CREATE TABLE IF NOT EXISTS office_gate_failure_state (
workspace_id TEXT NOT NULL,
gate TEXT NOT NULL,
consecutive_failures INTEGER NOT NULL DEFAULT 0,
last_escalation_at TIMESTAMP,
updated_at TIMESTAMP NOT NULL,
PRIMARY KEY (workspace_id, gate)
)`)
_, _ = r.db.Exec(`
CREATE TABLE IF NOT EXISTS office_causation_refusal (
id TEXT PRIMARY KEY,
workspace_id TEXT NOT NULL,
gate TEXT NOT NULL,
agent_profile_id TEXT NOT NULL,
causation_id TEXT NOT NULL DEFAULT '',
causation_depth INTEGER NOT NULL DEFAULT 0,
reason TEXT NOT NULL DEFAULT '',
refused_at TIMESTAMP NOT NULL
)`)
_, _ = r.db.Exec(`CREATE INDEX IF NOT EXISTS idx_causation_refusal_ws_time ON office_causation_refusal(workspace_id, refused_at)`)
_, _ = r.db.Exec(`CREATE INDEX IF NOT EXISTS idx_causation_refusal_agent_time ON office_causation_refusal(agent_profile_id, refused_at)`)
}
// backfillLaunchSafetyWorkspaceIDs repairs runs.workspace_id for runs still
// active (queued/claimed) when the ADD COLUMN migration above ran: their
// workspace_id starts as ” regardless of which workspace they belong to,
// which pools every such legacy run into the shared empty-bucket for
// per-workspace concurrency ceilings and budgets
// (AC-OFFICE-RUN-CAUSATION-001.19) instead of scoping it correctly. Only
// active rows are repaired; a finished run's workspace_id is historical and
// not read by any ceiling or budget check. A database that has not yet run
// the agent-settings migrations (agent_profiles missing) fails this step
// exactly like every other statement in this file: logged and swallowed,
// non-fatal to boot.
func (r *Repository) backfillLaunchSafetyWorkspaceIDs() {
stmt := r.db.Rebind(`
UPDATE runs SET workspace_id = (
SELECT workspace_id FROM agent_profiles WHERE id = runs.agent_profile_id
)
WHERE workspace_id = ''
AND status IN ('queued', 'claimed')
AND EXISTS (SELECT 1 FROM agent_profiles WHERE id = runs.agent_profile_id)
`)
if _, err := r.db.Exec(stmt); err != nil {
if r.log != nil {
r.log.Warn("launch safety workspace_id backfill failed", zap.Error(err))
}
}
}
// migrateAssignmentWakeRateIndexes adds the portable prefix used by the
// rolling assignment-wake count. The count deliberately has no status
// predicate, so idx_run_status_requested cannot support its reason/time scan.
func (r *Repository) migrateAssignmentWakeRateIndexes() error {
return r.migrate.Apply(
"idx_runs_assignment_rate_reason_requested",
`CREATE INDEX IF NOT EXISTS idx_runs_assignment_rate_reason_requested
ON runs(reason, requested_at)`,
)
}
// migrateContinuationScope adds runs.continuation_scope for databases
// created before WO-16's claim-time scope persistence. Existing rows receive
// a scope from their stored context snapshot so queued or claimed taskless
// runs keep their continuation chain after an upgrade.
func (r *Repository) migrateContinuationScope() error {
if err := r.migrate.Apply("runs.continuation_scope",
`ALTER TABLE runs ADD COLUMN continuation_scope TEXT NOT NULL DEFAULT ''`); err != nil {
return err
}
if err := r.backfillContinuationScopes(); err != nil {
return err
}
if err := r.migrate.Apply("runs.failure_scope_status_index",
`CREATE INDEX IF NOT EXISTS idx_run_failure_scope_status ON runs(agent_profile_id, continuation_scope, status)`); err != nil {
return err
}
return nil
}
func (r *Repository) backfillContinuationScopes() error {
var legacyRuns []struct {
ID string `db:"id"`
AgentProfileID string `db:"agent_profile_id"`
ContextSnapshot string `db:"context_snapshot"`
}
if err := r.db.Select(&legacyRuns,
`SELECT id, agent_profile_id, context_snapshot
FROM runs WHERE continuation_scope = ''`); err != nil {
return fmt.Errorf("runs.continuation_scope backfill query: %w", err)
}
for _, legacyRun := range legacyRuns {
scope := models.ContinuationScopeForRun(
&models.Run{ContextSnapshot: legacyRun.ContextSnapshot},
legacyRun.AgentProfileID,
)
if _, err := r.db.Exec(r.db.Rebind(`
UPDATE runs SET continuation_scope = ?
WHERE id = ? AND continuation_scope = ''
`), scope, legacyRun.ID); err != nil {
return fmt.Errorf("runs.continuation_scope backfill update %q: %w", legacyRun.ID, err)
}
}
return nil
}
// migrateCostEventContract adds the cache read/write split, turn
// attribution, and cost-provenance columns to office_cost_events for
// databases created before this contract (docs/specs/office/requirements/costs.md). Every
// ALTER is nullable with no DEFAULT: a legacy row must read NULL, never 0,
// because a merged tokens_cached_in cannot be decomposed and an unversioned
// "0" would be indistinguishable from "no cache activity". Keep this column
// set byte-identical to the inline CREATE TABLE in createCostTables so a
// fresh database and a migrated one converge.
func (r *Repository) migrateCostEventContract() {
r.migrate.Apply("office_cost_events.tokens_cached_read",
`ALTER TABLE office_cost_events ADD COLUMN tokens_cached_read INTEGER`)
r.migrate.Apply("office_cost_events.tokens_cached_write",
`ALTER TABLE office_cost_events ADD COLUMN tokens_cached_write INTEGER`)
r.migrate.Apply("office_cost_events.turn_id",
`ALTER TABLE office_cost_events ADD COLUMN turn_id TEXT`)
r.migrate.Apply("office_cost_events.usage_event_id",
`ALTER TABLE office_cost_events ADD COLUMN usage_event_id TEXT`)
r.migrate.Apply("office_cost_events.cost_source",
`ALTER TABLE office_cost_events ADD COLUMN cost_source TEXT`)
r.migrate.Apply("office_cost_events.rate_input_per_million",
`ALTER TABLE office_cost_events ADD COLUMN rate_input_per_million INTEGER`)
r.migrate.Apply("office_cost_events.rate_cached_read_per_million",
`ALTER TABLE office_cost_events ADD COLUMN rate_cached_read_per_million INTEGER`)
r.migrate.Apply("office_cost_events.rate_cached_write_per_million",
`ALTER TABLE office_cost_events ADD COLUMN rate_cached_write_per_million INTEGER`)
r.migrate.Apply("office_cost_events.rate_output_per_million",
`ALTER TABLE office_cost_events ADD COLUMN rate_output_per_million INTEGER`)
r.migrate.Apply("office_cost_events.pricing_catalog_version",
`ALTER TABLE office_cost_events ADD COLUMN pricing_catalog_version TEXT`)
r.migrate.Apply("office_cost_events.cost_contract_version",
`ALTER TABLE office_cost_events ADD COLUMN cost_contract_version INTEGER`)
r.migrate.Apply("uniq_office_cost_usage_event",
`CREATE UNIQUE INDEX IF NOT EXISTS uniq_office_cost_usage_event
ON office_cost_events(usage_event_id) WHERE usage_event_id IS NOT NULL`)
}
func (r *Repository) migrateRunPayloadIndexes() {
r.migrate.Apply(
"runs.idx_run_payload_comment_id",
runPayloadCommentIDIndexSQL(r.db.DriverName()),
)
}
// migrateParentWakeIndexes adds the tasks(parent_id) index
// ListStuckParents' three parent_id-correlated subqueries (has-a-live-
// child, no-non-terminal-child, the child-set-key GROUP_CONCAT) need to
// avoid a full tasks scan on every 30-second reconciler tick. Also
// benefits AreAllChildrenTerminal and GetChildSummaries (blockers.go),
// which query the same shape. The office repository is also used in isolated
// tests before the task schema is installed, so the migration is skipped when
// tasks is absent. Once the table exists, an unexpected index failure is fatal
// to the required office store.
func (r *Repository) migrateParentWakeIndexes() error {
exists, err := db.TableExists(r.db, "tasks")
if err != nil {
return fmt.Errorf("inspect tasks table for parent wake index: %w", err)
}
if !exists {
return nil
}
columnExists, err := db.ColumnExists(r.db, "tasks", "parent_id")
if err != nil {
return fmt.Errorf("inspect tasks.parent_id for parent wake index: %w", err)
}
if !columnExists {
return nil
}
return r.migrate.Apply(
"idx_tasks_parent_id",
`CREATE INDEX IF NOT EXISTS idx_tasks_parent_id ON tasks(parent_id)`,
)
}
// migrateParentWakeReceiptColumns adds operation identity for receipts
// created by workflow-engine dispatch, and the child generation a receipt
// was delivered against. Existing rows receive the empty default for both;
// an existing receipt with an empty child_generation is treated by
// ListStuckParents' third OR arm as not matching any non-empty generation,
// so it is re-admitted once on the next tick after upgrade rather than
// silently trusted as current.
func (r *Repository) migrateParentWakeReceiptColumns() {
// Apply's errors are swallowed by design (see db.MigrateLogger.Apply) and
// surface instead through r.migrate.Err(), which runMigrations checks
// once after every migration step — explicitly discarded here rather
// than left unchecked, matching that contract for errcheck.
_ = r.migrate.Apply(
"parent_child_wake_receipts.delivery_operation_id",
`ALTER TABLE parent_child_wake_receipts
ADD COLUMN delivery_operation_id TEXT NOT NULL DEFAULT ''`,
)
_ = r.migrate.Apply(
"parent_child_wake_receipts.child_generation",
`ALTER TABLE parent_child_wake_receipts
ADD COLUMN child_generation TEXT NOT NULL DEFAULT ''`,
)
}
// migrateWakeWaveColumns adds the completion-wave identity columns for
// databases created before parent-wake-wave-identity. No backfill: existing
// rows keep the empty defaults, stay outside the partial unique index, and
// are judged by the parent-scoped compatibility clause ListStuckParents
// still applies to a parent with no keyed run at all.
//
// Apply's errors are swallowed by design (see db.MigrateLogger.Apply) and
// surface instead through r.migrate.Err(), which runMigrations checks once
// after every migration step — explicitly discarded here rather than left
// unchecked, matching that contract for errcheck.
func (r *Repository) migrateWakeWaveColumns() {
_ = r.migrate.Apply("runs.wake_wave_key",
`ALTER TABLE runs ADD COLUMN wake_wave_key TEXT NOT NULL DEFAULT ''`)
_ = r.migrate.Apply("runs.wake_wave_string",
`ALTER TABLE runs ADD COLUMN wake_wave_string TEXT NOT NULL DEFAULT ''`)
_ = r.migrate.Apply("idx_run_wake_wave",
`CREATE UNIQUE INDEX IF NOT EXISTS idx_run_wake_wave
ON runs(wake_wave_key, agent_profile_id) WHERE wake_wave_key <> ''`)
}
// migrateProviderRouting creates the office_workspace_routing,
// office_run_route_attempts, and office_provider_health tables. The
// routing columns are also added with replayable ALTER statements so
// databases created before a column shipped converge to the fresh schema.
func (r *Repository) migrateProviderRouting() error {
if _, err := r.db.Exec(`
CREATE TABLE IF NOT EXISTS office_workspace_routing (
workspace_id TEXT PRIMARY KEY,
enabled INTEGER NOT NULL DEFAULT 0,
default_tier TEXT NOT NULL DEFAULT 'balanced',
provider_order TEXT NOT NULL DEFAULT '[]',
provider_profiles TEXT NOT NULL DEFAULT '{}',
tier_per_reason TEXT NOT NULL DEFAULT '{}',
role_tiers TEXT NOT NULL DEFAULT '{}',
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
)`); err != nil {
return fmt.Errorf("office_workspace_routing table: %w", err)
}
if _, err := r.db.Exec(`
CREATE TABLE IF NOT EXISTS office_run_route_attempts (
run_id TEXT NOT NULL,
seq INTEGER NOT NULL,
execution_profile_id TEXT NOT NULL DEFAULT '',
provider_id TEXT NOT NULL,
model TEXT NOT NULL,
tier TEXT NOT NULL,
tier_source TEXT NOT NULL DEFAULT '',
outcome TEXT NOT NULL,
error_code TEXT,
error_confidence TEXT,
adapter_phase TEXT,
classifier_rule TEXT,
exit_code INTEGER,
raw_excerpt TEXT,
reset_hint TIMESTAMP,
started_at TIMESTAMP NOT NULL,
finished_at TIMESTAMP,
PRIMARY KEY (run_id, seq),
FOREIGN KEY (run_id) REFERENCES runs(id) ON DELETE CASCADE
)`); err != nil {
return fmt.Errorf("office_run_route_attempts table: %w", err)
}
r.migrate.Apply("runs.resolved_execution_profile_id",
`ALTER TABLE runs ADD COLUMN resolved_execution_profile_id TEXT`)
r.migrate.Apply("office_run_route_attempts.execution_profile_id",
`ALTER TABLE office_run_route_attempts ADD COLUMN execution_profile_id TEXT NOT NULL DEFAULT ''`)
r.migrate.Apply("office_workspace_routing.role_tiers",
`ALTER TABLE office_workspace_routing ADD COLUMN role_tiers TEXT NOT NULL DEFAULT '{}'`)
r.migrate.Apply("office_run_route_attempts.tier_source",
`ALTER TABLE office_run_route_attempts ADD COLUMN tier_source TEXT NOT NULL DEFAULT ''`)
if _, err := r.db.Exec(`
CREATE TABLE IF NOT EXISTS office_provider_health (
workspace_id TEXT NOT NULL,
provider_id TEXT NOT NULL,
scope TEXT NOT NULL,
scope_value TEXT NOT NULL,
state TEXT NOT NULL,
error_code TEXT,
retry_at TIMESTAMP,
backoff_step INTEGER NOT NULL DEFAULT 0,
last_failure TIMESTAMP,
last_success TIMESTAMP,
raw_excerpt TEXT,
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (workspace_id, provider_id, scope, scope_value)
)`); err != nil {
return fmt.Errorf("office_provider_health table: %w", err)
}
return nil
}
// migrateFailureColumns creates the auxiliary failure-handling tables:
// workspace settings, inbox dismissals, and durable auto-pause recovery
// snapshots.
// The runs.error_message column is part of the canonical CREATE TABLE
// in base.go, so no ALTER is needed here.
func (r *Repository) migrateFailureColumns() error {
if _, err := r.db.Exec(`
CREATE TABLE IF NOT EXISTS office_workspace_settings (
workspace_id TEXT PRIMARY KEY,
agent_failure_threshold INTEGER NOT NULL DEFAULT 3,
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
)`); err != nil {
return fmt.Errorf("office_workspace_settings table: %w", err)
}
if _, err := r.db.Exec(`
CREATE TABLE IF NOT EXISTS office_inbox_dismissals (
user_id TEXT NOT NULL,
item_kind TEXT NOT NULL,
item_id TEXT NOT NULL,
dismissed_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (user_id, item_kind, item_id)
)`); err != nil {
return fmt.Errorf("office_inbox_dismissals table: %w", err)
}
if _, err := r.db.Exec(`CREATE INDEX IF NOT EXISTS idx_office_inbox_dismissals_kind ON office_inbox_dismissals(item_kind, item_id)`); err != nil {
return fmt.Errorf("idx_office_inbox_dismissals_kind: %w", err)
}
if _, err := r.db.Exec(`
CREATE TABLE IF NOT EXISTS office_agent_pause_recoveries (
agent_id TEXT NOT NULL,
task_id TEXT NOT NULL,
failed_run_id TEXT NOT NULL,
captured_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (agent_id, task_id)
)`); err != nil {
return fmt.Errorf("office_agent_pause_recoveries table: %w", err)
}
if _, err := r.db.Exec(`CREATE INDEX IF NOT EXISTS idx_office_agent_pause_recoveries_agent ON office_agent_pause_recoveries(agent_id)`); err != nil {
return fmt.Errorf("idx_office_agent_pause_recoveries_agent: %w", err)
}
if _, err := r.db.Exec(`CREATE INDEX IF NOT EXISTS idx_office_agent_pause_recoveries_failed_run ON office_agent_pause_recoveries(failed_run_id)`); err != nil {
return fmt.Errorf("idx_office_agent_pause_recoveries_failed_run: %w", err)
}
return nil
}
// migrateSchedulerColumns adds the atomic task-checkout columns to the
// canonical tasks table. The tasks table exists on main, so this ALTER
// is necessary for upgrade. All run/routine column ALTERs that used to
// live here have been folded into the canonical CREATE TABLE statements
// (base.go) — office is new, so main upgrades pick up the final shape
// directly without an interim ALTER step.
func (r *Repository) migrateSchedulerColumns() error {
// These columns belong to the task repository. They are replayed here for
// deployments that initialize the office package first, so skip them until
// that owner has created tasks. Once the table exists, the required migration
// logger makes every unexpected ALTER failure fatal.
exists, err := db.TableExists(r.db, "tasks")
if err != nil {
return fmt.Errorf("inspect tasks table for scheduler migration: %w", err)
}
if !exists {
return nil
}
for _, migration := range []struct {
name string
stmt string
}{
{"tasks.checkout_agent_id", `ALTER TABLE tasks ADD COLUMN checkout_agent_id TEXT`},
{"tasks.checkout_at", `ALTER TABLE tasks ADD COLUMN checkout_at TIMESTAMP`},
{"tasks.checkout_run_id", `ALTER TABLE tasks ADD COLUMN checkout_run_id TEXT`},
} {
if err := r.migrate.Apply(migration.name, migration.stmt); err != nil {
return err
}
}
return nil
}
// migrateTaskFTS creates the FTS5 virtual table and triggers for full-text task search.
// Skips entirely when the tasks table does not exist or when the SQLite build lacks FTS5.
func (r *Repository) migrateTaskFTS() error {
// Guard: tasks table may not exist yet (office schema runs before task schema).
var exists int
if err := r.db.QueryRow(
"SELECT 1 FROM sqlite_master WHERE type='table' AND name='tasks'",
).Scan(&exists); err != nil {
if err == sql.ErrNoRows {
return nil
}
return fmt.Errorf("inspect tasks table for FTS: %w", err)
}
// Attempt to create the FTS5 virtual table. If the SQLite build lacks FTS5,
// this will fail silently and we skip triggers + backfill.
//
// NOTE: Use internal content storage (no `content=` clause). External
// content mode (content='tasks') was previously used but never actually
// indexed any rows — the AFTER INSERT trigger's INSERT INTO tasks_fts(
// rowid, ...) is supposed to be a sync directive in external mode, but
// in this setup it left the index empty (search returned 0 even for
// seeded onboarding tasks). Internal mode duplicates the text into the
// FTS table itself, so the trigger does a real INSERT and the index
// stays in sync. The storage cost is negligible for our task volumes.
if err := r.maybeDropLegacyExternalContentFTS(); err != nil {
return err
}
if _, err := r.db.Exec(`
CREATE VIRTUAL TABLE IF NOT EXISTS tasks_fts USING fts5(
title, description, identifier
)
`); err != nil {
if strings.Contains(strings.ToLower(err.Error()), "no such module: fts5") {
return nil
}
return fmt.Errorf("create tasks FTS table: %w", err)
}
if err := r.createFTSTriggers(); err != nil {
return err
}
if err := r.backfillFTS(); err != nil {
return err
}
return nil
}
// maybeDropLegacyExternalContentFTS drops the legacy external-content
// tasks_fts table (and its triggers) when the existing schema indicates
// the previous shape — `CREATE VIRTUAL TABLE … USING fts5(…, content='tasks',
// content_rowid='rowid')`. Older databases were created with that mode, which
// never populated the index in this codebase. Dropping lets migrateTaskFTS
// recreate it in internal-content mode and backfill from `tasks`. No-op when
// the table doesn't exist or is already internal-content.
func (r *Repository) maybeDropLegacyExternalContentFTS() error {
var sqlText string
err := r.db.QueryRow(
`SELECT sql FROM sqlite_master WHERE type='table' AND name='tasks_fts'`,
).Scan(&sqlText)
if err != nil {
if err == sql.ErrNoRows {
return nil
}
return fmt.Errorf("inspect legacy tasks FTS table: %w", err)
}
if !strings.Contains(sqlText, "content='tasks'") &&
!strings.Contains(sqlText, `content="tasks"`) {
return nil // already internal-content
}
for _, statement := range []string{
`DROP TRIGGER IF EXISTS tasks_fts_insert`,
`DROP TRIGGER IF EXISTS tasks_fts_update`,
`DROP TRIGGER IF EXISTS tasks_fts_delete`,
`DROP TABLE IF EXISTS tasks_fts`,
} {
if _, err := r.db.Exec(statement); err != nil {
return fmt.Errorf("drop legacy tasks FTS object: %w", err)
}
}
return nil
}
// createFTSTriggers installs INSERT/UPDATE/DELETE triggers to keep the FTS
// index in sync. tasks_fts is an internal-content FTS5 table, so plain
// INSERT/DELETE statements drive the index — the 'delete' command literal
// is reserved for external-content mode and raises "SQL logic error" here
// (the prior implementation broke every UPDATE on tasks).
func (r *Repository) createFTSTriggers() error {
for _, statement := range []string{
`DROP TRIGGER IF EXISTS tasks_fts_insert`,
`DROP TRIGGER IF EXISTS tasks_fts_update`,
`DROP TRIGGER IF EXISTS tasks_fts_delete`,
`CREATE TRIGGER IF NOT EXISTS tasks_fts_insert AFTER INSERT ON tasks BEGIN
INSERT INTO tasks_fts(rowid, title, description, identifier)
VALUES (new.rowid, new.title, COALESCE(new.description,''), COALESCE(new.identifier,''));
END`,
`CREATE TRIGGER IF NOT EXISTS tasks_fts_update AFTER UPDATE ON tasks BEGIN
DELETE FROM tasks_fts WHERE rowid = old.rowid;
INSERT INTO tasks_fts(rowid, title, description, identifier)
VALUES (new.rowid, new.title, COALESCE(new.description,''), COALESCE(new.identifier,''));
END`,
`CREATE TRIGGER IF NOT EXISTS tasks_fts_delete AFTER DELETE ON tasks BEGIN
DELETE FROM tasks_fts WHERE rowid = old.rowid;
END`,
} {
if _, err := r.db.Exec(statement); err != nil {
return fmt.Errorf("create tasks FTS trigger: %w", err)
}
}
return nil
}
// backfillFTS populates the FTS index from existing task rows.
func (r *Repository) backfillFTS() error {
if _, err := r.db.Exec(`
INSERT OR IGNORE INTO tasks_fts(rowid, title, description, identifier)
SELECT rowid, title, COALESCE(description,''), COALESCE(identifier,'') FROM tasks
`); err != nil {
return fmt.Errorf("backfill tasks FTS: %w", err)
}
return nil
}
// migrateTaskPriorityToText converts the tasks.priority column from INTEGER to
// TEXT with a CHECK constraint and 'medium' default. It is idempotent: when
// the column is already TEXT (or the tasks table does not yet exist) the
// function returns silently. All existing integer values are remapped to
// 'medium' per spec — the integer was not surfaced anywhere meaningful.
// Returns an error so the migration runner can log a meaningful message;
// the recreate is wrapped in a tx so failures don't half-modify the DB.
func (r *Repository) migrateTaskPriorityToText() error {
if !r.tasksTableExists() {
return nil
}
if !r.taskPriorityIsInteger() {
return nil
}
if err := r.runTaskPriorityRecreate(); err != nil {
return err
}
if r.log != nil {
r.log.Info("migration applied", zap.String("name", "tasks.priority_text_rebuild"))
}
return nil
}
// tasksTableExists returns true when the `tasks` table is present.
func (r *Repository) tasksTableExists() bool {
var exists int
err := r.db.QueryRow(
"SELECT 1 FROM sqlite_master WHERE type='table' AND name='tasks'",
).Scan(&exists)
return err == nil && exists == 1
}
// taskPriorityIsInteger returns true when tasks.priority has INTEGER type.
// SQLite stores type info via PRAGMA table_info; we look for the legacy type.
func (r *Repository) taskPriorityIsInteger() bool {
rows, err := r.db.Queryx(`PRAGMA table_info(tasks)`)
if err != nil {
return false
}
defer func() { _ = rows.Close() }()
for rows.Next() {
var cid int
var name, ctype string
var notnull, pk int
var dflt sql.NullString
if err := rows.Scan(&cid, &name, &ctype, &notnull, &dflt, &pk); err != nil {
return false
}
if name == "priority" {
return strings.EqualFold(ctype, "INTEGER")
}
}
return false
}
// runTaskPriorityRecreate performs the SQLite table-recreate dance to change
// tasks.priority from INTEGER to TEXT. The whole sequence runs on a single
// connection grabbed via db.Conn so PRAGMA + statements share the same SQLite
// session — matters for :memory: databases that are connection-local.
//
// The recreate dance itself is idempotent: each step works against the
// current schema, and tasks_priority_new is rebuilt fresh every run.
func (r *Repository) runTaskPriorityRecreate() error {
ctx := context.Background()
conn, err := r.db.Conn(ctx)
if err != nil {
return fmt.Errorf("acquire migration connection: %w", err)
}
defer func() { _ = conn.Close() }()
if _, err := conn.ExecContext(ctx, `PRAGMA foreign_keys=OFF`); err != nil {
return fmt.Errorf("disable foreign keys: %w", err)
}
defer func() { _, _ = conn.ExecContext(ctx, `PRAGMA foreign_keys=ON`) }()
// archived_by_cascade_id is added to the canonical tasks shape by
// internal/task/repository/sqlite/base.go runMigrations() (line 222)
// AFTER initTaskSchema creates the legacy INTEGER-priority table
// but BEFORE the office migrations run. On test fixtures that seed
// a pre-cascade legacy schema (see TestMigrate_PriorityIntegerToText)
// the column is absent, add it before the recreate SELECT. The legacy
// fixtures used by the priority migration predate several of these columns,
// while current installs have already received them from the task owner.
legacyColumns := []struct {
name string
stmt string
}{
{"archived_by_cascade_id", `ALTER TABLE tasks ADD COLUMN archived_by_cascade_id TEXT DEFAULT ''`},
{"wip_admitted", `ALTER TABLE tasks ADD COLUMN wip_admitted INTEGER NOT NULL DEFAULT 1`},
{"queued_for_step_id", `ALTER TABLE tasks ADD COLUMN queued_for_step_id TEXT NOT NULL DEFAULT ''`},
{"queued_at", `ALTER TABLE tasks ADD COLUMN queued_at TIMESTAMP`},
{"autopilot_enabled", `ALTER TABLE tasks ADD COLUMN autopilot_enabled INTEGER NOT NULL DEFAULT 0`},
{"external_id", `ALTER TABLE tasks ADD COLUMN external_id TEXT COLLATE BINARY`},
{"external_id_settled_at", `ALTER TABLE tasks ADD COLUMN external_id_settled_at TIMESTAMP`},
{"assignee_user_id", `ALTER TABLE tasks ADD COLUMN assignee_user_id TEXT NOT NULL DEFAULT ''`},
{"assignment_generation", `ALTER TABLE tasks ADD COLUMN assignment_generation INTEGER NOT NULL DEFAULT 0`},
{"workflow_agent_overrides", `ALTER TABLE tasks ADD COLUMN workflow_agent_overrides TEXT`},
}
for _, column := range legacyColumns {
if _, err := conn.ExecContext(ctx, column.stmt); err != nil && !db.IsDuplicateColumnError(err) {
return fmt.Errorf("add legacy tasks.%s: %w", column.name, err)
}
}
for _, stmt := range taskPriorityMigrationStatements() {
if _, err := conn.ExecContext(ctx, stmt); err != nil {
return fmt.Errorf("priority migration step failed: %w", err)
}
}
return nil
}
// taskPriorityMigrationStatements returns the ordered SQL statements that
// recreate the tasks table with a TEXT priority column AND drop the
// legacy office columns retired in Phase 4 of task-model-unification
// (requires_approval, execution_policy, execution_state). Existing
// integer priority values are mapped to 'medium' as the spec requires.
//
// The migration runs once when the existing tasks.priority column is
// still INTEGER. After it lands, the table matches the final shape for
// kanban+office unification: stage progression is owned by the
// workflow engine, so the legacy policy/state columns are gone.
func taskPriorityMigrationStatements() []string {
return []string{
// ADR 0005 Wave F dropped assignee_agent_profile_id from the
// canonical tasks shape. Per-task runner now lives in
// workflow_step_participants. Old INTEGER-priority rows that
// still carry the column have it discarded by the SELECT below.
`CREATE TABLE tasks_priority_new (
id TEXT PRIMARY KEY,
workspace_id TEXT NOT NULL DEFAULT '',
workflow_id TEXT NOT NULL DEFAULT '',
workflow_step_id TEXT NOT NULL DEFAULT '',
workflow_agent_overrides TEXT,
title TEXT NOT NULL,
description TEXT DEFAULT '',
state TEXT DEFAULT 'TODO',
priority TEXT NOT NULL DEFAULT 'medium'
CHECK (priority IN ('critical','high','medium','low')),
position INTEGER DEFAULT 0,
wip_admitted INTEGER NOT NULL DEFAULT 1,
queued_for_step_id TEXT NOT NULL DEFAULT '',
queued_at TIMESTAMP,
metadata TEXT DEFAULT '{}',
is_ephemeral INTEGER NOT NULL DEFAULT 0,
parent_id TEXT DEFAULT '',
autopilot_enabled INTEGER NOT NULL DEFAULT 0,
archived_at TIMESTAMP,
archived_by_cascade_id TEXT DEFAULT '',
created_at TIMESTAMP NOT NULL,
updated_at TIMESTAMP NOT NULL,
origin TEXT DEFAULT 'manual',
project_id TEXT DEFAULT '',
labels TEXT DEFAULT '[]',
identifier TEXT,
checkout_agent_id TEXT,
checkout_at TIMESTAMP,
checkout_run_id TEXT,
external_id TEXT COLLATE BINARY,
external_id_settled_at TIMESTAMP,
assignee_user_id TEXT NOT NULL DEFAULT '',
assignment_generation INTEGER NOT NULL DEFAULT 0
)`,
// archived_by_cascade_id and external_id/external_id_settled_at are
// added to the task schema by task/repository/sqlite/base.go
// runMigrations() via idempotent ALTER ADD COLUMN calls that run
// BEFORE this office recreate, as is assignee_user_id. If the recreate omitted them from the
// new shape: archived_by_cascade_id missing would 500
// httpArchiveTask -> HandoffService.ArchiveTaskTree (the CAS update
// in ArchiveTaskIfActive references it); external_id missing would
// silently drop task create-idempotency on any install that still
// needed this priority rebuild. Carry both over so they survive the
// recreate dance. external_id is not COALESCEd — NULL is its
// meaningful "no identity" state.
`INSERT INTO tasks_priority_new (
id, workspace_id, workflow_id, workflow_step_id, workflow_agent_overrides, title, description,
state, priority, position, wip_admitted, queued_for_step_id, queued_at, metadata, is_ephemeral, parent_id, autopilot_enabled,
archived_at, archived_by_cascade_id, created_at, updated_at,
origin, project_id,
labels, identifier,
checkout_agent_id, checkout_at, checkout_run_id,
external_id, external_id_settled_at, assignee_user_id, assignment_generation
) SELECT
id, COALESCE(workspace_id,''), COALESCE(workflow_id,''),
COALESCE(workflow_step_id,''), workflow_agent_overrides, title, COALESCE(description,''),
COALESCE(state,'TODO'), 'medium', COALESCE(position,0),
COALESCE(wip_admitted,1), COALESCE(queued_for_step_id,''), queued_at,
COALESCE(metadata,'{}'), COALESCE(is_ephemeral,0),
COALESCE(parent_id,''), COALESCE(autopilot_enabled,0), archived_at,
COALESCE(archived_by_cascade_id,''),
created_at, updated_at,
COALESCE(origin,'manual'),
COALESCE(project_id,''),
COALESCE(labels,'[]'), identifier,
checkout_agent_id, checkout_at, checkout_run_id,
external_id, external_id_settled_at,
COALESCE(assignee_user_id,''), COALESCE(assignment_generation,0)
FROM tasks`,
`DROP TABLE tasks`,
`ALTER TABLE tasks_priority_new RENAME TO tasks`,
`CREATE INDEX IF NOT EXISTS idx_tasks_workflow_id ON tasks(workflow_id)`,
`CREATE INDEX IF NOT EXISTS idx_tasks_workflow_step_id ON tasks(workflow_step_id)`,
`CREATE INDEX IF NOT EXISTS idx_tasks_archived_at ON tasks(archived_at)`,
`CREATE INDEX IF NOT EXISTS idx_tasks_workspace_id ON tasks(workspace_id)`,
`CREATE INDEX IF NOT EXISTS idx_tasks_workspace_archived ON tasks(workspace_id, archived_at)`,
`CREATE INDEX IF NOT EXISTS idx_tasks_project_id ON tasks(project_id)`,
// idx_tasks_assignee was removed in ADR 0005 Wave F when the
// per-task assignee moved to workflow_step_participants.
//
// uniq_tasks_external_id enforces task create-idempotency
// (docs/specs/tasks/system-design/external-id-idempotency.md). DROP TABLE tasks above
// silently drops every index on the old table, this one included —
// unlike a plain ALTER TABLE ADD COLUMN, recreating the table means
// every index must be explicitly relisted here or it is gone from
// any install that still needs this historical rebuild.
`CREATE UNIQUE INDEX IF NOT EXISTS uniq_tasks_external_id ON tasks(workspace_id, external_id) WHERE external_id IS NOT NULL`,
}
}