Scenarios Overview

These scenarios follow the OAGi ConnectSpec pattern — each defines participants (typed by ontological category), assumptions, a business workflow (sequence described with PKO vocabulary), and exception handling (PKO IssueOccurrences + FallbackSteps). They serve as the Operational Analysis (OA) layer in the Arcadia method, directly traceable to logical components and physical infrastructure.

Every scenario’s entities, relations, and processes are grounded in the ontology stack. See the Domain Ontology Mapping for the single source of truth on entity-to-ontology mappings.

Scenario catalog

Data pipelines (ProcedureExecutions)

Scenario	Trigger	Primary actors	Key tables	Ontological character
Daily Shopify Bulk Sync	Cron (daily) or manual	Cron, Ingest Worker, Shopify API	procedure_execution_*, commercial_transaction_record, transaction_participation_record, material_artifact, sales_measurement_dataset, performance_measurement_dataset	ProcedureExecution acquiring Process Records
Product Tag Sync	Manual (“Sync Tags”)	Staff, Ingest Worker, Shopify API	material_artifact	Act updating MaterialArtifact Qualities
Asset Ingest	Staff submits artifact + URL	Staff, Ingest Worker, Dropbox, R2, Shopify	information_content_entity, denotation_relation	ProcedureExecution: ICE concretized_by IBE, denotes MaterialArtifact
CSV Export	Staff requests export	Staff, Ingest Worker, R2	document_artifact, commercial_transaction_record	ProcedureExecution producing Document Artifact
Fulfillment Monitoring	Read-only (data from daily sync)	Fulfillment team	fulfillment_daily_summary	Measurement Data by Temporal Region

Analytics & classification (Measurement Data + Nominal Classification)

Scenario	Trigger	Primary actors	Key tables	Ontological character
Performance Metrics	Browsing + settings	Ops/Creative, Dashboard API	performance_measurement_dataset, objective_specification	Measurement Data retrieval; Objective Specification governs Nominal Classification
Tag Analytics	Browsing + refresh	Creative/Ops, Dashboard API	material_artifact, sales_measurement_dataset, tag_content_entity	Aggregation over ICEs producing Measurement Data
Tag Groups	Staff creates/edits groups	Creative/Ops, Dashboard API	information_entity_collection	CRUD on ICE Collections (member_part_of)
Tag Classification	Staff bulk-classifies tags	Staff, Dashboard API	tag_content_entity	Creating ICEs with is_about relation to MaterialArtifact collections
Designer Assignment	Staff assigns tags to designers	Creative lead, Dashboard API	agent_role_assignment, material_artifact, sales_measurement_dataset	Person bearing DesignerRole; agent_in relation to sales attribution

Combo management (Plan Specifications + Creative Act Reports)

Scenario	Trigger	Primary actors	Key tables	Ontological character
Combo Log CRUD	Staff creates/imports combos	Staff, Dashboard API	creative_act_report	Report (IAO) lifecycle; realizes Plan Specification
Combo Templates	Staff manages template library	Creative, Dashboard API	plan_specification	Plan Specification lifecycle with Action Specifications
Combo Suggestions	Staff requests generation	Staff, Ingest Worker	suggestion_content_entity, creative_act_report, performance_measurement_dataset	ProcedureExecution producing ICEs with measurement_confidence

Lookup (Process Record retrieval)

Scenario	Trigger	Primary actors	Key tables	Ontological character
Order Lookup	Staff searches by ID/name	Staff, Dashboard API	commercial_transaction_record, transaction_participation_record	Information retrieval of Process Records (orders as Occurrents)

API endpoints matrix

Scenario	Endpoints	Auth
Bulk Sync	POST /api/performance-metrics/sync, GET /api/ingest/runs, GET /api/health	CF_ACCESS
Tag Sync	POST /api/products/tags/sync, GET /api/products/tags/sync/status	CF_ACCESS
Performance Metrics	GET/POST/PUT/DELETE /api/performance-metrics, GET /api/performance-metrics/stats/summary, GET/PUT /api/performance-metrics/settings/classification	CF_ACCESS
Tag Analytics	POST /api/tag-analytics/performance, GET /api/tag-analytics/distribution/:category, GET /api/tag-analytics/group-performance/:groupId, POST /api/tag-analytics/refresh	CF_ACCESS
Tag Groups	GET/POST /api/tag-groups, DELETE /api/tag-groups/:groupId	CF_ACCESS
Tag Classification	POST /api/tag-classifications/bulk, GET /api/tag-classifications/unclassified	CF_ACCESS
Designer Assignment	GET /api/designers, GET /api/designers/names, POST /api/designers/assign, DELETE /api/designers/unassign, DELETE /api/designers/:designerName	CF_ACCESS
Combo CRUD	GET/POST /api/combo-logs, PUT/DELETE /api/combo-logs/:id, POST /api/combo-logs/import, GET /api/combo-logs/export	CF_ACCESS
Combo Templates	GET/POST /api/combo-templates, DELETE /api/combo-templates/:templateId	CF_ACCESS
Combo Suggestions	POST /api/combo-suggestions/generate, GET /api/combo-suggestions, POST /api/combo-suggestions/:id/accept	CF_ACCESS
Asset Ingest	POST /api/assets/ingest, GET /api/assets/:productId, GET /api/assets/status/:productId	CF_ACCESS
CSV Export	POST /api/csv/generate, GET /api/csv/exports, GET /api/csv/exports/:id	CF_ACCESS
Order Lookup	POST /api/orders/lookup	CF_ACCESS
Fulfillment	GET /api/fulfillment-daily-summary	CF_ACCESS

Cross-scenario standards

Authentication

All endpoints are staff-only, protected by Cloudflare Access. All authenticated users are Persons (CCO) bearing Roles (BFO). JWT validation uses the Cf-Access-Jwt-Assertion header (cookie is not guaranteed).

Queue semantics

Scenarios using Cloudflare Queues for ProcedureExecution dispatch assume:

• Batch delivery: configurable max_batch_size (default 10) and max_batch_timeout (default 5s)
• Default delivery retries: 3
• Explicit msg.ack() prevents redelivery even if later messages fail
• Delayed retry: up to 12 hours (for rate-limit backoff)
• DLQ recommended for poison messages (PKO IssueOccurrences that exhaust FallbackSteps)

Database batching

All pipeline writes must respect PlanetScale limits: 100k rows per statement, 64 MiB result size, 20s transaction timeout.

Operational scripts (not scenario-scoped)

These one-time or maintenance workflows exist in the codebase but don’t warrant standalone scenarios:

Script	Purpose	Frequency
Shopify OAuth callback	One-time token exchange for permanent offline access	Once
Asset backfill	Batch-process existing Dropbox links into R2 (IBEs)	One-time migration
Metafield audit	Compare Dropbox links vs denotation_relation	Ad-hoc diagnostic
Asset retry / cleanup	Retry failed ProcedureExecutions, fix content types, delete old ICEs	Ad-hoc maintenance