Ordering Platform — Architecture Decision Records
Most of these were settled in the August 2026 design review. Later records show their own
dates. The scoped services/ai_ordering/CLAUDE.md tracks which are enforced in code today.
| ADR | Decision |
|---|---|
| 001 | Service interfaces over activity polymorphism |
| 002 | Collection is an OEM-declared job set, executed by collection workers |
| 003 | Registries removed in favor of durable run state |
| 004 | Selection pipelines initialize per scope, at scope entry |
| 005 | BigQuery snapshots keyed (dealer, table, date, collection_id), checked for freshness before a run |
| 006 | Orderable candidates: scored candidate in, OMS values out, auditable |
| 007 | Three-state order reporting; cured results feed the candidate pool |
| 008 | Internal model_id is product identity |
| 009 | OrderingInput.extras becomes a typed RunConfig |
| 010 | OEM profile is pure job config; shared contracts stay closed |
| 011 | Config selects code paths only at the composition root |
| 012 | One active ordering job per supply cluster; supply ≠ demand clusters |
| 013 | All collectors run in the Python runner |
| 014 | One image; one ECS service per (OEM, run kind); trigger-driven scaling |
| 015 | A scope-level stop: SupplyExhausted ends the scope and lets the run continue |
| 016 | Snapshots are appended collections in Iceberg; collectors are Dagster assets |
| 017 | Staged orders are cancelled by a dedicated workflow on the ordering queue |
| 018 | The dealer report presents a modification as changes to the existing order |
ADR-001: Service interfaces over activity polymorphism
Status: Accepted (2026-08-05). Amended:
- 2026-08-12: one service class per OEM serves every run kind. The injected private API client is the only difference between compositions.
Context
Per-OEM behavior was dispatched by registering per-OEM activity implementations under shared
activity names, selected by task queue. Nothing bound the implementations to the
OemOrderingActivities Protocol, so a fifth activity was added without the Protocol changing.
OEM logic was coupled to Temporal and unusable elsewhere, such as in daily amendment and BMW
template generation.
Decision
A Temporal-free OrderingService interface in services/ordering.py, implemented per OEM. One
generic OrderingActivities layer, the only temporalio importer, resolves the run's service from
the OrderingServiceFactory injected at the worker's composition root. The live and simulated
factories are the two compositions. Conformance is checked by mypy.
One service class per OEM serves every run kind: simulated, live validation and live submission
execute the same code. One live queue and one simulated queue each serve every OEM. A run names
its OEM in its input, and the activity layer dispatches on (oem, market). A simulated run
cannot reach a private API:
- the simulated workflow calls no activity that reaches one
- its queue registers none
- its services hold a mock private API client
The workflow keeps the per-target loop, since each iteration is a durability checkpoint.
Consequences
Adding an OEM is one profile, one service implementation and one queue registration. The services also serve callers outside the workflow, such as BMW template generation.
ADR-002: Collection is an OEM-declared job set, executed by collection workers
Status: Accepted (2026-08-05). Amended:
- 2026-08-12: an OEM declares its collection jobs as a list, and every job satisfies one workflow contract.
- 2026-08-14:
collection_idnames the completed session. Today it is derived fromfetch_datewhen the run resolves the session. After ADR-013 the child workflow's id is written on every row. Until then, each table the run checks resolves its owncollection_id. - 2026-09-08: a collection job is a Dagster asset materialization that the run requests.
collection_idis that run's id (ADR-016). - 2026-10-22: a simulated run has its own staleness limit,
simulated_max_staleness.
Context
The original design gave the ordering service a pull_data method. Scheduled collectors do the
same pulls with no ordering run involved, so the method would have been duplicated there, and
the ordering workers would have held private API code they never run.
Decision
Collection is separate from ordering, and each OEM configures it: the profile lists the
collection jobs an ordering run requires. A CollectionJob names a workflow type, a task queue
and its staleness limits. An OEM runs many collection jobs, and each OEM's run requires a
different subset.
Every job satisfies one contract: it starts with the run's user and dealer, and it writes each
table's rows as one session named by a collection_id (ADR-005). A run resolves one
collection_id per table of each declared job (CollectionJob.tables). A job may write more
tables than the run checks. Collection jobs execute on the collection workers, whether a
schedule or a run started them. A live run compares each table's age with refresh_after and
max_staleness:
- younger than
refresh_after: the run reuses the data - between
refresh_afterandmax_staleness: the run starts the job as a child workflow - older than
max_staleness: the run stops
A simulated run never starts a job. It reads the most recent session and stops when that session
is older than simulated_max_staleness. The warehouse data that a simulated run reads is already
older than the data a live run collects, so simulated_max_staleness can be longer than
max_staleness.
Consequences
Ordering workers host only OrderingService, and collection workers host only collection jobs,
so the queue split is also the capability split. Each OEM normalizes its own structures once,
in its collection jobs. ADR-013 says when that moves to write time. The TypeScript collectors
and their Python migrations satisfy the same contract, so the configured list works throughout
the migration.
ADR-003: Registries removed in favor of durable run state
Status: Accepted (2026-08-05)
Context
Three module-global dict[str, Any] registries (pipeline_registry, oem_payload_registry,
target_inputs_registry) held run state as its only copy: untyped, importable from anywhere, and
lost when a worker restarted, which orphaned the run and forced desired_count=1. A typed
RunStore[T] would have allowed the same misuse.
Decision
The registries are removed. Each kind of state has a durable home: snapshots in the snapshot store (ADR-005), reference data in the warehouse, and OEM payloads and live selection pipelines in Temporal external storage.
Selection pipelines pass between activities:
initialize_pipelinereturns them- the selection activities take them
confirm_pipeline_orderreturns them, so the supply state it advanced reaches the next iteration
The workflow holds them as an opaque RawValue and never decodes one, because deserializing a
pipeline with pickle imports polars, whose module body reads os.environ, which the workflow
sandbox forbids. The activities at either end decode.
A PipelineCache that rebuilds from durable state on a miss was rejected: it needs a rebuild
path and a replay of confirmed orders whose cost grows with every order a run places.
Consequences
Any worker can continue any run, since no worker holds state the run depends on. Per-iteration cost scales with pipeline size: a scope map covering every scope measured about 414 MB, so pipelines shrink to one live scope (ADR-004) to fit in memory.
ADR-004: Selection pipelines initialize per scope, at scope entry
Status: Accepted (2026-08-05). Amended:
- 2026-08-12: the pipeline initializes when the scope is entered instead of at the first recommendation.
Context
initialize_pipeline built every scope's pipeline at the start, with every model's frames in
memory at once and a transient Arrow double buffer during load. The 2026-08-04 allocation run
exhausted an 8 GB worker's memory on a dealer with nine orders.
Decision
A scope's pipeline is built when the scope is entered and evicted when its targets are done. Pipeline state crosses activities as typed inputs and outputs (ADR-003), and the workflow knows which scope it enters next, so waiting for the first recommendation gains nothing. Stellantis targets are emitted contiguously per model, so the working set is one scope. Mercedes slot targets may interleave, so the workflow sorts targets by scope.
Consequences
Memory is bounded at about one scope however many models a dealer orders. Eviction is safe because the state the loop needs next is what the last activity returned (ADR-003).
ADR-005: BigQuery snapshots keyed (dealer, table, date, collection_id), checked for freshness before a run
Status: Accepted (2026-08-05). Amended:
- 2026-08-14: reads are
resolveplus a generic typedread_rows. Row structures are OEM-internal, and the ref is the only cross-OEM snapshot contract. - 2026-09-08: the store is Iceberg. A day's partition keeps every collection made that day (ADR-016).
Context
Scheduled collectors write snapshots to BigQuery, and Dagster copies them into Iceberg. Ordering needs OEM data that is fresh when a run starts, and simulated and live runs must read the same source. Writing Iceberg from the collectors, with Dagster external-asset reporting, was kept as the option to revisit once Iceberg becomes the primary consumer of these snapshots.
Decision
BigQuery remains the shared snapshot store. An ordering run starts collection as a child workflow with the run's user and dealer, so collection uses the captured session that ordering itself uses.
Snapshots are keyed (dealer, table, date, collection_id). collection_id names the completed
session: today it is derived from fetch_date at read. After ADR-013 the child's workflow id
is written on every row. A pull later in the day never overwrites what an earlier run read, so a
simulation reads the same collection the run read.
Reads go through one generic SnapshotStore: resolve, and read_rows(ref, row_model)
returning typed models. Each OEM binds its own row models where it calls read_rows, and rows
never cross an activity boundary. A run that cannot collect must not order.
Consequences
One collection code path serves scheduled and run-started pulls. The run inherits collection's SLA and failure modes.
ADR-006: Orderable candidates — scored candidate in, OMS values out, auditable
Status: Accepted (2026-08-05). Amended:
- 2026-08-12: the mapping input is the scored candidate, which the orderable holds by composition.
- 2026-08-17: only the base type crosses an activity boundary. Each activity derives the OEM representation itself.
- 2026-08-23: the OEM representation is service-internal values.
- 2026-08-24: the boundary type is
SelectedCandidate. The layering is checked in CI. - 2026-08-26: the boundary type is
NormalizedCandidateitself. The partition date that pins the mapping moved toRunContext.
Context
The mapping from candidate to order format was spread across candidate_mapping.py and the
wizard walk, and the workflow serialized full candidates and recommendations into every activity
call. Internal code should reference canonical ids. OEM codes belong at the ordering boundary.
Decision
The workflow passes the ordering service the scored candidate as selection emitted it.
Recommendation output is already in external storage, so nothing new enters event history.
(candidate.id, RunContext.partition_date) determines the mapping for replay. The partition is
constant for a run, because the warehouse probe takes a partition whole and every candidate of a
run was selected from that date.
The service derives the private API values from the candidate's internal ids, without repeating
warehouse lookups for fields selection already resolved. The values are consumed where they are
computed. Each brand does this inside its own service under oem/. No per-brand record holds
the mapping, and nothing OEM-specific enters types/, whose models are the cross-OEM contract.
Brands share no OMS fields, so a shared structure would hold fields most brands never use. The
exact representation attempted is persisted per attempt. Whether orderable candidates are
precomputed or generated at order time remains open.
Activity signatures annotate NormalizedCandidate. The data converter decodes to the annotation
and silently drops any field the annotation does not declare, because the model ignores unknown
keys.
tests/test_domain_layer_boundary.py enforces the layering: oem/, services/ and types/
import without temporalio, and no module under oem/ imports ai_ordering.activities or
ai_ordering.workflows.
Consequences
Event history holds claim-check references and no inline candidates. Mapping runs once per
activity that needs it, so it must stay cheap. The factory gives one service instance to every
run a worker takes, so anything a mapping keeps between calls is keyed by what it was read for.
The OEM's own representation reaches reporting through the per-attempt record. CureResult
holds the cured build normalized so it can re-enter the selection pool (ADR-007).
ADR-007: Three-state order reporting; cured results feed the candidate pool
Status: Accepted (2026-08-05). Amended:
- 2026-09-11:
originalalso holds the build of a staged order a cancellation run removed (ADR-017). - 2026-10-09: the build we requested is the recommendation the attempt names by
recommendation_id, and theordering_eventsstream records it. It is not a fourth snapshot, because no OMS returned it. See ADR-018 for how the dealer report presents a modification.
Context
OEM systems cure, mutate or add defaults to submitted candidates:
- BMW's BYO validation returns what is in effect a new candidate, with a new hash
- Mercedes cures mid-flow
- Stellantis holds non-conforming orders in BG or BX status
A derived diff alone cannot be analyzed when the diff logic is wrong, and per-option pricing makes diffs large.
Decision
Persist three raw builds per attempt, in one overlayable schema:
- original: the build on the existing order, for modify flows
- cured: the build as the OMS accepted it for submission
- final: the build the OEM kept
Diffs are derived for analysis. The three builds are the record. A cured result may be a new candidate: its id is recomputed from the returned build, because order ids are many-to-one to candidates, and it enters the candidate pool through the next collection. Mutation by restriction must remain distinguishable from dealer modification.
Consequences
Reporting shows what the OEM kept. Which discrepancies need action and which are analytics only remains open, as does the persistence target: run reporting writes to Mongo today, and a standardized BigQuery stream is the proposed successor.
ADR-008: Internal model_id is product identity
Status: Accepted (2026-08-05)
Context
Volume optimization composed a product_id = model_code|trim_identifier from the internal
model_id, only for ordering to split it again for the order wizard. The format declaration
(ProductIdFormat) was defined on iceberg_tables, an identity contract coupled to a storage
choice. group_cols was declared in two places with nothing keeping them in agreement.
Decision
SelectionScope.product_id becomes the internal model_id, which is year-specific because a
specific year's car is ordered. Loaders filter on it directly. ProductIdFormat,
compose_product_id and parse_model_code are cancelled. OEM codes (model code, trim, Baumuster)
live on the orderable candidate and in cross-references only. group_cols is cancelled from both
places: base_model_id is the statistical granularity, because the per-OEM judgment is already
absorbed in its derivation at ingestion.
Consequences
A grouping setting returns only with a named use case.
ADR-009: OrderingInput.extras becomes a typed RunConfig
Status: Accepted (2026-08-05). Amended:
- 2026-08-13: the field itself is typed. The workflows register
ValidationErroras a failure exception type.allocation_sourceleaves the run input.
Context
extras: dict[str, Any] was an untyped side channel. Per-block parsing validated known blocks
and silently ignored unknown top-level keys. Full typing had been deferred to avoid a matching
change in Job Freezer, the TypeScript service that constructs the input.
Decision
OrderingInput.extras is one frozen, fully typed RunConfig: every block is a declared field,
and extra="forbid" at the top level rejects an unknown block. Because the field is typed,
Temporal's converter validates the config while decoding the input, so a bad config fails the run
at its first workflow task, before any activity runs.
It fails the run rather than the workflow task only because both ordering workflows declare
failure_exception_types=[ValidationError]. Without that registration, _convert_payloads
reports the rejection as Failed decoding arguments and Temporal retries the workflow task
forever. Do not remove that registration. Its cost is that any ValidationError raised inside
these workflows fails the run instead of retrying the task until a fix is deployed.
RunConfig holds only settings a run may choose (ADR-011): run_summary, volume_optimization
and the optional volume_fill. allocation_source, DealerConnect's market letter and ship-to
dealer, is a per-OEM fact, so ADR-010 places it inside the adapter. Job Freezer never set
extras, so it needs no change.
Consequences
A run is reproducible from its input alone, and a typo in its config cannot run at defaults
unnoticed. extras is a closed schema in its serialized form, so removing or renaming a block breaks
decoding of any history that contains it, whether a completed run being replayed or an in-flight
run's continuation. Treat a block removal as a versioning change. Every block is declared for
every OEM even when only one reads it. Per-OEM blocks need a discriminated union keyed on the
OEM, because the converter validates against the field's annotation and rejects a subclass with
extra blocks.
ADR-010: OEM profile is pure job config; shared contracts stay closed
Status: Accepted (2026-08-05)
Context
Per-OEM facts were scattered:
product_id_formatinside candidate_selection's storage config, fetched by anoemstring lookup into package internalsorder_labelas a module constant- grouping declared twice
Per-OEM data structures led to optional fields on shared models, such as trim: str | None, or
to per-OEM subclasses. Both were rejected: Temporal's converter round-trips declared
types, and isinstance(target, StellantisTarget) in shared code is the coupling being removed.
Decision
OrderingOEMProfile holds only per-OEM choices, read once at the composition root: oem,
market, operating_mode, order_label, collection_jobs. Everything downstream receives
typed values. The profile is interim: the long-term direction is hard ingestion contracts, a
standardized schema plus canonical internal entity ids with cross-references, and profile fields
are removed as those are released. One question decides where a varying field goes: does shared code
need to understand it?
- OEM-private: typed models in the service
- present but unread: opaque slots
- shared-math dimensions only some OEMs have: semantic attribute rows
- required everywhere: canonical typed fields
Consequences
Adding an OEM adds a profile and no fields on shared models.
ADR-011: Config selects code paths only at the composition root
Status: Accepted (2026-08-05)
Context
Whether volume optimization should be a config flag generalizes to one question: where may
configuration change behavior? A runtime flag in shared code, such as
volume_optimization_enabled, is a branch that every run decides again from mutable data. The
simulated queue exists so that no run decides at run time whether it may order, and such a flag
undoes that.
Decision
Three places, each with one job:
- deployment sets capability: which services a worker injects (live, simulated, volume-optimizing)
- the OEM profile declares per-OEM facts
- run input (
RunConfig) sets a run's scope: brands to allocate, thresholds, recipients
The composition root selects code only at worker startup, using operating_mode to bind
construct_targets. During a run, configuration sets quantities and scope only.
Consequences
A worker's capabilities are fixed at deployment. If operators need per-run volume-optimization toggling, it becomes an explicit run-input selection among strategies composed in advance.
ADR-012: One active ordering job per supply cluster; supply ≠ demand clusters
Status: Accepted (2026-08-05). Amended:
- 2026-08-06: the per-iteration shared-supply refresh is deferred, because current supply
formulas give nearby-dealer supply negligible weight. The refresh and the
(dealer, candidate)write-back activate when that weighting needs realtime data. The run loop's structure does not change.
Context
Per-dealer ordering is locally optimal and collectively wrong: whole cars cannot be fractionally allocated, and every subdivision amplifies rounding error. Two dealers in one cluster starting concurrently would read the same empty supply state and place identical top-scored orders. The existing "smart clusters" are demand clusters based on buyer similarity. They are not geographically aligned and have not been validated for supply coordination.
Decision
Coordination happens at the smallest supply cluster that matters, a new and empirically derived
concept. Concurrency control is a job-level lock: one active ordering job per supply cluster.
Shared cluster supply state records which dealer ordered which candidate, because neighbor
supply weighs differently from own-store supply, and the loop re-reads it every iteration. Its
durable store lives with candidate_selection, extending the supply state confirm_order already
mutates. Restriction evidence stays in ordering persistence. Ordering keeps a multi-dealer
dealer_ids input while executing per dealer.
Consequences
Daily dry runs estimate what the rest of the cluster would order, which reduces order-sequencing bias. Cluster definition and cluster-level take rates are upstream work. Stellantis cross-dealer allocation also requires OEM authorization. The trigger and windowing mechanism remains open.
ADR-013: All collectors run in the Python runner
Status: Accepted (2026-08-05). Amended:
- 2026-09-08: the Python collectors are Dagster assets writing Iceberg (ADR-016).
Context
The same private API parsers existed twice: TypeScript scheduled collectors in
ppm-ordering-services and Python in ai_ordering. Moving transport clients and parsers into
one package per private API (packages/ai_dealer_connect, packages/ai_netstar) removed the
cause.
Decision
All new collectors are written in Python on those packages. The existing TypeScript collectors
are migrated per source (DealerConnect, NetSTAR), keep the same BigQuery destination, and are
then decommissioned. From that point the collection jobs normalize at write, and the read-side
shims behind SnapshotStore are removed.
Consequences
One pull implementation per OEM serves scheduled collection, run-started collection and ordering. Until the migration completes, the TypeScript collectors write raw structures and normalization runs at read.
ADR-014: One image; one ECS service per (OEM, run kind); trigger-driven scaling
Status: Accepted (2026-08-05)
Context
Ordering runs a few days per month per OEM. Collectors run daily. A single always-on worker
process with desired_count=1 hosts every queue. Temporal polling cannot filter by input, so
scaling is per queue, and per-OEM scaling requires per-OEM queues.
Decision
One codebase, one image, one ECS service definition, instantiated per (OEM, run kind), with each
instance's queue and OEM set by configuration. Per-OEM queues stay as the unit of scaling and
isolation. Ordering services scale between zero and one with the run trigger, which already
knows work is coming, so nothing polls a backlog. Collection workers scale on task-queue backlog
metrics. ResourceBasedSlotSupplier caps per-worker concurrency by memory and CPU. Simulated
runs get their own queue and deployment.
Consequences
An OEM's ordering workers stay at zero outside its ordering windows. desired_count > 1 per OEM
depends on ADR-003. Scale-down must never terminate in-flight work.
ADR-015: A scope-level stop: SupplyExhausted ends the scope and lets the run continue
Status: Accepted (2026-09-03)
Context
A submit ends in one of two ways. An OrderingError fails the activity with a non-retryable
error, and the run fails. Anything else returns as a FAILURE attempt, and the loop asks for the
next candidate. Neither fits a scope whose supply is gone mid-run, such as an allocation remainder
that reached zero because another order consumed it. Failing the run discards every other scope.
A FAILURE attempt retries the same candidate until max_retries_per_target is used up, then the
scope's next slot repeats that, so the run makes max_retries_per_target × remaining slots OMS
calls that each read a remainder of zero.
Decision
SupplyExhausted(OrderingError) in types/errors.py means the scope's supply is gone. A service
raises it where its OMS reports that fact: Audi from submit, when validateRemainingQuantity
answers less than the quantity requested. The workflow catches the failure in _fill_target:
- records the attempt as
FAILUREwitherror.type="SupplyExhausted" - makes no attempt on the scope's remaining targets
- continues with the next scope
Those targets count as skipped. OrderingExitReason is unchanged. The ended scope's
SupplyExhausted attempt is the record of the stop.
Consequences
The workflow matches the canonical type name. Only submit reads the remainder, so only an
execute run raises the stop. _cure turns every activity failure into a refused cure. The stop
is per scope: a carline whose allocation is gone leaves the run's other carlines to fill.
ADR-016: Snapshots are appended collections in Iceberg; collectors are Dagster assets
Status: Proposed (2026-09-08)
Context
ADR-005 kept BigQuery as the snapshot store until Iceberg became the primary consumer of the snapshots. Audi's derived tiers build eleven tables from them, and an ordering run reads three. Ingestion partitions raw assets by day and overwrites the partition on materialization. An ordering run needs the collections inside a day kept: it resolves the latest one at or before its reference time, and a simulated run must read the same collection a live run read. The first collectors to migrate under ADR-013 are Audi's, so the store decides how they are built.
Decision
A collection job is a Dagster asset, partitioned by dealer and day. A shared table such as
product data partitions by day alone. The asset pulls the source with the dealer's captured session.
A sensor watches for a new session for the dealer and, when one appears, requests a materialization
of the day's partition. An ordering run whose freshness verdict is stale or expired requests a
materialization of the same partition and waits for it. Temporal remains the ordering runner. The
request replaces ADR-002's child workflow. The materializing run's id is the collection_id,
written on every row.
Snapshots live in Iceberg with ADR-005's key, (dealer, table, date, collection_id).
Each materialization appends its rows, with collection_id and collected_at, into the day's
partition. Nothing inside a day is overwritten. Downstream assets take the latest collection per
partition through one shared read filter, so the transformed tier sees one snapshot per day. Ordering
resolves the latest collection at or before its reference time per dealer, records its
collection_id in the snapshot ref, and reads by it. A simulated run reads by the recorded id.
Every collection is kept.
Audi migrates first. A source whose collector has not migrated keeps writing BigQuery, and
SnapshotStore selects the backend per SnapshotSource.
Consequences
ADR-005's key and freshness check stand. A CollectionJob names an asset and a partition. The
scheduled collectors' missing-partition check is unchanged, because a partition appears at the
day's first collection. Freshness within a day is the ordering run's decision. Re-materializing a
day appends a collection. Removing a bad one is a delete by collection_id. The raw components
that copy a migrated source out of BigQuery are removed, and transformed reads the collector's
table. The worker's GCP credential path stays until the last BigQuery source migrates. A
collection in flight is findable by dealer through its run's tags, so a run can wait for it.
ADR-017: Staged orders are cancelled by a dedicated workflow on the ordering queue
Status: Proposed (2026-09-11)
Context
An OMS that supports stage mode holds orders nobody has submitted. AccessAudi fills a dealer's pending submissions with pre-built orders when an allocation opens, and a stage run adds its own. A predictive run has to remove the pre-builds before it adds orders, a dealer demo has to remove what the demo added, and a run redone after dealer feedback has to remove only what the service added. The ordering workflow has no step that removes a staged order.
Decision
A second workflow on the live queue, StagedOrderCancellationWorkflow. Its input names the dealer,
the models in scope, or none for every model the dealer holds allocation for, and
all_orders: unset, the run cancels the staged orders identified as
our placements by the comment this service writes; set, every staged order in scope. An
explicit list of staged order ids narrows either, and an id outside our placements is refused
unless all_orders is set. A dry run lists the staged orders in scope and cancels none, so an
operator can name them to an execute run. It runs on its own or as a child of the ordering run,
which passes its own run id so the records group under one run.
OrderingService gains list_staged_orders and cancel_staged_order. An OEM that does not
support stage mode raises ConfigurationError from both. The Audi service resolves the scope
to carline and model year through the product model snapshot, reads its pending submissions,
selects orders by their comment, and looks up the STAGED attempt behind each selected order
by the reference in that comment in one indexed query. It cancels one order per call: it reads the list
again first, treats an order already gone as cancelled, and requires the OMS's echo to name it.
Each removed order is a new OrderAttempt with status CANCELLED, the removed build in
original and the echo in its raw payload. The STAGED attempt that added the order is left
as it was; the two share candidate_id and staged_order_ref, which every staged attempt
records. A staged order with no attempt behind it gets a candidate built from the OMS's own
record. A staged order the OMS refuses to cancel gets no record; the run counts it as failed.
Consequences
The run's cancel_staged_orders setting decides whether an ordering run starts the child.
A run that omits the setting uses its OEM profile's default.
allstarts the child withall_ordersset.oursstarts the child withall_ordersunset.nonestarts no child.
The run starts the child after it builds targets and before it places. The child covers the
models in the run's target filter, or every model if the filter names none. The run starts
the child even when the volume solve orders nothing. A dry run, or a run with ordering
disabled, starts it in dry-run mode. A simulated run skips it. A child that fails, or that
leaves an order uncancelled, stops the run with STAGED_ORDER_CANCELLATION_FAILED before it
places anything. A cancellation run writes no
ordering_runs document. The reporting DAG derives a
staged order's state from its STAGED and CANCELLED attempts. Whether extending the shared
interface for one OEM stays right is judged on reuse when the next OEM that supports stage mode
arrives.
ADR-018: The dealer report presents a modification as changes to the existing order
Status: Proposed (2026-10-09)
Context
The dealer report shows one card per attempt, and each card lists one build. A net-new order needs nothing more. A modification run changes an order the dealer already holds, so the dealer has to see what changed on that order. Three builds determine what changed:
- the order before the run changed it, which is the attempt's
original; - the build we requested, which is the recommendation the attempt names by
recommendation_id(ADR-007); - the build the OMS kept, which is
final, orcureduntil the OEM's flow records afinal.
The OMS may refuse part of a request and add codes the request did not name. The report shows both.
Take rates count each card's headline rows and options.
Decision
A card for a modification lists the card's build in full, in headline and options, as
a net-new card does. The card's build is final when the attempt has one, and cured
otherwise.
DealerReportBuild gets an optional modification, and a net-new build leaves it unset.
modification holds three lists of CandidateOption:
added: codes in the card's build thatoriginaldoes not have;removed: codes inoriginalthat the card's build does not have;not_kept: changes we requested that the card's build does not reflect. These are the codes we requested to add that the build lacks, and the codes we requested to remove that the build still has.
The OEM's service computes all three lists in its report_data, with set operations on the
snapshots' option_codes. It maps the recommendation to codes of the same form. For
not_kept, it counts only the changes its cure derives from the recommendation. When
added, removed and not_kept are all empty, the card says the order already holds the
build.
Take rates count the card's build and ignore modification. A take rate in a modification
report is therefore the share of the modified orders that include a value.
Consequences
The persisted original, cured, final and recommendation do not change.
report_data derives the three lists from them after the run and writes them into
report_build, which holds the presentation. The report template renders the three lists
on each modification card. Any other OEM that modifies orders sets the same field.