CSV Export

Overview

Produce a Casestry-format CSV for a specified date range — a ProcedureExecution (PKO) that queries warehouse data, generates a Document Artifact (IAO), and stores it in R2 as an Information Bearing Entity for download.

Goal: Generate a downloadable Document Artifact and a durable export record.

Participants

Actor	Ontological type	Role
Staff user	Person (CCO) bearing Role	Requests export with date range
Dashboard API Worker	EngineeredSystem (IOF)	Creates Document Artifact record, enqueues ProcedureExecution
Ingest Worker	EngineeredSystem (IOF)	ProcedureExecution: queries data, generates Document, uploads to R2
PlanetScale	EngineeredSystem (IOF)	IBE store for data source + Document Artifact records
R2	EngineeredSystem (IOF)	IBE store for generated Document

Main success scenario

[PKO: ProcedureExecution producing IAO Document concretized_by R2 IBE]

1. Person bearing Role calls POST /api/csv/generate with date range
2. API validates Access, writes document_artifact row as pending
3. API enqueues DOCUMENT_ARTIFACT_GENERATE(export_id, date_range)
4. Step: Query — Worker queries commercial_transaction_record / transaction_participation_record for the range
5. Step: Join — Worker joins with denotation_relation → information_content_entity for design asset bearer URLs
6. Step: Format — Worker formats Casestry CSV (34 columns including vendor resolution)
7. Step: Store — Worker uploads Document to R2 (creates IBE) and stores file URL in document_artifact.file_url
8. Step: Finalize — Worker updates document_artifact.status = 'completed' with counts and metadata

Exception flows

IssueOccurrence	FallbackStep
Missing denotation_relation	Include placeholder value; record count in metadata.error_count
PlanetScale limits	Chunk reads; stream CSV generation; stay under 64 MiB result sets
Document creation fails	Set status = 'failed', store error_message

Queue contract

{
  "job_type": "DOCUMENT_ARTIFACT_GENERATE",
  "job_id": "uuid",
  "export_id": "uuid",
  "date_range_start": "YYYY-MM-DD",
  "date_range_end": "YYYY-MM-DD"
}

API endpoints

• POST /api/csv/generate — enqueue ProcedureExecution (p99 < 200ms)
• GET /api/csv/exports — list Document Artifacts with status
• GET /api/csv/exports/:id — single Document Artifact detail + bearer_entity_url for download

Acceptance criteria

• PASS: CSV rows match expected order count; bearer_entity_url resolves; Document Artifact record transitions pending → completed
• FAIL: Incorrect formatting; missing required columns; data mismatch vs commercial_transaction_record