@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.10

package/docs/handbook/cloudflare/deploy-and-operate.md

@@ -1,104 +1,82 @@
 ---
-description: Production checklist, the check loop, deploy and post-deploy probes, day-to-day content operations, and version pins.
+description: Install schema explicitly, migrate before deploying, and operate a native Worker.
 ---
 # Deploy and operate
 
-This page is the production checklist for a Mantle Worker on Cloudflare: what to pin and configure, which checks to run before `wrangler deploy`, how to verify a deployment, how content is operated afterwards, and how to move versions.
+Run the same generation command with `--check`, typecheck the application and test its selected routes before deploying. Keep generated TypeScript, SQL and Wrangler edits committed; keep bundle `dist/` untracked. The app owns the database, auth secrets, trusted origin and assets.
 
-## Before the first deploy
+## Public fetch routing
 
-- Pin every `@aotter/mantle*` package to one exact version and commit the lockfile. Install with `pnpm install --frozen-lockfile` (or `npm ci`) from then on. See [Project and CLI](../start/project-and-cli.md).
-- Set `PUBLIC_ORIGIN` to the real HTTPS origin, without a trailing slash. It drives canonical URLs, `.md` mirrors, `llms.txt`, the MCP resource and the OAuth callback. If a static documentation build also emits absolute URLs, give it the same value.
-- Set the production D1 `database_id` (and `account_id` if your deployment needs it) in `wrangler.jsonc`. A local `database_name` is not a production identifier, and local D1 is not production data.
-- Choose production Auth: a generated CF app uses `MANTLE_AUTH_MODE=self-managed` or `hosted` with `ADMIN_GITHUB_LOGIN` and the matching provider credentials. Local `local-otp` works only on loopback. If you author your own Worker Auth factory, replace console email delivery with a real `EmailSender`. Store secrets with `wrangler secret put`. See [Authentication](./authentication.md).
-- Keep `compatibility_flags: ["nodejs_compat", "global_fetch_strictly_public"]`.
-- Enable observability:
+Workers use `compatibility_flags: ["nodejs_compat", "global_fetch_strictly_public"]`.
+The public-fetch flag routes native `fetch` through Cloudflare's public Internet
+boundary. OAuth verification needs it to fetch JWKS on the service's own public
+hostname; CIMD also requires this boundary for client metadata. `nodejs_compat`
+alone does not establish it.
 
-```jsonc
-"observability": { "enabled": true, "logs": { "head_sampling_rate": 1 } },
-"upload_source_maps": true
-```
-
-## The check loop
+`mantle generate cloudflare-*` adds these flags without replacing other flags,
+including in environments with their own `compatibility_flags` array. The same
+command with `--check` refuses missing flags without writing. JSON/JSONC configs
+are updated; TOML receives manual-edit instructions. Keep both flags in every
+TOML environment override. An explicit `global_fetch_private_origin` is preserved
+for applications without OAuth/CIMD, but conflicts with selected OAuth/CIMD auth
+and with the public-fetch flag: generation refuses that config without rewriting
+it. Such applications must use public routing for their OAuth/CIMD transport.
 
-Run the project's `check` script before every deploy. The minimal reference chains:
+After deployment, complete a real OAuth sign-in and use the resulting bearer
+for MCP `initialize` and `tools/list`. Local development and cookie-only Admin
+checks do not verify production public-hostname routing.
 
-```sh
-mantle generate && mantle generate --check && mantle validate \
-  && mantle skills && mantle skills --check && tsc --noEmit && node smoke.mjs
-```
-
-Add tests and the frontend build where the project has them, then confirm index coverage for every public View:
+## Install and change schemas
 
-```sh
-pnpm exec mantle-harness indexes --require-public --format text
-```
+The runtime never creates, alters or checks tables. Boot and requests run no DDL, introspection or schema checks.
 
-A required path fails on a required Schema-table scan, a temporary sort or an unindexed data-field predicate. Then dry-run and deploy:
+For the first install, apply generated `schema.sql`, including selected auth/site DDL, to an empty database. Apply selected seed SQL explicitly.
 
-This local SQLite check intentionally runs without planner statistics. Treat it
-as a conservative preflight; use post-deploy D1 metrics for production cost and
-latency claims.
+For every later schema change, the application's coding agent diffs the regenerated `schema.sql`, writes a migration with the host's native tool (`wrangler d1 migrations` or the app's PostgreSQL migration tool), rehearses it on a copy, and applies it before deploying the new code.
 
-```sh
-wrangler deploy --dry-run
-wrangler deploy
-```
+Destructive changes and type changes need explicit data migration. Mantle drops nothing. Initial `schema.sql` is not an upgrade script.
 
-## Post-deploy verification
+For D1, create a migration with `pnpm exec wrangler d1 migrations create <database> <name>`, review its SQL, then rehearse `pnpm exec wrangler d1 migrations apply <database> --local` against copied data. Apply the reviewed migrations to the target before `wrangler deploy`. Initial DDL may be placed in the first migration for a new database.
 
-Probe the deployed origin, not `wrangler dev`. Run only the probes for surfaces
-the application mounts and configures:
+For PostgreSQL, use the app's migration tool and deployment credentials. Plan lock waits and long index builds there; request credentials need no DDL privileges. Configure session settings on the role/database as described in [native execution](../guides/native-execution.md#postgresql-settings). Hyperdrive query caching must be disabled for authority and mutation visibility.
 
-| Probe | Expect |
-|---|---|
-| `GET /api/views/<public-view>` | `200`, `{ "ok": true, "data": { "rows": [...] } }` |
-| `GET /<locale>/<segment>/<slug>` and `GET /<locale>/<segment>/<slug>.md` | `200` HTML and Markdown for a published entry |
-| `GET /llms.txt`, `GET /sitemap.xml`, `GET /robots.txt` | `200` |
-| `GET /<locale>/<segment>/does-not-exist` | `404` from your `notFoundRenderer` |
-| `POST /mcp/staff` without credentials | `401` with `WWW-Authenticate`; `GET /mcp` is `405` |
-| `GET /admin` | Sign-in page; sign in with the `ADMIN_GITHUB_LOGIN` account |
+## Latency placement and D1 read replication
 
-Then check the cache: a second anonymous `GET` of a public page should show `cf-cache-status: HIT`; publish a change in Admin and the next request should be a `MISS`. Sample latency with:
+Measure these options against the application's real traffic; neither is a
+default latency guarantee. [Smart Placement](https://developers.cloudflare.com/workers/configuration/placement/)
+can move fetch execution closer to observed back-end services:
 
-```sh
-pnpm exec mantle-harness http --base-url https://example.com \
-  --route recent=/api/views/recent-posts --route page=/en/posts/hello --rounds 20 --warmup 2
+```jsonc
+"placement": { "mode": "smart" }
 ```
 
-## Operating content
-
-Sign in to Admin with a staff account. Publishing collections (`lifecycle: publishing`) follow draft, publish, verify:
+For globally distributed, read-heavy D1 traffic, enable
+[read replication](https://developers.cloudflare.com/d1/best-practices/read-replication/)
+on the database and pass one request-scoped `env.DB.withSession(...)` handle to
+the selected generated Views, Procedures and Store. Those D1 entry points accept
+`D1DatabaseSession`. Without the Sessions API, queries continue to use the primary.
 
-1. Create a draft with its title, slug, locale and body.
-2. Publish (`editor` or above). The write purges the deployment-scoped public cache tag.
-3. Open the public URL and its `.md` mirror. Drafts never appear on pages, mirrors, `llms.txt` or the sitemap; use `?preview=1` with a staff session to see one.
-4. Unpublish removes the entry from every public surface; the Admin delete action and the Staff MCP `archive_entry` tool retire it.
+Use `first-unconstrained` only when a replica snapshot is acceptable,
+`first-primary` when the flow must start from the latest primary state, or carry
+a bookmark between logical sessions for sequential consistency. Reuse the same
+session within that logical flow; all writes still go to the primary. Keep fresh
+authentication/authorization checks and mutation/read-after-write paths on their
+required current-authority path rather than weakening them for replica latency.
 
-Operational collections (`lifecycle: operational`) have no publish step; records are edited in place and do not purge the public cache. The same operations are available to agents through Staff MCP; see [MCP and agents](../concepts/mcp-and-agents.md).
+## Operate
 
-Site settings split by owner. Brand, title and description seed once from `siteDefaults` and are then edited in Admin (`owner`); each edit purges the public cache. Origin, icons, locales and media purposes are code-owned and re-sync from `siteDefaults` on every boot, so change them in the Worker and redeploy. Analytics, pixels and search-engine verification are host chrome, not Core settings; see [Site chrome](./site-chrome.md) and [Site config](../reference/site-config.md).
+Enable Workers Logs and traces in production. The top-level `observability.enabled` alone does not enable traces:
 
-## Changing versions
-
-Pin every selected `@aotter/mantle*` package to one exact version and keep them together. This handbook describes the snapshot in this source tree; use the docs that ship with the version you install.
+```jsonc
+"observability": {
+  "enabled": true,
+  "logs": { "enabled": true, "head_sampling_rate": 1 },
+  "traces": { "enabled": true, "head_sampling_rate": 0.01 }
+}
+```
 
-1. Pin the new exact release for every selected package and update the lockfile through the package manager; review peer ranges.
-2. Keep application source, Worker/D1/KV identity, origins, auth mode and secrets.
-3. Run `mantle generate`, `generate --check`, `skills`, `skills --check`, `validate`, typecheck and tests.
-4. Test local routes and authorization, then deploy.
+Auth configuration and production email delivery are app-owned; follow [authentication](authentication.md). Keep secrets in the platform's secret store. With `secrets.required`, `wrangler deploy` refuses to upload while a required secret is unset: set them with `wrangler secret put` (or pass `--secrets-file` on the first deploy). Serve the selected Admin assets through the [native Admin](../guides/native-admin.md) shell contract.
 
-Each Manifest Schema is a native table. Safe additive storage changes deploy online. Destructive changes — including any `uniqueIndexes` tuple add, remove, reorder or rewrite — are rejected; rebuild the instance and move required data outside Mantle. There is no in-product data-move workflow.
+Scheduling is app-owned. Wire generated system-only TTL sweeps into `scheduled()` and configure Wrangler crons explicitly. Bound each invocation and retain a cursor if work remains; see [TTL maintenance](../guides/native-execution.md#ttl-maintenance). Expired rows remain stored and hold unique keys until removed.
 
-## Source
-- [`packages/mantle/README.md`](../../../packages/mantle/README.md)
-- [`packages/adapters/cloudflare/README.md`](../../../packages/adapters/cloudflare/README.md)
-- [`docs/direct-authoring.md`](../../../docs/direct-authoring.md)
-- [`docs/performance-harness.md`](../../../docs/performance-harness.md)
-- [`docs/examples/host-minimal-worker/README.md`](../../../docs/examples/host-minimal-worker/README.md)
-- [`docs/examples/host-minimal-worker/package.json`](../../../docs/examples/host-minimal-worker/package.json)
-- [`docs/examples/host-minimal-worker/wrangler.jsonc`](../../../docs/examples/host-minimal-worker/wrangler.jsonc)
-- [`docs/examples/host-minimal-worker/smoke.mjs`](../../../docs/examples/host-minimal-worker/smoke.mjs)
-- [`packages/mantle-spec/src/domain/model/SiteConfig.ts`](../../../packages/mantle-spec/src/domain/model/SiteConfig.ts)
-- [`packages/mantle-admin/src/mountMantleAdmin.ts`](../../../packages/mantle-admin/src/mountMantleAdmin.ts)
-- [`packages/adapters/cloudflare/src/oauth/cachePolicy.ts`](../../../packages/adapters/cloudflare/src/oauth/cachePolicy.ts)
+After deployment, verify public and protected reads, member/admin sign-in, a persisted write, stale OCC and selected MCP/Admin/web routes. An `OUTCOME_UNKNOWN` write may have committed; reconcile before deciding what to do next and never retry automatically.

package/docs/handbook/cloudflare/media-r2.md

@@ -1,216 +1,72 @@
----
-description: Enable staff media uploads on R2 — presigned PUT flow through Staff MCP, media purposes, wrangler config, commit cost and cleanup.
----
-# Media uploads with R2
+# Optional site settings and media
 
-R2-backed media is an optional post-launch capability for Workers whose staff or agents need to upload images and files. This page covers the native Cloudflare direct-to-R2 flow, the configuration it needs, how a Schema references an asset, what a commit costs, and how to clean up. For ChatGPT Sites with an R2 binding but no S3 credentials, use [the same-origin Worker flow](../chatgpt-sites/host-reference.md#media-with-only-an-r2-binding).
+Declare a TypeScript `siteDefaults` object using the 0.2 `SiteDefaults` shape and
+pass it to generation, or use `mantle generate ... --site ./site-config.ts`.
+Apply the emitted `schema.sql` to a new database; apply idempotent `site-seed.sql`
+on subsequent deployments to seed only absent operator fields. Import `site` from the generated
+`site` module; call `site(db, verifiedCaller).read()`, `.updateSettings({brand,title,
+description})`, or `.media(storage)` to access the library. Construction runs no
+queries, migrations, seeds, or storage work. The library accepts verified admin
+Callers of any credential kind; the Admin handler must additionally keep its
+cookie-session-only gate and the shared session-mutation origin check. The optional module is absent from
+a Worker that does not import it.
 
-## When to enable it
-
-Turn this on only after the site already has a working deploy, staff auth configured, and a real need for staff-managed media. R2 setup may require billing, so it is deliberately not part of the first-deploy path. Everything on this page is inert until the bucket, credentials and at least one media purpose all exist.
-
-Media maintenance also needs an agent that can read local files, process images and make outbound `PUT` requests to `*.r2.cloudflarestorage.com`. A sandboxed agent without egress cannot finish the flow.
-
-## The upload flow
-
-```txt
-1. create_media_upload   staff MCP  -> purpose, variants, mime types, byte sizes
-2. Mantle                           -> signed upload URLs + required headers
-3. agent or browser                 -> PUT bytes directly to R2
-4. commit_media_upload   staff MCP  -> validate, stamp, save the asset row
-```
-
-Bytes travel from the agent to R2 over a signed URL; the Worker sees policy, not payload. Never pass image bytes or base64 payloads through MCP tool arguments — the tool dispatchers count streamed JSON bytes and return `413` above the 1 MiB control-plane limit. The Worker validates; the agent runtime does the file work.
-
-## Cloudflare setup
-
-```sh
-wrangler r2 bucket create <project>-media
-wrangler r2 bucket dev-url enable <project>-media
-```
-
-Then create an R2 S3 API token in the dashboard: open **R2**, open **Manage R2 API Tokens**, create an **Object Read & Write** token, and copy the Access Key ID and Secret Access Key.
-
-The R2 binding alone cannot issue presigned `PUT` URLs: presigning is an S3-protocol operation, so this **direct-to-R2 adapter** needs these credentials in addition to the binding. This is not a requirement of Mantle's `MediaStorage` port: a host may return an authenticated same-origin Worker `PUT` URL instead. Media tools appear whenever `mediaStorage` and a media purpose are bound, regardless of which transport the adapter uses.
-
-## Wrangler configuration
-
-```toml
-[vars]
-R2_ACCOUNT_ID = "<account-id>"
-MEDIA_PUBLIC_URL_BASE = "https://pub-<hash>.r2.dev"
-
-[[r2_buckets]]
-binding = "MEDIA_BUCKET"
-bucket_name = "<project>-media"
-```
-
-A `wrangler.jsonc` project writes the same binding as an `"r2_buckets"` array; see [Bindings and primitives](./bindings.md#r2-media-bucket-optional) for the JSON form and the matching `Env` fields.
-
-```sh
-wrangler secret put R2_ACCESS_KEY_ID
-wrangler secret put R2_SECRET_ACCESS_KEY
-```
-
-`MEDIA_PUBLIC_URL_BASE` is the origin public URLs are built from — the `r2.dev` development URL, or a custom domain in production. `R2_ACCOUNT_ID` builds the S3 endpoint, which is a different host from the public one.
-
-## Wiring `R2MediaStorage`
-
-Build the adapter from `env`, returning `undefined` when any part is missing so a half-configured environment degrades to no media rather than failing to boot:
+Each media purpose in `siteDefaults.media.purposes` lists mime **slots** and a byte cap per full mime type:
 
 ```ts
-import { R2MediaStorage } from "@aotter/mantle/cloudflare";
-import { AwsClient } from "aws4fetch";
-
-function buildMediaStorage(env: Env) {
-  if (
-    !env.MEDIA_BUCKET ||
-    !env.R2_ACCOUNT_ID ||
-    !env.R2_ACCESS_KEY_ID ||
-    !env.R2_SECRET_ACCESS_KEY ||
-    !env.MEDIA_PUBLIC_URL_BASE
-  ) {
-    return undefined;
-  }
-
-  const s3 = new AwsClient({
-    accessKeyId: env.R2_ACCESS_KEY_ID,
-    secretAccessKey: env.R2_SECRET_ACCESS_KEY,
-    region: "auto",
-    service: "s3",
-  });
-
-  return new R2MediaStorage(
-    env.MEDIA_BUCKET,
-    s3,
-    `https://<project>-media.${env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
-    env.MEDIA_PUBLIC_URL_BASE,
-  );
-}
+{ name: "cover", required: ["image/jpeg,image/png,image/webp"], maxBytes: { "image/jpeg": 5_000_000, "image/png": 5_000_000, "image/webp": 5_000_000 } }
 ```
 
-Pass it through the `bindings` hook, spreading the conventional set:
-
-```ts
-export default createMantleWorker<Env>({
-  plan,
-  bindings: (env, conventional) => ({
-    ...conventional,
-    mediaStorage: buildMediaStorage(env),
-  }),
-});
-```
+`required` entries use `<input accept>` grammar (full mime, comma list, or a subtype shorthand such as `webp`);
+`maxBytes` must cover every mime the slots allow, keyed by the full mime type.
 
-`aws4fetch` is an application dependency; the adapter takes the signing client rather than embedding one. See [The conventional Worker](./conventional-worker.md#a-bindings-hook).
-
-## Declaring media purposes
-
-A purpose is the upload policy: which variants an asset must have, and how large each may be.
+Applications own their R2 binding, public bucket URL and S3 credentials; the SDK
+package does not manage them. Import `r2MediaStorage` from `@aotter/mantle/media/r2`:
 
 ```ts
-siteDefaults: {
-  media: {
-    purposes: [
-      {
-        name: "page-image",
-        required: ["image/jpeg,image/png", "image/webp", "image/avif"],
-        maxBytes: {
-          "image/jpeg": 5_000_000,
-          "image/png": 5_000_000,
-          "image/webp": 3_000_000,
-          "image/avif": 2_000_000,
-        },
-      },
-    ],
-  },
-},
-```
-
-`required` is slot-based, in the grammar of an `<input accept>` list. The example declares three slots: slot 0 takes exactly one fallback mime preserving source semantics (`image/jpeg` for opaque photos, `image/png` when alpha must survive), slot 1 a WebP variant, slot 2 an AVIF variant. That models a multi-variant `<picture>`. A narrower purpose may declare a single slot such as `["image/jpeg,image/png,image/webp,image/gif"]`, in which case the agent picks exactly one mime from that list and must not upload one variant per listed mime.
-
-Purpose names are slugs (`^[a-z0-9]+(-[a-z0-9]+)*$`), every slot must be non-empty, slots may not overlap on a mime, and every `maxBytes` key must be a mime some slot accepts with a positive value. Violations fail at boot. SVG uploads are rejected unless the Worker sets `mediaAllowSvg`. See [Site defaults and site_config](../reference/site-config.md).
-
-The runtime emits the policy summary into the `create_media_upload` tool description, so an agent reads the contract straight from `tools/list` without an extra round trip.
-
-## Tool visibility
-
-`create_media_upload` and `commit_media_upload` are registered only when **both** hold:
-
-- `bindings.mediaStorage` is set;
-- `siteDefaults.media.purposes` contains at least one purpose.
-
-If either is missing the tools never appear in `tools/list`. That is the intended diagnostic: an agent that cannot see the tools is looking at a deployment where media is not configured, not at a permissions problem. A call that reaches a runtime without media storage answers `MEDIA_NOT_CONFIGURED`.
-
-## Referencing an asset from a Schema
-
-Entries store asset ids, not URLs. Mark the field with both existing v0.1 grammar extensions:
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v1
-kind: Schema
-metadata:
-  name: pages
-spec:
-  title: Pages
-  schema:
-    type: object
-    additionalProperties: false
-    required: [slug, title]
-    properties:
-      slug: { type: string, pattern: "^[a-z0-9-]+$" }
-      title: { type: string, minLength: 1 }
-      coverAssetId:
-        type: string
-        x-mantle-ref: media_assets
-        x-mcp-hint: media-image
+const storage = r2MediaStorage({
+  bucket: env.MEDIA,
+  endpoint: "https://bucket.account.r2.cloudflarestorage.com",
+  publicBase: "https://media.example.com",
+  signer, // app-owned SigV4 signer: sign(url, {method:"PUT",aws:{signQuery:true,service:"s3"}})
+});
+const media = site(db, caller).media(storage);
+const upload = await media.createUpload({
+  filename: "cover.jpg", purpose: "cover",
+  variants: [{mimeType:"image/jpeg",byteSize:1234,role:"primary"}]
+});
+// Client PUTs bytes directly to upload.capabilities[i].uploadUrl,
+// with its requiredHeaders. Never send the bytes through Mantle.
+const asset = await media.commitUpload(upload.uploadGroupId);
 ```
 
-`x-mantle-ref: media_assets` marks the string as an id in the media asset collection, which is what makes Admin show a media picker instead of a text box. `x-mcp-hint: media-image` tells an MCP client the field expects an image asset. Neither key is validated as a foreign key; they are informational. At render time, resolve ids to their variants with `runtime.media.resolve(id)` or `resolveMany(ids)`, which batches a render pass into one database round trip. No new manifest keys are involved; see [Schema](../reference/schema.md).
-
-## What a commit costs
-
-R2 has no metadata-only patch. To stamp `committedAt`, `role`, `uploadGroupId` and the filename markers, Mantle streams each uploaded object through a `GET` and a `PUT`. So a successful N-variant commit performs N `GET`s and N `PUT`s and rewrites the sum of the variant sizes.
-
-- Commits validate the bundle shape before any I/O.
-- Variants are processed in batches of at most three; a batch settles before the next starts or an error returns.
-- A mime or size failure cancels the unused `GET` stream; a failed `PUT` also attempts cancellation while preserving the original error.
-- The asset row is saved only after every variant succeeds. All-or-nothing.
-
-Parallelism reduces waiting, not operation count or bytes. Keep variant counts and byte caps deliberate. A partial R2 failure leaves the pending D1 record in place so the commit can be retried before it expires; already stamped objects stay stamped.
-
-## Cleanup
-
-An upload can reach R2 and never be committed — an interrupted agent, a rejected commit. Remove those objects with the version-matched `media-gc` skill. It is opt-in and deliberately not projected into a repository by `mantle skills`, because it deletes remote objects.
-
-Its posture is audit first, delete only what an operator confirmed. It treats an object as a candidate only when it is over 24 hours old, has no `committedAt` custom metadata, and matches the exact key layout `<purpose>/<group>/(primary|alternate|fallback).<ext>` for a purpose this project declares. It reports account, bucket, prefixes, cutoff, counts, bytes and a digest of the candidate set without printing keys or URLs; on confirmation it re-runs the same audit and stops if anything changed.
-
-> **Do not use an R2 lifecycle rule**
-> Committed and uncommitted media share the same purpose prefix, so an age-based rule deletes live assets. After a pending record expires, partially stamped orphans require an operator audit against D1 references: a missing pending record does not mean an object is unused.
-
-## Diagnostics
-
-| Code | HTTP | Raised when |
-|---|---|---|
-| `MEDIA_NOT_CONFIGURED` | 501 | No `mediaStorage` port is bound on this deployment |
-| `MEDIA_PURPOSE_REJECTED` | 400 | The requested purpose is not declared; the declared set is returned so an agent can self-correct |
-| `MEDIA_MIME_REJECTED` | 400 | A mime outside `image/png`, `image/jpeg`, `image/webp`, `image/avif`, `image/gif` |
-| `MEDIA_SIZE_EXCEEDED` | 400 | A declared byte size exceeds its cap |
-| `MEDIA_SVG_REJECTED` | 400 | An SVG was offered while SVG is not allowed; object storage does not sanitize SVG payloads |
-| `MEDIA_VARIANTS_INCOMPLETE` | 400 | The bundle misses a mime the purpose requires; the missing set is returned |
-| `MEDIA_VARIANT_SIZE_EXCEEDED` | 400 | One variant exceeds the cap declared for its mime |
-| `MEDIA_VARIANTS_SUSPICIOUS_SIZE` | 400 | A modern variant is larger than its fallback (AVIF above JPEG), so it looks unoptimized |
-| `MEDIA_ASSET_NOT_FOUND` | 404 | No `media_assets` row matches the id |
-| `MEDIA_UPLOAD_EXPIRED` | 410 | The upload capability's TTL elapsed, or it was never created |
-| `MEDIA_OBJECT_NOT_FOUND` | 409 | A variant's bytes were never PUT before commit |
-
-The full catalog is in [Diagnostic codes](../reference/diagnostics.md).
-
-## Source
-- [`docs/media-uploads.md`](../../../docs/media-uploads.md)
-- [`docs/adr/0017-media-multi-variant-agent-side-optimization.md`](../../../docs/adr/0017-media-multi-variant-agent-side-optimization.md)
-- [`packages/mantle-runtime/src/domain/port/MediaStorage.ts`](../../../packages/mantle-runtime/src/domain/port/MediaStorage.ts)
-- [`packages/mantle-runtime/src/domain/port/MediaAssetRepository.ts`](../../../packages/mantle-runtime/src/domain/port/MediaAssetRepository.ts)
-- [`packages/mantle-spec/src/domain/service/SiteDefaultsValidator.ts`](../../../packages/mantle-spec/src/domain/service/SiteDefaultsValidator.ts)
-- [`packages/mantle-spec/src/kernel/diagnostic.ts`](../../../packages/mantle-spec/src/kernel/diagnostic.ts)
-- [`packages/adapters/cloudflare/README.md`](../../../packages/adapters/cloudflare/README.md)
-- [`docs/skills/media-gc/SKILL.md`](../../skills/media-gc/SKILL.md)
+An existing S3 signer (for example an application already using aws4fetch) fits
+this port. This package adds no AWS SDK. The signer must return a SigV4
+query-signed PUT URL and preserve `X-Amz-Expires`; never give its credentials to
+the client. Configure bucket CORS to allow PUT from the application's origins
+and the returned Content-Type header. Serve the `committed/` prefix on the public domain; these keys differ from 0.2's `{purpose}/{group}/{role}` keys. Keep `uploads/` private/unserved on the
+public domain and add a bucket lifecycle rule for abandoned upload keys.
+
+Commit checks every object's MIME and size, then rechecks the exact GET
+response used for the copy. Public keys cannot be reached by an upload URL. Each commit attempt has a separate
+public-key UUID, while the asset id remains the upload-group UUID. A concurrent
+loser can neither overwrite nor remove the winner's objects. After SQL selects
+the durable asset, the losing attempt removes only its own unselected copies.
+Upload sources remain until the database commit succeeds, so an uncertain DB
+write can be reconciled/retried with the same UUID. Failed object deletion keeps
+the media row; retry the same id. An upload group expires after 15 minutes. Asset `createdAt` is the upload-group creation time (epoch milliseconds), not the later commit time.
+No R2 upload or deployment is performed by generation.
+
+A positively identified native rollback deletes only that attempt's copied
+objects. Plain/network failures lack rollback evidence, retain copies, and return
+`OUTCOME_UNKNOWN`, including a lost D1 batch response.
+An uncertain native write preserves copies, because they may belong to the
+durable winning row. If SQL durability or unselected-copy cleanup returns `OUTCOME_UNKNOWN`, reconcile
+storage with the durable `media_assets.variants` keys. Attempt-isolated copies
+may remain after an uncertain outcome; never delete the winning asset's keys or
+expire all `committed/` objects indiscriminately. The group UUID remains the
+reconciliation and retry id.
+
+Admin's `media` option takes a `MediaStorage` value, so build it where `env` is available (for example once per
+Worker in the fetch handler). Uploads use presigned S3 PUT URLs: `wrangler dev --local` has an R2 binding but no S3
+endpoint, so test the upload flow against a real bucket; local tests can cover everything up to the signed URL.