tinybeeai 0.0.0-stage → 0.16.1

package/docs/DATA-MODEL.md

@@ -0,0 +1,518 @@
+# Data model review
+
+This review compares the data that localdost stores today with the data a QA team needs. Stage 1 of the test management epic (KAT-223) is the goal: the dot manages tests on its own. Sync with Jira, Xray, Linear, TestRail, and Katalon True Platform comes after stage 1.
+
+The first version of this review mapped Xray Test Executions and TestRail runs onto localdost runs. That was wrong. A localdost run (a **dot run**, the `runs` table) is one automated flow job: one `pr_check`, `post_merge`, or `rerun` that the queue ran. A **test run** is a planned pass over a set of cases. One test run can take results from several dot runs (one per browser, or a rerun after a fix), and a manual test run has no dot run at all because a person works it by hand. Section 2.3 describes the corrected model, and sections 3 to 5 follow it.
+
+Scope: section 1 describes `main` at `c7d7c60` (2026-10-09). Sources read: `SCHEMA` (in `src/db.ts` at that commit, now `src/db-schema.ts`) and `INDEXES` in `src/db.ts`, `src/types.ts`, `src/cases.ts`, `src/links.ts`, the tables that other modules create, and [STAGES.md](STAGES.md), [TRACE-MAP.md](TRACE-MAP.md), [MULTI-REPO.md](MULTI-REPO.md), [TRACKERS.md](TRACKERS.md). Items marked "to confirm" were not checked on a primary source.
+
+## Contents
+
+1. Today's model
+2. The QA domain a tester expects
+3. Gaps
+4. External sync
+5. Phased plan
+
+---
+
+## 1. Today's model
+
+### 1.1 How storage works
+
+| Rule | Effect |
+|---|---|
+| One SQLite file, WAL mode | One writer. Good for one server, no sharding |
+| Every `SCHEMA` table has `id TEXT PRIMARY KEY`, `createdAt TEXT`, `extra TEXT` (JSON) | A field that `SCHEMA` does not declare goes into `extra`. Filters on it use `json_extract` and have no index |
+| `migrate()` creates tables and adds columns only | It never renames, drops, or changes a column type. Rollback to an older build is safe |
+| No foreign keys, no `NOT NULL`, no checks | Links between rows are text ids. A deleted row leaves dangling ids. Code, not the database, keeps the rules |
+| JSON columns hold nested entities | Runs, reports, verdicts, and test results are not rows. A query across runs reads and parses every run |
+| Ids from `newId()` sort by time | Some tables use natural ids: `repos` (`owner/name`), `issue_state` (`owner/name#N`), `links` (`lk_` + hash), `ticket_titles` (lower-case ref), `phone_prefs` (`phone`) |
+| Five tables live outside `SCHEMA` | `pages`, `connections`, `connect_values`, `connect_audit`, `poll_cursors`. Each module creates its own |
+| Two names for one key | Older tables use `watchId`. `test_cases` and `case_results` use `dotId`. Both hold `watches.id` |
+
+### 1.2 Stored entities
+
+The request names "updates", "asks", and "observations". None of them is a table:
+
+- An "ask" is an `approvals` row with status `pending`.
+- An "update" is a live event on the in-memory bus (`LiveEventV2`). It is not stored. The lasting record is `runs.steps`.
+- An "observation" is a line in `artifacts/<runId>/observations.jsonl` (`PageObservation`). The Traceability map reads the files of recent runs on each request.
+
+| Table | Holds | Key fields | Links to | Notes |
+|---|---|---|---|---|
+| `watches` | One dot | `name`, `mission`, `notifyWhen`, `mustNot`, `repo`, `repos` (json `WatchRepo[]`), `tracker` (json), `baseUrl`, `probes`, `statusPages`, `runner` (json), `rules` (json), `digestHour`, `paused`; in `extra`: `role`, `instructions`, `mascot`, `connections`, `slackChannel`, `archived`, `review`, `waitForPreviewSec`, `waitForDeploySec`, `deployEnvironment`, `stages`, `stageModels`, `stagesNotice` | `repos.id` through `repos[].repo`; `connections.id` | The product area. Stages: STAGES.md section 5 |
+| `repos` | Workspace repo | id `owner/name`, `defaultBranch`, `private`, `scan` (json state), `intake`, `lastEventAt` | `repo_profiles.repoId` | Shared by dots |
+| `repo_profiles` | One scan of a repo | `repoId`, `sha`, `profile` (json `RepoProfile`: apps, routes, areas, specs, CI, owners), `overrides`, `version`, `mode` | `repos` | Newest row is live; last 5 kept |
+| `events` | One trigger as received | `watchId`, `source`, `kind`, `dedupeKey`, `title`, `url`, `jobId`, `trigger` (json `TriggerEvent`) | `jobs` | Raw intake log |
+| `jobs` | Queue item | `kind` (`JobKind`), `watchId`, `eventId`, `dedupeKey` (unique), `payload`, `status`, `attempts`, `error`, `runAfter`; in `extra`: `checkStatus`, `heldBy` (`model_cap` or `deploy_wait`), `deployWait` (a merge job that waits for the deploy of its commit: `state`, `since`, `environment`, `sha`, `repo`, `runId`, `outcome`) | `events`, `runs.jobId` | |
+| `runs` | One flow execution | `watchId`, `kind`, `trigger` (json, holds a ticket snapshot in `inlineTicket`), `status`, `steps` (json `RunStep[]`), `report` (json `TestReport` with `cases[]` and `evidence`), `verdict` (json, holds `qa: QaReview` with risks and `whatToTest`), `actions` (json), `finishedAt`; in `extra`: `jobId`, `rerunOf`, `diff`, `leaseUntil`, `interruptReason` (`deploy_wait` with `deployWait` while a merge run waits for a deploy), `deployWaitedMs` (the time a merge run waited, which its duration leaves out) | `jobs`, `approvals`, `case_results`, artifacts folder | The largest row. Test results, What to test items, and verdicts live only here |
+| `approvals` | An outward action that waits for a person (an "ask") | `watchId`, `runId`, `action` (json `OutwardAction`), `reason`, `status`, `decidedAt`, `decidedBy`; in `extra`: `expiresAt`, `executedAt`, `error`, `escalation`, `supersededBy`, `closedReason` | `runs` | `decidedBy` names the person when one decided it: a paired device's name, the Tailscale owner's login, or a Slack user as `Slack <name>` (`Slack <user id>` when Slack sends no name); the shared admin token and a server close store none. An edit replaces `action.body`, so the first draft is lost |
+| `outbox` | An action that went nowhere (demo, no credentials) | `watchId`, `runId`, `action` | `runs` | |
+| `memory` | Dot notes | `watchId`, `kind` (`flaky_spec`, `env_quirk`, `convention`, `decision`, `note`), `text`, `source` (`agent`, `user`) | `watches` | Flaky marks are free text |
+| `messages` | Chat and call turns | `watchId`, `role`, `content`, `runId`; in `extra`: `blocks` | `watches`, `runs` | |
+| `links` | Traceability edge | `kind` (`closes`, `references`, `parent`, `blocks`, `tests`, `covers`), `fromRef`, `toRef`, `source`, `watchId`, `meta` | Text refs: `owner/name#N`, `shop-12` | No `defect` kind yet; defects use `references` with source `defect` |
+| `issue_state` | GitHub issue as last read | id `owner/name#N`, `repoId`, `number`, `title`, `bodyHash`, `scopeSig` (labels, type, milestone as JSON text), `state`, `updatedAt`, `testStatus` | `links` by ref | GitHub only. Jira and Linear have no such row |
+| `ticket_titles` | Title cache for refs | id lower-case ref, `title`, `url`, `fetchedAt`, `failedAt`, `error` | refs | One-day cache |
+| `test_cases` | Stored case (KAT-163) | `dotId`, `key` (`TC-n`, unique per dot), `title`, `steps` (json `{action, expected?}[]`), `kind` (`manual`, `playwright`, `aivision`), `requirementRefs` (json), `specPath`, `priority`, `status` (`draft`, `ready`, `retired`), `source`, `updatedAt` | refs; `case_results` | An edit overwrites the row. No revision, no history |
+| `case_results` | Result of a case, append only | `caseId`, `dotId`, `runId`, `result` (`passed`, `failed`, `skipped`, `blocked`), `notes`, `evidence` (json artifact names), `source` (`run`, `manual`), `at` | `test_cases`, `runs` | One row per case per run. No step results, no environment, no build |
+| `probe_state` | Probe health per URL | `watchId`, `url`, `kind`, `down`, `consecutiveFailures`, `lastStatus`, `lastError`, `lastLatencyMs`, `downSince` | `watches` | Current state only, no history |
+| `model_calls` | One answered model call (KAT-362) | `watchId`, `runId`, `stage` (a stage key, `chat`, or `other`), `backend` (`claude`, `codex`, `anthropic`), `inputTokens`, `outputTokens` (empty when the backend sent no count) | `watches`, `runs` | Behind the daily model cap and the Model use card. Rows older than 35 days are removed |
+| `push_subs` | Web push subscription | `endpoint` (unique), `keys`, `subscription`, `deviceId` | `devices` | |
+| `devices` | Paired phone, or a teammate's device | `name`, `platform`, `tokenHash`, `lastSeenAt`, `lastIp`, `revokedAt`, `pairedBy`; in `extra`: `viaInvite`, `role` (`member` or `editor`, unset is a member) | | The named actor behind `decidedBy`. A teammate types the name when joining |
+| `pair_invites` | Invite code for a teammate (KAT-356) | `hash` (sha256 of the code), `expiresAt`, `createdBy`; in `extra`: `role` | | One use: the row is removed when the code is used, cancelled, burned, or past `expiresAt` |
+| `device_audit` | Pairing log | `action`, `deviceId`, `deviceName`, `actor`, `detail` | `devices` | |
+| `phone_prefs` | One row, alert choices | `prefs` (json) | | |
+| `pages` | Report page | `watchId`, `parentId`, `title`, `kind` (`test_plan`, `readiness`, `incident`, `digest`, `note`), `markdown`, `revision`, `sourceRunId` | `runs`, `pages` | Has a revision check (409) |
+| `connections` | MCP server | in `extra`: `name`, `transport`, `tools`, `status`, `preset`, `envRefs` | `watches.connections` | |
+| `connect_values` | Saved setting, encrypted | `key`, `provider`, `enc`, `secret`, `last4`, `updatedBy` | | |
+| `connect_audit` | Settings log | `at`, `provider`, `key`, `action`, `actor`, `last4` | | |
+| `poll_cursors` | Poller position | `id` (for example `github:<repo>:<branch>`), `value` | | |
+
+Files in the data folder: `artifacts/<runId>/` (screenshots, videos, traces, logs, JSON reports, `observations.jsonl`), `mirrors/`, `checkouts/`, `repo-cache/`, `graph-cache/`, `runner-cache/`, `eval-candidates/`, `vapid.json`, `secret.key`. The artifact cap (`src/runner/artifact-cap.ts`, 2 GB per dot) deletes screenshots, videos, and traces of the oldest runs first. `case_results.evidence` can then name files that are gone.
+
+In memory only: deployment previews (`rememberPreview` in `src/integrations/github.ts`, 500 entries, lost on restart) and live events.
+
+### 1.3 Entities that live inside JSON
+
+| Entity | Lives in | Identity | Effect |
+|---|---|---|---|
+| Ticket (title, description, AC, type, milestone, labels) | `runs.trigger.inlineTicket`, `events.trigger` | Key string | The current ticket of Jira and Linear is the snapshot in the newest `ticket_review` run. `ticketCatalog` reads the last 1000 such runs |
+| Automated test result | `runs.report.cases[]` (`TestCaseResult`) | `file` + `title`; the Playwright project is a `[project]` prefix in `title` | No stable test id. Flaky history needs a scan of all runs |
+| Evidence per test | `runs.report.cases[].evidence` | Artifact names | |
+| What to test item | `runs.verdict.qa.whatToTest[]` (`QaTestToRun`) | `t1`, `t2` per review | Not a case. Ids repeat across reviews |
+| Risk, impact area | `runs.verdict.qa.risks[]`, `impactAreas[]` | `r1`, `a1` per review | Area ids are not stable |
+| Feature area | `repo_profiles.profile.areas[]` | Slug, for example `checkout` | Stable per repo. No case points to it |
+| Defect | `approvals.action` with kind `file_defect` or `issue_create`; `action.meta.bugKey`, `meta.filedUrl`; `links` with source `defect` | Bug key or signature hash | No row per defect. State (open or closed) comes from a tracker read |
+| Change (PR, commit) | `runs.trigger.pr`, `push`; `events` | PR number, sha | No row per PR or commit |
+| Page and state | `observations.jsonl`; map nodes built on read | Hash of kind and route | A case cannot point to a page |
+| Stage | Not built | | STAGES.md task 1 adds `RunRecord.stage` |
+
+### 1.4 Diagram
+
+Solid lines are id columns. Dotted lines are text refs or JSON. No line is a foreign key in SQLite.
+
+```mermaid
+erDiagram
+  watches ||--o{ events : "watchId"
+  watches ||--o{ jobs : "watchId"
+  events  ||--o| jobs : "jobId"
+  jobs    ||--o{ runs : "jobId"
+  watches ||--o{ runs : "watchId"
+  runs    ||--o{ approvals : "runId"
+  runs    ||--o{ outbox : "runId"
+  runs    ||--o{ case_results : "runId"
+  runs    ||--o{ pages : "sourceRunId"
+  runs    ||--o{ messages : "runId"
+  watches ||--o{ memory : "watchId"
+  watches ||--o{ messages : "watchId"
+  watches ||--o{ probe_state : "watchId"
+  watches ||--o{ links : "watchId"
+  watches ||--o{ test_cases : "dotId"
+  watches }o--o{ repos : "repos[].repo (json)"
+  watches }o--o{ connections : "connections (json)"
+  repos   ||--o{ repo_profiles : "repoId"
+  repos   ||--o{ issue_state : "repoId"
+  test_cases ||--o{ case_results : "caseId"
+  test_cases }o..o{ issue_state : "requirementRefs (text)"
+  links   }o..o{ issue_state : "fromRef, toRef (text)"
+  ticket_titles |o..o{ links : "ref (text)"
+  pages   ||--o{ pages : "parentId"
+  devices ||--o{ push_subs : "deviceId"
+  devices ||--o{ device_audit : "deviceId"
+
+  watches { text id PK
+    text name
+    json repos
+    json tracker
+    json runner
+    json rules }
+  runs { text id PK
+    text watchId
+    text kind
+    json trigger
+    json steps
+    json report
+    json verdict
+    json actions }
+  test_cases { text id PK
+    text dotId
+    text key
+    json steps
+    json requirementRefs
+    text specPath
+    text status }
+  case_results { text id PK
+    text caseId
+    text runId
+    text result
+    json evidence }
+  links { text id PK
+    text kind
+    text fromRef
+    text toRef
+    text source }
+  approvals { text id PK
+    text runId
+    json action
+    text status }
+```
+
+### 1.5 Findings that matter for stage 1
+
+| Finding | Detail | Evidence |
+|---|---|---|
+| Small case type | The built `TestCase` is smaller than the STAGES.md design. It has no `covers`, `preconditions`, `data`, `revision`, `origin`, `waitsOn`, AI-Vision form, or Playwright form | `src/types.ts` Test case store vs STAGES.md 4.2 |
+| Spec-only linking | A case links to automation by `specPath` only. Every test in that file sets the case result | `linkRunResults` in `src/cases.ts` |
+| Thin case results | `CaseResult` has no `stage`, `engine`, `sha`, `prRef`, environment, or step results. STAGES.md 4.2 lists the first four | `src/types.ts` |
+| String test identity | Test identity is a string. The Playwright project (browser or device) is a title prefix | `src/runner/playwright-json.ts` |
+| No tracker tables | No table holds Jira or Linear tickets, acceptance criteria, or releases | Section 1.3 |
+| Defects without rows | Defects have no row. Severity, state, and the failing step are not stored | `src/flows/defects.ts` |
+| History lost on edit | Edits lose history: case edits overwrite, approval edits replace the draft, and no row records who decided | `updateCase`, `approveAction` |
+| Flakiness as notes | Flakiness is a free-text memory note plus a scan of recent runs | `memory.kind = flaky_spec`, `src/agent/triage.ts` |
+| Previews in memory | Deploy previews are in memory only | `rememberPreview` |
+| Stages not built | `RunRecord.stage` and `Watch.stages` are not built | grep for `StageKey` in `src/` finds none |
+
+---
+
+## 2. The QA domain a tester expects
+
+### 2.1 Concepts
+
+| Concept | What a tester means | Key fields | Relates to |
+|---|---|---|---|
+| Product | What the company ships | name | Has apps |
+| App | One deployable unit under test: web, API, mobile | name, kind, host or base URL per environment, repo | Has areas and pages |
+| Area | A feature area in user words: "Checkout and payment" | stable id, name, paths, routes | Has pages, requirements, cases |
+| Page | A route pattern a user visits: `/checkout` | app, route, title | Has states; cases visit it |
+| State | A distinct view on one page: a dialog, an empty cart | page, heading set or dialog name | Cases visit it |
+| Requirement | A ticket that asks for behavior: story, feature, bug fix | external key, title, type, status, release, text | Has acceptance criteria; cases cover it |
+| Acceptance criterion | One checkable statement of a requirement | requirement, ordinal, text | Cases cover it |
+| Folder | A place in the case tree: "Checkout / Coupons" | name, parent folder, position | Holds cases and folders |
+| Test case | A repeatable check | key, title, preconditions, steps (action, data, expected), priority, type, status, revision, owner, folder | Covers criteria; has automation forms; belongs to suites |
+| Case version | The case as it was at one revision | case, revision, snapshot of title and steps, who, when | Run items pin one |
+| Test step | One action with its expected result | order, action, data, expected | Step results point to it through the pinned version |
+| Test data | Inputs a case needs: users, cards, coupons | name, values or a secret ref, environment | Cases and steps use it |
+| Test suite | A named set of cases: smoke, checkout regression | name, a static list of cases or a saved query (folder, kind, priority, requirement, words) | Plans and test runs use it |
+| Test plan | What to run for a goal, where, by when | name, release, suites or cases, environment, configurations, dates, status | Has test runs, one per configuration |
+| Environment | Where the app runs: local, preview, staging, prod | name, base URL, kind | Test runs run in it |
+| Configuration | How the test runs: browser, OS, device, viewport | browser, version, OS, device, project name | Test runs run with it |
+| Build | The exact code under test | repo, sha, version label, deploy id | Test runs test it |
+| Dot run | One automated flow job of a dot: a PR check, a post-merge run, a rerun | kind, trigger, steps, report, verdict | Produces automated results; never a test run itself |
+| Test run | A planned pass over a set of cases | name, source (manual or automated), plan, suite, environment, configuration, build sha, assignee, status | Has run items |
+| Run item | One case inside one test run | test run, case, pinned case version, state, assignee | Has results |
+| Result | One attempt on a run item; the newest attempt sets the item state | run item, attempt, result, engine, duration, sha, environment, configuration, executed by a person or a dot run | Has step results, evidence, defects |
+| Step result | The outcome of one step of the pinned version | step position, result, actual result | Defects point to it |
+| Evidence | Proof: screenshot, video, trace, log, HAR | kind, file, step, kept until | Belongs to a result or step result |
+| Defect | A product fault found by a test | external key, title, severity, priority, status, steps to reproduce, signature | Points to the failing result or step result, build, environment, requirement |
+| Change | A PR, a commit, or a deploy | repo, number or sha, author, state, merged at, deployed to | Builds come from it; requirements link to it |
+| Release and milestone | A target that groups requirements and builds | name, kind (release, milestone, sprint, cycle), due date, state | Has requirements, plans, readiness |
+| Coverage | Which criteria, requirements, areas, and pages have cases, and which passed | computed per scope and build | Read model |
+| Flakiness history | Pass and fail over time per test and configuration | test key, configuration, window counts, last flip, quarantine state | Read model over results |
+| Audit | Who did what, when, from where | actor, action, entity, before, after, time | Every write |
+
+### 2.2 Target diagram
+
+```mermaid
+erDiagram
+  APP ||--o{ AREA : has
+  AREA ||--o{ PAGE : has
+  PAGE ||--o{ STATE : has
+  RELEASE ||--o{ REQUIREMENT : groups
+  REQUIREMENT ||--o{ CRITERION : has
+  CRITERION }o--o{ TEST_CASE : "covered by"
+  FOLDER ||--o{ FOLDER : contains
+  FOLDER ||--o{ TEST_CASE : holds
+  TEST_CASE ||--o{ CASE_VERSION : "snapshot per edit"
+  TEST_CASE }o--o{ PAGE : visits
+  TEST_CASE }o--o{ SUITE : "member of (list or query)"
+  TEST_CASE }o--o{ TEST_DATA : uses
+  PLAN }o--o{ SUITE : runs
+  PLAN }o--|| RELEASE : for
+  PLAN ||--o{ TEST_RUN : "one per configuration"
+  SUITE ||--o{ TEST_RUN : "source (optional)"
+  TEST_RUN }o--|| ENVIRONMENT : in
+  TEST_RUN }o--|| CONFIGURATION : with
+  TEST_RUN }o--|| BUILD : tests
+  BUILD }o--|| CHANGE : "built from"
+  TEST_RUN ||--o{ RUN_ITEM : has
+  RUN_ITEM }o--|| CASE_VERSION : pins
+  RUN_ITEM ||--o{ RESULT : "attempts, newest wins"
+  DOT_RUN ||--o{ RESULT : "produced (automated)"
+  DOT_RUN ||--o{ TEST_RUN : "automated, one per configuration"
+  RESULT ||--o{ STEP_RESULT : has
+  RESULT ||--o{ EVIDENCE : has
+  DEFECT }o--o| RESULT : "found in"
+  DEFECT }o--o| STEP_RESULT : "found at"
+  DEFECT }o--o{ REQUIREMENT : affects
+  CHANGE }o--o{ REQUIREMENT : implements
+```
+
+### 2.3 Dot runs and test runs
+
+A dot run and a test run are different things, and neither one is the other's parent in every case.
+
+| Question | Dot run | Test run |
+|---|---|---|
+| What it is | One automated flow job the queue ran | A planned pass over a set of cases |
+| Who starts it | A trigger: a PR, a merge, a schedule, a rerun | A person (from a suite, a selection, or a plan) or a dot run that reported case results |
+| What it holds | Steps, a test report, a verdict, outward actions | Run items, one per case, each with its results |
+| Where it runs | One runner, one command | One environment and one configuration |
+| How many per pass | One | One per configuration: a plan for Chrome and Safari makes two test runs |
+
+Three shapes follow from this:
+
+- **Manual test run.** A person creates it, works the items one by one, and records results with step results. No dot run takes part.
+- **Automated test run.** A dot run reports results for cases that point to its specs. The dot run creates one automated test run per configuration (Playwright project) it ran, and updates it when its retry pass saves the report again. The test run links back by `dotRunId`, and each result points at the same dot run, so the evidence is one click away. People read it; they do not edit it.
+- **Mixed later.** A manual test run can take an automated result when a person reruns one item's spec. The result then points at that dot run, and the item stays in the manual test run. This is later work.
+
+#### Entities
+
+| Entity | Fields | Rules |
+|---|---|---|
+| Folder | `dotId`, `name`, `parentId` (none for a top folder), `position`, `repo` (the repo of the GitHub issue a ticket folder was made for, set by the designer only) | A tree per dot. A name is unique among its siblings. Deleting a folder moves its cases and subfolders to its parent, and a query suite on it becomes a static list of the cases it held. A suite or plan never fails on a missing folder: the reference is dropped with a note. `test_cases.folderId` places a case; none means unfiled |
+| Case version | `caseId`, `version`, `snapshot` (title, steps, kind, spec file, priority, status, requirements), `actor`, `at` | Written on create and on every edit. `test_cases.revision` is the newest version. Rows are never changed |
+| Suite | `dotId`, `name`, `kind` (`static` or `query`), `caseIds` for a static list, `query` (folder with or without subfolders, kind, priority, requirement, words) | A query suite is read when a test run starts, so it picks up new cases. Retired cases never join |
+| Plan | `dotId`, `name`, `release`, `suiteIds`, `caseIds`, `environment`, `configs` (list of configurations), `status` | Starting a plan makes one test run per configuration, each with `planId` |
+| Test run | `dotId`, `name`, `source` (`manual` or `automated`), `status` (`open`, `in_progress`, `done`, `cancelled`), `environment`, `config` (browser, OS, device, viewport, project), `buildSha`, `assignee`, `planId`, `suiteId`, `dotRunId` (automated only), `startedAt`, `finishedAt` | A manual test run moves to `in_progress` at its first result. A person closes it. An automated test run is `done` when its dot run saves the report |
+| Run item | `testRunId`, `caseId`, `caseVersion`, `position`, `state` (`untested`, `passed`, `failed`, `blocked`, `retest`, `skipped`), `assignee` | One per case per test run. The pinned version decides which steps the tester sees, so a case edit after the start does not move results |
+| Result | `runItemId`, `testRunId`, `caseId`, `attempt`, `result` (`passed`, `failed`, `blocked`, `skipped`), `notes`, `stage`, `engine`, `durationMs`, `sha`, `environment`, `config`, `executedBy` (a person) or `dotRunId` (automated), `steps` (step results), `evidence`, `defects`, `at` | Every attempt is kept. The newest attempt sets the item state. Retest marks the item `retest`, and the next result is the next attempt |
+| Step result | Inside `result.steps`: `index` (position in the pinned version), `result`, `actual` | A result cannot be `passed` when one of its steps failed |
+| Evidence | Inside `result.evidence`: artifact names of the dot run (screenshots, video, trace) | Manual results carry notes and step actual results for now; uploads are later work |
+| Defect | Inside `result.defects`: `ref` (tracker key or `owner/name#N`), optional `stepIndex` | The defect row of section 3 points at the result and the step |
+| Draft version | A `case_versions` row with `draft` set to `draft` (or `rejected`), plus `ticket` and `impactId` | Proposed by a ticket review (KAT-304). It is not part of the case's history: `caseVersions` and run items ignore it. Accepting it writes a normal next version through the usual edit path and removes the draft row; rejecting keeps it as `rejected` |
+| Impact row | `dotId`, `ticket`, `runId`, `subject` (`case` or `spec`), `caseId`, `specPath`, `title`, `verdict` (`valid`, `update`, `obsolete`), `confidence`, `ticketLine`, `note`, `changes` (the new steps), `signals`, `state` (`open`, `accepted`, `rejected`, `expired`, `none`), `ticketHash`, `draftVersion`, `approvalId`, `decidedAt`, `decidedBy` | One per dot, ticket, and subject (table `case_impacts`). An obsolete row follows its Inbox approval (`case_retire`): executed means accepted, rejected means rejected, expired or superseded means expired, and a case retired by hand accepts it. `ticketHash` is a hash of the ticket title, description, and acceptance criteria the row was checked against, and so of the text a person decided on. A flagged case (`state` open, verdict not `valid`) carries "Needs review". See [STAGES.md](STAGES.md) section 3.8 |
+
+`case_results` becomes the results table: it keeps its rows and gains the new columns, so no data moves. A case's latest result is still the newest row for that case, from any test run or none.
+
+#### Later work
+
+- **Shared steps.** A step list that several cases call, with its own versions. A case version then pins the shared step versions too.
+- **Data-driven iterations.** One case run once per data row (Xray iterations, TestRail parameters). A result then has one entry per iteration, each with its own step results.
+- **Uploads on manual results.** Screenshots and files from the phone, stored next to run artifacts.
+
+---
+
+## 3. Gaps
+
+Risk words: Low means a new table or an optional field, with no change to old reads. Medium means a backfill from JSON or a change to how existing code writes. High means a change to an existing field's meaning.
+
+| Gap | Today | What breaks without it | Proposed table or field | Migration risk |
+|---|---|---|---|---|
+| Case versions | Missing. `updateCase` overwrites | A result cannot say which steps it ran. Two writers (designer and person) overwrite each other. STAGES.md 3.5 retire and revise rules cannot work | `test_cases.revision` (int, starts at 1); new `case_versions` (append only: `caseId`, `version`, `snapshot` json, `actor`, `at`), written on create and every edit; run items pin `caseVersion`. Later: 409 on a stale revision, as `pages` does | Low. Existing cases get version 1 on first use |
+| Folders | Missing. Cases are one flat list | A team with 300 cases cannot find them. TestRail sections, Xray folders, and True Platform folders have no source | New `folders` (`dotId`, `name`, `parentId`, `position`); `test_cases.folderId` | Low |
+| Step results | Missing. Only `runs.steps` (flow log) and `PageObservation.steps` | The tester cannot see which step failed and what happened. Xray and TestRail step results have no source | `case_results.steps` json: `{ index, result, actual? }[]`, where `index` is the step position in the pinned case version. Step ids that survive a reorder are later work | Low |
+| Test identity | `file` + `title` string; project in the title | Flaky history, case links, and sync keys change when a title or a project changes | `testKey` = `<repo>:<file>::<describe › title>`, plus `project` as its own field on `TestCaseResult`; `test_cases.specTitle` to pick one test inside `specPath` | Medium. New field on new reports; old reports keep the prefix |
+| Test result rows | Missing. `runs.report.cases[]` JSON | Flakiness, history per test, and coverage need a scan and parse of every run | New `test_results`: `dotId`, `runId`, `testKey`, `file`, `title`, `project`, `status`, `retries`, `durationMs`, `error` (first line), `sha`, `environment`, `at`. Index on `(dotId, testKey, at)` | Medium. Backfill from `runs.report`; volume grows with runs (cap by age) |
+| Test runs | Missing. Dot runs stand in for them | A manual pass has nowhere to live. A pass over Chrome and Safari cannot be one plan with two test runs. Xray Test Executions and TestRail runs map to the wrong thing | New `test_runs`: `dotId`, `name`, `source` (`manual`, `automated`), `status`, `environment`, `config` json, `buildSha`, `assignee`, `planId`, `suiteId`, `dotRunId`, `startedAt`, `finishedAt` | Medium. Backfill: one automated test run per dot run that wrote case results |
+| Run items | Missing | A test run cannot list its cases, their state, or who works them | New `run_items`: `testRunId`, `dotId`, `caseId`, `caseVersion`, `position`, `state` (`untested`, `passed`, `failed`, `blocked`, `retest`, `skipped`), `assignee` | Medium. Backfill: one item per case in each backfilled test run, latest result wins |
+| Result context | `result`, `notes`, `evidence`, `source` | The guard cannot say "passed on staging in Chrome at 9be0d11". Duplicate results from two engines mix. A retest overwrites the first attempt | `case_results` gains `runItemId`, `testRunId`, `attempt`, `stage`, `engine` (`playwright`, `aivision`, `manual`), `durationMs`, `sha`, `environment`, `config` json, `executedBy`, `dotRunId`, `steps` json, `defects` json | Low. New columns; existing rows keep their meaning |
+| Requirement store | GitHub only (`issue_state`); Jira and Linear in run snapshots; titles in `ticket_titles` | A case points to a key the dot may not know. Coverage per release is wrong for Jira and Linear. The designer has no current AC to read | New `requirements`: id lower-case ref, `tracker`, `key`, `externalId`, `title`, `type`, `status`, `statusCategory`, `releaseIds`, `description`, `acText`, `bodyHash`, `url`, `fetchedAt`. `issue_state` and `ticket_titles` stay and feed it | Medium. Backfill from `issue_state`, `ticket_titles`, and the newest `ticket_review` run per key |
+| Acceptance criteria | One text field on `Ticket` | A case cannot cover one criterion. Coverage per criterion is not possible | New `criteria`: `requirementRef`, `ordinal`, `text`, `hash`, `status` (`active`, `removed`). `test_cases.covers` json of criterion ids or idea text | Low |
+| Defect records | Approvals and links | No severity, no state, no link to the failing case, step, build, or environment. Readiness counts defects by guess | New `defects`: `dotId`, `ref`, `tracker`, `externalId`, `url`, `title`, `severity` (`critical`, `high`, `medium`, `low`), `priority`, `state`, `sig`, `dotRunId`, `testRunId`, `caseId`, `resultId`, `stepIndex`, `testKey`, `sha`, `environmentId`, `approvalId`, `filedAt`, `closedAt`. `links.kind` adds `defect` (STAGES.md 4.1) | Medium. Backfill from executed `file_defect` and `issue_create` approvals |
+| Test suites | Missing. `smokeGrep` and spec picks per run | The team cannot name "checkout regression" and start a test run from it again. Sync to TestRail suites, Xray Test Sets, and True Platform test suites has no source | New `suites`: `dotId`, `name`, `kind` (`static`, `query`), `caseIds` json, `query` json (folder, subfolders, kind, priority, requirement, words) | Low |
+| Test plans | Missing. `pages.kind = test_plan` is Markdown | No "run these suites on staging in Chrome and Safari for 2026.11". No progress per plan | New `plans`: `dotId`, `name`, `release`, `suiteIds`, `caseIds`, `environment`, `configs` json, `status`, `dueAt`. A plan starts one test run per configuration | Low |
+| Environments | `Watch.baseUrl`, preview URL in memory | Results do not say where they ran. A preview result and a staging result count the same | New `environments`: `dotId`, `name`, `kind` (`local`, `preview`, `staging`, `production`), `baseUrl`. `runs.environment` (snapshot: id, name, baseUrl) | Low |
+| Configurations | Playwright project in the title prefix | Flaky in Safari and stable in Chrome look the same. Xray and TestRail configurations cannot map | `config` json on `test_runs`, `test_results`, and `case_results`: `{ project, browser, browserVersion, os, device, viewport }`, read from the Playwright JSON report | Low |
+| Builds and deploys | `trigger.pr.headSha`, `mergeSha`; previews in memory | "Which build did we test" needs the trigger JSON. Previews vanish on restart | `runs.build` json: `{ repo, sha, ref, version?, deployId?, url? }`. New `deploys`: `repo`, `sha`, `environment`, `url`, `state`, `at` from `deployment_status` | Low |
+| Change records | `runs.trigger`, `events` | "Out of date" and release contents need run scans. A PR has no title or state of its own | New `changes`: id `owner/name#N` or `owner/name@sha`, `kind` (`pr`, `commit`), `title`, `author`, `state`, `headSha`, `baseRef`, `mergedSha`, `mergedAt`, `url` | Low |
+| Releases and milestones | GitHub milestone string on the issue only | Readiness per release works only for GitHub. Jira `fixVersions`, Linear cycles and project milestones are not read | New `releases`: `dotId`, `name`, `kind` (`release`, `milestone`, `sprint`, `cycle`), `tracker`, `externalId`, `dueAt`, `state`. `requirements.releaseIds` | Low |
+| Case areas | Profile areas exist; cases have none | Coverage by area and the map cannot count cases | `test_cases.areaId` (profile area slug), `test_cases.tags` json | Low |
+| Page identity | Map nodes built on read from `observations.jsonl` | A case cannot say which page it checks. Gap nodes cannot list the cases that should cover them | New `app_pages`: `dotId`, `host`, `route`, `stateKey`, `title`, `firstSeenAt`, `lastSeenAt`, `lastRunId`, filled when a run ends. `test_cases.pages` json of `app_pages.id` | Low |
+| Test data | `QaTestToRun.data` free text; `passEnv` for secrets | Cases cannot share a "guest with a coupon" set. Data-driven runs (Xray iterations, TestRail parameters) cannot map | Stage 1: `test_cases.preconditions`, `test_cases.data` (text). Later: `data_sets` (`dotId`, `name`, `rows` json, `secretRefs` as env names only) | Low |
+| Flakiness history | `memory` free text; triage over recent runs | No flake rate, no quarantine, no trend | Read model over `test_results` (Test result rows). New `test_flags`: `dotId`, `testKey`, `config`, `state` (`quarantined`, `known_flaky`), `reason`, `actor`, `at` | Low after Test result rows |
+| Coverage history | Computed on read in traceability and the map | No coverage at a past build or release. Reports change after the fact | Read model first. Later `coverage_snapshots`: `dotId`, `scope` (`release`, `area`, `requirement`), `scopeId`, `sha`, `counts` json, `at`, written by the Release guard | Low |
+| Audit trail | `device_audit`, `connect_audit`, `source` fields; no decider on approvals | No answer to "who approved this defect" or "who changed this case". Sync conflicts cannot be explained | New `audit`: `at`, `actor` (`device:<id>`, `token`, `dot:<id>/<stage>`, `github:<login>`, `system`), `action`, `entity`, `entityId`, `before` hash, `after` json, `runId`. `approvals.decidedBy`, `approvals.originalBody` | Low |
+| Run stage | Missing | Results and timeline rows cannot say which specialist did the work | `RunRecord.stage` (STAGES.md task 1), copied into `case_results.stage` | Low |
+| Sync references | Refs are text in `links`; filed URL in `approvals.action.meta` | Sync cannot tell a local case from an imported one, find the remote id, or detect a conflict | New `external_refs` (section 4.6) | Low |
+| Referential checks | None | Deleted dots leave orphan cases, results, and links | Keep no foreign keys (the migrator cannot add them). Add a boot check that counts orphans and a delete path per dot | Low |
+
+---
+
+## 4. External sync
+
+Direction words: Pull means the tool is the source and localdost reads. Push means localdost is the source and writes. Both means each side owns some fields. Field names come from public docs as known on 2026-10-09; rows marked "to confirm" need a check against the API before the sync task starts.
+
+### 4.1 Ownership rules
+
+| Rule | Why |
+|---|---|
+| One owner per field. The other side treats it as read-only | No merge of free text, no edit wars |
+| The tracker owns requirements, criteria text, releases, defect state | People work there |
+| localdost owns automated results, evidence, flakiness, and coverage it computes | It runs the tests |
+| Cases: the side that created the case owns its title and steps. The other side gets a copy | A designer case pushes; an imported TestRail case pulls |
+| Every push carries the localdost marker (`<!-- localdost:bot sig=... -->`) or an external id field, as the loop guard does today | No echo loops |
+| Every push passes the rules gate as `mcp_tool` or a new `test_sync` action kind, default `ask` | Same as other outward actions |
+
+### 4.2 Jira and Xray
+
+Xray adds issue types to Jira: Test, Pre-Condition, Test Set, Test Plan, Test Execution. A Test Execution is a test run: it lists Tests, and each Test inside it is a Test Run with its own status and step results. Results import through `POST /api/v2/import/execution` (Xray JSON) or JUnit import. Xray Cloud also has a GraphQL API (to confirm per edition: Cloud or Data Center). Xray Cloud organizes Tests in a folder tree in the Test Repository of each project.
+
+| localdost entity | Jira or Xray entity | Id kept | Fields and owner | Direction |
+|---|---|---|---|---|
+| Requirement | Jira issue (Story, Epic, Bug) | `id` (numeric), `key` | summary, description, status, priority, labels, components: Jira | Pull |
+| Acceptance criterion | Description section or a custom field (`JIRA_AC_FIELD`) | requirement key + ordinal | text: Jira | Pull |
+| Release | Version (`fixVersions`), sprint field | version `id` | name, releaseDate, released: Jira | Pull |
+| Folder | Test Repository folder | folder path and id | name, parent: owner of the case tree | Both |
+| Test case | Xray Test issue, type Manual or Generic | issue `id`, `key` | summary, steps (action, data, result): case owner. Test type Generic carries the `testKey` as its definition | Both |
+| Case version | Test version (Xray Cloud test versioning, to confirm per edition) | version id | case owner | Both |
+| Case covers requirement | Issue link "tests" (Xray coverage) | link `id` | localdost for its cases | Push |
+| Precondition | Pre-Condition issue | `key` | text: case owner | Push |
+| Suite | Test Set issue | `key` | members: localdost for its suites. A query suite pushes its members at the time of the push | Push |
+| Plan | Test Plan issue | `key` | tests, fixVersion: localdost or Jira, per plan. Each test run of the plan is a Test Execution linked to the Test Plan | Both |
+| Test run | Test Execution issue | `id`, `key` | summary, `testEnvironments` (environment and configuration), revision (build sha), fixVersion, assignee: localdost | Push |
+| Run item | Test Run (one Test inside one Test Execution) | Test Run id | status, assignee: localdost | Push |
+| Result | The Test Run's status and comment; earlier attempts as the Test Run history | Test Run id | status (`PASSED`, `FAILED`, `TODO`, `EXECUTING`, `ABORTED`), comment, start, finish, executedBy: localdost | Push |
+| Step result | Test Run step | step id, mapped by position in the pinned version | status, actualResult, evidences, defects: localdost | Push |
+| Evidence | Attachment on the Test Run or step | attachment id | localdost | Push |
+| Defect | Jira issue type Bug, linked to the Test Run or step | `id`, `key` | summary, steps, environment: localdost at create; status, resolution: Jira | Push, then Pull |
+| Environment and configuration | `testEnvironments` values (strings), one Test Execution per configuration | name | localdost | Push |
+| Dot run | None. A link in the Test Run comment and a remote link on the ticket point at it | `globalId` = dot run id | localdost | Push |
+
+Item state map: `passed` to PASSED, `failed` to FAILED, `blocked` to ABORTED or a custom BLOCKED status (to confirm per project), `untested` and `skipped` to TODO, `retest` to TODO with the earlier attempt kept in history.
+
+### 4.3 Linear
+
+Linear has no test management objects. localdost keeps folders, cases, suites, plans, test runs, and results, and Linear holds requirements, defects, and links back.
+
+| localdost entity | Linear entity | Id kept | Fields and owner | Direction |
+|---|---|---|---|---|
+| Requirement | Issue | `id` (UUID), `identifier` (`ENG-12`) | title, description, state, priority (0 to 4), labels, parent: Linear | Pull |
+| Acceptance criterion | Description section or checklist | identifier + ordinal | Linear | Pull |
+| Release | Cycle, project milestone, project | `id` | name, dates: Linear | Pull |
+| Requirement links | Issue relations (`blocks`, `related`, `duplicate`), parent and sub-issues | relation `id` | Linear | Pull |
+| Defect | Issue with label `localdost` (exists today) | `id`, `identifier` | title, body: localdost at create; state: Linear | Push, then Pull |
+| Test status on a requirement | Attachment (URL link to the test run or the case list) and one comment | attachment `id` | localdost | Push |
+| Folder, case, suite, plan, test run, run item, result | None | | localdost only | None |
+
+### 4.4 TestRail
+
+TestRail API v2. Ids: project `P`, suite `S`, section, case `C`, plan, run `R`, test `T` (a case inside a run), result, milestone `M`, configuration. A TestRail run is a test run, and a TestRail test is a run item. A TestRail suite is a case repository (in multi-suite mode), not a localdost suite.
+
+| localdost entity | TestRail entity | Id kept | Fields and owner | Direction |
+|---|---|---|---|---|
+| Dot or product | Project, plus the suite that holds its cases (single or multi-suite mode) | `project_id`, `suite_id` | TestRail | Pull |
+| Folder | Section (nested through `parent_id`) | `section_id` | name, parent: owner of the case tree | Both |
+| Test case | Case | `case_id` | title, `custom_preconds`, `custom_steps_separated` (content, expected), `priority_id`, `type_id`, `refs` (requirement keys as text), `estimate`, `section_id`: case owner | Both |
+| Case version | Case history (`get_history_for_case`) | change id | TestRail keeps it; localdost reads it | Pull |
+| Requirement link | `refs` field on the case | text | case owner | Both |
+| Release | Milestone (with parent milestones) | `milestone_id` | TestRail or Jira, per team | Pull |
+| Suite | No direct match. A static suite becomes the `case_ids` of the run it starts; a query suite is resolved first | | localdost | Push as case lists |
+| Plan | Plan with entries; each entry has one run per configuration | `plan_id`, `entry_id` | localdost for plans it makes | Push |
+| Configuration | Configuration group and config (browser, OS) | `config_id` | TestRail admin | Pull |
+| Test run | Run (`add_run` with `case_ids`, or a run inside a plan entry with `config_ids`) | `run_id` | name, milestone, description (build sha, environment), `assignedto_id`: localdost | Push |
+| Run item | Test | `test_id` | status, `assignedto_id`: localdost | Push |
+| Result | Result (`add_results_for_cases`), one per attempt; TestRail shows the newest | `result_id` | `status_id` (1 Passed, 2 Blocked, 3 Untested, 4 Retest, 5 Failed), `comment`, `version` (build sha), `elapsed`, `defects` (keys as text): localdost | Push |
+| Step result | `custom_step_results` (content, expected, actual, `status_id`) | position | localdost | Push |
+| Evidence | Attachment on the result (`add_attachment_to_result`) | `attachment_id` | localdost | Push |
+| Defect | `defects` text on the result; the defect itself in Jira or another tracker | key | Tracker | Push the key |
+| Dot run | None. A link in the result comment points at it | | localdost | Push |
+
+Item state map: `passed` 1, `blocked` 2, `untested` 3, `retest` 4, `failed` 5, `skipped` to a custom status or Untested with a comment (to confirm per instance). TestRail steps have no step ids. localdost maps by position in the pinned case version, so a reorder after a test run started does not move its step results.
+
+### 4.5 Katalon True Platform
+
+True Platform has releases and sprints, requirements synced from Jira or Azure DevOps, test cases in folders with versions, test suites, manual and automated test runs with an executor and a configuration (for example "Windows 11 + Chrome 143"), step-level evidence, and defects linked to Jira (docs read 2026-10-09: Manual Test Run, Manage Releases and Requirements). It accepts JUnit and Playwright reports through the Katalon report uploader, and it has an MCP server. API endpoint and field names: to confirm in the True Platform API docs.
+
+| localdost entity | True Platform entity | Id kept | Fields and owner | Direction |
+|---|---|---|---|---|
+| Requirement | Requirement (synced from Jira or ADO) | requirement id + the Jira key | True Platform mirrors Jira; localdost reads the Jira key | Pull (or read through Jira) |
+| Release and plan | Release or sprint, with its build | release id, sprint id | True Platform | Pull |
+| Folder | Test case folder | folder id | owner of the case tree | Both |
+| Test case and version | Test case (manual or automated) and its version | test case id, version | name, steps: case owner | Both |
+| Suite | Test suite | suite id | owner of the suite | Both |
+| Test run | Test run (manual or automated), in a release or sprint | test run id | name, release, sprint, configuration, executor: localdost for its test runs | Push |
+| Run item and result | Test result inside the test run, with step results, screenshots, video | result id | localdost | Push (report upload for automated test runs) |
+| Configuration | Configuration (OS, browser) | config id | True Platform | Pull |
+| Defect | Defect linked to Jira | Jira key | Jira | Pull state |
+| Dot run | None. The uploaded report names it | | localdost | Push |
+
+Two paths, smallest first: (1) upload the JUnit or Playwright report of each automated test run with the uploader, which needs no case mapping; (2) map folders, cases, and test runs one to one through the API or the MCP server for manual test runs and step results.
+
+### 4.6 The external ref shape
+
+Every syncable entity (requirement, criterion, release, folder, case, case version, suite, plan, test run, run item, result, defect, environment, configuration) gets zero or more rows in one table. No sync field goes on the entity rows, so a new tool adds no columns.
+
+```ts
+// src/types.ts (add only). Table external_refs, index on (entity, entityId) and (system, externalId).
+export interface ExternalRef {
+  id: string;
+  dotId: string;
+  /** Local table and row: 'test_cases' + case id. */
+  entity: string;
+  entityId: string;
+  /** 'jira' | 'xray' | 'linear' | 'testrail' | 'katalon' | 'github'. */
+  system: string;
+  /** Site or tenant: 'acme.atlassian.net', TestRail host, True Platform project id. */
+  instance: string;
+  /** Remote type: 'issue', 'test', 'test_execution', 'test_run', 'section', 'case', 'run', 'test'. */
+  externalType: string;
+  /** Immutable remote id: Jira numeric id, Linear UUID, TestRail case id. */
+  externalId: string;
+  /** Human key, can change on a move: SHOP-12, C123. */
+  externalKey?: string;
+  url?: string;
+  /** Who owns the content fields of this pair. */
+  owner: 'local' | 'remote';
+  direction: 'pull' | 'push' | 'both';
+  /** Remote version or updated time at the last sync, for conflict checks. */
+  remoteVersion?: string;
+  /** Hash of the local fields at the last push. */
+  localHash?: string;
+  syncedAt?: string;
+  state: 'linked' | 'pending' | 'conflict' | 'error' | 'unlinked';
+  error?: string;
+}
+```
+
+Rules: `externalId` is the join key, never `externalKey`. A conflict is a change on the non-owner side since `syncedAt`; it stays in state `conflict` and shows in the Inbox. A delete on either side sets `unlinked` and deletes nothing.
+
+---
+
+## 5. Phased plan
+
+Each row is one PR that leaves the product working. All changes are add only: new tables through `SCHEMA` and new optional fields, so `migrate()` handles them and an older build ignores them. Sizes: S is one table or a few fields, with no backfill. M is several fields plus a backfill, or a new flow. L is an external sync with mapping both ways.
+
+### Phase 1: stage 1, the dot manages tests on its own
+
+| Name | Change | Gaps | Size | Depends on | Unblocks |
+|---|---|---|---|---|---|
+| Run context fields | `RunRecord.stage` (STAGES.md task 1); `runs.environment` and `runs.build` snapshots | Run stage, Environments, Builds and deploys (fields) | S | | Every result knows stage, place, and build |
+| Case versions and folders | `test_cases.revision` and `case_versions` written on every create and edit; `folders` table and `test_cases.folderId`, with create, rename, move, and delete | Case versions, Folders | M | | A test run can pin what it ran; a large case set has a tree |
+| Case details | `origin`, `preconditions`, `covers`, `areaId`, `tags`, `specTitle`, step `data`; 409 on a stale revision | Case areas, Test data (text) | M | Case versions and folders | Designer writes and person edits stop overwriting each other |
+| Test runs and results | `test_runs` and `run_items` tables; `case_results` gains `runItemId`, `testRunId`, `attempt`, `stage`, `engine`, `durationMs`, `sha`, `environment`, `config`, `executedBy`, `dotRunId`, `steps`, `defects`; manual result and retest API; a dot run that reports case results creates its automated test run per configuration; backfill of one automated test run per dot run from existing case results | Test runs, Run items, Result context, Step results, Configurations | M | Case versions and folders | A person works a manual test run step by step; automated passes show as read-only test runs with their dot run evidence |
+| Test result table | `test_results` table written at report save, with `testKey` and `project` as fields; backfill job from `runs.report` (last 90 days) | Test identity, Test result rows, Configurations | M | | Flakiness and history queries |
+| Requirement tables | `requirements` and `criteria` tables, filled by ticket review, pollers, and `issue_state`; backfill from the newest `ticket_review` run per key | Requirement store, Acceptance criteria | M | | Designer input, coverage per criterion |
+| Defect table | `defects` table and `links.kind = 'defect'`; the defect flows write a row; severity from the review; `resultId` and `stepIndex` set when a case step failed; `case_results.defects` refs become rows; backfill from executed approvals | Defect records | M | Test runs and results | Defect with severity, linked to the failing step |
+| Suite and plan tables | `suites` (static list or saved query) and `plans` tables with their API; a test run starts from a suite, a selection, or a plan (one test run per plan configuration) | Test suites, Test plans | M | Test runs and results | Named regression sets and planned passes |
+| Run a suite automatically | "Run with the dot": a `rerun` with the specs of an automated suite's cases, which fills an automated test run with the suite's `suiteId` | Test suites | S | Suite and plan tables | Regression sets on demand |
+| Environment table | `environments` table; preview URLs stored in `deploys` instead of memory | Environments, Builds and deploys | S | Run context fields | Results per environment survive a restart |
+| Audit log | `audit` table; `approvals.decidedBy` and `approvals.originalBody`; actor on case writes | Audit trail | S | | Who did what |
+| App page records | `app_pages` written at run end from `observations.jsonl`; `test_cases.pages` | Page identity | S | | Cases on the map |
+| Read models | Read models: flake rate and `test_flags` (quarantine), coverage per criterion, requirement, area, and page | Flakiness history, Coverage history | M | Test result table, Requirement tables, App page records | Release guard input |
+
+Order: Case versions and folders, Test runs and results, Suite and plan tables first: they fix the model the sync maps onto. Then Run context fields, Audit log, Case details, Test result table, Requirement tables. Then Defect table, Run a suite automatically, Environment table, App page records. Read models last. After Defect table the dot can design cases, file them in folders, group them in suites and plans, work manual test runs, record automated test runs per configuration with step results and evidence, and file a defect that points to the failing step, with no outside tool.
+
+### Phase 2: sync
+
+| Name | Change | Size | Depends on |
+|---|---|---|---|
+| External ref table | `external_refs` table; backfill from `issue_state` ids, `requirements.externalId`, and `defects.externalId` | S | Requirement tables, Defect table |
+| Release table | `releases` table: Jira `fixVersions` and sprints, Linear cycles and project milestones, GitHub milestones; `requirements.releaseIds` | M | Requirement tables |
+| Sync action kind | `test_sync` action kind (default `ask`) through the rules gate; conflict state in the Inbox | S | External ref table |
+| Katalon report upload | Katalon True Platform, path 1: upload the JUnit or Playwright report of each automated test run | S | Sync action kind |
+| Xray sync | Xray: push folders and Test issues for designer cases, Test Sets for suites, Test Plans for plans, one Test Execution per test run and its Test Runs per run item with step results and evidence; pull coverage links | L | External ref table, Sync action kind, Test runs and results |
+| TestRail sync | TestRail: map sections and cases both ways, push plans with one run per configuration, tests per run item, and one result per attempt with step results and attachments | L | External ref table, Sync action kind, Test runs and results |
+| Linear status link | Linear: attachment link and one status comment per requirement | S | External ref table, Sync action kind |
+| Katalon case mapping | Katalon True Platform, path 2: folder, case, test suite, and test run mapping through the API or the MCP server, with manual results and step results | M | External ref table, Sync action kind, Katalon report upload (API to confirm) |
+| Coverage snapshots | `coverage_snapshots` per release, written by the Release guard | S | Release table, Read models |
+
+### Risks for the whole plan
+
+| Risk | Mitigation |
+|---|---|
+| Backfills read every run row and parse JSON | Run them as a queued job in batches of 200, once, with a marker in `poll_cursors` |
+| `test_results` grows with every run | Keep 180 days or the cap per dot, like artifacts |
+| New union values (item states such as `retest` and `untested`) break exhaustive client maps | Change the server and client maps in the same PR, as STAGES.md asks for `JobKind` |
+| Two writers for one case (designer, person, sync) | Case versions on every write, a revision check (Case details), owner field on `external_refs` |
+| Evidence names point to files the artifact cap deleted | Mark the evidence `pruned` when the cap deletes it, and push evidence to the external tool before the cap runs |