Meridian Simulation Deep Dive

Source repos pinned for this briefing: . and ../voyage-bank

Pinned commits: voyage 14f3b190db8817399dcd30e1dc4e1ae7674bbf8a; voyage-bank ef4d7d4f9a66a05d68c265debc681d506a0606c6

Audience: engineers, architects, operators, investors.

Purpose: explain why the Meridian National Bank simulation proves the platform at bank scale.

Scope: simulation data, topology, workload generation, verification, gaps, and operating commands.

1. Opening - Scale Summary

Meridian National Bank is not a toy tenant.

It is a bank-scale simulation.

The checked-in seed and verification outputs describe 380 canonical branches.

They describe 10 regional operational shards.

They describe 64 customer-directory shards.

They describe 1,696,932 generated service sessions.

They describe 702,912 generated bookings.

They describe 926,566 generated queue entries.

They describe 668,400 generated reporting-fact rows.

The canonical branch count comes from ../voyage-bank/seed/branches/branches.json:6.

The 10-region branch distribution comes from ../voyage-bank/seed/branches/branches.json:10.

The operational row counts come from ../voyage-bank/seed/verification-report.json:13.

The reporting-fact count comes from ../voyage-bank/seed/verification-report.json:25.

The customer-shard count comes from ../voyage-bank/seed/verification-report.json:37.

The historical scale summary also appears in ../voyage-bank/docs/reality-roadmap.md:52.

The data generator is a 4,663-line TypeScript program at ../voyage-bank/scripts/backfill-day.ts.

The direct tests for that generator are in ../voyage-bank/scripts/__tests__/backfill-day.test.ts.

The seed validator is a 1,840-line TypeScript program at ../voyage-bank/scripts/validate-seed-data.ts.

The seed verifier is at ../voyage-bank/seed/verify-seed.ts.

The forward-generation runbook is at ../voyage-bank/docs/simulation-forward-generation-runbook.md.

The simulation is designed to answer operational questions.

It does not merely fill charts.

It models queues.

It models bookings.

It models service sessions.

It models role-qualified staff.

It models event-driven follow-up.

It models branch-day reporting facts.

It models queue-day reporting facts.

It models service-day reporting facts.

It models staff-day reporting facts.

It models customer-shard distribution.

It models D1 operational shard placement.

It models workload pressure by time of day.

It models appointment grid rules.

It models walk-in off-grid arrival timestamps.

It models lunch blocks.

It models short breaks.

It models no double-booking constraints.

It models role-service eligibility constraints.

It models status-state differences between historical and future data.

It models failures in the generation pipeline.

It models rollup repair.

The result is a simulated bank that can be interrogated like a working system.

2. Why Simulate?

A demo without live traffic can lie.

It can show dashboards without operational stress.

It can show branch views without scheduling pressure.

It can show queues without capacity conflicts.

It can show appointments without role constraints.

It can show reports without shard topology.

It can show success without showing repair paths.

Meridian exists to close that gap.

The simulation makes a demo answer real operational questions.

How does a branch look during morning rush?

How does it look during lunch pressure?

How does it look during the afternoon appointment surge?

Which services are tellers allowed to perform?

Which services require a mortgage officer?

Which services require an investment advisor?

Which branches can host events?

Which staff members can host those events?

How do wait times change by queue type?

How do scheduled appointments coexist with walk-ins?

How does reporting stay consistent when operational shards are separate?

How does a tenant behave when regional databases are large?

How does forward generation behave when a D1 import fails?

How does the system avoid pretending a failed multi-region fill succeeded?

The architecture spec states that the goal is lifelike simulation, not mock data.

That claim is explicit in ../voyage-bank/docs/architecture/simulation-ecosystem-spec.md:10.

The spec describes dynamic customers and staff in ../voyage-bank/docs/architecture/simulation-ecosystem-spec.md:42.

The spec describes generated traffic and realistic banking patterns in ../voyage-bank/docs/architecture/simulation-ecosystem-spec.md:106.

The spec sets mega-scale targets in ../voyage-bank/docs/architecture/simulation-ecosystem-spec.md:137.

The spec says Meridian is the first mega-scale instance in ../voyage-bank/docs/architecture/simulation-ecosystem-spec.md:200.

That matters to engineers.

The generator has to be deterministic.

The generator has to be idempotent.

The generator has to be shard-aware.

The generator has to respect role eligibility.

The generator has to respect temporal conflicts.

The generator has to repair reporting facts.

The generator has to support future-safe states.

That also matters to buyers.

The buyer sees dashboards that behave like operations.

The buyer can ask capacity questions.

The buyer can ask staffing questions.

The buyer can ask branch-comparison questions.

The buyer can ask executive-rollup questions.

The buyer can ask operational-risk questions.

The demo does not need a live bank integration to show those behaviors.

It needs a credible simulated operating system.

That is what Meridian supplies.

3. The Topology

The Meridian topology has four main planes.

The first plane is tenant configuration.

The second plane is regional operations.

The third plane is customer directory sharding.

The fourth plane is reporting and simulation control.

The branch configuration lists 380 branches in ../voyage-bank/seed/branches/branches.json:6.

The branch configuration lists 10 regions in ../voyage-bank/seed/branches/branches.json:9.

The first region entry binds the northeast region to mnb-ops-current-northeast in ../voyage-bank/seed/branches/branches.json:69.

The first region entry exposes the binding name OPS_NORTHEAST_DB in ../voyage-bank/seed/branches/branches.json:74.

The simulation orchestrator binds the config database in ../voyage-bank/workers/simulation-orchestrator/wrangler.toml:5.

The simulation orchestrator binds the simulation core database in ../voyage-bank/workers/simulation-orchestrator/wrangler.toml:10.

The simulation orchestrator binds the simulation observer database in ../voyage-bank/workers/simulation-orchestrator/wrangler.toml:15.

The simulation orchestrator binds 10 operational D1 databases in ../voyage-bank/workers/simulation-orchestrator/wrangler.toml:20.

The queue worker binds operational D1 databases and customer shards in ../voyage-bank/workers/queue/wrangler.toml:11.

The reporting worker binds operational D1 databases and customer shards in ../voyage-bank/workers/reporting/wrangler.toml:11.

The generated topology package lists the 10 operational regions in ../voyage-bank/packages/shard-routing/src/generated-topology.ts:15.

The generated topology package lists the 64 customer shard indices in ../voyage-bank/packages/shard-routing/src/generated-topology.ts:51.

The routing package resolves customer shard index by CRC32 modulo shard count in ../voyage-bank/packages/shard-routing/src/index.ts:55.

The routing package resolves operational region from an explicit branch map or CRC32 fallback in ../voyage-bank/packages/shard-routing/src/index.ts:58.

3.1 Branch Distribution

3.2 Branch Archetype Distribution

3.3 D1 Plane

3.4 ASCII Topology

                          Meridian National Bank tenant
                                      |
                                      v
                            CONFIG_DB / tenant config
                                      |
            +-------------------------+-------------------------+
            |                         |                         |
            v                         v                         v
   Branch topology seed       Staff and services          Simulation config
   380 canonical branches     role/service matrix         target horizon 14
            |                         |                         |
            +-------------------------+-------------------------+
                                      |
                                      v
                        Simulation generator and orchestrator
                                      |
            +-------------------------+-------------------------+
            |                                                   |
            v                                                   v
    10 regional ops D1 databases                       64 customer shards
            |                                                   |
            v                                                   v
 bookings, queue entries, service sessions             customer directory
 orders, events, registrations                         profile lookup
            |
            v
     reporting facts rollups
            |
            v
 branch_day, queue_day, service_day, staff_day

3.5 Regional Ops Bindings

3.6 Current Seed Footprint

The seed tree currently contains 173 files.

The seed tree is approximately 11 GB on disk.

The largest simulation SQL file is the Midwest regional seed at about 1.2 GB.

The full customer directory SQL file is about 1.2 GB.

The staff JSON file is about 168 MB.

The staff SQL file is about 146 MB.

The reporting-facts SQL file is about 43 MB.

Those sizes make the simulation operationally meaningful.

They also make D1 import behavior part of the architecture.

4. Service-Staff Skill Matrix

The simulation does not assign work to arbitrary staff.

It uses a role-service matrix.

The matrix is loaded in ../voyage-bank/scripts/backfill-day.ts:368.

The generator builds role entries and event entries in ../voyage-bank/scripts/backfill-day.ts:372.

The generator builds service-role eligibility in ../voyage-bank/scripts/backfill-day.ts:422.

The service-role factory document defines the canonical matrix in ../voyage-bank/docs/architecture/voyage-bank-factories/f34-service-role-matrix.md:13.

The checked-in tenant matrix is ../voyage-bank/config/tenant/service-role-matrix.json.

The validator enforces role eligibility through isEligible in ../voyage-bank/scripts/validate-seed-data.ts:484.

The validator reports booking skill-match pass status in ../voyage-bank/seed/validation-report.json:122.

The validator reports session skill-match pass status in ../voyage-bank/seed/validation-report.json:133.

The validator reports queue skill-match pass status in ../voyage-bank/seed/validation-report.json:144.

4.1 Matrix Summary

4.2 Role Rules

Tellers are the primary queue workers.

Tellers get high queue volume.

Tellers get very low appointment volume.

Personal bankers are appointment-heavy but still absorb some queue work.

Mortgage officers handle long appointments.

Mortgage officers can host homebuyer events.

Investment advisors can host investment and retirement events.

Business bankers can host small-business roundtables.

Branch managers handle escalations and limited appointments.

Regional vice presidents exist in the staff seed.

Regional vice presidents are not active branch-lane workers in the daily generator.

Metro directors exist in the staff seed.

Metro directors are not active branch-lane workers in the daily generator.

The staff seed summary reports 208,000 total staff.

The staff seed summary reports 87,330 tellers.

The staff seed summary reports 62,450 personal bankers.

The staff seed summary reports 30,970 mortgage officers.

The staff seed summary reports 23,370 investment advisors.

The staff seed summary reports 3,800 branch managers.

The staff seed summary reports 70 metro directors.

The staff seed summary reports 10 regional vice presidents.

Those counts come from ../voyage-bank/seed/staff/staff.json:208006.

4.3 Why the Matrix Matters

The matrix makes the demo resistant to superficial data.

A mortgage consultation is not assigned to a teller.

A teller queue is not staffed by a mortgage officer.

A retirement workshop is not hosted by unqualified frontline staff.

Queue routing has distinct teller and advisor lanes.

Event follow-up inherits the qualified-service constraint.

Reporting facts aggregate the resulting operational shape.

This is why the generated data looks like a bank.

The generator asks who can do the work before it creates the work.

The validator checks the generated result afterward.

The tests assert role-specific behavior before deployment.

5. Daily Generation Walkthrough

The daily generator lives in ../voyage-bank/scripts/backfill-day.ts.

It is the center of the simulation.

It takes a date range.

It takes a generation profile.

It takes optional region filters.

It reads branch topology.

It reads service definitions.

It reads staff rosters.

It reads the role-service matrix.

It generates SQL for each regional operational database.

It bulk-loads that SQL into D1.

It recomputes reporting facts.

It is deterministic.

It uses seed 42 in ../voyage-bank/scripts/backfill-day.ts:360.

It defines a total synthetic customer universe of 68,000,000 in ../voyage-bank/scripts/backfill-day.ts:361.

It uses the role-service matrix at ../voyage-bank/scripts/backfill-day.ts:368.

It maps queue type by role at ../voyage-bank/scripts/backfill-day.ts:380.

It defines teller and advisor queue behavior at ../voyage-bank/scripts/backfill-day.ts:387.

It builds service eligibility at ../voyage-bank/scripts/backfill-day.ts:422.

It defines service revenue at ../voyage-bank/scripts/backfill-day.ts:431.

It defines event targets by branch archetype at ../voyage-bank/scripts/backfill-day.ts:440.

5.1 Inputs

The generator consumes branch configuration.

The generator consumes service configuration.

The generator consumes staff configuration.

The generator consumes simulation configuration.

The generator consumes region topology.

The generator consumes date ranges.

The generator consumes generation profile names.

The generator consumes optional asOfDate.

The generator consumes D1 database metadata.

The generator consumes reporting database metadata.

5.2 Service Selection

The generator computes eligible staff service IDs in ../voyage-bank/scripts/backfill-day.ts:1180.

It intersects role matrix services with staff service IDs.

It checks service booking modes.

It avoids inventing work a staff member cannot perform.

It picks weighted services by branch archetype in ../voyage-bank/scripts/backfill-day.ts:1273.

It uses day patterns and branch profile to change the service mix.

It makes express branches behave differently from wealth centers.

It makes regional hubs behave differently from business centers.

5.3 Queue Definition

The generator builds queue definitions in ../voyage-bank/scripts/backfill-day.ts:1194.

It supports teller queues.

It supports advisor queues.

It records eligible service IDs per queue.

It records eligible staff IDs per queue.

It writes queue settings JSON.

It separates teller wait assumptions from advisor wait assumptions.

The queue type config sets teller wait minutes per person to 4 in ../voyage-bank/scripts/backfill-day.ts:387.

The queue type config sets advisor wait minutes per person to 12 in ../voyage-bank/scripts/backfill-day.ts:403.

The queue type config sets teller maximum active queue to 24.

The queue type config sets advisor maximum active queue to 10.

That creates different operational pressure by lane.

5.4 Appointment Candidates

The generator builds 30-minute appointment candidates in ../voyage-bank/scripts/backfill-day.ts:1308.

Appointments snap to :00 or :30.

That mirrors real branch scheduling.

Walk-in queue arrivals deliberately do not use the same grid.

The off-grid choice is documented in ../voyage-bank/scripts/backfill-day.ts:1694.

The tests assert appointment grid alignment in ../voyage-bank/scripts/__tests__/backfill-day.test.ts:712.

The tests assert off-grid walk-in arrivals in ../voyage-bank/scripts/__tests__/backfill-day.test.ts:721.

The validator reports 100 percent half-hour grid compliance for 78,625 checked bookings in ../voyage-bank/seed/validation-report.json:100.

5.5 Shift Blocks

The generator creates lunch blocks in ../voyage-bank/scripts/backfill-day.ts:1377.

Lunch can be 30, 45, or 60 minutes.

Lunch starts between 11:30 and 14:30.

The generator creates short breaks in ../voyage-bank/scripts/backfill-day.ts:1392.

Short breaks are 15 minutes.

Short breaks have a 50 percent probability.

The tests assert no appointment during lunch in ../voyage-bank/scripts/__tests__/backfill-day.test.ts:881.

The validator reports 0 booking overlap conflicts in ../voyage-bank/seed/validation-report.json:36.

The validator reports 0 session overlap conflicts in ../voyage-bank/seed/validation-report.json:47.

5.6 Event Calendar

The generator chooses event start windows in ../voyage-bank/scripts/backfill-day.ts:1412.

It avoids Monday morning.

It avoids Friday afternoon.

It snaps event start times to the 30-minute grid.

It generates weekly branch events in ../voyage-bank/scripts/backfill-day.ts:1441.

It chooses events by branch archetype.

It chooses hosts by event type.

It adds prep time.

It adds debrief time.

It creates registrations.

It applies show-up rates.

It records follow-up behavior.

The service-role matrix defines event prep and debrief in ../voyage-bank/docs/architecture/voyage-bank-factories/f34-service-role-matrix.md:100.

The tests assert event blocking against host appointments in ../voyage-bank/scripts/__tests__/backfill-day.test.ts:914.

The validation report shows event host overlap conflicts at 0 in ../voyage-bank/seed/validation-report.json:68.

5.7 Follow-Up Work

The generator collects event follow-ups in ../voyage-bank/scripts/backfill-day.ts:1538.

It assigns follow-ups to qualified staff in ../voyage-bank/scripts/backfill-day.ts:3463.

It uses event type and service eligibility.

It turns events into downstream appointment pressure.

That gives the simulation operational continuity.

An event is not just a calendar decoration.

It can create future work.

5.8 Duration Rules

The generator defines appointment duration by role in ../voyage-bank/scripts/backfill-day.ts:1593.

Mortgage work lasts 60 to 90 minutes.

Investment work can last 45 to 90 minutes.

Business work can last 45 to 90 minutes.

Personal banker work can last 30 to 60 minutes.

Branch manager work can last 30 to 60 minutes.

The generator defines walk-in duration in ../voyage-bank/scripts/backfill-day.ts:1615.

Teller walk-ins last 5 to 15 minutes.

Specialist walk-ins last 15 to 45 minutes.

The tests assert mortgage appointment duration in ../voyage-bank/scripts/__tests__/backfill-day.test.ts:573.

The validator reports 100 percent booking duration alignment in ../voyage-bank/seed/validation-report.json:89.

5.9 Demand Windows

The generator chooses time windows in ../voyage-bank/scripts/backfill-day.ts:1663.

Walk-ins weight morning and lunch.

Appointments weight the afternoon more heavily.

Events weight the afternoon most heavily.

The simulation config defines morning rush from 08:00 to 11:00 in ../voyage-bank/config/tenant/simulation.json:31.

The simulation config defines lunch spike from 11:30 to 13:30 in ../voyage-bank/config/tenant/simulation.json:40.

The simulation config defines advisor follow-up from 15:00 to 17:00 in ../voyage-bank/config/tenant/simulation.json:49.

That makes the time series legible to operators.

The generated day has a shape.

The generated day is not uniform noise.

5.10 Delete and Replace

The generator builds delete statements in ../voyage-bank/scripts/backfill-day.ts:3094.

It disables foreign keys before deletion.

It deletes child tables before parent tables.

It deletes order items.

It deletes orders.

It deletes event registrations.

It deletes tickets.

It deletes events.

It resets staff status.

It deletes service sessions.

It deletes bookings.

It deletes queue entries.

It re-enables foreign keys.

The tests assert delete-statement behavior in ../voyage-bank/scripts/__tests__/backfill-day.test.ts:373.

This makes backfill reruns idempotent.

5.11 Region-Day Batch

The generator starts each region-day batch in ../voyage-bank/scripts/backfill-day.ts:3110.

It computes active-minute context for current-day partial generation in ../voyage-bank/scripts/backfill-day.ts:3123.

It builds deterministic region/date/profile seed context in ../voyage-bank/scripts/backfill-day.ts:3131.

It creates batch arrays and stats in ../voyage-bank/scripts/backfill-day.ts:3136.

It builds a weekly event cache in ../voyage-bank/scripts/backfill-day.ts:3160.

It iterates sorted branches in ../voyage-bank/scripts/backfill-day.ts:3186.

It skips branches with empty duty rosters in ../voyage-bank/scripts/backfill-day.ts:3198.

It computes branch arrival pattern and scenario demand in ../voyage-bank/scripts/backfill-day.ts:3200.

It emits queue rows in ../voyage-bank/scripts/backfill-day.ts:3211.

It constructs staff timelines in ../voyage-bank/scripts/backfill-day.ts:3221.

5.12 Event Rows

The generator filters and sorts same-day events in ../voyage-bank/scripts/backfill-day.ts:3247.

It creates event rows in ../voyage-bank/scripts/backfill-day.ts:3256.

It creates ticket rows.

It creates host service sessions.

It creates registration rows.

It creates attendee service sessions.

It creates event satisfaction payloads.

The validation report shows event validity at 100 percent in ../voyage-bank/seed/validation-report.json:265.

The validation report shows event registration resolution at 100 percent in ../voyage-bank/seed/validation-report.json:276.

The validation report shows event capacity exceeded count at 0 in ../voyage-bank/seed/validation-report.json:287.

The validation report shows event session alignment at 100 percent in ../voyage-bank/seed/validation-report.json:298.

5.13 Staff Loop

The generator enters the per-staff loop in ../voyage-bank/scripts/backfill-day.ts:3480.

It resolves the role entry.

It creates deterministic staff RNG.

It applies lunch blocks.

It applies short-break blocks.

It computes eligible appointment service IDs.

It computes eligible queue service IDs.

It computes appointment targets.

It computes queue targets.

It caps teller appointments.

The teller cap is visible in ../voyage-bank/scripts/backfill-day.ts:3517.

The tests assert teller workload in ../voyage-bank/scripts/__tests__/backfill-day.test.ts:543.

The tests assert personal banker workload in ../voyage-bank/scripts/__tests__/backfill-day.test.ts:607.

The tests assert mortgage officer workload in ../voyage-bank/scripts/__tests__/backfill-day.test.ts:573.

5.14 Appointment Materialization

The generator creates appointments in ../voyage-bank/scripts/backfill-day.ts:3544.

It chooses an appointment window.

It chooses an eligible service.

It chooses duration.

It finds an available block.

It assigns status.

It assigns a customer.

It creates optional order revenue.

It creates a booking row.

It creates a service session row.

The validator checks appointment-source reconciliation in ../voyage-bank/scripts/validate-seed-data.ts:1475.

The validation report shows appointment sessions resolve to bookings at 100 percent in ../voyage-bank/seed/validation-report.json:78.

5.15 Walk-In Planning

The generator plans walk-ins in ../voyage-bank/scripts/backfill-day.ts:3697.

It chooses a walk-in window.

It chooses a service.

It chooses duration.

It finds an available service block.

It assigns source as kiosk, staff, or QR.

Walk-ins do not create bookings.

Walk-ins do create queue entries.

Walk-ins do create service sessions when served.

Walk-ins can abandon.

The validation report reports abandonment at 5.92 percent in ../voyage-bank/seed/validation-report.json:254.

5.16 Queue Materialization

The generator initializes queue state in ../voyage-bank/scripts/backfill-day.ts:3745.

It materializes planned walk-ins in ../voyage-bank/scripts/backfill-day.ts:3758.

It computes queue depth.

It computes estimated wait.

It chooses off-grid joined minutes.

It assigns queue position.

It creates queue entries.

It creates service sessions for served walk-ins.

It creates optional order revenue.

The validator checks queue timestamp monotonicity in ../voyage-bank/seed/validation-report.json:210.

The validator checks queue waits in ../voyage-bank/seed/validation-report.json:221.

The validator checks queue-session alignment in ../voyage-bank/seed/validation-report.json:232.

The validator checks off-grid arrivals in ../voyage-bank/seed/validation-report.json:243.

5.17 Scenario Metadata

The generator applies branch operational events in ../voyage-bank/scripts/backfill-day.ts:3918.

It applies scenario metadata in ../voyage-bank/scripts/backfill-day.ts:3937.

It applies session satisfaction scores.

It applies event satisfaction rollups.

The validation report shows scenario labels valid in ../voyage-bank/seed/validation-report.json:354.

The validation report shows scenario mix deviation at 0 in ../voyage-bank/seed/validation-report.json:366.

The validation report shows mean satisfaction 4.17 in ../voyage-bank/seed/validation-report.json:331.

The validation report shows positive/negative scenario satisfaction separation in ../voyage-bank/seed/validation-report.json:342.

5.18 SQL Rendering

The generator builds insert column arrays in ../voyage-bank/scripts/backfill-day.ts:3961.

It sets INSERT_CHUNK_SIZE to 50 in ../voyage-bank/scripts/backfill-day.ts:4030.

It renders column-less insert statements in ../voyage-bank/scripts/backfill-day.ts:4040.

It builds insert statements in dependency order in ../voyage-bank/scripts/backfill-day.ts:4060.

It writes the generated SQL file in ../voyage-bank/scripts/backfill-day.ts:4077.

The reality roadmap states that column-less INSERT VALUES bypassed a D1 parser issue in ../voyage-bank/docs/reality-roadmap.md:58.

The chunk size matters because D1 import behavior is part of the performance envelope.

5.19 D1 Bulk Load

The generator bulk-loads files with Wrangler in ../voyage-bank/scripts/backfill-day.ts:4081.

It executes wrangler d1 execute.

It uses --remote.

It uses --file.

It uses --yes.

It retries transient D1_RESET_DO errors.

It retries long-running import errors.

It retries too-many-requests errors.

The retry logic is visible in ../voyage-bank/scripts/backfill-day.ts:4088.

The reality roadmap documents the D1 retry behavior in ../voyage-bank/docs/reality-roadmap.md:61.

5.20 Reporting Facts

The generator recomputes reporting facts in ../voyage-bank/scripts/backfill-day.ts:4112.

It initializes branch-day accumulators in ../voyage-bank/scripts/backfill-day.ts:4128.

It queries service sessions by region database in ../voyage-bank/scripts/backfill-day.ts:4143.

It accumulates branch-day metrics in ../voyage-bank/scripts/backfill-day.ts:4170.

It accumulates service-day metrics in ../voyage-bank/scripts/backfill-day.ts:4196.

It accumulates staff-day metrics in ../voyage-bank/scripts/backfill-day.ts:4204.

It accumulates revenue from orders in ../voyage-bank/scripts/backfill-day.ts:4235.

It accumulates events in ../voyage-bank/scripts/backfill-day.ts:4255.

It accumulates queue entries in ../voyage-bank/scripts/backfill-day.ts:4281.

It deletes prior fact rows in ../voyage-bank/scripts/backfill-day.ts:4333.

It creates fact rows in ../voyage-bank/scripts/backfill-day.ts:4357.

It inserts branch, queue, service, and staff facts in ../voyage-bank/scripts/backfill-day.ts:4461.

It bulk-loads reporting facts in ../voyage-bank/scripts/backfill-day.ts:4474.

The verification report counts fact_branch_day rows in ../voyage-bank/seed/verification-report.json:25.

The verification report counts fact_queue_day rows in ../voyage-bank/seed/verification-report.json:26.

The verification report counts fact_service_day rows in ../voyage-bank/seed/verification-report.json:27.

The verification report counts fact_staff_day rows in ../voyage-bank/seed/verification-report.json:28.

6. Role-Lane Workload

The role-lane factory is documented in ../voyage-bank/docs/architecture/voyage-bank-factories/f35-role-lane-generator.md.

The role-lane model is summarized in ../voyage-bank/docs/architecture/voyage-bank-factories/f35-role-lane-generator.md:18.

Appointments are generated from role targets in ../voyage-bank/docs/architecture/voyage-bank-factories/f35-role-lane-generator.md:32.

Queue interactions are generated from arrival distributions in ../voyage-bank/docs/architecture/voyage-bank-factories/f35-role-lane-generator.md:42.

Breaks are modeled in ../voyage-bank/docs/architecture/voyage-bank-factories/f35-role-lane-generator.md:51.

Appointment time alignment is required in ../voyage-bank/docs/architecture/voyage-bank-factories/f35-role-lane-generator.md:57.

Duty roster sizing is described in ../voyage-bank/docs/architecture/voyage-bank-factories/f35-role-lane-generator.md:61.

Weekly events are described in ../voyage-bank/docs/architecture/voyage-bank-factories/f35-role-lane-generator.md:73.

Event follow-up is described in ../voyage-bank/docs/architecture/voyage-bank-factories/f35-role-lane-generator.md:86.

Event impact is described in ../voyage-bank/docs/architecture/voyage-bank-factories/f35-role-lane-generator.md:93.

6.1 Daily Role-Lane Table

6.2 Workload Interpretation

Tellers create the queue density.

Personal bankers create mixed appointment and queue density.

Mortgage officers create long-duration appointment pressure.

Investment advisors create long-duration appointment pressure plus event pressure.

Business bankers create service-specific branch demand.

Branch managers create escalation capacity.

Regional vice presidents create management hierarchy realism.

The generator uses the same matrix to decide who can receive work.

The validator uses staff service IDs to confirm the generated rows.

The tests verify specific role lanes.

The teller test starts at ../voyage-bank/scripts/__tests__/backfill-day.test.ts:543.

The mortgage-officer test starts at ../voyage-bank/scripts/__tests__/backfill-day.test.ts:573.

The personal-banker test starts at ../voyage-bank/scripts/__tests__/backfill-day.test.ts:607.

The event-generation test starts at ../voyage-bank/scripts/__tests__/backfill-day.test.ts:637.

The event-host load test starts at ../voyage-bank/scripts/__tests__/backfill-day.test.ts:669.

The service-role matrix enforcement tests start at ../voyage-bank/scripts/__tests__/backfill-day.test.ts:1085.

7. Queue and Appointment Balance

Queue and appointment balance is where the simulation becomes operational.

A branch day has scheduled appointments.

A branch day has walk-in arrivals.

A branch day has teller queues.

A branch day has advisor queues.

A branch day has abandonment.

A branch day has service sessions.

A branch day has orders and revenue.

A branch day has satisfaction.

The simulation config defines target sessions per branch day at ../voyage-bank/config/tenant/simulation.json:4.

The simulation config defines banking hours at ../voyage-bank/config/tenant/simulation.json:5.

The simulation config defines weekday demand patterns at ../voyage-bank/config/tenant/simulation.json:31.

The generator uses walk-in, event, and appointment window weights in ../voyage-bank/scripts/backfill-day.ts:1663.

7.1 Time-of-Day Shape

7.2 Archetype Arrival Rates

7.3 Queue Ratios

Teller queues are short-service, high-throughput lanes.

Advisor queues are longer-service, lower-throughput lanes.

The teller wait model uses 4 minutes per person in ../voyage-bank/scripts/backfill-day.ts:387.

The advisor wait model uses 12 minutes per person in ../voyage-bank/scripts/backfill-day.ts:403.

The teller active-queue maximum is 24.

The advisor active-queue maximum is 10.

The tests verify teller and advisor queue definitions in ../voyage-bank/scripts/__tests__/backfill-day.test.ts:749.

The tests verify queue routing and positions in ../voyage-bank/scripts/__tests__/backfill-day.test.ts:790.

The tests verify teller waits are shorter than advisor waits in ../voyage-bank/scripts/__tests__/backfill-day.test.ts:849.

7.4 Appointment Balance

Appointments occupy staff timelines.

Walk-ins occupy staff timelines.

Events occupy staff timelines.

Breaks occupy staff timelines.

The scheduler must find available blocks.

The scheduler must not place appointments over lunch.

The scheduler must not place appointments over event host blocks.

The scheduler must not place two bookings on the same staff member at the same time.

The validation report shows booking overlap conflicts at 0.

The validation report shows session overlap conflicts at 0.

The validation report shows event-host conflicts at 0.

Those results are in ../voyage-bank/seed/validation-report.json:36, ../voyage-bank/seed/validation-report.json:47, and ../voyage-bank/seed/validation-report.json:68.

8. Forward Generation

Forward generation extends the simulated bank into future dates.

The target horizon is 14 days.

The minimum healthy horizon is 7 days.

Those values are in ../voyage-bank/docs/simulation-forward-generation-runbook.md:5.

The same values are configured in ../voyage-bank/config/tenant/simulation.json:10.

The configured forward-generation cron is 5 0 * * *.

That value is in ../voyage-bank/config/tenant/simulation.json:11.

The runbook calls the scheduler workers/simulation-orchestrator.

That appears in ../voyage-bank/docs/simulation-forward-generation-runbook.md:8.

The runbook describes future-safe states.

Bookings are generated as scheduled.

Service sessions are generated as scheduled.

Queue entries are generated as waiting.

Those future-safe states appear in ../voyage-bank/docs/simulation-forward-generation-runbook.md:14.

8.1 Current Cron Reality

There are two cron concepts in the codebase.

The first concept is the live simulation tick.

The live tick computes action load over a 3-minute interval.

That computation is visible in ../voyage-bank/workers/simulation-orchestrator/src/index.ts:464.

The second concept is forward horizon fill.

Forward horizon fill is configured as a daily cron.

That configuration is visible in ../voyage-bank/config/tenant/simulation.json:11.

The current orchestrator Wrangler file disables scheduled triggers.

The disabled trigger block is in ../voyage-bank/workers/simulation-orchestrator/wrangler.toml:78.

The same block says to restore the tick and daily forward-fill crons when re-enabling.

The historical battle-plan document says the simulator cron was */3 * * * *.

That historical note is in ../voyage-bank/docs/battle-plan.md:56.

The current checked-in deployment config is more conservative.

It has crons = [].

This briefing treats the 3-minute cadence as the live-tick design.

This briefing treats the 14-day horizon as the forward-fill target.

This briefing treats the daily forward-fill cron and disabled Wrangler schedule as the current source of truth.

8.2 Orchestrator State

The orchestrator defines simulation_forward_generation_state in ../voyage-bank/workers/simulation-orchestrator/src/index.ts:20.

The state has target days ahead.

The state has minimum days ahead.

The state has horizon date.

The state has run status.

The state has failure fields.

The state is initialized or updated from config in ../voyage-bank/workers/simulation-orchestrator/src/index.ts:366.

The orchestrator loads configured regions from state in ../voyage-bank/workers/simulation-orchestrator/src/index.ts:606.

The orchestrator resolves the next target date in ../voyage-bank/workers/simulation-orchestrator/src/index.ts:627.

The monitor writes healthy, warning, or stale status in ../voyage-bank/workers/simulation-orchestrator/src/index.ts:646.

The run path starts at ../voyage-bank/workers/simulation-orchestrator/src/index.ts:733.

The run path skips if the horizon is already healthy.

The run path loops region by region.

The run path calls rebuildRegionDate.

The run path records failures.

The run path only advances horizon on full success.

That matters for partial-day reconciliation.

If one region fails, the core state must not pretend all regions are complete.

8.3 Runbook Findings

The runbook reports that the horizon was extended through 2026-04-28 across all 10 simulation regions.

That appears in ../voyage-bank/docs/simulation-forward-generation-runbook.md:13.

The runbook reports the scheduled Worker entrypoint does fire.

That appears in ../voyage-bank/docs/simulation-forward-generation-runbook.md:18.

The runbook also reports that live scheduled testing against remote D1 does not reliably complete a full multi-region load today.

That appears in ../voyage-bank/docs/simulation-forward-generation-runbook.md:19.

Observed failures include D1 long-running import and D1_RESET_DO.

Those failures appear in ../voyage-bank/docs/simulation-forward-generation-runbook.md:23.

The runbook concludes that the Worker cron is suitable for monitoring and status.

It concludes that it should not be the sole writer for full forward-day generation across all regions yet.

That conclusion appears in ../voyage-bank/docs/simulation-forward-generation-runbook.md:34.

The runbook recommends queue-based sharding or pre-generation outside the Worker.

That recommendation appears in ../voyage-bank/docs/simulation-forward-generation-runbook.md:118.

8.4 Manual Extension

The runbook lists one-region-at-a-time manual extension commands in ../voyage-bank/docs/simulation-forward-generation-runbook.md:39.

The current scripts/forward-fill.ts CLI exposes --date, --date-from, --date-to, --days-ahead, --as-of-date, --profile, and --region.

Those options are defined in ../voyage-bank/scripts/forward-fill.ts:373.

Use the current CLI flags when operating from HEAD.

The runbook command examples use older --start and --end names.

That discrepancy is an operational paper cut.

It belongs in the gaps section.

9. Reality Constraints

The simulation is credible because it is constrained.

It is not a random row factory.

It enforces temporal constraints.

It enforces skill constraints.

It enforces business-hour constraints.

It enforces appointment-grid constraints.

It enforces queue timestamp constraints.

It enforces workload constraints.

It enforces event-capacity constraints.

It enforces satisfaction coverage.

9.1 Appointment Grid

Appointments are generated on 30-minute edges.

The generator builds candidates in ../voyage-bank/scripts/backfill-day.ts:1308.

The generator documents appointment snapping in ../voyage-bank/scripts/backfill-day.ts:1694.

The tests assert 30-minute appointment boundaries in ../voyage-bank/scripts/__tests__/backfill-day.test.ts:712.

The validation report shows 100 percent half-hour grid compliance in ../voyage-bank/seed/validation-report.json:100.

9.2 Walk-In Off-Grid Arrivals

Walk-in arrivals are intentionally not all at :00 or :30.

The generator avoids grid minutes for joined timestamps in ../voyage-bank/scripts/backfill-day.ts:1694.

The tests assert off-grid walk-in arrivals in ../voyage-bank/scripts/__tests__/backfill-day.test.ts:721.

The validation report shows 100 percent queue off-grid arrivals in ../voyage-bank/seed/validation-report.json:243.

9.3 Business Hours

Banking hours are configured in ../voyage-bank/config/tenant/simulation.json:5.

The validation report shows 100 percent booking business-hours compliance in ../voyage-bank/seed/validation-report.json:111.

The generator clamps current-day active minute to banking hours in ../voyage-bank/scripts/backfill-day.ts:3123.

9.4 No Double-Booking

The generator uses staff timelines.

It records blocked intervals.

It finds available blocks before creating work.

It records event prep and debrief as unavailable time.

It records lunch as unavailable time.

The validator counts booking overlaps.

The validator counts session overlaps.

The validator counts event-host appointment overlaps.

The validation report shows 0 booking overlap conflicts in ../voyage-bank/seed/validation-report.json:36.

The validation report shows 0 session overlap conflicts in ../voyage-bank/seed/validation-report.json:47.

The validation report shows 0 event-host overlap conflicts in ../voyage-bank/seed/validation-report.json:68.

9.5 Role Eligibility

Role eligibility starts in the matrix.

Role eligibility is applied in the generator.

Role eligibility is checked in validation.

The generator builds eligibility in ../voyage-bank/scripts/backfill-day.ts:422.

The validator checks eligibility in ../voyage-bank/scripts/validate-seed-data.ts:484.

The validation report shows 100 percent booking skill match in ../voyage-bank/seed/validation-report.json:122.

The validation report shows 100 percent session skill match in ../voyage-bank/seed/validation-report.json:133.

The validation report shows 100 percent queue skill match in ../voyage-bank/seed/validation-report.json:144.

The validation report shows 100 percent event host skill match in ../voyage-bank/seed/validation-report.json:155.

9.6 Shift Patterns

The generator creates lunch blocks.

The generator creates short breaks.

The role-lane factory requires realistic rosters.

Weekday roster sizing is 60 to 80 percent.

Saturday roster sizing is 30 to 50 percent.

Sunday is closed.

That design is documented in ../voyage-bank/docs/architecture/voyage-bank-factories/f35-role-lane-generator.md:61.

The tests assert weekday and Saturday roster behavior in ../voyage-bank/scripts/__tests__/backfill-day.test.ts:953.

The validation report shows shift alignment violations at 0.03 percent in ../voyage-bank/seed/validation-report.json:199.

9.7 Capacity Rules

The validator uses role-aware session caps in ../voyage-bank/scripts/validate-seed-data.ts:468.

The validation report shows workload cap pass status in ../voyage-bank/seed/validation-report.json:166.

The validation report shows high utilization is rare at 0.01 percent of staff-days in ../voyage-bank/seed/validation-report.json:188.

This matters because a demo branch should look busy without looking impossible.

9.8 Queue Quality

Queue timestamps must be monotonic.

Queue waits must be bounded.

Queue service sessions must align with queue entries.

Queue arrivals should be off-grid.

The validation report shows queue timestamp monotonicity at 100 percent in ../voyage-bank/seed/validation-report.json:210.

The validation report shows queue waits valid at 100 percent in ../voyage-bank/seed/validation-report.json:221.

The validation report shows queue session alignment at 100 percent in ../voyage-bank/seed/validation-report.json:232.

The validation report shows queue off-grid arrivals at 100 percent in ../voyage-bank/seed/validation-report.json:243.

10. Scale Performance

The performance story is grounded in checked-in runbook numbers.

The historical backfill completed all 10 regional operations shards.

That result is documented in ../voyage-bank/docs/reality-roadmap.md:52.

The generated operations data includes 1,696,932 sessions.

The generated operations data includes 702,912 bookings.

The generated operations data includes 926,566 queue entries.

Those numbers appear in ../voyage-bank/docs/reality-roadmap.md:52.

The reporting layer includes 668,000-plus fact rows.

That number appears in ../voyage-bank/docs/reality-roadmap.md:53.

The seed verification report gives the precise fact count as 668,400.

That precise count appears in ../voyage-bank/seed/verification-report.json:27.

10.1 50x Speedup

The reality roadmap reports a 50x speedup.

The source is ../voyage-bank/docs/reality-roadmap.md:57.

The speedup came from wrangler d1 execute --file.

The generator uses file-based D1 execution in ../voyage-bank/scripts/backfill-day.ts:4081.

The generator writes SQL files before bulk load in ../voyage-bank/scripts/backfill-day.ts:4077.

The generator chunks inserts at 50 rows per statement in ../voyage-bank/scripts/backfill-day.ts:4030.

The generator uses column-less INSERT VALUES in ../voyage-bank/scripts/backfill-day.ts:4040.

The reality roadmap cites column-less INSERT VALUES as a D1 parser workaround in ../voyage-bank/docs/reality-roadmap.md:58.

10.2 Ten-Minute Gap Fill

The reality roadmap reports an Apr 6-7 gap fill across 10 regions plus reporting facts.

The reported runtime is 10 minutes and 10 seconds.

The source is ../voyage-bank/docs/reality-roadmap.md:64.

This is the best checked-in runtime number for generation throughput.

This briefing does not invent newer runtime claims.

10.3 Retry Behavior

The generator retries transient D1 errors.

The retry list includes D1_RESET_DO.

The retry list includes long-running import.

The retry list includes too many requests.

The retry logic is in ../voyage-bank/scripts/backfill-day.ts:4088.

The reality roadmap documents the retry behavior in ../voyage-bank/docs/reality-roadmap.md:61.

The forward-generation runbook shows why this matters.

It records D1 long-running import and D1_RESET_DO failures in ../voyage-bank/docs/simulation-forward-generation-runbook.md:23.

10.4 Reporting Facts

Reporting facts are not a side note.

They make executive and operational views fast.

The generator recomputes branch-day facts.

The generator recomputes queue-day facts.

The generator recomputes service-day facts.

The generator recomputes staff-day facts.

The fact tables are inserted in ../voyage-bank/scripts/backfill-day.ts:4461.

The seed verification report counts 114,000 branch-day facts.

The seed verification report counts 114,000 queue-day facts.

The seed verification report counts 410,400 service-day facts.

The seed verification report counts 30,000 staff-day facts.

Those counts appear in ../voyage-bank/seed/verification-report.json:25.

11. Verification

The simulation has three verification layers.

The first layer is unit tests.

The second layer is seed verification.

The third layer is seed validation.

11.1 Unit Tests

The test file is ../voyage-bank/scripts/__tests__/backfill-day.test.ts.

It includes 48 test cases by current static scan.

The reality roadmap reports 42 tests passing in ../voyage-bank/docs/reality-roadmap.md:63.

The discrepancy likely reflects test growth after that roadmap entry.

This briefing cites the runbook number only as a historical performance claim.

The test suite covers date enumeration.

The test suite covers request date and timezone behavior.

The test suite covers satisfaction scoring.

The test suite covers delete-statement safety.

The test suite covers deterministic output.

The test suite covers teller workload.

The test suite covers mortgage workload.

The test suite covers personal banker workload.

The test suite covers weekly event generation.

The test suite covers event host load reduction.

The test suite covers appointment grid alignment.

The test suite covers walk-in off-grid arrivals.

The test suite covers queue definition.

The test suite covers queue routing.

The test suite covers wait-time differences.

The test suite covers lunch blocks.

The test suite covers event host blocking.

The test suite covers roster sizing.

The test suite covers overload and reassignment.

The test suite covers service-role matrix enforcement.

The test suite covers scenario assignment.

The test suite covers deterministic scenario hashing.

11.2 Local Test Command Note

A direct root-level command was attempted for this briefing:

pnpm exec vitest run scripts/__tests__/backfill-day.test.ts --reporter=dot

That command failed because vitest was not available from the root workspace command path.

The failure was Command "vitest" not found.

This briefing therefore does not claim a fresh local test pass.

It cites checked-in test files and checked-in runbook outputs.

11.3 Seed Verification

The seed verifier is ../voyage-bank/seed/verify-seed.ts.

It writes verification-report.json in ../voyage-bank/seed/verify-seed.ts:31.

It sets WINDOW_DAYS to 30 in ../voyage-bank/seed/verify-seed.ts:32.

It sets expected branches to 380 in ../voyage-bank/seed/verify-seed.ts:33.

It sets the customer spread threshold in ../voyage-bank/seed/verify-seed.ts:34.

It sets the ops spread threshold in ../voyage-bank/seed/verify-seed.ts:35.

It streams SQL insert rows in ../voyage-bank/seed/verify-seed.ts:92.

It identifies customer shard files in ../voyage-bank/seed/verify-seed.ts:120.

It identifies ops seed files in ../voyage-bank/seed/verify-seed.ts:127.

It computes fact counts and major table counts in ../voyage-bank/seed/verify-seed.ts:142.

It checks expected branch and queue fact counts in ../voyage-bank/seed/verify-seed.ts:159.

It emits shard balance warnings in ../voyage-bank/seed/verify-seed.ts:171.

It writes the report in ../voyage-bank/seed/verify-seed.ts:179.

11.4 Verification Report

The verification report was generated at 2026-04-06T12:03:21.689Z.

That timestamp appears in ../voyage-bank/seed/verification-report.json:2.

It scanned 80 files.

That appears in ../voyage-bank/seed/verification-report.json:3.

It reports 1,696,932 service sessions.

That appears in ../voyage-bank/seed/verification-report.json:31.

It reports 702,912 bookings.

That appears in ../voyage-bank/seed/verification-report.json:14.

It reports 926,566 queue entries.

That appears in ../voyage-bank/seed/verification-report.json:29.

It reports 500,000 customer rows across shards.

That appears in ../voyage-bank/seed/verification-report.json:38.

It reports 64 customer shards.

That appears in ../voyage-bank/seed/verification-report.json:37.

It reports balanced customer shards.

That appears in ../voyage-bank/seed/verification-report.json:43.

It reports 10 operational shards.

That appears in ../voyage-bank/seed/verification-report.json:306.

It reports ops shard distribution as not balanced.

That appears in ../voyage-bank/seed/verification-report.json:312.

11.5 Seed Validation

The seed validator is ../voyage-bank/scripts/validate-seed-data.ts.

It imports seed loaders and SQL streaming parsers in ../voyage-bank/scripts/validate-seed-data.ts:1.

It defines aggregate stats in ../voyage-bank/scripts/validate-seed-data.ts:109.

It parses schema files in ../voyage-bank/scripts/validate-seed-data.ts:231.

It defines scenario tolerance in ../voyage-bank/scripts/validate-seed-data.ts:245.

It counts overlaps in ../voyage-bank/scripts/validate-seed-data.ts:352.

It defines role-aware session caps in ../voyage-bank/scripts/validate-seed-data.ts:468.

It checks eligibility in ../voyage-bank/scripts/validate-seed-data.ts:484.

It loads staff index and schedules in ../voyage-bank/scripts/validate-seed-data.ts:790.

It streams ops seed rows in ../voyage-bank/scripts/validate-seed-data.ts:974.

It checks booking invariants in ../voyage-bank/scripts/validate-seed-data.ts:996.

It checks queue invariants in ../voyage-bank/scripts/validate-seed-data.ts:1033.

It checks service-session invariants in ../voyage-bank/scripts/validate-seed-data.ts:1160.

It counts conflict totals in ../voyage-bank/scripts/validate-seed-data.ts:1299.

It checks schema constraints in ../voyage-bank/scripts/validate-seed-data.ts:1350.

It defines invariant report rows in ../voyage-bank/scripts/validate-seed-data.ts:1475.

It writes and logs the report in ../voyage-bank/scripts/validate-seed-data.ts:1813.

11.6 Validation Report

The validation report was generated at 2026-04-13T14:23:18.574Z.

That timestamp appears in ../voyage-bank/seed/validation-report.json:2.

It scanned 1 file.

That scope appears in ../voyage-bank/seed/validation-report.json:3.

It reports 33 total checks.

It reports 33 passing checks.

It reports 0 warnings.

It reports 0 failures.

Those overview values appear in ../voyage-bank/seed/validation-report.json:4.

It validates 1,589,054 rows for schema table coverage.

That appears in ../voyage-bank/seed/validation-report.json:12.

It validates 1,589,054 rows for schema constraints.

That appears in ../voyage-bank/seed/validation-report.json:24.

It checks 78,625 bookings for overlap.

That appears in ../voyage-bank/seed/validation-report.json:36.

It checks 337,355 sessions for overlap.

That appears in ../voyage-bank/seed/validation-report.json:47.

It checks 257,729 queue entries for queue timing.

That appears in ../voyage-bank/seed/validation-report.json:210.

It reports abandonment at 5.92 percent.

That appears in ../voyage-bank/seed/validation-report.json:254.

It reports satisfaction coverage at 100 percent.

That appears in ../voyage-bank/seed/validation-report.json:309.

It reports mean satisfaction at 4.17.

That appears in ../voyage-bank/seed/validation-report.json:331.

12. Gaps

The simulation is strong.

It is not finished.

The gaps matter because they are specific.

They are not reasons to dismiss the simulation.

They are the next engineering frontiers.

12.1 Forward Generation Autonomy

The runbook says the scheduled Worker entrypoint fires.

The runbook also says remote D1 does not reliably complete full multi-region forward generation.

The current Wrangler schedule is disabled.

The safe path is manual extension or queue-sharded generation.

This is the largest operational gap.

The current implementation proves the data model.

It does not yet prove fully autonomous, all-region, always-on forward fill from the Worker.

12.2 Cron Documentation Drift

The historical battle plan mentions a 3-minute cron.

The live tick math still uses a 3-minute interval.

The simulation config uses a daily forward-fill cron.

The current Wrangler file disables scheduled triggers.

This should be reconciled before presenting the system as fully cron-driven.

12.3 CLI Documentation Drift

The forward-generation runbook uses --start and --end.

The current CLI exposes --date-from and --date-to.

The operator path should be updated.

12.4 Customer Directory Warning

The verification report warns that customer directory rows do not match customer profile rows.

That warning appears in ../voyage-bank/seed/verification-report.json:1084.

This is probably an artifact of how directory files and profile files are counted.

It still deserves cleanup before investor-facing claims about customer population.

12.5 Ops Shard Balance Warning

The verification report marks customer shards balanced.

It marks operational shards not balanced.

The ops spread warning appears in ../voyage-bank/seed/verification-report.json:1086.

Some imbalance is expected because regions have different branch counts.

The report threshold should distinguish natural regional load from unhealthy shard skew.

12.6 Satisfaction Depth

The validator proves satisfaction coverage.

It proves scenario separation.

It does not prove deeply causal customer sentiment.

Future realism can link satisfaction to wait deltas, repeat visits, service type, and staff load more explicitly.

12.7 Reassignment Depth

The tests cover overload and reassignment paths.

The current generated seed still appears primarily deterministic and precomputed.

Future live simulation can make overload reassignment more event-driven.

12.8 Abandonment Depth

The validation report shows abandonment at 5.92 percent.

Future realism can make abandonment depend more directly on queue depth, service type, branch archetype, customer history, and time of day.

12.9 Executive Role Activity

Regional vice presidents and metro directors exist in the staff hierarchy.

They are not active daily branch-lane workers.

Future simulation could add executive review workflows, exception queues, and regional intervention events.

12.10 Verification Scope

The current validation report scanned 1 file.

The seed verification report scanned 80 files.

Both are useful.

They answer different questions.

The next verification improvement is an all-region validation report with the same invariant depth as the current single-file report.

13. Why This Matters to a Buyer

Most demos show a happy path.

Meridian shows an operating model.

A buyer can inspect branches.

A buyer can inspect regions.

A buyer can inspect queues.

A buyer can inspect bookings.

A buyer can inspect staff.

A buyer can inspect services.

A buyer can inspect rollups.

A buyer can inspect failure handling.

A buyer can see the architecture under load.

The platform does not need fake screenshots.

It has data.

The platform does not need manually curated anecdotes.

It has patterns.

The platform does not need a live customer integration to show bank-scale behavior.

It has a generated tenant with real constraints.

That is rare because realistic simulation is usually treated as disposable.

Here it is part of the product proof.

It validates the data model.

It validates the shard model.

It validates reporting.

It validates role-based scheduling.

It validates queue behavior.

It validates operational observability.

It gives engineers a regression surface.

It gives sales teams a credible demo surface.

It gives investors a way to see scale without waiting for a production migration.

14. Appendix - Running the Simulator

This appendix is operational.

It assumes the working directory is ../voyage-bank.

It assumes Cloudflare credentials are already present in the shell or local env files.

It does not push.

It does not commit.

It does not create external-system artifacts.

14.1 Environment

cd ../voyage-bank
export CLOUDFLARE_ACCOUNT_ID=1c4242a5ff4262714297ce7b929c0bf8
export CLOUDFLARE_API_TOKEN="${CLOUDFLARE_API_TOKEN}"

The account ID default is documented in the repository operating instructions.

Cloudflare token values must not be committed.

14.2 Verify Seed Counts

pnpm tsx seed/verify-seed.ts

Expected output path:

seed/verification-report.json

The verifier writes that path from ../voyage-bank/seed/verify-seed.ts:31.

14.3 Validate One Ops Seed

pnpm tsx scripts/validate-seed-data.ts --sql-file seed/simulation/ops-seed-v2-northeast.sql

Use this when validating invariant depth on a regional seed file.

The current validation report scope was one file.

14.4 Forward-Fill One Region

pnpm tsx scripts/forward-fill.ts --date-from 2026-04-16 --date-to 2026-04-28 --region northeast

Repeat per region:

pnpm tsx scripts/forward-fill.ts --date-from 2026-04-16 --date-to 2026-04-28 --region mid_atlantic
pnpm tsx scripts/forward-fill.ts --date-from 2026-04-16 --date-to 2026-04-28 --region southeast
pnpm tsx scripts/forward-fill.ts --date-from 2026-04-16 --date-to 2026-04-28 --region florida
pnpm tsx scripts/forward-fill.ts --date-from 2026-04-16 --date-to 2026-04-28 --region midwest
pnpm tsx scripts/forward-fill.ts --date-from 2026-04-16 --date-to 2026-04-28 --region texas
pnpm tsx scripts/forward-fill.ts --date-from 2026-04-16 --date-to 2026-04-28 --region mountain
pnpm tsx scripts/forward-fill.ts --date-from 2026-04-16 --date-to 2026-04-28 --region norcal
pnpm tsx scripts/forward-fill.ts --date-from 2026-04-16 --date-to 2026-04-28 --region socal
pnpm tsx scripts/forward-fill.ts --date-from 2026-04-16 --date-to 2026-04-28 --region pacific_northwest

The CLI flags are defined in ../voyage-bank/scripts/forward-fill.ts:373.

14.5 Verify Forward Fill

pnpm tsx scripts/verify-forward-fill.ts --date 2026-04-28 --region northeast

The forward verification script counts bookings.

It counts queue entries.

It counts events.

It counts registrations.

It counts scheduled states.

Those checks are visible in ../voyage-bank/scripts/verify-forward-fill.ts:125.

14.6 Query Forward State

npx wrangler d1 execute mnb-sim-core \
  --remote \
  --command "SELECT id, horizon_date, target_days_ahead, minimum_days_ahead, last_status, last_run_started_at, last_run_finished_at, last_error FROM simulation_forward_generation_state WHERE id = 'mnb-default';"

The runbook includes this status query in ../voyage-bank/docs/simulation-forward-generation-runbook.md:93.

14.7 Expected Healthy State

Target days ahead should be 14.

Minimum days ahead should be 7.

The horizon should be at least the expected date for the run.

The last status should be healthy.

The runbook defines the expected healthy state in ../voyage-bank/docs/simulation-forward-generation-runbook.md:108.

14.8 Deploy Orchestrator

npx wrangler deploy --config workers/simulation-orchestrator/wrangler.toml

Deploy only with the approved personal Cloudflare account.

Do not assume scheduled triggers are active after deploy.

The current Wrangler file has crons = [].

That source is ../voyage-bank/workers/simulation-orchestrator/wrangler.toml:82.

14.9 Rebuild Reporting Facts

The backfill generator recomputes reporting facts after regional loads.

The recompute function starts in ../voyage-bank/scripts/backfill-day.ts:4112.

If reporting facts look stale, rerun the backfill or forward-fill path that triggers recomputation.

Do not manually patch reporting tables unless debugging.

14.10 Golden Outputs

Current verified scale:

service_sessions: 1,696,932
bookings: 702,912
queue_entries: 926,566
fact_branch_day: 114,000
fact_queue_day: 114,000
fact_service_day: 410,400
fact_staff_day: 30,000
customer_shards: 64
customer_rows: 500,000

The exact counts come from ../voyage-bank/seed/verification-report.json:13.

Appendix A - Source Evidence Ledger

Appendix B - Region Operating Cards

B001 Northeast

Region key: northeast.

Canonical branch count: 38.

Ops binding: OPS_NORTHEAST_DB.

Ops database: mnb-ops-current-northeast.

Branch-count source: ../voyage-bank/seed/branches/branches.json:12.

Binding source: ../voyage-bank/workers/simulation-orchestrator/wrangler.toml:20.

Forward-fill command:

pnpm tsx scripts/forward-fill.ts --date-from 2026-04-16 --date-to 2026-04-28 --region northeast

B002 Mid-Atlantic

Region key: mid_atlantic.

Canonical branch count: 43.

Ops binding: OPS_MID_ATLANTIC_DB.

Ops database: mnb-ops-current-mid-atlantic.

Branch-count source: ../voyage-bank/seed/branches/branches.json:16.

Binding source: ../voyage-bank/workers/simulation-orchestrator/wrangler.toml:25.

Forward-fill command:

pnpm tsx scripts/forward-fill.ts --date-from 2026-04-16 --date-to 2026-04-28 --region mid_atlantic

B003 Southeast

Region key: southeast.

Canonical branch count: 43.

Ops binding: OPS_SOUTHEAST_DB.

Ops database: mnb-ops-current-southeast.

Branch-count source: ../voyage-bank/seed/branches/branches.json:20.

Binding source: ../voyage-bank/workers/simulation-orchestrator/wrangler.toml:30.

Forward-fill command:

pnpm tsx scripts/forward-fill.ts --date-from 2026-04-16 --date-to 2026-04-28 --region southeast

B004 Florida

Region key: florida.

Canonical branch count: 32.

Ops binding: OPS_FLORIDA_DB.

Ops database: mnb-ops-current-florida.

Branch-count source: ../voyage-bank/seed/branches/branches.json:24.

Binding source: ../voyage-bank/workers/simulation-orchestrator/wrangler.toml:35.

Forward-fill command:

pnpm tsx scripts/forward-fill.ts --date-from 2026-04-16 --date-to 2026-04-28 --region florida

B005 Midwest

Region key: midwest.

Canonical branch count: 55.

Ops binding: OPS_MIDWEST_DB.

Ops database: mnb-ops-current-midwest.

Branch-count source: ../voyage-bank/seed/branches/branches.json:28.

Binding source: ../voyage-bank/workers/simulation-orchestrator/wrangler.toml:40.

Forward-fill command:

pnpm tsx scripts/forward-fill.ts --date-from 2026-04-16 --date-to 2026-04-28 --region midwest

B006 Texas

Region key: texas.

Canonical branch count: 36.

Ops binding: OPS_TEXAS_DB.

Ops database: mnb-ops-current-texas.

Branch-count source: ../voyage-bank/seed/branches/branches.json:32.

Binding source: ../voyage-bank/workers/simulation-orchestrator/wrangler.toml:45.

Forward-fill command:

pnpm tsx scripts/forward-fill.ts --date-from 2026-04-16 --date-to 2026-04-28 --region texas

B007 Mountain

Region key: mountain.

Canonical branch count: 27.

Ops binding: OPS_MOUNTAIN_DB.

Ops database: mnb-ops-current-mountain.

Branch-count source: ../voyage-bank/seed/branches/branches.json:36.

Binding source: ../voyage-bank/workers/simulation-orchestrator/wrangler.toml:50.

Forward-fill command:

pnpm tsx scripts/forward-fill.ts --date-from 2026-04-16 --date-to 2026-04-28 --region mountain

B008 Northern California

Region key: norcal.

Canonical branch count: 33.

Ops binding: OPS_NORCAL_DB.

Ops database: mnb-ops-current-norcal.

Branch-count source: ../voyage-bank/seed/branches/branches.json:40.

Binding source: ../voyage-bank/workers/simulation-orchestrator/wrangler.toml:55.

Forward-fill command:

pnpm tsx scripts/forward-fill.ts --date-from 2026-04-16 --date-to 2026-04-28 --region norcal

B009 Southern California

Region key: socal.

Canonical branch count: 44.

Ops binding: OPS_SOCAL_DB.

Ops database: mnb-ops-current-socal.

Branch-count source: ../voyage-bank/seed/branches/branches.json:44.

Binding source: ../voyage-bank/workers/simulation-orchestrator/wrangler.toml:60.

Forward-fill command:

pnpm tsx scripts/forward-fill.ts --date-from 2026-04-16 --date-to 2026-04-28 --region socal

B010 Pacific Northwest

Region key: pacific_northwest.

Canonical branch count: 29.

Ops binding: OPS_PNW_DB.

Ops database: mnb-ops-current-pnw.

Branch-count source: ../voyage-bank/seed/branches/branches.json:48.

Binding source: ../voyage-bank/workers/simulation-orchestrator/wrangler.toml:65.

Forward-fill command:

pnpm tsx scripts/forward-fill.ts --date-from 2026-04-16 --date-to 2026-04-28 --region pacific_northwest

Appendix C - Validation Checklist

• C001 Confirm branch count is 380 from ../voyage-bank/seed/branches/branches.json:6.
• C002 Confirm region count is 10 from ../voyage-bank/seed/branches/branches.json:9.
• C003 Confirm customer shard count is 64 from ../voyage-bank/seed/verification-report.json:37.
• C004 Confirm service session count is 1,696,932 from ../voyage-bank/seed/verification-report.json:31.
• C005 Confirm booking count is 702,912 from ../voyage-bank/seed/verification-report.json:14.
• C006 Confirm queue entry count is 926,566 from ../voyage-bank/seed/verification-report.json:29.
• C007 Confirm reporting fact count is 668,400 from ../voyage-bank/seed/verification-report.json:27.
• C008 Confirm booking overlaps are 0 from ../voyage-bank/seed/validation-report.json:36.
• C009 Confirm session overlaps are 0 from ../voyage-bank/seed/validation-report.json:47.
• C010 Confirm event host overlaps are 0 from ../voyage-bank/seed/validation-report.json:68.
• C011 Confirm appointment sessions resolve to bookings from ../voyage-bank/seed/validation-report.json:78.
• C012 Confirm booking duration alignment from ../voyage-bank/seed/validation-report.json:89.
• C013 Confirm booking half-hour grid alignment from ../voyage-bank/seed/validation-report.json:100.
• C014 Confirm booking business-hour alignment from ../voyage-bank/seed/validation-report.json:111.
• C015 Confirm booking skill match from ../voyage-bank/seed/validation-report.json:122.
• C016 Confirm session skill match from ../voyage-bank/seed/validation-report.json:133.
• C017 Confirm queue skill match from ../voyage-bank/seed/validation-report.json:144.
• C018 Confirm event host skill match from ../voyage-bank/seed/validation-report.json:155.
• C019 Confirm workload caps from ../voyage-bank/seed/validation-report.json:166.
• C020 Confirm high utilization rarity from ../voyage-bank/seed/validation-report.json:188.
• C021 Confirm shift alignment from ../voyage-bank/seed/validation-report.json:199.
• C022 Confirm queue timestamp monotonicity from ../voyage-bank/seed/validation-report.json:210.
• C023 Confirm queue wait validity from ../voyage-bank/seed/validation-report.json:221.
• C024 Confirm queue-session alignment from ../voyage-bank/seed/validation-report.json:232.
• C025 Confirm off-grid queue arrivals from ../voyage-bank/seed/validation-report.json:243.
• C026 Confirm abandonment from ../voyage-bank/seed/validation-report.json:254.
• C027 Confirm event validity from ../voyage-bank/seed/validation-report.json:265.
• C028 Confirm event registration resolution from ../voyage-bank/seed/validation-report.json:276.
• C029 Confirm event capacity from ../voyage-bank/seed/validation-report.json:287.
• C030 Confirm event session alignment from ../voyage-bank/seed/validation-report.json:298.
• C031 Confirm satisfaction coverage from ../voyage-bank/seed/validation-report.json:309.
• C032 Confirm mean satisfaction from ../voyage-bank/seed/validation-report.json:331.
• C033 Confirm scenario gap from ../voyage-bank/seed/validation-report.json:342.
• C034 Confirm scenario labels from ../voyage-bank/seed/validation-report.json:354.
• C035 Confirm scenario mix from ../voyage-bank/seed/validation-report.json:366.

Appendix D - Investor Readout Points

• D001 The simulation has enough records to expose real database behavior.
• D002 The simulation has enough branches to expose regional operations behavior.
• D003 The simulation has enough staff to expose scheduling behavior.
• D004 The simulation has enough queue rows to expose wait-time behavior.
• D005 The simulation has enough bookings to expose appointment behavior.
• D006 The simulation has enough fact rows to expose reporting behavior.
• D007 The simulation uses deterministic generation, so demos are repeatable.
• D008 The simulation uses role eligibility, so demos are credible.
• D009 The simulation uses D1 sharding, so demos exercise Cloudflare-native architecture.
• D010 The simulation uses validation reports, so claims are auditable.
• D011 The simulation has known gaps, so roadmap discussion is concrete.
• D012 The simulation already found operational constraints around D1 imports.
• D013 The simulation turns pre-sales demos into system tests.
• D014 The simulation turns engineering tests into investor proof.
• D015 The simulation lowers dependence on live tenant data.
• D016 The simulation protects privacy because no real bank customers are needed.
• D017 The simulation supports branch-level demos.
• D018 The simulation supports regional rollup demos.
• D019 The simulation supports queue management demos.
• D020 The simulation supports appointment management demos.
• D021 The simulation supports staffing demos.
• D022 The simulation supports event and follow-up demos.
• D023 The simulation supports reporting demos.
• D024 The simulation supports failure-mode demos.
• D025 The simulation supports scale conversations with concrete numbers.

Appendix E - Engineering Readout Points

• E001 The generator is deterministic.
• E002 The generator is idempotent.
• E003 The generator is shard-aware.
• E004 The generator uses D1 file imports.
• E005 The generator chunks insert statements.
• E006 The generator recomputes rollups.
• E007 The generator validates constraints after generation.
• E008 The generator separates queue and appointment semantics.
• E009 The generator separates teller and advisor queue models.
• E010 The generator enforces service-role eligibility.
• E011 The generator models lunch and breaks.
• E012 The generator models event prep and debrief.
• E013 The generator models event registration.
• E014 The generator models event follow-up.
• E015 The generator models abandoned queue entries.
• E016 The generator models orders and revenue.
• E017 The generator models satisfaction.
• E018 The generator models branch scenarios.
• E019 The generator models reporting facts.
• E020 The generator has direct tests.
• E021 The seed has a verification report.
• E022 The seed has a validation report.
• E023 The forward-fill path has a runbook.
• E024 The orchestrator has state tables.
• E025 The orchestrator records failed forward runs.

Appendix F - Current-State Caveats

• F001 Do not say the current deployed Wrangler schedule runs every 3 minutes.
• F002 The current Wrangler file disables crons.
• F003 The live tick design uses 3-minute math.
• F004 The historical battle plan mentions a 3-minute cron.
• F005 The forward-fill config uses a daily cron.
• F006 The forward horizon target is 14 days.
• F007 The runbook says Worker cron is not the sole safe writer yet.
• F008 Manual region-by-region forward fill remains the safe operating mode.
• F009 The runbook command flags need updating to current CLI names.
• F010 The verification report contains customer-directory and ops-spread warnings.

Appendix G - Pinned Commits

• voyage: 14f3b190db8817399dcd30e1dc4e1ae7674bbf8a
• voyage-bank: ef4d7d4f9a66a05d68c265debc681d506a0606c6