@bytebrand/export-cars 1.26.40 → 1.26.42

package/docs/autouncle/AUDIT.md

@@ -1,97 +1,103 @@
-# AutoUncle inventory feed — audit (ADV-322 / ADV-323)
-
-Status 13.10.2026, base `origin/deploy_develop` 3a025095, `@bytebrand/export-cars` 1.26.31.
-Historical documents (Confluence "autouncle [paused]", "2.7.2 Export Plugins", ACF-3604/3650/3717/3725/6172/6190)
-are evidence only. No current AutoUncle inventory schema is available; the public AutoUncle B2B
-"automotive API" is a dealer/DMS **valuation** API and is not used as a schema here.
-
-## 1. Is the export live? — No
-
-| Where | Event | State | Last run | Output |
-|---|---|---|---|---|
-| PROD Cronicle (`auto-de-prod-cronicle-01`, export-cars 1.26.18) | `3.0 Export to autouncle - part 1` `ek61rkico08` | **disabled**, no timing, nothing chains into it | one manual run 07.07.2026, aborted by user | `resources/autouncle-export/api_export_cars_autouncle.json` = 8 bytes (`{"ads":[`) |
-| | `3.1 Export to autouncle - part 2` `ek61ro0yv09` | **disabled**; shell `cp` of the JSON to `htdocs/autouncle/export_cars_autouncle.json` | never ran | `htdocs/autouncle/` does not exist |
-| DEV Cronicle (`auto-de-dev-cronicle-01`, 1.26.31) | `3.0 Export to Autouncle part1` `ek60tym7m0b` | enabled, no timing; chained from `2.1 Export facebook - part 2` | 10.09.2026, code 0 | 467 KB JSON of 10.09 (298 ads) |
-| | `3.1 Export to Autouncle part2` `ek60u1gsd0c` | enabled, chains to `ek87441xa04` | 10.09.2026, **code 1** every run (`cp: … htdocs/autouncle/… No such file or directory`) | — the rest of the DEV chain (criteo, meinestadt, ooyyo, …) stops here |
-
-PROD 3.0 params: `environment=production`, `String` = allow-list of 19 dealer `metaData.ownerId`s, `Number` =
-`metaData.imagesCount:2`. DEV 3.0: no rules. Both events were last modified 2023 (DEV) / 01.04.2026 (PROD,
-migration). Events, keys and scripts were read with `storage-cli list_get`, secrets redacted.
-
-Hosting: `https://scheduler.auto.de/autouncle/export_cars_autouncle.json` (historic) — no answer (timeout);
-`https://cronicle.auto.de/autouncle/…` and `http://cronicle.autode-dev.de/autouncle/…` — 404. Nothing is
-hosted for AutoUncle today, on any environment.
-
-## 2. Code path
-
-`ExportType.AUTOUNCLE = 'autouncle'` → `AutouncleConfig` + `AutouncleExporter` (`export.schema.ts`).
-
-Before (unchanged since the monorepo import 3046a15d, CO2 class ADV-187 b46e7e83):
-`emptyDir(resources/autouncle-export)` → for every car of the base export snapshot: shared `filterCar`
-(imagesCount > 0 + Cronicle rules) → UPA dealer profile (skip if none) → `AutouncleTransformer` →
-`AutouncleJsonBuilder` appends `{"ads":[…]}` directly to the published file.
-
-After (this branch): `AutouncleFeedRun` (`services/autouncle-feed-run.ts`) — lock → source snapshot check
-(shared ADV-335 `FeedGuard`) → per car: duplicate id, `filterCar`, car-level exclusions, dealer address (UPA,
-cached per dealer), clean images (ADV-336 `getCleanImages` + `ImageUrlValidator` + `selectOpenAiImageFields`)
-→ pure `mapAutouncleItem` → temp file → count check → atomic rename (`.prev` kept) → report.
-Dry-run is the default and writes `resources/autouncle-dryrun/`, which no Cronicle step reads.
-
-## 3. Field mapping (`ads[]`, keys/order/spellings unchanged)
-
-| Key | Source | Before | Now | Open |
-|---|---|---|---|---|
-| back_link | CBD `_id` | `https://www.<domain>/search/vehicle/<_id>?source=classifieds&medium=cpc&campaign=autouncle` | same; stable across runs | UTM pattern = Confluence 2.7.2; others existed (ACF-3650/6172) → Q8 |
-| make / model_name / model_variant | mainData.make / model / subModel | raw | same | `SONSTIGE` placeholder models are exported (data) → Q9 |
-| fuel / body / gear_type | consumption.fuel / mainData.category / driveSuspension.gearbox | fixed maps; an unmapped or null selector made the key **disappear** from JSON | unmapped/null → `Other` / `other` | enum values → Q6 |
-| doors | mainData.doors | string | same | |
-| price | price.currentSalesPrice | `EUR <value>`; missing price → `"EUR "` and the car was still sent | same format; no valid positive price → car not sent (`no_valid_price`). Never a rate, never purchasePrice | currency format → Q6 |
-| year | mainData.firstRegistration (Unix s) | null → `moment(0)` → **1970** (143 of 1044 DEV cars) | missing/0/null/invalid → `""`; outside 1900..next year → `""` | null vs "" → Q6 |
-| status | same | `Neuwagen` only when firstRegistration === 0 | `Neuwagen` when no valid firstRegistration (same rule, null included) | 3 of 143 DEV cars are `condition=used` without registration → Q7 |
-| mileage | mainData.mileage | `<n>km`, 0 → `1km` | same | |
-| leasing / has_4wd | — | always `""` | same | → Q10 |
-| color | exterior.exteriorColor, German label | same | same | |
-| engine_size | engineData.cubicCapacity | `ccm` with no number when missing (189/1044) | `""` when missing | |
-| power | engineData.powerKW | kW, no unit | same | unit → Q6 |
-| seller_type / seller_name | — | `Dealer` / `auto.de` | same | marketplace vs dealer identity → Q3 |
-| seller_id | metaData.ownerId | **dealer** id already (not a vehicle id) | same; contract test with two cars of one dealer | |
-| seller_region / city / street_address / postcode | UPA businessAddress, else mainAddress; region from the postal code table | if the table did not know the place, street/city/zip were **blanked** (664/1044 DEV cars) | dealer's own values kept, region `Deutschland` | |
-| description | offer.offerDescription | raw | same; 192/1002 empty on DEV, some contain literal `\\` line breaks (dealer data) | → Q10 |
-| images | Imbo images | default profile: `/large` (format negotiated, can be WebP), padded with **3 noimage placeholders** below 17 photos (2820 placeholder URLs on DEV) | `[{url}]`, ADV-336 clean profile, explicit `large-cached.jpeg`, every URL checked (200 + image/jpeg|png); no valid 3/4 hero → car not sent | limits → ADV-323 gate |
-| fuel_economy / co2_emission | consumption.consumptionCombined / environmentEmissions.co2 | raw | same | |
-| co2_effiency_class / euro_emission_class / enviromental_sticker | environmentEmissions.* | raw selector keys (`selector_energyEfficiencyClass_d`) | same (no schema to translate to) | → Q6 |
-
-Car-level exclusions (new, counted in the report): `duplicate_id`, `filtered`, `no_id`, `no_dealer`,
-`reserved_or_sold` (offer.offerAvailability reserved/sold), `no_valid_price`, `no_valid_image`.
-
-## 4. Fixes on this branch
-
-1. Builder wrote the first car twice (`{"ads":[A,A,B…`) — fixed, test.
-2. Year 1970 for a null first registration (ACF-3717/3725 class of bug) — fixed, tests.
-3. Price must be a valid positive end-customer price, otherwise the car is not sent.
-4. Reserved / sold cars are not sent (absence = removal; partner semantics unknown → Q5).
-5. Dealer address no longer blanked when the postal code table misses the place.
-6. `engine_size` without a value is `""`, not `ccm`; unmapped selectors never drop a key.
-7. Images: clean profile + validator, no placeholders, no WebP risk, hero first (ADV-323).
-8. Fail-closed: no `emptyDir`; empty / partial / stale snapshot, empty result or a drop > 20 % against the
-   last good run → run blocked (exit 1, `3.1` copy does not run), last good file stays. Lock per state dir.
-9. Dry-run default; live only with `autouncleDryRun=false`.
-
-## 5. Evidence
-
-- `npm test`: 138 ok (116 existing + 14 mapping + 8 run).
-- Other feeds byte-identical: `origin/deploy_develop` and this branch compiled with the same `node_modules`;
-  every emitted `.js` outside the AutoUncle files is identical (only `params.interface.d.ts` gains three
-  optional fields). Covers Google, FB/Meta, Criteo, meinestadt, OOYYO, OpenAI and the rest.
-- DEV dry-run 13.10.2026 (local, DEV snapshot 12.10 15:00 CEST, DEV `3.0` params): 2234 source cars →
-  1002 ads, 370 dealers, excluded `filtered` 1190 / `no_valid_image` 42, images 7259/7259 ok, 0 placeholders,
-  0 × 1970, 0 duplicate links. Old exporter on the same snapshot: 1045 ads (first duplicated), 143 × 1970,
-  2820 placeholder URLs. 20-car sample in `autouncle-sample/` (worktree, not committed).
-
-## 6. Not done / not decided
-
-- No partner schema, no test import, no activation, no Cronicle change, no version bump / publish.
-- `minPublishedItems` default is 1 (PROD exports an allow-list of 19 dealers; real size unknown) — set per job
-  before activation.
-- `3.1` copy target `htdocs/autouncle/` does not exist on either Cronicle; hosting/transport is a partner question (Q4).
-- Portrait / small images: the validator checks status + MIME only, no pixel size — waits for partner limits.
+# AutoUncle inventory feed — audit (ADV-322 / ADV-323)
+
+Status 13.10.2026, base `origin/deploy_develop` 3a025095, `@bytebrand/export-cars` 1.26.31.
+Historical documents (Confluence "autouncle [paused]", "2.7.2 Export Plugins", ACF-3604/3650/3717/3725/6172/6190)
+are evidence only. No current AutoUncle inventory schema is available; the public AutoUncle B2B
+"automotive API" is a dealer/DMS **valuation** API and is not used as a schema here.
+
+## 1. Is the export live? — No
+
+| Where | Event | State | Last run | Output |
+|---|---|---|---|---|
+| PROD Cronicle (`auto-de-prod-cronicle-01`, export-cars 1.26.18) | `3.0 Export to autouncle - part 1` `ek61rkico08` | **disabled**, no timing, nothing chains into it | one manual run 07.07.2026, aborted by user | `resources/autouncle-export/api_export_cars_autouncle.json` = 8 bytes (`{"ads":[`) |
+| | `3.1 Export to autouncle - part 2` `ek61ro0yv09` | **disabled**; shell `cp` of the JSON to `htdocs/autouncle/export_cars_autouncle.json` | never ran | `htdocs/autouncle/` does not exist |
+| DEV Cronicle (`auto-de-dev-cronicle-01`, 1.26.31) | `3.0 Export to Autouncle part1` `ek60tym7m0b` | enabled, no timing; chained from `2.1 Export facebook - part 2` | 10.09.2026, code 0 | 467 KB JSON of 10.09 (298 ads) |
+| | `3.1 Export to Autouncle part2` `ek60u1gsd0c` | enabled, chains to `ek87441xa04` | 10.09.2026, **code 1** every run (`cp: … htdocs/autouncle/… No such file or directory`) | — the rest of the DEV chain (criteo, meinestadt, ooyyo, …) stops here |
+
+PROD 3.0 params: `environment=production`, `String` = allow-list of 19 dealer `metaData.ownerId`s, `Number` =
+`metaData.imagesCount:2`. DEV 3.0: no rules. Both events were last modified 2023 (DEV) / 01.04.2026 (PROD,
+migration). Events, keys and scripts were read with `storage-cli list_get`, secrets redacted.
+
+Hosting: `https://scheduler.auto.de/autouncle/export_cars_autouncle.json` (historic) — no answer (timeout);
+`https://cronicle.auto.de/autouncle/…` and `http://cronicle.autode-dev.de/autouncle/…` — 404. Nothing is
+hosted for AutoUncle today, on any environment.
+
+## 2. Code path
+
+`ExportType.AUTOUNCLE = 'autouncle'` → `AutouncleConfig` + `AutouncleExporter` (`export.schema.ts`).
+
+Before (unchanged since the monorepo import 3046a15d, CO2 class ADV-187 b46e7e83):
+`emptyDir(resources/autouncle-export)` → for every car of the base export snapshot: shared `filterCar`
+(imagesCount > 0 + Cronicle rules) → UPA dealer profile (skip if none) → `AutouncleTransformer` →
+`AutouncleJsonBuilder` appends `{"ads":[…]}` directly to the published file.
+
+After (this branch): `AutouncleFeedRun` (`services/autouncle-feed-run.ts`) — lock → source snapshot check
+(shared ADV-335 `FeedGuard`) → per car: duplicate id, `filterCar`, car-level exclusions, dealer address (UPA,
+cached per dealer), clean images (ADV-336 `getCleanImages` + `ImageUrlValidator` + `selectOpenAiImageFields`)
+→ pure `mapAutouncleItem` → temp file → count check → atomic rename (`.prev` kept) → report.
+Dry-run is the default and writes `resources/autouncle-dryrun/`, which no Cronicle step reads.
+
+## 3. Field mapping (`ads[]`, keys/order/spellings unchanged)
+
+| Key | Source | Before | Now | Open |
+|---|---|---|---|---|
+| back_link | CBD `_id` | `https://www.<domain>/search/vehicle/<_id>?source=classifieds&medium=cpc&campaign=autouncle` | stable across runs; since 1.26.41 (ADV-324) `?source=autouncle&medium=listing&campaign=listing&utm_source=autouncle&utm_medium=listing&utm_campaign=listing` | pending AutoUncle approval → Q8 |
+| make / model_name / model_variant | mainData.make / model / subModel | raw | same | `SONSTIGE` placeholder models are exported (data) → Q9 |
+| fuel / body / gear_type | consumption.fuel / mainData.category / driveSuspension.gearbox | fixed maps; an unmapped or null selector made the key **disappear** from JSON | unmapped/null → `Other` / `other` | enum values → Q6 |
+| doors | mainData.doors | string | same | |
+| price | price.currentSalesPrice | `EUR <value>`; missing price → `"EUR "` and the car was still sent | same format; no valid positive price → car not sent (`no_valid_price`). Never a rate, never purchasePrice | currency format → Q6 |
+| year | mainData.firstRegistration (Unix s) | null → `moment(0)` → **1970** (143 of 1044 DEV cars) | missing/0/null/invalid → `""`; outside 1900..next year → `""` | null vs "" → Q6 |
+| status | same | `Neuwagen` only when firstRegistration === 0 | `Neuwagen` when no valid firstRegistration (same rule, null included) | 3 of 143 DEV cars are `condition=used` without registration → Q7 |
+| mileage | mainData.mileage | `<n>km`, 0 → `1km` | same | |
+| leasing / has_4wd | — | always `""` | same | → Q10 |
+| color | exterior.exteriorColor, German label | same | same | |
+| engine_size | engineData.cubicCapacity | `ccm` with no number when missing (189/1044) | `""` when missing | |
+| power | engineData.powerKW | kW, no unit | same | unit → Q6 |
+| seller_type / seller_name | — | `Dealer` / `auto.de` | same | marketplace vs dealer identity → Q3 |
+| seller_id | metaData.ownerId | **dealer** id already (not a vehicle id) | same; contract test with two cars of one dealer | |
+| seller_region / city / street_address / postcode | UPA businessAddress, else mainAddress; region from the postal code table | if the table did not know the place, street/city/zip were **blanked** (664/1044 DEV cars) | dealer's own values kept, region `Deutschland` | |
+| description | offer.offerDescription | raw | same; 192/1002 empty on DEV, some contain literal `\\` line breaks (dealer data) | → Q10 |
+| images | Imbo images | default profile: `/large` (format negotiated, can be WebP), padded with **3 noimage placeholders** below 17 photos (2820 placeholder URLs on DEV) | `[{url}]`, ADV-336 clean profile, explicit `large-cached.jpeg`, every URL checked (200 + image/jpeg|png); no valid 3/4 hero → car not sent | limits → ADV-323 gate |
+| fuel_economy / co2_emission | consumption.consumptionCombined / environmentEmissions.co2 | raw legacy fields; a BEV sent its kWh (CBD mirrors it into consumptionCombined) as fuel economy | since 1.26.41: the Google feed's EnVKV picks as plain numbers (WLTP first, legacy only as fallback; confirmed plug-in weighted); BEV: fuel `""`, CO₂ `0`; estimated values withheld by the publication gate (enforce) | units → Q6 |
+| co2_effiency_class | environmentEmissions.wltpEnergyEfficiencyClass (ADV-187) | raw | same; `""` when the CO₂ value is withheld (the class is derived from CO₂) | → Q6 |
+| euro_emission_class / enviromental_sticker | environmentEmissions.* | raw selector keys | same (no schema to translate to) | → Q6 |
+
+Car-level exclusions (new, counted in the report): `duplicate_id`, `filtered`, `no_id`, `no_dealer`,
+`reserved_or_sold` (offer.offerAvailability reserved/sold), `no_valid_price`, `no_valid_image`.
+
+## 4. Fixes on this branch
+
+1. Builder wrote the first car twice (`{"ads":[A,A,B…`) — fixed, test.
+2. Year 1970 for a null first registration (ACF-3717/3725 class of bug) — fixed, tests.
+3. Price must be a valid positive end-customer price, otherwise the car is not sent.
+4. Reserved / sold cars are not sent (absence = removal; partner semantics unknown → Q5).
+5. Dealer address no longer blanked when the postal code table misses the place.
+6. `engine_size` without a value is `""`, not `ccm`; unmapped selectors never drop a key.
+7. Images: clean profile + validator, no placeholders, no WebP risk, hero first (ADV-323).
+8. Fail-closed: no `emptyDir`; empty / partial / stale snapshot, empty result or a drop > 20 % against the
+   last good run → run blocked (exit 1, `3.1` copy does not run), last good file stays. Lock per state dir.
+9. Dry-run default; live only with `autouncleDryRun=false`.
+10. (1.26.41, 10.11) EnVKV: WLTP picks + EnVKV C8 publication gate (same params as the Google job). A live run
+    refuses to start without `publicationGate=enforce`. The run report has `envkv.estimated` for the two sent
+    attributes (fuel_consumption, co2_emissions; 1.26.42). DEV dry-run 10.11 (enforce): 1731 ads, estimated fuel 884 /
+    CO₂ 848 sent empty, 128 BEV with fuel "" and CO₂ 0, WLTP picks changed 338 fuel / 403 CO₂ values.
+11. (1.26.41, 10.11) `back_link` parameters per ADV-324 (partner in `source`, identical utm pair).
+
+## 5. Evidence
+
+- `npm test`: 138 ok (116 existing + 14 mapping + 8 run).
+- Other feeds byte-identical: `origin/deploy_develop` and this branch compiled with the same `node_modules`;
+  every emitted `.js` outside the AutoUncle files is identical (only `params.interface.d.ts` gains three
+  optional fields). Covers Google, FB/Meta, Criteo, meinestadt, OOYYO, OpenAI and the rest.
+- DEV dry-run 13.10.2026 (local, DEV snapshot 12.10 15:00 CEST, DEV `3.0` params): 2234 source cars →
+  1002 ads, 370 dealers, excluded `filtered` 1190 / `no_valid_image` 42, images 7259/7259 ok, 0 placeholders,
+  0 × 1970, 0 duplicate links. Old exporter on the same snapshot: 1045 ads (first duplicated), 143 × 1970,
+  2820 placeholder URLs. 20-car sample in `autouncle-sample/` (worktree, not committed).
+
+## 6. Not done / not decided
+
+- No partner schema, no test import, no activation, no Cronicle change, no version bump / publish.
+- `minPublishedItems` default is 1 (PROD exports an allow-list of 19 dealers; real size unknown) — set per job
+  before activation.
+- `3.1` copy target `htdocs/autouncle/` does not exist on either Cronicle; hosting/transport is a partner question (Q4).
+- Portrait / small images: the validator checks status + MIME only, no pixel size — waits for partner limits.

package/docs/autouncle/PARTNER-QUESTIONS.md

@@ -33,7 +33,9 @@ ingestion contract and is not used as one.
    registration date "new"?
 8. **Unique key and links.** Which field is the unique ad key on your side — `back_link`, or should we add a
    stable vehicle id? Which UTM parameters do you want on `back_link` (historic:
-   `source=classifieds&medium=cpc&campaign=autouncle`)? Do you need a click id passed through?
+   `source=classifieds&medium=cpc&campaign=autouncle`; proposed and on DEV since 1.26.41:
+   `source=autouncle&medium=listing&campaign=listing` plus the same values as `utm_*`)? Do you need a click id
+   passed through?
 9. How do you treat ads whose model is unknown (our placeholder "SONSTIGE")? Exclude or send?
 10. Optional fields: do you use `leasing`, `has_4wd`, `description` (German text), and do you support
     structured financing offers (rate, duration, deposit, balloon, mileage, APR with legal disclosures) instead

package/docs/autouncle/RUNBOOK.md

@@ -15,6 +15,8 @@ Not activated. Nothing below has been done on any Cronicle host.
 | `feedGuardMaxSourceAgeHours` | 26 | newest base export chunk must be younger |
 | `feedGuardMaxStaleHours` | 48 | last good file reported STALE after this |
 | `feedGuardAcceptDrop` | off | `true` for ONE run after a real stock drop |
+| `publicationGate` | off | `audit` counts estimated EnVKV values, `enforce` sends them empty. **A live run needs `enforce`** (config error otherwise). enforce fails the run if the enrichment log cannot be read |
+| `publicationGateBqProject` / `…Dataset` / `…Table` | — | CBD enrichment log table, same values as the Google job; required for audit / enforce |
 
 `String` / `Number` rules stay as they are (PROD: dealer allow-list + `metaData.imagesCount:2`).
 

package/docs/criteo/RUNBOOK.md

@@ -1,86 +1,86 @@
-# Criteo catalog feed — runbook (ADV-319)
-
-Status 06.11.2026, `@bytebrand/export-cars` 1.26.40. DEV only; PROD events `4.0` / `4.1` are disabled
-and no Criteo account, contract or importer test exists yet. Nothing here allows a live upload.
-
-## What the job does
-
-`4.0 export criteo - part 1` (`exportType=criteo`) reads the base export snapshot
-(`resources/cars-export/cars.<n>.json`) and writes the legacy Criteo RSS/XML file
-`resources/criteo-export/api_export_cars_criteo.xml`. The chained `4.1 Export criteo - part 2` uploads that
-file. Format, enums and field order are the legacy ones (decision 20.10.2026: restore as before).
-
-Per car, in this order (first match wins, counted in `excluded`):
-
-| Reason | Rule |
-|---|---|
-| `no_id` | empty `_id` |
-| `duplicate_id` | `_id` already seen in this run (first one is kept) |
-| `filtered` | shared partner filter: `metaData.imagesCount > 0` and the Cronicle rule params |
-| `reserved_or_sold` | `offer.offerAvailability` is reserved or sold (Criteo 16.10: only marketable stock) |
-| `no_valid_price` | `price.currentSalesPrice` missing, not a number or ≤ 0 |
-| `no_marketing_image` | no generated `criteo-<id>.jpg`; no noimage placeholder is ever sent |
-
-A car that went offline is not in the snapshot, so it is missing from the next full file; Criteo's next
-full import removes it. `published-ids.json` keeps the ids of the last published file, and the report
-lists `ids.added` / `ids.removed` / `ids.kept` (+ up to 20 removed ids) for each run.
-
-Item fields: `installment` and `custom_label_0` only when the car has a real rate (months and amount > 0);
-`energy_efficiency_class` only for a known WLTP class.
-
-## Fail-closed guard
-
-Shared `FeedGuard` (same as meinestadt / AutoUncle / OpenAI). The new XML is written to
-`api_export_cars_criteo.xml.tmp` and renamed over the published file only after all checks passed; the
-previous file is kept as `.prev`. A blocked run keeps the published file, moves the temp file to
-`.rejected`, and **fails the job** (Cronicle code 1), so `4.1` does not upload anything.
-
-| Code | Meaning | Action |
-|---|---|---|
-| `source_empty` | no snapshot chunk files (base export failed / wiped) | fix the base export, re-run |
-| `source_partial` | chunk files with gaps | re-run the base export |
-| `source_stale` | newest chunk older than `feedGuardMaxSourceAgeHours` (26) | base export did not run |
-| `source_too_small` | snapshot below `feedGuardMinSourceItems` (1000) | check the base export |
-| `published_too_small` | fewer items than `feedGuardMinPublishedItems` (500), e.g. all reserved/sold | check stock / images |
-| `count_drop` | source or items dropped by more than `feedGuardMaxDropPercent` (20 %) vs last good | if the stock really dropped: re-run once with `feedGuardAcceptDrop=true` |
-| `locked` | another run holds `resources/criteo-state/run.lock` (stale after 6 h) | wait / check the other job |
-
-Stale fallback: each report carries `lastGoodAgeHours`; after `feedGuardMaxStaleHours` (48) without a
-successful run, `stale: true` and the log line `criteo feed STALE`. The job itself already failed on every
-blocked run, which is the alert. Whether Criteo should then get an empty file (to stop advertising
-old stock) is an open partner question, not built.
-
-All thresholds are Cronicle params of the `4.0` event (`feedGuardMinSourceItems`,
-`feedGuardMinPublishedItems`, `feedGuardMaxDropPercent`, `feedGuardMaxSourceAgeHours`,
-`feedGuardMaxStaleHours`, `feedGuardAcceptDrop`).
-
-## Files
-
-| Path (relative to `/opt/cronicle`) | Content |
-|---|---|
-| `resources/criteo-export/api_export_cars_criteo.xml` | published file (what `4.1` uploads) |
-| `resources/criteo-export/api_export_cars_criteo.xml.prev` | file before the last publish |
-| `resources/criteo-export/api_export_cars_criteo.xml.rejected` | output of the last blocked run |
-| `resources/criteo-state/last-good.json` | counts + time of the last publish |
-| `resources/criteo-state/last-run-report.json` | report of the last run (also printed as `criteo feed report: {...}`) |
-| `resources/criteo-state/published-ids.json` | ids of the published file |
-
-Report metrics: source chunk age (`source.ageHours`), run time (`durationMs`), source cars, items,
-exclusions by reason, items with a rate, items without energy class, id changes, last good age.
-Criteo's accepted / rejected records come from the Criteo importer, not from this job.
-
-## Rollback
-
-1. Code: `sudo npm --prefix /opt/cronicle install @bytebrand/export-cars@<previous> --prefer-online`
-   (DEV before this release: 1.26.39). Only the export-cars package changes; back up
-   `/opt/cronicle/package.json` and `package-lock.json` first.
-2. File: `cp resources/criteo-export/api_export_cars_criteo.xml.prev resources/criteo-export/api_export_cars_criteo.xml`.
-3. State: `resources/criteo-state/` can be deleted; the next run then has no last good counts (no drop check
-   once) and reports all ids as added.
-
-## Tests
-
-`test/criteo-mapping.test.ts` (item mapping) and `test/criteo-feed-run.test.ts`: 20 anonymized DEV cars
-(`test/fixtures/criteo-20-cases.json`, synthetic ids, mapping fields only) plus sold, reserved, offline,
-no image, price change, invalid price, duplicate id, missing id, source outage, partial / stale snapshot,
-count drop + acceptDrop, empty stock, lock, stale last good, atomic publish. Run: `npm test`.
+# Criteo catalog feed — runbook (ADV-319)
+
+Status 06.11.2026, `@bytebrand/export-cars` 1.26.40. DEV only; PROD events `4.0` / `4.1` are disabled
+and no Criteo account, contract or importer test exists yet. Nothing here allows a live upload.
+
+## What the job does
+
+`4.0 export criteo - part 1` (`exportType=criteo`) reads the base export snapshot
+(`resources/cars-export/cars.<n>.json`) and writes the legacy Criteo RSS/XML file
+`resources/criteo-export/api_export_cars_criteo.xml`. The chained `4.1 Export criteo - part 2` uploads that
+file. Format, enums and field order are the legacy ones (decision 20.10.2026: restore as before).
+
+Per car, in this order (first match wins, counted in `excluded`):
+
+| Reason | Rule |
+|---|---|
+| `no_id` | empty `_id` |
+| `duplicate_id` | `_id` already seen in this run (first one is kept) |
+| `filtered` | shared partner filter: `metaData.imagesCount > 0` and the Cronicle rule params |
+| `reserved_or_sold` | `offer.offerAvailability` is reserved or sold (Criteo 16.10: only marketable stock) |
+| `no_valid_price` | `price.currentSalesPrice` missing, not a number or ≤ 0 |
+| `no_marketing_image` | no generated `criteo-<id>.jpg`; no noimage placeholder is ever sent |
+
+A car that went offline is not in the snapshot, so it is missing from the next full file; Criteo's next
+full import removes it. `published-ids.json` keeps the ids of the last published file, and the report
+lists `ids.added` / `ids.removed` / `ids.kept` (+ up to 20 removed ids) for each run.
+
+Item fields: `installment` and `custom_label_0` only when the car has a real rate (months and amount > 0);
+`energy_efficiency_class` only for a known WLTP class.
+
+## Fail-closed guard
+
+Shared `FeedGuard` (same as meinestadt / AutoUncle / OpenAI). The new XML is written to
+`api_export_cars_criteo.xml.tmp` and renamed over the published file only after all checks passed; the
+previous file is kept as `.prev`. A blocked run keeps the published file, moves the temp file to
+`.rejected`, and **fails the job** (Cronicle code 1), so `4.1` does not upload anything.
+
+| Code | Meaning | Action |
+|---|---|---|
+| `source_empty` | no snapshot chunk files (base export failed / wiped) | fix the base export, re-run |
+| `source_partial` | chunk files with gaps | re-run the base export |
+| `source_stale` | newest chunk older than `feedGuardMaxSourceAgeHours` (26) | base export did not run |
+| `source_too_small` | snapshot below `feedGuardMinSourceItems` (1000) | check the base export |
+| `published_too_small` | fewer items than `feedGuardMinPublishedItems` (500), e.g. all reserved/sold | check stock / images |
+| `count_drop` | source or items dropped by more than `feedGuardMaxDropPercent` (20 %) vs last good | if the stock really dropped: re-run once with `feedGuardAcceptDrop=true` |
+| `locked` | another run holds `resources/criteo-state/run.lock` (stale after 6 h) | wait / check the other job |
+
+Stale fallback: each report carries `lastGoodAgeHours`; after `feedGuardMaxStaleHours` (48) without a
+successful run, `stale: true` and the log line `criteo feed STALE`. The job itself already failed on every
+blocked run, which is the alert. Whether Criteo should then get an empty file (to stop advertising
+old stock) is an open partner question, not built.
+
+All thresholds are Cronicle params of the `4.0` event (`feedGuardMinSourceItems`,
+`feedGuardMinPublishedItems`, `feedGuardMaxDropPercent`, `feedGuardMaxSourceAgeHours`,
+`feedGuardMaxStaleHours`, `feedGuardAcceptDrop`).
+
+## Files
+
+| Path (relative to `/opt/cronicle`) | Content |
+|---|---|
+| `resources/criteo-export/api_export_cars_criteo.xml` | published file (what `4.1` uploads) |
+| `resources/criteo-export/api_export_cars_criteo.xml.prev` | file before the last publish |
+| `resources/criteo-export/api_export_cars_criteo.xml.rejected` | output of the last blocked run |
+| `resources/criteo-state/last-good.json` | counts + time of the last publish |
+| `resources/criteo-state/last-run-report.json` | report of the last run (also printed as `criteo feed report: {...}`) |
+| `resources/criteo-state/published-ids.json` | ids of the published file |
+
+Report metrics: source chunk age (`source.ageHours`), run time (`durationMs`), source cars, items,
+exclusions by reason, items with a rate, items without energy class, id changes, last good age.
+Criteo's accepted / rejected records come from the Criteo importer, not from this job.
+
+## Rollback
+
+1. Code: `sudo npm --prefix /opt/cronicle install @bytebrand/export-cars@<previous> --prefer-online`
+   (DEV before this release: 1.26.39). Only the export-cars package changes; back up
+   `/opt/cronicle/package.json` and `package-lock.json` first.
+2. File: `cp resources/criteo-export/api_export_cars_criteo.xml.prev resources/criteo-export/api_export_cars_criteo.xml`.
+3. State: `resources/criteo-state/` can be deleted; the next run then has no last good counts (no drop check
+   once) and reports all ids as added.
+
+## Tests
+
+`test/criteo-mapping.test.ts` (item mapping) and `test/criteo-feed-run.test.ts`: 20 anonymized DEV cars
+(`test/fixtures/criteo-20-cases.json`, synthetic ids, mapping fields only) plus sold, reserved, offline,
+no image, price change, invalid price, duplicate id, missing id, source outage, partial / stale snapshot,
+count drop + acceptDrop, empty stock, lock, stale last good, atomic publish. Run: `npm test`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytebrand/export-cars",
-  "version": "1.26.40",
+  "version": "1.26.42",
   "description": "",
   "author": "bytebrand",
   "license": "UNLICENSED",

package/src/configs/autouncle.config.ts

@@ -1,7 +1,7 @@
 import { toNumber } from 'lodash';
 
 import { ExportType, FileType, ImageType } from '../enums';
-import { Params } from '../interfaces/params.interface';
+import { Params, PublicationGateConfig } from '../interfaces/params.interface';
 import { FeedGuardOptions } from '../services/feed-guard';
 import { Config } from './config';
 
@@ -55,8 +55,33 @@ export class AutouncleConfig extends Config {
       maxStaleHours: positiveNumber(params.feedGuardMaxStaleHours, AUTOUNCLE_DEFAULTS.maxStaleHours),
       acceptDrop: text(params.feedGuardAcceptDrop).toLowerCase() === 'true',
     };
+    this.publicationGate = parsePublicationGate(params);
+    // ADV-322 "do not guess emissions": a live file never goes out with unchecked EnVKV estimates.
+    if (!this.dryRun && this.publicationGate?.mode !== 'enforce') {
+      throw new Error('a live AutoUncle run (autouncleDryRun=false) needs publicationGate=enforce');
+    }
     this.outputFiles = [
       `${this.pathesConfig.localConvertedDirectory}/api_export_cars_${ExportType.AUTOUNCLE}.${FileType.JSON}`,
     ];
   }
 }
+
+// Same params and rules as the Google job (GoogleConfig): off by default; audit / enforce need the
+// enrichment log table (publicationGateBqProject / Dataset / Table).
+function parsePublicationGate(params: Params): PublicationGateConfig | undefined {
+  const mode = text(params.publicationGate).toLowerCase();
+  if (!mode || mode === 'off') return undefined;
+  if (mode !== 'audit' && mode !== 'enforce') {
+    throw new Error(`publicationGate must be off, audit or enforce, got "${mode}"`);
+  }
+  const gate = {
+    mode: mode as PublicationGateConfig['mode'],
+    project: text(params.publicationGateBqProject),
+    dataset: text(params.publicationGateBqDataset),
+    table: text(params.publicationGateBqTable),
+  };
+  if (!gate.project || !gate.dataset || !gate.table) {
+    throw new Error(`publicationGate=${mode} needs publicationGateBqProject, publicationGateBqDataset and publicationGateBqTable`);
+  }
+  return gate;
+}

package/src/configs/criteo.config.ts

@@ -1,54 +1,54 @@
-import { toNumber } from 'lodash';
-
-import { ExportType, FileType, ImageType } from 'src/enums';
-import { Params } from '../interfaces/params.interface';
-import { FeedGuardOptions } from '../services/feed-guard';
-import { Config } from './config';
-
-const text = (value: unknown): string => (typeof value === 'string' ? value.trim() : '');
-
-const positiveNumber = (value: unknown, fallback: number): number => {
-  const parsed = toNumber(text(value));
-  return text(value) && Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
-};
-
-// Same guard defaults as the meinestadt / OpenAI feeds; a job can override them via the
-// feedGuard* Cronicle params.
-export const CRITEO_DEFAULTS = {
-  minSourceItems: 1000,
-  minPublishedItems: 500,
-  maxDropPercent: 20,
-  maxSourceAgeHours: 26,
-  maxStaleHours: 48,
-};
-
-/**
- * Criteo catalog (ADV-319): legacy RSS/XML file at the same path as before, which the chained
- * `4.1 Export criteo - part 2` step uploads. Guard state lives in resources/criteo-state.
- */
-export class CriteoConfig extends Config {
-  stateDir: string;
-  feedGuard: FeedGuardOptions;
-
-  constructor(params: Params) {
-    super(params);
-    this.campaign = ExportType.CRITEO;
-    this.pathesConfig.localConvertedDirectory = `resources/${ExportType.CRITEO}-export`;
-    this.stateDir = `resources/${ExportType.CRITEO}-state`;
-    this.imageType = ImageType.marketing;
-    this.marketingImageConfigId = this.environmentConfig[params.environment].criteoMarketingImagesConfigId;
-    this.feedGuard = {
-      stateDir: this.stateDir,
-      minSourceItems: positiveNumber(params.feedGuardMinSourceItems, CRITEO_DEFAULTS.minSourceItems),
-      minPublishedItems: positiveNumber(params.feedGuardMinPublishedItems, CRITEO_DEFAULTS.minPublishedItems),
-      maxDropPercent: positiveNumber(params.feedGuardMaxDropPercent, CRITEO_DEFAULTS.maxDropPercent),
-      maxSourceAgeHours: positiveNumber(params.feedGuardMaxSourceAgeHours, CRITEO_DEFAULTS.maxSourceAgeHours),
-      maxStaleHours: positiveNumber(params.feedGuardMaxStaleHours, CRITEO_DEFAULTS.maxStaleHours),
-      acceptDrop: text(params.feedGuardAcceptDrop).toLowerCase() === 'true',
-    };
-    this.outputFiles = [
-      `${this.pathesConfig.localConvertedDirectory}/api_export_cars_${ExportType.CRITEO}.${FileType.XML}`,
-    ];
-    this.isCriteo = true;
-  }
-}
+import { toNumber } from 'lodash';
+
+import { ExportType, FileType, ImageType } from 'src/enums';
+import { Params } from '../interfaces/params.interface';
+import { FeedGuardOptions } from '../services/feed-guard';
+import { Config } from './config';
+
+const text = (value: unknown): string => (typeof value === 'string' ? value.trim() : '');
+
+const positiveNumber = (value: unknown, fallback: number): number => {
+  const parsed = toNumber(text(value));
+  return text(value) && Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
+
+// Same guard defaults as the meinestadt / OpenAI feeds; a job can override them via the
+// feedGuard* Cronicle params.
+export const CRITEO_DEFAULTS = {
+  minSourceItems: 1000,
+  minPublishedItems: 500,
+  maxDropPercent: 20,
+  maxSourceAgeHours: 26,
+  maxStaleHours: 48,
+};
+
+/**
+ * Criteo catalog (ADV-319): legacy RSS/XML file at the same path as before, which the chained
+ * `4.1 Export criteo - part 2` step uploads. Guard state lives in resources/criteo-state.
+ */
+export class CriteoConfig extends Config {
+  stateDir: string;
+  feedGuard: FeedGuardOptions;
+
+  constructor(params: Params) {
+    super(params);
+    this.campaign = ExportType.CRITEO;
+    this.pathesConfig.localConvertedDirectory = `resources/${ExportType.CRITEO}-export`;
+    this.stateDir = `resources/${ExportType.CRITEO}-state`;
+    this.imageType = ImageType.marketing;
+    this.marketingImageConfigId = this.environmentConfig[params.environment].criteoMarketingImagesConfigId;
+    this.feedGuard = {
+      stateDir: this.stateDir,
+      minSourceItems: positiveNumber(params.feedGuardMinSourceItems, CRITEO_DEFAULTS.minSourceItems),
+      minPublishedItems: positiveNumber(params.feedGuardMinPublishedItems, CRITEO_DEFAULTS.minPublishedItems),
+      maxDropPercent: positiveNumber(params.feedGuardMaxDropPercent, CRITEO_DEFAULTS.maxDropPercent),
+      maxSourceAgeHours: positiveNumber(params.feedGuardMaxSourceAgeHours, CRITEO_DEFAULTS.maxSourceAgeHours),
+      maxStaleHours: positiveNumber(params.feedGuardMaxStaleHours, CRITEO_DEFAULTS.maxStaleHours),
+      acceptDrop: text(params.feedGuardAcceptDrop).toLowerCase() === 'true',
+    };
+    this.outputFiles = [
+      `${this.pathesConfig.localConvertedDirectory}/api_export_cars_${ExportType.CRITEO}.${FileType.XML}`,
+    ];
+    this.isCriteo = true;
+  }
+}

package/src/exporters/autouncle.exporter.ts

@@ -9,6 +9,7 @@ import { resolveOpenAiImageFields } from '../transformers/openai-image-fields';
 import { CarService, RulesService, LoaderService, ConfigService, ImagesService } from '../services';
 import { ImageUrlValidator } from '../services/image-url-validator.service';
 import { FeedGuard } from '../services/feed-guard';
+import { PublicationGate, loadPublicationGate } from '../services/publication-gate';
 import { AutouncleFeedRun, AutouncleSourceCar } from '../services/autouncle-feed-run';
 import { AutouncleConfig } from '../configs/autouncle.config';
 import { Exporter } from '../interfaces/exporter.interface';
@@ -36,6 +37,16 @@ export class AutouncleExporter implements Exporter {
     const transformer = await this.moduleRef.create(AutouncleTransformer);
     const addresses = new Map<string, Promise<AutouncleAddress | null>>();
 
+    // EnVKV C8 (ADV-322): estimated values are withheld (enforce) or only counted (audit). enforce fails
+    // the job when the enrichment log cannot be read, so the last published file stays.
+    let gate: PublicationGate;
+    try {
+      gate = await loadPublicationGate(config.publicationGate);
+    } catch (error) {
+      LoggerService.exitError(`autouncle feed not published: ${error?.message ?? error}`);
+      process.exit(1);
+    }
+
     const run = new AutouncleFeedRun(
       {
         forEachChunk: fn => this.loaderService.process((chunk: FsChunkInterface) => fn(chunk.data as AutouncleSourceCar[])),
@@ -55,6 +66,7 @@ export class AutouncleExporter implements Exporter {
         imageStats: () => validator.stats,
         translate: key => transformer.translate(key),
         guard: new FeedGuard(config.feedGuard),
+        gate,
       },
       {
         runId: config.runId,