loomrail 0.1.0-alpha.1

package/apps/cli/migrations/0006_session_handoff.sql

@@ -0,0 +1,166 @@
+-- Spec docs/plans/07-a1-session-handoff-spec.ru.md §4.2, §4.4, §6.5.
+--
+-- Adds durable storage for the session-handoff loop: the recipe used to assemble each provider
+-- session's context pack, the sessions themselves, and the checkpoints an agent publishes mid-
+-- session. Also widens the `events` CHECK to admit the five new session-handoff event types, and
+-- adds the unproductive-session counter to `stage_attempts` (§6.5: it must survive a daemon
+-- restart, so it lives in the database rather than in daemon memory).
+
+CREATE TABLE provider_sessions (
+  id TEXT PRIMARY KEY,
+  schema_version INTEGER NOT NULL CHECK (schema_version = 1),
+  stage_attempt_id TEXT NOT NULL REFERENCES stage_attempts(id) ON DELETE RESTRICT,
+  ordinal INTEGER NOT NULL CHECK (ordinal > 0),
+  status TEXT NOT NULL CHECK (status IN ('RUNNING', 'ENDED')),
+  end_reason TEXT CHECK (
+    end_reason IS NULL OR
+    end_reason IN ('COMPLETED', 'HANDOFF', 'CONTEXT_EXHAUSTED', 'INTERRUPTED', 'CANCELLED')
+  ),
+  handoff_requested_at TEXT,
+  started_at TEXT NOT NULL,
+  ended_at TEXT,
+  version INTEGER NOT NULL CHECK (version > 0),
+  UNIQUE (stage_attempt_id, ordinal),
+  -- Mirrors providerSessionSchema's two refines: an ENDED session carries both an end reason and
+  -- an end timestamp, and a RUNNING one carries neither.
+  CHECK ((status = 'ENDED') = (end_reason IS NOT NULL)),
+  CHECK ((status = 'ENDED') = (ended_at IS NOT NULL))
+) STRICT;
+
+-- The link to ProviderSession is owned here, one-directional: a two-way FK between this table and
+-- provider_sessions would be circular (spec §6.1 step 4 writes both in one transaction, and each
+-- side's NOT NULL FK would need the other to exist first). UNIQUE enforces the 1:1 the design
+-- assumes -- one recipe per session -- in the schema, not by convention. The StageAttempt is
+-- reachable through the session; a second path to it here would be a second thing that can
+-- disagree with the first.
+CREATE TABLE context_pack_recipes (
+  id TEXT PRIMARY KEY,
+  schema_version INTEGER NOT NULL CHECK (schema_version = 1),
+  provider_session_id TEXT NOT NULL UNIQUE REFERENCES provider_sessions(id) ON DELETE RESTRICT,
+  template_id TEXT NOT NULL,
+  template_version INTEGER NOT NULL CHECK (template_version > 0),
+  spec_source TEXT NOT NULL CHECK (spec_source = 'WORKFLOW_TEMPLATE'),
+  -- [{ id, sources: [{ kind, id, version }], bytes }] -- see contextPackRecipeSectionSchema.
+  sections_json TEXT NOT NULL CHECK (json_valid(sections_json)),
+  -- [{ id, reason }] -- see contextPackRecipeOmittedSectionSchema.
+  omitted_json TEXT NOT NULL CHECK (json_valid(omitted_json)),
+  content_hash TEXT NOT NULL CHECK (content_hash LIKE 'sha256:%'),
+  estimated_tokens INTEGER NOT NULL CHECK (estimated_tokens >= 0),
+  budget_tokens INTEGER NOT NULL CHECK (budget_tokens > 0),
+  estimate_quality TEXT NOT NULL
+    CHECK (estimate_quality IN ('ACTUAL', 'PROVIDER_ESTIMATE', 'LOOMRAIL_ESTIMATE')),
+  created_at TEXT NOT NULL
+) STRICT;
+
+CREATE TABLE checkpoints (
+  id TEXT PRIMARY KEY,
+  schema_version INTEGER NOT NULL CHECK (schema_version = 1),
+  stage_attempt_id TEXT NOT NULL REFERENCES stage_attempts(id) ON DELETE RESTRICT,
+  provider_session_id TEXT NOT NULL REFERENCES provider_sessions(id) ON DELETE RESTRICT,
+  ordinal INTEGER NOT NULL CHECK (ordinal > 0),
+  summary TEXT NOT NULL CHECK (length(summary) BETWEEN 1 AND 4000),
+  completed_json TEXT NOT NULL CHECK (json_valid(completed_json)),
+  remaining_json TEXT NOT NULL CHECK (json_valid(remaining_json)),
+  dead_ends_json TEXT NOT NULL CHECK (json_valid(dead_ends_json)),
+  open_questions_json TEXT NOT NULL CHECK (json_valid(open_questions_json)),
+  created_at TEXT NOT NULL,
+  UNIQUE (provider_session_id, ordinal)
+) STRICT;
+
+-- §6.5: the counter lives in state, not in daemon memory, because a daemon restart is itself a
+-- normal end of a session -- a counter held in memory would be reset by the very event it exists
+-- to guard against.
+ALTER TABLE stage_attempts
+  ADD COLUMN unproductive_sessions INTEGER NOT NULL DEFAULT 0
+  CHECK (unproductive_sessions >= 0);
+
+CREATE INDEX provider_sessions_attempt_ordinal_idx
+  ON provider_sessions(stage_attempt_id, ordinal);
+CREATE INDEX checkpoints_attempt_created_idx
+  ON checkpoints(stage_attempt_id, created_at DESC, id);
+
+CREATE TRIGGER checkpoints_are_append_only_update
+BEFORE UPDATE ON checkpoints
+BEGIN
+  SELECT RAISE(ABORT, 'checkpoints are append-only');
+END;
+
+CREATE TRIGGER checkpoints_are_append_only_delete
+BEFORE DELETE ON checkpoints
+BEGIN
+  SELECT RAISE(ABORT, 'checkpoints are append-only');
+END;
+
+CREATE TRIGGER context_pack_recipes_are_append_only_update
+BEFORE UPDATE ON context_pack_recipes
+BEGIN
+  SELECT RAISE(ABORT, 'context pack recipes are append-only');
+END;
+
+CREATE TRIGGER context_pack_recipes_are_append_only_delete
+BEFORE DELETE ON context_pack_recipes
+BEGIN
+  SELECT RAISE(ABORT, 'context pack recipes are append-only');
+END;
+
+-- `events` bakes its allowed types into a CHECK, so widening it requires a rebuild: drop the
+-- triggers and indexes, rename the table aside, recreate it with the widened list, copy every row
+-- preserving `sequence`, drop the renamed table, then recreate the indexes and the append-only
+-- triggers. This mirrors 0005_acceptance_evidence.sql's rebuild of the same table.
+DROP TRIGGER events_are_append_only_update;
+DROP TRIGGER events_are_append_only_delete;
+DROP INDEX events_project_sequence_idx;
+DROP INDEX events_aggregate_sequence_idx;
+ALTER TABLE events RENAME TO events_v5;
+
+CREATE TABLE events (
+  sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+  id TEXT NOT NULL UNIQUE,
+  schema_version INTEGER NOT NULL CHECK (schema_version = 1),
+  type TEXT NOT NULL CHECK (
+    type IN (
+      'PROJECT_REGISTERED', 'WORK_ITEM_CREATED', 'WORK_ITEM_UPDATED', 'WORK_ITEM_STATE_CHANGED',
+      'PIPELINE_STARTED', 'STAGE_ATTEMPT_CHANGED', 'HUMAN_REQUEST_OPENED',
+      'HUMAN_REQUEST_RESOLVED', 'USAGE_RECORDED', 'BUDGET_THRESHOLD_REACHED',
+      'PIPELINE_PAUSED', 'PIPELINE_RESUMED', 'PIPELINE_CANCELLED',
+      'BUDGET_OVERRIDE_APPROVED', 'RECOVERY_REPORT_CREATED', 'PIPELINE_COMPLETED',
+      'EVIDENCE_ARTIFACT_RECORDED', 'ACCEPTANCE_REQUESTED', 'ACCEPTANCE_RESOLVED',
+      'PROVIDER_SESSION_STARTED', 'CONTEXT_HANDOFF_REQUESTED', 'CHECKPOINT_PUBLISHED',
+      'PROVIDER_SESSION_ENDED', 'CONTEXT_FLOOR_EXCEEDED'
+    )
+  ),
+  aggregate_type TEXT NOT NULL CHECK (aggregate_type IN ('PROJECT', 'WORK_ITEM')),
+  aggregate_id TEXT NOT NULL,
+  project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE RESTRICT,
+  actor_type TEXT NOT NULL CHECK (actor_type IN ('HUMAN', 'SYSTEM')),
+  actor_id TEXT NOT NULL,
+  occurred_at TEXT NOT NULL,
+  correlation_id TEXT NOT NULL,
+  data_json TEXT NOT NULL CHECK (json_valid(data_json))
+) STRICT;
+
+INSERT INTO events (
+  sequence, id, schema_version, type, aggregate_type, aggregate_id, project_id,
+  actor_type, actor_id, occurred_at, correlation_id, data_json
+)
+SELECT
+  sequence, id, schema_version, type, aggregate_type, aggregate_id, project_id,
+  actor_type, actor_id, occurred_at, correlation_id, data_json
+FROM events_v5;
+
+DROP TABLE events_v5;
+
+CREATE INDEX events_project_sequence_idx ON events(project_id, sequence);
+CREATE INDEX events_aggregate_sequence_idx ON events(aggregate_id, sequence);
+
+CREATE TRIGGER events_are_append_only_update
+BEFORE UPDATE ON events
+BEGIN
+  SELECT RAISE(ABORT, 'events are append-only');
+END;
+
+CREATE TRIGGER events_are_append_only_delete
+BEFORE DELETE ON events
+BEGIN
+  SELECT RAISE(ABORT, 'events are append-only');
+END;

package/apps/cli/migrations/0007_pack_share_backoff.sql

@@ -0,0 +1,11 @@
+-- Spec docs/plans/07-a1-session-handoff-spec.ru.md §7 (the mis-estimated-pack branch).
+--
+-- When a provider rejects a pack Loomrail judged as fitting, the pack share for the next session of
+-- the same StageAttempt drops by a fixed step; after one such retry the attempt asks the owner
+-- instead of narrowing blindly. That "one retry" has to survive a daemon restart for the same
+-- reason `unproductive_sessions` does (§6.4 makes a restart the ordinary end of a session), so the
+-- count lives here rather than in daemon memory.
+
+ALTER TABLE stage_attempts
+  ADD COLUMN pack_share_backoffs INTEGER NOT NULL DEFAULT 0
+  CHECK (pack_share_backoffs >= 0);

package/apps/cli/migrations/0008_stage_attempt_counter_backfill.sql

@@ -0,0 +1,169 @@
+-- Spec docs/plans/07-a1-session-handoff-spec.ru.md §6.5, §7.
+--
+-- Migrations 0006 and 0007 added `unproductive_sessions` and `pack_share_backoffs` as columns with
+-- a DEFAULT, so every stored StageAttempt *row* came through the upgrade correct. The matching
+-- fields on `stageAttemptSchema` are required and the schema is `.strict()`, and that entity is
+-- embedded verbatim in the payloads of PIPELINE_STARTED, STAGE_ATTEMPT_CHANGED, PIPELINE_PAUSED,
+-- PIPELINE_RESUMED, PIPELINE_CANCELLED, BUDGET_OVERRIDE_APPROVED, RECOVERY_REPORT_CREATED,
+-- ACCEPTANCE_REQUESTED, ACCEPTANCE_RESOLVED and PIPELINE_COMPLETED -- none of which 0006 rewrote:
+-- its rebuild of `events` copied `data_json` verbatim. Every payload written before this milestone
+-- therefore fails `domainEventSchema.parse` inside `eventFromRow`, which makes the whole activity
+-- timeline and the events endpoint unreadable on a database that predates A1. The board keeps
+-- loading because snapshots are read from rows, which is exactly why no test caught it: every test
+-- starts from an empty database, so every stored payload already has the post-A1 shape.
+--
+-- The same applies to `commands.result_json`, which is replayed through `stateCommandResultSchema`
+-- when a command id is reused, so a pre-A1 receipt would fail its replay in the same way.
+--
+-- This is the same class of repair as 0004_pipeline_started_budget_backfill.sql, and follows it:
+-- backfill the missing fields with the value the column default already gave the row (0), guard so
+-- the pass is idempotent and touches nothing already correct, and drop and recreate the
+-- append-only triggers around the writes as 0004 and 0005 both do.
+--
+-- Unlike 0004 the paths cannot be spelled out literally: a StageAttempt appears at the top level of
+-- a command result *and* inside `$.events[i].data`, and `events` is an array whose length varies by
+-- command type (RECONCILE_WORKFLOWS emits one report per interrupted run). So the paths are found
+-- with json_tree and folded over with a recursive CTE, one json_insert per occurrence. Adding
+-- object keys never shifts an array index, so the fold order does not matter.
+--
+-- `$.stage IS NOT NULL` narrows the match to actual StageAttempt objects: the key name alone is the
+-- convention this backfill leans on, and requiring a field only a StageAttempt has keeps the pass
+-- from stamping counters onto some future payload that reuses the name for something else.
+--
+-- The guard is "either counter absent", not "unproductiveSessions absent". A database written by a
+-- build between 0006 (which added `unproductive_sessions`) and 0007 (which added
+-- `pack_share_backoffs`) holds payloads carrying the first field and not the second; keying the
+-- guard on the first alone would skip exactly those, and 0008 is recorded as applied afterwards, so
+-- there is no second pass -- that history would stay unreadable for good. `json_insert` rather than
+-- `json_set` for the same reason: on a half-legacy payload the counter that is already there is a
+-- real count, and json_set would flatten it back to 0.
+--
+-- The occurrence list is materialised into a TEMP TABLE indexed on (sequence, n) rather than left
+-- as a CTE. A non-materialised CTE is re-evaluated per fold step -- json_tree over every row again,
+-- once per occurrence -- which made the pass quadratic in history size: measured on synthetic
+-- legacy histories, 2000 events took 9.3s and 2000 events plus 2000 four-occurrence command
+-- receipts took 89s, with no progress output, inside the BEGIN IMMEDIATE of a startup path the
+-- owner cannot skip. The temp table is the same set of rows; only the number of times it is
+-- computed changes.
+
+DROP TRIGGER events_are_append_only_update;
+
+CREATE TEMP TABLE legacy_event_attempt (
+  sequence INTEGER NOT NULL,
+  path TEXT NOT NULL,
+  n INTEGER NOT NULL
+);
+
+INSERT INTO legacy_event_attempt (sequence, path, n)
+SELECT events.sequence, tree.fullkey,
+       ROW_NUMBER() OVER (PARTITION BY events.sequence ORDER BY tree.fullkey)
+FROM events, json_tree(events.data_json) AS tree
+WHERE tree.key IN ('stageAttempt', 'previousStageAttempt')
+  AND tree.type = 'object'
+  AND json_type(tree.value, '$.stage') IS NOT NULL
+  AND (json_type(tree.value, '$.unproductiveSessions') IS NULL
+       OR json_type(tree.value, '$.packShareBackoffs') IS NULL);
+
+CREATE INDEX legacy_event_attempt_fold_idx ON legacy_event_attempt (sequence, n);
+
+CREATE TEMP TABLE backfilled_event (
+  sequence INTEGER PRIMARY KEY,
+  data_json TEXT NOT NULL
+);
+
+INSERT INTO backfilled_event (sequence, data_json)
+WITH RECURSIVE
+  backfilled(sequence, n, data_json) AS (
+    SELECT events.sequence, 0, events.data_json
+    FROM events
+    WHERE events.sequence IN (SELECT sequence FROM legacy_event_attempt)
+    UNION ALL
+    SELECT backfilled.sequence, legacy_event_attempt.n,
+           json_insert(backfilled.data_json,
+                       legacy_event_attempt.path || '.unproductiveSessions', 0,
+                       legacy_event_attempt.path || '.packShareBackoffs', 0)
+    FROM backfilled
+    JOIN legacy_event_attempt
+      ON legacy_event_attempt.sequence = backfilled.sequence
+     AND legacy_event_attempt.n = backfilled.n + 1
+  )
+SELECT backfilled.sequence, backfilled.data_json
+FROM backfilled
+JOIN (SELECT sequence, MAX(n) AS n FROM legacy_event_attempt GROUP BY sequence) AS folded
+  ON folded.sequence = backfilled.sequence
+ AND folded.n = backfilled.n;
+
+UPDATE events
+SET data_json = (SELECT data_json FROM backfilled_event WHERE backfilled_event.sequence = events.sequence)
+WHERE events.sequence IN (SELECT sequence FROM backfilled_event);
+
+DROP TABLE backfilled_event;
+DROP TABLE legacy_event_attempt;
+
+CREATE TRIGGER events_are_append_only_update
+BEFORE UPDATE ON events
+BEGIN
+  SELECT RAISE(ABORT, 'events are append-only');
+END;
+
+DROP TRIGGER commands_are_append_only_update;
+
+CREATE TEMP TABLE legacy_command_attempt (
+  command_id TEXT NOT NULL,
+  path TEXT NOT NULL,
+  n INTEGER NOT NULL
+);
+
+INSERT INTO legacy_command_attempt (command_id, path, n)
+SELECT commands.command_id, tree.fullkey,
+       ROW_NUMBER() OVER (PARTITION BY commands.command_id ORDER BY tree.fullkey)
+FROM commands, json_tree(commands.result_json) AS tree
+WHERE tree.key IN ('stageAttempt', 'previousStageAttempt')
+  AND tree.type = 'object'
+  AND json_type(tree.value, '$.stage') IS NOT NULL
+  AND (json_type(tree.value, '$.unproductiveSessions') IS NULL
+       OR json_type(tree.value, '$.packShareBackoffs') IS NULL);
+
+CREATE INDEX legacy_command_attempt_fold_idx ON legacy_command_attempt (command_id, n);
+
+CREATE TEMP TABLE backfilled_command (
+  command_id TEXT PRIMARY KEY,
+  result_json TEXT NOT NULL
+);
+
+INSERT INTO backfilled_command (command_id, result_json)
+WITH RECURSIVE
+  backfilled(command_id, n, result_json) AS (
+    SELECT commands.command_id, 0, commands.result_json
+    FROM commands
+    WHERE commands.command_id IN (SELECT command_id FROM legacy_command_attempt)
+    UNION ALL
+    SELECT backfilled.command_id, legacy_command_attempt.n,
+           json_insert(backfilled.result_json,
+                       legacy_command_attempt.path || '.unproductiveSessions', 0,
+                       legacy_command_attempt.path || '.packShareBackoffs', 0)
+    FROM backfilled
+    JOIN legacy_command_attempt
+      ON legacy_command_attempt.command_id = backfilled.command_id
+     AND legacy_command_attempt.n = backfilled.n + 1
+  )
+SELECT backfilled.command_id, backfilled.result_json
+FROM backfilled
+JOIN (SELECT command_id, MAX(n) AS n FROM legacy_command_attempt GROUP BY command_id) AS folded
+  ON folded.command_id = backfilled.command_id
+ AND folded.n = backfilled.n;
+
+UPDATE commands
+SET result_json = (
+  SELECT result_json FROM backfilled_command WHERE backfilled_command.command_id = commands.command_id
+)
+WHERE commands.command_id IN (SELECT command_id FROM backfilled_command);
+
+DROP TABLE backfilled_command;
+DROP TABLE legacy_command_attempt;
+
+CREATE TRIGGER commands_are_append_only_update
+BEFORE UPDATE ON commands
+BEGIN
+  SELECT RAISE(ABORT, 'commands are append-only');
+END;

package/apps/cli/migrations/0009_session_window_occupancy.sql

@@ -0,0 +1,44 @@
+-- Spec docs/plans/07-a1-session-handoff-spec.ru.md §6.2: window occupancy is saved.
+--
+-- It was not. Below the handoff threshold `REQUEST_CONTEXT_HANDOFF` decided NO_ACTION and wrote
+-- nothing, so the only occupancy that survived a session was the single reading that crossed the
+-- threshold, and only as a field inside the CONTEXT_HANDOFF_REQUESTED audit event.
+-- LIST_PROVIDER_SESSIONS then rebuilt a displayable number by scanning that event log, which is
+-- exactly the separation of current state from audit that AGENTS.md forbids collapsing.
+--
+-- These four columns give the reading a home in current state. What they hold is the HIGHEST
+-- occupancy the session has been observed at, not its current one: that is the figure that answers
+-- "how full did this session get", which is what explains a cut after the fact, and the write in
+-- REQUEST_CONTEXT_HANDOFF enforces it rather than trusting the order reports arrive in. All four
+-- are nullable together: a session that has never been measured has no occupancy at all, and that
+-- is a different fact from a session measured at zero.
+
+ALTER TABLE provider_sessions
+  ADD COLUMN context_used_tokens INTEGER
+  CHECK (context_used_tokens IS NULL OR context_used_tokens >= 0);
+
+ALTER TABLE provider_sessions
+  ADD COLUMN context_window_tokens INTEGER
+  CHECK (context_window_tokens IS NULL OR context_window_tokens > 0);
+
+ALTER TABLE provider_sessions
+  ADD COLUMN context_usage_quality TEXT
+  CHECK (
+    context_usage_quality IS NULL OR
+    context_usage_quality IN ('ACTUAL', 'PROVIDER_ESTIMATE', 'LOOMRAIL_ESTIMATE')
+  );
+
+-- Mirrors the two-sided CHECKs 0006 wrote for this table's status/end_reason pair, and carries the
+-- whole-row invariant because it is the last column added: contextWindowUsageSchema is one value
+-- with three parts plus the moment it was reported, so all four are present or all four are absent
+-- -- never a used count with no window to measure it against. `usedTokens <= windowTokens` is the
+-- schema's own refine and stays there; SQLite would accept it here too, but a stored row that
+-- predates the constraint cannot be re-checked by ALTER TABLE, so the parse on read is the honest
+-- place for it.
+ALTER TABLE provider_sessions
+  ADD COLUMN context_usage_reported_at TEXT
+  CHECK (
+    (context_usage_reported_at IS NULL) = (context_used_tokens IS NULL) AND
+    (context_usage_reported_at IS NULL) = (context_window_tokens IS NULL) AND
+    (context_usage_reported_at IS NULL) = (context_usage_quality IS NULL)
+  );

package/apps/cli/migrations/0010_provider_session_pid.sql

@@ -0,0 +1,5 @@
+-- The process a RUNNING session is driving, so a daemon that died without killing it can find that
+-- process on the next start. Nullable on purpose: a session that never reached `spawn` has no
+-- process, and that is a different fact from "a process whose pid is 0".
+ALTER TABLE provider_sessions
+  ADD COLUMN process_pid INTEGER CHECK (process_pid IS NULL OR process_pid > 0);

package/apps/cli/migrations/0011_work_item_workspaces.sql

@@ -0,0 +1,94 @@
+-- The Git worktree a WorkItem is edited in (spec D1/D6, docs/plans/14-e1-workspace-execution-
+-- implementation-plan.ru.md Задача 7). `work_item_id` is UNIQUE: the workspace belongs to the
+-- WorkItem, not to any one StageAttempt, and a second row for the same WorkItem would mean two
+-- writers past the lease. That invariant belongs to the schema, not to a convention callers are
+-- trusted to follow.
+--
+-- `base_commit`/`snapshot_commit` are nullable, not optional-with-a-default: an empty repository
+-- genuinely has no HEAD, and a workspace cut from a clean working copy genuinely carried nothing
+-- forward, so there is no snapshot commit to name (spec §2.9/§2.12, see
+-- packages/contracts/src/workspace.ts).
+--
+-- `lease_holder` names the StageAttempt currently allowed to write, or no one (spec D6): the
+-- workspace outlives any single attempt, so this is a lease held for an attempt's duration, not an
+-- owner. It is acquired by a single `UPDATE ... WHERE lease_holder IS NULL` -- see
+-- ACQUIRE_WORKSPACE_LEASE in src/index.ts -- so the check and the claim are one atomic statement
+-- rather than a read followed by a write.
+CREATE TABLE work_item_workspaces (
+  id TEXT PRIMARY KEY,
+  schema_version INTEGER NOT NULL,
+  project_id TEXT NOT NULL REFERENCES projects(id),
+  work_item_id TEXT NOT NULL UNIQUE REFERENCES work_items(id),
+  branch TEXT NOT NULL,
+  worktree_path TEXT NOT NULL,
+  base_commit TEXT,
+  snapshot_commit TEXT,
+  status TEXT NOT NULL CHECK (status IN ('READY', 'ORPHANED', 'REMOVED')),
+  lease_holder TEXT REFERENCES stage_attempts(id),
+  created_at TEXT NOT NULL,
+  version INTEGER NOT NULL CHECK (version > 0)
+);
+
+-- `events` bakes its allowed types into a CHECK, so widening it for WORK_ITEM_WORKSPACE_CREATED and
+-- WORK_ITEM_WORKSPACE_ORPHANED requires a rebuild: drop the triggers and indexes, rename the table
+-- aside, recreate it with the widened list, copy every row preserving `sequence`, drop the renamed
+-- table, then recreate the indexes and the append-only triggers. This mirrors
+-- 0006_session_handoff.sql's rebuild of the same table.
+DROP TRIGGER events_are_append_only_update;
+DROP TRIGGER events_are_append_only_delete;
+DROP INDEX events_project_sequence_idx;
+DROP INDEX events_aggregate_sequence_idx;
+ALTER TABLE events RENAME TO events_v10;
+
+CREATE TABLE events (
+  sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+  id TEXT NOT NULL UNIQUE,
+  schema_version INTEGER NOT NULL CHECK (schema_version = 1),
+  type TEXT NOT NULL CHECK (
+    type IN (
+      'PROJECT_REGISTERED', 'WORK_ITEM_CREATED', 'WORK_ITEM_UPDATED', 'WORK_ITEM_STATE_CHANGED',
+      'PIPELINE_STARTED', 'STAGE_ATTEMPT_CHANGED', 'HUMAN_REQUEST_OPENED',
+      'HUMAN_REQUEST_RESOLVED', 'USAGE_RECORDED', 'BUDGET_THRESHOLD_REACHED',
+      'PIPELINE_PAUSED', 'PIPELINE_RESUMED', 'PIPELINE_CANCELLED',
+      'BUDGET_OVERRIDE_APPROVED', 'RECOVERY_REPORT_CREATED', 'PIPELINE_COMPLETED',
+      'EVIDENCE_ARTIFACT_RECORDED', 'ACCEPTANCE_REQUESTED', 'ACCEPTANCE_RESOLVED',
+      'PROVIDER_SESSION_STARTED', 'CONTEXT_HANDOFF_REQUESTED', 'CHECKPOINT_PUBLISHED',
+      'PROVIDER_SESSION_ENDED', 'CONTEXT_FLOOR_EXCEEDED',
+      'WORK_ITEM_WORKSPACE_CREATED', 'WORK_ITEM_WORKSPACE_ORPHANED'
+    )
+  ),
+  aggregate_type TEXT NOT NULL CHECK (aggregate_type IN ('PROJECT', 'WORK_ITEM')),
+  aggregate_id TEXT NOT NULL,
+  project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE RESTRICT,
+  actor_type TEXT NOT NULL CHECK (actor_type IN ('HUMAN', 'SYSTEM')),
+  actor_id TEXT NOT NULL,
+  occurred_at TEXT NOT NULL,
+  correlation_id TEXT NOT NULL,
+  data_json TEXT NOT NULL CHECK (json_valid(data_json))
+) STRICT;
+
+INSERT INTO events (
+  sequence, id, schema_version, type, aggregate_type, aggregate_id, project_id,
+  actor_type, actor_id, occurred_at, correlation_id, data_json
+)
+SELECT
+  sequence, id, schema_version, type, aggregate_type, aggregate_id, project_id,
+  actor_type, actor_id, occurred_at, correlation_id, data_json
+FROM events_v10;
+
+DROP TABLE events_v10;
+
+CREATE INDEX events_project_sequence_idx ON events(project_id, sequence);
+CREATE INDEX events_aggregate_sequence_idx ON events(aggregate_id, sequence);
+
+CREATE TRIGGER events_are_append_only_update
+BEFORE UPDATE ON events
+BEGIN
+  SELECT RAISE(ABORT, 'events are append-only');
+END;
+
+CREATE TRIGGER events_are_append_only_delete
+BEFORE DELETE ON events
+BEGIN
+  SELECT RAISE(ABORT, 'events are append-only');
+END;

package/apps/cli/migrations/0012_registered_repository_projects.sql

@@ -0,0 +1,54 @@
+-- Spec docs/plans/13-e1-workspace-execution-spec.ru.md §4: a Project is a local Git repository the
+-- owner registered by path, and the two bundled fixtures are only the cheap ground the first run
+-- starts from. Until now `projects.fixture_id` said the opposite -- `NOT NULL UNIQUE CHECK
+-- (fixture_id IN ('web-app-a', 'api-service-b'))` -- so the table could hold nothing but the two
+-- demos, and the owner could run a live agent only against Loomrail's own fixtures.
+--
+-- After this migration `fixture_id` is nullable and unrestricted: a Project registered by path
+-- genuinely has no fixture, and NULL records that fact rather than omitting it. It stays UNIQUE,
+-- which in SQLite constrains only non-NULL values -- every NULL is distinct in a UNIQUE index --
+-- so the two demos still cannot each be registered twice while any number of path-registered
+-- Projects coexist. `packages/contracts/src/work-management.ts` makes `projectSchema.fixtureId`
+-- `.nullable()` for the same reason, and on the same grounds.
+--
+-- SQLite cannot alter a CHECK, so this is a table rebuild, the same shape 0006_session_handoff.sql
+-- and 0011_work_item_workspaces.sql use for `events`. `projects` is harder than `events` was:
+-- nothing references `events`, while thirteen tables reference `projects(id)`, twelve of them
+-- ON DELETE RESTRICT. Two things follow, and both are why this migration is declared
+-- `rebuildsAReferencedTable` in src/migrations.ts and therefore runs with `PRAGMA foreign_keys` off
+-- -- SQLite's own documented procedure for this change, checked at the end of the same transaction
+-- by `PRAGMA foreign_key_check`:
+--
+--   * With foreign keys ON, `ALTER TABLE projects RENAME TO ...` rewrites all thirteen
+--     `REFERENCES projects(id)` clauses to name the renamed-aside table, and the database would end
+--     up pointing at a table this migration just dropped. With them off, SQLite leaves those
+--     clauses alone, so they still name `projects` -- which the last statement here restores.
+--   * With foreign keys ON, `DROP TABLE projects` performs an implicit DELETE of every row, and
+--     ON DELETE RESTRICT refuses it immediately. RESTRICT is the one action `defer_foreign_keys`
+--     cannot defer, so deferring is not a way around this either (both were tried).
+--
+-- Every existing row is carried across column by column: the owner's real database has Projects in
+-- it, and this migration preserves them exactly. test/local-state.integration.test.ts asserts both
+-- halves -- the rows survive, and `PRAGMA foreign_key_check` is empty afterwards.
+CREATE TABLE projects_v12 (
+  id TEXT PRIMARY KEY,
+  workspace_id TEXT NOT NULL REFERENCES workspaces(id) ON DELETE RESTRICT,
+  fixture_id TEXT UNIQUE,
+  name TEXT NOT NULL CHECK (length(name) BETWEEN 1 AND 200),
+  repository_path TEXT NOT NULL UNIQUE,
+  status TEXT NOT NULL CHECK (status IN ('ACTIVE', 'ARCHIVED')),
+  version INTEGER NOT NULL CHECK (version > 0),
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+) STRICT;
+
+INSERT INTO projects_v12 (
+  id, workspace_id, fixture_id, name, repository_path, status, version, created_at, updated_at
+)
+SELECT
+  id, workspace_id, fixture_id, name, repository_path, status, version, created_at, updated_at
+FROM projects;
+
+DROP TABLE projects;
+
+ALTER TABLE projects_v12 RENAME TO projects;