Asset Ingest

Overview

Backup and normalize creative assets: a ProcedureExecution (PKO) that ingests from Dropbox, creates an Information Content Entity (IAO) concretized by an R2 Information Bearing Entity, deduplicates by content hash identifier (SHA-256), and establishes a denotation relation to the target MaterialArtifact.

Goal: Reliable asset redundancy and a canonical ICE bearer URL per MaterialArtifact.

Participants

Actor	Ontological type	Role
Staff user	Person (CCO) bearing Role	Submits artifact_identifier + Dropbox URL
Dashboard API Worker	EngineeredSystem (IOF)	Validates, enqueues job
Ingest Worker	EngineeredSystem (IOF)	ProcedureExecution: downloads, uploads, updates
Dropbox public link	External EngineeredSystem	ICE source (IBE carrying design asset)
R2	EngineeredSystem (IOF)	IBE store for design assets
Shopify Admin API	External EngineeredSystem	Metafield update target
PlanetScale	EngineeredSystem (IOF)	IBE store for ICE records + denotation relations

Main success scenario

[PKO: ProcedureExecution with Steps | IAO: ICE concretized_by IBE, denotes MaterialArtifact]

1. Person bearing Role calls POST /api/assets/ingest
2. API validates Access JWT and enqueues ICE_INGEST, returns 202 Accepted
3. Step: Download — Ingest Worker downloads asset from Dropbox link (converts dl=0 → dl=1)
4. Step: Hash — Worker computes content_hash_identifier (SHA-256)
5. Step: Deduplicate — Worker checks information_content_entity.content_hash_identifier for existing match — if found, reuses existing ICE
6. Step: Store — Worker uploads to R2 via binding API (env.R2_BUCKET.put()) — creates IBE
7. Step: Record — Worker upserts:
   • information_content_entity(content_hash_identifier, bearer_entity_key, bearer_entity_url, file_size, content_type, dropbox_url) — the ICE record
   • denotation_relation(artifact_identifier, asset_id) — ICE denotes MaterialArtifact
8. Step: Metafield — Worker updates Shopify metafield custom.production_asset_url with bearer_entity_url

sequenceDiagram
  participant User as Staff (Person bearing Role)
  participant API as Dashboard API (EngineeredSystem)
  participant Q as CF Queue
  participant Ingest as Ingest Worker (EngineeredSystem)
  participant Dropbox as Dropbox (External)
  participant R2 as R2 (IBE Store)
  participant DB as PlanetScale (IBE Store)
  participant Shopify as Shopify API (External)

  User->>API: POST /api/assets/ingest
  API->>Q: enqueue ICE_INGEST
  API-->>User: 202 Accepted + job_id
  Q->>Ingest: deliver
  Ingest->>Dropbox: fetch asset stream
  Ingest->>Ingest: compute content_hash_identifier (SHA-256)
  Ingest->>R2: put(IBE object)
  Ingest->>DB: upsert information_content_entity + denotation_relation
  Ingest->>Shopify: update metafield (bearer_entity_url)

Race condition handling

If two concurrent ProcedureExecutions produce the same content_hash_identifier:

1. First write succeeds (UNIQUE constraint on content_hash_identifier)
2. Second write gets a duplicate key IssueOccurrence
3. FallbackStep: handler catches the error, fetches existing ICE by content_hash_identifier
4. Reuses existing ICE id for the denotation_relation

Exception flows

IssueOccurrence	FallbackStep
Dropbox link invalid/expired	Mark ProcedureExecution failed; no DB writes beyond failure record
R2 upload fails	Retry with backoff; Worker CPU limit allows up to 5 minutes
Shopify metafield update fails	Retry; idempotent (same URL set = safe)
Duplicate content_hash_identifier (race)	Fetch existing ICE, reuse ID for denotation_relation

Queue contract

{
  "job_type": "ICE_INGEST",
  "job_id": "uuid",
  "artifact_identifier": "string",
  "dropbox_url": "string",
  "original_filename": "string",
  "requested_at": "ISO8601"
}

API endpoints

• POST /api/assets/ingest — enqueue ProcedureExecution (p99 < 200ms)
• GET /api/assets/:productId — resolve current canonical denotation_relation for MaterialArtifact
• GET /api/assets/status/:productId — ProcedureExecution status

Acceptance criteria

• PASS: Given artifact_identifier + dropboxUrl, system produces stable bearer_entity_url; denotation_relation exists; Shopify metafield equals the URL
• FAIL: Duplicate ICEs created for identical content_hash_identifier; metafield not updated after retries