@cat-factory/worker 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Savin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/migrations/0001_init.sql

@@ -0,0 +1,57 @@
+-- Initial schema for the Agent Architecture Board.
+--
+-- Every aggregate is scoped by `workspace_id` and keyed by a composite primary
+-- key (workspace_id, id), so the stable seed ids can be reused across boards.
+-- JSON-shaped fields (dependsOn, features, pipeline agentKinds, execution steps)
+-- are stored as TEXT and (de)serialised in the repository mappers.
+
+CREATE TABLE workspaces (
+  id         TEXT    NOT NULL PRIMARY KEY,
+  name       TEXT    NOT NULL,
+  created_at INTEGER NOT NULL
+);
+
+CREATE TABLE blocks (
+  workspace_id         TEXT    NOT NULL,
+  id                   TEXT    NOT NULL,
+  title                TEXT    NOT NULL,
+  type                 TEXT    NOT NULL,
+  description          TEXT    NOT NULL DEFAULT '',
+  pos_x                REAL    NOT NULL DEFAULT 0,
+  pos_y                REAL    NOT NULL DEFAULT 0,
+  status               TEXT    NOT NULL,
+  progress             REAL    NOT NULL DEFAULT 0,
+  depends_on           TEXT    NOT NULL DEFAULT '[]',
+  execution_id         TEXT,
+  level                TEXT    NOT NULL DEFAULT 'frame',
+  parent_id            TEXT,
+  confidence           REAL,
+  confidence_threshold REAL,
+  module_name          TEXT,
+  features             TEXT,
+  PRIMARY KEY (workspace_id, id)
+);
+
+CREATE INDEX idx_blocks_parent ON blocks (workspace_id, parent_id);
+
+CREATE TABLE pipelines (
+  workspace_id TEXT NOT NULL,
+  id           TEXT NOT NULL,
+  name         TEXT NOT NULL,
+  agent_kinds  TEXT NOT NULL DEFAULT '[]',
+  PRIMARY KEY (workspace_id, id)
+);
+
+CREATE TABLE executions (
+  workspace_id  TEXT    NOT NULL,
+  id            TEXT    NOT NULL,
+  block_id      TEXT    NOT NULL,
+  pipeline_id   TEXT    NOT NULL,
+  pipeline_name TEXT    NOT NULL,
+  steps         TEXT    NOT NULL DEFAULT '[]',
+  current_step  INTEGER NOT NULL DEFAULT 0,
+  status        TEXT    NOT NULL,
+  PRIMARY KEY (workspace_id, id)
+);
+
+CREATE UNIQUE INDEX idx_executions_block ON executions (workspace_id, block_id);

package/migrations/0002_execution_workflow.sql

@@ -0,0 +1,13 @@
+-- Durable execution support. `updated_at` is a lease the cron sweeper uses to
+-- find runs that are still `running` but whose Workflows instance has died;
+-- `error` records an agent failure that survived the per-step retries;
+-- `workflow_instance_id` records the durable instance driving the run (equal to
+-- the execution id today, stored explicitly so that can change without a schema
+-- change). Existing rows default safely so tick-mode is unaffected.
+
+ALTER TABLE executions ADD COLUMN updated_at INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE executions ADD COLUMN error TEXT;
+ALTER TABLE executions ADD COLUMN workflow_instance_id TEXT;
+
+-- Supports the sweeper's "running + stale lease" scan.
+CREATE INDEX idx_executions_running_lease ON executions (status, updated_at);

package/migrations/0003_token_usage.sql

@@ -0,0 +1,20 @@
+-- Spend safeguard ledger. One row per metered LLM call: the token counts and a
+-- cost estimate priced at record time (so historical rows stay stable even if
+-- pricing config changes). The budget is org-wide, so usage is summed across all
+-- workspaces for the current billing period via the created_at index.
+
+CREATE TABLE token_usage (
+  id            TEXT    NOT NULL PRIMARY KEY,
+  workspace_id  TEXT    NOT NULL,
+  execution_id  TEXT,
+  agent_kind    TEXT    NOT NULL,
+  provider      TEXT    NOT NULL,
+  model         TEXT    NOT NULL,
+  input_tokens  INTEGER NOT NULL DEFAULT 0,
+  output_tokens INTEGER NOT NULL DEFAULT 0,
+  cost_estimate REAL    NOT NULL DEFAULT 0,
+  created_at    INTEGER NOT NULL
+);
+
+-- Supports the "sum usage since the start of this period" budget query.
+CREATE INDEX idx_token_usage_created ON token_usage (created_at);

package/migrations/0004_github_projections.sql

@@ -0,0 +1,141 @@
+-- GitHub integration: local projections of the GitHub data cat-factory reads
+-- often, so the UI/agents don't hit the API on every read and aren't blocked by
+-- rate limits. Projections are kept fresh by webhook-driven incremental syncs,
+-- on-demand resyncs, and a periodic cron reconciliation pass.
+--
+-- Conventions follow the existing schema (0001/0003): aggregates are scoped by
+-- workspace via composite primary keys, timestamps are INTEGER epoch-ms, JSON is
+-- stored as TEXT, there are no foreign keys, and rows that disappear upstream are
+-- soft-deleted via a `deleted_at` tombstone (so a webhook delete and a later full
+-- reconciliation converge without losing audit history).
+
+-- One GitHub App installation per workspace. Also caches the short-lived (~1h)
+-- installation access token + its expiry so we don't re-mint on every call; a
+-- lost cache is harmless (the token is cheaply re-derivable from the app JWT).
+CREATE TABLE github_installations (
+  installation_id   INTEGER NOT NULL PRIMARY KEY,
+  workspace_id      TEXT    NOT NULL,
+  account_login     TEXT    NOT NULL,
+  target_type       TEXT    NOT NULL,
+  cached_token      TEXT,
+  token_expires_at  INTEGER,
+  created_at        INTEGER NOT NULL,
+  deleted_at        INTEGER
+);
+-- A workspace connects to at most one *live* installation. Partial so a
+-- tombstoned binding doesn't block reconnecting the workspace to a new one.
+CREATE UNIQUE INDEX idx_gh_install_workspace
+  ON github_installations (workspace_id)
+  WHERE deleted_at IS NULL;
+
+CREATE TABLE github_repos (
+  workspace_id     TEXT    NOT NULL,
+  github_id        INTEGER NOT NULL,
+  installation_id  INTEGER NOT NULL,
+  owner            TEXT    NOT NULL,
+  name             TEXT    NOT NULL,
+  default_branch   TEXT,
+  private          INTEGER NOT NULL DEFAULT 0,
+  block_id         TEXT,                       -- optional link to a board block
+  etag             TEXT,
+  synced_at        INTEGER NOT NULL,
+  deleted_at       INTEGER,
+  PRIMARY KEY (workspace_id, github_id)
+);
+CREATE INDEX idx_gh_repos_install ON github_repos (installation_id);
+
+CREATE TABLE github_branches (
+  workspace_id     TEXT    NOT NULL,
+  repo_github_id   INTEGER NOT NULL,
+  name             TEXT    NOT NULL,
+  head_sha         TEXT    NOT NULL,
+  protected        INTEGER NOT NULL DEFAULT 0,
+  synced_at        INTEGER NOT NULL,
+  deleted_at       INTEGER,
+  PRIMARY KEY (workspace_id, repo_github_id, name)
+);
+
+CREATE TABLE github_pull_requests (
+  workspace_id     TEXT    NOT NULL,
+  repo_github_id   INTEGER NOT NULL,
+  number           INTEGER NOT NULL,
+  github_id        INTEGER NOT NULL,
+  title            TEXT    NOT NULL,
+  state            TEXT    NOT NULL,
+  head_ref         TEXT,
+  base_ref         TEXT,
+  head_sha         TEXT,
+  merged           INTEGER NOT NULL DEFAULT 0,
+  author           TEXT,
+  gh_updated_at    INTEGER,
+  synced_at        INTEGER NOT NULL,
+  deleted_at       INTEGER,
+  PRIMARY KEY (workspace_id, repo_github_id, number)
+);
+-- Supports the board's "open PRs for this workspace" reads.
+CREATE INDEX idx_gh_pr_state ON github_pull_requests (workspace_id, state);
+
+CREATE TABLE github_issues (
+  workspace_id     TEXT    NOT NULL,
+  repo_github_id   INTEGER NOT NULL,
+  number           INTEGER NOT NULL,
+  github_id        INTEGER NOT NULL,
+  title            TEXT    NOT NULL,
+  state            TEXT    NOT NULL,
+  author           TEXT,
+  labels           TEXT    NOT NULL DEFAULT '[]',
+  gh_updated_at    INTEGER,
+  synced_at        INTEGER NOT NULL,
+  deleted_at       INTEGER,
+  PRIMARY KEY (workspace_id, repo_github_id, number)
+);
+
+CREATE TABLE github_commits (
+  workspace_id     TEXT    NOT NULL,
+  repo_github_id   INTEGER NOT NULL,
+  sha              TEXT    NOT NULL,
+  message          TEXT    NOT NULL,
+  author           TEXT,
+  authored_at      INTEGER,
+  synced_at        INTEGER NOT NULL,
+  PRIMARY KEY (workspace_id, repo_github_id, sha)
+);
+
+CREATE TABLE github_check_runs (
+  workspace_id     TEXT    NOT NULL,
+  repo_github_id   INTEGER NOT NULL,
+  github_id        INTEGER NOT NULL,
+  head_sha         TEXT    NOT NULL,
+  name             TEXT    NOT NULL,
+  status           TEXT    NOT NULL,
+  conclusion       TEXT,
+  synced_at        INTEGER NOT NULL,
+  PRIMARY KEY (workspace_id, repo_github_id, github_id)
+);
+-- Supports "what is the CI status for this commit?" gating reads.
+CREATE INDEX idx_gh_checks_sha ON github_check_runs (workspace_id, repo_github_id, head_sha);
+
+-- Incremental sync bookkeeping per (repo, entity kind): the ETag for
+-- conditional GETs and/or the `since` timestamp for delta listing.
+CREATE TABLE github_sync_cursors (
+  workspace_id     TEXT    NOT NULL,
+  repo_github_id   INTEGER NOT NULL,
+  kind             TEXT    NOT NULL,
+  etag             TEXT,
+  last_synced_at   INTEGER,
+  since_iso        TEXT,
+  PRIMARY KEY (workspace_id, repo_github_id, kind)
+);
+
+-- Rate-limit ledger: one row per observed `x-ratelimit-*` snapshot, imitating
+-- the token_usage spend ledger. Lets us track headroom and back off proactively.
+CREATE TABLE github_rate_limits (
+  id               TEXT    NOT NULL PRIMARY KEY,
+  installation_id  INTEGER NOT NULL,
+  resource         TEXT    NOT NULL,
+  limit_total      INTEGER,
+  remaining        INTEGER,
+  reset_at         INTEGER,
+  observed_at      INTEGER NOT NULL
+);
+CREATE INDEX idx_gh_ratelimit_observed ON github_rate_limits (observed_at);

package/migrations/0005_block_fragments.sql

@@ -0,0 +1,4 @@
+-- Per-block selection of best-practice prompt fragments. Stored as a JSON array
+-- of fragment ids (TEXT), mirroring the existing `features` column; (de)serialised
+-- in the repository mappers. Nullable: existing blocks have no selection.
+ALTER TABLE blocks ADD COLUMN fragment_ids TEXT;

package/migrations/0005_confluence.sql

@@ -0,0 +1,48 @@
+-- Confluence integration: a workspace's connection to a Confluence Cloud site,
+-- and local projections of the requirement/RFC/PRD pages it has imported. The
+-- cached page body backs both the doc → board planner and the agent-context
+-- injection, so neither path re-fetches the page on every read.
+--
+-- Conventions follow the existing schema (0001/0004): aggregates are scoped by
+-- workspace, timestamps are INTEGER epoch-ms, there are no foreign keys, and a
+-- soft-delete `deleted_at` tombstone with a partial unique index lets a workspace
+-- disconnect and reconnect without the binding colliding.
+
+-- At most one *live* Confluence connection per workspace. The API token is stored
+-- as plaintext-at-rest (like github_installations.cached_token) and is never sent
+-- on the wire; it is read only by the import path to authenticate to the site.
+CREATE TABLE confluence_connections (
+  workspace_id   TEXT    NOT NULL,
+  base_url       TEXT    NOT NULL,
+  account_email  TEXT    NOT NULL,
+  api_token      TEXT    NOT NULL,
+  created_at     INTEGER NOT NULL,
+  deleted_at     INTEGER,
+  PRIMARY KEY (workspace_id, account_email)
+);
+-- A workspace connects to at most one live site. Partial so a tombstoned binding
+-- doesn't block reconnecting the workspace to a new account.
+CREATE UNIQUE INDEX idx_confluence_conn_workspace
+  ON confluence_connections (workspace_id)
+  WHERE deleted_at IS NULL;
+
+-- One row per imported Confluence page. `body` holds the full storage-format
+-- XHTML (consumed by the planner); `excerpt` is a short plain-text preview.
+-- `linked_block_id` attaches the page to a board block as agent context.
+CREATE TABLE confluence_documents (
+  workspace_id     TEXT    NOT NULL,
+  page_id          TEXT    NOT NULL,
+  space_key        TEXT    NOT NULL,
+  title            TEXT    NOT NULL,
+  url              TEXT    NOT NULL,
+  version          INTEGER NOT NULL DEFAULT 0,
+  excerpt          TEXT    NOT NULL DEFAULT '',
+  body             TEXT    NOT NULL DEFAULT '',
+  linked_block_id  TEXT,
+  synced_at        INTEGER NOT NULL,
+  deleted_at       INTEGER,
+  PRIMARY KEY (workspace_id, page_id)
+);
+-- Supports the execution engine's "documents linked to this block" lookup.
+CREATE INDEX idx_confluence_docs_block
+  ON confluence_documents (workspace_id, linked_block_id);

package/migrations/0006_storage_retention.sql

@@ -0,0 +1,10 @@
+-- Storage & data-retention follow-ups (see docs/storage-and-retention.md).
+--
+-- The unbounded ledgers already have the indexes their retention sweeps need:
+-- token_usage.idx_token_usage_created (created_at) and
+-- github_rate_limits.idx_gh_ratelimit_observed (observed_at). github_commits is
+-- the one append-only projection without a column the retention pass can scan, so
+-- add an index on authored_at to keep the periodic `DELETE … WHERE authored_at <
+-- horizon` cheap (and bounded by the rows actually being reclaimed).
+
+CREATE INDEX idx_gh_commits_authored ON github_commits (authored_at);

package/migrations/0007_block_model.sql

@@ -0,0 +1,5 @@
+-- Per-block selection of the LLM model to run its agents with. Stored as the
+-- catalog model id (TEXT); resolved to a concrete provider/model at run time
+-- (see MODEL_CATALOG in @cat-factory/core). Nullable: existing blocks have no
+-- selection and fall back to the agent routing's default model.
+ALTER TABLE blocks ADD COLUMN model_id TEXT;

package/migrations/0008_environments.sql

@@ -0,0 +1,59 @@
+-- Ephemeral environment provider integration: a workspace's binding to its own
+-- self-rolled environment management API (described by a declarative manifest),
+-- and the registry of environments that have been provisioned from it.
+--
+-- Conventions follow the existing schema (0001/0004/0005): aggregates are scoped
+-- by workspace, timestamps are INTEGER epoch-ms, there are no foreign keys, and a
+-- soft-delete `deleted_at` tombstone with a partial unique index lets a workspace
+-- re-register without the binding colliding.
+--
+-- Credentials are stored as opaque ciphertext (AES-256-GCM via SecretCipher),
+-- never plaintext: `secrets_cipher` holds the per-tenant management-API secret
+-- bundle; `access_cipher` holds a provisioned env's own access creds; and
+-- `provision_fields_cipher` holds the fields captured at provision time that
+-- status/teardown calls interpolate.
+
+-- At most one *live* environment provider per workspace.
+CREATE TABLE environment_connections (
+  workspace_id    TEXT    NOT NULL,
+  provider_id     TEXT    NOT NULL,
+  label           TEXT    NOT NULL,
+  base_url        TEXT    NOT NULL,
+  manifest_json   TEXT    NOT NULL,
+  secrets_cipher  TEXT    NOT NULL,
+  created_at      INTEGER NOT NULL,
+  deleted_at      INTEGER,
+  PRIMARY KEY (workspace_id, provider_id)
+);
+-- A workspace registers at most one live provider. Partial so a tombstoned
+-- binding doesn't block re-registering the workspace with a new provider.
+CREATE UNIQUE INDEX idx_environment_conn_workspace
+  ON environment_connections (workspace_id)
+  WHERE deleted_at IS NULL;
+
+-- One row per provisioned environment.
+CREATE TABLE environments (
+  id                       TEXT    NOT NULL PRIMARY KEY,
+  workspace_id             TEXT    NOT NULL,
+  block_id                 TEXT,
+  execution_id             TEXT,
+  provider_id              TEXT    NOT NULL,
+  external_id              TEXT,
+  url                      TEXT,
+  status                   TEXT    NOT NULL,
+  access_cipher            TEXT,
+  provision_fields_cipher  TEXT,
+  created_at               INTEGER NOT NULL,
+  expires_at               INTEGER,
+  last_error               TEXT,
+  deleted_at               INTEGER
+);
+-- Discovery: the live environment provisioned for a board block (consumed by the
+-- execution engine to enrich downstream tester context).
+CREATE INDEX idx_environments_block
+  ON environments (workspace_id, block_id)
+  WHERE deleted_at IS NULL;
+-- TTL sweep: the cron tears down environments whose expiry has elapsed.
+CREATE INDEX idx_environments_expiry
+  ON environments (expires_at)
+  WHERE deleted_at IS NULL AND expires_at IS NOT NULL;

package/migrations/0009_block_test_target.sql

@@ -0,0 +1,6 @@
+-- Per-block choice of where acceptance / Playwright tests run: 'github_actions'
+-- (project CI, against a service spun up in the same run) or 'ephemeral_env'
+-- (the provisioned ephemeral environment for the run). Stored as TEXT; the
+-- acceptance-testing agents fold it into their prompt. Nullable: existing blocks
+-- have no preference recorded.
+ALTER TABLE blocks ADD COLUMN test_target TEXT;

package/migrations/0010_block_pull_request.sql

@@ -0,0 +1,5 @@
+-- The pull request a block's implementation ("implementer") agent opened for its
+-- work: a small JSON ref ({ url, number?, branch? }) recorded on a task once its
+-- container agent pushes a branch and opens a PR. Stored as TEXT and
+-- (de)serialised in the repository mappers. Nullable: blocks with no PR yet.
+ALTER TABLE blocks ADD COLUMN pull_request TEXT;

package/migrations/0010_bootstrap.sql

@@ -0,0 +1,44 @@
+-- Repo-bootstrap feature: a workspace-scoped, CRUD-managed list of "reference
+-- architectures" (base/golden-template repos new repositories are bootstrapped
+-- from) and a log of "bootstrap repo" jobs, one row per run with its outcome.
+--
+-- Conventions follow the existing schema (0001/0004/0005/0008): aggregates are
+-- scoped by workspace, timestamps are INTEGER epoch-ms, there are no foreign
+-- keys, and reference architectures carry a soft-delete `deleted_at` tombstone.
+-- Bootstrap jobs are an append-mostly log (no soft delete): they are inserted as
+-- `running` and updated in place to their terminal `succeeded`/`failed` state.
+
+-- The managed reference architecture list.
+CREATE TABLE reference_architectures (
+  id                   TEXT    NOT NULL PRIMARY KEY,
+  workspace_id         TEXT    NOT NULL,
+  name                 TEXT    NOT NULL,
+  description          TEXT    NOT NULL DEFAULT '',
+  repo_owner           TEXT    NOT NULL,
+  repo_name            TEXT    NOT NULL,
+  default_instructions TEXT    NOT NULL DEFAULT '',
+  created_at           INTEGER NOT NULL,
+  updated_at           INTEGER NOT NULL,
+  deleted_at           INTEGER
+);
+CREATE INDEX idx_reference_architectures_workspace
+  ON reference_architectures (workspace_id)
+  WHERE deleted_at IS NULL;
+
+-- One row per "bootstrap repo" run.
+CREATE TABLE bootstrap_jobs (
+  id                          TEXT    NOT NULL PRIMARY KEY,
+  workspace_id                TEXT    NOT NULL,
+  reference_architecture_id   TEXT    NOT NULL,
+  reference_architecture_name TEXT    NOT NULL,
+  repo_name                   TEXT    NOT NULL,
+  repo_owner                  TEXT,
+  repo_url                    TEXT,
+  instructions                TEXT    NOT NULL DEFAULT '',
+  status                      TEXT    NOT NULL,
+  error                       TEXT,
+  created_at                  INTEGER NOT NULL,
+  updated_at                  INTEGER NOT NULL
+);
+CREATE INDEX idx_bootstrap_jobs_workspace
+  ON bootstrap_jobs (workspace_id, created_at);

package/migrations/0011_repo_blueprints.sql

@@ -0,0 +1,28 @@
+-- Board-scan feature: the persisted "repository blueprint" — a decomposition of
+-- one repository into the canonical service → modules → features tree, anchored
+-- to codebase paths. Exactly one blueprint is kept per (workspace, repo): a
+-- re-scan replaces it in place, so the row is the single current map rather than
+-- an append-only log.
+--
+-- Conventions follow the existing schema (0001/0004/0010): aggregates are scoped
+-- by workspace, timestamps are INTEGER epoch-ms, and there are no foreign keys.
+-- The tree is stored as a JSON blob in `service_json` (read/written whole), like
+-- other structured-but-opaque payloads in the projections.
+
+CREATE TABLE repo_blueprints (
+  id           TEXT    NOT NULL PRIMARY KEY,
+  workspace_id TEXT    NOT NULL,
+  repo_owner   TEXT    NOT NULL,
+  repo_name    TEXT    NOT NULL,
+  source       TEXT    NOT NULL,
+  service_json TEXT    NOT NULL,
+  created_at   INTEGER NOT NULL,
+  updated_at   INTEGER NOT NULL
+);
+
+-- One blueprint per repository within a workspace (enforces the upsert key).
+CREATE UNIQUE INDEX idx_repo_blueprints_repo
+  ON repo_blueprints (workspace_id, repo_owner, repo_name);
+
+CREATE INDEX idx_repo_blueprints_workspace
+  ON repo_blueprints (workspace_id, updated_at);

package/migrations/0012_document_sources.sql

@@ -0,0 +1,62 @@
+-- Document-source integration: a workspace's connections to external document
+-- sources (Confluence, Notion, …) and local projections of the requirement /
+-- RFC / PRD pages it has imported from them. Supersedes the Confluence-specific
+-- tables (migration 0005): a `source` discriminator tags every row, so one pair
+-- of tables serves every provider. The cached page body (normalized to Markdown)
+-- backs both the doc → board planner and the agent-context injection.
+--
+-- Conventions follow the existing schema: aggregates are scoped by workspace,
+-- timestamps are INTEGER epoch-ms, there are no foreign keys, and a soft-delete
+-- `deleted_at` tombstone lets a workspace disconnect and reconnect.
+
+-- At most one live connection per (workspace, source). The credential bag is a
+-- JSON object of string→string, stored plaintext-at-rest (like the cached GitHub
+-- installation token) and never sent on the wire; it is read only by the import
+-- path to authenticate to the source.
+CREATE TABLE document_connections (
+  workspace_id  TEXT    NOT NULL,
+  source        TEXT    NOT NULL,
+  credentials   TEXT    NOT NULL,
+  label         TEXT    NOT NULL DEFAULT '',
+  created_at    INTEGER NOT NULL,
+  deleted_at    INTEGER,
+  PRIMARY KEY (workspace_id, source)
+);
+
+-- One row per imported page. `body` holds the normalized Markdown (consumed by
+-- the planner); `excerpt` is a short plain-text preview. `linked_block_id`
+-- attaches the page to a board block as agent context.
+CREATE TABLE documents (
+  workspace_id     TEXT    NOT NULL,
+  source           TEXT    NOT NULL,
+  external_id      TEXT    NOT NULL,
+  title            TEXT    NOT NULL,
+  url              TEXT    NOT NULL,
+  excerpt          TEXT    NOT NULL DEFAULT '',
+  body             TEXT    NOT NULL DEFAULT '',
+  linked_block_id  TEXT,
+  synced_at        INTEGER NOT NULL,
+  deleted_at       INTEGER,
+  PRIMARY KEY (workspace_id, source, external_id)
+);
+-- Supports the execution engine's "documents linked to this block" lookup.
+CREATE INDEX idx_documents_block
+  ON documents (workspace_id, linked_block_id);
+
+-- Carry over any live Confluence connections/documents from migration 0005, then
+-- drop the superseded tables. Only live rows are migrated (the new schema keys
+-- connections by (workspace_id, source), so historical tombstones can't collide).
+INSERT INTO document_connections (workspace_id, source, credentials, label, created_at, deleted_at)
+  SELECT workspace_id, 'confluence',
+         json_object('baseUrl', base_url, 'accountEmail', account_email, 'apiToken', api_token),
+         base_url, created_at, NULL
+  FROM confluence_connections
+  WHERE deleted_at IS NULL;
+
+INSERT INTO documents (workspace_id, source, external_id, title, url, excerpt, body, linked_block_id, synced_at, deleted_at)
+  SELECT workspace_id, 'confluence', page_id, title, url, excerpt, body, linked_block_id, synced_at, NULL
+  FROM confluence_documents
+  WHERE deleted_at IS NULL;
+
+DROP TABLE confluence_documents;
+DROP TABLE confluence_connections;

package/migrations/0013_runner_pools.sql

@@ -0,0 +1,32 @@
+-- Self-hosted runner-pool integration ("bring your own infra"): a workspace's
+-- binding to its own container runner pool's scheduler API (described by a
+-- declarative manifest), used instead of per-run Cloudflare Containers for the
+-- repo-operating coding jobs.
+--
+-- Conventions follow the existing schema (esp. 0008_environments): aggregates are
+-- scoped by workspace, timestamps are INTEGER epoch-ms, there are no foreign keys,
+-- and a soft-delete `deleted_at` tombstone with a partial unique index lets a
+-- workspace re-register without the binding colliding.
+--
+-- The per-tenant scheduler-API secret bundle is stored as opaque ciphertext
+-- (AES-256-GCM via SecretCipher), never plaintext, in `secrets_cipher`. There is
+-- no per-job table: the execution engine already tracks each job durably and the
+-- pool is addressed by the cat-factory job id, so poll/release need no extra row.
+
+-- At most one *live* runner pool per workspace.
+CREATE TABLE runner_pool_connections (
+  workspace_id    TEXT    NOT NULL,
+  provider_id     TEXT    NOT NULL,
+  label           TEXT    NOT NULL,
+  base_url        TEXT    NOT NULL,
+  manifest_json   TEXT    NOT NULL,
+  secrets_cipher  TEXT    NOT NULL,
+  created_at      INTEGER NOT NULL,
+  deleted_at      INTEGER,
+  PRIMARY KEY (workspace_id, provider_id)
+);
+-- A workspace registers at most one live pool. Partial so a tombstoned binding
+-- doesn't block re-registering the workspace with a new pool.
+CREATE UNIQUE INDEX idx_runner_pool_conn_workspace
+  ON runner_pool_connections (workspace_id)
+  WHERE deleted_at IS NULL;

package/migrations/0014_task_sources.sql

@@ -0,0 +1,49 @@
+-- Task-source integration: a workspace's connections to external task/issue
+-- trackers (Jira, …) and local projections of the individual issues it has
+-- imported from them. A sibling of the document-source tables (migration 0012),
+-- but task-shaped: an issue is a structured record (status/type/assignee/…) used
+-- as extra agent context, not a page body expanded into board structure.
+--
+-- Conventions follow the existing schema: aggregates are scoped by workspace,
+-- timestamps are INTEGER epoch-ms, there are no foreign keys, and a soft-delete
+-- `deleted_at` tombstone lets a workspace disconnect and reconnect.
+
+-- At most one live connection per (workspace, source). The credential bag is a
+-- JSON object of string→string, encrypted at rest (AES-256-GCM envelope) and
+-- never sent on the wire; it is read only by the import path to authenticate.
+CREATE TABLE task_connections (
+  workspace_id  TEXT    NOT NULL,
+  source        TEXT    NOT NULL,
+  credentials   TEXT    NOT NULL,
+  label         TEXT    NOT NULL DEFAULT '',
+  created_at    INTEGER NOT NULL,
+  deleted_at    INTEGER,
+  PRIMARY KEY (workspace_id, source)
+);
+
+-- One row per imported issue. The structured fields back the agent-context
+-- injection; `labels` and `comments` are JSON; `description` is normalized
+-- Markdown; `excerpt` is a short plain-text preview. `linked_block_id` attaches
+-- the issue to a board block as agent context.
+CREATE TABLE tasks (
+  workspace_id     TEXT    NOT NULL,
+  source           TEXT    NOT NULL,
+  external_id      TEXT    NOT NULL,  -- issue key, e.g. PROJ-123
+  title            TEXT    NOT NULL,
+  url              TEXT    NOT NULL,
+  status           TEXT    NOT NULL DEFAULT '',
+  type             TEXT    NOT NULL DEFAULT '',
+  assignee         TEXT,
+  priority         TEXT,
+  labels           TEXT    NOT NULL DEFAULT '[]',  -- JSON array of strings
+  description      TEXT    NOT NULL DEFAULT '',
+  comments         TEXT    NOT NULL DEFAULT '[]',  -- JSON array of {author,createdAt,body}
+  excerpt          TEXT    NOT NULL DEFAULT '',
+  linked_block_id  TEXT,
+  synced_at        INTEGER NOT NULL,
+  deleted_at       INTEGER,
+  PRIMARY KEY (workspace_id, source, external_id)
+);
+-- Supports the execution engine's "issues linked to this block" lookup.
+CREATE INDEX idx_tasks_block
+  ON tasks (workspace_id, linked_block_id);

package/migrations/0015_bootstrap_freeform.sql

@@ -0,0 +1,32 @@
+-- Allow "bootstrap repo" runs with no reference architecture (freeform prompt).
+-- The original 0010 schema declared `reference_architecture_id` and
+-- `reference_architecture_name` NOT NULL; from-scratch runs leave them null, so
+-- relax both columns. SQLite can't drop a NOT NULL constraint in place, so we
+-- rebuild the table (12-step pattern: create new, copy, drop, rename, re-index).
+
+CREATE TABLE bootstrap_jobs_new (
+  id                          TEXT    NOT NULL PRIMARY KEY,
+  workspace_id                TEXT    NOT NULL,
+  reference_architecture_id   TEXT,
+  reference_architecture_name TEXT,
+  repo_name                   TEXT    NOT NULL,
+  repo_owner                  TEXT,
+  repo_url                    TEXT,
+  instructions                TEXT    NOT NULL DEFAULT '',
+  status                      TEXT    NOT NULL,
+  error                       TEXT,
+  created_at                  INTEGER NOT NULL,
+  updated_at                  INTEGER NOT NULL
+);
+
+INSERT INTO bootstrap_jobs_new
+  SELECT id, workspace_id, reference_architecture_id, reference_architecture_name,
+         repo_name, repo_owner, repo_url, instructions, status, error,
+         created_at, updated_at
+  FROM bootstrap_jobs;
+
+DROP TABLE bootstrap_jobs;
+ALTER TABLE bootstrap_jobs_new RENAME TO bootstrap_jobs;
+
+CREATE INDEX idx_bootstrap_jobs_workspace
+  ON bootstrap_jobs (workspace_id, created_at);

package/migrations/0016_workspace_owner.sql

@@ -0,0 +1,14 @@
+-- Workspace ownership. Until now every authenticated user could read and mutate
+-- EVERY workspace (the table had no owner column, and no route checked one) — a
+-- cross-tenant access-control hole. We add the owning GitHub user id so the API
+-- can scope list/read/write to the owner.
+--
+-- The column is nullable so the migration is additive. Rows created before this
+-- migration have NULL owner and are therefore NOT accessible once auth is
+-- enabled (NULL never equals a signed-in user's id) — the fail-closed choice.
+-- Such legacy boards must be re-created (or claimed by a manual UPDATE) by an
+-- operator. When auth is disabled (local dev / AUTH_DEV_OPEN), ownership is not
+-- enforced and all boards remain visible.
+ALTER TABLE workspaces ADD COLUMN owner_user_id INTEGER;
+
+CREATE INDEX idx_workspaces_owner ON workspaces (owner_user_id);

package/migrations/0017_accounts.sql

@@ -0,0 +1,52 @@
+-- Multi-tenant accounts. Until now a workspace was owned by a single GitHub user
+-- (migration 0016) and a GitHub App installation was bound exclusively to one
+-- workspace (migration 0004) — so a team of engineers could not share boards, and
+-- one GitHub account could not back several boards. This migration introduces an
+-- account tenancy layer:
+--
+--   * an `account` (a personal account-of-one, or an org) owns workspaces;
+--   * `memberships` map GitHub users to accounts with a role, so many engineers
+--     can see and use the same org's workspaces;
+--   * a GitHub App installation is bound to an account, so every workspace in that
+--     account can link the account's repos (repos are still linked *explicitly*
+--     per workspace via the github_repos projection).
+--
+-- The columns are additive and nullable so the migration is safe and so the
+-- auth-disabled / local-dev path (account_id NULL, no signed-in user) behaves
+-- exactly as before: no scoping is enforced and every board stays visible.
+
+CREATE TABLE accounts (
+  id                   TEXT    NOT NULL PRIMARY KEY,
+  type                 TEXT    NOT NULL,            -- 'personal' | 'org'
+  name                 TEXT    NOT NULL,
+  github_account_login TEXT,                        -- the GitHub org/user login, when known
+  created_at           INTEGER NOT NULL
+);
+
+-- One personal account per GitHub login, so ensuring it on sign-in is idempotent.
+CREATE UNIQUE INDEX idx_accounts_personal
+  ON accounts (github_account_login)
+  WHERE type = 'personal';
+
+CREATE TABLE memberships (
+  account_id TEXT    NOT NULL,
+  user_id    INTEGER NOT NULL,                       -- GitHub user id (stable across renames)
+  role       TEXT    NOT NULL DEFAULT 'member',      -- 'owner' | 'member'
+  created_at INTEGER NOT NULL,
+  PRIMARY KEY (account_id, user_id)
+);
+CREATE INDEX idx_memberships_user ON memberships (user_id);
+
+-- Workspaces gain an owning account. NULL means "unscoped" (legacy rows and the
+-- auth-disabled dev path); a signed-in user only sees workspaces whose account is
+-- one they are a member of.
+ALTER TABLE workspaces ADD COLUMN account_id TEXT;
+CREATE INDEX idx_workspaces_account ON workspaces (account_id);
+
+-- A GitHub App installation is now bound to an account (not a single workspace).
+-- The workspace_id column from 0004 is retained as the *connector* workspace (and
+-- as the binding key for the auth-disabled path, where account_id is NULL).
+ALTER TABLE github_installations ADD COLUMN account_id TEXT;
+CREATE INDEX idx_gh_install_account
+  ON github_installations (account_id)
+  WHERE deleted_at IS NULL;

package/migrations/0017_bootstrap_board.sql

@@ -0,0 +1,16 @@
+-- Make a "bootstrap repo" run observable and board-integrated. Two new columns
+-- on bootstrap_jobs (conventions per 0010): the board service frame the run
+-- materialises, and the live subtask progress the bootstrapper agent reports
+-- while the container works.
+--
+--   block_id  — the service frame this run creates up front (in `running` state)
+--               so the bootstrap shows on the board immediately as a provisional
+--               "bootstrapping…" card; on success the frame is linked to the new
+--               repo and becomes a normal, droppable service. NULL for older rows
+--               recorded before this column existed.
+--   subtasks  — JSON {completed,inProgress,total} mirrored from the agent's todo
+--               list, surfaced as an "N/M done" progress bar. NULL until the agent
+--               first reports (or for older rows).
+
+ALTER TABLE bootstrap_jobs ADD COLUMN block_id TEXT;
+ALTER TABLE bootstrap_jobs ADD COLUMN subtasks TEXT;

package/migrations/0018_bootstrap_failure.sql

@@ -0,0 +1,14 @@
+-- Capture structured failure diagnostics for a "bootstrap repo" run, so a crash
+-- is recorded as more than a one-line `error` and the board can classify it (and
+-- decide whether a retry is likely to help). Conventions per 0010/0017.
+--
+--   failure  — JSON-encoded BootstrapFailure {kind, message, detail, hint,
+--              occurredAt, lastSubtasks} written when a run faults. `kind` is one
+--              of preflight | dispatch | evicted | timeout | agent | unknown. The
+--              container's stdout/stderr can't be folded in (an evicted container
+--              is gone), so for `evicted`/`timeout` the `hint` points at the
+--              Cloudflare container logs. NULL while running/succeeded, and for
+--              older failed rows recorded before this column existed (their
+--              one-line `error` still renders).
+
+ALTER TABLE bootstrap_jobs ADD COLUMN failure TEXT;

package/migrations/0019_agent_runs.sql

@@ -0,0 +1,52 @@
+-- Unify the two container-backed agent flows — "bootstrap repo" runs and task
+-- pipeline "execution" runs — onto a single `agent_runs` table that is the source
+-- of truth for run lifecycle, live subtask progress, structured failure and
+-- retry. This is the cross-cutting concern both flows duplicated; folding them
+-- into one table lets the board surface failure + retry uniformly and lets one
+-- cron sweeper re-drive any stale run (fixing the previously-missing bootstrap
+-- sweeper). Conventions per 0001/0010: workspace-scoped, INTEGER epoch-ms
+-- timestamps, no foreign keys.
+--
+-- Clean break (dev DB): the old `bootstrap_jobs` table is dropped here and the
+-- old `executions` table in 0020 (no data is migrated). `reference_architectures`
+-- is unaffected.
+--
+--   kind      — 'bootstrap' | 'execution'; every query is scoped by it so the two
+--               flows share storage without colliding.
+--   block_id  — the board block this run is attached to. Nullable: a bootstrap run
+--               is inserted before its provisional service frame exists; an
+--               execution run always has its task block.
+--   status    — fine-grained run status (running | blocked | paused | succeeded |
+--               done | failed). Kept top-level (not buried in `detail`) because the
+--               sweeper scans `status='running'` and must NOT re-drive blocked
+--               (awaiting decision) or paused (spend gate) runs.
+--   detail    — kind-specific structural JSON nothing queries on:
+--               execution  {pipelineId, pipelineName, steps, currentStep}
+--               bootstrap  {referenceArchitectureId, referenceArchitectureName,
+--                           repoName, repoOwner, repoUrl, instructions}
+--   subtasks  — JSON {completed,inProgress,total} run-level progress (bootstrap's
+--               todo counts). Execution keeps per-step counts inside detail.steps.
+--   failure   — JSON-encoded AgentFailure {kind,message,detail,hint,occurredAt,
+--               lastSubtasks} when a run faults; NULL otherwise.
+--   updated_at— refreshed on every write; doubles as the sweeper's lease.
+
+CREATE TABLE agent_runs (
+  workspace_id          TEXT    NOT NULL,
+  id                    TEXT    NOT NULL,
+  kind                  TEXT    NOT NULL,
+  block_id              TEXT,
+  status                TEXT    NOT NULL,
+  detail                TEXT    NOT NULL DEFAULT '{}',
+  subtasks              TEXT,
+  error                 TEXT,
+  failure               TEXT,
+  workflow_instance_id  TEXT,
+  created_at            INTEGER NOT NULL,
+  updated_at            INTEGER NOT NULL,
+  PRIMARY KEY (workspace_id, id)
+);
+CREATE INDEX idx_agent_runs_workspace    ON agent_runs (workspace_id, created_at);
+CREATE INDEX idx_agent_runs_status_lease ON agent_runs (status, updated_at);
+CREATE INDEX idx_agent_runs_block        ON agent_runs (workspace_id, block_id);
+
+DROP TABLE IF EXISTS bootstrap_jobs;

package/migrations/0019_github_installation_app.sql

@@ -0,0 +1,7 @@
+-- Two-App tiering for repository provisioning (ADR 0005). A workspace may now be
+-- connected via either the default (restricted) GitHub App or a privileged App
+-- that carries `Administration: write`. Since an installation id belongs to
+-- exactly one App, record which App owns each installation so token minting routes
+-- to the right key. Existing rows predate the tier and were created via the
+-- default App, so a NULL `app_id` is interpreted as "the default App".
+ALTER TABLE github_installations ADD COLUMN app_id TEXT;

package/migrations/0020_drop_executions.sql

@@ -0,0 +1,5 @@
+-- Execution runs now live in the unified `agent_runs` table (migration 0019) as
+-- `kind='execution'` rows, owned by D1ExecutionRepository. Drop the legacy
+-- `executions` table — clean break, no data migration (dev DB).
+
+DROP TABLE IF EXISTS executions;

package/migrations/0020_prompt_fragments.sql

@@ -0,0 +1,57 @@
+-- Prompt-fragment library (ADR 0006). Promotes the best-practice fragment
+-- catalog from build-static code to a managed, tenant-scoped projection. A
+-- resolved catalog for a workspace is the merge of three tiers — the built-in
+-- @cat-factory/prompt-fragments collections (never written here), account-owned
+-- fragments, and workspace-owned ones — later tiers overriding earlier by the
+-- stable fragment id, with a tombstone (deleted_at) suppressing an inherited or
+-- removed-upstream fragment.
+--
+-- Rows are scoped by an (owner_kind, owner_id) pair so the one table backs both
+-- tiers, mirroring how the GitHub installation/repo linkage inherits account →
+-- workspace. Provenance columns remember the repo source a fragment came from so
+-- a resync is a cheap sha comparison. Additive + opt-in: untouched when the
+-- PROMPT_LIBRARY_ENABLED gate is off.
+
+CREATE TABLE prompt_fragments (
+  fragment_id  TEXT    NOT NULL,            -- stable id (slug, or src:<sourceId>:<path>)
+  owner_kind   TEXT    NOT NULL,            -- 'account' | 'workspace'
+  owner_id     TEXT    NOT NULL,            -- account id or workspace id
+  version      TEXT    NOT NULL,
+  title        TEXT    NOT NULL,
+  category     TEXT,
+  summary      TEXT    NOT NULL,            -- fed to the relevance selector
+  body         TEXT    NOT NULL,            -- folded into the system prompt
+  applies_to   TEXT,                        -- JSON { blockTypes?, agentKinds? }
+  tags         TEXT,                        -- JSON string[]
+  source_id    TEXT,                        -- → fragment_sources.id (null = hand-authored)
+  source_path  TEXT,                        -- file path within the source repo
+  source_sha   TEXT,                        -- blob sha last synced; powers "changed?"
+  created_at   INTEGER NOT NULL,
+  updated_at   INTEGER NOT NULL,
+  deleted_at   INTEGER,                     -- tombstone (suppress / removed upstream)
+  PRIMARY KEY (owner_kind, owner_id, fragment_id)
+);
+CREATE INDEX idx_prompt_fragments_owner
+  ON prompt_fragments (owner_kind, owner_id) WHERE deleted_at IS NULL;
+CREATE INDEX idx_prompt_fragments_source
+  ON prompt_fragments (source_id) WHERE deleted_at IS NULL;
+
+-- A repo directory linked as a source of Markdown guideline files. Linkable at
+-- either tier; reads reuse the account's existing GitHub installation. The
+-- last-synced digest makes "check for changes" a cheap comparison, not a re-read.
+CREATE TABLE fragment_sources (
+  id              TEXT    NOT NULL PRIMARY KEY,
+  owner_kind      TEXT    NOT NULL,         -- 'account' | 'workspace'
+  owner_id        TEXT    NOT NULL,
+  repo_owner      TEXT    NOT NULL,         -- GitHub owner/login
+  repo_name       TEXT    NOT NULL,
+  git_ref         TEXT    NOT NULL DEFAULT 'HEAD',
+  dir_path        TEXT    NOT NULL DEFAULT '',
+  last_synced_sha TEXT,                     -- tree digest at last successful sync
+  last_synced_at  INTEGER,
+  created_at      INTEGER NOT NULL,
+  deleted_at      INTEGER,
+  UNIQUE (owner_kind, owner_id, repo_owner, repo_name, git_ref, dir_path)
+);
+CREATE INDEX idx_fragment_sources_owner
+  ON fragment_sources (owner_kind, owner_id) WHERE deleted_at IS NULL;

package/migrations/0021_requirement_reviews.sql

@@ -0,0 +1,25 @@
+-- Requirements-review feature: a stateless reviewer agent raises questions /
+-- gaps / clarifications about a board block's collected requirements, humans
+-- answer or dismiss each, and the agent folds the answers back into the block's
+-- description. Unlike executions/bootstraps this flow is synchronous and has no
+-- durable driver, so it gets its own small table rather than a row in agent_runs.
+--
+-- At most one *live* review per block: the service deletes the block's prior
+-- review before inserting a fresh one, so `block_id` effectively identifies the
+-- current review. `items` holds the JSON-serialized array of review items
+-- (id/category/severity/title/detail/status/reply/timestamps).
+
+CREATE TABLE requirement_reviews (
+  workspace_id              TEXT    NOT NULL,
+  id                        TEXT    NOT NULL,
+  block_id                  TEXT    NOT NULL,
+  status                    TEXT    NOT NULL,              -- 'ready' | 'incorporated'
+  items                     TEXT    NOT NULL DEFAULT '[]', -- JSON array of review items
+  model                     TEXT,                          -- 'provider:model' that produced it
+  incorporated_requirements TEXT,                          -- revised requirements after incorporation
+  created_at                INTEGER NOT NULL,
+  updated_at                INTEGER NOT NULL,
+  PRIMARY KEY (workspace_id, id)
+);
+
+CREATE INDEX idx_requirement_reviews_block ON requirement_reviews (workspace_id, block_id);

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@cat-factory/worker",
+  "version": "1.0.0",
+  "description": "Reusable Cloudflare Worker library (Hono + D1) exposing the Agent Architecture Board core: the `createApp()` Hono factory, the default fetch/scheduled/queue handler, and the Durable Object + Workflow classes. Deployments (see deploy/backend) supply the wrangler.toml + config and re-export these.",
+  "files": [
+    "dist",
+    "migrations"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./app": {
+      "types": "./dist/app.d.ts",
+      "default": "./dist/app.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "^3.0.0",
+    "@ai-sdk/openai": "^3.0.0",
+    "@ai-sdk/openai-compatible": "^2.0.0",
+    "@cloudflare/containers": "^0.3.7",
+    "@hono/valibot-validator": "^0.5.2",
+    "ai": "^6.0.0",
+    "hono": "^4.6.0",
+    "pino": "^9.5.0",
+    "valibot": "^1.0.0",
+    "workers-ai-provider": "^3.2.0",
+    "@cat-factory/contracts": "1.0.0",
+    "@cat-factory/prompt-fragments": "1.0.0",
+    "@cat-factory/core": "1.0.0"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "^0.16.15",
+    "@cloudflare/workers-types": "^4.20250620.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.8",
+    "wrangler": "^4.100.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "wrangler dev",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "db:migrate:local": "wrangler d1 migrations apply cat_factory --local"
+  }
+}