Skip to content

Commit 687572a

Browse files
natengallodev
authored andcommitted
test ADR sidecar migration and recovery
1 parent 19f5bdf commit 687572a

2 files changed

Lines changed: 111 additions & 0 deletions

File tree

‎docs/upstream-sync/adr-recovery.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# ADR sidecar recovery and compatibility
2+
3+
File-backed stores keep decision records in `<graph-db>.adr.db`. Existing
4+
databases are compatible: the first ADR write or explicit migration copies
5+
legacy `project_summaries` rows with `INSERT OR IGNORE`, then records the
6+
`migrated` marker in the same sidecar transaction. A crash before commit rolls
7+
back both copied rows and marker; retry can safely copy again. Existing sidecar
8+
rows win conflicts. Reads do not migrate: they open an existing marked sidecar
9+
read-only, fall back to legacy graph rows when the sidecar is absent or has no
10+
migration marker, and otherwise return the sidecar row. `:memory:` stores
11+
continue using the graph database.
12+
13+
Reindexing or replacing the graph database leaves the sidecar file untouched.
14+
Back up and restore the graph database and its `.adr.db` sidecar together to
15+
preserve ADRs. Team artifacts retain the existing interchange format: export
16+
copies the selected ADR into `project_summaries` in the snapshot, and import
17+
restores it into the sidecar only if that project has no local ADR. A failed
18+
artifact ADR restore is logged; graph import remains successful, so recover the
19+
ADR from the artifact and retry after fixing the sidecar problem.
20+
21+
The graph row may remain after migration or deletion. The migration marker
22+
prevents stale graph rows from being recopied after deletion; artifact export
23+
clears snapshot summaries before injecting the current sidecar ADR, preventing
24+
deleted rows from being resurrected. SQLite transaction recovery applies to
25+
committed sidecar writes; copying only the graph database is not a complete
26+
backup of post-migration ADR state.

‎tests/test_artifact.c‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -271,6 +271,90 @@ TEST(artifact_export_roundtrip_keeps_adr) {
271271
PASS();
272272
}
273273

274+
/* Existing graph databases keep their legacy ADR until the first write/migration.
275+
* Migration is transactional, and replacing the graph file leaves the sidecar
276+
* authoritative. A query-only open must read that sidecar without creating it. */
277+
TEST(adr_sidecar_migrates_and_survives_graph_replacement) {
278+
setup_artifact_test();
279+
create_test_db(g_db);
280+
281+
sqlite3 *raw = NULL;
282+
ASSERT_EQ(sqlite3_open(g_db, &raw), SQLITE_OK);
283+
ASSERT_EQ(
284+
sqlite3_exec(
285+
raw,
286+
"CREATE TABLE project_summaries (project TEXT PRIMARY KEY, summary TEXT NOT NULL, "
287+
"source_hash TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL);"
288+
"INSERT INTO project_summaries VALUES ('test-proj','legacy ADR','h','c','u');",
289+
NULL, NULL, NULL),
290+
SQLITE_OK);
291+
sqlite3_close(raw);
292+
293+
char sidecar[1100];
294+
snprintf(sidecar, sizeof(sidecar), "%s.adr.db", g_db);
295+
cbm_store_t *s = cbm_store_open_path_query(g_db);
296+
ASSERT_NOT_NULL(s);
297+
cbm_adr_t adr = {0};
298+
ASSERT_EQ(cbm_store_adr_get(s, "test-proj", &adr), CBM_STORE_OK);
299+
ASSERT_STR_EQ(adr.content, "legacy ADR");
300+
cbm_store_adr_free(&adr);
301+
cbm_store_close(s);
302+
ASSERT_FALSE(cbm_file_exists(sidecar)); /* Read-only legacy access creates no sidecar. */
303+
304+
ASSERT_EQ(sqlite3_open(sidecar, &raw), SQLITE_OK);
305+
ASSERT_EQ(
306+
sqlite3_exec(
307+
raw,
308+
"CREATE TABLE project_summaries (project TEXT PRIMARY KEY, summary TEXT NOT NULL, "
309+
"source_hash TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL);"
310+
"CREATE TABLE adr_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);"
311+
"BEGIN; INSERT INTO project_summaries VALUES ('test-proj','partial','h','c','u');",
312+
NULL, NULL, NULL),
313+
SQLITE_OK);
314+
sqlite3_close(raw); /* Simulated process loss rolls back the uncommitted copy. */
315+
316+
s = cbm_store_open_path(g_db);
317+
ASSERT_NOT_NULL(s);
318+
ASSERT_EQ(cbm_store_adr_migrate_once(s), CBM_STORE_OK);
319+
memset(&adr, 0, sizeof(adr));
320+
ASSERT_EQ(cbm_store_adr_get(s, "test-proj", &adr), CBM_STORE_OK);
321+
ASSERT_STR_EQ(adr.content, "legacy ADR");
322+
cbm_store_adr_free(&adr);
323+
ASSERT_EQ(sqlite3_open_v2(sidecar, &raw, SQLITE_OPEN_READONLY, NULL), SQLITE_OK);
324+
sqlite3_stmt *count = NULL;
325+
ASSERT_EQ(
326+
sqlite3_prepare_v2(raw, "SELECT count(*) FROM project_summaries WHERE project='test-proj';",
327+
-1, &count, NULL),
328+
SQLITE_OK);
329+
ASSERT_EQ(sqlite3_step(count), SQLITE_ROW);
330+
ASSERT_EQ(sqlite3_column_int(count, 0), 1);
331+
sqlite3_finalize(count);
332+
sqlite3_close(raw);
333+
ASSERT_EQ(cbm_store_adr_store(s, "test-proj", "updated ADR"), CBM_STORE_OK);
334+
cbm_store_close(s);
335+
336+
ASSERT_EQ(sqlite3_open(sidecar, &raw), SQLITE_OK);
337+
ASSERT_EQ(sqlite3_exec(raw,
338+
"BEGIN; UPDATE project_summaries SET summary='partial write' WHERE "
339+
"project='test-proj';",
340+
NULL, NULL, NULL),
341+
SQLITE_OK);
342+
sqlite3_close(raw); /* An interrupted update must leave the prior committed ADR. */
343+
344+
remove_graph_db_keep_sidecar(g_db);
345+
create_test_db(g_db);
346+
s = cbm_store_open_path_query(g_db);
347+
ASSERT_NOT_NULL(s);
348+
memset(&adr, 0, sizeof(adr));
349+
ASSERT_EQ(cbm_store_adr_get(s, "test-proj", &adr), CBM_STORE_OK);
350+
ASSERT_STR_EQ(adr.content, "updated ADR");
351+
cbm_store_adr_free(&adr);
352+
cbm_store_close(s);
353+
354+
cleanup_dir(g_tmpdir);
355+
PASS();
356+
}
357+
274358
/* Regression: a stale legacy `project_summaries` row that lingers in the graph DB
275359
* after its ADR was migrated then DELETED must NOT resurrect through an export.
276360
* With the sidecar empty, the snapshot must ship an empty table, so an import
@@ -1407,6 +1491,7 @@ SUITE(artifact) {
14071491
RUN_TEST(artifact_repo_path_shell_safe_rejects_cmd_metachars_on_windows);
14081492
RUN_TEST(artifact_export_fast_roundtrip);
14091493
RUN_TEST(artifact_export_roundtrip_keeps_adr);
1494+
RUN_TEST(adr_sidecar_migrates_and_survives_graph_replacement);
14101495
RUN_TEST(artifact_export_without_adr_does_not_resurrect_legacy_row);
14111496
RUN_TEST(artifact_import_does_not_clobber_local_adr);
14121497
RUN_TEST(artifact_import_restores_adr_when_local_absent);

0 commit comments

Comments
 (0)