Counterfoil — Raffle Administrator’s Guide

Counterfoil is a management and recordkeeping system. Two things it will never do, because Washington law forbids them:

Also absent by design, so you know where the boundaries are: no payment processing or cardholder storage, no merchant or bank integration, no inbound webhook of any kind, no printer driver or spooler, no email server, no electronic filing channel to WSGC or your county, and no delete path for any record.

1. Every write is attributed. Persisting a record with no authenticated user and no system context throws. There is no anonymous write path and no null-actor escape hatch. This is why an Auditor session cannot change anything anywhere, and why retiring a user account disables it rather than deleting it — the attribution has to survive the three-year retention window.

2. Records are appended, never edited or deleted. The payment ledger, the reserve-balance log, the significant-event log and the tax-jurisdiction lookup are all append-only. A mistake is corrected by a new entry that supersedes or offsets the old one, so the record shows what was recorded and later corrected — which is what an auditor actually wants to see. Destruction after retention expiry is redaction under a permanent certificate, not deletion.

3. Time comes from one clock. No component reads the wall clock directly; they all take the injected system clock (R16). This is what makes tests deterministic and what will let Module 13 bolt on NTP monitoring without touching a single record path.

4. A significant event is written in the same transaction as the thing it describes. If the change rolls back, so does the event. The one deliberate exception is rejections: ORDER_REJECTED, PAYMENT_REJECTED and CONFIGURATION_LOCKED_ATTEMPT commit in their own transaction precisely because the surrounding one rolled back, and "attempts are rejected and logged" is the acceptance criterion.

5. Frozen artefacts and live views get different guarantees, and the difference matters.

Applying the wrong one would either promise byte identity we cannot deliver, or freeze a view that is supposed to track fulfilment as it progresses.

Five roles, fixed in code; a person may hold several and their permissions are the union.

Two roles are permanently excluded from gaming writes — AUDITOR and SYSTEM_ADMINISTRATOR — and an architecture test auto-discovers every new endpoint to keep it that way.

The tax-jurisdiction lookup is the one System-Administrator-writable table that touches money. It is safe because it is reference data about municipal ordinances, and because it is structurally incapable of altering a raffle: the jurisdiction and rate are snapshotted onto the raffle at configuration and frozen again onto the worksheet at filing.

The winner control is worth understanding in detail because it happens live, in front of an audience. The witness authenticates in band — no session is created and no token is issued — through the same password verification, the same lockout counter and the same per-IP rate limit as a normal sign-in. Every possible witness failure (unknown email, wrong password, insufficient role, same person as the requester) returns one indistinguishable answer, WITNESS_INVALID, so the endpoint cannot be used to enumerate accounts.

Disqualifying a stub is deliberately one person. The remedy for a bad disqualification is the next draw, and requiring a second signature at the barrel would slow the one moment where speed matters.

Every notable action lands in one append-only, hash-chained log (R14, GLI-31 §5.6). Each event carries a unique id, its type, a UTC and a local timestamp, the acting user (or system), the affected entity type and id, a before/after summary for mutations, and the hash of the preceding event.

Counterfoil holds the licensee and the records custodian in hashed JSON files, not tables, because one server serves one legal entity forever and a one-row table models a cardinality that does not exist. A file also cannot be edited by a role — its history lives in the append-only event log.

The asymmetry in records.json is deliberate and is asserted by test: losing your custodian configuration should not stop the raffle selling, but it must stop you filing. Because nothing else notices its absence, a smoke test will not catch a missing records.json — check cfoil records-profile show explicitly.

The two files are kept separate on purpose. organization.json is frozen onto every raffle at its pre-sale lock, so receipts print the licensee as it stood when selling began. Custodian data has the opposite lifetime — it must stay live across a three-year retention window and today’s filing must name today’s custodian. Merging them would freeze stale custodian data onto locked raffles.

records.json must name state: WA. R12 requires records maintained in Washington, and the server refuses to start if it says otherwise, naming the field.

Every failure returns the same envelope:

code is stable and safe to branch on; rule appears when a regulatory constraint is the reason. cfoil exits 10 for a rejected request, 13 for forbidden, 20 for auth required, 30 for transport failure, 2 for a usage error.

Every station or device that submits an order must be registered as a sales unit first, so every order traces to where it was taken. This is also the expansion point for dedicated sales units (L2) and call-centre vendor feeds (L1) later: they become additional registered clients of the same API, not new code paths.

What is validated as you type:

Drawing types: GRAND, EARLY_BIRD, MULTIPLE_TICKET. REFER_A_FRIEND is defined but not selectable in v1 and returns FEATURE_NOT_AVAILABLE — reserved so adding it later (L4) does not migrate a live raffle.

The pre-sale compliance checklist (cfoil raffles checklist) is pass/fail on LICENSE, ORGANIZATION, R3, R4, R5, R10 and R18. Run it days before sales day. The two most common day-one failures — no WSGC licence number recorded, and no licensee profile on file — both surface here rather than at the counter, and both would otherwise refuse the first sale.

Sales channel is required and is exactly one of IN_PERSON, MAIL, FAX, TELEPHONE (R1).

Purchaser rules: state must be WA with a Washington postal code (P1 — a v1 policy, and a code seam rather than a config toggle, so relaxing it for L6 is a deliberate re-release, not a checkbox); an affirmative 18+ attestation is required and is stored with the attesting operator’s id and timestamp (R8). Orders are accepted only inside the configured sales window.

You never type a price. No order request field anywhere in the system accepts money. The server prices from the locked plan and snapshots the plan label, ticket count, price and per-ticket rate onto each order line — because R18 requires the discounted rate recorded against the sale, and because the record set must be reproducible years later from stored data alone.

An order is born complete. There is no draft order and no reservation: the purchaser, the order, its lines, the ticket-series provisioning and all of its consecutive draw numbers are one transaction. Any failure rolls the whole thing back, including the number counter.

Replays are safe and the safety is mandatory. Every submit carries a client-generated clientRequestId, unique per sales unit. Retry the same submit and you get the original order back. This is not optional convenience: undoing a duplicate mint costs a two-person void per ticket and the numbers are gone forever, because a draw number is never freed or reused.

Duplicate purchasers prompt, they do not block. A matching name and postal code returns PURCHASER_MATCH_FOUND with candidates; you either reuse the existing purchaser or acknowledge the duplicate, and the acknowledgement is stored as evidence the prompt was answered.

Corrections: cfoil raffles orders update exposes the source reference and the note only. Changing what was sold goes through a void, not an edit.

Counterfoil is record-only. Your merchant facility processes the payment; Counterfoil records what happened.

As with voids, approving or rejecting a refund requires a --note.

Methods: CASH, CHECK, MONEY_ORDER, CREDIT_CARD_EXTERNAL.

The ledger is append-only and signed. Three entry types: PAYMENT (positive), REVERSAL and REFUND (both negative). There is no update and no delete, so SUM(amount) for an order is its amount paid — which makes "the report equals the sum of individual payment records" a definition rather than a reconciliation exercise. There is no ADJUSTMENT type and adding one would break that property.

Reversal and refund are different things and only one touches tickets.

Eligibility is all-or-nothing. An order’s tickets become drawing-eligible only when payments total the full order amount. Partial payment is not partial eligibility; it is no eligibility.

Two payment dates, never interchangeable. paymentDate is the business date the money moved — use it for deposit matching and as the reconciliation report’s default axis. recordedAt is the clock instant the system learned, and it is what pool determinism and audit replay use. A report’s basis must apply to both sides of the report or its balancing identity means nothing.

No card number can exist anywhere. The last-4 field is four characters wide, and every operator-supplied text field is scanned for any 13–19 digit run (separators between digits ignored). A rejected value is never echoed back, logged, or written to the event log — you get CARD_DATA_REJECTED and nothing else.

Overpayment is rejected (PAYMENT_EXCEEDS_ORDER_TOTAL). Money above the order total is not a gambling receipt, and recording it here would corrupt the R18 breakout at its source.

Gross receipts are recognized when an order becomes fully paid, never prorated across installments. Partially paid money sits in an explicit held bucket until the order completes, which is what lets an order paid in installments across a period boundary balance in both periods.

A reconciliation report that does not balance is not returned with a warning flag — it fails, naming the discrepancy.

The financial summary’s netReceiptsProvisional is computed against configured prize exposure. It is labelled provisional for a reason: never file on it. The tax worksheet uses prizes paid, and the difference can be the entire grand prize.

Receipts are issued automatically for every fully paid order by a sweeper, so no operator has to remember. It runs on a schedule rather than inside the payment transaction deliberately — putting it there would hand the money path an outbound dependency it does not have.

A receipt carries every R9/R10 disclosure, resolved and frozen at issuance: organization name and licence number, raffle name, purchaser, order reference, every draw number, the plan option and amount paid, each drawing’s date/time/location, the winner-must-be-present flag, prize descriptions and any disclosed minimum.

Delivery channels are exactly EMAIL and MAIL_PRINT — the two R9 authorizes. There is no SMS channel.

A receipt is a snapshot, so re-sending can never change what a purchaser was told, even after their address is corrected. A correction is a reissue: a new version supersedes the prior one, which is retained, and the draw numbers never change.

Printing is not confirmation. Generating the batch PDF marks nothing. A receipt becomes "printed for mail" only when an operator confirms the run. A jam is an explicit abandonment with a reason that requeues every member, and a run left unconfirmed past its expiry is abandoned automatically so a forgotten batch cannot strand receipts.

Email is at-least-once and bounces are polled, never received. Providers offer no idempotency key, and R9 settles the choice between an occasional duplicate and an occasional silence. A hard bounce queues a mail fallback and suppresses the address until it is corrected — but emailedAt stands, because the send did happen. There is no inbound webhook anywhere in this system and adding one is out of scope.

No card digits appear on a receipt: the payment method name only.

A drawing’s eligible pool is a pure function of the locked configuration and an instant. Nobody decides membership by hand, and nothing in the pool engine can see a winner.

R6 is enforced by absence: no rule takes a winner as input, references a winner record or can even import the drawing code — asserted by a dependency test, not left to care. A scenario test proves today’s code does not subtract a winner; the dependency test proves the next engineer cannot make it.

show prints the eligibility rule in plain English, generated from the locked configuration — that is what you hand a WSGC inspector who asks how the pool was decided, and it cannot drift from the rule because the rule generates it.

A batch is a materialized, immutable set — not a query. Generation resolves the eligible pool at one instant and writes one row per stub, freezing the purchaser name, city, state and phone that print on it. Every one of those inputs stays mutable afterwards, so the record of what went into the barrel is frozen too. A batch is reproducible from its stored pool instant alone.

Each stub carries: draw number, purchaser name, city/state, phone, the raffle licence number, the drawing identifier, batch id and sequence number, and a machine-readable code encoding CF1:<raffleId>:<drawingId>:<drawNumber>.

Render profiles: ESCPOS_80 (the reference — a receipt printer with a partial cut between stubs, which is exactly the tear-off artefact a barrel wants), ESCPOS_58 (carries a QR code instead of Code 128, which is not reliably scannable across a 384-dot head), PDF_LETTER and PDF_A4 (4-up with cut guides). All four carry the identical payload.

Practical advice for a grand-prize barrel. Twenty thousand stubs on an 80 mm thermal roll is roughly 800 m of paper and 90 minutes of continuous printing. Use --render-profile PDF_LETTER and an office printer with a guillotine: about fifteen minutes for the identical stub.

Supplements and replacements. A supplement takes the eligible pool minus every member of every active batch, which is what makes "the union of manifests equals the eligible pool" true by construction. Active batches for a drawing stay pairwise disjoint — a duplicate stub in the barrel is a second chance to win. A replacement supersedes every active batch, requires a reason and is Raffle-Administrator-only; superseded batches and all their stubs are retained forever.

Streaming bytes is not printing, and printing is not confirmation. cfoil counterfoils print opens a run, streams the server’s bytes verbatim to the printer, and then asks whether they came out. Only your confirmation records stubs as being in the barrel. A jam is abandon with a required reason; you resume from where it stopped rather than reprinting. A transport failure never resolves the run — the CLI exits 40 and says plainly that only a human can tell how much reached paper.

A confirmed run with no stream hash is meaningful, not missing data: it marks a range accepted off a partial stack rather than driven through a device in that run. Do not backfill it.

The CLI does no layout and no encoding — the server renders, because the server is the signed, lab-certifiable artefact and rendering a $1M drawing’s printed evidence in an unsigned client would put it outside the certified boundary.

Verification compares the manifest to the eligible pool and produces the numbers you act on:

This is the phase most likely to stop a drawing at the worst possible moment. Start it weeks out.

Every winner gets a fulfilment record inside the award transaction: no winner without one, and no record without a winner. States are PENDING → AWARDED | FORFEITED_REDRAWN, both terminal, each transition carrying its user, instant and reason.

Forfeiture is the interlock that makes a redraw legal, and the order is not negotiable. A generated database column nulls itself on forfeiture under a unique index, so at most one unforfeited winner exists per prize across sessions. Forfeit first, then redraw — attempt it the other way and the award simply fails on the key.

deliveredOn is not paperwork: it is what finally resolves R12’s "printed tickets kept ≥ 30 days or until the prize is awarded", and without it the retention answer for the physical counterfoils is NOT_COMPUTABLE.

There is no returned-prize state, no procurement workflow, and no tax computation or withholding of any kind — federal tax reporting is L5, and the winner record reserves an attributes area that nothing currently reads.

See Chapter 3, which is entirely about this phase.

Every report carries its generation timestamp, generating user, raffle licence number and content hash, and every fetch of one emits an EXPORT_PRODUCED event.

The record set is gross receipts with the R18 discounted-sales breakout, prizes paid, net receipts, the ticket-sales summary, the winners register and the unsold/void ticket listing.

Counterfoil composes it and never recalculates it. Every figure is fetched from the part of the system that owns it — gross receipts from the payment ledger, ticket counts from the inventory, pools from the eligibility engine, batches from the barrel, results from the drawing reports, winners from fulfilment. The only arithmetic performed here is net receipts and the tax. A second SUM over payments in the reporting code would be a second definition of gross gambling receipts, which is exactly the mistake the barrel was forbidden from making with pool membership.

A mismatch blocks generation (RECORD_SET_NOT_RECONCILED) and names the discrepancy. cfoil records reconcile shows the verdicts whether or not they block:

Finalizing requires a note. It records why the filing was frozen when it was, and it is stored beside the filing, not inside it: it is not one of the filed figures, so it is not part of the worksheet’s content hash, its PDF or its report exports, and a worksheet finalized earlier reads exactly as it did. cfoil tax show and the API return it as finalizationNote; the archive carries it; the finalization event records it.

Tax = (net receipts − the $10,000 exemption, floored at zero) × the raffle’s effective rate, capped at 5%. The document shows every input, the jurisdiction (city/county/state), whether the rate was system-suggested or administrator-overridden, the citation and the rate’s effective date.

The worksheet uses prizes paid, never prizes configured. Prizes paid is the retail value of every prize held by an unforfeited winner. Prizes configured but never awarded contribute nothing and are printed as their own line, because they raise the taxable figure and their absence must be visible rather than inferred.

Finalization freezes the worksheet and the tax rate together, in one transaction, and is a significant event. Afterwards cfoil raffles tax-rate refuses with TAX_RATE_FINALIZED. Regenerating from unchanged data yields an identical document.

Preconditions you will meet: RAFFLE_NOT_COMPLETE, RECORD_SET_NOT_RECONCILED, CUSTODIAN_NOT_CONFIGURED, and EXEMPTION_ALREADY_CLAIMED.

On the exemption. RCW 9.46.110 exempts the first $10,000 per organization per year, not per raffle. For a licensee running one enhanced raffle a year — this product’s target — the two readings coincide. Where they diverge, finalization refuses unless you acknowledge it explicitly. Counterfoil does not apportion the exemption across raffles: that is your filing decision with your compliance lead, not a rule to invent in software.

One surface, one cover page carrying the WAC 230-11-105 custodian details, one export event and one hash discipline. Keys: record-set, tax-worksheet, reconciliation (needs from/to), financial-summary, ticket-inventory. The module-specific endpoints still work unchanged; this adds a uniform way to fetch any of them, and brings reconciliation, the financial summary and the ticket inventory into PDF.

Items Module 13 still owes a lab: signed builds with startup software verification, the compliance matrix structured to GLI-31 v1.1 section numbering, backup/restore evidence, row-level integrity checks and clock-drift alerting.

The archive holds every record class for one raffle: orders, purchasers, payments, tickets, pools, counterfoil manifests, drawing reports, winners, generated reports and the raffle’s significant events, plus a manifest of file-level checksums and record counts.

verify and extract run with no server, no database and no network. That is a PRD requirement, not a convenience: the utility and the server share one implementation of the container format, because two implementations of a cipher is how a format silently forks.

The chain witness is what makes a per-raffle cut of a global hash chain verifiable. Exporting only one raffle’s events would leave holes indistinguishable from deletions, so the archive carries (seq, eventHash, prevHash) for every event in the covered range — hashes only, no payloads. An offline verifier re-links the excerpt into an unbroken chain without the archive containing one byte about another raffle.

Round-trip check: cfoil archive status --export 3 returns the live record counts the archive’s manifest is compared against. That comparison never requires the key to come back to the server.

The passphrase is never stored, hashed, hinted at or returned — not even as a derived verifier, which would be an offline-crackable artefact of a key we promised not to keep. There is no escrow, no recovery and no reset. This is also why there is no queued export state: the key lives only in the requesting process, so a restart mid-export fails it unresumably, with that reason recorded. Escrow the passphrase in your organization’s own key custody arrangement before you export.

A destruction decision is stated, never assumed. The approval requires both an explicit approve (true or false; in cfoil, --approve or --reject) and a note. A request that omits either is refused and nothing is redacted.

NOT_COMPUTABLE is a real answer, not a failure: either no fiscal-year end is configured, or a winner has not claimed so the "or until the prize is awarded" half is genuinely unresolved. A guessed date on a compliance screen would be worse than an honest gap.

Destruction is redaction under a permanent certificate, never a delete. Every count, figure, draw number and hash survives; only personal detail is overwritten — which is why the record set still reconciles the day after one runs, and why the certificate itself is retained forever.

Three hard preconditions:

Frozen artefacts are never destructible: receipts, drawing reports, counterfoil manifests, tax worksheets and the event log. WAC requires their retention and nowhere requires their destruction — so accept that a winner’s name survives in an immutable R17 report after a purchaser redaction.

No sweep ever repairs. A finding is an alarm; a silent repair would destroy the only evidence that something moved.

Counterfoil writes an operational log to standard output, separate from the significant-event log. They answer different questions and neither replaces the other: the event log is the tamper-evident legal record an auditor interrogates months later; this is what tells you, now, what the system is doing.

The server also serves a browser interface for account administration, raffle configuration and a Raffle Administrator’s approvals and oversight, at

on the same port and from the same jar as the REST API. It is a client of that API, not a second implementation of it: every form calls the API’s own code in-process, so a change made in the browser writes the same rows, is attributed to the same user, emits the same significant events and is refused with the same error code, rule and citation as the equivalent cfoil command. It adds no endpoint to /api/v1 (see Appendix B).

Sign in with the same account and password as cfoil. Lockout, the per-address rate limit and the idle and absolute session timeouts are shared: five failed sign-ins in any mix of browser and cfoil lock the account. A user whose password must be changed is held on the password page until they change it. A session that expires with a form open sends the user to the sign-in page and discards what was typed; nothing is saved.

Every environment variable application.yml reads, alphabetically. These are the deployment surface: anything in the table above that is not bound to one of these is changed by editing the YAML and restarting.

The four integrity sweeps are staggered (03:15, 03:25, 03:40, 03:50) so they do not contend, and they run after the 02:00 chain verification. If you move one, keep the ordering: each later sweep assumes the earlier data is settled.

cfoil reads its own separate environment variables, configuring the client rather than the server — they have no effect on the server. Precedence (highest wins), the same order the client applies everywhere: a command-line flag, then the environment variable below, then the active profile (~/.counterfoil/config.json), then the built-in default.

Three settings above name a file rather than a value, because what they hold is licensee identity rather than tuning: the server reads each one at startup, validates it, and hashes it. The application never writes any of them.

Every field below is taken from the loader that validates it. A file that is present but invalid fails startup naming the offending field — deliberately, because a mistyped licensee name reaching a document mailed to the public is worse than a server that refuses to boot. An absent file is a different state: it means "not configured yet" and the server starts.

System-integrity operations (Module 13) arrive with a later release (see the product PRD and Appendix C).

These apply to every endpoint unless a section states otherwise.

Fixed enum (no runtime editing in v1). Used verbatim as the authorization role string.

A user holds one or more roles; effective permissions are the union.

Issues, inspects, and revokes the opaque server-side session tokens that authenticate every other call, and handles self-service password change. Defined by the identity & access-control module spec.

Login key is email (unique, case-insensitive, normalized to lower-case).

Account lifecycle for the five fixed roles: creation, role assignment, lockout recovery, password reset, and retirement. Defined by the identity & access-control module spec.

All endpoints require SYSTEM_ADMINISTRATOR. Users are never hard-deleted — retirement is disable (attribution must survive for the records' retention life, R12).

POST /api/v1/users request:

User resource (returned by create / fetch / update):

Password fields are never present in any response. User-admin mutations emit RECORD_CREATE / RECORD_MODIFY significant events (entity_type=users) with email masked in the event summary.

The system’s audit backbone: an append-only, hash-chained log of significant events — every event carries the hash of the prior event, so any edit, deletion, or reorder is detectable — with an interrogation search (R14) and chain verification. Defined by the event-log module spec.

Events are written only internally (by every component, through the event port) — there is no create/update/delete endpoint. These endpoints are read/observe only.

Access is limited to the read-only reviewer and operator roles: AUDITOR, RAFFLE_ADMINISTRATOR, SYSTEM_ADMINISTRATOR. Running a verification is a system operation restricted to SYSTEM_ADMINISTRATOR — it appends an EVENT_CHAIN_* event, so it is a state change an Auditor may not cause (Auditors read the outcome instead).

The enhanced raffle’s legal parameters of record: the raffle itself, pricing plans (single + bundles, R3/R18), drawings with typed eligibility parameters (R5), fixed-value prizes (R4/R10; percentage-of-receipts prizes are reserved, non-selectable in v1), and the local gambling-tax rate (R19) — all governed by the irreversible pre-sale lock. Defined by the raffle-configuration module spec.

Lock semantics (R5): when the first ticket is issued (order intake), the configuration transitions irreversibly to LOCKED. Thereafter every mutating configuration endpoint returns 409 CONFIGURATION_LOCKED and emits a CONFIGURATION_LOCKED_ATTEMPT significant event. There is no unlock and no manual-lock endpoint. Exception: the tax rate (PUT /raffles/{id}/tax-rate) remains editable post-lock until the tax worksheet is finalized (409 TAX_RATE_FINALIZED thereafter). A raffle cannot lock — cannot sell its first ticket — until licenseNumber is recorded (409 LICENSE_REQUIRED surfaces through the issuance flow).

Authorization: reads are open to all five roles (raffle parameters are public ticket disclosures). Writes are RAFFLE_ADMINISTRATOR only — segregation of duties: SYSTEM_ADMINISTRATOR and AUDITOR hold no gaming-record write authority.

Representation: regulatory violations return 400 RULE_VIOLATION with error.rule (e.g. "R3") and error.details.citation; money and rates follow the Money & rates convention.

Reference data: the city/county/state local gambling-tax lookup that suggests a rate at raffle creation (R19). Defined by the raffle-configuration module spec. All roles may read; the System Administrator maintains it.

A rate change is an append, never an edit. The suggestion already picks the latest row in effect, so history is preserved by construction and yesterday’s suggestion stays reproducible. A row that has taken effect is history — a raffle may have been configured from it — so it is superseded by a new row rather than edited, and PATCH refuses with 409 JURISDICTION_IN_EFFECT. There is no DELETE: a jurisdiction that stops taxing raffles gets a new row at 0.0000.

Why a System Administrator write is not a breach of segregation of duties. This is reference data about municipal ordinances — the same kind of fact as a timezone database — not a gaming record. A write here touches no raffle, order, ticket, payment, pool, drawing or winner, and it is structurally incapable of altering a raffle’s figures: the jurisdiction is snapshotted onto the raffle at configuration and frozen again onto the tax worksheet at finalization. Giving it to the Raffle Administrator instead would let the person who configures a raffle move the rate it was suggested.

GET …/suggestion 200 OK:

{ "matched": false } is a normal answer — the administrator enters the rate directly.

The single source of draw numbers: consecutive, gapless, unique per raffle, with clearly-identified voids (R10, R13). Defined by the ticket-inventory module spec.

Issuance has no HTTP endpoint. A draw number is minted only through order completion (order intake), which calls the internal issuance seam inside its transaction; that call also triggers the first-sale configuration lock (R5). There is deliberately no manual-mint path — mirroring the no-manual-lock rule.

Voids are a two-person control (R13, AC #4): one user (Sales Operator or higher) opens a void request with a controlled reason and free text; a different Raffle Administrator or Finance/Records Officer approves it (409 VOID_APPROVAL_SELF if the same user). Only an approved void flips the ticket to VOID — the number is kept, never freed, and the row stays permanently visible in inventory and reports. A pending void does not change eligibility.

Authorization: reads (inventory, ticket lookups, void-request queue) are open to all five roles (the Auditor must read inventory). Void writes are gaming-record mutations — SYSTEM_ADMINISTRATOR and AUDITOR hold no write authority.

The sales-entry API (Module 5) — the one versioned surface through which every order enters the system, whatever channel it arrived on. The operator UI is a client of these endpoints, not a privileged path beside them, which is what lets a future call-center feed (L1) or RSU device (L2) become an additional registered client rather than additional code.

An order and its draw numbers are created together, in one transaction, or not at all. There is no draft order, no reservation, and no endpoint anywhere that mints a draw number on its own. If any step fails — closed window, exhausted inventory, unlicensed raffle — the whole order rolls back and no number is consumed.

Prices are never client-supplied. A request names a pricingPlanId and a quantity; the server reads the locked plan and derives the money. No request body in this section has a price or amount field. Each stored line keeps a snapshot of the plan’s terms, including the R18 discounted per-ticket rate.

The registry of stations and devices permitted to submit orders. Every order records the sales_unit_id it came from, which is the seam that lets L1 vendor feeds and L2 RSU devices arrive as registered clients of the same order API.

Segregation. This is administered by the SYSTEM_ADMINISTRATOR because it is station/device inventory, not a gaming record — the row holds no purchaser, money, or ticket data, and GLI-31 Ch. 3 treats sales-unit registration as a system-administration function. That role has no write authority on orders, purchasers, or tickets.

Deployment checklist: at least one ACTIVE WORKSTATION must be registered before the first sale, or every order is refused with 409 SALES_UNIT_UNKNOWN.

Errors: 400 VALIDATION_ERROR (unknown type, duplicate code), 400 FEATURE_NOT_AVAILABLE (RSU, VENDOR_FEED) on create; 404 NOT_FOUND on retire.

type is WORKSTATION in v1. RSU (L2) and VENDOR_FEED (L1) are declared but not registrable — attempting either returns FEATURE_NOT_AVAILABLE, so those phases add rows rather than a migration. Registration and retirement emit RECORD_CREATE / RECORD_MODIFY (entity_type = sales_units).

Counterfoil never processes a payment. Card, check and cash handling all happen on the organization’s existing merchant facilities; this module records what happened, when, and the processor’s transaction-ID reference. There is no gateway client, no webhook endpoint, no settlement importer and no tokenization vault anywhere in the system — so "the payment processor is down" changes nothing here.

No column can hold a primary account number. cardLast4 is exactly four digits, and every operator-supplied free-text field is rejected if it contains a 13–19 digit sequence (spaces and hyphens between digits are ignored, so 4111 1111 1111 1111 is caught). The rejected value is never echoed back, logged, or written to the event log. This is the PRD’s literal rule rather than a Luhn check; the known cost is that a purely numeric 13–19 digit processor reference is refused.

A refund returns money and voids every ticket on the order, in the same transaction. There is no state in which a refund exists against a live ticket: any failure rolls back the whole thing. One person requests; a different Raffle Administrator or Finance/Records Officer approves — the same control Module 4 applies to ticket voids, kept at the level where the human decision actually is.

v1 refunds a whole order. A purchaser returning some tickets is handled as a full refund plus a fresh order; a line-level partial refund would require a mutable order total and an R18 breakout no source document supports. To correct a recording mistake without touching tickets, use a reversal instead.

The request carries no amount — a refund always returns the whole of what the order has paid, re-read under the order lock at approval time so it cannot go stale against a payment or reversal that lands in between. REFUND_NOT_ELIGIBLE also covers the case where a ticket on the order has a pending individual void request: the refund waits for that control rather than racing it.

Approval response 200 names the consequence explicitly:

The list carries orderReference on every row and, on an APPROVED row, voidedTicketCount and voidedDrawNumbers — the same consequence the approval response named, read back from the stored void rows. refundPaymentId and order appear on the approval response only.

Each ticket voided by a refund gets its own ticket_void_request row carrying reason = REFUND and the refund’s id, so an auditor sees one decision that voided seven tickets, not seven unexplained voids. REFUND is not selectable on an individual void request — the only way to reach it is the refund control.

Errors: 400 VALIDATION_ERROR, 404 NOT_FOUND on both.

basis is PAYMENT_DATE (default — the business axis, for deposit matching) or RECORDED_AT (the system axis, for audit replay). It governs both sides of the report, because the balancing identity only holds when both are measured on the same axis. Generating a report emits REPORT_GENERATED.

Two views, two sources, deliberately. byMethod / byChannel / byEntryType are every ledger entry in the range — the figure a deposit is matched against. grossReceiptsByPlanOption is the R18 discounted-sales breakout, taken from each order’s immutable line snapshot and recognized when an order becomes fully paid (never prorated across installments — splitting a partial payment across a mixed single-plus-bundle order would invent a per-plan figure no source document supports). heldAgainstPartialOrders is the real quantity that ties them together: money received against orders that are not yet fully paid, and therefore not yet gross gambling receipts.

An order paid in two installments across a period boundary shows as held in the first period and recognized in the second, and both periods balance:

A report that does not balance is never returned with a warning flag — it fails with the discrepancy named, matching Module 12’s "any mismatch blocks generation" posture. contentHash covers the figures only (not the generation timestamp or user), so regenerating from unchanged records yields an identical hash.

financial-summary reports gross receipts to date, the prize exposure configured in Module 3, and netReceiptsProvisional. That net is legitimately and deeply negative early in a raffle, because a $1M grand prize is configured long before receipts accumulate; the response carries notes stating that prizes paid, the cash/noncash split and the R11 reserve check are Module 11’s, and the tax worksheet is Module 12’s.

Every fully paid order gets a receipt carrying the disclosures RCW 9.46.0323(3)(j) (R9) and WAC 230-11-010/-360 (R10) require: organization name and license number, raffle name, purchaser name, order reference, every draw number issued, the pricing-plan option and amount paid, each drawing’s date/time/location, whether the winner must be present, and the prize descriptions with any disclosed minimum.

A receipt is an immutable snapshot, not a query. The disclosures are resolved and frozen at issuance and stored as content_json; the PDF is rendered from that snapshot on demand and never stored. Two things follow. Re-sending never changes what a purchaser was told, even after their address is corrected or the local tax rate is edited. And the render is byte-deterministic — the document’s dates and /ID come from the receipt’s own issuance instant and content hash rather than the wall clock — so a reprint three years later is provably the same document.

A correction is a reissue: a new version supersedes the prior one, which is retained. The draw numbers cannot change; they are re-read from the same tickets.

Issuance is automatic. A server-side sweeper issues a receipt for every fully paid order, so no operator has to remember. The endpoint below is the on-demand path and is idempotent.

deliver is AUTO (default — email when the purchaser has a usable address, otherwise mail) or NONE (issue the record and queue nothing; the first-enable backfill mode on a raffle that has been selling for months).

GET …/document marks nothing. Rendering bytes is not evidence that a purchaser was sent anything — a receipt becomes "printed for mail" only when an operator confirms a print run.

Three separate acts, deliberately. Generate gathers what is waiting and renders it. Fetch streams the PDF as often as you like and marks nothing. Confirm is the one thing that records a purchaser as mailed, with the confirming user and the time — because a record saying a receipt was sent must mean a human saw it come off the printer. An abandon requires a reason and returns every member to the queue as a fresh attempt; a run left unconfirmed past its expiry is abandoned automatically, so a forgotten batch cannot strand receipts.

The batch PDF is one multi-page document with each receipt beginning on a fresh page, so a run can be split at page boundaries and never puts two purchasers on one sheet. pageCount is the sheet count to check the paper stack against, and contentHash covers the ordered member receipt hashes.

The physical drawing pool: the stubs a winner is hand-drawn from, and the record that proves the barrel is complete (R2, R10, R12, R13, R17). Defined by the counterfoil module spec.

A batch is a materialized, immutable set — not a query. Generating one resolves the drawing’s eligible pool at a single instant (poolAsOf) and writes one row per stub, freezing the purchaser name, city, state and phone that print on it. Everything downstream — rendering, the manifest, the checksum, a reprint after a jam, Module 12’s archive — reads those frozen rows and never re-derives the set. It has to work this way because the inputs move: a purchaser can be corrected, a ticket voided, a payment reversed. The barrel is a snapshot of a moment, so its record is one too.

This module does not compute pools. Section B.18 owns the eligibility rules and supplies membership through a contract this module only consumes. A batch cut against a drawing whose pool is still open records poolBasis: PRELIMINARY; once the pool is closed it records poolBasis: CLOSED with that pool’s poolId, so an auditor can tell from the batch row alone whether it was cut against a final pool or a moving one.

Which tickets are in which drawing — the most legally sensitive logic in the system (R5, R6). Defined by the drawing pools module spec.

A pool is a pure function of (locked configuration, asOf). Membership recomputes from immutable inputs only: the locked drawing’s typed parameters, placedAt, issuedAt/voidedAt, and Module 6’s as-of ledger form — never paymentStatus, which is a cache. Given the same instant it returns the same set today, on drawing night, and in the 2029 audit.

Closure freezes that output, once, irreversibly. There is no reopen, no re-close and no supersession; "open" is simply the absence of a closure. Closing is refused before the drawing’s entry cutoff has passed, which is what makes irreversibility survivable — the failure it would otherwise expose, a pool closed before the sales it was meant to contain, cannot happen.

Two instants, never interchangeable. The entry cutoff bounds the sale (placedAt ≤ cutoff) and comes from locked configuration — for a grand prize drawing it is structurally the raffle’s sales close. The closing instant bounds what the system knew: void and payment state are evaluated there. A mail order placed before an early bird cutoff whose cheque clears afterwards is in the pool if the administrator closes once the mail is processed, and out if they close at the stroke of the cutoff. That choice is theirs, and pendingPaymentCount tells them what it costs before they make it.

Membership and standing are different questions. Membership is frozen and can only shrink after closure, never grow — no sale and no late payment can join a closed pool. Standing — can this stub still win — is computed live, so a ticket voided or a payment reversed after closure leaves the drawable set immediately (R13) with no write anywhere. Those members stay in the frozen list, named in withdrawn with a reason, because the stub is physically in the barrel and someone has to pull it.

Rules per drawing type, dispatched from a registry so adding one touches no existing rule:

ruleId is versioned and frozen onto every closed pool, so a pool closed under a superseded rule stays traceable and the determinism check can distinguish "not reproducible under this build" from "corrupt".

Errors: GET /pool and /members — 400 FEATURE_NOT_AVAILABLE, 400 RULE_VIOLATION, 404 NOT_FOUND; closure — 409 POOL_ALREADY_CLOSED, 409 POOL_CUTOFF_NOT_REACHED, 409 POOL_PENDING_PAYMENTS, 400 FEATURE_NOT_AVAILABLE, 400 RULE_VIOLATION, 404 NOT_FOUND; verification — 409 POOL_NOT_CLOSED, 404 NOT_FOUND.