@@ -56,11 +56,22 @@ To install everything this guide uses while developing: `pip install -e '.[dev,p
5656
5757## Layout notes
5858
59- ` adcp_reporting_row_sets ` is the side table that records where a revision's rows live until the shared Core layout
60- (persistence Stage 3). It matches the JavaScript table column for column except that ` obligation_id ` has no
59+ ` adcp_reporting_row_sets ` is the side table that records where a revision's rows live.
60+ It matches the JavaScript table column for column except that ` obligation_id ` has no
6161foreign key: Python obligations live in ` reporting_obligations ` , not in the JavaScript
6262` adcp_reporting_obligations ` table. If the JavaScript migration created the table first, ` ready_row_storage `
63- refuses with the constraint name; apply this migration first, or drop that constraint.
63+ refuses with the constraint name and a schema-qualified, quoted statement to remove it.
64+ Apply the Python migration first, or, for an existing database with Python as its writer,
65+ remove the JavaScript foreign key before running readiness again. The default constraint name is:
66+
67+ ``` sql
68+ ALTER TABLE adcp_reporting_row_sets
69+ DROP CONSTRAINT adcp_reporting_row_sets_obligation_id_fkey;
70+ ```
71+
72+ Run this in the ledger schema. Use the exact statement from the refusal if the schema or
73+ constraint has a different name. This removes the cross-SDK foreign key; row integrity
74+ continues to be verified against the stored digests.
6475
6576A revision written before protocol-shape control totals (see the release notes) has a binding over ` {name, value} `
6677pairs. Its row set records the rows-only digest profile ` rows_v1 ` , and its pair binding is verified against the
@@ -302,7 +313,9 @@ A period qualifies once the later of its period end and its newest revision or a
302313` ledger_record_retention_days ` is the generation's ` status_retention_days ` ; a shorter value is ignored, because a row
303314retention shorter than the advertised window is non-conformant.
304315
305- Python keeps revision headers and their records until the shared Core layout (persistence Stage 3). A pruned row set
316+ Python keeps revision headers and their records. Record retirement refuses periods with protected reconciliation
317+ or audit evidence, so production periods carrying those records remain retained; row-byte pruning still runs.
318+ A pruned row set
306319stays as a small marker that makes reads answer as expired; the records are already outside the status projection,
307320whose horizon excludes periods past retention. Versioned buckets, soft delete and retention locks are allowed as
308321backstops, but a ` pruned ` period is not "erased" while they keep the old bytes.
@@ -346,12 +359,13 @@ either verify in the other. Three things must match between the two deployments:
346359- ** The same binding definitions.** A binding's identity digest is ` sha256(JCS([kind, provider, identity_config])) `
347360 over the names the JavaScript SDK uses (` location ` , ` prefix ` , ` keyTemplate ` ), so an object binding that differs in
348361 location, prefix or key template is a different binding and is refused rather than silently redirected.
349- - ** The row-storage migration applied by this SDK first** , because the JavaScript ` adcp_reporting_row_sets ` has a
350- foreign key to its own obligations table that Python obligations can never satisfy. See "Layout notes".
362+ - ** The row-storage migration applied by this SDK first** , or the JavaScript foreign key removed with
363+ ` ALTER TABLE adcp_reporting_row_sets DROP CONSTRAINT adcp_reporting_row_sets_obligation_id_fkey; `
364+ in the ledger schema. Python obligations cannot satisfy that foreign key. See "Layout notes" for renamed constraints.
351365
352- Until the shared Core layout (persistence Stage 3) each SDK keeps its own revision headers, so what is shared today
366+ Each SDK keeps its own revision headers, so what is shared today
353367is the row sets: JavaScript-written row sets verify through ` ReportingRowStorageV1.find ` and ` read_all ` here, and the
354- other way around.
368+ other way around. A shared Core layout is no longer planned; keep one writer SDK per ledger database.
355369
356370The acceptance test runs both SDKs against one PostgreSQL schema and one filesystem bucket root, in both directions:
357371
0 commit comments