Database

Why GREATEST at all: Hazelcast guarantees delivery, not order, so a message reporting iteration 4 can arrive after one reporting iteration 5, and both are true statements about the past. Taking the maximum makes the four columns immune to that reordering — the stored value is the furthest the device is known to have got, and no arrival order can walk it backwards.

serial, state and state_reason are not monotonic — a device legitimately goes SENT, then ERROR, then WAN_CHECK, and there is no "greater" state — so the only correct merge for them is newest-wins, decided by observed_at with >= rather than >: two messages can carry the same observation instant, and the later arrival is then at least as informed as the stored one. observed_at itself takes the maximum, so a reordered older message updates the counters it can only raise and leaves both the state and the watermark alone.

=== fcc_audit

Who did what to a campaign — an append-only trail, never updated and never deleted.

The four audit columns every table already carries answer "when was this row last touched and by whom"; they do not answer "who stopped this campaign on the 14th", because an update overwrites its predecessor. A compliance campaign disturbs subscriber lines and its results end up in a regulatory filing, so the lifecycle actions have to be a trail of their own. And because the product has no role model, this row is the only accountability there is — see No Authentication by Design.

Index: fcc_audit(entity_type, entity_id, created) is built for the read behind the history tab of a test, WHERE entity_type = ? AND entity_id = ? ORDER BY created DESC — but FccAuditRepository declares no query method at all today, and nothing else reads fcc_audit either. The index anticipates a read that does not exist yet; that is a defensible thing to have done, since the append-only rule and the column shapes already have to be right before a reader can be built on top of them, but it means the index is currently unexercised rather than serving anything. created is the third column so that, once a reader is added, the sort is answered from the index instead of a filesort over a trail that only grows. The leading entity_type is what lets the same index serve the M3 entity types without a second one.

==== Three Entity Types, One Action Vocabulary

FccAuditService gained an overload in M3 (record(entityType, action, entityId, domainId, userId, details)); the original five-argument method is now a thin delegate that passes AUDIT_ENTITY_TYPE_TEST.

action stays the closed FccAuditActionEnum while entity_type is a set of String constants, and the split is deliberate: CREATE / UPDATE / DELETE mean the same thing on all three entities, so per-entity constants such as MODEL_CAPABILITY_UPDATE would make the trail impossible to read across them — "what changed on the 14th" would become three queries instead of one — for exactly no gain.

The null domain_id on MODEL_CAPABILITY is a statement, not a gap. The change belongs to no domain — the table is installation-global ([fcc-model-capability]) — and recording the actor’s own domain would suggest the change was scoped to it, which is precisely the misreading the X-FT-Domain-Scope: ALL requirement exists to prevent.

Both new paths write in the same transaction as the change they describe, enforced by Propagation.MANDATORY exactly as the campaign paths are.

=== fcc_result_dead_letter

The last resort for a measurement that could not be stored.

A measurement is the product of a compliance campaign: the ACS disturbed a subscriber line to produce it and it may end up in a regulatory filing, so it must never be silently lost. Through M1 the only place a result could live between arriving on the Hazelcast queue and reaching ClickHouse was an in-memory buffer, and exhausting that buffer — or restarting the service while it was full — destroyed the rows. This table is where they go instead; it replaces both TODO(M2) drop paths and the shutdown drop.

Index: fcc_result_dead_letter(state, created) serves the only reader, WHERE state = 'PENDING' AND reason <> 'LATE' ORDER BY created, id. The state prefix is what keeps the read proportional to the backlog rather than to the whole table, since RESENT and DISCARDED rows are kept forever and never removed by the service.

=== fcc_model_capability

What one CPE model can be asked to do, as far as this installation has been told. At most one row per model.

Installation-global, not per-domain. There is no domain_id column, because a connection ceiling is a property of the hardware: the same model behaves the same way in every domain. That is also why the admin write path requires X-FT-Domain-Scope: ALL — a row here constrains every operator of the installation, and this product has no role model that could express "installation administrator" any other way (The Two Administration Tables Are Not Authorized the Same Way).

Index: fcc_model_capability(model_id) UNIQUE. It enforces one row per model in the database rather than only in the admin service — the PUT is an upsert keyed on model_id, and two rows for one model would make the ceiling that is applied depend on which one the read happened to return first. It also serves the only two reads there are: WHERE model_id = ? (the admin details screen) and WHERE model_id IN (…​) (FccModelCapabilityProvider, which resolves the whole model set of a catalog page or of a resolved fleet in one statement, chunked at 1000 for Oracle).

Oracle additionally gets a FCC_MODEL_CAPABILITY_0 sequence, the same convention every other table of this schema uses.

=== fcc_domain_setting

The middle level of the three-level settings chain — see [settings-resolution-chain] for what the chain does and when it runs. At most one row per domain.

The per-domain level exists for multi-ISP installations: one deployment serves several ISPs, each is a domain, and each has its own test servers. A single global URL is wrong for all but one of them, while making every operator retype the same two URLs into every campaign is how they end up mistyped.

Every field is nullable, and a null is indistinguishable from the absence of the row: both mean "this domain publishes no opinion on this value". FccDomainSettingResolver.forDomain returns an Optional and FccTestService.chain treats an empty one and a null field identically, on purpose — a caller that had to tell them apart would be encoding a distinction that has no meaning.

Index: fcc_domain_setting(domain_id) UNIQUE, enforced in the database and not only in the admin service. The PUT is an upsert keyed on domain_id, and two rows for one domain would make the URL a campaign is frozen with depend on which row the read happened to return first — the exact silent divergence the save-time freeze exists to prevent. It serves the read that runs on every save of every test (WHERE domain_id = ?, FccDomainSettingResolver) and the scoped admin list (WHERE domain_id IN (…​), the caller’s visible domains).

Oracle additionally gets a FCC_DOMAIN_SETTING_0 sequence.

=== fcc_legacy_import

The cursor and the progress of the legacy ETL, which reads the FCC results the ACS wrote before this service existed and replays them into ClickHouse — see Legacy FCC Import for what the import reconstructs and why.

Exactly two rows, one per result_kind, and that is the whole cardinality of the table. The two legacy sources are imported by independent cursors because they are not the same shape: ug_fcc_speed_result carries end_date, type and the bom/eom counters, and ug_fcc_latency_result has none of those and carries the round-trip aggregates instead. A single shared cursor would have to be the union of both column sets — and, worse, a stall on one kind (an unreadable row, a ClickHouse outage on one table) would hold the other kind’s import hostage. Two rows let one kind sit FAILED while the other keeps making progress, and let an operator restart one of them alone.

Index: fcc_legacy_import(result_kind) UNIQUE — the two-rows-only rule enforced in the database and not only in the service. Every access is "the row for this kind": the ETL loads it by kind at start, updates it by kind after each batch, and /status reads both. A second row for one kind would hand a resuming import a stale cursor and re-import a range that was already written, which on ClickHouse cannot be undone. The unique index is also what makes the get-or-create at startup safe under two processes racing to begin the same import. Oracle additionally gets a FCC_LEGACY_IMPORT_0 sequence, the same convention every other table of this schema uses.

M4 also adds one index to the existing fcc_test, in changelog_add_fcc_test_legacy_ug_index.xml so the table changelog keeps its checksums: fcc_test(legacy_ug_id, type) UNIQUE, the key the import finds its own anchor campaign by — see One Update Group Can Become Two Anchors for why the type column is in it.

Four of the columns above — watermark_started_before, pending_ug_id, rows_late_skipped and rows_invalid — arrived with the M4 review, in changelog_add_fcc_legacy_import_watermark.xml and not in changelog_create_fcc_legacy_import.xml, for the same reason: that file has already run at every installation and its changesets have to keep their checksums. Each changeset is guarded by a not columnExists precondition with onFail="MARK_RAN", so an installation that already carries the column records the changeset as run rather than failing on it.

==== Why the Cursor Is Composite and Not a Last-Id

Rows are read in the order

because that is exactly the order the per-group iteration rank is defined over: iteration numbers the measurements of one (window, serial, direction) group in the order they were taken, and the truncation to the second is what makes rows written within the same second rank deterministically instead of by insertion accident.

A plain "resume after id N" cursor cannot express a position in that order — ids are not monotonic along it — so a batch that ended in the middle of a group could not resume the group’s ranking. Hence the five position columns, plus cursor_iteration, which carries the running rank of the group the cursor currently sits in: a group split across a batch boundary continues at iteration N+1 on the next batch instead of restarting at 1 and producing two measurements that both claim to be the first.

cursor_result_id on its own therefore says nothing about how far the import has got. Only the tuple does.

Two rules the tuple has to obey, both of which the M4 review found broken:

==== Why pending_from_id / pending_result_id / pending_ug_id Exist

ClickHouse MergeTree has no unique constraint and no upsert: a row inserted twice stays in the table twice, forever, and there is no statement that can remove it. In a regulatory report that is not a cosmetic defect — it silently inflates the sample.

So the id range of a batch is written here and committed before the ClickHouse insert is attempted, and cleared to null only after the insert is acknowledged. A non-null pending_result_id found at startup therefore means the previous run died inside exactly that window and the batch’s fate is unknown; the recovery re-checks that bounded id range against ClickHouse — and only that range — before re-importing it, instead of having to reconcile the whole import.

The range is MIN..MAX of the batch and not first..last, because the traversal order above is deliberately not id order and the ids of one batch are scattered.

pending_ug_id ties the range to the campaign it was read for, and the recovery set is offered to that campaign and to no other. A run that died in the first batch of a campaign committed no cursor for it, so the stored cursor still names the previous campaign — which has nothing left to skip. Without the column the recovery set is handed to that previous campaign and cleared there, and the batch that genuinely is in doubt is re-imported into a table with no unique constraint. For the same crash, a non-null pending_result_id makes the row resumable on its own, with no cursor behind it: a fresh claim would otherwise erase the only record of which ids are in doubt before the probe could read it.

FccLegacyImportDao is hand-written JDBC and no method on it is transactional, which is what this contract rests on: each statement runs on autocommit, so the pending marker is durable the instant the call returns. Wrapping the import in a transaction would defer every cursor commit to the end of a run that may take hours and lose all of them to the crash they exist to survive. The counters are written as column = column + ? for the same reason — a commit adds what the batch actually did rather than overwriting the row with a stale absolute.

==== Why the Watermark Is a Date, and Why watermark_result_id Is Only a Diagnostic

A pass needs a completeness mark separately from the cursor at all because the cursor columns cannot answer the question: they name a position in a traversal order that is deliberately not id order, so a position in it says nothing about which rows are complete. The cursor resumes an interrupted pass; the watermark is what makes a new pass cheap and non-duplicating — without one a second run would re-read every row, and on a MergeTree with no unique constraint the duplicates could never be removed.

watermark_started_before is that mark. A pass covers start_date >= watermark_started_before AND start_date < cutoff, and on completion sets watermark_started_before = cutoff. The mark and the inclusion predicate are the same column, so the intervals of successive passes tile the timeline with no gap and no overlap; completeness is true by construction rather than by argument. It is a local wall clock because the legacy column it is compared against is one, and nullable because a kind that has never completed a pass has no lower bound — null reads as "start from the beginning".

watermark_result_id is kept, and is now only a diagnostic high-water mark. It records the highest legacy id any completed pass has covered, it bounds no read, and its one remaining use is the late-arrival predicate: a row matching start_date < watermark_started_before AND id > watermark_result_id reached ftacs after its day-window had already been imported, and is counted as rows_late_skipped rather than back-filled into a closed and already ranked window (Late Arrivals Are Counted). It only ever moves up: a later pass covers a later date interval whose highest id is not necessarily higher, and letting the mark fall would over-report rows_late_skipped.

The comment inside changelog_create_fcc_legacy_import.xml that calls it the completeness mark describes the superseded design, and says so in place.

== The Settings Resolution Chain

FccTestService.chain is the one implementation, and resolveConfigDefaults / resolveSpeedDefaults / resolveLatencyDefaults are its three callers.

=== Which Fields Have Which Levels

Not every field has all three, and the gaps are deliberate.

testMode is not a chain at all: it is FILE_BASED when absent, full stop.

=== Blank Text Is Absent, Not a Value

chain and chainText differ in exactly one respect, and it is not cosmetic.

chainText treats a blank string as absent. A form that posts "urlDl": "" for a field the operator left empty is the normal shape of an FT UI request, and a strict first-non-null chain would let that empty string beat the domain default — so the per-domain URL would never apply for exactly the caller it exists for, and the campaign would fail validateRunnable later with no indication that a default was available.

Blank is also what validateRunnable already reads as missing, so this keeps the two halves agreeing on what "absent" means.

And "absent" is stored as NULL, never as "". Having decided that a blank is not a value, returning one would write an empty string into a nullable column whose entire vocabulary for "no value" is IS NULL — and every report, every migration and every hand-written query over fcc_test_setting_speed.url_dl would then have to know about a second spelling of nothing. So when neither the request nor the domain has anything, the result is null.

=== It Runs Once, at Save Time, and Never at Activation

This is the whole point of the design and the easiest thing to get wrong.

A campaign with reactivation_days = 7 runs for a week and is activated daily. If the chain were walked on each activation, an administrator who changed a global or per-domain URL on day three would silently make days 1-3 and days 4-7 measure different servers — and nothing in the report would show it: the test row, the activation snapshots and the measurements would all look internally consistent, each describing the configuration that was in force when it was written.

A regulatory filing has to state one set of parameters for the whole campaign. So FccTestService freezes the resolved values into fcc_test_config / fcc_test_setting_speed / fcc_test_setting_latency when the user saves, and each activation additionally snapshots them into fcc_activation ([fcc-activation-snapshot]).

The consequences, stated plainly because they are what an operator will ask about:

=== There Is No Walk Up the Domain Tree, and There Cannot Honestly Be One

FccDomainSettingResolver.forDomain is an exact domain_id match. A domain with no row of its own does not inherit its parent’s; it falls straight through to the global default.

That is a deliberate limitation rather than an omission, and it is not a limitation this service can lift by trying harder. Two independent facts stand in the way:

And a guess is the wrong kind of wrong here: a wrongly inherited URL is a campaign that measures the wrong server while looking perfectly configured. It produces numbers, they go into a report, and nothing anywhere says which host they came from.

An installation that wants one URL for a subtree writes a row per domain of that subtree. That is more rows, and they are rows somebody can read.

== The fcc_activation Settings Snapshot

The 32-column block on fcc_activation (test_type, test_mode, wan_sample_mode, threshold_dl/ul, tier_dl/ul, url_dl/ul, connections_dl/ul, file_size_ul, time_based_duration_sec, time_based_interval_sec, ping_host, ping_repetitions, ping_timeout_ms, ping_data_block_size, total_duration_h, single_duration_min, batch_interval_min, retry_failed, retry_wan, wan_sample_gap_sec, wan_retry_interval_sec, wan_step_timeout_sec, diag_timeout_sec, speed_success_percent, latency_success_ms, only_online, push, hubb_id — 28 names above, four of which are the dl/ul pairs counted as one each, for 32 columns in the table itself) duplicates fcc_test_config / fcc_test_setting_speed on purpose.

The test is editable; the run is not. A regulatory report has to show the parameters the ACS actually applied at the time a run happened, not the ones somebody typed into the test afterwards. Reading the settings back off fcc_test at report time would silently rewrite history every time an operator edits a test.

The consequence: editing a test’s settings takes effect only from the next reactivation. FccTestService.resolveConfigDefaults / resolveSpeedDefaults / resolveLatencyDefaults resolve absent values once, at save time — never at activation time — and since M3 they walk the full three-level chain (request, then fcc_domain_setting, then FT Configs) rather than only the global one: see [settings-resolution-chain]. A test with reactivationDays=7 runs for a week and is activated daily; if the defaults were re-read on every activation, an administrator changing a global or per-domain default mid-run would silently make days 1-3 and days 4-7 measure different things. The defaults are frozen into the test when the user saves it, and each activation additionally snapshots them into fcc_activation — two freezes, for two different reasons (the test freeze protects against a default drifting between two runs of one campaign; the activation freeze protects the report against a later edit of the test).

The ping_* and latency_success_ms columns were created in M1, before any latency campaign could exist, precisely so the M2 latency milestone became a code change and not an ALTER TABLE on a table that by then held live activations. They are in use since M2.

=== The Snapshot Is Type-Driven, and the Other Half Is Written NULL

FccActivationMapper.applySnapshot switches on fcc_test_config.type — the CONFIGURATION’s type and not the campaign’s, which no longer exists: a SPEED configuration’s activation gets the fcc_test_setting_speed columns, a LATENCY one gets the fcc_test_setting_latency ones. The half that does not belong to the type is written null, explicitly, rather than left as it was.

This row is what a regulatory report renders, and a leftover URL next to a ping result is a report stating parameters the run never used. Leaving the other half alone would do exactly that on the two paths that re-snapshot an existing row: a test whose type was changed between two runs, and FccActivationHandler.dispatch, which re-takes the snapshot of a row that was planned under the previous type. For a LATENCY run the upload columns (threshold_ul, tier_ul) stay null as well — a ping is symmetric and the contract states FccWanThresholdsDto.ulKbps / FccTiersDto.ulKbps are null for a latency test — and so do test_mode and wan_sample_mode, which describe how a throughput measurement is taken and have no meaning for a ping.

=== A Planned Reactivation Re-Takes Its Snapshot at Dispatch

FccActivationHandler.planReactivation writes a provisional snapshot when it creates tomorrow’s run as PLANNED, so that a planned row is a complete, readable run rather than a stub the UI has to special-case. FccActivationHandler.dispatch then re-takes the snapshot from the current fcc_test_config / fcc_test_setting_* rows at the moment the run is actually sent.

That re-take is what implements the product rule stated above: the run already on the ACS keeps the configuration its command carried — a republish re-sends the stored fcc_acs_outbox.payload and never re-runs the mapper — while the next one picks up whatever the operator changed in the meantime. Snapshotting once at planning time instead would freeze a configuration hours or days before it is used, and an operator who fixed a wrong URL would watch the wrong one run anyway.

command_seq is the one column planReactivation deliberately leaves unset, storing the placeholder 0 until dispatch assigns the real sequence in the same transaction as the outbox row. The sequence is consumed by the command, not by the activation row: the ACS discards a command whose sequence is not greater than the last one it accepted, so a reactivation planned today and sent tomorrow would otherwise burn a sequence now and make every command written in between look stale. activation_count is not bumped by planReactivation either — it counts the activations an operator asked for, which is what freezes the device set after the first one, and a reactivation the service planned by itself is not a new decision by anybody.

== The iotw Grant: Two Tables, SELECT Only

configs[].sourceType=Condition names a saved view of the portal’s device list, and that data lives in `ui-backend’s own schema. This service reads two tables there and nothing else:

Four properties of this grant are worth stating, because each is a decision rather than a default:

== ClickHouse Schema

=== fcc_result_speed

One row per speed diagnostic iteration and direction, in the shared database ftacs_qoe_ui_data (QoE already owns diag_speed_test and diag_ip_ping there — hence the fcc_ prefix and the separate Flyway history, see [flyway-history]).

Engine: MergeTree, PARTITION BY toDate(created), ORDER BY (fcc_test_id, serial, direction, created), TTL created + INTERVAL 400 DAY.

LowCardinality is applied only to the string columns that have a small, repeating value set: serial, status, source, direction, hubb_id. It is deliberately not applied to tier_kbps: that column is numeric, and wrapping a number in LowCardinality buys nothing while adding a dictionary per part.

The column list is treated as final for M1: everything the M4 legacy ETL will need was added now, on purpose, because an ALTER TABLE …​ ADD COLUMN over tens of millions of rows while the ETL is running is exactly the operation this design avoids discovering it needs later.

The natural de-duplication key is (activation_id, serial, direction, iteration). It is not enforced by MergeTree (no unique constraint exists in ClickHouse), so readers — and FccResultIngestService, implemented and code-read, via one atomic Hazelcast IMap.putIfAbsent per result, see De-Duplication Is One Atomic putIfAbsent — de-duplicate on it themselves.

=== fcc_result_latency

One row per latency (IPPing) diagnostic iteration, created by the Flyway migration V2create-fcc-result-latency-table.sql in the same shared database ftacs_qoe_ui_data, with two columns added by V3add-ping-actuals-to-fcc-result-latency.sql under contract 1.5 — see [contract-1-5-ping-actuals].

A second table rather than more Nullable columns on fcc_result_speed: the two diagnostics share nothing below the common block, a MergeTree part would carry a dictionary and a null map for every column the other diagnostic owns, and the ORDER BY that serves a speed report is not the one that serves a latency report.

The first twenty columns are therefore exactly those of fcc_result_speed, with the same provenance and the same fallbacks (FccResultIngestService.toLatencyRow fills them from the same helpers toSpeedRow uses). Two of them read oddly for a ping and are kept anyway:

The columns that are the latency half — five from V2, plus the two V3 adds for contract 1.5:

Engine, partitioning, ordering and TTL are the same as fcc_result_speed: MergeTree, PARTITION BY toDate(created), ORDER BY (fcc_test_id, serial, direction, created), TTL created + INTERVAL 400 DAY, index_granularity = 8192. The LowCardinality rule of [lowcardinality-rule] applies unchanged, and the natural de-duplication key is again (activation_id, serial, direction, iteration), again unenforced. The same TTL caveat applies — see the warning under [fcc-result-speed].

status is computed by this service, from ping_ok = avg_ms < latencySuccessMs && success_count > 0, and stored in the same SUCCESS \| FAILED \| CROSS_TALK \| OTHER dictionary the speed table uses. The ACS publishes raw measurements only and never a verdict. See The Pass/Fail Formula for the resolution order, and in particular for why success_count == 0 is FAILED and not OTHER.

The column list was treated as final for the M4 legacy ETL for the same reason fcc_result_speed’s is: everything that ETL will need (`legacy_ug_id, legacy_result_id, source) was created up front, because an ALTER TABLE …​ ADD COLUMN over tens of millions of rows while the ETL is running is exactly the operation this design avoids discovering it needs later. Contract 1.5’s repetitions / data_block_size ([contract-1-5-ping-actuals]) are the one exception, and are not a reversal of that rule: they are Nullable with no DEFAULT, so the ADD COLUMN that created them was metadata-only, not the rewrite the rule above was written to avoid. The ETL columns are still not to be extended casually; a Nullable addition with no default is the narrow exception this migration relied on, not a precedent for widening the table freely.

=== The Report Read Path

FccResultQueryDao is the read side of this schema, behind the four M4 reporting endpoints (Endpoints Implemented in M4). It never runs ahead of the write side: every column it selects is one fcc_result_speed / fcc_result_latency already carries, and every predicate it builds comes from the one FccResultFilter all four endpoints resolve through FccReportScopeResolver — which is what stops the run list, the measurement list, the report header and the export from ever disagreeing about which rows a filter means.

==== The UNION ALL Is Generated, Never Hand-Written Twice

ClickHouse matches a UNION ALL by position, not by name — the hard rule [fcc-result-latency] already states for the common block. The read side takes that one step further: the two branches of every cross-diagnostic query are not two pieces of SQL, they are two renderings of one Java list (FccResultQueryDao.COLUMNS), and every column is CAST to the same type on both sides. A column the branch does not own becomes CAST(NULL AS <the same type>) at the same position, which is what makes the two renderings union-compatible by construction rather than by review.

That is also why connections, speed_kbps, packets_sent and packets_received are projected Nullable in a report row although [fcc-result-speed] and [fcc-result-latency] declare them non-Nullable in their own tables: a speed row has nothing to offer packets_sent, and the honest way to say so in a positional union is NULL, not a fabricated 0 a reader could mistake for a real count.

==== The Period Predicate Is Two Predicates

Both tables are PARTITION BY toDate(created) while a report filters on started_at — the instant the device measured, not the instant the row was written. The two differ by the ACS batching, or, for a row the legacy ETL imports, by years. Narrowing on created instead of started_at would therefore silently drop measurements; narrowing on started_at alone forces ClickHouse to read every partition, because the engine has no way to relate the two columns to each other.

The read adds a second, widened predicate on created beside the one on started_at — one day either side of the requested window (FccResultQueryDao.PARTITION_MARGIN_DAYS). It cannot exclude a row the started_at bound keeps, because nothing is written a day before it is measured, and it is what lets ClickHouse prune whole partitions instead of scanning the table. FccReportActivationSpecifications.byFilter applies the plain started_at bound to fcc_activation for the run list, on the relational side, where there is no partition to prune and a second predicate would add nothing — see fcc_activation for the index it now runs against.

==== Model and Manufacturer Are Resolved Through the Frozen Fleet

Neither result table carries a model, a manufacturer or a cpe_id column, and none is being added: V1 and V2 declare their column lists final ([lowcardinality-rule]), and an ALTER TABLE over tens of millions of rows is exactly the operation those comments exist to avoid. FccReportScopeResolver resolves a model or manufacturer filter in three steps instead — manufacturer to model ids through the ACS catalog, model ids to campaigns and serials through fcc_test_device (the frozen snapshot), and those into an fcc_test_id IN (…​) predicate on the result rows, narrowed further to a serial IN (…​) only when the model does not already cover every device of the selected campaigns.

The snapshot, and never the live ftacs.cpe. It describes the fleet a run actually executed against; a CPE re-provisioned into another model since then must not change what a finished run reports — the same argument that put protocol into the snapshot in M3 (Why a Snapshot Carries the Protocol).

=== Two Different source Dictionaries — Do Not Merge Them

There are two, unrelated source columns in this system, and they must never be treated as one enum:

The Java-side enums mirror the split exactly: FccTestSourceEnum (ACS_STREAM, LEGACY) versus FccResultSourceEnum (ACS_STREAM, LEGACY_ETL) are two distinct types.

=== What a LEGACY_ETL Row Carries, and What It Cannot

An imported row fills the same columns a live one does, but several of them have no source in the legacy schema at all, and how each says so depends on whether the column is Nullable.

=== Flyway History Table

spring.flyway.enabled is false: Spring Boot’s own Flyway autoconfiguration never runs, and spring.flyway.table is never set at all. ClickHouseFlywayConfig builds a Flyway instance by hand instead — the community ClickHouse dialect stops at 10.24.0 while Boot manages a newer core — and it is that instance whose history table defaults to flyway_schema_history_fcc, never the Flyway default flyway_schema_history. ACS, ui-backend and ft-device-network all keep their own Flyway histories in this same shared ClickHouse database; a shared default history table name has already caused one incident (see ClickHouseFlywayConfig). The history table name is read from a property (ft.fcc.clickhouse.flyway.table) rather than hardcoded, unlike the raw-SQL self-healing block found in some sibling repos' FlywayConfig classes.

== Entity Diagram