Why this document exists
The VSR replatform deliberately develops the front-end representation and the data layer in
parallel isolation, so that mismatches between the legacy Domino model and the new RDS
model surface visibly rather than silently. This report catalogues every known divergence between
the legacy cart-line record (CART_DETAIL) and the RDS analog (cart_items),
and — crucially — attributes each one to its provenance: why it diverges.
The headline: Most divergences are not defects. The RDS table is an
intentionally distilled subset. The one genuine correctness defect
(the loose-surcharge carton factor) was fixed in this ticket. Everything else is either deliberate
design, work not yet started, or a consequence of the upstream data model moving under us.
Companion document (preferred viewing): read
infra/sql/README.md — “VSR RDS Schema — Normalized Layout vs. the Domino
Backend” — for the narrative rationale and the entity/relationship model. That README is the
best entry point for the why; this report is the field-by-field register for the
what. The two are kept in agreement: shared facts (provenance tags, the
bulk_factor_qt / loose-charge resolution under DECISION_LOG D011, and
the INT-2793 reconciliation backlog) match across both.
How to read provenance
A · Initial-analysis misunderstanding
Came from an incorrect interpretation of the legacy model during early research. These are the only category that were ever "wrong." Both are now resolved.
B · Unfinished / not yet built
Deliberately deferred. The legacy behaviour is understood; the RDS/GraphQL/UI work simply hasn't been done yet. Backlog, not bugs.
C · Backend data-store change since kickoff
The upstream source model changed after the cart layer was first designed, making a legacy column obsolete or unavailable. The divergence tracks reality, not a mistake.
D · Intentional design divergence
A conscious, documented decision to differ from legacy (e.g. drop Domino-only artifacts, or compute live instead of persisting). Correct by design.
2
A · misunderstanding
(both resolved)
(both resolved)
8
B · unfinished work
2
C · backend change
3
D · intentional design
Divergence register
| Legacy field / group | RDS cart_items |
Provenance | Status | Explanation & evidence |
|---|---|---|---|---|
BULK_FACTOR_QT |
bulk_factor_qt — added |
A | ✔ RESOLVED | The early "distilled subset" dropped the carton factor on the belief that the loose surcharge
was $0.30 × full quantity. Without the factor the line over-charged every full
carton (qty 80 billed $24 instead of $0). Added in migration 005, snapshotted at
add-to-cart. Evidence: handoff §1, DECISION_LOG D011. |
| Loose-charge rule (logic, not a column) | computeLooseUnits = qty % bulkFactor |
A | ✔ RESOLVED | Misread legacy Domino: the surcharge bills only the loose remainder beyond whole cartons, never an exact multiple. Corrected server-side (authoritative) and mirrored on the front-end. Evidence: DECISION_LOG D011; tests 7→$2.10, 80→$0, 81→$0.30, 163→$0.90. |
CART_MIN_ORDER_FLAG / MIN_ORDER_QT / MIN_ORDER_AM |
min_order_flag present but hard-wired false |
C | ○ dormant | The min-order surcharge path is inert because the upstream source changed:
V_PRODUCTS was retired and re-pointed at raw PRODUCT, where
MIN_ORDER_IN is NULL. The column is wired end-to-end and will light up
if/when the source supplies the flag again. Evidence: DECISION_LOG D001;
resolver comment in addToCart. |
INV_FILL_FLAG / INV_CDS_AVAIL_QT / INV_VSR_AVAIL_QT |
absent | C B | ○ open | Per-line inventory snapshot superseded by a backend change: stock is now read live from
PRODUCT.AVAILABLE_QT (the per-product V_INVENTORY call was dropped), so
the legacy per-line inventory columns are largely obsolete. Any remaining inventory-fill display
gated by VSR_CONTROL is also not yet built. Evidence: DECISION_LOG D004. |
LOGICAL_DELETE_IN (soft delete) |
absent — removeCartItem hard-DELETEs |
B | ○ open | Legacy soft-deletes lines (keeps an audit trail); the RDS analog physically deletes. Soft-delete semantics simply haven't been ported. No behavioural bug for the user; loses line-level audit history. Reconciliation deferred to INT-2793. |
Header rollups: TOTAL_*, category qtys (merch / new-release / catalog) |
absent — totals computed live at read | B | ○ open | CART_HEADER persists many pre-aggregated totals and per-category quantity
breakdowns. The RDS carts row carries none — totals are recomputed on every read.
Fine for correctness; the category breakdowns (used by legacy reporting) are not yet ported. |
SHADOWBOX_ORDER_IN / SHADOWBOX_DESC |
absent | B | ○ open | The "shadowbox" ordering feature has not been built in the replatform. Columns intentionally omitted until the feature is scoped. |
CART_NEW_RELEASE_FLAG |
absent | B | ○ open | Per-line new-release marking not yet carried on the cart. New-release handling currently lives in the catalog/browse layer, not the cart line. Not yet done. |
VSR_WAIVE_LOOSE_CHARGE_IN (header-level waive) |
only line-level waive_loose_bulk |
B | ○ open | Legacy supports a cart-wide loose-charge waiver in addition to the per-line deal waiver. Only the line-level waiver is ported; the header-level override is not yet implemented. |
DETAIL_STATUS / STATUS_CD |
absent | B | ○ open | Per-line status lifecycle fields not yet modelled on the cart line. Deferred. |
RED_PRICE_CD / CONFIGURATION_CD / ALTERNATE_CATLG_ID / IN_STORE_DT |
absent on cart line (some captured on order_items) |
B | ○ open | Descriptive/price-code fields trimmed from the cart line as part of the distillation. Several are
snapshotted onto order_items at checkout, so order history is unaffected; the cart
line itself is leaner. Full parity deferred to INT-2793. |
LINE_NO (cart keyed on (CART_ID, LINE_NO)) |
keyed on (cart_id, upc_cd); line no. synthesized at order time |
D | ○ by design | Deliberate: a UPC-unique upsert (ON CONFLICT (cart_id, upc_cd)) gives idempotent
add-to-cart and natural quantity merging. Legacy line numbering is reconstructed at checkout
(i+1). Reconciliation to explicit LINE_NO is unpursued but not required. |
Persisted LOOSE_CHARGE_QT/AM on the cart line
(MIN_ORDER_* dormant, D001) |
loose_charge_qt / loose_charge_am — present & maintained |
D | ✔ decided | Adopted from PR #26 for legacy CART_DETAIL parity: migration 005
adds loose_charge_qt/loose_charge_am to cart_items and
refreshLooseChargeSnapshot keeps them fresh on every write path. Cart reads still recompute
the billed truth live in pricing.ts (authoritative); the persisted columns exist for parity
and downstream sync, and the durable order snapshot lives on order_items.
MIN_ORDER_QT/AM remain unpersisted — min-order is dormant (D001).
Evidence: PR #26; DECISION_LOG D011; migration 005. |
AUTHORS / READERS |
absent | D | ✔ correct | Domino-specific ACL / reader-field artifacts. Correctly dropped — RDS/Postgres access control is handled by the auth layer, not per-document reader lists. |
Provenance narrative
A What came from a misunderstanding during initial research
Only two items, and both are now fixed under INT-2851:
- The dropped carton factor (
BULK_FACTOR_QT) — the early data-model distillation treated the loose surcharge as a flat per-unit charge and therefore saw no need for the carton size. That interpretation was wrong, and it produced the only user-visible billing defect. - The loose-charge formula — a direct consequence of the same misunderstanding: charging the full quantity rather than the loose remainder.
These are the genuine "we got it wrong initially" cases. The rest of the register is not in this category.
B What is simply unfinished / not yet pursued
The largest group — legacy behaviour that is understood but where the replatform work hasn't been done yet. These are backlog items, not bugs:
- Soft-delete semantics (
LOGICAL_DELETE_IN) — the RDS hard-deletes today. - Header rollups & per-category quantity breakdowns from
CART_HEADER. - Shadowbox ordering (
SHADOWBOX_*). - Per-line new-release flag (
CART_NEW_RELEASE_FLAG). - Header-level loose-charge waiver (
VSR_WAIVE_LOOSE_CHARGE_IN). - Line status lifecycle (
DETAIL_STATUS,STATUS_CD). - Descriptive/price-code fields (
RED_PRICE_CD,CONFIGURATION_CD,ALTERNATE_CATLG_ID,IN_STORE_DT). - Full
CART_DETAIL↔cart_itemscolumn reconciliation is tracked under INT-2793.
C What is due to backend data-store changes since we began
Cases where the upstream source model moved after the cart layer was first designed:
- Min-order surcharge went dormant —
V_PRODUCTSwas retired and the single product mapping re-pointed at rawPRODUCT/ nav-view columns (D001).MIN_ORDER_INis nowNULLat the source, somin_order_flagis hard-wiredfalse. The plumbing remains; only the source signal is gone. - Per-line inventory columns obsoleted — stock is now read live from
PRODUCT.AVAILABLE_QT, and the per-productV_INVENTORYcall was dropped (D004). The legacy per-lineINV_*snapshot fields no longer map cleanly to the current source.
Confidence note: attribution here is grounded in the project's own decision log (D001, D004). A broader audit of upstream schema drift since kickoff is out of scope for this report.
D What is intentional design divergence (correct by choice)
- UPC-keyed cart lines instead of
LINE_NO— enables idempotent add-to-cart and clean quantity merging; line numbers are reconstructed at checkout. - Persisted cart-line loose charges for parity, live recompute for billing (D011) —
loose_charge_qt/amare persisted oncart_items(adopted from PR #26) for legacyCART_DETAILparity and refreshed on every write; the authoritative billed amount is still recomputed live on read, and the durable snapshot also lives onorder_items. - Dropping Domino ACL artifacts (
AUTHORS,READERS) — access control now lives in the auth layer.
Bottom line
Of 15 catalogued divergences: 2 were true early-analysis mistakes (both fixed this
ticket), 3 are intentional and correct, 2 reflect the backend data
store changing under us, and 8 are simply unfinished replatform work tracked for
INT-2793. The cart layer is a deliberate distilled subset — the divergences are, overwhelmingly, either
by design or by backlog, not defects.