Combo Log CRUD + CSV Import

Overview

Maintain a durable ledger of tested combos as combo reports (ontology: Creative Act Reports) stored in macrodata_artifact rows with kind=combo_report. Each combo report documents a completed creative test that realizes a combo template (ontology: Plan Specification). The combo template identifier convention TYPE-PRODUCT-COUNT-AUDIENCE-SEQ (e.g., SP-IPH-2-WOMEN-001) provides human-readable, sortable structured identifiers.

Goal: CRUD for combo reports and bulk CSV import/export for operational workflows.

API endpoints

Both the low-level macrodata CRUD API and the higher-level creative-ops workflow API expose combo report operations:

Method	Path	Spec	Description
GET	`/creative-ops/combo-tests`	creative-ops.yaml	List combo reports with filters
POST	`/creative-ops/combo-tests`	creative-ops.yaml	Create a new combo report
GET	`/creative-ops/combo-tests/{test_id}`	creative-ops.yaml	Get combo report detail
POST	`/creative-ops/combo-tests/{test_id}/finalize`	creative-ops.yaml	Mark combo report as complete
GET	`/macrodata-catalogs/{catalog_id}/artifacts?kind=combo_report`	macrodata.yaml	List combo reports in a catalog
POST	`/macrodata-artifacts`	macrodata.yaml	Create artifact (kind: `combo_report`)
PUT	`/macrodata-artifacts/{artifact_id}`	macrodata.yaml	Update combo report artifact
DELETE	`/macrodata-artifacts/{artifact_id}`	macrodata.yaml	Archive combo report artifact
POST	`/macrodata-artifacts/upload`	macrodata.yaml	Upload CSV for bulk import
GET	`/creative-ops/exports`	creative-ops.yaml	List/download export jobs (CSV export)

All endpoints use CF Access auth and target p99 < 200ms.

Schema tables

Table	Role
`macrodata_catalog`	Catalog/namespace that groups combo report artifacts
`macrodata_artifact`	Stores combo reports (`kind=combo_report`), templates, suggestions
`link_product_macrodata_artifact`	Links products to combo report artifacts
`product`	Product reference data for fuzzy matching during CSV import

Infrastructure

Resource	Purpose
Internal Worker (CF Worker)	Serves CRUD and import/export endpoints behind CF Access
Ingest Worker (CF Worker)	Processes queued CSV import jobs
CF Queue	`COMBO_REPORT_IMPORT` job queue for async import
PlanetScale (Postgres via Hyperdrive)	Primary data store for all artifacts
R2 (`measurement.performance`)	Performance data used for product fuzzy matching

Combo template identifier convention

{type}-{productCode}-{productCount}-{audience}-{sequenceNum}

Segment	Values	Example
`type`	`SP` (Split), `CT` (Carousel), `NT` (Narrow), `UGC`, `ST`	`SP`
`productCode`	Derived from products (ontology: Material Artifacts): `IPH`, `SAM`, `AIR`, `MIX`	`IPH`
`productCount`	Number of products in combo	`2`
`audience`	Target audience	`WOMEN`
`sequenceNum`	Auto-incremented, zero-padded	`001`

CSV import workflow

POST /macrodata-artifacts/upload with CSV payload
API enqueues COMBO_REPORT_IMPORT for background processing (ontology: ProcedureExecution)
Ingest Worker parses rows, applies fuzzy matching against measurement.performance on R2 for product resolution
Worker upserts into macrodata_artifact (kind=combo_report) in chunks
Returns summary: N valid rows imported, M errors

Fuzzy matching: The current system uses Levenshtein distance + substring heuristics to match product titles from CSV to known products. This carries forward.

Queue contract (import)

{
  "job_type": "COMBO_REPORT_IMPORT",
  "job_id": "uuid",
  "source": { "type": "upload", "bearer_entity_key": "imports/..." }
}

Export

GET /creative-ops/exports?type=combo_reports triggers an async export job that generates a CSV of all combo reports matching current filters.

Acceptance criteria

PASS: Create/update/delete reflect in list; CSV import workflow adds N valid rows and reports M invalid rows deterministically
FAIL: Non-idempotent import creates duplicates; corrupted JSON in cases_included