Assets Use Cases

The Assets module stores the files a business owns (product photos first, brand logos and AI-generated images later) and tells every other module how to show them, without any business domain ever persisting a storage URL, a bucket, an object key or a provider credential. This document follows the structure of CATALOG_USE_CASES.md: numbered cases (AS1… for the Assets side, AC1… for the Catalog side of the link), routes, statuses, codes, the decisions behind them, the schema changes they need, and the slices that build them. Status: built through A6. Stages A1a to A6 (A4b included) are built and each has an "as built" note in §14.1; the module lives in src/modules/assets and the media worker in src/media-worker.ts. A7 and A8a to A8d are specified and blocked on the personal-data policy (OD15), and the erasure trigger (OD23) is not built. The owner's infrastructure stage A0 is recorded per environment in ASSETS_INFRASTRUCTURE_RUNBOOK.md §0.4. Where a design section and an "as built" note differ, the note says what the code does.

Ground truth. database/canonical/0070_assets.sql (line numbers below refer to that file unless another file is named), catalog.item_assets in database/canonical/0080_catalog.sql:615-726, database/access/runtime_grants.sql, database/canonical/0060_platform.sql (plan limits), database/canonical/0360_events.sql (tenant outbox), .railway/railway.ts, src/foundation/config/schema/environment-variables.schema.ts, src/worker/worker.module.ts, src/foundation/logging/redaction/**, src/foundation/telemetry/pipelines/node-instrumentation.ts, src/modules/catalog/**, tooling/repository/check-case-matrix.ts; AGENTS.md; docs/reference/ARCHITECTURE.md, DOMAIN_MAP.md, DECISIONS.md (D18, D24, D26, D30), OUTBOX_USE_CASES.md, SUBSCRIPTION_PLANS_USE_CASES.md, BUSINESS_DESIGN.md §4, CATALOG_USE_CASES.md; docs/contracts/MODULE_CONTRACTS.md, API_AND_SCHEMA_DISCIPLINE.md, FOUNDATION_HTTP_AND_OBSERVABILITY.md. External facts cite their source in section 18.

Status words used below. Decided means this document takes the decision because repository facts back it, and the owner only needs to object. Recommended means the owner must answer; each one is an OD row in section 15 with a recommended default, so "yes, use the recommended values" closes them all. Proposed means a shape this document suggests for a later slice, to be confirmed when that slice is designed in detail. Assumption means a fact this document could not verify.

---

Contents

1. Purpose and scope
2. Ownership and boundaries
3. Infrastructure that exists today
4. Table traceability and schema gaps
5. Domain model and state machines
6. Design decisions
7. Use cases
8. Derived API
9. Vertical variations
10. Authorization and plan
11. Security
12. Performance and data design
13. Infrastructure plan (AWS, Cloudflare, OpenAI, Railway)
14. Delivery slices
15. Owner decisions
16. Risks and what the existing SQL gets wrong or leaves open
17. Planned case matrix
18. Sources
19. Glossary

---

1. Purpose and scope

1.1 What Assets is for

Assets answers two questions for every other module: "is this file id mine, and is it usable?" and "how does a client show it?". It owns the logical file (assets.assets), its renditions (assets.asset_variants), the physical copies (assets.storage_objects) and the provider definitions (assets.storage_providers). The meaning of a file (a dish photo, a brand logo, a payment receipt) belongs to the module that references it: the header of 0070_assets.sql:18-24 says product/menu image semantics belong to catalog/commerce, brand logos to organization/commerce, and "CDN/public delivery URLs -> delivery layer/config".

Business	What it needs on day one	What it does NOT need
Small restaurant	A photo per dish and drink, shown on the till tile and on a digital menu later; uploaded from a phone	Galleries of many photos, documents, video
Retail shop	A photo per product, sometimes per variant (the red shirt vs the blue shirt); bulk upload later	Video, 3D, PDFs of spec sheets (later)
Hotel	Photos of sellable extras (minibar, spa) as catalog items; room photos belong to Hospitality later	Room-type galleries now

1.2 In scope for the first delivery

Decided:

1. Image upload by an organization-wide member, directly from the client to AWS S3 with a short-lived presigned POST whose policy bounds key, type and size; the API never receives the bytes (§6.2).
2. Server-side verification and sanitization by the media-worker: the uploaded bytes are sniffed, decoded under pixel limits, re-encoded into a metadata-free master, and never served as uploaded (§6.3, §11).
3. Renditions (thumbnail, tile, card, detail) generated by the worker from a job queued in the same transaction as the upload completion (D26 pattern).
4. Public delivery of public assets through immutable, unguessable, cacheable URLs on Cloudflare (R2 public bucket, §6.1, §6.4).
5. A media library: read one asset, list, rename, archive, restore.
6. The Catalog link: set the images of an item and of a variant (catalog.item_assets), images in the item read (C3) and the till read (C17/C19).
7. Two in-process contracts other modules consume: attachability and delivery (§6.6).
8. Plan capability and limits, quotas and abandoned-upload cleanup.

1.3 Explicitly out of scope, with the reason

Out of scope	Reason	Where it goes
Private and sensitive delivery (signed GET URLs)	No first-delivery consumer stores private files; the only existing sensitive consumer, audit.export_artifacts, requires access_class = 'sensitive' (0380_audit.sql:2148-2152) but audit export is not built	Slice A7 (AS14), designed here, blocked until the residency sign-off (OD15)
AI-generated images (OpenAI GPT Image)	Fully designed (§6.7) but built after the first delivery, once OD15 and OD17 are answered	Slices A8a–A8d (AS15, AS16, AC6)
Documents (PDF), video, audio	Need content disarm or malware scanning before any serving (OWASP, §11) and different renditions; duration_ms exists (0070:177) but no consumer needs it now	Later, with its own design
SVG	Script and XXE risk (OWASP); forbidden (OD4)	Not planned
Import from a URL	Server-side fetch is an SSRF surface (§11)	Later, behind an allow-listed fetcher
Animated images	First frame only (§6.3)	Later if a storefront needs it
Content-hash deduplication	Saves little storage at these sizes (§12.3) and cross-tenant dedup leaks existence	Per-organization hint later (SG10)
Brand logos, storefront assets, payment evidence, delivery proofs	Their owning modules are not built; they reference assets.assets by FK already (§2.4)	Each consumer's own slice, reusing AS1–AS13
Image editing (crop, rotate) in the server	The client crops before upload; the worker only auto-orients	Not planned

---

2. Ownership and boundaries

2.1 Facts Assets owns

• the logical identity of a file: id, organization, display name, original filename (metadata only), access class, lifecycle (0070:84-133);
• its renditions and their immutable content facts: media type, byte size, SHA-256, dimensions (0070:156-159, protected by protect_asset_variant, 0070:644-716);
• where each rendition physically lives (storage_objects, 0070:389-511) and which provider holds it (storage_providers, 0070:318-371);
• new (§4.2): upload intents, processing jobs and per-organization usage;
• later: generation requests (AI provenance).

2.2 Neighbours

Neighbour	Direction	What crosses	Mechanism
Identity	Assets consumes	Permission decision	PermissionCheckContract / OperationAuthorizationContract
Platform	Assets consumes	Capability assets.media, limits	OperationAuthorizationContract; platform.effective_limit read in SQL inside the usage lock (as identity.assert_membership_seat_available does, 0040_identity.sql:2103-2129)
Audit	Assets consumes	Tenant audit records	TenantAuditContract
Catalog	Consumes Assets	"Are these asset ids mine, ready, public?" and "give me delivery for these ids"	AssetUsageContract, AssetDeliveryContract (§6.6) inside the caller's tenant transaction (D18)
Media worker process (media-worker, OD14)	Executes Assets jobs and sweeps	Claim one job, record outcome, expire uploads, purge	SECURITY DEFINER functions granted to ninaku_worker only (D26, OB6)
Object storage (AWS S3 for uploads and masters, Cloudflare R2 for public renditions, OD1)	Assets infrastructure	Sign POST policies (API, local computation), read/write objects (media worker)	ObjectStoragePort in assets/application/ports, adapter in assets/infrastructure
Every other module with an FK to assets.assets (§2.4)	Consume later	Same two contracts	No new mechanism

2.3 Module contracts (R1 to R9)

Decided. The module lives at src/modules/assets/ with the standard layers (ARCHITECTURE.md §6; ARCHITECTURE.md:112 already lists modules/assets/ in the target layout).

Rule	Consequence for Assets
R1	Assets imports only identity/contracts, platform/contracts, audit/contracts. Catalog imports only assets/contracts, never the opposite: Assets never knows who references an asset (DOMAIN_MAP.md:37: "no obligar a conocer significado de todos sus consumidores")
R2, R6, R7	Use cases open the tenant transaction; repositories run SQL; the storage SDK lives only in infrastructure/
R3	Pure domain: media-type allow-list, magic-byte sniffing, dimension rules, rendition profile, state transitions, object key layout
R4	The storage adapter is Assets' own infrastructure, not foundation/: only Assets touches storage. If a second module ever needs raw object storage, the wrapper moves to foundation/ then (AGENTS.md §4, "three copies" rule)
R9	No system transaction in Assets: the API always runs with tenant context; the worker reaches the database only through SECURITY DEFINER functions as ninaku_worker, exactly as the Identity security outbox does (runtime_grants.sql:177-181)

Published contracts (section 15 of MODULE_CONTRACTS.md lists them in the same change that publishes them): AssetUsageContract (src/modules/assets/contracts/asset-usage.contract.ts) and AssetDeliveryContract (src/modules/assets/contracts/asset-delivery.contract.ts).

2.4 Schema boundary and existing cross-schema SQL

• The API cannot reach the schema. runtime_grants.sql:36 grants USAGE only on reference, identity, organization, platform (catalog is added at :116, audit at :130); nothing on assets. ninaku_worker has only the Identity outbox functions (:177-181).
• Fourteen tables already reference assets.assets by a tenant-safe composite FK (asset_id, organization_id) (counted with rg 'REFERENCES assets\.'): catalog.item_assets (constraint at 0080:660, REFERENCES at 0080:665), commerce.storefront_assets (0100:374), payments.payment_evidence (0130:1349), fulfillment.handoff_proofs (0160:2347), tax.party_exemptions (0260:909), documents.template_assets (0310:263), documents.render_snapshots (0310:609), printing.print_content_snapshots (0320:638), communications.message_revision_attachments (0340:564), sync.bootstrap_sessions.snapshot_asset_id (0370:523), audit.export_artifacts (0380:782), two analytics tables (0390:531, 0390:1551) and fiscal qualification evidence (0400:625). Asset identity is load-bearing: an asset id is never reused and a referenced asset is never purged (§6.8, AS10).
• None of those FKs has ON DELETE, so PostgreSQL refuses to delete a referenced assets.assets row (23503); AS10 uses the DELETE's own 23503, caught inside its SECURITY DEFINER function, as its reference check, so Assets never lists or probes its consumers (no pg_constraint enumeration).
• Invariant (Decided): every consumer attaches an asset only through AssetUsageContract.assertAttachable (AS13), inside its own command's transaction. That is what lets AS10 mark an asset purging under a row lock and be sure no new reference appears afterwards; a consumer that inserts an FK row without the contract breaks erasure, so each consumer's slice carries a test that its attach path calls the contract.
• assets.assets has the unique (id, organization_id) that makes those composite FKs tenant-safe (0070:127-132).

---

3. Infrastructure that exists today

Fact	Evidence	Consequence
Railway runs four resources: postgres, database-migrator, api, worker	.railway/railway.ts:186-189	No storage resource is declared; adding buckets is an owner-approved infrastructure change (AGENTS.md §10)
api and worker each run one replica	railway.ts:127, :161	Image processing inside the API would compete with every request on one process; it goes to the worker (D26)
The worker is the same codebase with entrypoint node dist/worker, role ninaku_worker; it hosts only the Identity security outbox dispatch (OTP codes, invitations) and declares no memory limit	railway.ts:151-184, src/worker.ts, src/worker/worker.module.ts:8-18	A sharp out-of-memory crash there would delay sign-up and recovery codes. Image processing runs in a separate Railway service media-worker (same image, entrypoint node dist/media-worker, its own memory budget, OD14), with its own MediaWorkerModule
Scheduled sweeps run in the API process today	SubscriptionLifecycleSweepJob is registered in src/modules/platform/platform.module.ts:57,157, not in the worker	Assets sweeps (AS9) run in media-worker, copying that job's advisory-lock discipline, not its process
No storage, bucket, CDN or image variable exists	environment-variables.schema.ts:186-232 lists database, telemetry, AWS SES (:213-216), outbox settings; nothing for storage	New variables (§13.6, A0)
AWS credentials exist for SES only	railway.ts:140-142, @aws-sdk/client-sesv2 in package.json:67	The AWS SDK v3 family is already a dependency; @aws-sdk/client-s3 and @aws-sdk/s3-presigned-post talk to Amazon S3 for uploads and masters, and the same client-s3, configured with R2's endpoint, writes only the public renditions to R2. Storage credentials are separate variables, never the SES keys
No image library is installed	package.json dependencies (no sharp); multer appears only as an overrides pin (package.json:131-133)	sharp is a new worker dependency (§6.3), justified under NESTJS_STACK_GUIDE.md §1
Database timeouts: statement 5,000 ms, lock 2,000 ms, idle in transaction 10,000 ms	environment-variables.schema.ts:186-189	No transaction may stay open while bytes move or images decode (§6.3)
No JSON body limit override	no useBodyParser/bodyParser call under src/bootstrap (searched); Express' body-parser defaults to 100kb (source S16)	Bytes through the API would need multipart and a raised limit (§6.2)
Default rate limit 120 requests/minute per client IP	src/foundation/http/rate-limiting/rate-limit.ts:1-3	Upload intents get a stricter @Throttle plus a database cap (AS1)
CORS allows only the docs origins	railway.ts:24-41; FOUNDATION_HTTP_AND_OBSERVABILITY.md §13	The bucket's own CORS policy, not the API's, governs browser POST uploads (§6.4, §13.5)
Span exporter redacts X-Amz-Signature, X-Amz-Credential, X-Amz-Security-Token, X-Goog-Signature query params	src/foundation/telemetry/pipelines/node-instrumentation.ts:15-30	Signed URLs in spans are covered
Log redaction of query params does not cover X-Amz-Signature	redaction.ts:27-33 uses sensitive-field-names.ts:1-30: credential and token match, signature does not	Gap SEC-1 (§11): A2a adds it before any presigned URL exists
The tenant outbox events.outbox_records exists, unused, with no grant to anyone	0360_events.sql:202-234; OUTBOX_USE_CASES.md OX-W1 decision row	OD7 decides whether Assets jobs use it or a module-owned queue

---

4. Table traceability and schema gaps

4.1 Existing tables

Table (line)	Class	Reason
assets.assets (84)	USE NOW	The logical file. Columns used: all. Missing lifecycle columns (SG1–SG5)
assets.asset_variants (162)	USE NOW	original (sanitized master) and the p1-* renditions; its state machine (0070:674-706) supports retry from failed
assets.storage_objects (389)	USE NOW	One primary per variant; available at verification; deleted together with its variant and asset by the purge (SG16), never walked through deleting
assets.storage_providers (318)	USE NOW	Two seeded rows (OD1): s3-private (adapter s3: in/, m/, p/ prefixes) and r2-public (adapter cloudflare_r2); configuration_ref names the environment prefix, never a secret (0070:310-312)
catalog.item_assets (0080:623)	USE NOW (A5b)	Item- and variant-level images, primary/gallery, sort_order; one primary per item and per variant (0080:702-716)

4.2 Schema gaps (exact proposed changes)

Nothing is added to the database in this task. Each gap names the change a later migration makes, and why.

#	Gap	Evidence	Proposed change (migration)	Why
SG1	assets.assets has no lifecycle status: readiness can only be derived by joining variants and storage objects	0070:84-133: only created_at, archived_at	status varchar(20) NOT NULL DEFAULT 'pending', CHECK (status IN ('pending','processing','ready','failed','purging')) (purging: SG16); ready_at timestamptz, failed_at timestamptz, failure_code varchar(80); assets_status_state_chk: pending/processing ⇒ both null; ready ⇒ ready_at NOT NULL AND failed_at IS NULL; failed ⇒ failed_at NOT NULL AND ready_at IS NULL AND failure_code IS NOT NULL. A deferred constraint trigger asserts that a ready asset has its original and every variant of its rendition profile ready. archived_at stays independent (an archived asset keeps its status)	The delivery hot path (C17) must read one row per asset, never a three-table join (§12.2)
SG2	No delivery identifier: a public URL would have to expose the asset id or the object key	—	delivery_token varchar(26) NOT NULL, CHECK (delivery_token ~ '^[a-z2-7]{26}$') (128 random bits, base32), UNIQUE (delivery_token)	Unguessable, tenant-free public paths; the asset id and organization never appear in a URL (§6.4)
SG3	No rendition profile	—	rendition_profile smallint NOT NULL DEFAULT 1 CHECK (rendition_profile > 0)	A ready asset has every rendition of its profile, so delivery derives URLs with no variant join; a new profile regenerates under new codes without breaking old immutable URLs (§6.3)
SG4	No media kind	—	media_kind varchar(20) NOT NULL DEFAULT 'image' CHECK (media_kind IN ('image'))	Consumers (Catalog) require images; documents later widen the check
SG5	No provenance or creator	—	source_kind varchar(20) NOT NULL DEFAULT 'upload' CHECK (source_kind IN ('upload','ai_generated')) (SG21); created_by_membership_id uuid FK (created_by_membership_id, organization_id) → identity.memberships (id, organization_id) (the tenant-safe pair memberships_id_organization_uq, 0040_identity.sql:570)	AI provenance hook (§6.7) and "who uploaded this" in the library
SG6	No upload intent	—	New table assets.uploads: id uuid PK, organization_id uuid NOT NULL, asset_id uuid NOT NULL (FK (asset_id, organization_id), UNIQUE (asset_id)), staging_provider_id uuid NOT NULL FK providers, staging_object_key varchar(1024) NOT NULL, declared_media_type varchar(255) NOT NULL, declared_byte_size bigint NOT NULL CHECK (> 0), state varchar(20) NOT NULL DEFAULT 'issued' CHECK IN ('issued','received','verified','rejected','expired'), expires_at timestamptz NOT NULL, received_at, settled_at timestamptz, rejection_code varchar(80), creation_idempotency_key uuid NOT NULL, creation_request_hash text NOT NULL CHECK (creation_request_hash ~ '^[0-9a-f]{64}$') (the exact shape of migration 0081_catalog_creates_remember_their_request.sql:8-13), created_at; UNIQUE (organization_id, creation_idempotency_key); UNIQUE (staging_provider_id, staging_object_key); partial index (expires_at) WHERE state IN ('issued','received'); state-shape check like storage_objects_state_chk; RLS select/insert/update by organization (scalar subquery, API_AND_SCHEMA_DISCIPLINE.md §4)	Idempotent intent (FOUNDATION_HTTP_AND_OBSERVABILITY.md §7: the claim lives in the module's own table), expiry sweep, declared-vs-verified comparison. The staging object is not a storage_objects row: it is never a rendition and never served
SG7	No processing queue	0070:25 says "Worker queue execution -> BullMQ/workers", which D26 superseded	New table assets.processing_jobs (OD7): id uuid PK, organization_id, asset_id (FK), job_kind varchar(40) CHECK IN ('process_upload','render_profile','purge_asset') (generate_image added by A8a, SG21) (upload expiry is a sweep, AS9, not a job), state varchar(20) CHECK IN ('pending','leased','completed','dead_lettered'), available_at, lease_owner, lease_token uuid, lease_expires_at, attempt_count integer >= 0 (the total of every retry), processing_error_count integer >= 0 (processing errors only, the dead-letter budget; R1, 0093), last_error_code varchar(80), completed_at, created_at, updated_at; lease-shape check copied from evt_outbox_lease_shape_chk (0360:221-226); claim index (job_kind, available_at) WHERE state IN ('pending','leased') and error_class varchar(20) (storage, processing, permanent) recording the retry class (the stage specification is authoritative, ASSETS_STAGE_SPECS.md §4); UNIQUE (asset_id, job_kind) WHERE state IN ('pending','leased') so a job is never queued twice. No runtime SELECT; enqueue only inside assets.complete_upload(...) (SECURITY DEFINER, EXECUTE to ninaku_runtime); claim/record through assets.claim_processing_job(owner, lease_token, lease_seconds, job_kinds) (one job per call, of the kinds the calling loop handles, so a lease never covers work queued behind it) and assets.record_processing_outcome(...) (EXECUTE to ninaku_worker only)	D26/OB6: the API enqueues, only the worker dispatches; claim with FOR UPDATE SKIP LOCKED + lease (OX-W1–W3)
SG8	No usage counter: a quota check would sum every variant of the organization on each upload	—	New table assets.organization_usage (organization_id PK FK, active_asset_count integer NOT NULL DEFAULT 0, stored_bytes bigint NOT NULL DEFAULT 0, reserved_bytes bigint NOT NULL DEFAULT 0, updated_at), non-negative checks; row created by a trigger on organization.organizations insert and backfilled (the catalog_versions pattern, "K1 as built"); maintained only by SECURITY DEFINER functions (intent reserves declared bytes, outcome converts to verified bytes). Semantics (Decided): active_asset_count counts assets in pending, processing or ready that are not archived (failed, archived and purging assets do not count); stored_bytes counts every byte physically stored (archived assets included until purged); verified bytes (master + renditions) can exceed the declared upload size, so the storage quota is soft by that delta, at most a few MiB per asset. Reconciliation: assets.reconcile_usage(organization_id) recomputes the three counters from rows; purge and the nightly sweep call it instead of subtracting, so a counting bug in a release corrects itself instead of tripping the >= 0 check and failing the purge	O(1) quota check under a row lock, the per-organization serialization point for uploads
SG9	A failed variant has no reason	0070:250-274: failed only needs failed_at	asset_variants.failure_code varchar(80), required when status = 'failed' (extend asset_variants_state_chk)	The library shows why processing failed (assets.content_mismatch, assets.image_too_large, …)
SG10	No per-organization content lookup	—	Proposed, not v1: index (organization_id, checksum_sha256) WHERE lower(variant_code) = 'original'	A later "you already uploaded this photo" hint; never across organizations
SG11	catalog.item_assets is unreachable and invisible to the till ETag	No grant (runtime_grants.sql:117); item_assets is in the K1 contract test's unreachable list (database/tests/contracts/catalog-foundations-contracts.ts:45-57); the eleven version-bump tables of 0075_catalog_foundations.sql:60-112 exclude it	Catalog migration (A5b): GRANT SELECT, INSERT, UPDATE, DELETE ON catalog.item_assets TO ninaku_runtime; statement-level catalog.bump_catalog_version() triggers on item_assets insert/update/delete; index item_assets_organization_asset_idx (organization_id, asset_id)	Set-based image writes (AC1, AC2); C17's 304 must stop matching after an image change; the purge's foreign-key check and "where is this asset used" need an index leading with asset_id (today only (item_id, asset_id) and (item_variant_id, asset_id) partial uniques exist, 0080:688-700)
SG12	Library keyset order lacks a tiebreak	assets_organization_active_idx (organization_id, created_at DESC) WHERE archived_at IS NULL (0070:135-140)	Replace with (organization_id, created_at DESC, id DESC) WHERE archived_at IS NULL and add the archived twin, after EXPLAIN (ANALYZE, BUFFERS)	Keyset (created_at DESC, id DESC) (AGENTS.md §5.3)
SG13	No updated_at on assets.assets	0070:84-133	None: the application never needs it; the library item ETag is a content hash (D24)	Avoids a column with no reader (API_AND_SCHEMA_DISCIPLINE.md §3)
SG14	Physical erasure has no path for the runtime	No DELETE policy (0070:952-960)	assets.purge_asset_begin(job, lease) and assets.purge_asset_finish(job, lease), SECURITY DEFINER, EXECUTE to ninaku_worker only (AS10, slice A4b)	Retention and erasure without giving any role DELETE
SG15	Free text has no NUL or length discipline in SQL	original_filename varchar(500), display_name varchar(500) (0070:88-89)	None in SQL; the application applies trimmedBoundedText (≤255, rejects NUL, AGENTS.md §4)	One rule in the HTTP schema, as Catalog does
SG16	No terminal state while an asset is being erased: storage objects cannot move to deleting while their variant is ready (a ready variant needs an available primary at commit, 0070:883-949, and can never leave ready, 0070:657-672)	0070:657-672, :883-949	Add 'purging' to the SG1 status check (terminal: no transition out). AS6 restoration and AS13 assertAttachable refuse it; describe returns no URLs for it. Storage rows stay untouched until the provider delete is confirmed; purge_asset_finish deletes storage objects, variants, upload, jobs and the asset in one transaction, which satisfies both deferred triggers (a deleted variant has no primary to assert, a deleted asset no original)	Erasure that never breaks the existing invariants and cannot race a restore or an attach (A4b)
SG17	access_class can be updated freely	assets_update_policy (0070:982-992) allows any column	BEFORE UPDATE OF access_class trigger refusing any change (assets_access_class_immutable, 23514)	Switching public ↔ private means moving objects between buckets and purging the CDN; a new class is a new asset
SG18	Nothing guards assets.status transitions	SG1 adds the column	BEFORE UPDATE OF status trigger allowing only pending → processing → ready, pending/processing → failed, failed → processing (retry), ready/failed → purging; archived_at cannot be cleared while purging	The runtime never writes status (§14, A1a grants); the trigger is the backstop for the definer functions

4.3 Contradictions between the existing schema and this design

#	Contradiction	Resolution
X1	0070:25 assigns worker queues to "BullMQ/workers"	D26 (PostgreSQL queue, separate worker, never BullMQ) wins (AGENTS.md order: DECISIONS.md ranks above a canonical comment); the comment cannot be edited cheaply because lint:no-comments keeps a shrink-only allowlist (AGENTS.md §4); record only
X2	access_class defaults to private (0070:91), while product images must be public	The upload request carries accessClass explicitly (no default in the API); Catalog refuses non-public assets (AC1). The SQL default stays as the safe fallback
X3	"Every Asset has exactly one logical original Variant" (0070:146) assumes the original is the uploaded file	Decided: original is the sanitized master (re-encoded, metadata stripped, ≤ 4,096 px). The raw upload is a staging object, never a variant (§6.3). The content facts still "describe exact bytes" (0070:156-158)
X4	asset_variants_asset_code_ci_uq (0070:283-287) forbids a second tile for the same asset, and ready content is immutable (0070:657-672)	Rendition codes carry the profile (p1-tile), so a profile 2 adds p2-tile beside it; old URLs stay valid
X5	A ready variant needs an available primary storage object at commit (0070:937-949)	The worker function inserts the storage object (available, verified_at) and marks the variant ready in one transaction: compatible

---

5. Domain model and state machines

5.1 Aggregates

Aggregate	Root	Inside	Consistency boundary
Asset	Asset (assets.assets)	Rendition (variants), StoredCopy (storage objects), Upload (1:1 while it lives)	One asset changes in one transaction; the worker changes it only through its SECURITY DEFINER functions
Organization usage	OrganizationUsage (assets.organization_usage)	counters	Locked FOR UPDATE first by every command that reserves or releases bytes (lock order §7)
Processing job	ProcessingJob	lease, attempts	Claimed with SKIP LOCKED; never locked by the API

5.2 Identifiers, codes and keys

Field	Rule	Source
ids	UUIDv7 generated by the application	0070:52
delivery_token	26 lowercase base32 characters from 16 bytes of crypto.randomBytes	SG2
variant codes	original, p1-thumbnail, p1-tile, p1-card, p1-detail; pattern ^[a-z][a-z0-9_-]{0,79}$	0070:193-196
object keys	server-generated only, never from user input: staging in/<upload token> (S3); master m/<delivery token>/original.webp (S3); public renditions a/<delivery token>/p<profile>/<rendition>.webp (R2 public bucket); private renditions p/<delivery token>/p<profile>/<rendition>.webp (S3). <rendition> is the variant code without its profile prefix: variant p1-tile lives at a/<token>/p1/tile.webp, so the till's imageRef (<token>/p1) and the template …/a/{imageRef}/tile.webp (§6.4) name exactly that object	0070:379; OWASP "change the filename to something generated by the application" (S9)
no organization prefix	Decided: keys never carry the organization, so an organization's objects cannot be deleted by prefix. Offboarding purge is database-driven: it enumerates the organization's storage_objects through storage_objects_organization_idx (organization_id, asset_variant_id) (0070:535-539) and runs AS10 per asset (a staff command after the organization is archived, designed with A4b, built when offboarding is)	Accepted cost: no tenant identifier in any URL
display_name, original_filename	trimmedBoundedText, ≤255, NUL rejected, control characters stripped; metadata only, never in a key, a URL or a header	SG15

5.3 Asset state machine (SG1)

           completion (AS2)          worker verifies + renders (AS7)
 pending ───────────────────▶ processing ───────────────────────▶ ready
    │                             │   ▲                              │
    │ intent expires (AS9)        │   └─ transient error: retry ─────┘ (never leaves ready)
    ▼                             ▼
  failed ◀──────────── permanent error or retries exhausted (AS8)

 ready or failed ── purge begins, nothing references it (AS10) ──▶ purging ──▶ row deleted
 archived_at is orthogonal: archival (AS6) sets it on any status but purging;
 restoration clears it, never on a purging asset. purging is terminal (SG16).

Asset status	Original variant	Rendition variants	Upload state	Job
pending	pending	none yet	issued	none
processing	pending → processing	processing (inserted by the worker)	received	process_upload pending/leased
ready	ready (master, S3 m/)	all of profile 1 ready	verified	completed
failed	failed (failure_code)	failed or absent	rejected or expired	completed or dead_lettered
purging	unchanged (ready or failed)	unchanged	unchanged	purge_asset pending/leased

5.4 Variant and storage object machines

Variants use the existing transitions (0070:674-706): pending → processing → ready | failed, failed → pending | processing (retry); ready is final and immutable. Storage objects use theirs (0070:819-864) only for pending → available. Decided: the worker inserts storage objects directly as available after it has written and re-read the object (one row per variant, role primary). Purge never walks storage objects through deleting/deleted: while the variant is ready that would break assert_variant_has_primary_storage (0070:883-910); instead the rows are deleted together with their variant and asset in AS10's final transaction.

5.5 Rendition profile 1

Recommended (OD3):

Code	Geometry	Format	Purpose	Approx. size (assumption)
original	fit inside 4,096 × 4,096, never enlarged	WebP q90 (alpha kept)	Master for regeneration; S3 m/; never served publicly	300 KB–1.5 MB
p1-thumbnail	160 × 160 cover, attention crop	WebP q80	Back-office lists	5–10 KB
p1-tile	320 × 320 cover, attention crop	WebP q80	Till tile, offline cache	15–30 KB
p1-card	fit inside 640 × 640	WebP q80	Item detail panel, storefront card	40–80 KB
p1-detail	fit inside 1,280 × 1,280	WebP q82	Zoom, storefront detail	120–250 KB

WebP is chosen over AVIF for v1 because sharp's default AVIF effort is far slower per image and WebP decodes everywhere the clients run (S6); AVIF can be profile 2. sharp's WebP default is quality 80, effort 4 (S6).

---

6. Design decisions

Each decision states the alternatives, the tradeoffs, the default and the facts behind it.

6.1 Storage and delivery architecture (Recommended, OD1 — changed)

Owner input (2026-10-06). The owner already operates AWS (SES sends the security emails; the repository holds AWS credentials for SES only, railway.ts:140-142, environment-variables.schema.ts:213-216) and Cloudflare (DNS and CDN), and wants S3 used. The earlier default (R2 for everything) is replaced by an evaluation of four architectures.

Option	Storage	Delivery path	Origin authentication	Extra component	Consoles to run
A	S3	Media domain proxied by Cloudflare, origin S3	Cloudflare's Cloud Connector routes to S3 but "only supports public buckets" (S23); a private bucket needs a Cloudflare Worker that signs SigV4 requests (aws4fetch, S42). An IP allow-list of Cloudflare ranges or an aws:Referer secret in the bucket policy are brittle or weak	A Worker on every media request (Workers run before the cache and every request is billed, S24)	AWS, Cloudflare
B	S3	AWS CloudFront with Origin Access Control; the media hostname's DNS record in Cloudflare is DNS-only (not proxied)	OAC, native	CloudFront distribution	AWS, Cloudflare (DNS only)
C	R2 only (previous version)	R2 custom domain on Cloudflare	Native	None	Cloudflare, plus AWS for SES
D	S3 for the system of record (upload inbox, masters, private renditions) and R2 only for public renditions	R2 custom domain on Cloudflare (S3 is never on the delivery path)	S3 never public; R2 public bucket served natively	None (both are S3 APIs: one adapter, two configurations, 0070:302-308 already models several providers)	AWS, Cloudflare

Monthly cost (USD) by option. Prices: S3 $0.023/GB-month, GET $0.0004/1k, egress $0.09/GB after 100 GB free (S10); CloudFront 1 TB and 10 M requests free, then South America $0.110/GB and $0.022 per 10k HTTPS requests (S25), origin fetches from S3 free (S25); Workers Paid $5/month, 10 M requests included, $0.30/M after, cached requests billed (S24); R2 $0.015/GB-month, free egress, 10 M Class B free (S1). Assumptions: 25 KB average delivered object, 95% Cloudflare cache hit ratio, masters ≈ 70% of stored bytes, and the worker reads each upload from S3 once (≈ 3 MB).

Profile	Stored	Served/month	A: S3 + Cloudflare Worker	B: S3 + CloudFront	C: R2 only	D: S3 + R2 public
Small restaurant	0.3 GB	5 GB, 0.2 M requests	≈ $0 (Workers Free 100k/day, S24)	≈ $0 (free tier)	≈ $0	≈ $0
Retail, 50,000 images	50 GB	100 GB, 4 M requests	≈ $6 ($1.15 S3 + $5 Workers)	≈ $1.15	≈ $0.60	≈ $0.90
Platform, 1,000 organizations	2 TB	5 TB, 200 M requests	≈ $129 ($46 S3 + $13.5 egress on misses + $4 GETs + $62 Workers requests + ≈ $3 Workers CPU)	≈ $916 pay-as-you-go ($46 storage + 4,096 GB × $0.110 = $451 data + $418 requests) or the $1,000 Premium flat plan (S25)	≈ $30	≈ $46 ($32 S3 + $9 R2 + ≈ $4.5 S3 egress for the worker reading uploads, assuming ≈ 150 GB/month of uploads after the 100 GB monthly free allowance)

Free tiers belong to the account, not to each tenant, so only the platform row predicts the bill at scale.

Recommendation: D. It is not the cheapest: C (R2 only) costs about $30 against D's $46 at platform scale. D is chosen because the owner wants S3 used, and S3 is the only one of the two with POST policies that bound the upload size at the storage layer (§6.2) and IAM policies scoped by key prefix; D keeps that for uploads and masters while putting no AWS egress on the delivery path, needing no extra edge component and no origin-authentication trick. Cloudflare stays the single CDN, DNS and WAF the owner already runs.

D's costs beyond the table (master re-reads, note 21). Every time the worker re-reads masters from S3 it pays S3 egress to the internet ($0.09/GB after 100 GB/month, S10): a profile-2 regeneration of the platform's ≈ 1.4 TB of masters costs ≈ $126 once; AI "enhance" re-reads one master (≈ 1 MB) per request (≈ $1.80 per 20,000 requests). Railway's own egress for the worker's writes to S3 and R2 is unverified (Railway pricing not fetched).

Fallbacks, if the owner rejects R2: A (Cloudflare remains the CDN; about $129/month at platform scale, a Worker to own); B (documented, AWS-only delivery, ≈ $916/month at platform scale because CloudFront's South American egress and request prices dominate).

AWS region (Recommended, OD1). us-east-1. Its S3 prices are the ones quoted (S10); sa-east-1 is the only South American region and costs more per GB (assumption: about 1.7×, not fetched); round-trip time from Bogotá and Quito to Northern Virginia is lower than to São Paulo (assumption: no AWS-published figure fetched; A0 measures it from a phone on the tills' networks). Region matters only for uploads and the worker: public delivery goes through Cloudflare's edge. SES's region is the value of AWS_REGION, a preserved secret this task cannot read (the SES spec uses us-east-1 only as a test value, ses.connector.spec.ts:24); S3 gets its own variable, ASSETS_S3_REGION, so the two never depend on each other.

S3 layout (Decided): one bucket per environment, prefixes and IAM per principal. R2 needed three buckets because its tokens are scoped per bucket (S21); S3 IAM policies are scoped by key prefix, and lifecycle rules filter by prefix (S29), so one bucket per environment is enough:

Prefix (bucket ninaku-<env>-assets)	Holds	Writers	Readers	Lifecycle
in/	Raw uploads	Browser POST signed by the API principal	media-worker	Expire after 1 day; abort incomplete multipart after 1 day (S29)
m/	Masters (m/<token>/original.webp) and AI provider originals	media-worker	media-worker	None
p/	Private renditions (A7)	media-worker	API presign (A7)	None

Settings: Block Public Access on (all four settings), Object Ownership "Bucket owner enforced" with ACLs disabled, which is the default for new buckets (S28); default encryption SSE-S3, applied to every new object at no cost since 2023-01-05 (S27); SSE-KMS rejected for v1 (KMS charges and request quotas apply, S27, with no requirement that needs customer-managed keys); versioning off (keys are immutable and never overwritten after ready, and erasure must really delete: versioning would keep noncurrent copies); server access logs off in v1 (CloudTrail management events cover configuration changes; data events are billed per event and not justified until a private or sensitive file exists, A7). S3 Event Notifications are not used: the completion call (AS2) already enqueues the job in the same transaction as the state change (D26), while an event pipeline would add SQS, a consumer and a reconciliation between two queues.

R2 public bucket (ninaku-<env>-media-public). Written only by the media worker (a token scoped to this bucket, S21), served at the media domain (OD13) with Cloudflare cache, r2.dev disabled in production (R2-PB).

Regional/legal. Product photos are not personal data by design; EXIF (GPS, device) is stripped (§6.3). Masters sit in us-east-1, public renditions in R2 with location hint enam (S5). Assumption: neither Colombian nor Ecuadorian law requires in-country storage of product images. A legal sign-off is required before any private or sensitive file ships and before tenant data is sent to OpenAI (OD15); A7 and A8 stay blocked until it is answered.

6.2 Upload flow (Decided except limits, OD5)

The client never sends bytes through the API. Reasons (repository facts): the API runs one replica (railway.ts:127); Express' JSON parser accepts 100 kB by default (S16) and the API parses no multipart today; Railway closes uploads that take over 5 minutes and limits idle transfers (S13); decoding in the request process is exactly the saturation D26 moved out of the API. Even "small images through the API" would need multipart parsing, a raised limit and memory per request, for an image that must still go to storage and be decoded by the worker: no gain.

client                    API (tenant tx)                 S3 (in/)                 media-worker
  │ POST /assets/uploads ──▶ authorize, quota, rate cap
  │                          reserve_upload: asset(pending) + original(pending)
  │                          + upload(issued) + reserved bytes + audit
  │ ◀── 201 {asset, upload: {url, fields, expiresAt}}
  │                          (the POST policy is signed locally: no network call)
  │ multipart/form-data POST (fields + file) ──────────────▶ in/<token>
  │ POST /assets/uploads/{id}/completion ──▶ upload received, asset processing,
  │                          process_upload queued (same tx)
  │ ◀── 202 {asset status: processing}
  │                                                                     claim one job (tx1)
  │                                                    ◀── HEAD, GET ── sniff, decode once,
  │                                                    ── PUT ────────▶ master (S3 m/)
  │                                                                     renditions ──▶ R2 public
  │                                                                     record outcome (tx2)
  │ GET /assets/{id} (poll) ──▶ status ready + rendition URLs

1. Intent (AS1): POST /assets/uploads with Idempotency-Key and { mediaType, byteSize, accessClass, displayName?, originalFilename? }. One call to assets.reserve_upload(...) (SECURITY DEFINER, the only way the runtime can create assets, variants and uploads) creates the asset (pending), its original variant (pending, satisfying the deferred "original required" trigger, 0070:584-630), the assets.uploads row (SG6) and reserves byteSize in organization_usage (SG8). The response carries an S3 presigned POST (URL plus form fields) valid 10 minutes whose policy has exactly these conditions: {"bucket": "<bucket>"}, {"key": "in/<token>"} (exact, not starts-with), {"Content-Type": "<declared type>"} (exact), ["content-length-range", 1, <declared byteSize>], plus the x-amz-algorithm, x-amz-credential and x-amz-date conditions SigV4 requires (S11). How the upload size is bounded now: S3 itself refuses a body larger than the declared size (content-length-range, S11), and the declared size is at most 10 MiB (OD5). The previous "A2a gate" (proving that R2 enforces a signed Content-Length on PUT, with a 3-minute fallback) is no longer needed; what remains of it in A2a is a contract test that a POST one byte over the declared size and a POST with another content type or key are refused by S3 (run against the staging bucket and the local S3-compatible server). The abuse exposure of the previous version (dollars per day from 5 GiB uploads) disappears: an issued slot holds at most 10 MiB, and an organization holds at most 20 slots (AS1).
2. Completion (AS2): POST /assets/uploads/{uploadId}/completion. The API does not call S3: assets.complete_upload(...) (SECURITY DEFINER) moves the upload to received, the asset to processing, and enqueues process_upload in the same transaction. This keeps every external call out of the request (D26) and out of the 5 s statement budget.
3. Verification (AS7, media worker): HEAD (size, existence) → GET with a byte cap of declared + 1 → magic-byte sniff → sharp metadata() → pixel limit of the detected format (AVIF 12 MP, JPEG, PNG and WebP 40 MP, OD5) → decode once under that same limitInputPixels into the master (auto-orient, sRGB, strip metadata, ≤ 4,096 px) → derive every rendition from the master, never re-decoding the input → write the master to S3 m/ and the public renditions to R2 → one database transaction records SHA-256, sizes, dimensions, storage objects, ready, and adjusts usage to verified bytes. Staging cleanup on every terminal outcome: the in/ object is deleted after ready, after a permanent failure and at expiry (AS9), but not by the worker for a dead-lettered job, which can be re-queued until the in/ lifecycle removes it after one day (AS8); a second POST after processing (the policy may still be live) leaves an orphan the 1-day lifecycle deletes.
4. Idempotency and flaky networks: the intent replays with the catalog pattern (resolveIdempotentClaim, request hash stored next to the key, "Idempotent creates as built" in CATALOG_USE_CASES.md): same key and body → 201 with the asset as it is now and a fresh POST policy if the upload is still issued (the policy is not stored); same key, other body → 409 · idempotency.key_reused. A client whose POST fails mid-transfer simply repeats the intent with the same key and posts again to the same key in/<token> (S3 replaces the object, S26). Completion is idempotent by state: a repeat answers 202 with the current state and writes nothing.
5. Single request, not multipart (Decided). At ≤ 10 MiB one POST is enough; S3 multipart upload exists for large objects and would add initiate/part/complete calls and per-part presigning for no gain.
6. Abandoned uploads (AS9): an upload still issued 15 minutes after creation (policy lifetime + margin) is expired by the media worker's sweep: upload expired, asset failed (assets.upload_expired), reservation released, staging object deleted if present. Safety net: the in/ lifecycle rule (1 day).

What the clients do (web and mobile, Decided contract, client details Recommended). Restaurants and retailers upload their own photos from the camera or the gallery.

Concern	Decision
HEIC from iPhones	The client converts; the server refuses HEIC. sharp's prebuilt binaries exclude HEVC because it is patent-encumbered, and HEIC needs a custom libvips built with libheif and libde265 (S40, S8); owning that build and its licensing exposure is not worth it when the client can convert for free. The native app sets Expo ImagePicker's preferredAssetRepresentationMode to compatible (S38) and re-encodes with expo-image-manipulator to JPEG (S39); the web app relies on the browser's file input (accept="image/jpeg,image/png,image/webp"; iOS Safari's transcoding of HEIC to JPEG is unverified, A2b checks it on a device)
Size on the device	The client resizes to at most 4,096 px on the long side and encodes JPEG at quality ≈ 0.85 before requesting the intent (a 12 MP photo then weighs ≈ 1–3 MB, assumption), so byteSize is the real size and slow networks send less. Native: expo-image-manipulator (S39). Web: draw into a canvas from createImageBitmap and export with canvas.toBlob('image/jpeg', 0.85), which also re-encodes (and drops EXIF); iOS Safari's HEIC-to-JPEG transcoding of the file input stays unverified (A2b)
Progress	The client measures progress itself from the POST's upload events (XMLHttpRequest.upload.onprogress on the web, the upload task's progress in the native app); the API exposes only states: pending (waiting for bytes), processing, ready, failed with failureCode, through AS3 polling every 1 s for at most 30 s
Retries	Same Idempotency-Key for the intent; the POST is retried as a whole; completion retried freely (state-idempotent)
Quotas	Per organization: assets, megabytes (OD6) and 20 open uploads; the UI shows the 422 refusals by code (D25)
Bulk	A retailer with 5,000 products uses the import flow (later, §1.3): N intents in parallel up to the 20-slot cap, then AC5 to attach in bulk; the API needs no bulk upload route for that

6.3 Renditions and processing (Decided; formats OD3, SVG OD4)

Topic	Decision	Facts
Process	A separate Railway service media-worker (OD14): same image, entrypoint node dist/media-worker, role ninaku_worker, its own memory budget	The existing worker carries OTP and invitation delivery (worker.module.ts:8-18); an image out-of-memory crash must never delay a sign-up code
Library	sharp (libvips) in the media worker only	Prebuilt binaries for Linux x64 glibc ≥ 2.28 and musl, Node ≥ 20.9 (S8); input JPEG, PNG, WebP, AVIF, GIF, TIFF, SVG (S7). Alternatives: Jimp (pure JS, several times slower and memory-heavy, assumption), ImageMagick (shell-out, large attack surface), Cloudflare Images (paid per image, moves sanitization outside our control)
Accepted inputs	image/jpeg, image/png, image/webp, image/avif (OD3); declared type, sniffed signature and sharp's detected format must all agree	OWASP: "Content-Type … cannot be trusted" (S9)
Rejected	SVG (OD4), GIF, TIFF, HEIC/HEIF (prebuilt sharp binaries do not include HEIC, S8: converting is a client requirement, see the client table at the end of §6.2), anything else → assets.media_type_unsupported
Pixel limit	Per detected format (OD5): JPEG, PNG and WebP 40_000_000, AVIF 12_000_000, because decoding an AVIF costs far more memory per pixel (measured locally on macOS arm64, one image alone: a 12 MP AVIF peaks at 572 MB RSS and a 40 MP AVIF at 1,173 MB, against about 372 MB for a 40 MP JPEG or PNG; WebP was not in the measured matrix: perf:assets has covered a 12 MP and a 40 MP WebP since the job deadline hardening, still to be measured). Raised (a 48 MP phone photo is 8,000 × 6,000 = 48 M) only with new memory evidence. sharp's default would be 268,402,689 (S7). Read dimensions with metadata() before decoding; refuse more pixels than the format's limit or any side > 12,000 → assets.image_too_large; refuse any side < 64 → assets.image_too_small; the decode itself runs with limitInputPixels set to the limit of the format the decoder detects, never of the declared type	Decompression bombs (S9)
Pipeline order	Decode the input once into the master (fit inside 4,096 px: at most 4,096 × 4,096 × 4 bytes ≈ 67 MB RGBA), encode it, then derive every rendition from the in-memory master	Never re-decode a 40 MP input per rendition; memory peaks at one input decode plus one master
Strictness	failOn: 'warning' (sharp default, S7); unlimited: false	Truncated or malformed files fail permanently
Orientation	autoOrient: true (default false, S7) before stripping EXIF	Otherwise phone photos render sideways once EXIF is gone
Metadata	Default output removes all metadata including EXIF orientation; output converted to sRGB (S6). Never call keepMetadata/withMetadata	Removes GPS, device and author PII
Animated	animated: false: first frame only
Memory/CPU	One job at a time per media-worker process, sharp.concurrency(1) (default is 1 on glibc without jemalloc, S15), sharp.cache(false)	Scale by replicas; SKIP LOCKED makes that safe. A3c gate: peak RSS for a 40 MP JPEG and PNG and a 12 MP AVIF is measured and recorded in PERFORMANCE_BASELINE.md, and the service memory limit is set from it before A3c merges. Local measurement (macOS arm64) recommends 1.5 GB for media-worker, to be re-measured on Railway's Linux after A0
Transactions and lease	assets.claim_processing_job(owner, token, 120) claims one job per call (tx1), processes it with no open transaction, records it (tx2). The lease (120 s) must exceed the measured worst per-job time with margin; A3c sets it from the measurement	Idle-in-transaction timeout 10 s (environment-variables.schema.ts:189); claiming a batch processed sequentially would let the last job outlive its lease and be processed twice
Failure classes	Permanent (no retry): unsupported, mismatch, too large/small, corrupt, size differs from declared. Transient (retry): storage 5xx, timeouts, throttling	Same taxonomy as MESSAGE_DELIVERY_FAILURE (OUTBOX_USE_CASES.md)
Retry	Two classes (Decided). Storage errors (S3/R2 5xx, timeouts, DNS failures, throttling): re-queued with capped exponential backoff (5 s doubling to a 15-minute cap) and no attempt cap, so an outage of any length never fails an asset; a metric and an alert fire after 1 hour of continuous storage errors. Processing errors (an unexpected decoder or encoder error that is not one of the permanent refusals): the first attempt plus 4 retries after 5 s, 30 s, 2 min and 10 min (≈ 12.6 minutes of backoff in total), indexed by processing_error_count; the fifth processing error dead-letters the job and the asset is failed (assets.processing_exhausted). No processing retry waits longer than 15 minutes: record_processing_outcome refuses an available_at further ahead with 23514 assets_retry_backoff (0088, 0093), so OB4's 30-minute step is never scheduled here. The two classes have separate budgets (R1, 0093): the five processing errors are counted on their own (processing_error_count, consecutive or not); a storage retry adds only to the total attempt_count and never counts towards nor resets the processing budget, so an outage never shortens the processing budget of a valid image	OB4 (OUTBOX_USE_CASES.md:25) for the second class
Idempotent processing	Object keys are deterministic from delivery_token and code, so a re-run after a crash overwrites the same keys before anything is ready; once ready, keys are never rewritten (0070:657-672)
Regeneration	A new profile (p2-*) is a render_profile job reading the master; the asset's rendition_profile moves to 2 only when every p2-* variant is ready; profile 1 objects stay until a later cleanup job	Immutable URLs stay valid for cached clients
Documents	Out of scope (§1.3)

6.4 Delivery and access (Recommended default, OD2)

Rule: domains store only asset_id; URLs are computed at read time by AssetDeliveryContract from delivery_token, rendition_profile, access_class and the configured base URL. Nothing outside Assets ever persists a URL (0070:8-10).

Access class	Delivery	Cache headers on the object	In API responses
public (product images, default for catalog)	https://<ASSETS_PUBLIC_BASE_URL>/a/<token>/p<profile>/<rendition>.webp (variant p1-tile → /a/<token>/p1/tile.webp, §5.2) from the R2 public bucket's custom domain, Cloudflare cache in front (R2-PB); S3 is never on this path (option D, §6.1)	Cache-Control: public, max-age=31536000, immutable (RFC 8246, S19) and Content-Type: image/webp, set at upload by the worker	A plain URL with no expiry: deterministic from database state, so it can live inside a strong ETag body (C17)
private	Short-lived presigned GET on the S3 bucket's p/ prefix (A7), 5 minutes; signed by an API principal that A7 adds	private, max-age=300	Never inside an ETagged or cached body; only from AS14, Cache-Control: no-store
sensitive	As private, 60 s TTL, every issue audited, never prefetched	no-store	AS14 only, with a fresh step-up for staff contexts later

Why not signed URLs for product images: a signed URL changes with time, so a till read containing one could never answer 304 from a version-based strong ETag; the till would re-download the whole sellable list to refresh URLs. Product photos are marketing content shown to customers, so public with unguessable tokens is the right exposure. An alternative, Cloudflare WAF token authentication on the custom domain (HMAC + timestamp in a query parameter), requires a Pro plan or above (S17) and still expires.

ETag safety (Decided): a public URL depends on ASSETS_PUBLIC_BASE_URL, which can change (domain migration) without any database write. Every ETagged read that embeds URLs adds a delivery fingerprint (first 8 hex of SHA-256 of the base URL and the profile list) to its tag, e.g. C17 "c<catalogVersion>-s<structureVersion>-<businessUnitId>-d<fingerprint>".

AI disclosure in delivery (Recommended, OD19): describe returns aiGenerated: true for assets whose source_kind is ai_generated, and the till read carries it next to imageRef, so every customer-facing surface can show the label of OD19 without another call.

Hotlinking and abuse: tokens are unguessable (128 bits), but a public URL is shareable by design. Cloudflare's cache absorbs repeated reads and R2 egress is free (S1); a WAF rate rule per IP on the media host is an operations setting (A0). Hotlink protection by Referer is not recommended: native apps send no referrer.

Media host headers (A0): a Cloudflare transform rule on the media domain adds X-Content-Type-Options: nosniff and a restrictive Content-Security-Policy: default-src 'none'; img-src 'self'; sandbox, so even a mislabelled object can never run as a page.

Takedown and the CDN (Decided, OD2 — changed): immutable, max-age=31536000 means a deleted object can stay in Cloudflare's cache and in browsers. The purge job (AS10) therefore calls Cloudflare's purge-by-URL API (S22: up to 100 URLs per call, 800 URLs/s on the Free plan; an asset has at most four public URLs (the four profile 1 renditions), one call per asset) for every public rendition URL of the asset automatically, with a token scoped to cache purge on the media zone only (A0), before the database rows go. Browser and device caches cannot be recalled; that residual is accepted for public product photos and is the reason private files never use public URLs.

CORS: the S3 bucket allows POST from the app origins (web app; native apps need no CORS), with no credentials; the R2 public bucket allows GET from * so a web till's service worker can cache images with fetch (Decided: public content, no credentials). Both are bucket settings in A0, separate from the API's CORS_ALLOWED_ORIGINS (railway.ts:24-41).

What the API returns for an item image (Decided): never a bucket, key or provider. Two shapes:

• Back office (C3, AS3): full URLs per rendition, { assetId, status, thumbnailUrl, cardUrl, detailUrl }; bodies are small (≤ 10 images per item).
• Till (C17, C19): per item and per variant only imageRef: string | null (<delivery token>/p<profile>, 29 characters), plus onemeta.media = { tileUrlTemplate: "https://<media domain>/a/{imageRef}/tile.webp" }. The client builds the URL by replacing {imageRef}; the template comes from the server, so the client never hardcodes the key layout. Reason: "K7 as built" in CATALOG_USE_CASES.md found that the cost missing the budget on large tills is building and sending the JSON of a large body, and a full URL repeats ≈ 60 bytes of host and path on each of up to 2,000 items (≈ 120 KB before compression). The asset id is not sent: the till never needs it.

Offline till (Decided): BUSINESS_DESIGN.md §4 ("Solo se sincroniza el subconjunto autorizado por dispositivo/scope", :89). The till already loads only what its outlet sells (C17). It prefetches each tile URL into its local store keyed by URL; since an image change is a new asset (new token, new URL) and old URLs never change content, the device cache is correct by construction, and a 304 from C17 means no image changed. Budget: 2,000 items × ~25 KB ≈ 50 MB worst case per device (assumption on size).

Default access class for product images: public (OD2).

6.5 Authorization and plan (Recommended, OD6, OD11)

Topic	Decision
Permissions	assets.media.manage (request uploads, complete, rename, archive, restore) and assets.media.view (library reads); format module.resource.action (permissions_code_chk, as catalog)
Anchor	Organization-wide only: assets have no business-unit column (0070:84-133), and catalog master data is edited organization-wide (catalog OD3)
Roles (D30 pattern)	organization_owner and manager: both permissions (effective only with an organization-wide assignment, as catalog.items.manage); every other seeded role (cashier, waiter, kitchen, bar, sales_associate, stock_keeper): none. Least privilege: none of them manages images, and the item master (C3, which sales_associate and stock_keeper read with catalog.items.view) and the till (C17, catalog.sellables.view) already embed the image references they need
Capability	assets.media ("Images and files") gates AS1 (new uploads) only; assets.ai_generation gates AS15 (through AC6) with the monthly limit assets.ai_generations (OD18). Never gated: completion of an intent already issued, reads, rename, archive, restore, attach/detach in Catalog (attach is gated by catalog.items)
Limits	assets.active_assets (integer, unit assets), assets.stored_megabytes (integer, unit megabytes, MiB). An integer limit takes 0 to 2,147,483,647 (0060_platform.sql:1738-1750, migration 0074), so bytes cannot be an integer limit (2 GiB maximum); MiB can (2 PiB). decimal was rejected: quotas count whole things. Pionero defaults (OD6): 5,000 assets and 10,240 MiB
Max file size	A domain constant, not a plan limit: 10 MiB (OD5). One rule for everyone keeps the worker's memory bound fixed
Lapsed plan	Reads, archive, restore, rename, detach: never gated by the capability (restore still respects the asset limit). Organizations subscribed to an older Pionero version do not gain assets.media until staff move them, as with the catalog rollout (SUBSCRIPTION_PLANS_USE_CASES.md:719-733). New uploads: refused with 403 · platform.capability_not_entitled (capability lost) or 422 · assets.storage_limit_reached / assets.asset_limit_reached (over quota after a downgrade). Nothing is deleted because a plan lapsed
Rate limits	@Throttle on AS1: 30 requests per minute per client IP; database cap: at most 20 uploads in issued/received per organization (422 · assets.too_many_open_uploads), checked under the usage lock
Tenant isolation	RLS by organization_id on every tenant table (existing policies 0070:962-1048); keys and URLs never contain organization or asset ids (§5.2)
Deduplication	None across organizations (Decided: a cross-tenant hit would reveal that another business holds the same file). Per organization: not in v1 (SG10)

6.6 The Catalog link and the published contracts (Decided)

catalog.item_assets semantics: item-wide rows (item_variant_id IS NULL) and variant rows; media_role primary (at most one per item and per variant, 0080:702-716) or gallery; sort_order ≥ 0. Decided: at most 10 images per item set and 10 per variant set; the list is replaced as a whole (PUT, like C8 and C13), position in the list is sort_order, and the first entry is the primary.

Contracts (D18 modes):

// src/modules/assets/contracts/asset-usage.contract.ts (synchronous, shares the caller's tenant transaction)
interface AssetUsageContract {
  assertAttachable(ctx: TransactionContext, input: { assetIds: readonly string[]; requirement: { mediaKind: 'image'; accessClass: 'public' } }):
    Promise<readonly AttachableAsset[]>; // locks FOR SHARE in id order; throws AssetNotAttachableError { assetId, reason }
}
// reasons: 'not_found' (unknown or another tenant: RLS makes them identical), 'not_ready', 'archived', 'purging', 'wrong_media_kind', 'wrong_access_class'

// src/modules/assets/contracts/asset-delivery.contract.ts (read contract)
interface AssetDeliveryContract {
  describe(ctx: TransactionContext, input: { assetIds: readonly string[]; renditions: readonly RenditionName[] }):
    Promise<AssetDeliveryDescription>; // one set-based statement on assets.assets; ≤ 2,000 ids; public assets only get URLs
  fingerprint(): string; // the delivery fingerprint of §6.4, for consumers' ETags
}

Consumers ask only "is this id mine and usable" and "how do I show these ids". They never see keys, buckets, providers, storage objects or variant ids.

Lock order across the two modules (Decided): a Catalog image command locks catalog.catalog_versions first (the catalog rule, CATALOG_USE_CASES.md §5), then the item FOR UPDATE, then calls assertAttachable, which locks the asset rows FOR SHARE in id order. Assets commands lock organization_usage, then the asset FOR UPDATE, and never touch catalog rows. No cycle exists, so no deadlock. FOR SHARE makes "archive" (which takes the asset FOR UPDATE) and "attach" serialize: an asset archived concurrently is never attached.

Archived but attached: archiving an asset hides it from the library and makes it unattachable, but does not change existing references or delivery: its objects stay until AS10 proves nothing references it, and AS10 never starts on a referenced asset. So no catalog ETag can go stale because of an Assets command.

Catalog ETags: C3's item ETag is a hash of the representation ("K2 as built"), so adding images[] changes it automatically. C17's tag is version-based; SG11 adds the bump triggers on item_assets and §6.4 adds the delivery fingerprint.

Image writes and the till 304 (Recommended, OD16). Every image command is a catalog command: it takes catalog_versions FOR UPDATE and bumps the organization's version, so every till of the organization re-reads its whole sellable list once afterwards. An owner who sets 300 photos one item at a time causes 300 full till re-reads and 300 serialized version locks. The K8 measurement found that catalog commands keep succeeding next to admissions as long as a sale holds its transaction 50 ms or less (CATALOG_CASE_MATRIX.md preamble, PERFORMANCE_BASELINE.md §15); an image PUT is an ordinary short catalog command, so it adds no new starvation risk. The cost is accepted, and the recommended path for the product-creation wizard and imports is the bulk command AC5: images for up to 100 items in one request, one transaction, a constant number of version bumps (one per statement, independent of N).

CatalogSellableContract snapshot (Decided): it does not carry an image id in v1. Sales and Pricing never show images; the till gets images from C17. Adding primaryImageAssetId later is additive.

Audit actions to seed (Catalog migration, A5b): catalog.item.images_set and catalog.item.variant_images_set, the latter also written once per item by AC5 (resource kind catalog.item, category configuration, retention class administration.platform, as catalog R16).

6.7 AI-generated images with OpenAI GPT Image (Recommended, OD9, OD17–OD19 — changed)

The owner will use OpenAI's GPT Image models. This is now a fully designed future slice set (A8a–A8d); nothing is built before the owner answers OD17 and OD15.

Provider facts (fetched 2026-10-06).

Fact	Value	Source
Models offered for images	gpt-image-2.5-sunburst, gpt-image-2.5-flare, gpt-image-2 (snapshot gpt-image-2-2026-04-21), gpt-image-1.5 (gpt-image-1.5-2025-12-16), gpt-image-1-mini, gpt-image-1, chatgpt-image-latest	S31, S34, S33
Endpoints	v1/images/generations, v1/images/edits (image input, inpainting with a mask), v1/batch; also an image tool in the Responses API	S30, S34
Sizes	1024×1024, 1536×1024, 1024×1536 recommended; custom sizes in multiples of 16, ratio 1:3 to 3:1, edge ≤ 3,840 px (newest models)	S30
Quality	low, medium, high (and xhigh, max, auto on the 2.5 models)	S30
Output	base64 image data; png (default), jpeg, webp; transparent background with png/webp	S30
Moderation parameter	auto (default, standard filtering) or low	S30
Organization verification	"may need to complete the API Organization Verification" before using GPT Image models	S30
Latency	"Complex prompts may take up to 2 minutes"	S30
Price per image (1024×1024 / 1024×1536)	gpt-image-1-mini: low $0.005 / $0.006, medium $0.011 / $0.015, high $0.036 / $0.052 (S32). gpt-image-1.5: low $0.009 / $0.013, medium $0.034 / $0.05, high $0.133 / $0.20 (S33). gpt-image-2 and 2.5: token-priced (e.g. gpt-image-2 image output $30 per 1M tokens), per-image cost from OpenAI's calculator (S31)	S31–S33
Rate limits	gpt-image-1-mini and gpt-image-2: 20 images/minute at the Build tier, 150 at Launch, 250 at Grow (S32, S34)	S32, S34
Data	API data not used for training unless opted in; abuse-monitoring logs up to 30 days; image endpoints eligible for Zero Data Retention with some models; suspected CSAM retained for review even under ZDR	S35
Provenance	API images include C2PA metadata and a SynthID watermark (not Decided: from secondary sources and the search snippet of OpenAI's help page; the primary page was not fetched)	S36
Spend control	Monthly organization and project spend limits, as alerts or enforced hard limits that make requests fail with 429	S37
Usage policies	https://openai.com/policies/usage-policies/ (the page answered 403 to the fetch tool; its text is not quoted here; OD19's disclosure is Ninaku's own consumer-protection choice, not a claimed OpenAI requirement)	S41

Model choice (Recommended, OD17). The model is configuration (OPENAI_IMAGE_MODEL, OPENAI_IMAGE_QUALITY, size), never code. OpenAI's guide now leads with gpt-image-2.5 (sunburst, flare) and gpt-image-2 (S30), and describes gpt-image-1.5 as its previous image generation model, so 1.5 is not presented as current. A8 starts with gpt-image-1.5, medium, 1024×1024, output_format: png, moderation: auto, because its per-image price is published: $0.034 (low $0.009, high $0.133; 20/150/250 images per minute by tier) (S33). A8a compares it on real menu items against the 2.5 models (token-priced, S31; all three families listed as eligible for Zero Data Retention, S35) and switches the configuration if quality per dollar is better. Assumption: 1.5 medium is realistic enough for food and products.

Two intents.

Intent	Endpoint	Input
Generate a photo for a product that has none	images/generations	A prompt built by the server
Enhance a photo the user uploaded (clean background, better light)	images/edits	The asset's master (read from S3 m/ by the worker) plus the server-built prompt; no mask in v1

Flow.

user (product form) ── POST /catalog/items/{itemId}/image-generations {stylePreset, instruction?, sourceAssetId?}
  Catalog (AC6, tenant tx): permission, item read (name, description, primary category)
     └─ AssetGenerationContract.request(ctx, {subject, description, category, stylePreset, instruction, sourceAssetId, idempotencyKey})
          Assets (definer function): capability, monthly quota reserve, generation_request(queued), job generate_image  ── 202
media-worker: claim one generate_image job (tx1) ─ no transaction ─ OpenAI call (timeout 180 s)
     ├─ success: bytes → SAME pipeline as an upload (sniff, decode, master, renditions); provider original kept in S3 m/ (C2PA kept)
     │           asset(ready, source_kind ai_generated), request(review), quota consumed (tx2)
     └─ failure: request(failed | refused), quota released, no asset
user ── GET /assets/generations/{id} (poll) ── preview (thumbnail, card)
user ── POST /assets/generations/{id}/approval ── request(approved) ── now attachable (AC1/AC5)
     or /rejection ── request(rejected), asset archived (purged later, AS10); regenerate = a new request (new quota unit)

Rule	Decision
Prompt	Built server-side from the caller organization's own catalog data (RLS) and a fixed template per stylePreset (studio_white, rustic_table, bright_menu, transparent_cutout; the list is configuration): "Professional product photograph of {name}. {description ≤ 300 chars}. Category: {category}. Style: {preset text}. {instruction ≤ 200 chars}". The user's instruction is optional, ≤ 200 characters, NUL and control characters rejected, URLs removed. No other tenant's data can enter a prompt. Decided risk (note 18): a product name or description written by the same organization may carry a prompt injection; it is accepted because the data is the caller's own, the call has no tools and no data access, and the outcome is bounded by moderation and the mandatory human approval
Idempotency	Idempotency-Key on AC6 with the request hash (the AS1 pattern); a replay answers the same generation request
Asset quotas (Recommended, OD20)	A generated asset is a normal asset: it counts toward assets.active_assets and assets.stored_megabytes like an upload. Checked twice: at request time (AC6 reserves one asset slot and an estimated 3 MiB in organization_usage, refusing with assets.asset_limit_reached / assets.storage_limit_reached before any OpenAI cost) and again in create_generated_asset (verified bytes replace the estimate; if the limit was reached meanwhile, the image is still stored and counted, because OpenAI was already paid; the quota is soft by that one asset)
Generation quota	Plan limit assets.ai_generations, integer, reset_period = 'month' (0060_platform.sql:783-792), reserved under the usage row lock at request time, consumed when an image is produced, released when the call fails or is refused (the organization never pays for a failure). A provider timeout after the provider may have billed is consumed (Decided: at-least-once; OpenAI's cost is ours, the tenant is charged one unit)
Transactions and lease	No database transaction is open during the OpenAI call; one job per claim; the lease covers one attempt: lease 300 s > request timeout 180 s > OpenAI's 2-minute worst case (S30)
Retries	Re-queues, never one long lease: a 429 or 5xx records the attempt and sets available_at (honoring Retry-After), releasing the lease; at most 3 provider attempts, counted by the handler from the claimed attempt_count (storage errors while saving are uncapped, like every job; ASSETS_STAGE_SPECS.md §25); 400 refused by moderation: permanent, refused with the provider's reason code, quota released
Concurrency	The media worker runs two independent claim loops: the image loop (process_upload, render_profile, purge_asset) claims one job at a time so sharp work stays serialized (§6.3); the generation loop (generate_image) runs up to 2 jobs concurrently (Build tier 20 images/minute, S32) and hands the returned bytes to the image loop's pipeline through the same serialized decoder
Storage and asset creation	assets.create_generated_asset(job, lease, …) (SECURITY DEFINER, ninaku_worker only, SG19) creates, in one transaction, the ai_generated asset (processing: there is no upload step, so it never passes through pending; new delivery_token), its original variant and the private provider-original variant with its S3 m/ storage object; the bytes then go through the AS7 pipeline exactly like an upload. The provider original is kept so a C2PA manifest, if present (S36, not verified), survives for audits; served renditions are re-encoded and lose it
Provenance	generation_requests holds model, quality, size, provider request id (x-request-id), prompt SHA-256, prompt text (tenant data, retained 90 days then nulled), style preset, cost units, moderation outcome, requester, timestamps
Approval	assertAttachable refuses an ai_generated asset whose request is not approved (not_approved); approval and rejection need assets.media.manage; audited assets.generation.requested, .approved, .rejected
Disclosure	source_kind = 'ai_generated' is permanent; delivery carries aiGenerated: true; customer-facing surfaces show a label (OD19); counsel confirms the Colombian and Ecuadorian consumer-protection exposure as part of OD15 (note 19)
Secrets and logs	OPENAI_API_KEY and OPENAI_PROJECT_ID only in media-worker; never logged; prompt text and response bodies (base64) never logged; logs carry the request id, model, latency and outcome only
Cost ceiling	An OpenAI project per environment with an enforced hard monthly spend limit and an alert at 50% (S37); per-organization monthly limits (OD18)
Data	ZDR requested for the production project if eligible for the chosen model (S35); OD15 covers sending tenant product data to OpenAI

6.7.1 Schema gaps for AI (A8a)

#	Change
SG19	Function assets.create_generated_asset(job, lease_token, …) (SECURITY DEFINER, ninaku_worker only): creates the ai_generated asset, its original and provider-original variants and storage objects, links the request, and re-checks the asset quotas (OD20). Table assets.generation_requests: id, organization_id, asset_id (nullable until produced, FK tenant-safe), source_asset_id (nullable, enhance), requested_by_membership_id (FK (id, organization_id)), intent (generate, enhance), style_preset varchar(40), instruction varchar(200), prompt_text varchar(2000) (nullable after retention), prompt_sha256 text CHECK (~ '^[0-9a-f]{64}$'), model_code varchar(80), quality varchar(20), size varchar(20), provider_request_id varchar(120), state (queued, generating, review, approved, rejected, failed, refused), failure_code varchar(80), moderation_outcome varchar(40), cost_units integer, creation_idempotency_key uuid, creation_request_hash text (^[0-9a-f]{64}$), timestamps; unique (organization_id, creation_idempotency_key); RLS; state-shape check; runtime reads only, writes through definer functions
SG20	assets.ai_generation_usage (organization_id, period_start date, reserved integer, consumed integer), primary key (organization_id, period_start), non-negative checks; reserve/consume/release in definer functions under the row lock
SG21	SG5's source_kind values become ('upload','ai_generated'); job kind generate_image added to SG7

6.8 Retention and erasure (Recommended, OD8)

• Archive is soft (archived_at); restore within 30 days.
• Purge (AS10, slice A4b) of an asset archived more than 30 days, or failed more than 7 days, when nothing references it, in three steps:
  1. purge_asset_begin locks the asset FOR UPDATE and tests the reference with the DELETE itself: inside a PL/pgSQL block it deletes the asset's storage objects, variants, upload and asset row; a 23503 (some consumer's FK still points at it) is caught and answers referenced; success raises a private exception that rolls the block back and answers deletable. On deletable it sets status = 'purging' (SG16) in the same transaction. Storage rows are untouched. Because assertAttachable takes FOR SHARE on the same row and refuses purging, no reference can appear between the test and the status change, nor afterwards (the invariant of §2.4).
  2. The media worker deletes the objects from S3 and R2 (missing counts as done) and purges every public rendition URL from Cloudflare's cache (S22).
  3. purge_asset_finish deletes storage objects, variants, upload, jobs and the asset in one transaction, which satisfies the deferred triggers (0070:625-637, :937-949), then calls assets.reconcile_usage. A 23503 here can only come from a consumer that bypassed the contract: the function catches it, keeps the asset purging, records assets_asset_referenced_after_purge on the job and raises an alert metric; the objects are already gone, which is why the invariant is tested in every consumer slice.
• Each referencing table that holds data needs an index leading with asset_id so the DELETE's FK check is an index probe (SG11 for item_assets; each future consumer adds its own).
• Data-subject erasure (OD23). An erasure request under the personal-data policy maps to this existing path: archive the subject's assets, then the purge (AS10) deletes them from S3 and R2 and purges the CDN; the trigger path is defined when the policy exists. Backups and OpenAI's retention (abuse-monitoring logs, Zero Data Retention when granted, S35) are covered by the policy text, not by this purge.
• Erasure on request (GDPR-style): the consumer detaches first, then the owner archives, then a staff-triggered purge skips the 30-day wait. The CDN copies are purged automatically in step 2; copies already in browsers or devices cannot be recalled.

---

7. Use cases

Conventions for every case. Routes are relative to /api/v1; every request carries a session and X-Organization-Id (TenantContextGuard). Bodies are strict Zod schemas (D24). Responses use { data } or { data, meta }. detail is English; clients translate code (D25). Commands that change something write one tenant audit record through TenantAuditContract in the same transaction, only for a real change.

Lock order (Assets). Every Assets command that changes a usage counter (bytes or the active asset count: reservations, outcomes, sweeps, archive and restore) locks assets.organization_usage of its organization FOR UPDATE first, then the asset and its upload FOR UPDATE. Rename changes no counter and locks only the asset. Reads lock nothing. AssetUsageContract.assertAttachable takes FOR SHARE on asset rows only.

Shared rows (not repeated per case):

Shared path	Answer
No session	401 · identity.session_required
Organization not selectable	403 · tenant.context_rejected
Permission missing	403 · assets.action_forbidden (new, audited as denied, like catalog.action_forbidden)
Capability not in the plan (AS1, AS15 only; AS15 checks assets.ai_generation)	403 · platform.capability_not_entitled
Malformed id or body	400 · foundation.validation_failed
Unknown or foreign-tenant asset or upload	404 · assets.not_found (new; RLS makes both identical)
If-Match stale	412 · foundation.precondition_failed
Unmapped constraint	422 · assets.asset_refused (new, generic backstop)

7.1 Uploads

AS1 — Request an upload

Actor: assets.media.manage organization-wide; capability assets.media. Route: POST /assets/uploads, Idempotency-Key required. Request: { mediaType: 'image/jpeg'|'image/png'|'image/webp'|'image/avif', byteSize: 1..10485760, accessClass: 'public', displayName?, originalFilename? }. Decided: private and sensitive are refused (422 · assets.access_class_unavailable) until A7 ships a way to view them; accessClass is still required so the contract does not change when A7 widens it, and it is immutable after creation (SG17). Main path (one tenant transaction): authorize → assets.reserve_upload(...) (SECURITY DEFINER), which locks organization_usage → checks active_asset_count + 1 ≤ assets.active_assets, stored_bytes + reserved_bytes + byteSize ≤ assets.stored_megabytes × 2^20, open uploads < 20 → claims the Idempotency-Key on assets.uploads → inserts asset (pending, new delivery_token), original variant (pending), upload (issued, expires_at = now() + 15 min, staging key in/<random token>) → reserves bytes → audit assets.asset.upload_requested → commit → sign the S3 POST policy (10 minutes, exact key and content type, content-length-range 1..byteSize, §6.2). Response: 201 { asset: {id, status: 'pending', accessClass, displayName}, upload: { id, url, method: 'POST', fields: { key, 'Content-Type', policy, 'x-amz-algorithm', 'x-amz-credential', 'x-amz-date', 'x-amz-signature' }, maxBytes, expiresAt } }, Cache-Control: no-store. The client posts fields then file as multipart/form-data. The policy and signature are never stored, logged or audited. Idempotency: §6.2 item 4. Errors: 422 · assets.media_type_unsupported, 422 · assets.file_too_large (new, > 10 MiB), 422 · assets.asset_limit_reached, 422 · assets.storage_limit_reached, 422 · assets.too_many_open_uploads, 429 from the throttler. Concurrency: two intents of one organization serialize on the usage row; the last one over quota fails, never both pass. Audit: assets.asset.upload_requested (resource kind assets.asset). Scenario rows: in §17.

AS2 — Complete an upload

Actor: assets.media.manage organization-wide. Not capability-gated (the intent was already admitted). Route: POST /assets/uploads/{uploadId}/completion (no body). Main path: assets.complete_upload(upload_id) (SECURITY DEFINER, the only way the runtime moves an asset's status): lock the upload and asset FOR UPDATE → if issued and not expired: upload received, asset and original variant processing, process_upload job queued → no audit (the outcome is a processing fact; the request was audited in AS1). Response: 202 with the AS3 shape. Repeat in received/verified → 202, nothing written. Errors: 422 · assets.upload_expired (new), 422 · assets.upload_rejected (new, already rejected). Never calls the storage provider (§6.2).

AS3 — Read one asset

Actor: assets.media.view or assets.media.manage organization-wide. Route: GET /assets/{assetId}. Response: { id, status, accessClass, mediaKind, displayName, originalFilename, sourceKind, width, height, byteSize, createdAt, readyAt, archivedAt, failureCode, renditions: { thumbnail, tile, card, detail } } where each rendition is { url } for a ready public asset and null otherwise; never the master. ETag: content hash, private, no-cache (D24: read often while polling, changes rarely once ready). Not capability-gated.

AS4 — List the media library

Actor: as AS3. Route: GET /assets?status=&archived=&cursor=&limit=. Keyset (created_at DESC, id DESC) (SG12), limit 50 default, 100 max, signed cursor. Items: the AS3 shape with only the thumbnail URL. No ETag (cursor page, D24).

AS5 — Rename an asset

Actor: assets.media.manage. Route: PATCH /assets/{assetId}{ displayName }, optional If-Match. Unchanged → 200, nothing written. Audit: assets.asset.renamed. Never gated.

AS6 — Archive and restore an asset

Actor: assets.media.manage. Routes:POST /assets/{assetId}/{archival,restoration}. Never gated. Repeat → 200, nothing written. Both go through SECURITY DEFINER functions (assets.archive_asset, assets.restore_asset, created with A1b-3) because they change active_asset_count; the runtime has no UPDATE (archived_at). Restoration re-checks the asset limit (422 · assets.asset_limit_reached). Archive locks the usage row and then the asset FOR UPDATE (the lock order above; the asset lock serializes with AC1's FOR SHARE), sets archived_at; references and delivery are untouched (§6.6). Restore within 30 days; after that 422 · assets.restoration_expired. Restoration of a failed asset, and archival or restoration of a purging asset, is refused (422 · assets.transition_invalid); the restore path locks the asset FOR UPDATE, the same row purge_asset_begin locks, so a restore never races a purge. Audit: assets.asset.archived, assets.asset.restored.

7.2 Worker cases

AS7 — Process an upload

Actor: the media worker (ninaku_worker, service media-worker), no HTTP route. Main path: assets.claim_processing_job(owner, token, 120) (one job) → outside any transaction: HEAD staging object (missing → transient until the upload's expiry, then permanent assets.upload_missing); size must equal the declared size (assets.size_mismatch); GET with a byte cap; sniff magic bytes (JPEG FF D8 FF, PNG 89 50 4E 47 0D 0A 1A 0A, WebP RIFF….WEBP, AVIF ftyp with brand avif/avis) and compare with the declared type and sharp's detected format (assets.content_mismatch); check dimensions (§6.3); decode once into the master, derive profile 1 from the master, SHA-256 of each output; PUT the master to S3 m/ and each public rendition to the R2 public bucket with Content-Type and the immutable Cache-Control; then assets.record_processing_outcome(job, lease, …) in one transaction: storage objects available, variants ready with their content facts, asset ready, upload verified, usage: reserved → stored (sum of all variant bytes); then delete the staging object (on every terminal outcome, §6.2; the in/ lifecycle is the net). Lease: 120 s for exactly one job, above the worst processing time of a 40 MP JPEG, PNG or WebP or a 12 MP AVIF (assumption, measured in A3c, which sets the final value). A lost lease refuses the record call; the next claimant redoes the job (deterministic keys).

AS8 — Retry, fail and dead-letter processing

Permanent failure (unsupported, mismatch, too large or small, corrupt) → variant(s) failed with failure_code, asset failed, upload rejected, reservation released, job completed, staging object deleted. Storage errors → re-queued with capped backoff and no attempt cap (§6.3). Processing errors → OB4 schedule; the fifth processing error (counted apart from storage retries, which never count towards it nor reset it: R1) → job dead_lettered, asset failed (assets.processing_exhausted); the staging object is kept (not deleted by the worker) so the job can be re-queued, but only within one day of the upload: the in/ lifecycle rule deletes every inbox object after 1 day (§6.1), so an older dead letter stays failed and is purged after 7 days.

Dead-letter recovery (Recommended, OD21). v1 has no staff route: an operator runs the runbook query SELECT assets.requeue_dead_letters(ARRAY[...]::uuid[]) with the migrator's credentials after fixing the cause (for example a sharp upgrade). The SECURITY DEFINER function moves each dead-lettered process_upload job back to pending with attempt_count = 0 and processing_error_count = 0, the asset failed → processing (allowed by SG18) and the reservation back on, only for jobs created in the last day (the inbox lifetime); ninaku_runtime and ninaku_worker cannot execute it. A metric assets_processing_dead_letters is exported; a staff route reusing the OX-O1/OX-O2 shape comes when Platform's staff console needs it.

AS9 — Expire abandoned uploads

A sweep, not a job: a scheduled task in the media-worker process (every 5 minutes, transaction-scoped advisory lock, bounded batch of 500), copying the discipline of SubscriptionLifecycleSweepJob, which runs in the API process (platform.module.ts:57,157), not in the worker. It calls assets.expire_uploads(batch) (SECURITY DEFINER, ninaku_worker only), which moves issued uploads past expires_at to expired, their assets to failed (assets.upload_expired) and releases reservations; the sweep then deletes each returned staging object. The failed assets are purged later by AS10 (failed > 7 days). Nightly, the same sweep pages through every organization's usage row with assets.reconcile_usage_batch(after, batch) (A1c-2).

AS10 — Purge an asset (reference-safe, slice A4b)

Job purge_asset for assets archived > 30 days or failed > 7 days, in the three steps of §6.8: purge_asset_begin (reference test with the DELETE's own 23503 caught in the definer function, status purging, storage rows untouched) → the media worker deletes the objects from S3 (m/, p/) and from R2 (public renditions) and purges every public rendition URL from Cloudflare's cache (token from A0) → purge_asset_finish deletes storage objects, variants, upload, jobs and asset in one transaction and reconciles usage. A referenced asset answers referenced, stays as it is, and is re-checked after 30 days.

AS11 — Regenerate renditions for a new profile

Job render_profile per asset reading the master. No route in v1: a staff-run backfill when profile 2 is designed. Throughput §12.4.

7.3 Contracts

AS12 — Describe delivery (AssetDeliveryContract.describe)

One statement: SELECT id, status, access_class, delivery_token, rendition_profile FROM assets.assets WHERE organization_id = $1 AND id = ANY($2) under RLS (primary key lookups). Returns, per id, { status, imageRef, urls } for public and ready (imageRef = <token>/p<profile> for compact consumers like the till, urls for the renditions asked); null otherwise, also for purging. Archived assets still resolve (§6.6). ≤ 2,000 ids per call (CATALOG_USE_CASES.md C17 bound). Also exposes the tileUrlTemplate and the delivery fingerprint (§6.4).

AS13 — Check attachability (AssetUsageContract.assertAttachable)

SELECT … FOR SHARE in id order; refuses with a reason per id (§6.6). Throws AssetNotAttachableError; the consumer maps it to its own public code (Catalog: 422 · catalog.image_not_attachable with meta.errors[].reason).

7.4 Later cases (designed here, built in A7 and A8a–A8d)

Case	Route	Slice
AS14 Signed access to a private rendition	GET /assets/{assetId}/renditions/{rendition}/access → 200 { url, expiresAt }, Cache-Control: no-store; sensitive audited	A7
AS15 Request an AI image (contract AssetGenerationContract.request, reached through AC6; read with GET /assets/generations/{id})	No public create route in Assets: the prompt is built from catalog data by AC6 (§6.7); 202 with the request; refusals 403 · platform.capability_not_entitled, 422 · assets.ai_generation_limit_reached, 422 · assets.media_type_unsupported for an enhance source that is not a ready image	A8b
AS15w Generate in the worker (job generate_image)	OpenAI call, pipeline, quota consume/release, refusals (§6.7)	A8c
AS16 Approve or reject a generated image	POST /assets/generations/{id}/{approval,rejection}; approval makes the asset attachable; rejection archives it; audited	A8d

7.5 The Catalog side

AC1 — Set an item's images

Actor: catalog.items.manage organization-wide; capability catalog.items, except a list that only removes images (ungated, like C13). Route: PUT /catalog/items/{itemId}/images with { images: [{ assetId }] } (0–10, distinct, first = primary), optional If-Match (C3 ETag). Main path: lock catalog_versions → item FOR UPDATE → refuse archived item (422 · catalog.item_archived) → AssetUsageContract.assertAttachable(ids, {image, public}) for ids not already attached (already-attached ids stay even if their asset was archived later) → delete rows not in the list, upsert the rest with sort_order = position and media_role = primary for the first → bump (SG11 trigger) → audit catalog.item.images_set with before/after id lists. Response: 200 with the C3 shape and its new ETag. Same list → 200, nothing written. Errors: 422 · catalog.image_not_attachable (new), 400 for > 10 or duplicates, 404 · catalog.not_found.

AC2 — Set a variant's images

PUT /catalog/items/{itemId}/images with { images, variants? } (the separate variant route was merged into it in API v7), same rules on rows with item_variant_id; audit catalog.item.variant_images_set. The till shows the variant's primary image when the cashier picks that variant, else the item's.

AC3 — Item read with images (C3 extension)

images: [{ assetId, isPrimary, sortOrder, status, thumbnailUrl, cardUrl, detailUrl }] and variants[].images likewise; one extra statement (AssetDeliveryContract.describe) for all ids of the item. The item ETag (content hash) changes when images change.

AC4 — Till read with images (C17, C19 extension)

The C17 read statement left-joins item_assets through item_assets_one_item_primary_uq (0080:702-708) to carry the primary asset id; one describe call for the distinct ids (≤ 2,000) adds imageRef: string | null per item and per variant (when the variant has its own primary) and meta.media.tileUrlTemplate (§6.4). The ETag gains -d<fingerprint>. C19 adds the same fields per page.

Statement budgets (corrected). As built, C17 costs 8 statements for the 200 and 7 for the 304, and C19 8 (session, membership, BEGIN, tenant context, permission, outlet state, the read, COMMIT; "K7 as built" in CATALOG_USE_CASES.md, proven by test/e2e/statement-budget.e2e-spec.ts). AC4 adds the describe statement to the 200 paths only: C17 200 = 9, C17 304 = 7 (unchanged: the 304 answers before any read, so it never reads assets), C19 = 9. The slice that ships AC4 (A6) updates statement-budget.e2e-spec.ts and re-baselines the catalog-till-sellables rows of KNOWN_BREACHES (tooling/performance/measurement/known-breaches.ts): perf:http fails on a regression above 25% against that baseline (AGENTS.md §5.5), so A6 measures before and after and records the new baseline with its cause.

AC5 — Set images for many items at once (bulk)

Actor: as AC1. Route: PUT /catalog/item-images with { items: [{ itemId, images: [{ assetId }] }] }, 1–100 items, each list as AC1 (0–10, distinct, first = primary); an item may appear once. Main path (one transaction, atomic): lock catalog_versions → items FOR UPDATE in id order → assertAttachable once for every new asset id (≤ 1,000, id order) → one set-based DELETE and one set-based upsert for all items → audit one catalog.item.images_set per changed item. The statement-level bump triggers fire once per statement, so the till version moves by a constant (two), not by N. Response: 200 { items: [{ itemId, etag }] }; any refusal (unknown item, archived item, unattachable asset) refuses the whole request with meta.errors[] naming each item and asset, nothing written. Why: the product-creation wizard and imports set many images at once; AC1 per item would bump the version and force a full till re-read per item (§6.6, OD16).

AC6 — Request an AI image for an item (Catalog side, A8b)

Actor: a member holding catalog.items.manage and assets.media.manage organization-wide; capability assets.ai_generation and the monthly limit assets.ai_generations (OD18). Route: POST /catalog/items/{itemId}/image-generations, Idempotency-Key required, body { stylePreset, instruction?, sourceAssetId? } (sourceAssetId = enhance an uploaded photo; it must pass assertAttachable as an image of the organization). Main path (one tenant transaction, no external call): authorize → read the item (name, description, primary category; archived → 422 · catalog.item_archived) → AssetGenerationContract.request(...), which builds the prompt from those fields (§6.7), reserves one quota unit, inserts the generation request (queued) and the generate_image job, and audits assets.generation.requested → 202 { generationId, state: 'queued' }. The catalog writes nothing (no version bump): the image is attached later with AC1/AC5 after approval. Errors: 422 · assets.ai_generation_limit_reached (new), 403 · platform.capability_not_entitled, 404 · catalog.not_found, 400 for an unknown preset or an instruction over 200 characters. Statements: session, membership, BEGIN, tenant context, authorization (2 permissions + capability, 1), item read (1), request_generation (1: quota lock, insert, enqueue), audit (1), COMMIT = 9.

---

8. Derived API

Group	Routes	Cases
Uploads	POST /assets/uploads, POST /assets/uploads/{uploadId}/completion	AS1, AS2
Library	GET /assets, GET /assets/{assetId}, PATCH /assets/{assetId}, POST /assets/{assetId}/{archival,restoration}	AS3–AS6
Later	GET /assets/{assetId}/renditions/{rendition}/access, GET /assets/generations/{id}, POST /assets/generations/{id}/{approval,rejection}, POST /catalog/items/{itemId}/image-generations	AS14–AS16, AC6
Catalog	PUT /catalog/items/{itemId}/images ({ images, variants? }: the item list and the lists of its variants), PUT /catalog/item-images	AC1, AC2, AC5
Internal	AssetUsageContract, AssetDeliveryContract	AS12, AS13
Media worker	jobs process_upload, purge_asset, render_profile; sweep expire_uploads (not a job)	AS7–AS11

Routes carry the /assets prefix (task names: uploads, completion, archival), never table CRUD (API_AND_SCHEMA_DISCIPLINE.md §1).

---

9. Vertical variations

Concept	Restaurant	Retail	Hospitality	Where
Item photo on the till tile	Yes (visual menu)	Optional (search-and-scan tills often hide images)	Extras	Assets + Catalog, common
Variant photos	Rare	Core (colour)	—	AC2, common
Gallery	Rare	Storefront later	Room galleries (Hospitality)	Catalog gallery role, common
Brand logo	Receipts, menu	Receipts, labels	Folios	Organization/commerce later, same contracts
Bulk upload	—	Later (import)	—	Its own design

Decided: no vertical-specific table or if (vertical === …) in Assets (ARCHITECTURE.md §14, R8). The till client decides whether to show tiles.

---

10. Authorization and plan

10.1 Permission codes

Code	Grants	Anchor	Capability gate
assets.media.manage	AS1, AS2, AS5, AS6 (later AS16 and, with catalog.items.manage, AC6)	Organization-wide	assets.media for AS1; assets.ai_generation for AC6
assets.media.view	AS3, AS4	Organization-wide	none

10.2 Seeded role mapping (proposal, D30)

Role	assets.media.manage	assets.media.view
organization_owner	✓	✓
manager	✓ (effective only organization-wide)	✓
cashier, waiter, kitchen, bar, sales_associate, stock_keeper

10.3 Capability and limits

One capability assets.media attached to a new Pionero version (the migration 0071/0075 pattern: copy the current version, add, publish offerings). The new version number is the current maximum version of Pionero + 1, resolved inside the migration (staff can create plan versions at runtime, platform.create_draft_plan_version_as_staff, runtime_grants.sql:91), never a literal. Limit definitions assets.active_assets (integer, unit assets) and assets.stored_megabytes (integer, unit megabytes), values per OD6. Later: assets.ai_generation capability and assets.ai_generations limit (integer, reset_period = 'month').

---

11. Security

OWASP topic (S9)	Decision	Where
Extension/type allow-list	Four image types; extension ignored entirely	AS1, AS7
Content-Type not trusted	Declared type must equal sniffed magic bytes and sharp's detected format	AS7
Signature validation alone is insufficient	Full decode and re-encode (content disarm and reconstruction); raw bytes are never served or kept beyond processing	§6.3
Polyglots	Re-encoding to WebP drops any trailing or embedded payload	§6.3
SVG / XML / XXE	SVG refused (OD4)	AS1
Filename	Server-generated keys; original_filename is metadata, sanitized, never in keys, URLs or headers; a future download uses RFC 6266 filename*	§5.2
Path traversal in keys	Keys are composed only from base32 tokens and fixed codes	§5.2
Size limits / DoS	10 MiB declared, enforced by S3's content-length-range and verified again by the worker; 40 MP for JPEG, PNG and WebP and 12 MP for AVIF (OD5); open-upload cap; throttle; quotas; media worker isolated from the OTP worker (OD14)	AS1, AS7
Storage location	Separate hosts: S3 (private, Block Public Access) for raw uploads (in/) and masters (m/); R2 public bucket only for re-encoded renditions	§6.1
Authentication and authorization	Session + tenant + permission before an intent; POST policy scoped to one exact key, one content type and a size range, 10 minutes	AS1
Media host	X-Content-Type-Options: nosniff and a restrictive CSP by transform rule; r2.dev disabled in production	A0
Takedown	Automatic Cloudflare purge-by-URL in AS10	AS10
CSRF	Bearer tokens, no cookies (FOUNDATION_HTTP_AND_OBSERVABILITY.md §13)	—
Malware scanning	Recommended out of scope for images (OD10): every image is decoded and re-encoded, and only the re-encoded bytes are stored and served. Residual risk: a libvips decoder vulnerability exploitable during decode in the worker. Mitigations: keep sharp current, worker runs as an unprivileged process with no database privileges beyond its functions, limitInputPixels, failOn. Documents (PDF) require scanning before they are ever accepted	§6.3
SSRF	No server-side URL fetch in v1; AI provider endpoint is fixed configuration	§6.7
Signed URL TTL	Upload: S3 POST policy valid 10 minutes with content-length-range up to the declared size; private GET 5 min; sensitive 60 s	§6.2, §6.4
Leaking private assets	Private renditions live in S3 p/ (Block Public Access on), never in R2 or behind the media domain; describe returns URLs only for public	AS12
Quota abuse	Reservation at intent time (only through reserve_upload: the runtime has no INSERT on assets tables), verified bytes at outcome, expiry sweep, in/ lifecycle, AWS Budgets and Cloudflare alerts (OD12); at most 20 × 10 MiB staged per organization	§6.2
Log redaction (SEC-1)	Presigned URLs never logged, audited or stored. Gap: the log redaction (redaction.ts:27-33) does not treat X-Amz-Signature as sensitive, while spans already do (node-instrumentation.ts:15-19). A2a adds signature to SENSITIVE_FIELD_NAME_WORDS (or the four cloud parameter names to ADDITIONAL_SENSITIVE_QUERY_PARAM_NAMES) with a spec, before the first presign	A2a
PII in images and EXIF	EXIF/XMP/IPTC removed by default output (S6); faces in product photos are the tenant's responsibility	§6.3
Retention and deletion	§6.8	AS10
Credentials	Separate IAM users per environment and service with prefix-scoped policies (§13.4); an R2 token scoped to the public bucket for the media worker only (S21); a Cloudflare token scoped to cache purge on the media zone; S3 clients always receive explicit credentials, never the SDK's default chain, because AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY in the environment are the SES key (§13.1)	A0

---

12. Performance and data design

12.1 Expected cardinalities (assumption)

Profile	Items	Images	Photos per item	Uploads per day (steady)
Small restaurant	50–300	50–300	~1	< 10
Restaurant group	300–1,500	300–2,000	1–2	< 30
Small retail	500–5,000	500–8,000	1–2 (variant colours)	10–100
Larger retail	5,000–50,000	5,000–75,000	1–3	100–1,000, bursts on import

Per asset stored bytes ≈ 0.5–2 MB across master and four renditions (§5.5, assumption). Rows per asset: 1 asset + 5 variants + 5 storage objects + 1 upload + 1–2 jobs.

12.2 Hot reads

Read	Class	Design
Image bytes	hottest	Served by Cloudflare from the public bucket; zero API calls
C17 till read with images	hot (in perf:http)	+1 statement on the 200 (describe, PK lookups on ≤ 2,000 ids): 8 → 9; the 304 stays at 7; no join to variants or storage objects (SG1–SG3); imageRef plus one template instead of full URLs (§6.4). The 200 is already a known breach at p50 (AGENTS.md §5.5: 23.99 ms on a 925-item outlet, cause: building and sending one large body), so A6 re-baselines catalog-till-sellables with the measured delta
C3 item read	frequent	+1 statement
AS3 polling	frequent during uploads only	One row + nothing else; client polls every 1 s, up to 30 s; not in perf:http
AS4 library	administrative	Keyset on SG12 index

Decided: no denormalized primary_asset_id on catalog.items: the existing unique partial index item_assets_one_item_primary_uq already makes the join an index lookup per item; a denormalized column would need its own trigger to stay right. Revisit only if EXPLAIN (ANALYZE, BUFFERS) on the "larger retail" profile shows otherwise.

12.3 Storage growth and cost (R2-only prices, S1; the recommended S3 + R2 split is compared in §6.1 and §13.8)

Profile	Images	Stored	Storage cost/month	One-time Class A (≈7 writes per asset)
Small restaurant	300	0.3 GB	inside free tier	2,100 ops, free tier
Small retail	8,000	8 GB	inside free tier per account, else $0.12	56,000 ops ≈ $0.25
Larger retail	75,000	75 GB	$1.13	525,000 ops ≈ $2.36
1,000 tenants mixed (assumption: 2,000 images each)	2 M	2 TB	≈ $30	≈ $63 one-time

Egress is free on R2 (S1), which is why option D serves public renditions from R2 (§6.1); on S3 the same 2 TB tenant base re-downloading tiles monthly (say 5 TB of reads) would cost about $450 (S10). Deduplication would save cents at these sizes.

12.4 Media worker throughput (assumption, measured in A3c)

One job ≈ download + one input decode + master encode + 4 encodes derived from the master + 5 uploads ≈ 0.5–1.5 s for a 12 MP photo on one vCPU → 2,500–7,000 images per hour per media-worker replica. A 50,000 image import ≈ 7–20 hours on one replica, 2–5 hours on four. Small tenants see "ready" in 1–3 s.

12.5 Statement budget

Counted the way the built routes are counted: every statement the request sends, including session, membership, BEGIN, tenant context and COMMIT (C19 = 8 as built, "K7 as built" in CATALOG_USE_CASES.md). Each slice pins its routes in test/e2e/statement-budget.e2e-spec.ts.

Route	Statements (target)
AS1 (first call)	session (1) + membership (1) + BEGIN (1) + tenant context (1) + authorization (1) + reserve_upload (1: usage lock, limits, idempotency claim, inserts, reservation) + audit (1) + COMMIT (1) = 8
AS1 (replay)	same, with the existing upload read (1) instead of the audit = 8
AS2	session + membership + BEGIN + tenant context + permission + complete_upload (1) + asset read for the answer (1) + COMMIT = 8
AS3, AS4	session + membership + BEGIN + tenant context + permission + read (1) + COMMIT = 7
AS5	10 when it writes (session, membership, BEGIN, tenant context, permission, read and lock for If-Match, update, audit, read the answer, COMMIT); 7 when unchanged
AS6	9 (session, membership, BEGIN, tenant context, permission, the definer function, audit, read the answer, COMMIT)
AC1	session + membership + BEGIN + tenant context + authorization + version lock + item lock + assertAttachable + delete + upsert + audit + item representation read (C3's statements) + COMMIT ≈ 13, pinned by A5b
AC5	as AC1 with set-based statements for all items, plus one audit statement per changed item (≤ 100): constant in N except the audit; A5c measures it
C17 200	8 as built + describe = 9
C17 304	7, unchanged (answers before any read)
C19	8 as built + describe = 9
AC6	session + membership + BEGIN + tenant context + authorization + item read + request_generation + audit + COMMIT = 9
AS16	session + membership + BEGIN + tenant context + permission + decide_generation (1) + audit + read the answer + COMMIT = 9

12.6 perf:http

C17 with images replaces its current row (hot); the catalog-till-sellables baseline in KNOWN_BREACHES is re-measured and updated in A6, because perf:http fails on a regression above 25% (AGENTS.md §5.5). AS1/AS2 are administrative and not measured. AS7 throughput and the media worker's peak RSS are measured by a dedicated script in A3c (perf:assets, proposed), reported in PERFORMANCE_BASELINE.md; that measurement is the A3c gate for the pixel cap and the service memory limit.

---

13. Infrastructure plan (AWS, Cloudflare, OpenAI, Railway)

Nothing here is executed by an agent: railway config apply, variable changes and every console action are the owner's (AGENTS.md §10). Values never appear in this document, only names.

13.1 Existing AWS usage and what we reuse

What exists today	Evidence	What the Assets work must not break	Reused?
SES sends email through SesConnector (SESv2Client, SendEmailCommand, one attempt, 10 s timeout)	src/foundation/messaging/ses/ses.connector.ts:1,67-90; src/foundation/messaging/messaging.module.ts:19-42	Nothing in this design changes SES code, variables, region or sender	No: separate principals
SES configuration: AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, SES_SENDER_EMAIL_ADDRESS, all-or-nothing	environment-variables.schema.ts:213-216, :297-309	These names are also the AWS SDK's default credential-chain variables: an S3 client built without explicit credentials would silently use the SES key. Decided: every Assets AWS client receives explicit credentials from ASSETS_S3_* variables and a unit test asserts it	The @aws-sdk/* v3 family (package.json:67)
Who sends: the worker dispatches the security outbox (OTP codes, invitations); the API also holds the SES variables	railway.ts:140-143 (api), :174-177 (worker); worker.module.ts:8-18; identity.module.ts:3,160 imports MessagingModule	The worker service stays exactly as it is; images go to media-worker (OD14)	No
Sending domain and identity	SES_SENDER_EMAIL_ADDRESS (value preserved, not readable here)	Assumption: a verified SES domain identity exists in the SES region; its DNS records (DKIM, SPF, MAIL FROM) live in Cloudflare DNS and must not be touched when adding media records	DNS zone only

Shared AWS account hygiene (Recommended, OD12). One AWS account holds SES and S3 (same billing, as the owner asked), so:

• Separate IAM principals: the existing SES principal keeps only SES sending permissions (A0 verifies it has no S3 permission); new principals per environment and service for S3 (§13.4). No wildcard actions or resources in any policy; no principal holds both SES and S3.
• Root account: MFA on, no access keys, used only for account-level tasks; daily work through IAM Identity Center or an admin IAM user with MFA.
• AWS Budgets: a monthly cost budget for the whole account with alerts at 50%, 80% and 100% (OD12), plus an S3-filtered budget.
• CloudTrail: the default management-events trail (bucket policy and IAM changes). S3 data events are not enabled in v1: billed per event and not justified while only public product photos exist; revisit with A7 (private and sensitive files).
• Rotation: access keys rotated every 90 days with the two-key overlap IAM allows per user (assumption: AWS's documented limit of two access keys per user, not fetched); the procedure is in the A0 checklist.

13.2 Accounts and ownership

Account	Holds	Owner and billing	MFA	Alerts
AWS (existing)	SES (today), S3 buckets ninaku-staging-assets, ninaku-production-assets, IAM principals	The company account owner (OD12)	Root and every human user	AWS Budgets 50/80/100%; CloudTrail management events
Cloudflare (existing)	DNS zone(s), media custom domains, R2 public buckets ninaku-staging-media-public, ninaku-production-media-public, cache/transform/WAF rules, API tokens	The company account owner (OD12)	Every member	Billing notification; R2 storage usage notification
OpenAI (new, A8)	Organization (verified, S30), one project per environment, API keys, spend limits	The company account owner (OD17)	Every member	Project hard monthly limit and 50% alert (S37)
Railway (existing)	api, worker, database-migrator, postgres, new media-worker	Existing	Existing	Existing

13.3 Environment matrix

Environment	Object storage	CDN	OpenAI	How tests reach it
Unit and integration tests, CI	In-memory fake ObjectStoragePort; a fake image-model port	—	Fake	Every slice; CI needs no cloud credential
Local development	A local S3-compatible server in a container for the manual browser flow, POST policies included (Decided: MinIO first, LocalStack as fallback; assumption: current image availability and POST-policy support are checked in A2a); public renditions written to a second local bucket and served by it	None	Fake by default; a developer key only on request	npm run scripts in A2a
Staging	ninaku-staging-assets (S3) + ninaku-staging-media-public (R2)	media-staging.<domain> (OD13)	Staging project with a low hard limit	Contract test of the POST policy (A2a) and a manual end-to-end upload
Production	ninaku-production-assets + ninaku-production-media-public	media.<domain>	Production project, ZDR if eligible	—

Staging and production never share a bucket, a principal, a token or an OpenAI project.

13.4 Per-service credentials and least-privilege policies

Principal (per environment)	Used by	Can do	Cannot do
ninaku-<env>-assets-api (IAM user)	api	Sign POST policies for in/* (its s3:PutObject permission is what S3 checks on the browser's POST)	Read anything; write outside in/; delete
ninaku-<env>-assets-media-worker (IAM user)	media-worker	Read and delete in/*; read, write, delete m/* and p/*; s3:ListBucket on the bucket without a prefix condition (the bucket holds only assets), so that HEAD on a missing key answers 404, not 403 (a HEAD carries no prefix parameter, so a prefix-conditioned list grant would not apply; assumption from the HeadObject documentation, not fetched; A2a's contract test proves it on the staging bucket)	Touch bucket configuration; SES
SES principal	api, worker	SES sending only: a new SES-only key replaces the current one through the A0 swap (step 2), without changing SES behavior	S3, R2, anything else
R2 token media-public-<env> (Object Read & Write, one bucket, S21)	media-worker	Write and delete public renditions	Other buckets
Cloudflare token media-purge-<env> (Cache Purge, media zone)	media-worker	Purge by URL (S22)	Anything else
database-migrator	—	No storage or OpenAI credential, ever	—

API principal policy (design text):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "SignUploadPoliciesForTheInboxOnly",
      "Effect": "Allow",
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::ninaku-<env>-assets/in/*"
    }
  ]
}

Media worker principal policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadAndClearTheInbox",
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:DeleteObject"],
      "Resource": "arn:aws:s3:::ninaku-<env>-assets/in/*"
    },
    {
      "Sid": "ManageMastersAndPrivateRenditions",
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
      "Resource": [
        "arn:aws:s3:::ninaku-<env>-assets/m/*",
        "arn:aws:s3:::ninaku-<env>-assets/p/*"
      ]
    },
    {
      "Sid": "ListTheAssetsBucketSoMissingKeysAnswer404",
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::ninaku-<env>-assets"
    }
  ]
}

Bucket policy (both environments): deny every request when aws:SecureTransport is false; Block Public Access stays on, so no statement can make the bucket public.

Credential delivery (Decided). Railway is not AWS compute, so there is no instance role. Options weighed: (a) long-lived IAM user keys with the policies above, in Railway variables, rotated every 90 days; (b) a base key that can only call sts:AssumeRole into a role with those policies, giving 1-hour credentials: the base key is just as long-lived and as powerful in effect, and every service needs a refresh loop; a presigned POST signed with temporary credentials also dies with them (S26); (c) IAM Roles Anywhere: needs a private certificate authority. (a), with the rotation procedure in A0 and CloudTrail recording key use.

Log redaction. X-Amz-Signature, X-Amz-Credential and X-Amz-Security-Token never reach logs: spans already redact them (node-instrumentation.ts:15-19), the log redaction gets signature in A2a (SEC-1), and the API never logs a POST policy or its fields (the policy travels in a form field, so the field names policy and x-amz-signature are added to the redacted names too).

13.5 DNS and Cloudflare configuration

Item	Setting
media.<domain> / media-staging.<domain>	Connected from the R2 bucket's custom-domain settings (proxied), per environment (R2-PB)
r2.dev	Disabled for both public buckets in production; allowed only for staging debugging (R2-PB)
Cache rule	media hosts, path /a/*: eligible for cache, respect origin Cache-Control (public, max-age=31536000, immutable set by the worker)
Transform rule (response headers)	X-Content-Type-Options: nosniff; Content-Security-Policy: default-src 'none'; img-src 'self'; sandbox
WAF	One rate-limiting rule per media host by IP (assumption: the plan in use includes at least one rate-limiting rule; else skip, R2 egress is free)
R2 CORS	GET from *, no credentials
S3 CORS	POST from the web app origins only (staging and production lists kept apart, like CORS_ALLOWED_ORIGINS, railway.ts:24-41)
Tokens	R2 token per environment (one bucket); cache-purge token per zone
Existing records	SES DKIM/SPF/MAIL FROM and every other record untouched

13.6 Railway variables (names only)

Variable	api	media-worker	worker
ASSETS_S3_REGION, ASSETS_S3_BUCKET	✓	✓
ASSETS_S3_API_ACCESS_KEY_ID, ASSETS_S3_API_SECRET_ACCESS_KEY	✓
ASSETS_S3_WORKER_ACCESS_KEY_ID, ASSETS_S3_WORKER_SECRET_ACCESS_KEY		✓
ASSETS_R2_ACCOUNT_ID, ASSETS_R2_PUBLIC_BUCKET, ASSETS_R2_ACCESS_KEY_ID, ASSETS_R2_SECRET_ACCESS_KEY		✓
ASSETS_PUBLIC_BASE_URL	✓	✓
ASSETS_CDN_ZONE_ID, ASSETS_CDN_PURGE_TOKEN		✓
OPENAI_API_KEY, OPENAI_PROJECT_ID, OPENAI_IMAGE_MODEL, OPENAI_IMAGE_QUALITY (A8)		✓
DATABASE_* (user ninaku_worker), NODE_ENV, OTEL_*	existing	✓ (process role media-worker, telemetry name ninaku-media-worker, ASSETS_STAGE_SPECS.md §7)	existing
CURSOR_SIGNING_KEY, ACCESS_TOKEN_SIGNING_KEY, TOTP_SECRET_ENCRYPTION_KEY, SECURITY_OUTBOX_ENCRYPTION_KEY	existing	never (the media-worker role does not read them)	existing
AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, SES_SENDER_EMAIL_ADDRESS	existing, unchanged	never	existing, unchanged

Secrets use preserve() in .railway/railway.ts; ASSETS_PUBLIC_BASE_URL, model names and the bucket names are plain literals per environment, like CORS_ALLOWED_ORIGINS.

13.7 A0 owner checklist (in order)

1. Answer OD1, OD12, OD13, OD14 (and OD17 before A8).
2. AWS: confirm root MFA and no root keys; create AWS Budgets (account and S3-filtered). Do not edit the current SES key in place (it may be an administrator key, and narrowing it could stop the security emails): create a new IAM user with SES sending permission only, put its key in the Railway variables AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY of api and worker in staging, send a test OTP (sign-up code) and an invitation, repeat in production, and only then deactivate the old key (delete it a week later). This changes credentials, not SES behavior.
3. AWS, per environment: create bucket ninaku-<env>-assets in us-east-1 with Block Public Access on, Object Ownership "Bucket owner enforced", SSE-S3, versioning off; lifecycle rule in/ → expire 1 day and abort incomplete multipart uploads after 1 day; bucket policy denying non-TLS; CORS for POST from the web app origins.
4. AWS, per environment: create IAM users ninaku-<env>-assets-api and ninaku-<env>-assets-media-worker with the §13.4 policies; one access key each; store them only in Railway.
5. Cloudflare, before anything else: confirm R2 is enabled on the account (it may ask for a payment method even on the free tier: unverified, OD22); confirm the media domain's zone is in the same Cloudflare account as the R2 buckets (a custom domain must be a zone of that account, assumption); confirm no media or media-staging DNS record already exists in the zone. Then, per environment: create R2 bucket ninaku-<env>-media-public (location hint enam, S5); connect media[-staging].<domain>; disable r2.dev in production; R2 CORS GET *; the cache and transform rules; the R2 token (one bucket) and the cache-purge token; billing and R2 usage notifications.
6. Railway: add the media-worker service (same repository, entrypoint node dist/media-worker, a memory limit set from A3c's measurement; until then 1.5 GB, recommended from the local measurement and re-measured on Railway's Linux) and the §13.6 variables, through .railway/railway.ts and railway config plan showing only those changes; the owner applies.
7. Staging smoke test after A2c: upload one photo from a phone, see it ready, open its tile URL through media-staging.
8. Rotation (every 90 days, per principal): create the second key, update the Railway variable, redeploy, confirm traffic, deactivate the old key, delete it a week later.
9. OpenAI (A8): verify the organization (S30), create one project per environment, set enforced hard monthly limits and a 50% alert (S37), request ZDR for production if eligible (S35), create a project key, store it only in Railway.

13.8 Monthly cost estimate per profile

Assumptions as in §6.1 plus: AI images at gpt-image-1.5 medium 1024×1024, $0.034 each (S33); worker reads ≈ 3 MB per upload from S3; the media-worker Railway service cost is not estimated (unknown: depends on Railway's usage pricing and A3c's memory).

Profile	Images stored	Storage + requests + transfer (option D)	CDN	AI generations	Total
Small restaurant	300 (0.3 GB)	≈ $0.01	$0 (Cloudflare, free egress from R2)	20/month ≈ $0.68	≈ $0.70
Restaurant chain (20 outlets, one catalog)	2,000 (2 GB)	≈ $0.05	$0	50/month ≈ $1.70	≈ $1.75
Retail, 50,000 images	50 GB	≈ $0.90 (+ ≈ $4.50 once for the worker reading 50,000 uploads)	$0	200/month ≈ $6.80	≈ $7.70
Platform, 1,000 organizations	2 TB	≈ $46	$0	20,000/month ≈ $680	≈ $726

The AI line dominates as soon as generation is used, which is why OD18 sets a monthly limit per plan and OpenAI's project hard limit caps the total.

13.9 Third-party outage register

Outage	Effect	Behavior (Decided)
S3 unavailable	New uploads fail at the POST; processing jobs cannot read or write	The client shows "try again"; an unused intent expires and its quota is released (AS9); jobs re-queue with capped backoff and no attempt cap, so assets wait in processing instead of failing; an alert fires after 1 hour; delivery is unaffected (public renditions are on R2)
R2 unavailable	Public images not served on cache misses; renditions cannot be written	Cached images keep serving; the till's offline cache keeps showing tiles; jobs re-queue without an attempt cap
Cloudflare unavailable	Media domain down (and any other proxied hostname)	Tills show cached tiles; no fallback domain in v1 (accepted: a second CDN doubles configuration for a rare event)
OpenAI unavailable or rate-limited	Generation requests wait	Jobs retry with Retry-After, then fail and release quota; the UI says "try later"; nothing else depends on OpenAI
SES unavailable	Unchanged by this design	Unchanged (security outbox, D26)
Railway media-worker down	Uploads stay processing; generations stay queued	Nothing is lost (jobs in PostgreSQL); the api and the OTP worker are unaffected (OD14)

---

14. Delivery slices

This table is the overview; the PR splits, line estimates and migration numbers that a writer follows are those of ASSETS_STAGE_SPECS.md (§27 lists every PR: A1b is three PRs, A1c, A2a-1, A3c, A4b and A5b two each, A8a three).

Each slice is one PR into staging, ≤ 400 changed lines (AGENTS.md §7), counting the canonical mirror of every migration (AGENTS.md §8), which roughly doubles the SQL lines. Sizes: S 1–2 h, M 3–5 h, L 6 h+. Line counts are estimates; a slice that crosses 400 splits at the named point.

#	Slice	Cases	Depends on	Size	Est. lines	Risk	Security-critical	Migration	Measured
A0	Infrastructure (owner-run, §13.7): AWS (budgets, root MFA, S3 bucket per environment with prefixes, lifecycle, CORS, TLS-only policy, IAM users per service), Cloudflare (R2 public bucket per environment, media custom domain, r2.dev off in production, cache and transform rules, R2 and cache-purge tokens, alerts), OpenAI later (A8); .railway/railway.ts declares the media-worker service and the §13.6 variables with preserve()	—	OD1, OD12–OD14	S	≈ 80 (railway.ts)	Medium	Yes (credentials)	No	railway config plan shows only the new service and variables
A1a	Structure: SG1–SG5, SG9, SG12, SG16–SG18 on existing tables; SG6–SG8 tables, RLS, usage backfill; grants: runtime USAGE, SELECT on assets, asset_variants, uploads, organization_usage, storage_providers, column UPDATE (display_name) on assets.assets only (archive and restore go through definer functions that keep the usage counters), no INSERT; worker nothing yet. Also, in the same PR (OD7): a new decision D31 in DECISIONS.md (Spanish: "Las tareas pesadas de un módulo usan una cola propia del módulo con organization_id, con la forma de events.outbox_records; events.* queda para eventos de integración") and the amendment of AGENTS.md §5.4 naming the module-owned queue	—	—	M	≈ 650 → split A1a-1 (columns, triggers, grants, D31, AGENTS; ≈ 350) and A1a-2 (three tables, RLS, backfill; ≈ 330)	High	Yes	Yes (0083, then the next free number)	db:test contracts
A1b	Admission: reserve_upload and complete_upload (SECURITY DEFINER, the runtime's only write path for status and creation), seeds (two providers, s3-private and r2-public, permissions §10.1 and roles §10.2, capability assets.media on Pionero current maximum + 1, limit definitions per OD6, audit kind and actions), quota and idempotency contracts	—	A1a	M	≈ 500 → split seeds (≈ 200) from functions (≈ 300)	High	Yes	Yes (next free number)	db:test
A1c	Processing contract: claim_processing_job (one job), record_processing_outcome, expire_uploads, reconcile_usage; worker grants (USAGE, EXECUTE on these only); lease contracts	—	A1a	M	≈ 400	High	Yes	Yes (next free number)	db:test
A2a	Module skeleton, ObjectStoragePort, S3 POST-policy signer and the S3-API object adapter for S3 and R2 (explicit credentials only), 11 storage variables in the environment schema, SEC-1 log redaction (signature, policy, x-amz-signature). Contract check (no longer a gate): against the local S3-compatible server and the staging bucket, a POST one byte over the declared size, with another content type or another key is refused by S3, and a HEAD on a missing key answers 404	—	A0 (staging), A1b	L	≈ 650 → split A2a-1 (skeleton, port, environment schema, redaction; ≈ 300) and A2a-2 (POST signer, S3/R2 adapter, credential-isolation spec, the local-server contract test; ≈ 350)	High	Yes	No	—
A2b	AS1 and AS3	AS1, AS3	A2a	M	≈ 400	High	Yes	No	—
A2c	AS2 and the upload e2e journey with a fake storage adapter	AS2	A2b	S	≈ 300	Medium	Yes	No	—
A3a	media-worker entrypoint and module, job loop (claim one, record), staging cleanup, AS9 sweep	AS9 (sweep)	A1c, A2c	M	≈ 380	Medium	Yes	No	—
A3b	Image pipeline: sniff, decode once into the master, renditions from the master, sharp dependency	AS7	A3a	L	≈ 550 → split A3b-1 (magic-byte sniffing, dimension and pixel checks, master decode; ≈ 300) and A3b-2 (renditions, outputs to S3 and R2, outcome recording; ≈ 250)	High	Yes (decoder)	No	—
A3c	Retry classes (storage errors without attempt cap, processing errors 5 attempts), dead letter, assets.requeue_dead_letters runbook function (OD21), perf:assets, memory limit from measured peak RSS (gate for OD5)	AS8	A3b	M	≈ 400	High	Yes	Yes (next free number, the requeue function)	throughput, peak RSS
A4a	Library list, rename, archive, restore	AS4–AS6	A2b	M	≈ 400	Medium	No	No	—
A4b	Purge: purge_asset_begin/finish, deletes from S3 (m/, p/) and R2 (public renditions), automatic CDN purge by URL, offboarding enumeration designed	AS10	A3c, A5b	M	≈ 450 → split SQL (≈ 250) from worker (≈ 200)	High	Yes (erasure)	Yes (next free number)	—
A5a	AssetUsageContract, AssetDeliveryContract, MODULE_CONTRACTS.md §15 rows	AS12, AS13	A3b	M	≈ 350	High	Yes	No	—
A5b	Catalog: item_assets grants, bump triggers, index (SG11), audit actions; AC1–AC3	AC1–AC3	A5a	L	≈ 450 → split migration (≈ 150) from routes (≈ 300)	High (cross-module locks)	Yes	Yes (next free number)	—
A5c	Bulk image command	AC5	A5b	M	≈ 300	Medium	No	No	statement count
A6	Till read with imageRef and template, ETag fingerprint, statement-budget update (9/7/9), KNOWN_BREACHES re-baseline	AC4	A5b	M	≈ 250	High (hot path)	No	No	C17 p50–p99, 1 and 16 clients
A7	Private and sensitive delivery (blocked by OD15)	AS14	A3c, OD15	M	≈ 400	Medium	Yes	Maybe	—
A8a	AI SQL: SG19–SG21 (with create_generated_asset), request_generation, consume/release functions, capability assets.ai_generation, limit assets.ai_generations (integer, monthly), audit actions	—	A1c, OD9, OD15, OD17, OD18, OD20	M	≈ 500 → split tables (≈ 250) from functions and seeds (≈ 250)	High	Yes	Yes (next free number)	db:test
A8b	AssetGenerationContract, prompt builder and presets, AC6 route, AS15 read	AS15, AC6	A8a, A5b	M	≈ 400	High	Yes (prompt input)	No	—
A8c	Media worker: generation claim loop (concurrency 2), generate_image job, OpenAI client (fixed endpoint, key from variable, timeout 180 s), re-queue on 429/5xx, moderation and refusal handling, quota consume/release, create_generated_asset and pipeline hand-off	AS15w	A8b, A3c	L	≈ 550 → split A8c-1 (OpenAI client port and adapter, error classification, redaction of prompts and bodies; ≈ 250) and A8c-2 (claim loop, job, asset creation, quota; ≈ 300)	High	Yes (secret, cost)	No	provider latency, cost per image
A8d	Review: AS16 approval/rejection, not_approved in assertAttachable, aiGenerated in delivery and the till, disclosure label contract (OD19)	AS16	A8c	M	≈ 350	Medium	Yes	No	—

Default order: A0 ∥ A1a → A1b ∥ A1c → A2a-1 → A2a-2 → A2b → A2c → A3a → A3b-1 → A3b-2 → A3c → A5a → A5b → A6 → A5c → A4a → A4b → A7 → A8a → A8b → A8c-1 → A8c-2 → A8d (A7 and A8 wait for OD15). A4 moves after A6 because a restaurant can live without the library list before it can live without the till image; nothing is purged before A4b, so failed and archived assets simply wait.

14.1 Stage specifications

Every stage, A0 to A8d, is specified in ASSETS_STAGE_SPECS.md: goal, preconditions, deliverables per file, draft DDL for SQL stages, routes with schemas and statement counts for API stages, worker rules, exact test titles, mutation targets, security checks, gates, rollout and the definition of done. The owner's infrastructure stage A0 is the ordered checklist of ASSETS_INFRASTRUCTURE_RUNBOOK.md. The specifications are the source for the writers; where they refine a line of this document (a function signature, a migration number), the specification wins and this document was updated in the same change.

Status of every slice: specified on 2026-10-06; A1a to A6 (A4b included) are built, each with its "as built" note below; A7 and A8 are blocked on OD15.

A1a-1 as built (migration 0083_assets_lifecycle_columns, baseline revision 93)

Piece	As built
Columns (SG1–SG5, SG9)	As the stage DDL: assets.assets gains status, ready_at, failed_at, failure_code, delivery_token (NOT NULL, unique, ^[a-z2-7]{26}$), rendition_profile, media_kind, source_kind, created_by_membership_id (tenant-safe FK assets_created_by_membership_fk); assets.asset_variants gains failure_code with asset_variants_failure_code_chk. The migration refuses a non-empty assets.assets with assets_lifecycle_requires_empty_table (23514) and rolls back whole
Triggers (SG16–SG18)	assets_guard_status_trg (assets.guard_asset_status, BEFORE UPDATE OF status, archived_at): only the stage's transition table, same status always allowed, a purging asset keeps its status and archived_at; refusal constraint assets_status_transition. assets_protect_access_class_trg refuses any change with assets_access_class_immutable. assets_ready_requires_renditions_trg on assets and asset_variants_ready_asset_renditions_trg on asset_variants (deferred) require a ready asset to have original and every code of assets.profile_rendition_codes(rendition_profile) ready; a profile with no codes cannot be ready (a refinement of the spec, so an unknown profile never passes with its original alone). No trigger function is SECURITY DEFINER; errors name their code in CONSTRAINT
Indexes (SG12)	assets_organization_active_idx replaced by (organization_id, created_at DESC, id DESC) WHERE archived_at IS NULL; new assets_organization_archived_idx with WHERE archived_at IS NOT NULL
Grants	Runtime: USAGE on assets; SELECT on assets, asset_variants, storage_providers; UPDATE (display_name) on assets; EXECUTE on profile_rendition_codes(smallint) (the deferred trigger calls it as the writing role). Nothing for ninaku_worker. Asserted from information_schema.role_table_grants and role_column_grants
Proof	database/tests/contracts/assets-lifecycle-contracts.ts (NINAKU_ASSETS_LIFECYCLE_OK), the seven titles of the stage. Mutations that each fail a test: ready → pending allowed, p1-detail dropped from profile 1, the access class trigger dropped, UPDATE (status) or UPDATE (archived_at) granted. 0083 applied by db:prepare on a revision 92 database leaves a schema identical to a fresh revision 93 install

A1a-2 as built (migration 0085_assets_uploads_jobs_and_usage, baseline revision 95)

Piece	As built
Tables (SG6–SG8)	Exactly the stage DDL: assets.uploads (state machine with uploads_state_shape_chk, staging key ^in/[a-z2-7]{26}$ unique per provider, JPEG/PNG/WebP/AVIF of 1 byte to 10 MiB, idempotency key unique per organization with its SHA-256 request hash, expiry after creation), assets.processing_jobs (lease shape of events.outbox_records, error_class, processing_jobs_one_open_uq on (asset_id, job_kind) while pending or leased) and assets.organization_usage (three non-negative counters). Indexes: uploads_open_expiry_idx, uploads_organization_open_idx, processing_jobs_claim_idx, processing_jobs_one_open_uq, processing_jobs_dead_letters_idx
Usage row	organizations_assets_usage_insert_trg (AFTER INSERT ON organization.organizations) runs assets.create_organization_usage(), SECURITY DEFINER, search_path = pg_catalog, pg_temp, EXECUTE revoked from PUBLIC and granted to nobody; a plain insert, so an existing row is refused (organization_usage_pkey), never overwritten. The migration backfills every existing organization once with ON CONFLICT DO NOTHING; the canonical file has no backfill because a fresh install has no organizations (the catalog_versions precedent)
RLS and grants	RLS enabled on the three tables with one FOR SELECT tenant policy each (scalar subquery); no insert, update or delete policy (the stage spec wins over SG6's insert and update policies). Runtime: SELECT on uploads and organization_usage; no grant on processing_jobs to anyone; nothing for ninaku_worker. The A1a-1 contract's exact runtime grant list now includes both tables
Proof	database/tests/contracts/assets-tables-contracts.ts (NINAKU_ASSETS_TABLES_OK), the five titles of the stage plus RLS, definer and index checks. An unknown job state is refused by processing_jobs_lease_shape_chk, which PostgreSQL evaluates before processing_jobs_state_chk (name order). Mutations that each fail a test: processing_jobs_one_open_uq dropped, the usage trigger made ON CONFLICT DO UPDATE, a runtime INSERT grant added to runtime_grants.sql. 0085 applied by db:prepare on a revision 94 database with three existing organizations backfills three zeroed usage rows and leaves a schema (with privileges) identical to a fresh revision 95 install

A1b-1 as built (migration 0086_assets_vocabulary, baseline revision 96)

Piece	As built
Seeds	Providers s3-private (s3, ASSETS_S3) and r2-public (cloudflare_r2, ASSETS_R2); permissions assets.media.manage and assets.media.view on the system roles organization_owner and manager only (0070_assets.sql); capability assets.media and the integer, never-reset limit definitions assets.active_assets (assets) and assets.stored_megabytes (megabytes) (0060_platform.sql); resource kind assets.asset and the four tenant configuration actions upload_requested, renamed, archived, restored (0380_audit.sql). Every insert is ON CONFLICT DO NOTHING; no grant changes
Pionero version	One idempotent DO block, byte-identical in the migration and at the end of 0060_platform.sql: under a lock on the plan row it takes the active Pionero version with the highest number, publishes a new version numbered the highest version number of the plan plus one (the rule of platform.create_draft_plan_version_as_staff, 0060:3058, because plan_versions_plan_version_uq covers drafts too and "active + 1" would collide with a staff draft) with every capability and limit of that version plus assets.media, 5,000 and 10,240, copies its active offerings (market, currency, interval, amount, trial days, and also visibility and target organization, so a private offering never becomes public) before retiring it, and returns when any Pionero version already has assets.media. It refuses with platform_pionero_assets_seed_missing when there is no active Pionero version or the capability or a limit definition is missing. A fresh install yields version 5
Proof	database/tests/contracts/assets-seed-contracts.ts (NINAKU_ASSETS_SEED_OK), the two titles of the stage; the second replays the migration block twice, inside a rolled-back transaction, on a Pionero plan with an active version 6 (a private, a paused and two public offerings) and a draft version 7, expecting one new active version 8. Mutations that each fail a test: a hard-coded version number, "active + 1", no idempotency return, offerings read after the retirement, the permission given to cashier. 0086 applied by db:prepare on a revision 95 database with three organizations, three assets and a staff draft version 5 publishes version 6, keeps version 5 a draft and leaves a schema (with privileges) identical to a fresh revision 96 install

A1b-2 as built (migration 0087_assets_admission_functions, baseline revision 97)

Piece	As built
Functions	assets.reserve_upload(...) (the stage signature) and assets.complete_upload(uuid), SECURITY DEFINER, search_path = pg_catalog, pg_temp, EXECUTE revoked from PUBLIC and granted to ninaku_runtime only (migration and runtime_grants.sql; the canonical file only revokes, like every runtime grant). Both call identity.assert_tenant_context(), take the organization only from identity.current_organization_id() and refuse a transaction outside READ COMMITTED with assets_admission_isolation (0A000). No permission or capability check in SQL: the route authorizes first (OperationAuthorizationContract, §9.1 of the stage specification)
reserve_upload	In the stage order: lock the usage row FOR UPDATE (INTO STRICT: a missing row fails instead of admitting unserialized); an upload with the same (organization, idempotency key) answers existing with its stored asset, upload, state, request hash, staging key and expiry (the application compares the hash) before any refusal; then assets_access_class_unavailable, assets_asset_limit (active_asset_count + 1 > limit), assets_storage_limit (stored_bytes + reserved_bytes + byte_size > limit × 1048576) and assets_open_uploads_limit (20 or more uploads issued or received, the predicate of uploads_organization_open_idx), all 23514; platform.effective_limit with no row or unlimited is no ceiling. Inserts the asset (pending, created_by_membership_id = identity.current_membership_id()), the original variant (pending) and the upload (issued, provider s3-private, key in/<staging token>), adds 1 and the declared bytes to the usage row, answers created
complete_upload	Locks the upload FOR UPDATE filtered by the context organization; answers not_found (foreign or unknown), rejected, already_received (received, verified) or expired (state expired, or issued with expires_at <= now()) without writing; otherwise locks the asset FOR UPDATE (UC AS2; only on the writing path, after the upload, so a repeat never waits on the asset), sets the upload received with received_at = now(), the asset and its original processing, and inserts one process_upload job (uuidv7())
Proof	database/tests/contracts/assets-admission-contracts.ts (NINAKU_ASSETS_ADMISSION_OK): five titles of the stage, the stage's concurrency title (two psql sessions; kept in the contract script because database/tests/concurrency/ was outside this stage's edit surface), and two more: the definer shape, grants and isolation, and the asset row lock (a FOR KEY SHARE holder of the asset makes a completion wait; a plain status update would not). The archive and restore title belongs to A1b-3. Mutations that each fail a test: the usage row lock removed, the organization filter of complete_upload removed, an organization parameter added, the existing return removed, reserved_bytes left out of the storage check, the asset lock removed, EXECUTE granted to ninaku_worker in runtime_grants.sql. 0087 applied by db:prepare on a revision 96 database with three organizations, assets and issued uploads leaves a schema (with owners and privileges) identical to a fresh revision 97 install

A1c-1 as built (migration 0088_assets_processing_outcome_functions, baseline revision 98)

Piece	As built
Functions	assets.claim_processing_job(varchar, uuid, integer, varchar[]) and assets.record_processing_outcome(...) (the stage signatures), SECURITY DEFINER, search_path = pg_catalog, pg_temp, EXECUTE revoked from PUBLIC and granted to ninaku_worker only, with USAGE on schema assets and no table privilege (migration and runtime_grants.sql; the canonical file only revokes). Neither reads the tenant context; both refuse a transaction outside READ COMMITTED with assets_processing_isolation (0A000, §1.1 of the stage specification). expire_uploads and reconcile_usage_batch are A1c-2's
claim_processing_job	Refuses a lease outside 30–900 seconds (assets_job_lease_seconds); takes at most one job of the requested kinds that is pending with available_at <= now() or leased with lease_expires_at <= now(), ordered by available_at, id, FOR UPDATE SKIP LOCKED; leases it to the owner and token (the attempt count is untouched); returns the job, its asset's delivery token, access class and profile, and its upload (id, staging provider code and key, declared type and size; NULL when the asset has no upload)
record_processing_outcome	Locks the job FOR UPDATE; a job that is not leased, has another token or an expired lease is assets_job_lease_lost. assets_outcome_shape for: an unknown outcome, parallel arrays of different lengths, arrays on a non-ready outcome or none on ready, an error code on ready or none on a failure, any outcome but retry_storage on a job other than process_upload (purge storage errors, A4b, and generation re-queues, A8c-2, use retry_storage), and on ready codes that are not exactly original plus the profile's, an original id that is not the asset's, a rendition id that already exists or an unknown provider code. Retries refuse available_at missing or more than 15 minutes ahead (assets_retry_backoff). The writing outcomes (ready, failed_permanent, the fifth retry_processing) lock, in the lock order of §7, the usage row, then the asset, its upload and its original variant FOR UPDATE, which serializes them with the deferred ready-renditions check's unlocked read, and refuse an asset that is not processing or an upload that is not received (assets_outcome_state). A failure releases the active asset slot only while the asset is not archived (SG8: an archived asset is no longer counted). Known limits, requirements of A3c (ASSETS_STAGE_SPECS.md §14): an expired lease reclaimed by the claim does not increment attempt_count and keeps its old available_at, so a worker that crashes before recording (for example out of memory on a huge image) gets the same job back forever; and a job whose asset is no longer processing or whose upload is no longer received is refused with assets_outcome_state on every terminal outcome, stays leased and is reclaimed without bound
Proof	database/tests/contracts/assets-processing-contracts.ts (NINAKU_ASSETS_PROCESSING_OK): the six A1c-1 titles of the stage, its concurrency title (two psql sessions, kept in the contract script as A1b-2 did) and the asset row lock (a FOR KEY SHARE holder makes a ready outcome wait). Inside those titles the contract also proves the accepted lease bounds 30 and 900, assets_outcome_state for a failed asset and for a verified upload (the job stays leased), assets_outcome_shape for an unknown outcome, an error code on ready, variants on a retry and retry_processing or failed_permanent on a purge_asset job (whose retry_storage is accepted), assets_retry_backoff for a retry without available_at, and that an archived asset failed permanently or dead-lettered at the fifth error keeps its active count and releases its reserved bytes exactly once. The A1a-1 lifecycle contract now expects USAGE on assets for the worker. Mutations that each fail a test: SKIP LOCKED dropped, the lease-expiry check dropped from the record and from the claim, storage retries capped at five, active_asset_count forgotten on a failure, an archived asset uncounted twice, the asset lock dropped, the code-set check dropped, the assets_outcome_state guard dropped, the job-kind check dropped, EXECUTE granted to ninaku_runtime in runtime_grants.sql. 0088 applied by db:prepare on a revision 97 database with organizations, assets, uploads and jobs leaves a schema (with owners and privileges) identical to a fresh revision 98 install

A1c-2 as built (migration 0089_assets_upload_expiry_and_usage_reconciliation, baseline revision 99)

Piece	As built
Functions	assets.expire_uploads(integer) and assets.reconcile_usage_batch(uuid, integer) (the stage signatures), SECURITY DEFINER, search_path = pg_catalog, pg_temp, EXECUTE revoked from PUBLIC and granted to ninaku_worker only (migration and runtime_grants.sql; the canonical file only revokes). Neither reads the tenant context; both refuse a transaction outside READ COMMITTED (assets_processing_isolation) and a batch that is not 1–500 (assets_sweep_batch)
Counting predicate (SG8)	One helper, assets.counts_as_active_asset(varchar, timestamptz): pending, processing or ready and not archived; plain SQL, IMMUTABLE, EXECUTE revoked from PUBLIC and granted to nobody (only the definer functions call it). expire_uploads, reconcile_usage_batch and record_processing_outcome use it; 0089 replaces record_processing_outcome with that one line changed and no change of behaviour (it only fails a processing asset, so the predicate equals "not archived" there)
expire_uploads	Reads up to p_batch issued uploads with expires_at <= now(), oldest first (expires_at, id), without a lock; for each, locks in the lock order of §7 the usage row, the asset, the upload FOR UPDATE SKIP LOCKED re-checking issued and expired (a held or already settled upload is skipped, never waited for, never settled twice) and the original variant; sets the upload expired (settled_at), the asset and its original failed (assets.upload_expired, failed_at), releases the declared bytes once and the active asset slot only while the asset still counts (an asset archived before or while the sweep waits is not uncounted twice: F8), and returns the upload id, its staging provider code and key for the worker to delete. No job is touched (an issued upload has none)
reconcile_usage_batch	For up to p_batch organizations whose usage row id is greater than p_after (all when NULL), in id order: locks the usage row FOR UPDATE, then in a new statement (a fresh READ COMMITTED snapshot, so a reservation that committed while it waited is counted) sets active_asset_count from the predicate, stored_bytes to the sum of byte_size of ready variants with an available primary storage object, and reserved_bytes to the declared bytes of issued and received uploads. Returns the last organization processed, NULL only when none follows p_after. Purge's per-organization reconciliation (AS10, SG8 reconcile_usage) is A4b's
Proof	database/tests/contracts/assets-expiry-contracts.ts (NINAKU_ASSETS_EXPIRY_OK, registered after the processing script; a new script because the processing one is already 777 lines): the stage's two titles, plus frees the open uploads of an organization for new reservations once the sweep expires them (20 open uploads refuse a 21st with assets_open_uploads_limit; once they expire and are swept a new reservation is created), the grant and predicate title, and four races on two psql sessions: a held expired upload is skipped and swept next time; an archive committed while the sweep waits on the usage row is uncounted once; of two concurrent sweeps only one settles an upload; an archive committed while a failed_permanent outcome waits is uncounted once; a reservation committed while the reconciliation waits is counted. The reconciliation title also proves that the counters the functions maintained equal the reconciled ones. The A1c-1 grant title now lists the four worker functions. Mutations that each fail a test: SKIP LOCKED dropped from the expiry, the expiry's usage row lock dropped, an unconditional active decrement in the expiry and in record_processing_outcome, the reservation not released, the re-check of the locked upload dropped, newest first, the reconciliation's usage row lock dropped, received uploads left out of reserved_bytes, the batch limit ignored, archived assets counted (in the reconciliation and in the helper), EXECUTE on expire_uploads granted to ninaku_runtime and on the helper to ninaku_worker in runtime_grants.sql. Sweeping received uploads in the candidate scan survives because the re-check on the locked row refuses them (equivalent mutant). A ready variant without an available primary object cannot be built (the storage trigger refuses it), so the available filter of stored_bytes has no failing test. 0089 applied by db:prepare on a revision 98 database with three organizations, expired, archived and expired, received (with a job) and open uploads leaves a schema (with owners and privileges) identical to a fresh revision 99 install; on it the worker's sweep expired the six expired uploads and left each organization at 2,0,4096
Carried to A1b-3	archive_asset changes active_asset_count, so it must lock the usage row before the asset, like every writer here; §7 says archive "locks only the asset", which would deadlock against a sweep or an outcome holding the usage row and waiting for that asset. Done in A1b-3 (below), and §7 now says so

A2a-1a as built (process roles and assets environment groups, no migration)

Piece	As built
Process role	src/foundation/config/values/process-role.ts: PROCESS_ROLE (api, worker, media-worker), databaseUserFor (api → ninaku_runtime, the other two → ninaku_worker) and serviceNameFor (ninaku-api, ninaku-worker, ninaku-media-worker, the last added to SERVICE_NAME). src/main.ts, src/worker.ts, WorkerConfigModule, DatabaseModule and WorkerDatabaseModule pass a process role; DatabaseRuntimeRoleGuardService receives the process role and checks databaseUserFor(role)
Schemas	validateEnvironmentVariables(raw, role): api and worker keep one shape and one type (EnvironmentVariables, the four identity keys required); media-worker has its own shape and type (MediaWorkerEnvironmentVariables: database, logging, telemetry and its storage group only), so the identity keys, SES, Wasender, OAuth and outbox variables are not read there even when set. The value parsers moved to schema/environment-value-parsers.ts, the groups to schema/assets-storage-variables.ts
Groups (S4)	API upload-signing group and media-worker storage group, each all-or-nothing with the reportPartiallyConfiguredChannel message; ASSETS_PUBLIC_BASE_URL must be an absolute https origin without path. A non-blank variable of a group the process role does not own (computed from both groups, so the shared ASSETS_S3_REGION, ASSETS_S3_BUCKET and ASSETS_PUBLIC_BASE_URL are refused only in worker) fails the boot with <KEY> belongs to another process role. No variable has a default value. The CDN purge and OpenAI groups join with A4b and A8c-1
Settings	AppConfigService.assetsStorageSettings(): the API group or undefined
Redaction	signature in SENSITIVE_FIELD_NAME_WORDS (covers X-Amz-Signature and the x-amz-signature POST field; X-Amz-Credential and X-Amz-Security-Token were already covered by credential and token); policy as an exact field name (case-insensitive, so retentionPolicy is not affected), which also makes it a sensitive query parameter. The log string redactor masks the value of X-Amz-Signature, X-Amz-Credential, X-Amz-Security-Token and Signature (CloudFront-style) query parameters wherever a URL or query text appears in any logged string (after ? or &, at the start of a bare query string, after whitespace, a quote, a comma or a semicolon, and percent-encoded inside another URL), keeping host, path, fragment and other parameters; spans keep their own query redaction (redacting-span-exporter.ts). Proven in redaction.spec.ts and through serializeLogRecord in log-record.spec.ts; mutations removing the masking or the exact policy name each fail a test
Proof	The six stage titles in environment-variables.schema.spec.ts and redaction.spec.ts, plus an https origin test, two assetsStorageSettings tests and the media-worker role in database-runtime-role-guard.service.spec.ts. Mutations that each fail a test: signature dropped from the list; the identity keys required for media-worker; the api role reading the media-worker group
Carried to A3a	createProcessLogger, startTelemetry and collectEnvironmentSecrets take EnvironmentVariables; the media-worker entry point needs them to accept MediaWorkerEnvironmentVariables (or the fields they read), and its secrets (ASSETS_S3_WORKER_SECRET_ACCESS_KEY, ASSETS_R2_SECRET_ACCESS_KEY) must join the known secrets; the API's ASSETS_S3_API_SECRET_ACCESS_KEY joins them in A2a-2, when it is first used

R1 as built (migration 0093_assets_processing_error_budget, baseline revision 103)

Piece	As built
Defect	Architect review of staging 29ba81bf, R1: record_processing_outcome (0088, 0089) re-queued retry_storage without a cap but incremented the same attempt_count that retry_processing compared with 5, so four storage retries followed by the first processing error dead-lettered a possibly valid image (asset and original failed, upload rejected, reservation released). The stage table wrote the shared counter too, so the design itself codified the interaction
Decision	Two budgets (Decided, the architect's recommendation accepted by the owner). attempt_count stays the total of every retry, for metrics and backoff; a separate processing_error_count counts processing errors only and alone drives the dead letter: five processing errors, consecutive or not, dead-letter. A storage retry never counts towards it and never resets it: a reset on a class change would let interleaved storage retries erase real processing failures
Column	assets.processing_jobs.processing_error_count integer NOT NULL DEFAULT 0 with processing_jobs_processing_errors_chk (>= 0), added by 0093 (expand only) and in the canonical table. Backfill (a conservative approximation): attempt_count for jobs whose error_class is processing, 0 for the rest. The true number of processing errors inside an old attempt_count is unknowable, because the job keeps only its latest error class. A job whose latest error was processing is backfilled to its whole total, so it never gets more processing attempts than the old rule allowed. A pending or leased job whose latest error was storage but whose earlier errors were processing is backfilled to 0, so those earlier processing errors are forgotten and it gets a fresh budget of five. The approximation is harmless: no worker has claimed a job in any environment yet (no Assets code exists), so every existing job has attempt_count = 0 and the backfill writes 0 everywhere
record_processing_outcome	CREATE OR REPLACE with the same owner, SECURITY DEFINER, search_path = pg_catalog, pg_temp and ninaku_worker grant; only the retry and dead-letter lines change. retry_storage: attempt_count + 1, processing count untouched, no cap. retry_processing: both counters + 1; dead_lettered (both counters + 1) when processing_error_count + 1 >= 5. ready and failed_permanent do not change; the archived-asset rule (the active slot is released only while the asset counts) does not change
Carried to A3c (ASSETS_STAGE_SPECS.md §14)	requeue_dead_letters does not exist yet; when A3c-1 writes it, a requeued dead letter resets both counters. A reclaimed expired lease, when A3c-1 counts it, counts as a processing error (both counters). The OB4 processing backoff step must follow processing errors, while the claim returns only the total
Proof	database/tests/contracts/assets-processing-contracts.ts (NINAKU_ASSETS_PROCESSING_OK), four new titles: keeps a job pending at its first processing error after four storage retries (pending, total 5, processing 1, asset still processing); never resets the processing error count on a storage retry; dead-letters at the fifth processing error when storage retries are interleaved (P S P S S P S P P: eight pending, then dead_lettered with total 9 and processing 5); dead-letters after five accumulated processing errors, failing the asset and releasing its reservation once. The A1c-1 title now seeds processing_error_count instead of attempt_count for its fourth and fifth error and for the archived dead letter. assets-tables-contracts.ts refuses a negative count with processing_jobs_processing_errors_chk. Observed RED on the column alone (old function): the first three new titles and the accumulated one fail (dead_lettered at the first processing error; processing count stays 0). Mutations that each fail a named title: a storage retry counted as a processing error; attempt_count compared with 5 again; the processing count reset on a storage retry; the dead letter not incrementing the processing count. 0093 applied by db:prepare on a revision 101 database holding pending, leased, dead_lettered and completed jobs of every error class leaves a schema (with owners and privileges) identical to a fresh revision 103 install; there, the migrated processing job with 3 attempts dead-letters at its fifth processing error and a migrated storage job with 4 attempts stays pending at its first processing error

A1b-3 as built (migration 0094_assets_archive_restore, baseline revision 104)

Piece	As built
Functions	assets.archive_asset(uuid) and assets.restore_asset(uuid), both RETURNS varchar, SECURITY DEFINER, search_path = pg_catalog, pg_temp, EXECUTE revoked from PUBLIC and granted to ninaku_runtime only (migration and runtime_grants.sql; the canonical file only revokes). Both call identity.assert_tenant_context(), refuse a transaction outside READ COMMITTED with assets_admission_isolation (0A000, the runtime functions' name) and take the organization only from identity.current_organization_id(). No permission check in SQL: the A4a route authorizes first
Lock order	The usage row FOR UPDATE (INTO STRICT) first, then the asset FOR UPDATE filtered by the context organization, the order of every writer of §7 (the "Carried to A1b-3" row of A1c-2). The asset lock is the row purge_asset_begin (A4b) will lock, so a restore never races a purge
archive_asset	not_found (unknown or foreign); a purging asset is refused with assets_status_transition (23514, the name of the status guard trigger, mapped to 422 · assets.transition_invalid); already_archived without writing; else sets archived_at = now() and decrements active_asset_count only when assets.counts_as_active_asset held before (a failed asset is not counted, so it is archived without a decrement); answers archived
restore_asset	not_found; purging refused with assets_status_transition; not_archived without writing; failed refused with assets_status_transition; archived more than 30 days ago (archived_at < now() - 30 days, the complement of the A4b purge rule) refused with assets_restoration_expired (mapped to 422 · assets.restoration_expired); then, only when assets.counts_as_active_asset(status, NULL) holds for the asset once restored (the mirror of the archive check), active_asset_count + 1 over platform.effective_limit(organization, 'assets.active_assets') is refused with assets_asset_limit (no row or unlimited is no ceiling, as reserve_upload) and the count is incremented; it clears archived_at and answers restored. Every refusal is 23514 with its named constraint, the rule of §5.2 of the stage specification
Rename	No function: AS5 is a plain UPDATE (display_name) under the tenant RLS policy, granted by A1a-1, and changes no counter; A4a builds it
Proof	database/tests/contracts/assets-archive-contracts.ts (NINAKU_ASSETS_ARCHIVE_OK, registered after the expiry script; a new script because the admission one is already 554 lines): the stage title archives and restores through the definer functions only, keeping the active asset count, and refuses restoring past 30 days or over the asset limit (pending, processing and failed assets; the count is compared with the counting predicate after every step; refused at 30 days and 1 minute, restored at 29 days and 23 hours; an archive then a restore of a processing asset leaves the count unchanged; a tenant at a limit of 1; at a count of 5,000 a restore is refused by the plan limit of 5,000 but admitted with an unlimited override and with no limit row for the organization), answers another organization's asset as not found and takes the organization only from the tenant context and the definer shape, grant and isolation title. assets-lifecycle-contracts.ts: refuses archiving or restoring a purging asset and never lets its status leave purging. database/tests/concurrency/assets-archive-concurrency.ts (NINAKU_ASSETS_ARCHIVE_CONCURRENCY_OK): an archive waiting on the usage row while the expiry sweep holds it and then locks the same asset finishes with no deadlock and uncounts the asset once; a restoration waiting while a reservation takes the last slot is refused with assets_asset_limit; an archive waiting on a reconciliation uncounts from the reconciled count. Mutations that each fail a test: the usage row lock removed (archive: deadlock with the sweep; restore: admitted over the limit), the asset locked before the usage row (deadlock), the organization read from the asset row instead of the context (both functions), the counting check skipped (a failed asset uncounted), the 30-day check skipped, the limit check skipped (also caught by the plan limit of 5,000), the purging check removed (both functions), EXECUTE granted to ninaku_worker or to PUBLIC in runtime_grants.sql. Removing the counting gate of the restore (on the increment, or on both the limit check and the increment) survives as an equivalent mutant: the restore reaches the gate only for pending, processing or ready (assets_status_chk allows five statuses and failed and purging are refused before it), and the predicate holds for all three; the gate keeps the restore the exact mirror of the archive if a status is ever added. The expiry race backdates its upload 50 years, so the sweep's oldest-first batch of 500 always includes it whatever other expired uploads exist (proven with 600 leftover expired uploads). 0094 applied by db:prepare on a revision 103 database holding assets in every status, archived or not, leaves a schema (with owners and privileges) identical to a fresh revision 104 install

A2a-1b as built (module skeleton, domain and public failures, no migration, no route)

Piece	As built
Module	src/modules/assets/assets.module.ts (AssetsModule), imported by AppModule; it imports DatabaseModule and the audit, identity and platform contract modules only (R1) and has no provider or controller yet, so docs/generated/openapi.json does not change. No contracts/ folder yet: no module consumes Assets until A5
Delivery token	domain/delivery-token.ts: generateDeliveryToken() encodes 16 bytes of node:crypto randomBytes with the shared encodeBase32Unpadded (foundation/otp/base32.ts) in lowercase, 26 characters; isDeliveryToken(value) accepts only ^[a-z2-7]{26}$, the shape of assets_delivery_token_chk and uploads_staging_key_chk. The staging (upload) token has the same shape and generator
Object keys	domain/object-key.ts: stagingKey → in/<token>, masterKey → m/<token>/original.webp, publicRenditionKey → a/<token>/p<profile>/<name>.webp, privateRenditionKey → p/<token>/p<profile>/<name>.webp; profile and name are typed fixed codes, and every builder refuses a value that is not a generated token with ObjectKeyTokenInvalidError, whose message never carries the refused value
Rendition profile	domain/rendition-profile.ts: RENDITION_PROFILE.ONE, RENDITION_NAME (thumbnail, tile, card, detail), variantCode(profile, name) (p1-tile), renditionName(code) (undefined for original or any unknown code), profileRenditionCodes(1) in the order of assets.profile_rendition_codes(1), and PROFILE_ONE_GEOMETRY (§5.5: 160 and 320 cover, 640 and 1,280 inside, quality 80, 80, 80, 82)
Status	domain/asset-status.ts: ASSET_STATUS and canTransition(from, to), the exact pairs of assets.guard_asset_status() (same status allowed, purging terminal), plus isArchivable (not purging) and isRestorable (not purging, not failed), the early refusals of archive_asset and restore_asset
Media type	domain/media-type.ts: ACCEPTED_IMAGE_MEDIA_TYPE (image/jpeg, image/png, image/webp, image/avif), isAcceptedImageMediaType (exact, case-sensitive) and MAX_UPLOAD_BYTES = 10_485_760
Failures	presentation/failures/assets-failures.ts (ASSETS_FAILURE): the module's public codes, as Catalog keeps its own (catalog-failures.ts; the Foundation error registry holds only Foundation codes): 403 · assets.action_forbidden, 404 · assets.not_found, 503 · assets.storage_unavailable (retryable) and, all 422, assets.asset_refused, asset_limit_reached, storage_limit_reached, too_many_open_uploads, access_class_unavailable, media_type_unsupported, file_too_large, upload_expired, upload_rejected, transition_invalid, restoration_expired, ai_generation_limit_reached. to-public-assets-failure.ts maps a check violation on assets_asset_limit, assets_storage_limit, assets_open_uploads_limit, assets_access_class_unavailable, assets_status_transition and assets_restoration_expired to its code, any other check, unique, foreign key or exclusion violation to assets.asset_refused (the §7 backstop), and leaves everything else (transient failures, 0A000 isolation refusals, non-database errors) to the shared filters; AssetsFailureInterceptor applies it, as CatalogFailureInterceptor does
Proof	The four stage titles in delivery-token.spec.ts, object-key.spec.ts, rendition-profile.spec.ts and to-public-assets-failure.spec.ts, plus the geometry title, asset-status.spec.ts, media-type.spec.ts and assets-failure.interceptor.spec.ts. Mutations that each fail a named title: 15 random bytes (the token and the key titles); the token check of the key builders removed, so a display name becomes a key (the key title); assets_restoration_expired dropped from the mapping (the failure title)
Carried to A2b	The constraint mapping sits in presentation/failures/, as this stage specifies; today every other module turns a constraint into an application error in infrastructure/ and maps only error classes in presentation/. When A2b adds the first repository, decide whether the constraint table moves to an infrastructure mapper with an AssetsRefusedError, as Catalog and Identity do

A2a-2 as built (storage adapters and the storage contract, no migration, no route)

Piece	As built
Dependencies	@aws-sdk/client-s3 and @aws-sdk/s3-presigned-post ^3.1135.0, the version of @aws-sdk/client-sesv2, so the shared @aws-sdk/core and @smithy/* packages stay one copy; npm audit --omit=dev --audit-level=high finds 0 vulnerabilities before and after
Ports	application/ports/upload-policy-signer.port.ts: signUploadPolicy({ key, mediaType, maxBytes, expiresInSeconds }) → { url, fields, expiresAt } and UPLOAD_POLICY_LIFETIME_SECONDS = 600. application/ports/object-store.port.ts: STORAGE_PROVIDER (s3-private, r2-public, the codes seeded in assets.storage_providers), head → { byteSize } | null, readAtMost → Buffer | null (a missing object is absent here too, so a key removed between HEAD and GET is not a storage failure), put and remove, and StoredObjectTooLargeError. The Nest injection tokens join with the first provider that binds them (A2b), so no unused export exists today
Factory	infrastructure/storage/object-storage.factory.ts: createS3StorageBucket (the API's signing client and the media worker's S3 client) and createObjectStorageBuckets (one client per provider code). Every client receives explicit credentials from its own settings, never the default chain (UC §13.1, R18). The R2 client uses https://<ASSETS_R2_ACCOUNT_ID>.r2.cloudflarestorage.com, region auto and requestChecksumCalculation and responseChecksumValidation WHEN_REQUIRED (S14). Each provider's settings carry endpoint (absent: the provider's own endpoint) and forcePathStyle (off for real S3 and R2), which is how a local S3-compatible server stands in for both. No SDK logger is configured, so the clients log nothing
Signer	infrastructure/storage/s3-upload-policy-signer.ts: createPresignedPost with Conditions: [['content-length-range', 1, maxBytes], ['eq', '$Content-Type', mediaType], ['eq', '$key', key]], Fields: { 'Content-Type': mediaType } and Expires from the request (the use case passes 600). Signing is local, with no network call. The SDK also adds its own exact {"key": key} and {"Content-Type": mediaType} conditions from the fields. Policy fields are never logged; if they ever reach a log, Policy, X-Amz-Signature and X-Amz-Credential are masked by the A2a-1a redaction
Object store	infrastructure/storage/s3-object-store.ts: HeadObject (ContentLength), GetObject streamed through a byte counter that stops at the first byte past the cap and throws StoredObjectTooLargeError (leaving the loop destroys the body stream), PutObject with ContentLength, ContentType and CacheControl, and DeleteObject. Only a missing key is absent (null, or done for remove). On GetObject and DeleteObject that is the NoSuchKey error code. A HeadObject answer has no body, so the SDK names every 404 NotFound, whether the key or the bucket is missing. MinIO tells the two apart only in its own x-minio-error-code header, which S3 does not send. So a NotFound HEAD is confirmed with one HeadBucket (the worker's §13.4 s3:ListBucket grant): the bucket answers, so the key is absent; otherwise the failure surfaces. Every other failure, including NoSuchBucket, AccessDenied, a bare 404 without those names, a body stream error and a HEAD without a content length, becomes ObjectStorageFailedError (port, original error as cause, a fixed message), the storage failure A2b maps to 503 · assets.storage_unavailable. StoredObjectTooLargeError stays as it is. No 403 mapping: the local server answered 404 for a missing in/ key, and staging has not been measured yet (open item below). Review fix after the first approval: the original rule treated any 404 as absent, so a missing or deleted bucket made readAtMost answer null and remove succeed
Contract script	tooling/assets/check-storage-contract.ts (npm run assets:storage-contract, not part of verify) with tooling/assets/storage-contract-environment.ts. It reads the ten storage variables of the API and media-worker groups (ASSETS_S3_REGION, ASSETS_S3_BUCKET, ASSETS_S3_API_ACCESS_KEY_ID, ASSETS_S3_API_SECRET_ACCESS_KEY, ASSETS_S3_WORKER_ACCESS_KEY_ID, ASSETS_S3_WORKER_SECRET_ACCESS_KEY, ASSETS_R2_ACCOUNT_ID, ASSETS_R2_PUBLIC_BUCKET, ASSETS_R2_ACCESS_KEY_ID, ASSETS_R2_SECRET_ACCESS_KEY), plus the optional ASSETS_STORAGE_CONTRACT_S3_ENDPOINT and ASSETS_STORAGE_CONTRACT_R2_ENDPOINT (a set endpoint also turns on path-style addressing). When a variable is missing it names the variable and never prints a value. It signs with the API key and reads, writes and deletes with the worker keys. It uses a declared size of 65,536 bytes, because the bound is the same mechanism at any size. It prints one PASS or FAIL line per expectation, with only the status and the S3 error code, never a URL, field, policy or body. It removes every object it may have created, even after a failure, and ends with NINAKU_ASSETS_STORAGE_CONTRACT_OK or exit code 1. An expired-policy step was added to the specified steps. Real-provider options (2026-10-10): ASSETS_STORAGE_CONTRACT_KEY_PREFIX is put in front of every key the script signs, writes, reads or deletes (<prefix>/in/..., <prefix>/m/..., <prefix>/a/...; a missing closing / is added, a leading / or a .. segment is refused), and the script refuses to start without it unless every endpoint is an override on localhost, 127.0.0.1 or [::1] (storage-contract-environment.ts). With none of the four R2 variables it runs S3 only (Plan B, §8 of the stage specs): one S3 client and bucket stand for both providers, the R2 round trip prints SKIPPED (no R2 credentials) and an a/ rendition round trip runs on the S3 bucket instead; with only some of them it names the missing ones. A missing-key answer (the missing-key HEAD and GET, and the HEAD after removal) that is a 403 prints LIMITED by IAM (no ListBucket) with what AWS answered, never PASS or FAIL; every other step keeps its strict expectation. It first deletes three never-written keys (in/, m/, a/) with the worker key and, when one is refused, stops before writing anything; it also stops after the first POST when that answers 403. After cleanup it prints one CLEANUP line per tracked key with the delete outcome and what a GET answers afterwards. A run with a skipped or limited step and no failure ends with NINAKU_ASSETS_STORAGE_CONTRACT_PARTIAL: <n> passed, 0 failed, <n> skipped, <n> limited and exit code 0 (storage-contract-report.ts, storage-contract-requests.ts). Proof: storage-contract-environment.spec.ts and storage-contract-report.spec.ts (11 titles, no network), observed RED before the helpers existed
Real S3 run (legacy bucket, 2026-10-10)	One run, owner-authorized, against the legacy production bucket of another product (ninaku-assets-prod, us-east-1) with the legacy IAM user ninaku-s3-assets for both the API and the worker keys, prefix ninaku-new-module-contract-test/run-20261010-4745922c/, no R2 credentials, before the cleanup preflight existed. That user is known not to be allowed ListAllMyBuckets, HeadBucket, ListObjectsV2 or IAM reads. Per expectation: POST exactly the declared size PASS 204 · POST one byte over PASS 400 EntityTooLarge · POST with another Content-Type PASS 403 AccessDenied · POST to another key PASS 403 AccessDenied · POST with an expired policy PASS 403 AccessDenied · HEAD of the uploaded staging object FAIL 403 (SDK error name Unknown) · GET capped one byte below FAIL 403 AccessDenied · HEAD of a missing staging key LIMITED 403 (Unknown) · GET of a missing key LIMITED 403 AccessDenied · HEAD in a bucket that does not exist PASS ObjectStorageFailedError · put, read and remove on s3-private FAIL: PutObject succeeded, the HEAD after it answered 403 · put, read and remove of an a/ rendition (Plan B) FAIL, same answers · both HEAD after removal LIMITED 403 · put, read and remove on r2-public SKIPPED (no R2 credentials) · summary 4 storage contract expectation(s) failed. Finding: this user may PutObject (presigned POST and SDK) under the prefix but not GetObject, HeadObject or DeleteObject, so the bound of the upload policy is proven on real S3 (the four refusals and the exact-size 204 are AWS's answers, matching MinIO), but reads, deletes and the missing-key 404 are not. Missing key: AWS answered 403, not 404, and an existing key answered the same 403, so with this user a 403 cannot tell absent from refused. Left behind (cleanup refused, DeleteObject 403 AccessDenied): three objects under the prefix, in/dh5bvxiqbngwg3mbmr7rbhr3le (65,536 bytes), m/dr7ysjrn7bneelon5owyrnj5xq/original.webp (4,096 bytes) and a/iddsclraqzjru4tt27efkgwspu/p1/tile.webp (4,096 bytes); the other two tracked in/ keys were refused by S3 and never written. A GET of each afterwards answered 403 AccessDenied, which proves nothing about deletion. The cleanup preflight was added after this run so the script now stops before writing when the worker key cannot delete
Adapter consequence (open, owner)	Measured with the legacy user, production code unchanged. HeadObject refused answers a bodiless 403, which the SDK names Unknown: not NoSuchKey and not NotFound, so headOutput never reaches its HeadBucket confirmation and throws ObjectStorageFailedError (cause status 403); readAtMost does the same on AccessDenied, and remove cannot clear anything. In the worker, verifyAndMaster then fails every job with ObjectStorageFailedError, which failure-classifier.ts classifies as RETRY_PROCESSING · STORAGE_REFUSED (a 403 is not transient) with the processing backoff, never as StagingObjectMissingError. That is safe (it fails closed: nothing is treated as absent, no upload is expired as missing, no object is deleted by mistake) but not functional: no asset would ever be processed and purge and the expiry sweep could delete nothing. A user with s3:GetObject but without s3:ListBucket would process uploads that arrived, while an upload that never arrived would be retried as STORAGE_REFUSED instead of waiting for its expiry as upload_missing. Mapping 403 to null would be unsafe: this run shows an existing object answering the same 403. Decision for the owner: keep the adapter as is and grant the worker s3:ListBucket on the new bucket (runbook §4.4), so a missing key answers 404 and HeadBucket confirms it
Local run (2026-10-08)	MinIO on 127.0.0.1:9100, two fresh buckets (ninaku-test-private-<random> for S3, ninaku-test-public-<random> standing in for R2), both endpoints overridden, one MinIO user for the three principals; the buckets were empty after the run and were deleted. Transcript: PASS POST exactly the declared size: 204 · PASS POST one byte over the declared size: 400 EntityTooLarge · PASS POST with another Content-Type: 403 AccessDenied · PASS POST to another key with the same policy: 403 AccessDenied · PASS HEAD of the uploaded staging object with the worker key: 65536 bytes · PASS GET of the staging object capped one byte below its size: StoredObjectTooLargeError · PASS POST with an expired policy: 403 AccessDenied · PASS HEAD of a missing staging key with the worker key: absent (404) · PASS GET of a missing key: absent · PASS HEAD in a bucket that does not exist: ObjectStorageFailedError · PASS put, read and remove on s3-private: head 4096, read true, after removal null · PASS put, read and remove on r2-public: head 4096, read true, after removal null · NINAKU_ASSETS_STORAGE_CONTRACT_OK
Proof	The four stage titles in object-storage.factory.spec.ts, s3-upload-policy-signer.spec.ts and s3-object-store.spec.ts. Three more titles: the endpoint override with path-style addressing, the stored size and any other refusal rethrown, and put and remove going to the named provider's bucket. Observed RED: all three spec files failed while the adapters did not exist. Mutations: removing content-length-range fails the signer title, and the contract fails POST one byte over (204) and the staging HEAD (65,537 bytes). starts-with for the key fails the signer title, but the contract still passes, because the SDK's own exact {"key": key} condition still binds the key at the storage. Without credentials in the factory, the credential title fails: every client resolves the stubbed SES AWS_ACCESS_KEY_ID. A cap of maxBytes + 1 fails the read title. Review fix: surfaces a missing bucket and an unreadable bucket as storage failures and only treats a missing key as absent was RED against the any-404 rule. Treating NoSuchBucket as absent fails it, and so does dropping the HeadBucket confirmation
Open items (only real S3 and R2 can prove them)	(1) The HEAD of a missing in/ key with the staging worker key: 404 (the §13.4 s3:ListBucket grant) or 403. The adapter maps 403 to null only if staging answers 403. Partly answered on 2026-10-10 (row "Real S3 run"): without s3:ListBucket AWS answers 403, and an existing key answers the same 403 when GetObject is missing, so no 403 mapping; the 404 with the grant is still to be seen on the new bucket. Also open: the three objects left under ninaku-new-module-contract-test/run-20261010-4745922c/ in the legacy bucket, to be deleted by a principal that may (the owner), and the legacy credentials, to be rotated. (2) R2 accepts the client as configured: account endpoint, region auto, checksums only when required (S14). MinIO proves only the S3 API shape. (3) The IAM prefix policies of §13.4: the API key can sign but not read, the worker key can read and delete in/. MinIO ran with one user. The worker S3 key and the R2 token must also be allowed HeadBucket (s3:ListBucket), or a missing key surfaces as a storage failure. (4) The real S3 error codes and statuses for the refused POSTs. The local server matches the documented ones. Command for the owner, with the staging values in an untracked file outside the repository: set -a; . /path/to/assets-staging.env; set +a; npm run assets:storage-contract. The file sets the ten variables above and no ASSETS_STORAGE_CONTRACT_*_ENDPOINT, so the real S3 and R2 endpoints are used
Carried to A2b	ASSETS_S3_API_SECRET_ACCESS_KEY joins collectEnvironmentSecrets (src/foundation/logging/redaction/environment-secrets.ts) when A2b wires the signer into the API process. The worker secrets join in A3a. A2b also maps a storage failure of the signer or the store to 503 · assets.storage_unavailable

A2b as built (request an upload and read an asset, no migration)

Piece	As built
Routes	POST /api/v1/assets/uploads (UploadsController) and GET /api/v1/assets/{assetId} (AssetsLibraryController), both under AssetsController (session and tenant guards, AssetsFailureInterceptor, OpenAPI tag Assets). The intent is @Throttle 30 a minute (UPLOAD_INTENT_RATE_LIMIT in presentation/controllers/asset-route-documentation.ts, because foundation/http/rate-limiting was outside the stage), answers Cache-Control: no-store through HttpIdempotentResponse (Idempotent-Replayed: true on a replay). The read answers a strong tag of the body (computeContentEntityTag) with private, no-cache and 304 on a match
Request	Strict Zod (presentation/dtos/upload-request.schemas.ts): mediaType a type/subtype of at most 255 characters, byteSize a positive safe integer, accessClass one of the three classes, optional trimmed displayName and originalFilename of at most 255 (ASSET_TEXT_MAX_LENGTH, domain/access-class.ts). The domain refusals (acceptedMediaTypeOf, application/uploads/upload-intent.ts) answer 422 before any transaction, then the configuration check answers 503 · assets.storage_unavailable before authorizing
Use case	RequestUploadUseCase: in one tenant transaction AssetsAccess.admitUpload (OperationAuthorizationContract, assets.media.manage and assets.media, a refusal audited as denied on organization.organization and returned so the audit commits, as Catalog does), then reserve_upload through resolveIdempotentClaim (so a lock timeout answers 409 · idempotency.in_progress), then on created the assets.asset.upload_requested audit with the after attributes assets.asset.media_type, assets.asset.byte_size and assets.asset.access_class (the dotted attribute naming of the other modules). On existing it reads the asset (the replay's eighth statement) and compares the stored request hash (requestFingerprint of the five fields, absent names as null): another hash is 409 · idempotency.key_reused. After the commit it signs a policy of min(600 s, time left on the upload) seconds, or answers upload: null when the upload is no longer issued or has less than one second left
Created answer	reserve_upload does not return created_at, so the reserve statement also selects now(): the transaction timestamp, which is exactly the created_at default of the asset row. The other fields of the created asset are known (pending, image, upload), so the created path stays at 8 statements
Read	ReadAssetUseCase: PermissionCheckContract with assets.media.view organization-wide (a refusal is 403 · assets.action_forbidden, not audited, like Catalog's reads), then one statement reading the asset LEFT JOIN its original variant (width, height, byte size). AssetViews builds the four a/<token>/p1/<name>.webp addresses under ASSETS_PUBLIC_BASE_URL only for a ready, public, profile 1 asset; without the storage group there are no addresses. aiGenerated is sourceKind = ai_generated
Wiring	ASSETS_STORAGE_PORT (application/ports/assets-storage.port.ts) holds { configured: { signer, publicBaseUrl } | undefined }, built by ASSETS_STORAGE_PROVIDER from AppConfigService.assetsStorageSettings() with createS3StorageBucket (explicit API credentials, real endpoint). ASSET_REPOSITORY_PORT is AssetRepository (infrastructure/assets/). The API binds no object store: it never reads, writes or deletes objects (AS2, §13.4: the API key can only sign). ASSETS_S3_API_SECRET_ACCESS_KEY joined collectEnvironmentSecrets and KnownSecretsRegistryService
Failures	The application errors (application/assets-errors.ts) map in to-public-assets-failure.ts; an OperationRefusedError other than the capability one is the plain denial. A storage failure (AssetsStorageUnconfiguredError, ObjectStorageFailedError, which the signer now raises for any signing failure) becomes a ServiceUnavailableException carrying the code assets.storage_unavailable (decision accepted by the owner's coordinator). Foundation masks every PublicFailure of status 5xx: buildPublicFailureProblem answers foundation.internal_error for it, because a server-side failure is not meant to be actionable, so the ASSETS_FAILURE.STORAGE_UNAVAILABLE entry alone would never reach the client. The HttpException route is the one Foundation already opens for a module code: buildHttpExceptionProblem takes the code of the exception payload over the registry entry of its status (service.unavailable), while still hiding any 5xx detail. The answer is 503, code assets.storage_unavailable, retryable, with the registry's title and default detail, and the cause stays out of the answer. Publishing retryable 5xx public failures in Foundation would be the alternative, a change outside Assets. The constraint table stays in presentation/failures/ (the A2a-1b open point): reserve_upload raises named check violations and no repository needs its own refusal class
Proof	test/e2e/assets-uploads.e2e-spec.ts, assets-access.e2e-spec.ts and assets-library.e2e-spec.ts with the stage titles, one more e2e title for the 429 and the unit specs of the use case, the view, the signer failure, the storage provider and the failure mapping; statement-budget.e2e-spec.ts rows: 8 for an intent and for its replay, 7 for a read. The e2e use the real signer with fixed credentials (no network) through an override of ASSETS_STORAGE_PORT; a ready or failed asset is written in SQL with session_replication_role = replica, since the worker that produces it is A3. Mutations that each fail a named title: the hash comparison skipped (the replay title and the reuse unit title), addresses for a pending asset (the pending/processing/failed title and the view unit titles), the @Throttle removed (the 429 title)
OpenAPI	Three operations added under the Assets tag (tooling/openapi/openapi-document.ts); npm run openapi:compat against origin/staging: no breaking change, three path_added
Route classification	tooling/performance/http/route-classification-assets.ts classifies the three operations as admin, unmeasured (administrative media management, D24), registered in route-classification.ts; the typed table counts 157 operations (14 hot, 40 frequent, 101 admin, 2 not measurable, 41 measured), noted in PERFORMANCE_BASELINE.md §11.1

A2c as built (complete an upload, no migration)

Piece	As built
Route	POST /api/v1/assets/uploads/{uploadId}/completion, no body, 202 with the AS3 body and Cache-Control: private, no-store
Use case	CompleteUploadUseCase: PermissionCheckContract with assets.media.manage organization-wide (never the plan), complete_upload, then the asset read through AssetViews; not_found is 404 · assets.not_found (an upload of another organization answers the same), expired is 422 · assets.upload_expired, rejected is 422 · assets.upload_rejected, completed and already_received answer the asset. No audit and no storage call: the specification and UC AS2 keep every external call out of the request, so the HEAD of the staging object stays with the media worker (A3)
Proof	The three e2e titles of the stage, complete-upload.use-case.spec.ts › never calls the object storage while completing an upload (the use case is built by Nest with an object store spy bound to OBJECT_STORE_PORT, so a use case that injects and calls it fails), and the statement row: 8. Mutations that each fail a named title: a head call in the use case (the storage title) and an expired upload treated as completed (the expired/rejected title)

A3a as built (the media-worker process, no migration)

Piece	As built
Process	src/media-worker.ts validates the environment with the media-worker process role, starts the process logger and telemetry like src/worker.ts and boots createMediaWorkerApplication() (src/bootstrap/create-media-worker-application.ts), a Nest application context with no HTTP server, so no route and no health endpoint, exactly like the OTP worker. Graceful shutdown is the shared registerGracefulShutdown. Scripts start:media-worker and start:media-worker:prod (node dist/media-worker); knip.json and check-main-imports.ts list the entry with its root module
Modules	src/worker/media-worker.module.ts (MediaWorkerModule): MediaWorkerConfigModule, WorkerDatabaseModule, LoggingModule, ObservabilityModule, ScheduleModule.forRoot(), AssetsWorkerModule, and no messaging or Identity module. src/foundation/config/media-worker-config.module.ts validates with the media-worker role and provides AppConfigService and MediaWorkerSettingsService (storage(), the media-worker storage group or undefined, and processing). src/modules/assets/assets-worker.module.ts (AssetsWorkerModule) holds the processing providers only; AssetsModule is unchanged
Environment	ASSETS_IDLE_POLL_MS (default 2,000, 500–60,000) and ASSETS_IMAGE_LEASE_SECONDS (default 120, 30–900), read by the media-worker role only. The worker's two storage secrets join the known secrets: collectEnvironmentSecrets accepts either role's environment, and KnownSecretsRegistryService reads MediaWorkerSettingsService when it is present
Storage	Without the media-worker storage group the process boots and stays up (the OTP worker's rule for an unconfigured channel: warn and keep running, not crash-loop), logs assets.media_worker.storage_unconfigured once, and starts neither the claim loop nor the expiry sweep (MEDIA_WORKER_STORAGE_CONFIGURED), so no job is claimed and no upload is expired without a way to delete its staging object; only the nightly usage reconciliation, which needs no storage, runs. With the group, createMediaWorkerObjectStore builds the A2a-2 store from it
Repository	infrastructure/processing/processing-jobs.repository.ts calls the four A1c functions through DatabasePoolService: the claim and the record are one autocommit statement each, so no transaction is open while a handler runs. A record refused with assets_job_lease_lost answers lease_lost. expire_uploads and reconcile_usage_batch run in a short READ COMMITTED transaction that first takes pg_try_advisory_xact_lock(hashtextextended('assets.expire_uploads', 0)); the two use the same key, so the sweep and the reconciliation never overlap (A1c-2 lock-order requirement), and a busy lock answers "not acquired" without waiting
Image loop	application/processing/image-job-loop.ts claims one job with a fresh lease token, only of the image kinds that have a registered handler (process_upload since A3b-2), runs the handler outside any transaction, records its outcome with the same token and then calls the handler's afterRecord with the recorded result. A thrown failure is classified (processing-failure.ts): a permanent refusal → failed_permanent with its code; a storage failure → retry_storage (assets.storage_unavailable); anything else → retry_processing (assets.processing_error). Retries get available_at from processing-retry-delay.ts: storage 5 s doubling to 15 min, processing 5 s, 30 s, 2 min, 10 min indexed by the claimed total attempt_count (A3c re-indexes it by processing errors). infrastructure/worker/image-job-loop.runner.ts polls again at once after a job and every ASSETS_IDLE_POLL_MS when idle; on shutdown it stops claiming and waits, at most one lease, for the job in flight to record before the pool closes
Sweeps	ExpireUploadsJob (every 5 minutes): expire_uploads(500) under the lock, then each returned staging object is removed with up to three attempts (a missing object is done); objects still undeleted are counted and left to the in/ lifecycle rule. A failing batch is reported, the usage counters are reconciled and the batch is tried once more; a second failure logs assets.expire_uploads.repeated_failure (error). ReconcileUsageJob runs daily at 03:00 UTC, 500 organizations a batch, and retries a minute later while the sweep holds the lock
Sweep guards (review)	ExpireAbandonedUploadsUseCase deletes each returned staging object with up to three attempts, pausing 200 ms and 400 ms; an unknown staging provider is counted undeleted without a storage call. Orphan: the expiry commits first, so when every delete fails (or the worker stops between the commit and the delete) the staging object stays and nothing returns its key again; the in/ lifecycle rule of the runbook (§3.4, one day) is the backstop. ReconcileOrganizationUsageUseCase stops with lock_busy (retried a minute later), stalled when a batch's last organization does not move past the previous one (compared as lower-case uuid text, which orders like PostgreSQL's uuid byte order used by reconcile_usage_batch's organization_id > p_after), or batch_cap_reached after 10,000 batches; the job logs the last two as assets.reconcile_usage.incomplete (error). The loop runner re-checks the stop after every iteration and waits idle with abortableSleep on one AbortController signal, which removes its listener when the timer fires, so a shutdown during an iteration that found no job or failed returns at once and 10,000 idle waits leave no listener behind. The storage state reaches the runner and the expiry job as a typed MediaWorkerStorageState object (MEDIA_WORKER_STORAGE_STATE), and every dependency, the logger included, is injected by an explicit token
Placement	The stage table's paths moved to this branch's edit surface with the same content: src/media-worker/media-worker.module.ts is src/worker/media-worker.module.ts, assets-processing.module.ts is assets-worker.module.ts, and the two jobs live in infrastructure/worker/ (not presentation/jobs/) with their logic in application/processing/ use cases
Telemetry	startTelemetry now takes ProcessEnvironmentVariables (the "Carried to A2a-1a" row), so the media worker starts traces and metrics like the other processes. A boot of node dist/media-worker against a local database passed the role guard, claimed and recorded jobs and exited 0 on SIGTERM
Not built (needs SQL)	Isolating a poison upload "by id for the next run" (A1c-2 requirement) needs expire_uploads to skip ids or catch per row; A3a only reconciles, retries once and alerts
Proof	image-job-loop.spec.ts (the two stage titles, plus "claims nothing while no handler is registered" and the failure classes), expire-uploads.job.spec.ts (the stage title, deletes the staging object of an expired upload and ignores a missing one, and the reconcile-and-retry title), reconcile-usage.job.spec.ts, image-job-loop.runner.spec.ts, processing-jobs.repository.integration-spec.ts (claims, records and expires through the worker role only; never runs the expiry sweep and the reconciliation at the same time), create-media-worker-application.spec.ts (both stage titles), media-worker-processing-variables.spec.ts, media-worker-settings.service.spec.ts. Mutations that each fail a named title: recording before the handler runs, claiming every image kind instead of the registered ones, dropping the advisory lock
Review proof	expire-abandoned-uploads.use-case.spec.ts (three attempts on fake timers, the orphan, the unknown provider, the lock not acquired), reconcile-organization-usage.use-case.spec.ts (multi-batch walk, lock lost mid-run, a non-advancing cursor, the batch cap), new titles in image-job-loop.runner.spec.ts (stop during an idle or failed iteration, no loop without storage), expire-uploads.job.spec.ts (no sweep without storage), reconcile-usage.job.spec.ts (incomplete runs logged), and assets-worker.module.spec.ts, which compiles the real AssetsWorkerModule graph (only the pool, configuration and logger replaced) and the MediaWorkerModule root with its real configuration, logging and observability modules. Mutations that each fail a named title: the stop signal removed from the idle wait, the storage gate removed, the cursor guard removed, ProcessUploadHandler dropped from the providers

A3b-1 as built (verification and the master, no migration)

Piece	As built
Dependency	sharp ^0.35.5 (libvips 8.18); npm audit --omit=dev --audit-level=high finds 0 vulnerabilities
Domain	domain/media-signature.ts (mediaTypeBySignature: JPEG FF D8 FF, PNG's eight bytes, RIFF…WEBP, and an ftyp box at offset 4 whose major or compatible brand is avif or avis, read only inside the declared box size); domain/image-limits.ts (pixels per accepted media type: 40,000,000 for JPEG, PNG and WebP and 12,000,000 for AVIF, through maxInputPixelsOf; 12,000 and 64 px sides, master 4,096 px at WebP q90)
Codec	application/ports/image-codec.port.ts and infrastructure/processing/sharp-image-codec.ts: sharp.concurrency(1), sharp.cache(false); probe reads the header only (metadata(), failOn: 'warning', no pixel limit so an oversized image is reported as too large, not as corrupt) and maps heif with av1 compression to AVIF; encodeMaster reads the header again and decodes with limitInputPixels set to the limit of the format the decoder detected (12,000,000 for AVIF, 40,000,000 otherwise; a format it does not accept is ImageDecodeFailedError), failOn: 'warning', autoOrient: true, animated: false, unlimited: false, fits inside 4,096 without enlargement and encodes WebP q90 with alpha kept and no metadata (sRGB). A failure of probe or encodeMaster is ImageDecodeFailedError (permanent, assets.image_corrupt) when its message names a limit or the image, and ImageProcessingFailedError (retried as assets.processing_error) when it is a resource exhaustion (out of memory, thread creation, a non-Error rejection: isResourceFailure); every failure of encodeRendition is ImageProcessingFailedError, because the master is the service's own output (inputFailure and processingFailure in sharp-image-codec.ts). Since the job deadline hardening, a pipeline stopped by its timeout is ImageCodecTimeoutError in both
Failure classes (review)	encodeMaster and probe turn a sharp failure on the upload into ImageDecodeFailedError (permanent, assets.image_corrupt: truncated, corrupt header, unsupported format, pixel limit) unless its message names a resource exhaustion of the process (vips_malloc, std::bad_alloc, out of memory, Cannot allocate memory, ENOMEM, a thread that could not be created, or a non-Error rejection), which becomes ImageProcessingFailedError. A message that names a pixel, size, dimension or security limit stays permanent even when it also mentions memory, because a hostile HEIF or AVIF can make the decoder report its own allocation limit; encodeRendition works on the worker's own validated master, so every failure there is ImageProcessingFailedError. That error is retry_processing (assets.processing_error), counts against the five processing errors and never deletes the staging object. The message list is the best available signal: libvips reports no error codes to Node
Verification	application/processing/verify-and-master.ts: HEAD (missing → StagingObjectMissingError), stored size against the declared size (assets.size_mismatch), readAtMost capped at the declared size (a HEAD size that differs from the declaration is permanent assets.size_mismatch; once the HEAD agreed, a read that comes back shorter, or one byte past the cap as StoredObjectTooLargeError, is an inconsistent storage read and is retried as a storage error, keeping the staging object), magic bytes, declared type and decoded format must agree (assets.content_mismatch), dimensions (assets.image_too_large, assets.image_too_small), one decode into the master (assets.image_corrupt on a decoder error). A missing staging object is retry_storage (assets.upload_missing) while the upload's expires_at (returned by the claim since 0096) is in the future and failed_permanent after it, the rule of AS7
Proof	media-signature.spec.ts, image-limits.spec.ts, verify-and-master.spec.ts and image-pipeline.integration-spec.ts (the three stage titles, plus the four accepted formats, the size checks and the missing object). The polyglot (PNG signature over a JPEG body) and a truncated JPEG are assets.image_corrupt; an 8,000 × 5,001 PNG of 0.1 MB is assets.image_too_large before any decode. Mutations that each fail a named title: the signature comparison removed, the decoder comparison removed, keepMetadata() on the master, the pixel cap raised to 48 MP, the read cap raised past the declared size, autoOrient off
Pixel cap per format (owner decision, after the local memory measurement)	AVIF is capped at 12 MP, JPEG, PNG and WebP stay at 40 MP, in the dimension check (dimensionRefusal(detected, width, height), failure assets.image_too_large, permanent, staging object deleted) and in the decode (limitInputPixels of the detected format). The declared type cannot lower the cap: the magic bytes, the declared type and the decoder's format must already agree (assets.content_mismatch otherwise), and the codec reads the format from the bytes itself. Proof: image-limits.spec.ts (refuses an avif over 12 megapixels as too large and accepts one at exactly 12 megapixels, caps every accepted media type, avif at 12 megapixels and the others at 40), verify-and-master.spec.ts (refuses an avif declared as png or jpeg as a content mismatch before the decoder or the pixel limit sees it) and image-pipeline.integration-spec.ts (refuses an avif over 12 megapixels as too large, accepts one at exactly 12 megapixels and still accepts a 20 megapixel jpeg and png, caps the decode at the pixel limit of the format the decoder detects, whatever the caller declared, with 4,000 × 3,001 and 4,000 × 3,000 AVIFs of under 1 KB generated in the test). Mutations that each fail a named title: AVIF back to 40 MP, the decode cap taken from a type other than the detected one, >= instead of > at the limit, the decode cap one pixel lower. The front end also resizes before uploading; the server limits do not depend on it
Memory (local, not the A3c gate)	macOS arm64, one process: a 40 MP noisy JPEG of 4.3 MB through probe, master and four renditions peaked at 452 MB RSS (353 MB before, which includes generating the fixture), 1.2 s; a 40 MP RGBA PNG peaked at 315 MB (110 MB before), 0.6 s. Railway's Linux memory and the 12 MP, 40 MP and AVIF matrix are A3c's perf:assets

A3b-2 as built (migration 0096_assets_claim_original_variant, baseline revision 106)

Piece	As built
Migration	ready must name the asset's existing original variant id and the worker reads no table, so 0096 drops and recreates assets.claim_processing_job with two more result columns: original_variant_id (the claimed asset's own original, joined by asset and organization) and upload_expires_at (which replaced A3b-1's attempt-count bound for a missing object). Same body, owner, SECURITY DEFINER, search_path; EXECUTE from PUBLIC revoked and granted to ninaku_worker only; canonical 0070_assets.sql holds the end state. It follows Catalog's 0095 (revision 105)
Renditions	application/processing/derive-renditions.ts derives thumbnail and tile (cover, attention) and card and detail (inside, never enlarged) from the in-memory master, each WebP at its profile quality with its SHA-256
Handler	application/processing/process-upload.handler.ts, registered for process_upload in AssetsWorkerModule with SharpImageCodec as IMAGE_CODEC_PORT: verify and master (A3b-1), derive the renditions, put the master to s3-private m/<token>/original.webp (image/webp, private, no-store) and each rendition to r2-public a/<token>/p1/<name>.webp (image/webp, public, max-age=31536000, immutable), and only then answer ready with every variant: the original under its existing id, each rendition and every storage object under a new UUIDv7. A failed put is a storage retry and no ready is recorded. afterRecord removes the staging object only when a ready or failed_permanent outcome was recorded completed; retries, a dead letter and a lost lease keep it (the in/ lifecycle is the net). A non-public asset is refused as a processing error (the API admits only public today)
Preconditions (review)	Deterministic refusals are typed permanent failures, recorded failed_permanent at once instead of retried to a dead letter: a claim without the original variant (assets.original_variant_missing), a non-public access class (assets.access_class_unavailable), a job without its upload (assets.upload_unavailable) and an unknown staging provider (assets.storage_provider_unknown). A staging delete that fails after a recorded outcome is logged as assets.processing.staging_delete_failed (warn, job and upload ids) and left to the lifecycle rule
Proof	processing-jobs.repository.integration-spec.ts (the claim now returns the original variant id and the upload expiry), process-upload.handler.spec.ts (keys, content types and cache-control per bucket, the public bucket receiving only renditions, variant facts against the stored bytes, a failed master or rendition put, the staging delete per outcome and result), and test/integration/assets-processing.integration-spec.ts, which runs only when ASSETS_MEDIA_WORKER_E2E_ENDPOINT, …_ACCESS_KEY_ID and …_SECRET_ACCESS_KEY name an S3-compatible server (CI skips it): against MinIO and a fresh database it processes a rotated JPEG with GPS EXIF into a ready asset (upload verified, job completed, five ready variants with available primary objects, reserved bytes released, stored bytes increased by the sum of the variants, the active count unchanged), HEADs every object for its content type, length and cache-control, re-hashes each against its recorded checksum, finds no EXIF or XMP and the staging object gone; fails five bad uploads with each reservation released once and each staging object removed; retries a not-yet-arrived object as a storage error; expires an abandoned upload and deletes its staging object; it creates and deletes its own two buckets. database/tests/contracts/assets-processing-contracts.ts: the claim title's column list and returns the claimed asset's own original variant and upload expiry, never another tenant's. Mutations that each fail a named title: a rendition written without immutable; the rendition puts not awaited before answering ready; the staging delete skipped; the claim joining an original variant of another organization
Upgrade	A revision 105 database built from staging 61cd4d21 (with Catalog's 0095) and seeded with an organization, seven assets and their original variants, and jobs and uploads in every state (a ready asset with a verified upload and a completed job, a failed_permanent one, a dead_lettered one after five processing errors, a leased job, a pending job, an issued upload and an expired one) was upgraded by db:prepare from the merged tree: the ledger gained only baseline-r106 and 0096_assets_claim_original_variant. Under ninaku_worker the claim then returned the pending job with its own original variant id (uuid) and its upload's expires_at (timestamp with time zone), and pg_dump --schema-only of the upgraded database, owners and privileges included, is identical to a fresh install of the merged tree at revision 106
Deploy order and review proof	The migrator applies 0096 before the release's worker image starts; the old worker reads the claim's first 13 columns by name and ignores the two new ones, and the new repository selects and maps all 15 by name (c.original_variant_id, c.upload_expires_at, never by position). The join on lower(variant_code) = 'original' cannot see two originals: asset_variants_code_chk allows lower-case codes only and asset_variants_asset_code_ci_uq is unique on (asset_id, lower(variant_code)); the processing contract proves both refusals and that the worker receives uuid and timestamp with time zone (pg_typeof) for the two columns

A3c-1 as built (migration 0097_assets_requeue_dead_letters, baseline revision 107)

Piece	As built
Migration	0097, after Catalog's 0095 (revision 105) and A3b-2's 0096 (revision 106), drops and recreates assets.claim_processing_job with two more result columns at the end, processing_error_count integer and claim_state varchar, and creates assets.requeue_dead_letters(uuid[]) RETURNS integer. Same owner, SECURITY DEFINER, search_path = pg_catalog, pg_temp; the claim keeps EXECUTE for ninaku_worker only; the requeue has EXECUTE revoked from PUBLIC and granted to no role (runtime_grants.sql does not change). Canonical 0070_assets.sql holds the end state
Poison jobs (requirement 1)	The claim of an expired lease counts as a processing error: attempt_count + 1, processing_error_count + 1, error_class 'processing', last_error_code 'assets.lease_expired', and the job is leased to the new claimant (claim_state 'leased'). When processing_error_count + 1 >= 5 the claim dead-letters it instead, exactly as the fifth retry_processing does: under the usage, asset, upload and original-variant locks (the lock order of §7), the asset, its original variant and its upload fail with assets.processing_exhausted, the reservation and the active slot (only while the asset counts) are released, and the row comes back with claim_state 'dead_lettered' and no lease. A live lease is never reclaimed or counted. A job whose worker dies every time (out of memory on a huge image) is dead-lettered at its fifth expiry instead of being reclaimed forever. Other job kinds are counted the same way and only the job is dead-lettered (no such job is enqueued yet)
Stranded jobs (requirement 2)	At claim time, a process_upload job, pending or with an expired lease, whose asset is no longer processing or whose upload is no longer received is completed (completed_at, last_error_code 'assets.job_abandoned', lease cleared) without touching the asset, its upload or the usage row, and comes back with claim_state 'completed'. This is the terminal path of a job whose outcome was refused with assets_outcome_state: it stays leased until its lease expires and the next claim completes it
Requeue (OD21)	RETURNS TABLE (requeued, skipped_over_limit, skipped_ineligible). For 1 to 500 ids (else 23514 assets_requeue_batch), in READ COMMITTED (else assets_processing_isolation), it first takes the expiry sweep's advisory lock (pg_advisory_xact_lock(hashtextextended('assets.expire_uploads', 0)), waiting, so it never overlaps the expiry sweep or the reconciliation, which lock usage rows in other orders) and locks every named organization's usage row up front in organization_id order; then it locks each dead_lettered process_upload job in id order, and its asset, upload and original variant. A job is requeued only while its asset is failed with assets.processing_exhausted and not archived, its upload is rejected and was created less than a day ago. That is the inbox lifetime of OD21 and §14: the staging object cannot be older than its upload row, and the in/ lifecycle counts its day from the object's creation. uploads.expires_at cannot be the window: it is the POST policy deadline, 600 s after the reservation (UPLOAD_POLICY_LIFETIME_SECONDS), and a processing dead letter needs at least 5 s + 30 s + 2 min + 10 min of backoff after its first claim, so every processing dead letter has an expired upload. The object can still be gone (a lifecycle run, a manual delete): the requeued job then finds no staging object after the upload's expiry and fails for good with assets.upload_missing (AS7's rule), releasing its reservation again. Each candidate re-checks the organization's limits as reserve_upload does (platform.effective_limit; no row or unlimited means no ceiling): active_asset_count + 1 against assets.active_assets (only while the restored asset counts, assets.counts_as_active_asset) and stored_bytes + reserved_bytes + declared against assets.stored_megabytes; an organization over a limit leaves that job dead-lettered and counts it in skipped_over_limit, and the rest of the batch goes on. A requeued job: asset and original variant failed → processing (failure fields cleared), upload rejected → received (rejection_code and settled_at cleared), reserved_bytes plus the declared size, active_asset_count + 1 under the same predicate as the release, and the job pending with available_at = now(), attempt_count = 0 and processing_error_count = 0 (R1 requirement 1), error_class and last_error_code cleared. Every other distinct id (older, archived, unknown, completed, already requeued) counts in skipped_ineligible
Proof	database/tests/contracts/assets-dead-letter-contracts.ts (NINAKU_ASSETS_DEAD_LETTERS_OK): counts a reclaimed expired lease as a processing attempt and dead-letters the job at the fifth (leased at reclaims 1 to 4, dead-lettered at the fifth); completes or dead-letters a job whose asset no longer waits for an outcome instead of reclaiming it forever; completes a stranded job whose fifth lease expired instead of dead-lettering it, leaving its asset and usage untouched (abandon wins over exhaustion). Every row returned dead_lettered or completed is checked to have lease_owner, lease_token and lease_expires_at cleared (also enforced by processing_jobs_lease_shape_chk), and image-job-loop.spec.ts proves the loop runs no handler and records nothing for them. database/tests/contracts/assets-requeue-contracts.ts (NINAKU_ASSETS_REQUEUE_OK): resets both the attempt count and the processing error count of a requeued dead letter; requeues a dead-lettered processing job of the last day only through the operator function, restoring its reservation (function shape, permission denied for the worker and the runtime, batch bounds, isolation, an upload created 25 hours ago and an archived asset skipped, a repeated id counted once); skips the dead letter of an organization at its asset or storage limit and requeues the rest of the batch (1,2,0); restores the usage counters exactly after a dead letter and its requeue (one dead letter by record, one by the claim, usage back to the original values). database/tests/concurrency/assets-requeue-concurrency.ts: requeues two overlapping batches spanning two organizations in opposite orders without a deadlock. Shared helpers in database/tests/shared/assets-dead-letter-fixture.ts; both scripts registered in run-clean-install.ts. Mutations that each fail a named title: EXECUTE granted to ninaku_worker in runtime_grants.sql; a reclaimed expired lease left uncounted; a stranded job leased again; exhaustion checked before abandonment; the processing error count kept on a requeue; the limit check removed (2,1,0); the one-day window removed; the reservation restored twice; the advisory lock and the up-front ordered usage lock removed (deadlock detected). The only mutation the table catches first is a dead letter that keeps its lease (processing_jobs_lease_shape_chk)
Upgrade	A revision 106 database built from staging 94694e61 (migrations through 0096) and seeded with jobs in every state (pending, a live lease, an expired lease with four processing errors, a dead letter whose upload is from today and one whose upload is two days old, completed), upgraded by db:prepare (only 0097 applied), dumps a schema identical, with owners and privileges, to a fresh install of the merged tree (revision 107). On the migrated rows the pending job is claimed leased with its original variant and upload expiry, the expired lease is dead-lettered at its fifth processing error (7, 5), and the requeue returns 2,0,1 (that job and the recent dead letter; the two-day-old one is skipped) with the usage counters restored
Deploy order	The migrator applies 0097 before the new worker image. The old worker reads the claim's columns by name and ignores the two new ones; in that window it would process a row the claim returned as dead_lettered or completed, and its record call answers assets_job_lease_lost (the row holds no lease), so nothing is recorded twice

A3c-2 as built (worker retry classes, backoff, metrics and the memory gate, no migration)

Piece	As built
Classifier	application/processing/failure-classifier.ts (classifyHandlerFailure, moved from processing-failure.ts, which keeps the error types). Permanent: PermanentProcessingFailure with its §12 code, a decode error (assets.image_corrupt), a missing staging object after the upload's expiry. Storage (retry_storage, assets.storage_unavailable, no attempt cap): an ObjectStorageFailedError whose cause, or a cause up to five levels down, carries $metadata.httpStatusCode >= 500, any AWS SDK $retryable marker, the name or code SlowDown, TimeoutError, RequestTimeout, RequestTimeoutException, ServiceUnavailable, InternalError, EPIPE, ETIMEDOUT, EHOSTUNREACH, ENETUNREACH, ECONNABORTED, ECONNRESET, ECONNREFUSED, ENOTFOUND or EAI_AGAIN, or a message containing socket hang up or slow down (any case); a read longer than the declared size or shorter than its HEAD (InconsistentStorageReadError); a staging object not there yet before the upload's expiry (assets.upload_missing). Any other storage failure (403 AccessDenied, SignatureDoesNotMatch, NoSuchBucket, 412, a body that ends early, an error the list does not name) is retry_processing with assets.storage_refused: it counts towards the five processing errors, so a storage error that persists and is not on the list dead-letters the job after five attempts (about 12.6 minutes) instead of retrying forever; the operator fixes the cause and requeues it (runbook §11.2). Everything else is retry_processing (assets.processing_error)
Backoff	retryAvailableAt(outcome, job, now, random) in the same file (processing-retry-delay.ts removed). Storage: min(5 s × 2^attempt_count, 15 min) with ±20% jitter, then capped at 14 min 30 s: the SQL limit less a 30-second margin for the clock difference between the worker and PostgreSQL, because a retry the SQL refuses leaves the job leased until its lease expires, which now counts as a processing error. No attempt cap. Processing: 5 s, 30 s, 2 min, 10 min indexed by processing_error_count (the claim's new column, R1 requirement 2), the last step repeated, never jittered
Loop	A claim answered dead_lettered or completed is reported as an iteration with outcome: null and that result, without running a handler or recording anything; the runner polls again at once
Metrics and events	infrastructure/worker/media-worker-metrics.ts (meter ninaku-media-worker.assets): counter assets_processing_dead_letters with one attribute, ninaku.assets.settled_by (record or claim), and counter assets_storage_errors_total (one per retry_storage); no job or tenant id as an attribute. The runner counts every iteration that reached a job and logs assets.image_job.dead_lettered (error, job id and outcome only)
Operator entrypoint	The SQL function of A3c-1 through runbook §11.2, as OD21 decided; no script, job or route
Memory gate	npm run perf:assets (nest build && node tooling/assets/run-assets-benchmark.ts; the stage table names tooling/performance/, outside this branch's edit surface). The fixtures are generated in a child process (12 MP and 40 MP JPEG, 40 MP PNG, 12 MP AVIF, each at most 10 MiB like an upload; the job deadline hardening added a 12 MP and a 40 MP WebP, not measured yet, and gave each job the real deadline of ASSETS_IMAGE_LEASE_SECONDS, because the compiled handler had needed a ProcessingJobAttempt since the network timeouts fix); then one fresh process runs each image five times through the compiled ProcessUploadHandler (verify, master, four renditions, SHA-256, puts to an in-memory store), sampling RSS every 5 ms. tooling/assets/assets-benchmark-gate.ts decides: go when peak RSS ≤ 60% of ASSETS_BENCHMARK_MEMORY_LIMIT_MB (default 1,000 MB, so 600 MB) and p99 job time × 2 ≤ ASSETS_IMAGE_LEASE_SECONDS (default 120); otherwise it prints NINAKU_ASSETS_BENCHMARK_NO_GO with its refusals and exits 1. ASSETS_BENCHMARK_IMAGES runs a subset. At run time nothing else changes: a worker that exceeds its memory is killed, its lease expires, and A3c-1 counts each reclaim and dead-letters the job at the fifth
Measured (local only: macOS arm64, Node 24.13, sharp 0.35.5, libvips 8.18.7; not Railway, whose media-worker memory limit is not known yet)	The four images in one process, in this order: 12 MP JPEG (2.3 MB) p99 1.3 s, peak 333 MB; 40 MP JPEG (7.6 MB) p99 1.6 s, 338 MB; 40 MP PNG (3.2 MB) p99 1.9 s, 370 MB; 12 MP AVIF (1.5 MB) p99 1.6 s, 670 MB; 123 MB before the first job. Verdict at 1,000 MB: no-go (peak_rss_above_ceiling, 670 > 600); the lease condition passes by far (p99 1.9 s × 2 against 120 s). Each image alone in a fresh process: 304, 372, 372 and 572 MB, all under 600: the AVIF decoder dominates, and the process keeps memory it allocated for earlier images. Outside the stage's matrix, a 40 MP AVIF (4.9 MB, accepted when this was measured) peaked at 1,173 MB alone (2.5 s per job); it is refused now as assets.image_too_large, because OD5 capped AVIF at 12 MP (domain/image-limits.ts; image-limits.spec.ts › refuses an avif over 12 megapixels as too large and accepts one at exactly 12 megapixels and image-pipeline.integration-spec.ts with a 4,000 × 3,001 AVIF). The stage's no-go order offered about 1,120 MB (the four-image gate at 60%) or about 1,960 MB (a 40 MP AVIF). Decision recorded: .railway/railway.ts gives the media-worker 1,536 MiB (MEDIA_WORKER_MEMORY_BYTES), one replica, one job at a time (the image claim loop) and one libvips thread (sharp.concurrency(1)), and AVIF is capped at 12 MP. Pending: the re-measurement on Railway's Linux at that limit, ASSETS_BENCHMARK_MEMORY_LIMIT_MB=1536 npm run perf:assets, expected NINAKU_ASSETS_BENCHMARK_GO (not run: it needs an idle machine and the real limit; the gate defaults are unchanged). The lease of 120 s stays: the slowest job is about 50 times shorter
Proof	failure-classifier.spec.ts: classifies storage, permanent and processing failures; retries each transient storage signal alone as a storage error and counts an unknown storage failure as a processing error (every listed name, code, message and SDK marker on its own); schedules every processing retry, for processing errors 1 to 4, at most 15 minutes ahead (5 s, 30 s, 2 min and 10 min after 17 total attempts); the storage curve with its jitter and cap. infrastructure/processing/process-upload.handler.spec.ts (where A3b-2 put the handler spec; the stage table names application/processing/): retries a storage outage with capped backoff and no attempt cap, and dead-letters only the fifth processing error (40 storage retries, all pending and under 15 minutes, then processing delays of 5 s, 30 s, 2 min, 10 min and 10 min, the staging object kept; its dead letter comes from a repository double that mimics the SQL, so it proves the worker side only). The SQL side is proved by test/integration/assets-retries.integration-spec.ts never counts a storage retry as a processing error and dead-letters the job at its fifth processing error, which runs the real loop against the real claim_processing_job and record_processing_outcome (no storage server needed): storage, processing, storage and four processing errors give counters 1/0, 2/1, 3/1, 4/2, 5/3, 6/4 and the dead letter at 7/5 with the asset failed (assets.processing_exhausted); a storage retry counted as a processing error, or the threshold moved to the sixth, fails it. image-job-loop.spec.ts (jobs settled by the claim), image-job-loop.runner.spec.ts (metrics and the dead-letter event), media-worker-metrics.spec.ts, tooling/assets/assets-benchmark-gate.spec.ts. test/integration/assets-retries.integration-spec.ts, against MinIO and PostgreSQL: a storage outage (an unreachable endpoint, ECONNREFUSED) is retry_storage with one attempt and no processing error, then the upload is processed to ready; a job whose worker dies five times is dead-lettered by the claim with both counters at 5, its staging object kept and its reservation released, then requeued by the operator (both counters at 0) and processed to ready. The A3b-2 spec now shares its bucket and store setup through test/support/assets-media-worker-harness.ts. Mutations that each fail a named title: storage retries capped after nine; SlowDown classified as processing; the processing step indexed by the total attempts; the storage cap removed after the jitter; a job settled by the claim handled anyway; the runner not counting

A4a as built (the library: list, rename, archive and restore, no migration)

Piece	As built
Routes	GET /api/v1/assets (AssetsLibraryController, beside the AS3 read) and PATCH /api/v1/assets/{assetId}, POST /api/v1/assets/{assetId}/archival and POST /api/v1/assets/{assetId}/restoration (AssetChangesController), under AssetsController like A2b. None is capability-gated: the list needs organization-wide assets.media.view, the three writes assets.media.manage (PermissionCheckContract, a refusal is 403 · assets.action_forbidden, not audited, as the A2c completion)
List (AS4)	ListAssetsUseCase, one statement (libraryPageSql, infrastructure/assets/asset.queries.ts): the page is chosen in a subquery over assets.assets alone with an explicit organization_id = $1, a literal archived_at IS NULL or IS NOT NULL (so each listing reads its own partial index of A1a-1; EXPLAIN shows an index-only scan of assets_organization_active_idx), an optional status and the keyset predicate of foundation/pagination on (created_at, id), limit + 1 rows; the original variant is then joined for the AS3 fields. The cursor binding is the route, the organization, the status and archived, so a cursor sent with other filters or by another organization answers 400 · collection.cursor_incompatible. Items are the AS3 shape with only renditions.thumbnail (AssetListItem); private, no-cache, no ETag. archived is true or false only (default false): an archived listing never mixes with the active one
Rename (AS5)	RenameAssetUseCase: the asset is read with the AS3 statement plus FOR UPDATE OF a (the runtime's UPDATE (display_name) grant allows the lock), the optional If-Match is compared under that lock with the strong tag of the AS3 body (presentation/dtos/asset-entity-tag.ts, the same tag GET /assets/{assetId} answers; the controller hands the use case a precondition built from the header, because the tag hashes the response shape) and a mismatch is 412 · foundation.precondition_failed (ASSETS_FAILURE.PRECONDITION_FAILED, the code Catalog and Organization also publish). The current name answers the locked asset and writes nothing (7 statements); a change runs UPDATE assets.assets SET display_name under the tenant RLS policy, records assets.asset.renamed with assets.asset.display_name before and after, and reads the answer again (10 statements). The answer carries the new tag and private, no-store (HttpTaggedWriteResponse). The name is trimmedBoundedText(255), the A2b intent's rule, so a blank or NUL-bearing name is 400; clearing the name is not offered
Archive and restore (AS6)	ChangeAssetArchivalUseCase calls assets.archive_asset or assets.restore_asset (A1b-3) and answers the asset read after it. archived and restored record assets.asset.archived or assets.asset.restored once (9 statements); already_archived and not_archived answer 200 and record nothing (8); not_found is 404 · assets.not_found, another organization's asset included. The refusals raised by the functions flow unchanged to the A2a-1b mapping: assets_status_transition is 422 · assets.transition_invalid, assets_restoration_expired 422 · assets.restoration_expired, assets_asset_limit 422 · assets.asset_limit_reached; the transaction rolls back with no audit. Cache-Control: private, no-store
Proof	test/e2e/assets-library.e2e-spec.ts with the four stage titles, test/e2e/assets-archival.e2e-spec.ts (a failed asset's restoration and a purging asset's archival and restoration refused, nothing recorded), the A1b-3 contract assets-lifecycle-contracts.ts › refuses archiving or restoring a purging asset and never lets its status leave purging (unchanged, rerun green), the unit specs of the three use cases, the repository, the query and body schemas, the list item mapping, the failure mapping and the module wiring, and the statement-budget.e2e-spec.ts rows: 7 for a list, 10 for a rename and 7 when unchanged, 9 for an archival or a restoration and 8 for a repeat. The e2e "ready" fixture (processedIntoReady) now also inserts the four profile 1 renditions, because the deferred assert_ready_asset_renditions trigger re-checks a ready asset on any later write (the archival); the attached image is a catalog.item_assets row written in SQL, because the Catalog link routes are A5. Mutations that each fail a named title: the archived filter ignored (the repository titles and the list e2e title), the If-Match comparison skipped (the use case precondition title and the rename e2e title), a refused transition swallowed in the use case (the rollback unit title and three e2e titles), not_archived treated as restored (the repeat unit title, the archive e2e title and the statement row). The organization filter of the list removed fails only the repository title: the tenant RLS policy on assets.assets still filters the rows, so over HTTP it is an equivalent mutant; the explicit filter stays because the partial indexes lead with organization_id
OpenAPI	Four operations added under the Assets tag; npm run openapi:compat against origin/staging: no breaking change, path_added /api/v1/assets, /api/v1/assets/{assetId}/archival, /api/v1/assets/{assetId}/restoration and operation_added PATCH /api/v1/assets/{assetId}; no component schema added or removed, the three existing operations unchanged
Route classification	route-classification-assets.ts classifies the four operations as admin, unmeasured (administrative media management, D24); with the three Catalog image routes of A5b the typed table counts 164 operations (14 hot, 40 frequent, 108 admin, 2 not measurable, 41 measured)

A4b-1 as built (migration 0098_assets_purge, baseline revision 108)

Piece	As built
Migration	0098 (provisional: A3c's 0097 is not merged yet), expand only: four functions, three indexes, no table, policy or other function changed. SECURITY DEFINER, search_path = pg_catalog, pg_temp, EXECUTE revoked from PUBLIC and granted to ninaku_worker only (migration and runtime_grants.sql; the canonical 0070_assets.sql holds the end state and only revokes). All three refuse a transaction outside READ COMMITTED (assets_processing_isolation)
Indexes	assets_purge_archived_idx (archived_at) partial on archived_at IS NOT NULL AND status IN ('ready','failed','purging'), assets_purge_failed_idx (failed_at) partial on status IN ('failed','purging'), so the hourly scan is a BitmapOr of the two (measured with 50,000 assets: 190 buffers, 0.7 ms); processing_jobs_asset_kind_idx (asset_id, job_kind, completed_at), which serves the "no purge job in the last 30 days" probe and the processing_jobs foreign key check when an asset row is deleted (there was no index leading with asset_id on that table)
enqueue_purge_candidates(p_batch)	1–500 (assets_sweep_batch). Inserts a purge_asset job (uuidv7()) for up to p_batch assets that are ready, failed or purging and archived more than 30 days ago, or failed or purging and failed more than 7 days ago, with no open (pending, leased) purge job and no purge job completed, or dead-lettered (by updated_at), in the last 30 days; ON CONFLICT … DO NOTHING on processing_jobs_one_open_uq, so two sweeps never open two jobs. Returns (enqueued, needing_cdn): the jobs inserted and how many of them belong to an asset that was ever public and ready (the worker logs those as deferred while the CDN purge is unconfigured). No row lock: begin re-checks
purge_asset_begin(p_job_id, p_lease_token)	Locks the job (a job of another kind, not leased, with another token or an expired lease is assets_job_lease_lost), then the usage row and the asset (lock order of §7). Eligibility is a positive test: v_eligible := FOUND AND ((archived_at IS NOT NULL AND status IN ('ready','failed','purging') AND archived_at <= now() - 30 days) OR (failed_at IS NOT NULL AND status IN ('failed','purging') AND failed_at <= now() - 7 days)), every comparison guarded so no NULL reaches the branch, and the probe runs only on v_eligible IS TRUE. A missing asset row (or a job whose organization is not the asset's) answers not_found and completes the job with assets.purge_asset_missing; an asset no longer due (restored and re-archived, a purging asset without dates) answers ineligible and completes it with assets.purge_ineligible; neither changes the asset. Otherwise a nested block deletes, in the stage's order, every processing_jobs row of the asset (the running job included), its storage objects, variants, upload and the asset, then raises the private SQLSTATE NKP01, which rolls the block back; a foreign_key_violation instead answers referenced and completes the job with assets.asset_referenced, the asset untouched. On success the asset becomes purging (skipped when it already is, so a reclaimed job answers deletable again) and the function returns deletable, the storage objects' keys and provider codes (ordered by key), the upload's staging provider and key, the public rendition names (the profile's four when the asset is public and was ever ready; empty otherwise, since a never-ready asset never had a delivered URL), the delivery token and the profile. Storage rows are untouched
purge_asset_finish(p_job_id, p_lease_token)	Same lease check and locks; an asset that is not purging is assets_purge_not_begun. Computes the bytes to release with the reconciliation's predicates (ready variants with an available primary object; declared bytes of an issued or received upload), deletes storage objects, variants, upload, every job of the asset and the asset in one transaction, subtracts exactly those bytes and answers purged. Neither begin nor finish touches active_asset_count: every purgeable prior state is uncounted by counts_as_active_asset (an eligible asset is archived, or failed, or already purging), which the safety contract proves against reconcile_usage_batch for each of them. A foreign_key_violation keeps the asset purging, completes the job with assets.asset_referenced_after_purge and answers referenced_after_purge. Deviation: the spec says "calls assets.reconcile_usage"; no per-organization reconciliation function exists (A1c-2 left it to this stage), so the finish subtracts the asset's own contribution and the contract proves the result equals the reconciled counters
purge_asset_dead_letter(p_job_id, p_lease_token, p_error_code)	Lease check as begin; the code must match ^assets\.[a-z0-9_.]{1,72}$ (else assets_outcome_shape); sets the job dead_lettered with error_class 'permanent', the code, attempt_count + 1 and the lease cleared, and touches nothing else. The worker calls it when a purge cannot go on safely (assets.purge_urls_unavailable, assets.cdn_unconfigured_expired). assets.requeue_dead_letters (A3c) only requeues process_upload jobs, so a dead-lettered purge job named to it is counted in skipped_ineligible (proved); the recovery is automatic: the enqueue retries the asset 30 days after the dead letter
Deviations	(1) enqueue also picks purging assets (spec: "not purging"): a purge job that dead-letters would otherwise leave its asset purging forever with half-deleted objects; with this rule it is re-enqueued 30 days after its dead letter, and a referenced_after_purge asset monthly (accepted by the coordinator). (2) begin answers two more outcomes, ineligible and not_found, and returns job_created_at (for the worker's 14-day CDN cap). (3) No row lock in enqueue and no advisory lock: begin is the only writer that decides
Proof	database/tests/contracts/assets-purge-contracts.ts (NINAKU_ASSETS_PURGE_OK, registered in run-clean-install.ts after the requeue concurrency script), the four stage titles. Inside them: the three functions' shape and grants, the runtime refused (permission denied), a foreign lease, REPEATABLE READ, a finish before the begin; the referenced asset's rows, jobs and usage byte-identical before and after; the begin row exactly (five keys, providers, staging key, four names, token, profile 1), storage rows unchanged but the status; a reclaimed lease answering deletable again; after the finish no row of the asset left (asset, variants, objects, upload, jobs) and usage stored_bytes lower by the asset's 6,000 bytes and equal to the reconciliation; a failed asset 8 days old purged with no keys or names and usage unchanged; an asset no longer due answering ineligible; restore refused (assets_status_transition) and the attach lock reading purging; a reference inserted after the begin answering referenced_after_purge with nothing deleted; the enqueue bounds and isolation, a batch of 1, due (archived 31 days, failed 8 days, completed 31 days ago, a purging asset with a dead-lettered job) and not due (archived 29 days, failed 6 days, ready, completed 10 days ago, already open) assets, and a second sweep enqueuing nothing. Mutations, each failing a named title: purging set before the reference test (the referenced title); the asset row deleted before its variants in begin (the deletion title and the purging title answer referenced) and in finish (the deletion title); the 30-day completed-job window dropped (the enqueue title); the stored bytes not released (the deletion title); the archive age not re-checked in begin (the deletion title)
Review proof	database/tests/contracts/assets-purge-safety-contracts.ts (NINAKU_ASSETS_PURGE_SAFETY_OK, registered after the purge contract): begins a purge only when the asset is provably due and answers ineligible or not_found without changing anything otherwise (a purging asset with no dates, archived 29 against 31 days, failed 6 against 8 days, an asset row removed under session_replication_role = replica after its job was leased, a job moved to another organization the same way; a failed asset without failed_at is refused by assets_status_state_chk, so it cannot exist); leaves the active count, stored bytes and reserved bytes equal to the reconciliation after a purge from every purgeable prior state (failed, failed then archived, archived ready, archived processing and archived pending, both ineligible, archived then failed; each on its own organization, a reclaimed second begin before finish, and the counters compared with reconcile_usage_batch run over every organization); never duplicates a dead-lettered purge job across consecutive sweeps, refuses its operator requeue and retries it after 30 days. Mutations, each failing a named title: the original NULL-prone predicate with the not_found branch removed (the eligibility title: the undated purging asset, the vanished asset and the foreign lease answer deletable); finish releasing an active slot (the reconciliation title); the dead-letter suppression removed from the enqueue (the dead-letter title)
Upgrade	A revision 107 database built from feat/assets-retries b9553600 (db:fresh), seeded with one DO block through the real functions (pending, processing, ready, failed, dead-lettered, archived 40 days, failed 10 days, a purging asset, and an asset archived 40 days that a catalog item uses), upgraded by db:prepare from this branch: the ledger gained only baseline-r108 and 0098_assets_purge; pg_dump --schema-only (owners and privileges) is identical to a fresh install of this branch. Repeated after the review fixes with the same result. On the migrated rows, as ninaku_worker: the enqueue answered (3,2) (the archived, the failed and the referenced asset; two were ever public), the archived asset deletable (five keys, four names) then purged, the failed asset deletable with no keys then purged, the referenced asset referenced; usage went from 4,24000,4096 to 4,18000,4096
Renumbering	A new number changes: the file name database/migrations/0098_assets_purge.sql; its ninaku_migrations.claim('0098_assets_purge', …) id; baseline_revision 108 and the "Revision 108" scope paragraph in database/manifest/baseline.json; the 108 and 0098 mentions in database/README.md, this note, the A4b-2 note and the §16 "As built" line of ASSETS_STAGE_SPECS.md; the regenerated database/review/*

A4b-2 as built (the purge job, the CDN purge and the hourly sweep, no migration)

Piece	As built
Loop	The purge runs in the image loop (§6.3: one job at a time). ProcessingJobHandler.handle(job, leaseToken) now receives the claimed lease token, and a handler may answer { settledResult } (isSettledByHandler) when its own SQL already settled the job: the loop then records nothing and calls no afterRecord. ProcessUploadHandler is unchanged
Handler	application/processing/purge-asset.handler.ts (PurgeAssetHandler, registered for purge_asset): begin; referenced and ineligible settle at once; on deletable it builds the URLs <ASSETS_PUBLIC_BASE_URL>/a/<token>/p1/<name>.webp of the returned names (at most four), refuses to go on while the CDN purge is unconfigured and there is a URL (nothing is deleted yet), removes every returned key, the staging key and, for erasure completeness, the keys derived from the token (m/<token>/original.webp and the four a/<token>/p1/*.webp, which catches an object written by a put whose outcome was never recorded; a missing key counts as done), then purges the URLs in one call, then finish. Fail closed (purge-targets.ts): when the asset has any r2-public object or public rendition names, the URL list must be derivable completely (a valid delivery token, profile 1, a public base URL, known names, and every r2-public key among the derived ones); otherwise PurgeNeedsOperatorError (assets.purge_urls_unavailable) is raised before any delete and the job is dead-lettered through purge_asset_dead_letter, never finished. While the CDN purge is unconfigured a job that needs it retries without deleting, and once the job is 14 days old (job_created_at) it is dead-lettered with assets.cdn_unconfigured_expired instead. The settled event is emitted after the try, so a failing log or metric never turns a finished purge into a retry. Any other failure is answered retry_storage (the only retry the SQL accepts on a purge job, A1c-1) with a code: assets.cdn_unconfigured, assets.cdn_purge_failed, assets.storage_provider_unknown, the A3c classifier's assets.storage_unavailable or assets.storage_refused for a storage failure, assets.purge_error otherwise. Deviation: the A3c processing class (five attempts) cannot apply because record_processing_outcome refuses retry_processing on a purge job; a purge therefore retries without a cap at the storage backoff (at most about 15 minutes), and a worker that dies on it is still dead-lettered by the claim at its fifth lost lease
CDN port	application/ports/cdn-cache-purger.port.ts (CdnCachePurgerPort: isConfigured(), purgeUrls(urls)). infrastructure/purge/cloudflare-cdn-cache-purger.ts: POST https://api.cloudflare.com/client/v4/zones/<ASSETS_CDN_ZONE_ID>/purge_cache through OutboundHttpService with authorization: Bearer <token>, content-type: application/json, body {"files":[…]}, 10 s timeout, at most 100 URLs per call (S22); anything but a 2xx with "success": true, or a transport error, is CdnCachePurgeFailedError whose cause carries the status only. infrastructure/purge/unconfigured-cdn-cache-purger.ts when the group is absent: the module logs assets.media_worker.cdn_purge_unconfigured once at boot
Environment	CDN purge group of the media-worker (ASSETS_CDN_ZONE_ID, ASSETS_CDN_PURGE_TOKEN, MEDIA_WORKER_CDN_PURGE_SHAPE), all or nothing as its own channel (assets CDN purge), refused in the api and worker roles; MediaWorkerSettingsService.cdnPurge(). The token joins the known secrets (collectEnvironmentSecrets and KnownSecretsRegistryService), so the redactor masks it in any log line
Sweep	infrastructure/worker/enqueue-purge-candidates.job.ts: every hour, enqueue_purge_candidates(500) repeated until a batch inserts fewer than 500, at most 20 batches (10,000 jobs) a run; logs assets.purge.enqueued (count and batches) or assets.purge.enqueue_failed, and, once per run when the CDN purge is unconfigured, assets.purge.deferred_without_cdn with the number of enqueued purges that need it; not started without the storage group. It is not gated on the CDN: a never-public asset needs none. The UTC hour arithmetic of ReconcileUsageJob moved to next-utc-hour.ts
Repository	infrastructure/purge/asset-purge.repository.ts: the three functions, one autocommit statement each, so no transaction is open while objects are deleted or Cloudflare is called
Metrics and logs	Counter assets_purge_attempts (meter ninaku-media-worker.assets) with one attribute, ninaku.assets.purge_result (purged, referenced, ineligible, not_found, referenced_after_purge, retried, dead_lettered); logs assets.purge.settled (info), assets.purge.referenced_after_purge (error, the alert of §6.8) assets.purge.retried (warn) and assets.purge.dead_lettered (error), each with the job id, the code and the failure's name and code without its message. A purge retry is also counted in assets_storage_errors_total
Erasure entry (OD23)	Not built: the stage and OD23 define the trigger path with the personal-data policy; until then an erasure is "archive, then the purge 30 days later" (runbook §11.3, §11.4)
Proof	purge-asset.handler.spec.ts: the two stage titles plus the unconfigured CDN (nothing deleted), a never-ready asset purged without the CDN, referenced and ineligible settled without storage or CDN calls, referenced_after_purge reported, an unknown provider retried before any delete. cloudflare-cdn-cache-purger.spec.ts against a fake OutboundHttpService: the exact request (URL, method, headers, body, timeout), no call for an empty list and two calls for 101 URLs, a 403, "success": false, a non-JSON body, a 429 and a timeout each failing without the token or Bearer in the error. image-job-loop.spec.ts (hands the handler the claimed lease token and records nothing for a job the handler settled itself), purge-events.spec.ts, enqueue-purge-candidates.job.spec.ts, assets-worker.module.spec.ts (the handler map, the Cloudflare adapter with the group, the unconfigured adapter and its boot log without it), environment-variables.schema.spec.ts, media-worker-settings.service.spec.ts and the three secret specs. test/integration/assets-purge.integration-spec.ts against MinIO and PostgreSQL (skipped without ASSETS_MEDIA_WORKER_E2E_*): a processed JPEG archived 31 days ago is enqueued and purged, its five objects are gone from both buckets, no row is left, the recording CDN received exactly its four URLs and the usage counters fell by its ready bytes and equal the reconciliation; an asset archived 45 days ago that a catalog item uses answers referenced, keeps its five objects and rows, is not enqueued again the same month and is enqueued once its purge job is 31 days old; a corrupt upload failed 8 days ago is purged without a CDN call and with usage unchanged. Mutations, each failing a named title: the finish before the CDN purge (the first stage title); the unconfigured-CDN gate removed (the unconfigured title); retry_processing instead of retry_storage (the retry title and two more); the "success": true check dropped (the adapter refusal title); a settled job recorded (the loop title). The unit specs of the handler, the adapter, the loop and the job were seen failing before their code existed; the events spec and the MinIO end-to-end spec were written after the code they cover
Review proof	purge-targets.spec.ts: the four URLs, none for a never-public asset, and refuses for an operator instead of answering an incomplete list for a missing or malformed token, profile 2, an unknown name, no base URL, a public object without names and a public object outside the derived URLs. purge-asset.handler.spec.ts (doubles in test/support/purge-asset-handler-harness.ts): the dead letter without any delete, the 14-day cap (one minute before: retry; at 14 days: dead letter), a failing dead letter retried, a failing settled event not retried, not_found settled. asset-purge.repository.spec.ts against a fake pool (row mapping with job_created_at, null arrays, unknown outcome and result, unpaired keys and providers, no row, the dead-letter answer, the enqueue counts coerced to numbers). asset-purge.repository.integration-spec.ts against PostgreSQL through the worker role: begin and finish of an archived ready asset with the counters equal to the reconciliation, and a dead letter left out of two sweeps. enqueue-purge-candidates.job.spec.ts: hourly runs, batches until a short one, the 20-batch bound, a failure keeping the schedule, the deferred log. Mutations, each failing a named title: an incomplete URL list answered as empty (the seven refuses for an operator titles and the handler dead-letter title); the 14-day cap disabled (the cap title); the settled event inside the try (the settled-event title); a full batch treated as short (the three sweep titles); the key/provider pairing check dropped (the repository refusal title)
Job deadline (network timeouts fix)	Every attempt carries a deadline: the lease minus IMAGE_JOB_LEASE_MARGIN_MS (10 s, built in foundation/config/schema/image-job-lease-margin.ts from the 5 s default statement timeout, a 2 s lock and connection allowance and 3 s of headroom). The media-worker refuses to boot when DATABASE_STATEMENT_TIMEOUT_MS plus that allowance reaches the margin. The purge checks the deadline before the CDN call and before finish, and the Cloudflare call is capped at the smaller of 10 s and the time left. A job that runs out of time is answered retry_storage with the reused code assets.storage_unavailable, not a code of its own: the code list lives in domain/processing-job.ts, outside the scope of that fix. Operators therefore see a job that ran out of time exactly like an unreachable storage provider (assets.purge.retried with that code and the failure name JobDeadlineExceededError, or a storage error named TimeoutError or AbortError), retried at the storage backoff. The purge keeps that answer on purpose: all of its time goes to storage and Cloudflare calls. Image processing (process_upload) has had its own code since the job deadline hardening (assets.job_deadline_exceeded, see "Job deadline hardening as built")
Only the real services can prove	The Cloudflare request against the real API with the A0 token (status, "success": true, the 403 of a token without Cache Purge), that a purged URL answers HTTP/2 404 afterwards (runbook §10.5), the S3 DeleteObject permission of the worker key on m/ and in/ and the R2 token's on a/ (§13.4), and the latency of a purge on Railway

A5a as built (published contracts, no migration, no route)

Piece	As built
Surface	contracts/asset-usage.contract.ts (AssetUsageContract, ASSET_MEDIA_KIND, ASSET_ACCESS_CLASS, ATTACHMENT_REFUSAL and their types, AttachableAsset { assetId, imageRef }), contracts/asset-delivery.contract.ts (AssetDeliveryContract, ASSET_DELIVERY_LIMIT.ASSET_IDS = 2000, AssetDeliveryEntry { status, imageRef, aiGenerated, urls }, and the re-exported ASSET_STATUS and RENDITION_NAME, so a consumer never imports assets/domain), contracts/asset-contract.errors.ts (AssetNotAttachableError { refusals: [{ assetId, reason }] }, AssetDeliveryRequestTooLargeError) and contracts/assets-contracts.module.ts, which re-exports AssetsModule as catalog/contracts/catalog.module.ts does. AssetsModule binds both abstract classes to application/usage/asset-usage.ts and application/delivery/asset-delivery.ts and exports them. No type carries a key, bucket, provider or variant id; a type-level test in asset-delivery.contract.spec.ts pins the keys of the three result shapes
assertAttachable	One statement (infrastructure/usage/asset-usage.repository.ts): SELECT … FROM assets.assets WHERE id = ANY($1) ORDER BY id FOR SHARE in the caller's tenant transaction, so RLS answers a foreign asset as absent. Repeated ids are collapsed to their first occurrence before the lock. Refusals per distinct requested id, in that order, first match wins: not_found, purging, archived, not_ready, wrong_media_kind, wrong_access_class; any refusal throws AssetNotAttachableError with all of them. Otherwise it returns { assetId, imageRef } per distinct id in the order of the request (type AttachableAssetsInFirstRequestedOrder), not in the lock's id order. An empty list returns [] with no statement. wrong_media_kind is unreachable today (assets_media_kind_chk allows only image); not_approved joins with A8d
describe	One statement (infrastructure/delivery/asset-delivery.repository.ts): primary key lookups WHERE id = ANY($1) under RLS, no organization_id parameter (the contract receives only the transaction context; RLS filters the tenant). More than 2,000 ids throws AssetDeliveryRequestTooLargeError before any SQL; an empty list returns an empty map with no statement; unknown and foreign ids are absent from the map. A ready public asset gets imageRef (<token>/p<profile>) and one URL per requested rendition, <ASSETS_PUBLIC_BASE_URL>/ + publicRenditionKey(...); every other asset (also purging, processing, failed, private) keeps its status and aiGenerated with imageRef and urls null. Archived assets still resolve (§6.6)
Template and fingerprint	tileUrlTemplate() → <ASSETS_PUBLIC_BASE_URL>/a/{imageRef}/tile.webp; fingerprint() → the first 8 hex of SHA-256 of the base URL, a vertical bar and the profile list, that list being the profile numbers joined by commas (1 today)
Base URL	infrastructure/delivery/asset-delivery-settings.ts reads AppConfigService.assetsStorageSettings()?.publicBaseUrl (A2a-1a; no new variable). When the API group is absent (local, test), urls and tileUrlTemplate() are null and the fingerprint hashes an empty base URL, so a consumer never fails because Assets is unconfigured and its ETag still changes once the base URL is set
Grant	assets-lifecycle-contracts.ts: lets the runtime lock assets for share, which needs its column update grant on display_name locks a ready asset FOR SHARE as the runtime, then revokes UPDATE (display_name) inside an aborted transaction and observes permission denied for table assets
Proof	asset-usage.repository.integration-spec.ts and asset-delivery.repository.integration-spec.ts (through the application classes, seeded by test/support/assets-fixture.ts, which writes every variant of profile 1 so a ready asset passes assets_ready_requires_renditions), application/usage/asset-usage.spec.ts and application/delivery/asset-delivery.spec.ts (fake ports: refusal precedence and aggregation, request order with duplicates, empty and 2,000-id short circuits, masking of non-ready or non-public assets, no URLs without a base URL, deliveryFingerprint(baseUrl, profiles) stable and changing with the profile list), the delivery integration spec also requesting another organization's ready public asset, which RLS leaves out of the map, asset-delivery.contract.spec.ts (the fingerprint title, the template matching the tile URL, the type-level surface) and assets-contracts.module.spec.ts (the module exports exactly the two contracts; a Test.createTestingModule with the database, audit, identity and platform modules overridden resolves both contracts to the same AssetUsage and AssetDelivery instances and runs each through its real repository on a fake session and the configured base URL; replacing a useExisting alias with useClass fails it). Mutations that each fail a named title: FOR SHARE dropped (the usage title: another writer's FOR UPDATE NOWAIT is no longer refused inside the transaction); URLs returned for processing (the delivery title); the archived check dropped (the usage title)

A5b as built (migration 0095_catalog_item_images, baseline revision 105)

Piece	As built
Migration (A5b-1)	Expand only: GRANT SELECT, INSERT, UPDATE, DELETE ON catalog.item_assets TO ninaku_runtime (no TRUNCATE); the statement-level triggers item_assets_catalog_version_{insert,update,delete}_trg over changed_rows executing catalog.bump_catalog_version(); item_assets_organization_asset_idx (organization_id, asset_id) (SG11); the audit actions catalog.item.images_set and catalog.item.variant_images_set (catalog, configuration, tenant, medium, before and after, administration.platform). Canonical end state in 0080_catalog.sql, 0380_audit.sql and runtime_grants.sql; the K1 unreachable list and the prepare contract's unreachable tables lose item_assets. Upgrading a revision 104 database that already holds an item_assets row keeps the row and the catalog version, and its pg_dump --schema-only (grants included) is identical to a fresh install
Routes (A5b-2)	PUT /catalog/items/{itemId}/images and PUT /catalog/items/{itemId}/variants/{variantId}/images as built in A5b; since API v7 one route, PUT /catalog/items/{itemId}/images with { images, variants? }, sets the item list and the lists of its variants (ItemImagesController, one SetItemImagesUseCase for both scopes), { images: [{ assetId }] }, 0–10, distinct, optional If-Match (the C3 tag). Order: permission → catalog_versions FOR UPDATE → item FOR UPDATE (lockItemForWrite) → archived item 422, unknown variant 404, archived variant 422 · catalog.variant_archived → same list answers 200 with nothing written → capability only when the list adds or reorders (a removal only is ungated, the C13 rule, so a lapsed plan can always detach) → assertAttachable for the ids the list adds only (attachable-images.ts) → three set-based statements (infrastructure/items/item-image.queries.ts): delete the rows not in the list, demote the old primary when it stays (the one-primary indexes are not deferrable), and INSERT … ON CONFLICT (item_id, asset_id) WHERE item_variant_id IS NULL DO UPDATE … WHERE (media_role, sort_order) IS DISTINCT FROM … (the variant twin conflicts on (item_variant_id, asset_id) WHERE item_variant_id IS NOT NULL), sort_order = position, the first primary → one audit with the ids before and after (catalog.item.images, or catalog.item.variant and catalog.item.variant.images) → the item read. Catalog names no assets.* table; lint:sql-ownership keeps its zero catalog baseline
Refusals	AssetNotAttachableError becomes CatalogImagesRefusedError and, at the edge, 422 · catalog.image_not_attachable with one meta.errors[] entry per refused asset in the shared field-error shape: field items.<itemId>.images.<assetId>, code the reason (not_found, not_ready, archived, purging, wrong_media_kind, wrong_access_class), and a message naming both ids (deviation: the shared ProblemDetailsMeta admits only field errors, so { assetId, reason } travels as field and code)
C3 (AC3)	Item and every ItemVariant gain images[] (assetId, isPrimary, sortOrder, status, thumbnailUrl, cardUrl, detailUrl). The item statement carries them as two scalar JSON subqueries on item_assets, so no catalog statement is added; ItemRepository (read and lock) then calls AssetDeliveryContract.describe once for every image of the item, only when it has images (an item without images costs what it cost before). Every answer that carries the C3 shape (create, edit, lifecycle, classification, offers, variants, barcodes, images) therefore carries the images with their URLs, and the item tag, a hash of that whole representation, changes with the images and with the delivery base URL
Statements	17 for the measured PUT on an item that already has an image (session, membership, BEGIN, tenant context, permission, version lock, the item statement and one describe, the capability, assertAttachable, delete, demote, upsert, audit, the item statement and one describe, COMMIT); 25 before API v7 PR 6, when each item read was five statements
Proof	test/e2e/catalog-item-images.e2e-spec.ts (the five A5b titles of section 18), database/tests/contracts/catalog-item-images-contracts.ts (both titles), test/e2e/statement-budget.e2e-spec.ts (sets an item's images in the measured statements), set-item-images.use-case.spec.ts, item-image.repository.integration-spec.ts, item-response.spec.ts, domain/items/item-image.spec.ts. Mutations, each failing a named title: assertAttachable skipped for the new ids or run on the kept ones (the use-case order title), the asset locked before the version row (the same), the delete bump trigger dropped (the contract's bump title), the demotion removed (the integration title, item_assets_one_item_primary_uq)
Review hardening	Duplicates never reach SQL: the request schemas answer 400 · foundation.validation_failed for a repeated asset (ids are lowercased first, so two cases of one id repeat), more than 10 images, and in the bulk for zero or more than 100 items or a repeated item; both use cases repeat the check before opening a transaction and refuse with the catalog refusal image_list_invalid, answered with the same 400 (refused rather than deduplicated, because position is meaning: the first image is the primary). The three follow-up statements of the item read (ITEM_CATEGORIES_OF, ITEM_OFFERS_OF, ITEM_BARCODES_OF, infrastructure/items/item-read.queries.ts) are builders that take readonly string[] and bind it as their single ANY($1::uuid[]) parameter, so no caller can bind one id. A failing describe propagates and rolls the command back. The DB contract also proves write isolation (a foreign UPDATE and DELETE change nothing, a foreign INSERT is refused by the row policy) and one bump per statement kind through its own trigger, none for a no-op

A5c as built (no migration)

Piece	As built
Route	PUT /catalog/item-images (SetManyItemImagesUseCase), { items: [{ itemId, images: [{ assetId }] }] }, 1–100 items, each once, each list as AC1. One transaction: permission → version row → LOCK_ITEMS_FOR_IMAGES (every item FOR UPDATE in id order with its current item image ids, one statement) → unknown items 404 · catalog.not_found, then archived items 422 · catalog.item_archived, each with meta.errors[] naming every item (field items.<itemId>) → items whose list did not change are left out → capability unless every change only removes → one assertAttachable for every new id of every item → the AC1 delete, demotion and upsert, each once over all items → one catalog.item.images_set per changed item → one set-based read of every item sent (READ_ITEMS and the four follow-up statements by ANY) and one describe → 200 { data: { items: [{ itemId, etag }] } } in request order, each tag the one GET answers; Cache-Control: private, no-store
Statements and version	19 plus one audit per changed item, the same for 1 and for 100 items; the version moves by 1 to 4 whatever the number of items
Proof	test/e2e/catalog-item-images.e2e-spec.ts › sets the images of many items in one request moving the catalog version at most four times whatever the number of items, and refuses the whole request when one asset is not attachable; test/e2e/statement-budget.e2e-spec.ts › sets images for 100 items with a statement count independent of the number of items except the audits; set-many-item-images.use-case.spec.ts. Mutations: per-item write statements (the budget title: 316 against 19), a refusal swallowed so the rest commits (the use-case refusal title)

A6 as built (till read with images, no migration)

Piece	As built
Shape	C17 and C19 items carry imageRef (<token>/p<profile> or null) and aiGenerated (false without an image; always false until A8 writes AI assets); a variant carries both keys only when it has a primary image of its own (no keys otherwise, so a variant without one adds zero bytes and the till shows the item image); meta.media = { tileUrlTemplate } once per answer (null while ASSETS_PUBLIC_BASE_URL is unset). An attached asset that is not ready and public answers imageRef: null, aiGenerated: false; an archived attached asset keeps delivering (§6.6). No asset id, URL, key or bucket in the till body
SQL	The shared enriched page of C17 and C19 (infrastructure/till/till-read.queries.ts) left-joins catalog.item_assets on organization_id, item_id, item_variant_id IS NULL and media_role = 'primary' (the predicate of item_assets_one_item_primary_uq) and, inside the variant aggregate, on item_variant_id, IS NOT NULL and primary (item_assets_one_variant_primary_uq); both unique indexes guarantee at most one row, so no item or variant repeats. EXPLAIN (ANALYZE, BUFFERS) on the 925-item till with 1,000 primaries: the planner hashes the organization's primaries (one sequential pass, 54 buffers, 0.1 ms) for the item join and probes item_assets_one_variant_primary_uq per variant (875 loops, 0 rows); with enable_seqscan = off the item join uses an index too. Still one read statement; Catalog names no assets.* table
Delivery	ReadWhatAnOutletSellsUseCase injects AssetDeliveryContract; application/till/sellable-images.ts collects the distinct primary asset ids of the answered items and variants (after the 2,000-item cut) and calls describe once with no renditions (in chunks of 2,000 ids, so one call in practice); no ids, no call. The chunked call moved from infrastructure/items/item-reads.ts to application/images/asset-descriptions.ts, shared by C3 and the till
ETag	application/till/sellable-entity-tag.ts: "c<catalogVersion>-s<structureVersion>-<businessUnitId or none>-d<fingerprint>"; fingerprint() and tileUrlTemplate() run no SQL, so the 304 is still decided after the outlet state and before any item or image read. An image command already moves the catalog version (SG11 triggers), so an image change gives a new tag; another organization's change never does
ETag invariant	The C17 body now depends on delivery state while the tag is c-s-bu-d<fingerprint>; that is sound because every way that state can change for a listed image already moves one of the tag parts: (a) only ready public assets are ever linked (assertAttachable, AS13; access_class is immutable, assets_protect_access_class_trg); (b) every link change (attach, detach, reorder, primary moved) bumps the catalog version through the item_assets statement triggers of migration 0095 (SG11); (c) a ready asset can only become purging (asset-status.ts transitions; the runtime's only column grant on assets.assets is display_name), and archiving changes neither its status nor its delivery (§6.6); (d) the purge of A4b (built: "A4b-1 as built") answers referenced on the item_assets_asset_organization_fk violation and never removes a linked asset; (e) the media host is the fingerprint. Obligation on A4b and later stages: a purge must never remove a referenced asset; if it ever could, it must bump the catalog version in the same transaction (the requirement line of A4b in ASSETS_STAGE_SPECS.md). Proven by catalog-till-images.e2e-spec.ts › moves the till tag on every image link change and keeps the tag and the image reference when an attached asset is archived
Join fan-out	The item and variant joins repeat the predicates of item_assets_one_item_primary_uq and item_assets_one_variant_primary_uq, so neither can match two rows: till-read.repository.integration-spec.ts proves PostgreSQL refuses a second primary for an item and for a variant (23505 naming each index) and that an item with a primary, three gallery images and a variant with its own primary is listed once by C17 (also at a limit cut below the number of items) and once across C19 pages of one item
Wire contract	presentation/dtos/till/sellable-response.spec.ts: a variant without a primary of its own has no image keys, an undeliverable own image answers null and false, an item always carries both keys, the strict schemas accept the shape and refuse a missing imageRef or a non-boolean aiGenerated, and meta.media.tileUrlTemplate is a string or null but never absent. The use-case spec also covers the outlet no unit operates (empty lists, the template, a -none-d… tag, no read, no describe) and a describe limited to the 2,000 answered items
Review mutations	Each fails a named title: the tag ignoring the catalog version (two catalog-till-images titles), the item join without media_role = 'primary' (the fan-out integration title), a variant always carrying image keys (the wire title), describe over the 2,001st item (the 2,000 title)
Statements	Pinned in statement-budget.e2e-spec.ts › reads what an outlet sells with images in 9 statements and answers 304 in 7: C17 200 9, 304 7, C19 9 with images; the table rows without images stay 8, 7 and 8
Proof	test/e2e/catalog-till-images.e2e-spec.ts (the stage title plus the variant, media host, not-ready/private/archived and C19 titles), sellable-entity-tag.spec.ts (the stage title, with two real AssetDelivery fingerprints), read-what-an-outlet-sells.use-case.spec.ts (one describe, none without images, the 304 before any read, the page). Existing till e2e titles updated for the tag suffix, meta.media and the two item keys. Mutations, each failing a named title: fingerprint dropped from the tag (the entity tag title, two use-case titles, the media host e2e title); a describe call with no ids (describes nothing when no listed item or variant has an image; the former assetIds.length > 0 guard was an equivalent mutant because the chunked call already sends nothing for no ids, so it was removed); a non-deliverable entry keeping aiGenerated (two use-case titles); the item join without media_role = 'primary' (the stage e2e title: the gallery image duplicates the item); the variant join without item_variant_id = v.id (the variant e2e title); the 304 decided after the read (the use-case 304 title and the statement title)
OpenAPI	npm run openapi:compat against origin/staging: no breaking change; ten property_added (imageRef, aiGenerated on items and variants and meta.media on both routes)
perf:http gate	Paired runs on one loaded development machine (Apple M4 Pro, load average 25.6 and 27.3 at start, other agents running), staging 94694e61 then A6, each on a fresh ninaku_a6; A6's till world gives every odd-numbered item (every item both tills list) a ready public primary image. 1 client, p50 / p90 / p95 / p99 / max ms: catalog-till-sellables 27.68 / 29.33 / 31.10 / 36.77 / 43.12 → 31.06 / 32.40 / 33.12 / 36.76 / 41.97, 417,908 → 473,066 bytes (+12 % p50, +13 % bytes); catalog-till-sellables-restaurant 18.81 / 19.89 / 20.23 / 22.07 / 28.74 → 20.16 / 21.28 / 21.80 / 24.48 / 28.81, 214,237 → 231,658 bytes (+7 % p50, +8 % bytes); catalog-till-sellables-304 1.05 → 0.95 ms; C19 page of 50 7.91 → 8.24 ms, 21,677 → 24,860 bytes. 16 clients (informative): 71.95 / 80.89 / 83.55 / 91.13 / 94.22 → 94.54 / 107.86 / 112.55 / 124.48 / 143.20 and 51.89 / 66.47 / 71.18 / 79.48 / 87.66 → 54.69 / 63.93 / 66.20 / 70.48 / 76.81. Go: the restaurant's p90/p95/p99 meet 35/50/100 ms and the 304 stays near 1 ms; aiGenerated stays in the body. The change is +7 to +12 % at p50, under the 25 % tolerance; the recorded K7 baselines (23.99 and 15.24 ms at load average 4.6) failed the gate on this machine even for staging's own code (27.68 and 18.81 ms), so KNOWN_BREACHES is re-baselined with the A6 numbers above and their cause. Local evidence only, never production capacity

Job deadline hardening as built (no migration)

Piece	As built
Problem	The job deadline (lease minus 10 s) only reached the storage calls. probe, encodeMaster and encodeRendition took no deadline, nothing checked it between stages, and an image that took too long in the codec made the next storage put fail at once as a storage error: retry_storage with assets.storage_unavailable, which never counts toward the five processing errors, so a slow image was retried until its staging object expired (assets.upload_missing)
Between stages	application/processing/: verifyAndMaster checks the deadline after the staging read and after probe; deriveRenditions checks it before each rendition; ProcessUploadHandler checks it once more after the last rendition, before the first put. A check that finds the deadline gone throws JobDeadlineExceededError, so no rendition is encoded and no object is written after it
Running codec work	The codec port takes the deadline instant: encodeMaster(bytes, deadlineAt) and encodeRendition(master, geometry, deadlineAt). SharpImageCodec sets sharp's timeout({ seconds }) on both pipelines with pipelineTimeoutSeconds: the time left rounded up to whole seconds, at least 1 (0 would switch the timeout off) and at most 3,600 (sharp's maximum). sharp 0.35.5 implements it in libvips' progress callback (src/common.cc, VipsProgressCallBack): once the pipeline has run that many whole seconds it is killed and rejects with timeout: N% complete, which the codec turns into ImageCodecTimeoutError (never ImageDecodeFailedError, which would fail the image for good as corrupt). Because the seconds are rounded up, the pipeline never stops before the deadline; it can run up to one second past it. The clock starts when libvips opens the input, so time spent waiting for a libuv thread is not counted, and probe (metadata(), a header read) has no timeout
Not built	A codec in a worker_threads worker or a child process that could be killed at any instant: it would cost a redesign of the media-worker (memory accounting, crash handling) for one second of precision. The between-stage checks and sharp's timeout bound a job to its deadline plus about one second
Classification	failure-classifier.ts, in this order: a permanent refusal stays permanent; JobDeadlineExceededError or ImageCodecTimeoutError is retry_processing with assets.job_deadline_exceeded; the storage errors keep their classes (a storage request that stalled until the deadline is still retry_storage, because the time went to the network); then, when the job's deadline signal has fired, any other failure (an image error raised while the pipeline was killed) is retry_processing with assets.job_deadline_exceeded instead of assets.image_corrupt. The loop passes the deadline signal to the classifier. retry_processing counts toward the five processing errors, waits 5 s, 30 s, 2 min then 10 min, and the fifth dead-letters the job like any processing failure
Proof	process-upload.deadline.spec.ts: the deadline instant reaches the master and the four renditions; a deadline that expires during the staging read, the probe, the master, the second rendition and the last rendition stops at that stage, writes no object and is answered retry_processing assets.job_deadline_exceeded; a storage outage within the deadline is still retry_storage assets.storage_unavailable. failure-classifier.spec.ts (six deadline titles), image-job-loop.deadline.spec.ts (records an image failure raised after the deadline expired as the deadline, counted as a processing error), sharp-image-codec.spec.ts (the timeout message and pipelineTimeoutSeconds), process-upload.handler.spec.ts (counts a job that ran out of its deadline as a processing error: it retries at three earlier errors and dead-letters at four), and sharp-image-codec.timeout.integration-spec.ts (integration suite, no storage needed, kept out of npm test for its memory): a real 6,300 by 6,300 PNG with an alpha channel, the heaviest master input accepted (about 3.7 s to encode on the development machine), is stopped by the timeout after about 1 s with a deadline 1 ms away and rejects with ImageCodecTimeoutError; it tries up to three fresh images and fails loudly, with the measured times, if none is stopped. The test pinned before, fails the next put fast as a storage retry when the deadline expires during codec work, was replaced: it recorded the defect
Mutations	Each fails a named title: the check before each rendition removed (the master and second-rendition titles); the checks of verifyAndMaster removed (the read and probe titles); the check before the first put removed (the last-rendition title); the deadline errors not mapped (the two classifier deadline titles); the deadline signal ignored (the classifier image-failure title and the loop title); the loop not passing the signal (the loop title); sharp's timeout not set (the real-image timeout title, which then reports three encodings of about 3.7 s); the deadline answered as retry_storage (the dead-letter title)

Upload limits in the contract as built (no migration)

Piece	As built
Problem	The OpenAPI description of POST /assets/uploads stated only the 10 MiB limit. The format list, the side limits (64 to 12,000 pixels) and the pixel limits (40 megapixels, 12 for AVIF) were nowhere in the contract, and a client learnt about them only when the asset ended failed later
Derived text	presentation/controllers/upload-limits-documentation.ts builds the text from the domain constants (ACCEPTED_IMAGE_MEDIA_TYPE and MAX_UPLOAD_BYTES in domain/media-type.ts, IMAGE_LIMIT, maxInputPixelsOf and MASTER_ENCODING in domain/image-limits.ts), grouping the formats that share a pixel limit; no number is typed twice
Where the client reads it	The operation description of POST /assets/uploads (the limits, that the dimensions are checked only after completion by the media worker, that the asset then moves to failed with failureCode assets.image_too_large or assets.image_too_small, that GET /assets/{assetId} shows it, and that the client must check the format and dimensions and scale down before uploading, the master being at most 4,096 pixels on its longer side); the mediaType and byteSize descriptions of the request body; the completion route's description; and a new failureCode description on every asset schema
OpenAPI	npm run openapi:compat against origin/staging: no breaking change (descriptions only), so OPENAPI_DOCUMENT_VERSION stays 9.0.0
Proof	upload-limits-documentation.spec.ts: the media type list, the size and the side and pixel limits exactly as derived, and the asynchronous refusal text. Mutation: IMAGE_LIMIT.MAX_SIDE changed to 12,001 fails states the side and pixel limits from the domain, grouping the formats that share a pixel limit

Behaviours product should know (A5 findings, no change)

Behaviour	As built	Evidence
The original variant is not the uploaded file	It is the master: the upload re-encoded as WebP q90, fitted inside 4,096 pixels, without metadata, kept in the private S3 bucket (m/<token>, private, no-store). The uploaded bytes are deleted from the staging prefix once the job settles; no untouched copy is kept, so a product feature that promises "download the original" can only offer this master	ProcessUploadHandler.handle (ORIGINAL_VARIANT_CODE with image/webp and masterKey), afterRecord (staging delete)
Archived assets stay displayable but cannot be newly linked	Archiving changes neither the status nor the delivery (§6.6): an item already linked keeps its image in the till and the catalog. A new link of an archived asset is refused with the reason archived	AssetUsageContract (ATTACHMENT_REFUSAL.ARCHIVED), asset-delivery.repository.integration-spec.ts (an archived ready public asset is still delivered)
The storage quota counts every stored variant, and processing may pass the plan cap	Admission checks stored + reserved + declared upload bytes against assets.stored_megabytes. When the job is ready, assets.record_processing_outcome (introduced by migration 0088, current text database/canonical/0070_assets.sql around line 2064) releases the reservation and adds the bytes of all variants (the private master and the four public renditions) to stored_bytes without checking the cap again; the reconciliation (reconcile_usage_batch, 0089) recomputes the same sum. An organization near its cap can therefore end slightly over it; the next upload is then refused	0070_assets.sql lines 1497 and 2064-2068
Proposal for the cap	Do not refuse at processing time: the upload was admitted, the work is done, and failing a finished image would only waste it. The overshoot is bounded by the open uploads (at most 20) times the derived bytes of one image (a master of at most 4,096 pixels and four small renditions, a few MB). If product wants no overshoot, reserve an estimate of the derived bytes at admission instead of the declared upload size; that is an SQL change for a later stage	—
Renditions are public by design	The four renditions are served from the public R2 bucket through the CDN (public, max-age=31536000, immutable) under an unguessable delivery token: anyone with the URL can fetch them, and a purge removes them from the CDN by URL. They are not private; only the master is	OD2, RENDITION_CACHE_CONTROL in process-upload.handler.ts
Images only	Assets stores images (JPEG, PNG, WebP, AVIF in; WebP out). Private documents (A7) and AI-generated images (A8) are blocked until the personal-data policy is published (OD15, OD19)	§14.2, ASSETS_STAGE_SPECS.md §27

14.2 Plan completeness checklist

The single readiness table (stage, PRs, READY or blocked, by what) is ASSETS_STAGE_SPECS.md §27. In short: every stage is specified; A0 is ready (OD1 and OD13 confirmed); A7 and the A8 stages are blocked until the personal-data policy is published (OD15; A7 also needs the owner to confirm which private files will be stored, and A8 the approved AI-label wording, OD19); the spikes and gates are A0's smoke test (storage bound, HEAD 404/403, R2 enabled, SES after the key swap, latency), A2a-2's storage contract (S3 and R2), A3c's memory gate and A6's perf:http gate.

15. Owner decisions

Owner answers of 2026-10-06: OD1 (option D) and OD13 (media.ninaku.io, media-staging.ninaku.io) are confirmed, OD12 is answered, OD15 is owner-reported with conditions (the personal-data policy is being drafted by counsel). Still open: the publication of that policy (gates A7 and A8 in production) and OD23 (the erasure trigger path, defined with the policy). OD12 is answered; every other row keeps its recommended value unless the owner objects, so "yes, use the recommended values" closes them. Rows marked (changed) differ from the previous version of this document (owner clarification of 2026-10-06: AWS S3 and SES already in use, Cloudflare in front, OpenAI GPT Image to be used); (new) rows did not exist.

#	Needed before	Decision	Options and consequences	Recommended
OD1 (answered 2026-10-06: confirmed D)	A0	Storage, CDN and region	(A) S3 + Cloudflare in front: Cloud Connector needs a public bucket (S23), a private bucket needs a signing Worker billed per request (≈ $129/month at platform scale). (B) S3 + CloudFront OAC, DNS-only in Cloudflare (≈ $916/month at platform scale, South American egress). (C) R2 only (≈ $30, the cheapest, but no storage-side upload size bound and no S3). (D) S3 for uploads, masters and private renditions + R2 for public renditions behind Cloudflare (≈ $46, plus S3 egress on master re-reads: ≈ $126 once per platform-wide regeneration)	(D): not the cheapest; chosen because the owner wants S3 and only S3 bounds the upload size with a POST policy. S3 in the owner's existing AWS account, region us-east-1, one bucket per environment with in/, m/, p/ prefixes and per-principal IAM; R2 public bucket per environment, location hint enam. Fallbacks without R2: (A), or (B) for AWS-only delivery. Each stage specification states its plan B delta: only the public-rendition write path, the delivery host and the purge call differ (ASSETS_STAGE_SPECS.md §1.7). Owner answer: option D confirmed (S3 private + R2 public + Cloudflare CDN); plan B stays documented only as a fallback
OD2 (changed)	A2b	Default delivery for product images	(a) Public immutable URLs on the R2 custom domain behind Cloudflare, unguessable tokens, automatic Cloudflare purge-by-URL on erasure. (b) Signed URLs: breaks till ETags and offline caching. (c) WAF HMAC tokens: needs a Cloudflare Pro plan and still expires	(a); private/sensitive signed from S3 p/ (A7)
OD3	A3b	Accepted inputs and output formats	(a) JPEG, PNG, WebP, AVIF in; WebP renditions (profile 1 of §5.5). (b) Also GIF/HEIC: HEIC needs a custom libvips build. (c) AVIF output now: slower encodes	(a); HEIC converted by the client
OD4	A2b	SVG	(a) Forbid. (b) Sanitize: a whole sanitizer to maintain for XSS/XXE	(a) Forbid
OD5 (changed)	A2b, A3b	Maximum upload size, pixels and policy lifetime	5, 10 or 20 MiB; 40 or 50 MP; POST policy 5 or 10 minutes	10 MiB, enforced by S3's content-length-range (no gate needed); 40 MP for JPEG, PNG and WebP and 12 MP for AVIF (owner decision after measuring locally that a 12 MP AVIF alone peaks at 572 MB RSS and a 40 MP AVIF at 1,173 MB, against about 372 MB for JPEG and PNG at 40 MP, WebP not measured yet; media-worker memory 1,536 MiB in .railway/railway.ts, the re-measurement on Railway's Linux still pending); minimum 64 px; policy valid 10 minutes
OD6	A1b	Plan: capability and limits for Pionero	(a) Included with 5,000 assets and 10,240 MiB. (b) Unlimited (like the catalog, catalog OD6). (c) Paid add-on	(a): storage is cheap but unbounded uploads are an abuse vector; limits are overridable per organization
OD7	A1a	Processing queue	(a) Module-owned assets.processing_jobs with organization_id and the shape of events.outbox_records: jobs are work items per asset (attempts, leases, kinds), not integration events other modules consume; the Identity OB2 precedent (no organization_id) does not apply, so the departure from AGENTS.md §5.4 is recorded as D31 and §5.4 is amended in A1a. (b) events.outbox_records + domain event assets.upload_completed: matches §5.4 literally but needs event types, contract versions and a JSONB payload for an internal job	(a), with D31 and the §5.4 amendment in the same PR
OD8	A4b	Archive and retention	Restore window and purge delay	Restorable 30 days; purge unreferenced archived assets after 30 days, failed after 7
OD9 (changed)	A8a	AI-generated images	(a) Build the full design of §6.7 (generate and enhance, server-built prompts, monthly quota, mandatory human approval, disclosure) after the first delivery. (b) Hook only. (c) Build now	(a), after OD15 and OD17
OD10	A3b	Malware scanning for images	(a) Out of scope with documented residual risk (decode and re-encode everything). (b) Add a scanner service now	(a); mandatory for documents
OD11	A1b	Who uploads	(a) Owner and organization-wide managers. (b) Also business-unit managers	(a), as catalog OD3
OD12 (answered 2026-10-06)	A0	Accounts, billing, cost ceilings and alerts for AWS, Cloudflare and OpenAI	Who owns each account and pays; ceilings and alerts	The company account owner holds all three (§13.2); AWS Budgets on the whole account at 50/80/100% of $50/month and an S3-filtered budget; Cloudflare billing and R2 usage notifications (100 GB per environment); OpenAI project hard limits ($20 staging, $200 production) with a 50% alert; revisited with real usage. Owner answer: the owner, a single person, owns the AWS, Cloudflare and OpenAI accounts and the domains; billing, MFA, alerts and key rotation are theirs (ASSETS_INFRASTRUCTURE_RUNBOOK.md §0.3, §7, §11.1)
OD13 (answered 2026-10-06)	A0	The media domain	The domain the platform really serves is ninaku.io: api-staging.ninaku.io serves live traffic and api.ninaku.io is reserved (docs/operations/RAILWAY_OPERATIONS.md, "Custom domains"), the docs are docs.ninaku.io and docs-staging.ninaku.io (.railway/railway.ts:24-27), problem types use https://api.ninaku.io/problems/… (FOUNDATION_HTTP_AND_OBSERVABILITY.md §5), and its DNS is on Cloudflare (RAILWAY_OPERATIONS.md:102). ninaku.com appears only in test fixtures (src/main.spec.ts:53, environment-variables.schema.spec.ts:678) and ninaku.app only as an example in AWS_SES_CREDENTIALS.md	media.ninaku.io (production) and media-staging.ninaku.io (staging): same registrable domain as the API and the docs (one zone, one Cloudflare account, which R2 custom domains require, and no new domain to buy or verify; cookies are not involved because the API uses bearer tokens); a host of its own, never the API host, so cache and transform rules apply only to images and the API's Cache-Control rules never mix with immutable images. Owner answer: confirmed media.ninaku.io (production) and media-staging.ninaku.io (staging)
OD14	A0, A3a	Where images are processed	(a) A separate Railway service media-worker (same image, own entrypoint, own memory budget). (b) Share the existing worker that delivers OTP codes and invitations: an image out-of-memory crash delays security messages	(a)
OD15 (owner-reported 2026-10-06; policy being drafted by counsel)	A7, A8a	Data residency and legal sign-off	Counsel confirms (a) private or sensitive files in S3 us-east-1, and (b) sending tenant product data (names, descriptions, photos) to OpenAI under its data controls (S35)	Required before A7 and A8; both stay blocked until answered. Public product images proceed. Owner report (not a verified legal opinion): the owner's lawyer is drafting the personal-data policy; it includes OpenAI as a data processor and lets data subjects request deletion of their data; the owner considers product data not sensitive and sees no legal issue. Conditions: the published policy must name S3 us-east-1 storage and OpenAI; A8 does not reach production before that policy is published and the owner approves the AI-label wording (OD19); A7 stays gated until the same policy is published and the owner confirms which private files will be stored
OD16	A5b	Image writes bump the till version	(a) Accept: every image command is a catalog command and forces one full till re-read per organization; add the bulk command AC5 for wizards and imports. (b) A separate image version for the till: a second version row, a second lock, a second ETag component	(a) with AC5
OD17 (new)	A8a	AI provider, model and OpenAI account	Provider; model as configuration: gpt-image-1.5 (published per-image price, medium $0.034; OpenAI calls it its previous model), gpt-image-2 and the gpt-image-2.5 variants (current, token-priced), gpt-image-1-mini (medium $0.011); who owns the OpenAI organization, billing and its verification (S30)	OpenAI; start with gpt-image-1.5 medium 1024×1024 for its known price while A8a compares it against the 2.5 models (all ZDR-eligible, S35) and switches the configuration if better; the company account owner verifies the organization and owns one project per environment
OD18 (new)	A8a	Monthly generation limits per plan and the price model	Free allowance only; allowance plus paid credits; no AI in Pionero	Pionero: 20 generations per organization per month (≈ $0.68 at the recommended model); no paid credits in v1; higher allowances belong to future plans
OD19 (new)	A8d	Disclosure of AI-generated images	(a) A label on every customer-facing surface (storefront, digital menu, receipts with images), not switchable off in v1. (b) Configurable per organization. (c) No label	(a) "Imagen ilustrativa generada con IA" shown with every aiGenerated image to customers; the till (staff-facing) shows a small marker; switchable later only with legal advice
OD20 (new)	A8a	Do AI-generated assets count toward the asset and storage limits?	(a) Yes, as normal assets, checked at request time and again at creation (soft by one asset when OpenAI was already paid). (b) A separate AI-image allowance	(a)
OD21 (new)	A3c	How dead-lettered processing jobs are recovered	(a) Runbook query calling assets.requeue_dead_letters with the migrator's credentials, no route in v1. (b) A staff route in Platform with step-up (OX-O2 shape) now	(a); (b) when the staff console needs it
OD22 (new)	A0	Cloudflare R2 enablement	The owner confirms R2 is enabled on the Cloudflare account (a payment method may be required, unverified) and that the media zone lives in the same account	Confirm before step 5 of §13.7
OD23 (new, open until the policy exists)	A4b, policy publication	Data-subject erasure	A data subject's erasure request under the personal-data policy (OD15)	It triggers the purge of that subject's assets through the existing path (archive → purge, AS10, with the automatic CDN purge); the trigger path (who receives the request, how the subject's assets are identified, the staff or owner action that archives them and skips the 30-day wait) is defined when the policy exists

---

16. Risks and what the existing SQL gets wrong or leaves open

#	Finding	Evidence	Recommendation
R1	Runtime and worker cannot reach assets	runtime_grants.sql:36, :177-181	A1a–A1c grants, with negative contract tests
R2	No asset-level status, so readiness needs a three-table join	0070:84-133	SG1–SG3
R3	Header still names BullMQ	0070:25	X1: D26 wins; D31 records the module-owned queue
R4	catalog.item_assets writes would not invalidate the till 304	0075_catalog_foundations.sql:60-112	SG11
R5	item_assets FK checks tenant only, not readiness or access class	0080:660-668	assertAttachable under FOR SHARE (AS13) and the invariant of §2.4
R6	Default access_class = 'private' vs public product images	0070:91	Explicit accessClass in AS1, public only until A7, immutable (SG17)
R7	Upload size must be bounded at the storage layer	R2 has no POST policy (S2); S3 has content-length-range (S11)	Uploads go to S3 with a POST policy (§6.2); verified again in AS7; reserve quota; staging cleanup on every outcome; in/ lifecycle
R8	Log redaction misses X-Amz-Signature	redaction.ts:27-33, sensitive-field-names.ts:1-14	SEC-1 in A2a
R9	Decoder vulnerabilities in libvips	§11	Keep sharp updated; isolated media-worker with least privilege
R10	Media worker single replica; bulk imports take hours	§12.4	Scale replicas; SKIP LOCKED is safe
R11	Purging storage objects of a ready variant breaks the deferred triggers	0070:657-672, :883-949	SG16: purging status, storage rows deleted with variants and asset in one transaction (§6.8)
R12	A consumer that attaches without assertAttachable defeats erasure	§2.4 invariant	Test per consumer slice; purge_asset_finish detects it, keeps purging and alerts
R13	audit.export_artifacts accepts only sensitive assets	0380_audit.sql:2148-2152	Consistent with A7; nothing to change
R14	ASSETS_PUBLIC_BASE_URL change silently alters URLs	§6.4	Delivery fingerprint in ETags
R15	Public objects are cached with immutable for a year	§6.4	Automatic CDN purge in AS10; device caches are an accepted residual
R16	Every image write forces a full till re-read	§6.6	AC5 bulk command (OD16)
R17	Keys carry no organization prefix	§5.2	Database-driven offboarding purge
R18	An S3 client built without explicit credentials would use the SES key	AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY are the SES variables (environment-variables.schema.ts:213-216) and the SDK's default chain reads them	Explicit credentials in every Assets client, asserted by a unit test (A2a); the SES principal has no S3 permission (A0)
R19	AI generation cost grows with use	§13.8	Per-plan monthly limit (OD18), OpenAI project hard limit (S37), quota released on failures
R20	AI food images may mislead customers	§6.7	Mandatory human approval and the disclosure label (OD19)
R21	Prompt text is tenant data sent to a third party	§6.7	OD15 sign-off; ZDR if eligible (S35); prompt never logged; prompt text nulled after 90 days
R22	Third-party outages	§13.9	Degradation per provider as registered in §13.9

What this document could not verify: the exact cache-hit ratio, object sizes and upload volume behind the cost table of §6.1; Railway's egress pricing for the worker's writes; real image sizes, processing times and peak memory on Railway (A3c); Railway's base image libc (glibc assumed, which decides sharp's default concurrency, S15); whether iOS Safari transcodes HEIC on upload; legal residency requirements in Colombia and Ecuador (OD15); which product domain is on Cloudflare (OD13); the per-image price of gpt-image-2 and the 2.5 models (token-priced, calculator only); the text of OpenAI's usage policies (the page refused the fetch); S3 prices in sa-east-1 and real latencies from Colombia and Ecuador to us-east-1; whether the Cloudflare plan in use includes a rate-limiting rule; whether MinIO or LocalStack images are currently available for local development; the value of AWS_REGION (the SES region).

---

17. Planned case matrix

ASSETS_CASE_MATRIX.md exists since stage A2b.npm run lint:case-matrix checks every docs/reference/*_CASE_MATRIX.md it finds (tooling/repository/check-case-matrix.ts:12-13, :43-52), and a matrix that cites a planned test fails because the spec file does not exist (case-matrix-references.ts, formatBrokenReferenceFailure). So each stage adds its rows when it adds the tests that prove them; A2b and A2c added AS1, AS2 and AS3.

The single source of the proving test titles of built cases is ASSETS_CASE_MATRIX.md, which npm run lint:case-matrix checks against the spec files; ASSETS_STAGE_SPECS.md keeps the titles each stage planned. An earlier copy of the titles here drifted and was removed; in particular the expiry of abandoned uploads (AS9) is proven by src/modules/assets/infrastructure/worker/expire-uploads.job.spec.ts, test/integration/assets-processing.integration-spec.ts and the A1c contracts, and the HEAD on a missing key is not a test with a fixed answer but the A0 smoke test and A2a-2's assets:storage-contract, which record 404 or 403 (either is accepted).

---

18. Sources

Verified on 2026-10-06 unless marked.

#	Source	Used for
S1	Cloudflare R2 pricing — https://developers.cloudflare.com/r2/pricing/	Storage $0.015/GB-month, Class A $4.50/M, Class B $0.36/M, free egress, free tier
S2	Cloudflare R2 presigned URLs — https://developers.cloudflare.com/r2/api/s3/presigned-urls/	GET/HEAD/PUT/DELETE only, no POST; 1 s–7 days; Content-Type in the signature; not on custom domains
R2-PB	Cloudflare R2 public buckets — https://developers.cloudflare.com/r2/buckets/public-buckets/	Custom domain with Cloudflare cache and WAF; r2.dev rate-limited, non-production
S4	Cloudflare R2 object lifecycles — https://developers.cloudflare.com/r2/buckets/object-lifecycles/	Delete by age/prefix, abort multipart, applied within ~24 h
S5	Cloudflare R2 data location — https://developers.cloudflare.com/r2/reference/data-location/	Location hints (enam, …), jurisdictions eu, fedramp, us; immutable after creation
S6	sharp output options — https://sharp.pixelplumbing.com/api-output	Metadata removed by default, sRGB conversion, WebP q80 / AVIF q50 defaults
S7	sharp constructor — https://sharp.pixelplumbing.com/api-constructor	limitInputPixels default 268,402,689, failOn default warning, autoOrient default false, animated, input formats
S8	sharp installation — https://sharp.pixelplumbing.com/install	Prebuilt platforms, Node ≥ 20.9, formats of prebuilt binaries (no HEIC)
S9	OWASP File Upload Cheat Sheet — https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html	Allow-lists, untrusted Content-Type, signatures, generated names, size limits, separate storage, scanning/CDR, SVG/XML, CSRF
S10	Amazon S3 pricing — https://aws.amazon.com/s3/pricing/	$0.023/GB-month, PUT $0.005/1k, GET $0.0004/1k, egress $0.09/GB after 100 GB
S11	Amazon S3 POST policy — https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-HTTPPOSTConstructPolicy.html	POST policy expiration and conditions; content-length-range ("The minimum and maximum allowable size for the uploaded content"); exact and starts-with matching for key and Content-Type (fetched as https://docs.aws.amazon.com/AmazonS3/latest/developerguide/sigv4-HTTPPOSTConstructPolicy.md)
S12	Railway Storage Buckets — https://docs.railway.com/storage-buckets and https://docs.railway.com/storage-buckets/billing	Private only, presigned URLs, no lifecycle/versioning/SSE, $0.015/GB-month, free operations and egress
S13	Railway public networking limits — https://docs.railway.com/networking/public-networking/specs-and-limits	15 min with data flowing, 5 min idle, uploads within 5 minutes, 32 KB headers
S14	Cloudflare R2 S3 API compatibility — https://developers.cloudflare.com/r2/api/s3/api/	PutObject supports Content-MD5 and conditional headers; x-amz-checksum-* not implemented; PostObject absent; lifecycle and CORS implemented
S15	sharp utilities — https://sharp.pixelplumbing.com/api-utility	concurrency default (1 on glibc without jemalloc), cache defaults 50 MB/20 files/100 items
S16	Express body-parser — https://expressjs.com/en/resources/middleware/body-parser.html	JSON/raw limit default 100kb
S17	Cloudflare WAF token authentication — https://developers.cloudflare.com/waf/custom-rules/use-cases/configure-token-authentication/	HMAC tokens need Pro, Business or Enterprise
S18	Cloudflare R2 limits — https://developers.cloudflare.com/r2/platform/limits/	5 GiB single PUT, 1,024-byte keys, 1 write/s per key
S19	RFC 8246 (HTTP Immutable Responses) — https://www.rfc-editor.org/rfc/rfc8246	Cache-Control: immutable (not fetched in this task; standard reference)
S20	RFC 9110 (HTTP Semantics, conditional requests §13) — https://www.rfc-editor.org/rfc/rfc9110	Strong/weak ETag comparison already applied by conditional-request.ts (not fetched in this task; standard reference)
S21	Cloudflare R2 API tokens — https://developers.cloudflare.com/r2/api/tokens/	Object Read & Write and Object Read tokens can be scoped to a set of buckets, not to prefixes
S22	Cloudflare purge cache — https://developers.cloudflare.com/cache/how-to/purge-cache/ (and the single-file page https://developers.cloudflare.com/cache/how-to/purge-cache/purge-by-single-file/)	Purge by URL: Free plan 800 URLs/s and 100 URLs per call (Pro and Business 1,500/s); purge by tag, prefix and hostname exist on every plan (Free: 5 requests per minute)
S23	Cloudflare Cloud Connector — https://developers.cloudflare.com/rules/cloud-connector/	Routes traffic to AWS and others on all plans; "Your object storage bucket must be publicly accessible"; does not configure caching
S24	Cloudflare Workers pricing — https://developers.cloudflare.com/workers/platform/pricing/	Free 100,000 requests/day; Paid $5/month minimum, 10 M requests, $0.30/M after; Workers run before the cache and cached requests are billed
S25	Amazon CloudFront pricing — https://aws.amazon.com/cloudfront/pricing/ and https://aws.amazon.com/cloudfront/pricing/pay-as-you-go/	Free tier 1 TB and 10 M requests/month; US $0.085/GB, South America $0.110/GB; HTTPS $0.0100 (US) and $0.0220 (South America) per 10k; origin fetches from AWS origins free; flat plans Free $0, Pro $15, Business $200, Premium $1,000
S26	Amazon S3, uploading objects with presigned URLs — https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html	A presigned upload is limited by the signer's permissions; same key replaces the object; SDK presigned URLs up to 7 days
S27	Amazon S3 default encryption — https://docs.aws.amazon.com/AmazonS3/latest/userguide/default-bucket-encryption.html	SSE-S3 on every new object since 2023-01-05 at no cost; SSE-KMS subject to KMS charges and quotas; Bucket Keys
S28	Amazon S3 Object Ownership — https://docs.aws.amazon.com/AmazonS3/latest/userguide/about-object-ownership.html	"Bucket owner enforced" with ACLs disabled is the default for new buckets
S29	Amazon S3 lifecycle configuration elements — https://docs.aws.amazon.com/AmazonS3/latest/userguide/intro-lifecycle-rules.html	Filters by key prefix, tags and size; Expiration; AbortIncompleteMultipartUpload; up to 1,000 rules per bucket
S30	OpenAI image generation guide — https://developers.openai.com/api/docs/guides/image-generation	Models, endpoints, sizes, quality, output formats, transparency, moderation auto/low, organization verification, "up to 2 minutes"
S31	OpenAI pricing — https://developers.openai.com/api/docs/pricing	GPT Image model list; token prices (gpt-image-2 image output $30/1M, gpt-image-1 $40/1M); calculator for per-image cost
S32	OpenAI gpt-image-1-mini — https://developers.openai.com/api/docs/models/gpt-image-1-mini	Per-image prices by quality and size; 20/150/250 images per minute by tier
S33	OpenAI gpt-image-1.5 — https://developers.openai.com/api/docs/models/gpt-image-1.5	Per-image prices ($0.034 medium 1024×1024); snapshot gpt-image-1.5-2025-12-16
S34	OpenAI gpt-image-2 — https://developers.openai.com/api/docs/models/gpt-image-2	Endpoints (generations, edits, batch), inpainting, snapshot gpt-image-2-2026-04-21, 20/150/250 IPM
S35	OpenAI data controls — https://developers.openai.com/api/docs/guides/your-data	No training by default; 30-day abuse-monitoring logs; ZDR eligibility of image endpoints for some models; CSAM exception
S36	OpenAI C2PA and SynthID — https://help.openai.com/en/articles/8912793 (search snippet only), with secondary coverage (TNW; https://openai.com/index/advancing-content-provenance)	API images carry C2PA metadata and a SynthID watermark: secondary sources, primary page not fetched
S37	OpenAI spend limits — https://developers.openai.com/api/docs/guides/spend-limits	Organization and project monthly limits, alerts or enforced hard limits returning 429
S38	Expo ImagePicker — https://docs.expo.dev/versions/latest/sdk/imagepicker/	preferredAssetRepresentationMode (automatic, compatible, current), quality, mimeType, fileSize, exif
S39	Expo ImageManipulator — https://docs.expo.dev/versions/latest/sdk/imagemanipulator/	Resize and save as JPEG, PNG or WebP with compression
S40	sharp and HEIF — https://github.com/lovell/sharp/issues/3346 and https://github.com/strukturag/libheif/blob/master/README.md	Prebuilt binaries exclude patent-encumbered HEVC; HEIC needs a custom libvips with libheif/libde265 (search results of these pages; not fetched in full)
S41	OpenAI usage policies — https://openai.com/policies/usage-policies/	Not fetched (403); not quoted
S42	Cloudflare Workers VPC, private S3 bucket example — https://developers.cloudflare.com/workers-vpc/examples/private-s3-bucket/	The documented way for a Worker to reach a private S3-compatible origin (search result; not fetched in full)

Verified facts vs assumptions. Every price, limit and default above comes from S1, S2, R2-PB, S4–S18 and S21–S39 as fetched; S40 and S42 are search results, S41 was not readable. Image sizes per rendition, processing times, worker memory, upload volume, Railway egress, iOS upload format and legal residency are assumptions, each named where used and assigned to the slice that measures or confirms it.

---

19. Glossary

Term	Meaning here
Asset	One logical file of an organization (assets.assets); referenced by id from business domains; never changes content
Master	The original variant: the sanitized, re-encoded, metadata-free copy kept privately for regeneration
Rendition	A derived variant of a profile (p1-tile, …), immutable once ready
Rendition profile	The set of rendition codes an asset has; a ready asset has all of its profile
Upload intent	The assets.uploads row and its S3 presigned POST policy, valid 10 minutes
Staging object	The raw uploaded bytes at in/<token> in the S3 bucket; never a variant, never served, deleted on every terminal outcome
POST policy	The signed S3 form policy of an upload: exact key, exact content type, size range, expiry
Generation request	An assets.generation_requests row: one AI image asked for, its provenance, its review state
Purging	The terminal asset status between the reference test and the final deletion; nothing can attach or restore it
Media worker	The media-worker Railway service that processes images, separate from the worker that sends security messages
Image reference	imageRef, <delivery token>/p<profile>, which the till combines with one URL template
Delivery token	The random 128-bit identifier in a public URL path
Delivery fingerprint	A short hash of the delivery configuration added to ETags of reads that embed URLs
Access class	public (CDN URL), private (signed short URL), sensitive (signed, audited, shortest TTL)
Attachable	Same organization, ready, not archived, of the media kind and access class the consumer requires
Purge	Physical deletion of an unreferenced archived or failed asset by the worker