Skip to main content

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.

ADRDecision
001Service interfaces over activity polymorphism
002Collection is an OEM-declared job set, executed by collection workers
003Registries removed in favor of durable run state
004Selection pipelines initialize per scope, at scope entry
005BigQuery snapshots keyed (dealer, table, date, collection_id), checked for freshness before a run
006Orderable candidates: scored candidate in, OMS values out, auditable
007Three-state order reporting; cured results feed the candidate pool
008Internal model_id is product identity
009OrderingInput.extras becomes a typed RunConfig
010OEM profile is pure job config; shared contracts stay closed
011Config selects code paths only at the composition root
012One active ordering job per supply cluster; supply ≠ demand clusters
013All collectors run in the Python runner
014One image; one ECS service per (OEM, run kind); trigger-driven scaling
015A scope-level stop: SupplyExhausted ends the scope and lets the run continue
016Snapshots are appended collections in Iceberg; collectors are Dagster assets
017Staged orders are cancelled by a dedicated workflow on the ordering queue
018The 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_id names the completed session. Today it is derived from fetch_date when 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 own collection_id.
  • 2026-09-08: a collection job is a Dagster asset materialization that the run requests. collection_id is 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_after and max_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_pipeline returns them
  • the selection activities take them
  • confirm_pipeline_order returns 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 resolve plus a generic typed read_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 NormalizedCandidate itself. The partition date that pins the mapping moved to RunContext.

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: original also 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 the ordering_events stream 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 ValidationError as a failure exception type. allocation_source leaves 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_format inside candidate_selection's storage config, fetched by an oem string lookup into package internals
  • order_label as 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 FAILURE with error.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.

  • all starts the child with all_orders set.
  • ours starts the child with all_orders unset.
  • none starts 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, or cured until the OEM's flow records a final.

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 that original does not have;
  • removed: codes in original that 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.