(null);
const [requesting, setRequesting] = useState(false);
+ const [starting, setStarting] = useState(false);
useEffect(() => {
fetchAnalysisRuns(accessToken)
@@ -1597,6 +1611,22 @@ function AnalysisRunsPanel({
}
}
+ async function handleStartReconstruction() {
+ if (!selected) return;
+ setError(null);
+ setStarting(true);
+ try {
+ const started = await startAnalysisRun(accessToken, selected.analysis_run_id);
+ const listed = await fetchAnalysisRuns(accessToken);
+ setRuns(listed.analysis_runs);
+ setSelected(started);
+ } catch (err) {
+ setError(err instanceof BackendError ? err.message : String(err));
+ } finally {
+ setStarting(false);
+ }
+ }
+
async function handleOpen(runId: string) {
setError(null);
try {
@@ -1674,7 +1704,31 @@ function AnalysisRunsPanel({
+ {selected.status_code === "analysis_status_pending" && (
+ {analysisRunNextAction(selected)}
+ )}
+ {selected.run_kind_code === "analysis_run_lineage" &&
+ selected.status_code === "analysis_status_pending" && (
+
+ )}
+ {selected.reconstructed_edges && selected.reconstructed_edges.length > 0 && (
+
+ {selected.reconstructed_edges.map((edge) => (
+ -
+ {edge.child_post_title} follows {edge.parent_post_title}
+
+ ))}
+
+ )}
{selected.source_counts.map((count) => (
-
diff --git a/frontend/src/api.ts b/frontend/src/api.ts
index f9bd4068e..208d0f0dc 100644
--- a/frontend/src/api.ts
+++ b/frontend/src/api.ts
@@ -522,6 +522,14 @@ export interface AnalysisRunStatusEvent {
failure_code?: string;
}
+export interface AnalysisRunReconstructedEdge {
+ parent_post_id: string;
+ parent_post_title: string;
+ child_post_id: string;
+ child_post_title: string;
+ fused_score: number;
+}
+
export interface AnalysisRun {
analysis_run_id: string;
run_kind_code: string;
@@ -536,6 +544,8 @@ export interface AnalysisRun {
source_counts: AnalysisRunCount[];
status_history?: AnalysisRunStatusEvent[];
visible_posts?: { post_id: string; post_title: string }[];
+ reconstructed_edges?: AnalysisRunReconstructedEdge[];
+ reconstruction_result_sha256?: string;
code_revision_sha?: string;
configuration_sha256?: string;
}
@@ -565,3 +575,12 @@ export function createAnalysisRun(
body: JSON.stringify(request),
});
}
+
+export function startAnalysisRun(
+ accessToken: string,
+ analysisRunId: string,
+): Promise {
+ return backendFetch(`/api/analysis-runs/${analysisRunId}/start`, accessToken, {
+ method: "POST",
+ });
+}
diff --git a/lineageweave/__init__.py b/lineageweave/__init__.py
index 5f70c6064..6d22286fa 100644
--- a/lineageweave/__init__.py
+++ b/lineageweave/__init__.py
@@ -55,4 +55,4 @@
"sentence_excerpts",
]
-__version__ = "0.86.0"
+__version__ = "0.87.1"
diff --git a/migrations/0019_analysis_run_reconstruction.sql b/migrations/0019_analysis_run_reconstruction.sql
new file mode 100644
index 000000000..39d517760
--- /dev/null
+++ b/migrations/0019_analysis_run_reconstruction.sql
@@ -0,0 +1,79 @@
+-- Run-scoped lineage reconstruction result (ADR 0019).
+--
+-- A Pending analysis run may later persist the ThreadWeave parent choices
+-- for its cutoff bag. Edges belong to the run, not the live Event Lineage
+-- panel. No post body, DSN, or fabricated measurement is stored.
+
+create table if not exists analysis_run_reconstruction (
+ analysis_run_id uuid primary key
+ references analysis_run (analysis_run_id),
+ result_sha256 text not null,
+ edge_count integer not null,
+ reconstructed_at timestamptz not null,
+ recorded_at timestamptz not null default clock_timestamp(),
+ constraint analysis_run_reconstruction_digest_check
+ check (result_sha256 ~ '^[0-9a-f]{64}$'),
+ constraint analysis_run_reconstruction_edge_count_check
+ check (edge_count >= 0),
+ constraint analysis_run_reconstruction_time_check
+ check (reconstructed_at <= recorded_at)
+);
+
+comment on table analysis_run_reconstruction is
+ 'One immutable reconstruction digest per analysis run; never a post body '
+ 'or a fabricated psychometric score.';
+
+create table if not exists analysis_run_lineage_edge (
+ analysis_run_id uuid not null
+ references analysis_run_reconstruction (analysis_run_id),
+ child_post_id uuid not null
+ references source_post (post_id),
+ parent_post_id uuid not null
+ references source_post (post_id),
+ fused_score double precision not null,
+ reconstructed_at timestamptz not null,
+ primary key (analysis_run_id, child_post_id),
+ constraint analysis_run_lineage_edge_distinct_check
+ check (child_post_id <> parent_post_id),
+ constraint analysis_run_lineage_edge_score_check
+ check (fused_score >= 0 and fused_score <= 1)
+);
+
+comment on table analysis_run_lineage_edge is
+ 'One reconstructed parent choice per child post inside one analysis run.';
+
+create or replace function reject_analysis_run_reconstruction_update()
+returns trigger
+language plpgsql
+as $$
+begin
+ raise exception 'analysis_run_reconstruction_is_immutable';
+end
+$$;
+
+comment on function reject_analysis_run_reconstruction_update() is
+ 'Rejects mutation of a persisted reconstruction digest.';
+
+drop trigger if exists analysis_run_reconstruction_update_reject
+ on analysis_run_reconstruction;
+create trigger analysis_run_reconstruction_update_reject
+before update or delete on analysis_run_reconstruction
+for each row execute function reject_analysis_run_reconstruction_update();
+
+create or replace function reject_analysis_run_lineage_edge_update()
+returns trigger
+language plpgsql
+as $$
+begin
+ raise exception 'analysis_run_lineage_edge_is_immutable';
+end
+$$;
+
+comment on function reject_analysis_run_lineage_edge_update() is
+ 'Rejects mutation of a persisted run-scoped lineage edge.';
+
+drop trigger if exists analysis_run_lineage_edge_update_reject
+ on analysis_run_lineage_edge;
+create trigger analysis_run_lineage_edge_update_reject
+before update or delete on analysis_run_lineage_edge
+for each row execute function reject_analysis_run_lineage_edge_update();
diff --git a/migrations/0020_analysis_source_snapshot_member.sql b/migrations/0020_analysis_source_snapshot_member.sql
new file mode 100644
index 000000000..955d111d8
--- /dev/null
+++ b/migrations/0020_analysis_source_snapshot_member.sql
@@ -0,0 +1,35 @@
+-- Create-time cutoff membership for an analysis source snapshot (ADR 0019).
+--
+-- The snapshot digest already hashes authorized post ids. This relation
+-- stores those ids so start reconstructs the same bag, not a later
+-- backfill that shares the cutoff clock. No post body is stored.
+
+create table if not exists analysis_source_snapshot_member (
+ analysis_source_snapshot_id uuid not null
+ references analysis_source_snapshot (analysis_source_snapshot_id),
+ source_post_id uuid not null
+ references source_post (post_id),
+ primary key (analysis_source_snapshot_id, source_post_id)
+);
+
+comment on table analysis_source_snapshot_member is
+ 'Authorized post ids frozen at snapshot capture; start reconstructs '
+ 'these rows and never a later backfill.';
+
+create or replace function reject_analysis_source_snapshot_member_update()
+returns trigger
+language plpgsql
+as $$
+begin
+ raise exception 'analysis_source_snapshot_member_is_immutable';
+end
+$$;
+
+comment on function reject_analysis_source_snapshot_member_update() is
+ 'Rejects mutation of frozen snapshot membership.';
+
+drop trigger if exists analysis_source_snapshot_member_update_reject
+ on analysis_source_snapshot_member;
+create trigger analysis_source_snapshot_member_update_reject
+before update or delete on analysis_source_snapshot_member
+for each row execute function reject_analysis_source_snapshot_member_update();
diff --git a/migrations/rollback/0019_analysis_run_reconstruction.sql b/migrations/rollback/0019_analysis_run_reconstruction.sql
new file mode 100644
index 000000000..ce0c73588
--- /dev/null
+++ b/migrations/rollback/0019_analysis_run_reconstruction.sql
@@ -0,0 +1,37 @@
+-- Fail-closed rollback for migration 0019.
+--
+-- Reconstruction evidence must be exported or explicitly deleted under an
+-- approved retention procedure before these objects can be removed.
+
+begin;
+
+do $$
+declare
+ relation_name text;
+ relation_has_rows boolean;
+begin
+ foreach relation_name in array array[
+ 'analysis_run_lineage_edge',
+ 'analysis_run_reconstruction'
+ ] loop
+ if to_regclass('public.' || relation_name) is not null then
+ execute format('select exists (select 1 from %I)', relation_name)
+ into relation_has_rows;
+ if relation_has_rows then
+ raise exception 'analysis_run_reconstruction_not_empty';
+ end if;
+ end if;
+ end loop;
+end
+$$;
+
+drop trigger if exists analysis_run_lineage_edge_update_reject
+ on analysis_run_lineage_edge;
+drop trigger if exists analysis_run_reconstruction_update_reject
+ on analysis_run_reconstruction;
+drop function if exists reject_analysis_run_lineage_edge_update();
+drop function if exists reject_analysis_run_reconstruction_update();
+drop table if exists analysis_run_lineage_edge;
+drop table if exists analysis_run_reconstruction;
+
+commit;
diff --git a/migrations/rollback/0020_analysis_source_snapshot_member.sql b/migrations/rollback/0020_analysis_source_snapshot_member.sql
new file mode 100644
index 000000000..c0bdd685a
--- /dev/null
+++ b/migrations/rollback/0020_analysis_source_snapshot_member.sql
@@ -0,0 +1,27 @@
+-- Fail-closed rollback for migration 0020.
+--
+-- Snapshot membership must be exported or explicitly deleted under an
+-- approved retention procedure before these objects can be removed.
+
+begin;
+
+do $$
+declare
+ relation_has_rows boolean;
+begin
+ if to_regclass('public.analysis_source_snapshot_member') is not null then
+ execute 'select exists (select 1 from analysis_source_snapshot_member)'
+ into relation_has_rows;
+ if relation_has_rows then
+ raise exception 'analysis_source_snapshot_member_not_empty';
+ end if;
+ end if;
+end
+$$;
+
+drop trigger if exists analysis_source_snapshot_member_update_reject
+ on analysis_source_snapshot_member;
+drop function if exists reject_analysis_source_snapshot_member_update();
+drop table if exists analysis_source_snapshot_member;
+
+commit;
diff --git a/pyproject.toml b/pyproject.toml
index 0393b774a..9dea9d3f1 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "lineageweave"
-version = "0.86.0"
+version = "0.87.1"
description = "Reconstructs git-branch-style lineage DAGs from scattered short records using multi-channel score fusion and LLM adjudication."
readme = "README.md"
license = { text = "MIT" }
diff --git a/scripts/seed_demo_data.py b/scripts/seed_demo_data.py
index f6f575ccc..0131cc33d 100644
--- a/scripts/seed_demo_data.py
+++ b/scripts/seed_demo_data.py
@@ -120,6 +120,8 @@ def seed(
cur.execute((migrations / "0015_organization_name_resolution.sql").read_text())
cur.execute((migrations / "0016_cross_post_actor_identity.sql").read_text())
cur.execute((migrations / "0018_analysis_run_registry.sql").read_text())
+ cur.execute((migrations / "0019_analysis_run_reconstruction.sql").read_text())
+ cur.execute((migrations / "0020_analysis_source_snapshot_member.sql").read_text())
cur.execute(
"""
insert into common_lookup_value (lookup_category, lookup_code, lookup_label, display_order) values
@@ -1281,6 +1283,35 @@ def _ensure_demo_source_counts(cur, snapshot_id) -> None:
)
+def _ensure_demo_source_snapshot_members(cur, snapshot_id, corporate_entity_id) -> None:
+ """Freeze Demo Corp post ids on the shared snapshot when the table exists."""
+ cur.execute(
+ "select 1 from information_schema.tables "
+ "where table_schema = 'public' "
+ "and table_name = 'analysis_source_snapshot_member'"
+ )
+ if cur.fetchone() is None:
+ return
+ cur.execute(
+ "select 1 from analysis_source_snapshot_member "
+ "where analysis_source_snapshot_id = %s limit 1",
+ (snapshot_id,),
+ )
+ if cur.fetchone() is not None:
+ return
+ cur.execute(
+ """
+ insert into analysis_source_snapshot_member
+ (analysis_source_snapshot_id, source_post_id)
+ select %s, post_id from source_post
+ where corporate_entity_id = %s
+ and created_at <= '2026-01-12T00:00:00Z'
+ on conflict do nothing
+ """,
+ (snapshot_id, corporate_entity_id),
+ )
+
+
def _seed_demo_analysis_run(cur, requested_by_account_id, corporate_entity_id) -> None:
"""Insert one Demo-Corp lineage run so Analysis runs is not empty.
@@ -1290,6 +1321,7 @@ def _seed_demo_analysis_run(cur, requested_by_account_id, corporate_entity_id) -
"""
snapshot_id = _ensure_demo_source_snapshot(cur)
_ensure_demo_source_counts(cur, snapshot_id)
+ _ensure_demo_source_snapshot_members(cur, snapshot_id, corporate_entity_id)
cur.execute(
"""
select analysis_run_id from analysis_run
@@ -1385,6 +1417,7 @@ def _seed_demo_tepp_run(cur, requested_by_account_id, corporate_entity_id) -> No
"""
snapshot_id = _ensure_demo_source_snapshot(cur)
_ensure_demo_source_counts(cur, snapshot_id)
+ _ensure_demo_source_snapshot_members(cur, snapshot_id, corporate_entity_id)
cur.execute(
"""
select analysis_run_id from analysis_run
diff --git a/tests/test_analysis_run_reconstruction_schema.py b/tests/test_analysis_run_reconstruction_schema.py
new file mode 100644
index 000000000..0ad355028
--- /dev/null
+++ b/tests/test_analysis_run_reconstruction_schema.py
@@ -0,0 +1,144 @@
+"""Static and optional PostgreSQL contracts for run-scoped reconstruction."""
+
+from __future__ import annotations
+
+import os
+import re
+import uuid
+from pathlib import Path
+from urllib.parse import urlsplit, urlunsplit
+
+import pytest
+
+_ROOT = Path(__file__).resolve().parents[1]
+_INITIAL_MIGRATION = _ROOT / "migrations" / "0001_initial_schema.sql"
+_REGISTRY_MIGRATION = _ROOT / "migrations" / "0018_analysis_run_registry.sql"
+_RECONSTRUCTION_MIGRATION = _ROOT / "migrations" / "0019_analysis_run_reconstruction.sql"
+_RECONSTRUCTION_ROLLBACK = _ROOT / "migrations" / "rollback" / "0019_analysis_run_reconstruction.sql"
+_SNAPSHOT_MEMBER_MIGRATION = _ROOT / "migrations" / "0020_analysis_source_snapshot_member.sql"
+_SNAPSHOT_MEMBER_ROLLBACK = _ROOT / "migrations" / "rollback" / "0020_analysis_source_snapshot_member.sql"
+_POSTGRES_IMAGE = _ROOT / "docker" / "postgres-init" / "Dockerfile"
+_ADMIN_DSN = os.environ.get(
+ "LINEAGEWEAVE_TEST_POSTGRES_ADMIN_DSN", "postgresql://localhost/postgres"
+)
+_REQUIRED_TABLES = {
+ "analysis_run_reconstruction",
+ "analysis_run_lineage_edge",
+}
+
+
+def test_reconstruction_migration_is_normalized_and_wired() -> None:
+ """Static contract: 3NF names, no payload JSON, Dockerfile copy, rollback."""
+ migration = _RECONSTRUCTION_MIGRATION.read_text(encoding="utf-8")
+ rollback = _RECONSTRUCTION_ROLLBACK.read_text(encoding="utf-8")
+ dockerfile = _POSTGRES_IMAGE.read_text(encoding="utf-8")
+ created_tables = set(
+ re.findall(r"create table if not exists\s+([a-z0-9_]+)", migration, re.I)
+ )
+ assert _REQUIRED_TABLES <= created_tables
+ assert "jsonb" not in migration.casefold()
+ assert "metadata_payload" not in migration
+ assert "theta" not in migration.casefold()
+ assert "0019_analysis_run_reconstruction.sql" in dockerfile
+ assert "0020_analysis_source_snapshot_member.sql" in dockerfile
+ assert "analysis_run_reconstruction_not_empty" in rollback
+ assert "reject_analysis_run_reconstruction_update" in migration
+ assert "reject_analysis_run_lineage_edge_update" in migration
+ member_migration = _SNAPSHOT_MEMBER_MIGRATION.read_text(encoding="utf-8")
+ member_rollback = _SNAPSHOT_MEMBER_ROLLBACK.read_text(encoding="utf-8")
+ assert "analysis_source_snapshot_member" in member_migration
+ assert "jsonb" not in member_migration.casefold()
+ assert "theta" not in member_migration.casefold()
+ assert "analysis_source_snapshot_member_not_empty" in member_rollback
+ assert "reject_analysis_source_snapshot_member_update" in member_migration
+ for object_name in re.findall(
+ r"create table if not exists\s+([a-z0-9_]+)",
+ member_migration,
+ re.I,
+ ):
+ assert len(object_name.split("_")) >= 2, object_name
+
+ object_patterns = (
+ r"create table if not exists\s+([a-z0-9_]+)",
+ r"create or replace function\s+([a-z0-9_]+)",
+ r"create trigger\s+([a-z0-9_]+)",
+ )
+ for pattern in object_patterns:
+ for object_name in re.findall(pattern, migration, re.I):
+ assert len(object_name.split("_")) >= 2, object_name
+
+
+def _postgres_available() -> bool:
+ """Return whether the configured administrator DSN is reachable."""
+ try:
+ import psycopg2
+
+ psycopg2.connect(_ADMIN_DSN, connect_timeout=2).close()
+ return True
+ except Exception:
+ return False
+
+
+def _database_dsn(database_name: str) -> str:
+ """Replace only the database path while preserving DSN query options."""
+ parsed = urlsplit(_ADMIN_DSN)
+ return urlunsplit(parsed._replace(path=f"/{database_name}"))
+
+
+@pytest.fixture
+def reconstruction_db():
+ """Yield a throwaway registry+reconstruction database."""
+ if not _postgres_available():
+ pytest.skip("a reachable PostgreSQL administrator DSN is required")
+ import psycopg2
+
+ database_name = f"lineageweave_recon_{uuid.uuid4().hex[:12]}"
+ admin = psycopg2.connect(_ADMIN_DSN)
+ admin.autocommit = True
+ try:
+ with admin.cursor() as cursor:
+ cursor.execute(f'create database "{database_name}"')
+ finally:
+ admin.close()
+ conn = psycopg2.connect(_database_dsn(database_name))
+ conn.autocommit = True
+ try:
+ with conn.cursor() as cursor:
+ cursor.execute(_INITIAL_MIGRATION.read_text(encoding="utf-8"))
+ cursor.execute(_REGISTRY_MIGRATION.read_text(encoding="utf-8"))
+ cursor.execute(_RECONSTRUCTION_MIGRATION.read_text(encoding="utf-8"))
+ cursor.execute(_SNAPSHOT_MEMBER_MIGRATION.read_text(encoding="utf-8"))
+ yield conn
+ finally:
+ conn.close()
+ admin = psycopg2.connect(_ADMIN_DSN)
+ admin.autocommit = True
+ try:
+ with admin.cursor() as cursor:
+ cursor.execute(
+ "select pg_terminate_backend(pid) from pg_stat_activity "
+ "where datname = %s and pid <> pg_backend_pid()",
+ (database_name,),
+ )
+ cursor.execute(f'drop database "{database_name}"')
+ finally:
+ admin.close()
+
+
+def test_empty_reconstruction_rollback_is_replayable(reconstruction_db) -> None:
+ """An empty reconstruction schema can be rolled back and removed."""
+ with reconstruction_db.cursor() as cursor:
+ cursor.execute(
+ "select table_name from information_schema.tables "
+ "where table_schema = 'public' and table_name = any(%s)",
+ (list(_REQUIRED_TABLES),),
+ )
+ assert {row[0] for row in cursor.fetchall()} == _REQUIRED_TABLES
+ cursor.execute(_RECONSTRUCTION_ROLLBACK.read_text(encoding="utf-8"))
+ cursor.execute(
+ "select table_name from information_schema.tables "
+ "where table_schema = 'public' and table_name = any(%s)",
+ (list(_REQUIRED_TABLES),),
+ )
+ assert cursor.fetchall() == []
+ cursor.execute(_RECONSTRUCTION_ROLLBACK.read_text(encoding="utf-8"))
diff --git a/tests/test_analysis_run_start.py b/tests/test_analysis_run_start.py
new file mode 100644
index 000000000..f2b6e53ab
--- /dev/null
+++ b/tests/test_analysis_run_start.py
@@ -0,0 +1,100 @@
+"""Start-reconstruction contracts: digest stability and designed-tree fidelity."""
+
+from backend.app.analysis_run_ingestion import reconstructed_edge_is_visible
+from backend.app.analysis_run_start import (
+ AnalysisRunStartError,
+ reconstruction_member_ids,
+ reconstruction_result_digest,
+ start_write_conflict_error,
+)
+from backend.app.lineage_ingestion import records_from_source_posts
+from lineageweave.fixtures import sample_records
+from lineageweave.lineage_persistence import lineage_edge_specs
+
+
+def test_reconstruction_digest_is_stable_and_ignores_edge_order() -> None:
+ """The same parent choices hash the same way regardless of insert order."""
+ edges = lineage_edge_specs(sample_records())
+ reversed_edges = list(reversed(edges))
+ assert reconstruction_result_digest(edges) == reconstruction_result_digest(reversed_edges)
+ assert reconstruction_result_digest([]) == reconstruction_result_digest([])
+ assert reconstruction_result_digest(edges) != reconstruction_result_digest([])
+
+
+def test_start_uses_the_same_parent_choices_as_library_reconstruct() -> None:
+ """The product start path must recover the designed A-100 fork.
+
+ fixtures.sample_records() is the synthetic gold tree: rec-002 is the
+ branch point for the revised quote and the delivery question. A start
+ that dropped an edge or invented a parent would fail this check.
+ """
+ edges = lineage_edge_specs(sample_records())
+ children = {
+ edge.child_id for edge in edges if edge.parent_id == "rec-002"
+ }
+ assert children >= {"rec-003", "rec-004"}
+ assert all(0.0 <= edge.fused_score <= 1.0 for edge in edges)
+ assert "theta" not in reconstruction_result_digest(edges)
+
+
+def test_start_wiring_recovers_a100_from_source_post_rows() -> None:
+ """CI must exercise records_from_source_posts, not only library reconstruct."""
+ rows = [
+ {
+ "post_id": record.record_id,
+ "post_title": record.label,
+ "created_at": record.occurred_at,
+ "thread_group_key": record.group_key,
+ "secondary_grouping_key": record.secondary_key,
+ "process_unit_id": None,
+ "corporate_entity_id": "corp-demo",
+ }
+ for record in sample_records()
+ ]
+ edges = lineage_edge_specs(records_from_source_posts(rows))
+ children = {edge.child_id for edge in edges if edge.parent_id == "rec-002"}
+ assert children >= {"rec-003", "rec-004"}
+ assert reconstruction_result_digest(edges) == reconstruction_result_digest(
+ lineage_edge_specs(sample_records())
+ )
+
+
+def test_snapshot_members_exclude_a_later_backfill() -> None:
+ """Start reconstructs the create-time bag, not a later cutoff re-query."""
+ captured = ["rec-001", "rec-002", "rec-003", "rec-004"]
+ cutoff_with_backfill = [*captured, "rec-backfill"]
+ assert reconstruction_member_ids(captured, cutoff_with_backfill) == captured
+ assert reconstruction_member_ids([], cutoff_with_backfill) == cutoff_with_backfill
+
+
+def test_reconstructed_edge_hides_unaffiliated_private_titles() -> None:
+ """Edge titles use the same public-or-affiliated rule as cutoff posts."""
+ affiliated = ["corp-demo"]
+ assert reconstructed_edge_is_visible(
+ parent_visibility_code="public",
+ parent_corporate_entity_id="corp-other",
+ child_visibility_code="public",
+ child_corporate_entity_id="corp-other",
+ affiliated_entity_ids=affiliated,
+ )
+ assert not reconstructed_edge_is_visible(
+ parent_visibility_code="private",
+ parent_corporate_entity_id="corp-other",
+ child_visibility_code="public",
+ child_corporate_entity_id="corp-demo",
+ affiliated_entity_ids=affiliated,
+ )
+
+
+def test_start_error_carries_a_next_action() -> None:
+ """Operators get a next action, not an internal exception name."""
+ error = AnalysisRunStartError(
+ 422,
+ "Connect a TEPP transport from a Failed TEPP row. "
+ "This start path does not invent a measurement.",
+ )
+ assert error.status_code == 422
+ assert "invent a measurement" in error.detail
+ conflict = start_write_conflict_error()
+ assert conflict.status_code == 409
+ assert "Refresh to see the stored tree" in conflict.detail