Quote & Policy
Schema deep-dive · living document · #4 in the reading sequence
| Tables | enrollment.quotes, enrollment.policies[1][2] |
| Owner service | enrollment (sole writer) |
| Locators | QTE-YYYY-NNNNNN (quotes) · POL-YYYY-NNNNNN (policies) |
| Last updated | 2026-08-18 |
| Companion | ERD story, slide 4 · real policy JSON · previous: Product & catalogue |
1. Scope and usage
A Policy is the contract of insurance - the row that says this party holds this cover, under this product version, from this date. A Quote is the priced offer that can bind into one. Together they are the hub of the model: the policy row is where the identity spine (Party), the grouping (Scheme), the catalogue (ProductVersion) and, downstream, eligibility, claims and billing all meet. Every locator radiates from here.
Two issuance lineages share these tables:
- Quote → bind - the classic chain: create a DRAFT quote, price it, optionally underwrite it, issue it. Issue atomically flips the quote to ACCEPTED and creates the policy with
quote_idpinned[8]. Fully coded and exposed on real routes[9]; it activates the day broker or underwritten business arrives. Live issuance has run through Flow-0, so no live policy references a quote yet. - Flow-0 direct issue -
IssueInternal(#1164): HR adds an employee, the group-scheme composer callsPOST /internal/policies/issue, and a member-level policy is created quote-lessly, idempotent on (party, scheme)[7][10]. This is the path every live Flow-0 policy took.
Use the policy when you need what cover exists and for whom. Do not use it for what the cover contains (elements, next page), what has been consumed (eligibility accumulators), or what it costs per month (billing charges).
2. Boundaries and relationships
| A Policy is not… | That concern lives in | Join |
|---|---|---|
| the product | policy_admin.product_versions; the policy pins one at issue via product_version_id (uuid, cross-service soft ref)[2] | uuid soft ref |
| the content of the cover | policy_elements snapshot the catalogue into coverage_terms (next page) | policy_id FK |
| the adjudication anchor | policy_terms - accumulators and claims are term-scoped, not policy-scoped (next page) | policy_id FK |
| a scheme membership | group_scheme.scheme_members points at the policy via policy_locator; the roster row exists before the policy does (Scheme & roster) | locator, reversed |
| the payer or the money | billing.accounts (one per employer, keyed org_locator); policies.account_id is a synthetic per-member UUID, not that account - see §3 | none that resolves (§9) |
| what the member is eligible for | eligibility.member_coverage + accumulators, a projection built from policy.issued events[15] - never read from these tables at check time | events |
The locator hub. policies carries five locator columns - party_locator, member_locator, scheme_locator, org_locator, broker_locator - all soft references, none FKs (cross-service rule). Live data uses exactly two: party_locator (the policyholder, 495 rows) and scheme_locator (495 rows). member_locator and org_locator are NULL on every row. broker_locator is the column a broker-placed policy fills, and ListByBrokerLocator already serves broker portfolio views over it[6]; the broker identity it names is the piece still to model (§9). Same value space as Party's alias zoo: member_locator ≡ party_locator ≡ a PTY- value.
3. Structure
quotes
| Field | Type | Req | Notes |
|---|---|---|---|
id / locator | uuid / text | ✓ | PK / UNIQUE QTE- |
account_id | uuid | ✓ | Soft ref, indexed. Synthetic in live data (see below) |
product_version_id | uuid | ✓ | The version being quoted; cross-service soft ref |
status | text | ✓ | Default 'DRAFT'. Convention, no CHECK - vocabulary in §5 |
document | jsonb | Quote document; live rows carry {"jurisdiction": "GB"} | |
expires_at | timestamptz | Reserved for a quote validity window; NULL on all live rows (§9) | |
total_premium, premium_currency | numeric(14,4) / text | Written by the rating pass at price time[11]; NULL live, because the catalogue premium is the price source today (Product & catalogue §8) | |
member_locator, scheme_locator | text | Live-only columns: present in the DB, populated on all 17 live quotes, but no migration codifies them at the pinned commit and the pinned Quote model has no such fields[4] - added out-of-band by branch-side Flow-0 work (commit c877e6a7, not on main). §9 |
policies
| Field | Type | Req | Notes |
|---|---|---|---|
id / locator | uuid / text | ✓ | PK / UNIQUE POL- |
account_id | uuid | ✓ | NOT NULL but synthetic - UUIDv5 of the party locator (below) |
quote_id | uuid | Real FK to quotes (in-service)[2]. NULL on all 1 399 live rows | |
product_version_id | uuid | ✓ | The pin: what this cover was sold under |
status | text | ✓ | Default 'ACTIVE'. Convention, no CHECK. Live: ACTIVE (700), LAPSED (699) |
inception_date | date | ✓ | Contract start |
jurisdiction, region | text | ✓/- | "GB" on live rows; extracted from the quote document on the bind path[8] |
document | jsonb | Thin by design: Flow-0 rows carry only {"flow0": true}[7] | |
party_locator, scheme_locator | text | The Flow-0 anchors, added by migration 0019[3]; both indexed | |
member_locator, org_locator | text | Present + indexed in the live DB, NULL on every row, no codifying migration at the pinned commit (§9) | |
broker_locator | text | Migration 0012[12], indexed, NULL everywhere; the column a broker-placed policy fills (§9) | |
policy_structure | text | Default 'INDIVIDUAL', no CHECK - the vocabulary mismatch, §9 | |
plan_tier | text | Stringly: live values STANDARD (464), UNLIMITED (3), lowercase standard (28), NULL (904) |
Field-by-field: what and why
locator - POL-2026-001500 reads over the phone; the uuid joins fast. Same uuid-inside/locator-outside rule as Party. Minted from per-prefix Postgres sequences created by migration 0021 (locator_seq_pol, _qte, _trm, _txn, _elm, all START 1000)[13] via the shared PGGenerator (ADR-1164-05, #1169); a process-local atomic counter seeded from wall-clock nanos remains as an explicit fallback-with-warning when the DB generator errors[14]. The migration comment is candid that START 1000 exists to keep sequence-minted locators visually distinct from the pre-migration counter-minted rows[13] - which is why live locators cluster around POL-2026-001NNN.
account_id - NOT NULL, and a lie worth understanding. Flow 0 has no Account object, so IssueInternal derives a stable UUIDv5: uuid.NewSHA1(NameSpaceOID, "flow0-account:"+partyLocator)[7] - repeat calls hash to the same value, so the column is deterministic but backed by no row anywhere. Billing's accounts migration opens by naming this exact problem: "invoices.account_id was a UUID with no row behind it - enrollment mints a synthetic per-MEMBER UUIDv5" - and answers it with one real account per employer keyed by org_locator, deliberately not by this column[16]. Verified live: account_id on the worked example equals uuidv5(OID, "flow0-account:PTY-2026-000006") exactly.
product_version_id - the pin, and since the #1164 product-wiring fix, a hard gate: IssueInternal resolves the tier against the catalogue and refuses to issue when no version resolves - "issuing cover that covers nothing is worse than refusing to issue it"[7]. This closed the Flow-0 coverage gap where planTier-only policies were invisible to eligibility. Coverage attaches at enrol (D-07, #1010).
party_locator + scheme_locator - migration 0019's comment records the archaeology: scheme_locator already existed in the live DB (added out-of-band) and 0019 codified it as IF NOT EXISTS[3]. Migration 0020 then finished the flat shape and added the load-bearing index:
idx_policies_flow0_natural - UNIQUE (party_locator, scheme_locator) WHERE both NOT NULL[17]. This partial unique index is Flow-0's idempotency key: one member-level policy per (person, scheme). IssueInternal layers a fast-path pre-check on top, and treats a concurrent 23505 as "the other caller won" and re-fetches[7]. Legacy quote→bind policies leave both columns NULL and are untouched by the index[17]. The HTTP layer adds a third ring: the internal route requires an Idempotency-Key header and replays the first 2xx verbatim[10].
policy_structure - promoted out of the Document JSONB by 0020, default 'INDIVIDUAL', "Flow 0 issues member-level policies only. Group-master rows get 'GROUP_MASTER' when that path lands"[17]. Unconstrained TEXT here, while the product side CHECKs GROUP_MASTER | MEMBER_LEVEL - the two sides of decision #225 speak different vocabularies for the same concept. The top wart; anatomised in §9.
plan_tier - the stringly-typed glue between enrollment, billing's price lookup and the catalogue's tier (Product & catalogue §9). Nullable so pre-#1164 rows need no backfill[17]; nothing normalises case, and a 2026-08-12 test batch proved it by minting 28 lowercase 'standard' rows that a case-sensitive tier lookup would miss.
document - on the bind path this carries the quote's document forward; on Flow-0 it is deliberately a marker ({"flow0": true}) so analytics can find Flow-0 rows - "planTier / structure are first-class columns as of 0020"[7]. The schema-flattening direction: promote what code reads, keep jsonb for provenance.
D2C Quote & Buy: the Document is not thin
D2C Quote & Buy (QnB) additions, grounded in branch
feat/1675, pending merge. Citations below arepath:linerelative to the repo root; they carry nomaincommit SHA because the code is not yet onmain.
The Flow-0 and bind rows keep the Document thin ({"flow0": true} / {"jurisdiction": "GB"}). The D2C (individual, direct-to-consumer) channel is the exception: the same quotes.document jsonb becomes the record of the whole Quote & Buy transaction. A member creates the quote through the member-scoped front door (POST /me/quotes), and buildD2CDocument forces three keys before anything else touches it: channel: "D2C", requires_prepayment: true, and the verified party_locator from the JWT (never the client)[D1]. Price then routes any quote whose Document says channel:"D2C" or requires_prepayment:true to the D2C underwriting + rating path (quoteRequiresPrepayment → priceD2C)[D2] instead of the scheme rate-table engine.
Pricing stamps the outcome back onto the Document in two passes: mergeUnderwriting writes underwriting + premium[D3], then mergeChecks writes checks + nests premium.optimisation[D4].
| Block | Written by | Keys | Notes |
|---|---|---|---|
channel / requires_prepayment / party_locator | buildD2CDocument (handler) at create[D1] | "D2C" / true / PTY-… | the three forced keys; party_locator is the JWT claim, and every /me/quotes/* route ownership-checks the caller against it[D1] |
declaration | the FE, at create/update | age or dateOfBirth, sexAtBirth, postcode/postcodeArea, coverTier, voluntaryExcess, smoker, heightCm, weightKg, conditions[], addOns[], coverStart | the health & lifestyle questionnaire; ParseDeclaration maps it to the rating input, and needs at least an age or dateOfBirth (else ErrMissingDeclaration)[D5]. declaration.coverStart (YYYY-MM-DD, today-or-later) sets the policy inception at issue[D6] |
underwriting | mergeUnderwriting[D3] | decision, basis, loadings[], exclusions[], factors{}, addOns[] | decision ∈ ACCEPT/REFER/DECLINE; basis defaults MORATORIUM; factors is the multiplier breakdown kept for audit; addOns[] carries per-add-on {key, annual, priced} (an unrecognised add-on is priced:false, £0, visible not silently free)[D7] |
premium | mergeUnderwriting (build-up) + mergeChecks (optimisation)[D3][D4] | currency, baseAnnual, netAnnual, ipt, grossAnnual, grossMonthly, optimisation{} | the rated build-up (IPT 12% on net)[D8]; grossAnnual is what the top-level quotes.total_premium is set to. optimisation is observe-only (applied:false): it records a suggested final price, it does not change the charge[D9] |
checks | mergeChecks[D4] | identity, screening, fraud, affordability | one uniform envelope per check: {type, outcome, provider, reference, at, detail{}}; fraud adds score, affordability adds band[D9]. Provider is a mock today (mock-kyc / mock-sanctions / …); consumers read checks.<concept>.outcome, never a provider-specific shape, so the contract survives the swap to a real KYC/sanctions vendor. Best-effort: a missing/slow provider leaves its key off |
A priced D2C quote's Document, grounded in what the code writes:
{
"channel": "D2C",
"requires_prepayment": true,
"party_locator": "PTY-2026-000006",
"declaration": {
"dateOfBirth": "1990-04-12",
"sexAtBirth": "female",
"postcode": "SW1A 1AA",
"coverTier": "STANDARD",
"voluntaryExcess": 250,
"smoker": false,
"heightCm": 168,
"weightKg": 64,
"conditions": [],
"addOns": ["dental"],
"coverStart": "2026-09-01"
},
"underwriting": {
"decision": "ACCEPT",
"basis": "MORATORIUM",
"loadings": [],
"exclusions": [],
"factors": { "age": 1.0, "region": 1.05, "excess": 0.9 },
"addOns": [ { "key": "dental", "annual": 120, "priced": true } ]
},
"premium": {
"currency": "GBP",
"baseAnnual": 234,
"netAnnual": 341.1,
"ipt": 40.93,
"grossAnnual": 382.03,
"grossMonthly": 31.84,
"optimisation": {
"technicalPrice": 382.03, "finalPrice": 379,
"provider": "mock-pricing", "reference": "opt_7f3c",
"at": "2026-08-21T09:14:02Z", "applied": false
}
},
"checks": {
"identity": { "type": "identity", "outcome": "VERIFIED", "provider": "mock-kyc", "reference": "kyc_a1", "at": "2026-08-21T09:14:01Z" },
"screening": { "type": "screening", "outcome": "CLEAR", "provider": "mock-sanctions", "reference": "scr_b2", "at": "2026-08-21T09:14:01Z", "detail": { "lists": ["OFAC","HMT"], "hits": 0 } },
"fraud": { "type": "fraud", "outcome": "PASS", "provider": "mock-fraud", "reference": "frd_c3", "at": "2026-08-21T09:14:01Z", "score": 12 },
"affordability": { "type": "affordability", "outcome": "BAND_A", "provider": "mock-credit", "reference": "enr_d4", "at": "2026-08-21T09:14:01Z", "band": "A" }
}
}On issue this whole Document is copied verbatim onto policies.document (policy.Document = q.Document)[D6], so a D2C policy row carries the underwriting basis, premium build-up and check trail, where a Flow-0 policy carries only {"flow0": true}.
4. Invariants
| Invariant | Enforced by |
|---|---|
| Both locators unique | DB unique constraints[1][2] |
| One member-level policy per (party, scheme) | DB partial unique index idx_policies_flow0_natural[17] + 23505 re-fetch[7] |
| A bound policy's quote exists | DB FK policies.quote_id → quotes.id (in-service, so a real FK)[2] |
| Quote / policy status vocabularies | Application only - typed constants[18][19] + per-transition guards; no CHECK on either table |
| Status transitions race-safe | Application: conditional UPDATE … WHERE status = 'ACTIVE' so exactly one concurrent lapse wins[6] |
| A policy always names a resolvable product version | Application: ErrProductVersionUnavailable refuses quote-less issue without one[7]; the uuid itself is never verified again after issue |
policy_structure vocabulary | Nothing - free TEXT with a default, while the product side CHECKs a different vocabulary (§9) |
party_locator / scheme_locator / broker_locator point at real rows | Nothing - cross-service soft refs, application-trusted |
Issue emits exactly one policy.issued | Application: outbox row enqueued in the same DB transaction as the policy[7], drained to Kafka topic enrollment.events by the outbox worker[20] |
A prepaid (D2C) quote is not issued until its premium settles (QnB, branch feat/1675) | Application, fail-closed: Issue refuses a requires_prepayment/channel:"D2C" quote with ErrPaymentRequired (→402) when no paymentVerifier is wired or billing reports unpaid; issues only when the Stripe webhook has marked it paid, stamping policies.payment_intent_id[D20][D21]. Invoice-billed employer/scheme quotes skip the gate |
| A priced D2C quote is issuable only within its validity window (QnB) | Application: Issue refuses a quote past expires_at with ErrQuoteExpired (→410); the window is 30 days, stamped at price time[D10][D23] |
| Row changes captured to CDC | Debezium publication dbz_enrollment (live \d) |
5. Lifecycle
Two state machines, one per table. The quote's is the classic funnel - and acceptance is the moment that matters: "the contract will be in force from the effective date that has been agreed" .
Vocabulary from domain.QuoteStatus[19]; transitions guarded in QuoteService[8] (EXPIRED is declared, reserved for the validity window in §9). Pricing runs the rating pass and the pricing ruleset; a DENY or blocking underwriting flag aborts the transition. Live data holds DRAFT (2), PRICED (2) and ACCEPTED (13) rows only.
Policy vocabulary is ACTIVE | LAPSED | CANCELLED | EXPIRED[18]; live rows are ACTIVE/LAPSED only (EXPIRED not yet written, CANCELLED transient under test churn). Cancel and reinstate write a policy transaction alongside the status flip[6]; lapse flips status only. Every transition enqueues its event (policy.cancelled, policy.reinstated, policy.lapsed) for the eligibility projection to mirror.
How a Flow-0 policy comes to exist: hop 2 of the composition walked on the Party page - the composer calls Enrollment.IssuePolicy with an idempotency key derived from (party, scheme)[21], IssueInternal writes policy + term + element + outbox atomically[7], and the roster row gets the POL- back-filled.
D2C Quote & Buy: state machine, event vocabulary and the payment gate
D2C Quote & Buy (QnB) additions, grounded in branch
feat/1675, pending merge. Citations arepath:line(nomainSHA, code not yet merged); see D2C refs.
The D2C quote walks the same table, one more transition: Price can land in DECLINED when underwriting declines, and a priced quote now carries an expires_at (30-day validity window)[D10] so an abandoned quote lapses rather than being buyable forever.
enrollment.events vocabulary (D2C). Every event is enqueued to the outbox in the same DB transaction as the state change, keyed by the quote (or policy) locator, drained to Kafka topic enrollment.events. Each risk / eligibility outcome is its own domain fact (not a field on quote.calculated), emitted by enrollment (the orchestrator), not by the mock provider, so the contract holds when a real vendor lands[D11]. Every D2C-path event carries partyLocator (resolved from the Document), which lets the notifications / timeline / audit consumers bind to the member.
| Event | Fires when | Key payload fields | Ref |
|---|---|---|---|
quote.created | Create opens a DRAFT quote (D2C or employer) | quoteLocator, accountId, partyLocator, status:"DRAFT" | [D12] |
quote.calculated | priceD2C moves the quote to PRICED | quoteLocator, accountId, partyLocator, status:"PRICED", premiumCurrency, totalPremium, premiumMonthly, underwritingDecision, expiresAt | [D13] |
premium.rated | the scheme rate-table price path computes a premium (not the D2C path; that build-up rides quote.calculated) | quoteLocator, productVersionId, premiumCurrency, totalPremium | [D14] |
underwriting.decided | priceD2C, alongside quote.calculated | quoteLocator, accountId, partyLocator, decision, basis | [D15] |
identity.verified | priceD2C, when the KYC check returned | quoteLocator, accountId, partyLocator, outcome, provider, reference, at | [D16] |
sanctions.screened | priceD2C, when the sanctions check returned | as above (screening envelope) | [D16] |
fraud.assessed | priceD2C, when the fraud check returned | as above (fraud envelope) | [D16] |
affordability.checked | priceD2C, when the credit/affordability check returned | as above (affordability envelope) | [D16] |
quote.declined | priceD2C DECLINE or Refuse (employer/broker manual/rule decline) | D2C: quoteLocator, accountId, partyLocator, status:"DECLINED", declineReason. Refuse: quoteLocator, accountId, productVersionId, previousStatus, status:"DECLINED" (no partyLocator) | [D17] |
quote.accepted | Issue, as the quote flips to ACCEPTED | quoteLocator, accountId, productVersionId, policyLocator, status:"ACCEPTED" | [D18] |
policy.issued | Issue, as the policy is created | policyLocator, accountID, inceptionDate, partyLocator (added for the D2C notifications consumer) | [D18] |
Maps checkEventTypes (identity→identity.verified, screening→ sanctions.screened, fraud→fraud.assessed, affordability→ affordability.checked) is the one place a check concept is bound to its event[D19]; a check whose provider did not return emits no event.
The payment gate. A D2C quote may not be issued until its premium is settled, or a paid product could be obtained for £0. Issue calls quoteRequiresPrepayment(Document) (true when channel:"D2C" or requires_prepayment:true)[D2], and for those quotes fails closed[D20]:
| Condition at issue | Result | HTTP |
|---|---|---|
requires prepayment, no paymentVerifier wired | ErrPaymentRequired | 402 |
| requires prepayment, verifier says not paid | ErrPaymentRequired | 402 |
| requires prepayment, verifier says paid | issues; PaymentIntentID stamped on the policy | 201 |
| invoice-billed (employer/scheme, neither key) | gate skipped | - |
priced quote past expires_at | ErrQuoteExpired | 410 |
The verifier is the billing service: BillingClient.QuotePaymentStatus GETs billing /internal/quotes/{locator}/payment and returns (paid, paymentIntentId); a 404 is read as "not paid", so an unpaid quote fails the gate cleanly rather than erroring[D21]. paid flips true when the Stripe webhook records the settled payment on the billing side; the member's next POST /me/quotes/{locator}/issue then passes the gate, and the settling PaymentIntent id is written to the new policies.payment_intent_id column[D22]. The handler maps ErrPaymentRequired→402 (so the checkout UI can tell "pay first" from a hard error) and ErrQuoteExpired→410 (re-price to continue)[D23].
D2C code references (branch feat/1675, paths relative to repo root; line anchors may drift, the function is the anchor):
- [D1]
services/enrollment/internal/handler/me_quotes.go:100-163-createMemberQuote+buildD2CDocumentforcechannel/requires_prepayment/party_locator;:80-92ownsQuote;:28-45member-scoped routes - [D2]
services/enrollment/internal/service/quote.go:347-365-quoteRequiresPrepayment;:510-519Priceroutes topriceD2C - [D3]
services/enrollment/internal/service/quote.go:217-236-mergeUnderwriting(stampsunderwriting+premium) - [D4]
services/enrollment/internal/service/quote.go:238-266-mergeChecks(stampschecks, nestspremium.optimisation) - [D5]
services/enrollment/internal/d2crating/parse.go:29-77-ParseDeclaration;service/quote.go:77-80+service/errors.go:29ErrMissingDeclaration - [D6]
services/enrollment/internal/service/quote.go:268-302-coverStartFrom;:893-908inception +policy.Document = q.Document - [D7]
services/enrollment/internal/d2crating/d2crating.go:97-116-Outcome+AddOnLine(priced:falsefor unrecognised add-ons) - [D8]
services/enrollment/internal/d2crating/d2crating.go:42-95-Premiumbuild-up,iptRate = 0.12 - [D9]
services/enrollment/internal/integrations/client.go:101-150- check envelope (type/outcome/provider/reference/at/detail,fraud.score,affordability.band);:124-132optimisation(applied:false) - [D10]
services/enrollment/internal/service/quote.go:56-58-quoteValidity = 30 * 24h;:146,157,534,541SetExpiry - [D11]
services/enrollment/internal/service/quote.go:174-209- per-outcome domain facts emitted by enrollment - [D12]
services/enrollment/internal/service/quote.go:402-434-Createemitsquote.created - [D13]
services/enrollment/internal/service/quote.go:160-171-priceD2Cemitsquote.calculated - [D14]
services/enrollment/internal/service/quote.go:559-570- schemePriceemitspremium.rated - [D15]
services/enrollment/internal/service/quote.go:180-189-underwriting.decided - [D16]
services/enrollment/internal/service/quote.go:190-209- per-check events viacheckEventTypes - [D17]
services/enrollment/internal/service/quote.go:103-120(priceD2CDECLINE) +:788-808(Refuse) -quote.declined - [D18]
services/enrollment/internal/service/quote.go:929-963-Issueemitsquote.accepted+policy.issued(withpartyLocator) - [D19]
services/enrollment/internal/service/quote.go:60-70-checkEventTypesmap - [D20]
services/enrollment/internal/service/quote.go:869-891- the payment gate (fail-closed);service/errors.go:20ErrPaymentRequired,:24ErrQuoteExpired - [D21]
services/enrollment/internal/client/billing.go:13-63-BillingClient.QuotePaymentStatus(404 = not paid);service/quote.go:321-332PaymentVerifier+SetPaymentVerifier/SetIntegrations - [D22]
services/enrollment/internal/service/quote.go:855-891expiry gate + intent capture;packages/go/domain/policies.go:55-58PaymentIntentIDcolumn - [D23]
services/enrollment/internal/handler/handler.go:199-207-ErrPaymentRequired→402,ErrQuoteExpired→410;handler/me_quotes.go:217-245issueMemberQuote
6. Populated example: POL-2026-001500, walked end to end
The worked example of the whole documentation set - the same policy as the real policy JSON, the Party page's member Grant, and the Scheme & roster roster row. As it exists live:
{
"locator": "POL-2026-001500",
"account_id": "e88be030-df5e-56e4-8238-0ce04db3d4fc",
"quote_id": null,
"product_version_id": "446b1e15-6cf2-45e7-80f5-c848d6c6dedb",
"status": "ACTIVE",
"inception_date": "2026-08-17",
"jurisdiction": "GB",
"region": null,
"document": { "flow0": true },
"broker_locator": null,
"org_locator": null,
"member_locator": null,
"scheme_locator": "SCH-2026-000001",
"party_locator": "PTY-2026-000006",
"policy_structure": "INDIVIDUAL",
"plan_tier": "STANDARD",
"created_at": "2026-08-17T08:33:30Z"
}Field by field, what each value does:
| Key | Read by | What actually happens |
|---|---|---|
party_locator: PTY-2026-000006 | eligibility projection, claims, timeline, member portal | the policyholder join. Verified downstream: eligibility.member_coverage carries this exact (policy, party) pair live |
scheme_locator: SCH-2026-000001 | employer surfaces, billing pivot | which scheme sponsored it; with party_locator, the natural key the partial unique index enforces |
product_version_id: 446b1e15… | eligibility bootstrap fetch[15], upgrade idempotency check | resolves live to OHC-2026 v2 - the exact version walked on the Product & catalogue page |
account_id: e88be030… | nothing that resolves | uuidv5(OID, "flow0-account:PTY-2026-000006") - recomputed and matched exactly. No account row behind it (§3) |
quote_id: null | - | Flow-0 issues quote-lessly, so the bind FK is not exercised by these rows; it carries the QTE- pin the day a quote binds |
policy_structure: "INDIVIDUAL" | nothing at read time | note the contradiction: the pinned product version says GROUP_MASTER. Nothing reconciles the two (§9) |
plan_tier: "STANDARD" | billing price lookup | resolves to £19.50/member/month from the OHC-2026 v2 catalogue |
document: {"flow0": true} | analytics | the lineage marker, nothing else |
What issuing it caused (all verified live):
- One term + one element -
TRM-2026-001502(term 1, 2026-08-17 → 2027-08-17) andELM-2026-001518snapshotting the OHC-2026 v2 catalogue intocoverage_terms- the next page's worked example. - One
policy.issuedoutbox row - topicenrollment.events, keyPOL-2026-001500, published; payload carriescoverageTerms,planTier,partyLocator,schemeLocator,productVersionId- exactly the shape enqueued at issue[7]. - The projection materialised - one
eligibility.member_coveragerow (PTY-2026-000006 × element static idf6c127ac…) and six accumulators, term-scoped:gp_video0/5,physio_remote0/5,mental_health0/5 sessions,diagnostics£0/£250, plus two unmetered USAGE rows. - The roster pointer - the Scheme & roster example's
policyLocatoris this row.
And the quote table's live shape, since this policy has no quote: a real ACCEPTED quote (structure exact, one of the 17):
{
"locator": "QTE-2026-000051",
"status": "ACCEPTED",
"account_id": "7a9186e7-2d11-49a9-8911-4dbc96e94623",
"product_version_id": "9b127459-17e8-42a0-b5d5-a35eba8f3ceb",
"document": { "jurisdiction": "GB" },
"member_locator": "PTY-2026-000006",
"scheme_locator": "SCH-2026-000001",
"total_premium": null,
"premium_currency": "GBP",
"expires_at": null,
"created_at": "2026-06-15T14:03:35Z"
}Note what it shows: an ACCEPTED quote naming the same member and scheme as the policy above, that no policy row references - the funnel that minted it (June) and the issuance that covered the member (August) are separate lineages. Its product_version_id resolves to GH-2025 v1, not the version the policy was issued under. The quote table is currently a record of funnel activity, not the contractual offer the policy bound.
7. Who references a Policy
| Database.table | Column | Meaning there |
|---|---|---|
group_scheme.scheme_members | policy_locator | the cover issued for this roster row (back-filled by the composer) |
eligibility.member_coverage | policy_locator + policy_id | the projection's provenance - what this coverage row was built from |
claims.claims | policy_locator + policy_id | the policy claimed against |
documents.documents | policy_locator | policy schedule documents |
billing.charges / ledger_entries / installment_schedules | policy_id (uuid) | money joins on the uuid, not the locator |
enrollment.policy_terms / _transactions / _elements | policy_id | real FKs (in-service) - the next page |
Quotes are referenced by quote_events, quote_field_values and underwriting_flags (real in-service FKs, all empty live) and by policies.quote_id (not yet populated). No cross-service reference to a QTE- locator exists.
8. Design determinations
- Two issuance lineages, one table - Flow-0 issues quote-lessly rather than forcing HR flows through a quote funnel; the bind chain remains for broker/underwritten business. #1164 (#1171 epic context).
- Member-level vs group-master is product config, not a policy fork - the policy row carries
policy_structuredenormalised; the determination lives on the product version. #225 (R-01) under epic #219. - Idempotency by natural key, forward-fix, no compensation - the partial unique index is the source of truth for "already issued"; failure recovery is retry + idempotent replay, not sagas[7]. #1164 / DR #2 as cited in code.
- Locators from per-prefix DB sequences - same determination as Party. ADR-1164-05 · #1169.
- No coverage without a product version - refuse to issue rather than issue cover that covers nothing; coverage attaches at enrol. D-07 · #1010.
- A synthetic uuid ref is an acceptable interim identity -
account_idis a documented TODO(#1164); billing built the real employer account alongside it rather than blocking on enrollment growing one[16]. - Issue emits, projections listen - eligibility is built from
policy.issued+ element events, never by reading these tables. (Data architecture)
9. Caveats and extensibility
Group and individual. The fork costs this table almost nothing: an individual (direct-to-consumer) policy is a row with scheme_locator NULL, priced off a MEMBER_LEVEL product version. Every live row is a member-level policy under a group scheme; a future group-master row would be one more row with policy_structure = 'GROUP_MASTER' and elements per insured. The partial unique index already anticipates both: it only binds rows that have both locators.
Where to extend, and where the change lands. The hub was modelled for the full contract lifecycle, so most of what a new distribution channel or product shape needs is already a column, a route or a transaction category here.
| When we need … | What to add | Where |
|---|---|---|
| broker or underwritten business | nothing on the schema: create → price → underwrite → issue is coded and routed[9], and Issue pins quote_id on the policy it creates[8]. underwriting_flags carries the per-quote referrals, voidable via voided_at | QuoteService; a caller that drives the funnel |
| per-product questions on the quote form | field_definition rows on the product version; answers land in quote_field_values, and Issue refuses while a required one is missing[8] | POST /products/{locator}/versions/{version}/fields in policy-admin; consumers on Enrollment: dynamic fields & underwriting |
| quote data we have not promoted to columns | keys in quotes.document jsonb: the rule engine takes the whole document as its evaluation context, so a new key is rule-addressable with no migration, and bind reads jurisdiction straight out of it[8] | quotes.document; evaluateQuoteRules / extractJurisdiction |
| priced quotes to expire | stamp expires_at at price time and gate Issue on it; the column is on the table and EXPIRED is already in the status vocabulary[19] | enrollment.quotes.expires_at; QuoteService.Price / Issue |
| direct-to-consumer (individual) cover | a row with scheme_locator NULL against a MEMBER_LEVEL product version; the partial unique index binds only rows carrying both locators, so it leaves these alone[17] | no schema change |
| a group-master contract with member certificates under it | a policy row with policy_structure = 'GROUP_MASTER' and elements per insured; migration 0020's comment reserves exactly this[17] | enrollment.policies |
| broker-placed policies | set broker_locator at issue; the column is indexed[12] and ListByBrokerLocator serves portfolio views over it[6]. The addition is the broker identity itself: a BROKER value in the party_roles role CHECK (ACCOUNT_HOLDER, INSURED, BENEFICIARY, DEPENDENT today), or a locator on broker_api.broker_configs | policy-admin party_roles migration · broker_api.broker_configs |
| annual renewal | PolicyService.Renew writes term N+1 plus a DRAFT RENEWAL transaction atomically, on PATCH /policies/{locator}/renew. The addition is the scheduler that calls it on the anniversary | enrollment/internal/service/policy.go · Terms, transactions & elements |
| a mid-term change (add a dependant, switch tier) | PATCH /policies/{locator}/endorse writes an ENDORSEMENT transaction; the transaction category vocabulary already carries ISSUANCE | ENDORSEMENT | CANCELLATION | REINSTATEMENT | RENEWAL | REVERSAL | PolicyService.Endorse; enrollment.policy_transactions |
| to sell into a second market | jurisdiction (and region for sub-jurisdiction) are columns on the policy already, set from the quote document at bind; the per-market rules live in policy-admin's market_profiles | policies.jurisdiction / .region · Product & catalogue §9 |
Reading the live table. 699 LAPSED plus hundreds of NULL-tier legacy rows come from lifecycle e2e batches; the 495 (party, scheme)-keyed rows are the Flow-0 business rows. Filter on document->>'flow0' or party_locator IS NOT NULL for analysis. The 17 live quotes (13 ACCEPTED) were minted by branch-side funnel code and bound no policy, so the ERD's "quote binds into policy" edge is true of the code before it is true of the data.
Known defects, with the fix:
- The
policy_structurevocabulary mismatch. Policies default free-text'INDIVIDUAL'; product versions CHECKGROUP_MASTER | MEMBER_LEVEL. Same concept, two dialects, and the worked example holds the contradiction live: a policy stamped INDIVIDUAL pinned to a version stamped GROUP_MASTER, with nothing translating between them. Fix: migratepolicies.policy_structureto the product-side vocabulary (INDIVIDUAL→MEMBER_LEVEL) and add the matching CHECK, in a newservices/enrollment/migrations/step;IssueInternalis the single writer to update[7]. plan_tiercase drift. 28 lowercase'standard'rows sit alongside 464'STANDARD', and a case-sensitive tier lookup misses them. Fix: upper-case the tier at both writers (IssueInternaland the upgrade path) and upper-case the 28 existing rows. The NULLs stay: the column is nullable by design so pre-#1164 rows need no backfill[17].- Four columns exist in the live DB with no migration behind them.
quotes.member_locator,quotes.scheme_locator,policies.member_locatorandpolicies.org_locatorare present and indexed live, but a fresh database built from the pinned commit's migrations would not have them, and the pinned Quote model has no such fields[4]. Fix: add the codifying migration (ADD COLUMN IF NOT EXISTS+ index, the pattern 0019 used forscheme_locator[3]) for the ones we keep, and drop the rest.
References
Code links are pinned to commit 8329d7b on main (2026-08-19); the file is the anchor if lines drift. Pins are checked mechanically by docs/site/scripts/check-code-refs.py.
enrollment/migrations/0002_create_quotes.sql- quotes DDL: UNIQUE locator L4, DRAFT default L7enrollment/migrations/0004_create_policies.sql- policies DDL: quote_id FK L6, ACTIVE default L80019_add_party_locator_to_policies.sql- party/scheme locators + the out-of-band-scheme_locator admissionpackages/go/domain/quotes.go#L11- Quote model (no member/scheme locator fields at this commit)packages/go/domain/policies.go#L32- Policy model, Flow-0 column comments L44-54enrollment/internal/service/policy.go#L134- Cancel + Reinstate;#L113ListByBrokerLocator;#L687-L700race-safe Lapseenrollment/internal/service/policy.go#L465-IssueInternal: idempotency L470-496, UUIDv5 account L503-505, refuse-without-version L531-537, term+element L590-617, outbox L618-639, 23505 path L641-652enrollment/internal/service/quote.go#L397-Issue: quote→ACCEPTED L449,QuoteIDpinned L425, ISSUANCE txn L443;#L482-L521required-field gate;#L525-L537extractJurisdictionenrollment/internal/handler/quotes.go#L16- quote routes (price / underwrite / issue / refuse / discard)enrollment/internal/handler/internal.go#L28-/internal/policies/issuebehind mandatory Idempotency-Key middlewareenrollment/internal/service/quote.go#L268-rateQuoteElements: writesrated_premium+total_premiumat price time0012_add_broker_locator_to_policies.sql- broker_locator + index0021_locator_sequences.sql- the five sequences, START 1000 rationaleenrollment/internal/service/locator.go#L63-nextLocator: DB sequence preferred, atomic-counter fallback with warn-logeligibility/internal/projection/handlers.go#L30-handlePolicyIssued: bootstrap fetch + member_coverage + accumulatorsbilling/migrations/0018_create_accounts.sql- the synthetic-UUIDv5 problem statement; org_locator comment L25-270020_flow0_policy_columns.sql- policy_structure + plan_tier +idx_policies_flow0_naturalpackages/go/domain/enums.go#L11- PolicyStatus vocabularypackages/go/domain/enums.go#L42- QuoteStatus vocabularyenrollment/internal/outbox/worker.go#L20- outbox poll → Kafka publish → mark publishedgroup-scheme-service/internal/service/flow0_compose.go#L139- hop 2: composer calls enrollment issue with derived idempotency key
Live-schema facts (constraint list, index list, Debezium publication, all row counts and value distributions, the UUIDv5 recomputation, outbox and member_coverage evidence) come from PGPASSWORD=olly psql -h 10.0.1.2 -U olly -d enrollment · \d enrollment.quotes, \d enrollment.policies, plus -d eligibility / -d policy_admin / -d billing for the downstream verifications, 2026-08-18.