{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://arvia-staging.rogerwu188.workers.dev/hosts/spec.json",
  "title": "ROAN AI host onboarding — contracts 1.24.11 resource validator / AI主播接入资源校验器",
  "description": "Validates an existing Host or Clip manifest, not an external submission envelope. The staging receive-only supply envelope is documented by x-submission-endpoint; validate a specific resource through #/$defs/host or #/$defs/clip_manifest. JSON shape validation is not media, rights, signature or publication approval. / 校验现有Host或片单；staging 只供片提交信封见 x-submission-endpoint，不代表提交即审核或上线许可。",
  "oneOf": [
    {
      "$ref": "#/$defs/host"
    },
    {
      "$ref": "#/$defs/clip_manifest"
    }
  ],
  "$defs": {
    "common": {
      "title": "Shared definitions",
      "$defs": {
        "id": {
          "type": "string",
          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
        },
        "sku": {
          "type": "string",
          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$"
        },
        "timestamp": {
          "type": "string",
          "format": "date-time"
        },
        "url": {
          "type": "string",
          "format": "uri",
          "pattern": "^https?://"
        },
        "currency": {
          "description": "Currencies ROAN sells in (US and EU market). Extend only through a contract change.",
          "type": "string",
          "enum": [
            "USD",
            "EUR",
            "GBP"
          ]
        },
        "money": {
          "description": "An amount in minor units (cents) to avoid floating point: a supplier cost or a shipping estimate, which may be 0. Prices use price, sums use money_total. Producers must serialize amount_minor as a JSON integer (see INVARIANTS.md).",
          "type": "object",
          "additionalProperties": false,
          "required": [
            "amount_minor",
            "currency"
          ],
          "properties": {
            "amount_minor": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100000000,
              "description": "At most 100,000,000 minor units (USD 1,000,000): far above any MVP price and well inside JavaScript's exact integer range (2^53), so no platform arithmetic rounds."
            },
            "currency": {
              "$ref": "#/$defs/currency"
            }
          }
        },
        "price": {
          "description": "A price in minor units: a product, variant, slots, promo, cart or order unit price, or a product card price. At least 1 minor unit: a price of 0 is a data error, not a free item (PM batch 8, N94). Producers must serialize amount_minor as a JSON integer (see INVARIANTS.md). 1.24.0: optional `unit` (price_unit; absent = each).",
          "type": "object",
          "additionalProperties": false,
          "required": [
            "amount_minor",
            "currency"
          ],
          "properties": {
            "amount_minor": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100000000,
              "description": "1 to 100,000,000 minor units (USD 1,000,000): far above any MVP price and well inside JavaScript's exact integer range (2^53), so no platform arithmetic rounds."
            },
            "currency": {
              "$ref": "#/$defs/currency"
            },
            "unit": {
              "$ref": "#/$defs/price_unit"
            }
          }
        },
        "money_total": {
          "description": "A sum of line amounts (cart subtotal, order total): like money, with a higher ceiling, so that lines that are each valid always sum to a valid total (PM batch 7, N76). 0 only for an empty cart (cart.json); an order has at least one line priced at 1 or more, so its total is at least 1 (INVARIANTS 2). Producers must serialize amount_minor as a JSON integer (see INVARIANTS.md).",
          "type": "object",
          "additionalProperties": false,
          "required": [
            "amount_minor",
            "currency"
          ],
          "properties": {
            "amount_minor": {
              "type": "integer",
              "minimum": 0,
              "maximum": 200000000000,
              "description": "At most 200,000,000,000 minor units = 100 lines (cart and order maxItems) x qty 20 (line maximum) x 100,000,000 (price maximum), still far inside JavaScript's exact integer range (2^53 = 9,007,199,254,740,992)."
            },
            "currency": {
              "$ref": "#/$defs/currency"
            }
          }
        },
        "credits": {
          "description": "Giggle credits as an exact decimal string with up to two decimals. Giggle charges fractions (\"8.5\" for a 5 s 768p H3 clip, \"2\" for a TTS call, measured 2026-10-31); the two-decimal limit rests on those two observed charges, so a charge with more decimals is a contract change request, not something to round. Compare and sum as decimals, never as strings or floats (\"8.5\" == \"8.50\"). Giggle spend only; HopsAPI (LLM) spend is in usd_decimal.",
          "type": "string",
          "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,2})?$"
        },
        "product_source": {
          "type": "string",
          "enum": [
            "csv",
            "cj",
            "shopify",
            "amazon",
            "ebay",
            "aliexpress",
            "editorial",
            "demo"
          ],
          "description": "1.22.0: ebay (eBay Browse API, engine sources/ebay.py) and aliexpress (AliExpress Open Platform DS, engine sources/aliexpress.py; a2.10-room-quality 16634e08). Both need credentials; neither has made a recorded real call yet. 1.24.0 (12-SKU plan, decisions 2026-11-06): `editorial` = copy ROAN writes itself about its own services (the platform's seed pages for its own services, web/data/ai-products.json, which used it before the contract allowed it); `demo` = an invented demo item (merchant and item made up, labelled Demo on every page; product.json requires demo.is_demo true for it). Neither is read from a supplier feed."
        },
        "arvia_category": {
          "description": "ROAN channel. 1.22.0: every category is open (Roger; platform a1b-pdp migration 0031_open_categories.sql drops rooms.category's CHECK IN ('beauty','home','womens_apparel')). Any string of 1..64 characters that is not blank: the rule of 0031's triggers rooms_category_insert/_update (length(trim(category)) > 0 AND length(category) <= 64) and of the Worker's GET /v1/catalog check (a1b-pdp 3cf7b15d src/routes/public.ts getCatalog: category.trim() !== '' and length <= 64; GET /v1/rooms takes the openapi parameter, which is this definition). `pattern` \\S = at least one non-whitespace character (ECMA-262 \\S, the set JavaScript's trim() removes, so a tab-only or newline-only value is refused as the Worker refuses it; SQLite's trim() removes only spaces, so the contract is the stricter of the two). Length counts code points, as SQLite length() does; the Worker's .length counts UTF-16 units, so a value with characters outside the BMP may be refused by the Worker below 64 code points. beauty, home and womens_apparel (set by Roger on 2026-10-31) are no longer the only values; the web keeps labels for those three and shows other categories as written. Case and surrounding spaces are kept as sent (no normalisation): 'Garden' and 'garden' are different categories.",
          "type": "string",
          "minLength": 1,
          "maxLength": 64,
          "pattern": "\\S"
        },
        "eta_days": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "min",
            "max"
          ],
          "properties": {
            "min": {
              "type": "integer",
              "minimum": 0
            },
            "max": {
              "type": "integer",
              "minimum": 0
            }
          }
        },
        "gate": {
          "description": "The eight production gates, in order. Mapping to the product definition doc (https://claude.ai/artifact/JLb5QLxfsEzeo4YkTF8N1G, diagram 生产线 8 道门): brief=立项 (setup inputs: host photo, voice, category or CSV), host_model=主播建模, product_kb=商品知识库 (pull SKUs, prices, images; score into the recommended catalog; build the knowledge base), script=脚本, generate=素材匹配与生成, qa=QA 门禁, publish=编排开播 (package, upload, register clips, playlist, go live), operate=运行与沉淀 (live answers, voiceover). The daily FAQ loop re-enters at script. Placements are a main-session interpretation recorded in docs/decisions.md.",
          "type": "string",
          "enum": [
            "brief",
            "host_model",
            "product_kb",
            "script",
            "generate",
            "qa",
            "publish",
            "operate"
          ]
        },
        "clip_kind": {
          "type": "string",
          "enum": [
            "opener",
            "pitch",
            "faq",
            "closer",
            "broll",
            "transition",
            "holiday"
          ]
        },
        "qa_check_name": {
          "type": "string",
          "enum": [
            "duration",
            "black_frames",
            "silence",
            "asr_match",
            "onscreen_text",
            "camera_motion",
            "identity",
            "host_hands_empty"
          ],
          "description": "1.24.0: host_hands_empty = the host's hands hold nothing (a product-free host clip; required of every generated answer clip, INVARIANTS 71)."
        },
        "reply_mode": {
          "type": "string",
          "enum": [
            "text",
            "faq_clip",
            "voiceover"
          ]
        },
        "is_test": {
          "description": "True for records produced by simulated viewers/customers or in test rooms. Production rooms never receive is_test=true traffic.",
          "type": "boolean"
        },
        "error": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "string",
              "minLength": 1
            },
            "message": {
              "type": "string",
              "minLength": 1
            }
          }
        },
        "usd_decimal": {
          "description": "US dollars as an exact decimal string, up to 6 decimals (LLM calls cost fractions of a cent). Sum with decimal arithmetic.",
          "type": "string",
          "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$"
        },
        "policy_version": {
          "description": "A policy bundle version: 1, 2, 3, ... in publishing order (INVARIANTS 44).",
          "type": "integer",
          "minimum": 1
        },
        "staff_role": {
          "description": "A staff member's role (A1.15, 1.16.0): viewer reads the back office, operator also changes it, owner also manages staff and policy bundles. The ADMIN_TOKEN acts as an operator and is never an owner.",
          "type": "string",
          "enum": [
            "viewer",
            "operator",
            "owner"
          ]
        },
        "staff_email": {
          "description": "A staff member's e-mail address as the platform checks it (src/staff.ts emailOk, 1.16.0): at most 254 characters, something@something.something without spaces around the @; stored and returned trimmed.",
          "type": "string",
          "maxLength": 254,
          "pattern": "^\\s*[^\\s@]+@[^\\s@]+\\.[^\\s@]+\\s*$"
        },
        "staff_password": {
          "description": "A new staff password (1.16.0): 12 to 200 characters. Never returned, logged or stored in clear (PBKDF2-SHA256).",
          "type": "string",
          "minLength": 12,
          "maxLength": 200
        },
        "calendar_day": {
          "description": "A calendar day, YYYY-MM-DD (1.16.0).",
          "type": "string",
          "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$"
        },
        "segment_role": {
          "description": "1.16.1: the role of a clip in a product's ~3-minute segment (S32, docs/design/live-segment-playbook.md), in play order. 1.17.0: the playbook's 13 role names only, no aliases (decided; the engine's segment ROLES on a2.10-room-quality 3a6c4c1c). 1.16.1 also listed `faq`, which the platform accepts (a1.12-inserts ce6e3c7e src/segments.ts) and the playbook does not name: a pre-answered FAQ clip is faq_1 or faq_2.",
          "type": "string",
          "enum": [
            "bridge_in",
            "hook",
            "scene_pain",
            "proof_demo_1",
            "cta_1",
            "angle_detail",
            "proof_demo_2",
            "objection",
            "faq_1",
            "faq_2",
            "offer",
            "cta_2",
            "bridge_out"
          ]
        },
        "host_language": {
          "description": "1.17.0 (S31, S35): the language of a room's host voice, the tag the platform stores and checks (a1.12-inserts 73db9041 migration 0024 rooms.host_language CHECK IN ('en','zh-CN'), admin.room_language.json). Two tags, not free BCP 47: `en` (US English) and `zh-CN` (Simplified Chinese); `zh` alone, `en-US` and any other tag are refused. The same two values as account.json locale.",
          "type": "string",
          "enum": [
            "en",
            "zh-CN"
          ]
        },
        "locale": {
          "description": "1.17.0 (S35): the language of the page a viewer wrote from, the tag the platform stores (a1.12-inserts 9cf4796f migration 0024 comments.locale CHECK (locale IS NULL OR locale IN ('en','zh-CN'))). The same two tags as host_language and account.json locale: `en` and `zh-CN`; `zh` alone, `en-US`, `` and any other tag are refused (the platform maps a page's ?lang=zh to zh-CN before storing and never sends anything else).",
          "type": "string",
          "enum": [
            "en",
            "zh-CN"
          ]
        },
        "dimensions_mm": {
          "description": "Length, width and height in millimetres, copied verbatim from the supplier (1.22.0; unit mm per CJ docs 1.5). No unit conversion. Each above 0. Used for the product's own size (dimensions_mm) and the shipping package's (package_dimensions_mm; CJ variantLength/Width/Height are the package, A2 f2ad3629).",
          "type": "object",
          "additionalProperties": false,
          "required": [
            "l",
            "w",
            "h"
          ],
          "properties": {
            "l": {
              "type": "number",
              "exclusiveMinimum": 0
            },
            "w": {
              "type": "number",
              "exclusiveMinimum": 0
            },
            "h": {
              "type": "number",
              "exclusiveMinimum": 0
            }
          }
        },
        "weight_g": {
          "description": "A weight in grams as the supplier states it (1.22.0); above 0.",
          "type": "number",
          "exclusiveMinimum": 0
        },
        "weight_g_range": {
          "description": "A weight in grams that the supplier gives either as one number or as a range (1.22.0; CJ packingWeight is a string such as \"100.00-4486.00\"): a number, or {min, max} with min <= max (INVARIANTS 3). Values are the source's own, not rounded.",
          "oneOf": [
            {
              "$ref": "#/$defs/weight_g"
            },
            {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "min",
                "max"
              ],
              "properties": {
                "min": {
                  "$ref": "#/$defs/weight_g"
                },
                "max": {
                  "$ref": "#/$defs/weight_g"
                }
              }
            }
          ]
        },
        "price_unit": {
          "description": "1.24.0: what one `amount_minor` buys. each = one piece or one order line (the meaning of every price without a unit, so absent = each); per_month / per_year = a subscription period (a digital plan: TwinLive US$249 per_month); per_person = one guest; per_night = one night (a booking's from-price; the payable amount is the quote's); per_package = the whole package as described; total = the full amount of a single listing (a lead_gen home's list price, indicative). Cart and order unit prices carry the unit of the product price they were taken from.",
          "type": "string",
          "enum": [
            "each",
            "per_month",
            "per_year",
            "per_person",
            "per_night",
            "per_package",
            "total"
          ]
        },
        "fulfilment_type": {
          "description": "1.24.0 (Roger 2026-11-06, final): how an item reaches the buyer. Absent = physical, so 1.23.x producers and readers keep working. physical = shipped goods (CJ and the other supplier feeds, as before). digital = software, tokens / API credits, agent subscriptions (StoryClaw TwinLive): ordered and paid here, fulfilled by the supplier's API (a license key, API key, credits top-up or account activation), shown on the order page and sent by e-mail; no shipping; refunds follow the supplier's terms. local_delivery = food takeout / delivery: the order is placed with the restaurant or delivery partner through its API; it needs a delivery address and a time window; the total may include a delivery fee. booking = travel (flights, hotels, packages): dates and party at checkout, a supplier quote held until a time before payment, the cancellation policy shown before payment, traveller names collected only at checkout (PII). lead_gen = real estate only: advertising for a merchant, never a transaction; the CTA records a lead (POST /v1/leads). Cart, buy-now and checkout refuse lead_gen with 409 not_purchasable (INVARIANTS 65).",
          "type": "string",
          "enum": [
            "physical",
            "digital",
            "local_delivery",
            "booking",
            "lead_gen"
          ]
        }
      }
    },
    "host": {
      "title": "Host",
      "description": "Body of POST /v1/hosts and the host resource.",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "host_id",
        "display_name",
        "persona",
        "reference_images",
        "voice",
        "is_default"
      ],
      "properties": {
        "host_id": {
          "$ref": "#/$defs/common/$defs/id"
        },
        "display_name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 60
        },
        "display_name_zh": {
          "description": "1.23.0 (S41, S48): the host's name for viewers whose locale is zh-CN; absent means the page shows display_name in every language.",
          "type": "string",
          "minLength": 1,
          "maxLength": 60
        },
        "persona": {
          "type": "string",
          "maxLength": 2000
        },
        "avatar_url": {
          "$ref": "#/$defs/common/$defs/url"
        },
        "reference_images": {
          "description": "Cleaned studio reference frames (9:16) used for H3 generation.",
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/common/$defs/url"
          }
        },
        "voice": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "timbre_ref_url",
            "tts_voice_id"
          ],
          "properties": {
            "timbre_ref_url": {
              "description": "Public URL of the voice sample used as H3 timbre reference.",
              "$ref": "#/$defs/common/$defs/url"
            },
            "tts_voice_id": {
              "description": "Voice used for voiceover answers: a cloned voice id if available, otherwise a preset id.",
              "type": "string",
              "minLength": 1
            },
            "tts_voice_is_clone": {
              "type": "boolean"
            },
            "provider": {
              "description": "1.23.0: which TTS service tts_voice_id and tts_voices name: giggle (Giggle text-to-audio preset or clone id), edge (an edge-tts voice name), qwen3 (a local Qwen3-TTS clone). Absent means giggle, the meaning before 1.23.0.",
              "enum": [
                "giggle",
                "edge",
                "qwen3"
              ]
            },
            "tts_voices": {
              "description": "1.23.0: the voice per answer language for providers whose voices are per language (edge: one en voice, one zh-CN voice). A language not listed uses tts_voice_id.",
              "type": "object",
              "additionalProperties": false,
              "minProperties": 1,
              "properties": {
                "en": {
                  "type": "string",
                  "minLength": 1
                },
                "zh-CN": {
                  "type": "string",
                  "minLength": 1
                }
              }
            }
          }
        },
        "is_default": {
          "type": "boolean"
        },
        "pronoun": {
          "description": "1.16.0 (A1 N237, a1.12-inserts d4e5b440): the host's pronoun for the page's sentences about the host; null (or absent) when the profile has none, and the page names the host instead. Nullable for now.",
          "enum": [
            "she",
            "he",
            "they",
            null
          ]
        },
        "identity": {
          "description": "1.23.0 (S37 per host, S48, S50): the identity reference the engine checks this host's clips against. Agent- and engine-facing; never copied into viewer_host.json. Absent: the engine falls back to its policy's qa.host_references.",
          "type": "object",
          "additionalProperties": false,
          "required": [
            "reference_url",
            "bank_version"
          ],
          "properties": {
            "reference_url": {
              "description": "The approved identity reference image of this host (S37).",
              "$ref": "#/$defs/common/$defs/url"
            },
            "bank_version": {
              "description": "Version of the host's identity bank (hosts/<host_id>/identity_bank.json) built from reference_url; 2 = bank v2.",
              "type": "integer",
              "minimum": 1
            },
            "threshold": {
              "description": "Identity score a host clip must reach against this host's bank (median); absent means the engine policy's identity.bank_median_min.",
              "type": "number",
              "minimum": 0,
              "maximum": 1
            }
          }
        },
        "consent": {
          "description": "1.23.0: the seller's attestation that they are the person shown or hold the person's permission (model release) for AI-generated video of this person in live selling, from the agent console checkbox. Not public (never in viewer_host.json).",
          "type": "object",
          "additionalProperties": false,
          "required": [
            "attested_at",
            "attested_by"
          ],
          "properties": {
            "attested_at": {
              "$ref": "#/$defs/common/$defs/timestamp"
            },
            "attested_by": {
              "description": "Who ticked the box: the console account (e-mail or account id).",
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "release_url": {
              "description": "Optional uploaded signed model release.",
              "$ref": "#/$defs/common/$defs/url"
            }
          }
        }
      }
    },
    "clip": {
      "title": "Clip manifest entry",
      "description": "One finished clip that passed every required QA check. Produced by the engine (A2), registered by the agent (A3) via PUT /v1/rooms/{room_id}/clips inside a clip_manifest, played by the platform (A1). Clips with a host on screen need all seven checks; B-roll needs duration, black_frames and onscreen_text. Production clips (is_test=false) must carry at least one real provider task. Each check name appears at most once. pitch, faq and broll clips belong to a product (product_sku not null).",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "clip_id",
        "kind",
        "host_id",
        "product_sku",
        "duration_s",
        "url",
        "width",
        "height",
        "captions",
        "qa",
        "source_tasks",
        "cost_credits",
        "created_at",
        "is_test"
      ],
      "properties": {
        "clip_id": {
          "$ref": "#/$defs/common/$defs/id"
        },
        "kind": {
          "$ref": "#/$defs/common/$defs/clip_kind"
        },
        "host_id": {
          "$ref": "#/$defs/common/$defs/id"
        },
        "product_sku": {
          "oneOf": [
            {
              "$ref": "#/$defs/common/$defs/sku"
            },
            {
              "type": "null"
            }
          ]
        },
        "duration_s": {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 120,
          "description": "Measured duration of the finished media in seconds (>0, <=120), not a provider generation request. MiniMax-H3 generation requests use 5/10/15-second bands (round requested duration upward; 3 -> 5) in the agent/engine adapter. The Worker stores this measured duration and does not select, forward or invoke a provider duration; do not restrict finished media to those generation bands."
        },
        "url": {
          "$ref": "#/$defs/common/$defs/url"
        },
        "poster_url": {
          "oneOf": [
            {
              "$ref": "#/$defs/common/$defs/url"
            },
            {
              "type": "null"
            }
          ]
        },
        "width": {
          "type": "integer",
          "minimum": 1
        },
        "height": {
          "type": "integer",
          "minimum": 1
        },
        "captions": {
          "description": "Exact spoken text after slot filling at generation time. Empty string for clips without speech.",
          "type": "string",
          "maxLength": 2000
        },
        "voice": {
          "description": "PROTO-1 (M4f): engine speech metadata; has_speech is authoritative for QA.",
          "type": "object",
          "additionalProperties": false,
          "required": [
            "has_speech"
          ],
          "properties": {
            "has_speech": {
              "type": "boolean"
            },
            "speech_rate_x": {
              "type": "number",
              "minimum": 0.5,
              "maximum": 2
            },
            "speaker": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "audio_url": {
              "$ref": "#/$defs/common/$defs/url"
            }
          }
        },
        "captions_lang": {
          "type": "string",
          "minLength": 2,
          "maxLength": 35
        },
        "ai_disclosure": {
          "type": "boolean"
        },
        "duration_class": {
          "type": "string",
          "enum": [
            "standard_90",
            "travel_120_180"
          ]
        },
        "faq_question": {
          "description": "Canonical question this clip answers. Required (non-empty) when kind is faq.",
          "type": [
            "string",
            "null"
          ],
          "maxLength": 300
        },
        "theme": {
          "description": "Holiday theme this clip belongs to, if any.",
          "type": [
            "string",
            "null"
          ],
          "maxLength": 40
        },
        "qa": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "passed",
            "report_url",
            "checks"
          ],
          "properties": {
            "passed": {
              "const": true
            },
            "report_url": {
              "$ref": "#/$defs/common/$defs/url"
            },
            "checks": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "name",
                  "passed"
                ],
                "properties": {
                  "name": {
                    "$ref": "#/$defs/common/$defs/qa_check_name"
                  },
                  "passed": {
                    "const": true,
                    "description": "A registered clip has passed every check it lists."
                  },
                  "score": {
                    "type": "number"
                  },
                  "detail": {
                    "type": "string"
                  },
                  "threshold": {
                    "type": "number",
                    "description": "Pass threshold the score was compared with. Required when score is present; passed == (score >= threshold) is an invariant."
                  }
                },
                "dependentRequired": {
                  "score": [
                    "threshold"
                  ]
                }
              },
              "allOf": [
                {
                  "contains": {
                    "type": "object",
                    "required": [
                      "name"
                    ],
                    "properties": {
                      "name": {
                        "const": "duration"
                      }
                    }
                  },
                  "minContains": 0,
                  "maxContains": 1
                },
                {
                  "contains": {
                    "type": "object",
                    "required": [
                      "name"
                    ],
                    "properties": {
                      "name": {
                        "const": "black_frames"
                      }
                    }
                  },
                  "minContains": 0,
                  "maxContains": 1
                },
                {
                  "contains": {
                    "type": "object",
                    "required": [
                      "name"
                    ],
                    "properties": {
                      "name": {
                        "const": "silence"
                      }
                    }
                  },
                  "minContains": 0,
                  "maxContains": 1
                },
                {
                  "contains": {
                    "type": "object",
                    "required": [
                      "name"
                    ],
                    "properties": {
                      "name": {
                        "const": "asr_match"
                      }
                    }
                  },
                  "minContains": 0,
                  "maxContains": 1
                },
                {
                  "contains": {
                    "type": "object",
                    "required": [
                      "name"
                    ],
                    "properties": {
                      "name": {
                        "const": "onscreen_text"
                      }
                    }
                  },
                  "minContains": 0,
                  "maxContains": 1
                },
                {
                  "contains": {
                    "type": "object",
                    "required": [
                      "name"
                    ],
                    "properties": {
                      "name": {
                        "const": "camera_motion"
                      }
                    }
                  },
                  "minContains": 0,
                  "maxContains": 1
                },
                {
                  "contains": {
                    "type": "object",
                    "required": [
                      "name"
                    ],
                    "properties": {
                      "name": {
                        "const": "identity"
                      }
                    }
                  },
                  "minContains": 0,
                  "maxContains": 1
                }
              ]
            }
          }
        },
        "source_tasks": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "provider",
              "task_id",
              "model"
            ],
            "properties": {
              "provider": {
                "type": "string",
                "enum": [
                  "giggle",
                  "mock"
                ]
              },
              "task_id": {
                "type": "string",
                "minLength": 1
              },
              "model": {
                "type": "string",
                "minLength": 1
              }
            }
          }
        },
        "cost_credits": {
          "$ref": "#/$defs/common/$defs/credits"
        },
        "created_at": {
          "$ref": "#/$defs/common/$defs/timestamp"
        },
        "is_test": {
          "$ref": "#/$defs/common/$defs/is_test"
        },
        "role": {
          "description": "What the picture shows: host (the host on camera, mouth visible), product_closeup or product_in_use (the product with no visible mouth). A voiceover reply plays only over a product_closeup or product_in_use clip of the product it is about (INVARIANTS 38). Absent: not stated.",
          "type": "string",
          "enum": [
            "host",
            "product_closeup",
            "product_in_use"
          ]
        },
        "captions_url": {
          "description": "WebVTT of the clip's spoken text with real timing, made by the engine (1.14.0). GET /v1/rooms/{room_id}/clips/{clip_id}/captions.vtt redirects to it when it is an https URL. Absent: the platform writes the file from `captions` with estimated timing.",
          "$ref": "#/$defs/common/$defs/url"
        },
        "ai_marking": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "method",
            "digital_source_type"
          ],
          "properties": {
            "method": {
              "description": "c2pa: a signed C2PA manifest embedded in the MP4 (BMFF hash binding); mp4_metadata: MP4 tags (ai_generated=true, digital_source_type), unsigned, when c2pa is not available.",
              "type": "string",
              "enum": [
                "c2pa",
                "mp4_metadata"
              ]
            },
            "digital_source_type": {
              "description": "The IPTC digital source type written into the file: trainedAlgorithmicMedia for a generated clip.",
              "const": "http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia"
            }
          },
          "description": "1.16.0 (C1 S23, c1-shorts f623afa1 engine/arvia_engine/aimark): the machine-readable AI marking of the file at url (EU AI Act Art. 50(2); INVARIANTS 49). Absent: the file is not marked (packages made before the package step marks at birth)."
        },
        "product_box": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "x",
            "y",
            "w",
            "h"
          ],
          "properties": {
            "x": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "y": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "w": {
              "type": "number",
              "exclusiveMinimum": 0,
              "maximum": 1
            },
            "h": {
              "type": "number",
              "exclusiveMinimum": 0,
              "maximum": 1
            }
          },
          "description": "1.16.0 (A1 N226, a1.12-inserts af22d01d (code 83dfb583)): where the product is in the frame, as fractions of the frame's width (x, w) and height (y, h) from the top left; the player keeps the captions off it (just above it, else just below). Emitted by the engine (INVARIANTS 52). The same values may be written in the clip's WebVTT as `NOTE arvia product_box x=… y=… w=… h=…`; the player reads either, and when both exist they agree."
        },
        "caption_safe_zone": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "top",
            "bottom"
          ],
          "properties": {
            "top": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "bottom": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            }
          },
          "description": "1.16.0 (A1 N226): the horizontal band (fractions of the frame's height, top < bottom) where captions may sit without covering the product or the host's hands; it wins over product_box. WebVTT form: `NOTE arvia caption_safe_zone top=… bottom=…`. Absent both: the player's default band (under the top overlays, above the hands)."
        },
        "renditions": {
          "description": "1.22.0 (S38; engine a2.10-room-quality 9d8a255d package/manifest.py, c565def7 --keep-published, 9e1aacd8 package/published.py): every file of the clip the player may switch between, largest first. renditions[0] is the clip's own file: its url, width and height equal the clip's (INVARIANTS 64). Each smaller one is `clips/<clip_id>_<name>.mp4` beside it, encoded at the same keyframe times (same `keyframes` count), audio copied, AI-marked on its own. Absent: the clip has only `url`. Until the engine puts it into the clip document, the same list is `renditions: {clip_id: [...]}` in the package document, the room's `<job>.segments.json` and `manifests/<room_id>/renditions.json` (rooms not in the engine's ledger).",
          "type": "array",
          "minItems": 1,
          "maxItems": 8,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "name",
              "url",
              "width",
              "height",
              "bitrate",
              "avg_bitrate",
              "bytes",
              "sha256",
              "codecs",
              "keyframe_interval_s",
              "keyframes",
              "ai_mark"
            ],
            "properties": {
              "name": {
                "description": "<short side>p of the 9:16 frame (720p = 720x1280, 480p = 480x854), as PACKAGE_RENDITIONS names it (engine package/media.py parse_renditions).",
                "type": "string",
                "pattern": "^[1-9][0-9]{2,3}p$"
              },
              "url": {
                "$ref": "#/$defs/common/$defs/url"
              },
              "width": {
                "description": "The short side: even, at least 144 (parse_renditions).",
                "type": "integer",
                "minimum": 144,
                "multipleOf": 2
              },
              "height": {
                "description": "width x 16 / 9 rounded to even.",
                "type": "integer",
                "minimum": 256,
                "multipleOf": 2
              },
              "bitrate": {
                "description": "The video bitrate cap in bit/s (VBV maxrate; 720p 2,500,000, 480p 1,200,000 by default); at least 100 kb/s.",
                "type": "integer",
                "minimum": 100000
              },
              "avg_bitrate": {
                "description": "Measured: bytes x 8 / duration_s, rounded. It can exceed `bitrate` on a published file encoded before the cap existed. null only for a zero duration.",
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": 1
              },
              "bytes": {
                "description": "Size of the file as served (after AI marking).",
                "type": "integer",
                "minimum": 1
              },
              "sha256": {
                "description": "Lower-case hex sha256 of the file as served (after AI marking).",
                "type": "string",
                "pattern": "^[0-9a-f]{64}$"
              },
              "codecs": {
                "description": "RFC 6381 codecs of the H.264 + AAC-LC file (MediaSource.isTypeSupported, HLS CODECS), e.g. avc1.64001f,mp4a.40.2 (engine media.codecs_string).",
                "type": "string",
                "pattern": "^avc1\\.[0-9a-f]{6},mp4a\\.40\\.2$"
              },
              "keyframe_interval_s": {
                "description": "The fixed GOP in seconds (2.0) when the engine encoded every rendition from the raw clip; null when the keyframes were forced at an already published file's keyframe times (--keep-published, package renditions).",
                "type": [
                  "number",
                  "null"
                ],
                "exclusiveMinimum": 0
              },
              "keyframes": {
                "description": "Number of keyframes; equal in every rendition of the clip (the engine refuses misaligned renditions).",
                "type": "integer",
                "minimum": 1
              },
              "ai_mark": {
                "description": "How this file is AI-marked (S26, clip.json ai_marking method); null for a published file whose marking could not be read back.",
                "enum": [
                  "c2pa",
                  "mp4_metadata",
                  null
                ]
              },
              "published": {
                "description": "Only on renditions[0], when it is a file published before the smaller renditions were added (left byte for byte as it was).",
                "const": true
              },
              "reused": {
                "description": "Only on a smaller rendition made from a published file (package renditions): true when the object already existed and was reused, not replaced.",
                "type": "boolean"
              }
            }
          }
        }
      },
      "allOf": [
        {
          "if": {
            "properties": {
              "kind": {
                "const": "faq"
              }
            }
          },
          "then": {
            "properties": {
              "faq_question": {
                "description": "Required (non-null, non-empty) for faq clips; the type is checked by the property's own definition.",
                "not": {
                  "type": "null"
                },
                "minLength": 1
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "enum": [
                  "opener",
                  "pitch",
                  "faq",
                  "closer",
                  "transition",
                  "holiday"
                ]
              }
            }
          },
          "then": {
            "properties": {
              "qa": {
                "properties": {
                  "checks": {
                    "allOf": [
                      {
                        "contains": {
                          "type": "object",
                          "required": [
                            "name"
                          ],
                          "properties": {
                            "name": {
                              "const": "duration"
                            }
                          }
                        }
                      },
                      {
                        "contains": {
                          "type": "object",
                          "required": [
                            "name"
                          ],
                          "properties": {
                            "name": {
                              "const": "black_frames"
                            }
                          }
                        }
                      },
                      {
                        "contains": {
                          "type": "object",
                          "required": [
                            "name"
                          ],
                          "properties": {
                            "name": {
                              "const": "silence"
                            }
                          }
                        }
                      },
                      {
                        "contains": {
                          "type": "object",
                          "required": [
                            "name"
                          ],
                          "properties": {
                            "name": {
                              "const": "asr_match"
                            }
                          }
                        }
                      },
                      {
                        "contains": {
                          "type": "object",
                          "required": [
                            "name"
                          ],
                          "properties": {
                            "name": {
                              "const": "onscreen_text"
                            }
                          }
                        }
                      },
                      {
                        "contains": {
                          "type": "object",
                          "required": [
                            "name"
                          ],
                          "properties": {
                            "name": {
                              "const": "camera_motion"
                            }
                          }
                        }
                      },
                      {
                        "contains": {
                          "type": "object",
                          "required": [
                            "name"
                          ],
                          "properties": {
                            "name": {
                              "const": "identity"
                            }
                          }
                        }
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "broll"
              }
            }
          },
          "then": {
            "properties": {
              "qa": {
                "properties": {
                  "checks": {
                    "allOf": [
                      {
                        "contains": {
                          "type": "object",
                          "required": [
                            "name"
                          ],
                          "properties": {
                            "name": {
                              "const": "duration"
                            }
                          }
                        }
                      },
                      {
                        "contains": {
                          "type": "object",
                          "required": [
                            "name"
                          ],
                          "properties": {
                            "name": {
                              "const": "black_frames"
                            }
                          }
                        }
                      },
                      {
                        "contains": {
                          "type": "object",
                          "required": [
                            "name"
                          ],
                          "properties": {
                            "name": {
                              "const": "onscreen_text"
                            }
                          }
                        }
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "is_test": {
                "const": false
              }
            }
          },
          "then": {
            "properties": {
              "source_tasks": {
                "minItems": 1,
                "items": {
                  "properties": {
                    "provider": {
                      "const": "giggle"
                    }
                  }
                }
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "enum": [
                  "pitch",
                  "faq",
                  "broll"
                ]
              }
            }
          },
          "then": {
            "properties": {
              "product_sku": {
                "description": "Not null in this case; the value's format is checked by the property's own definition.",
                "not": {
                  "type": "null"
                }
              }
            }
          }
        }
      ]
    },
    "clip_manifest": {
      "title": "Clip manifest",
      "description": "Output of the engine's package step (A2.7) and body of PUT /v1/rooms/{room_id}/clips. Every clip's is_test equals the manifest's, which equals the room's (INVARIANTS.md); clip_ids are unique and every clip's host_id equals the manifest's. `replace` (1.17.0, S37, INVARIANTS 58): true makes `clips` the room's full clip set; every other clip registered for the room is removed softly (removed_at) and leaves chapters, replay, captions, segments and the timeline; a removed clip named again in any PUT is registered again. Absent or false: upsert by clip_id, as before. Only a boolean is taken.",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "room_id",
        "host_id",
        "generated_at",
        "clips",
        "is_test"
      ],
      "properties": {
        "room_id": {
          "$ref": "#/$defs/common/$defs/id"
        },
        "host_id": {
          "$ref": "#/$defs/common/$defs/id"
        },
        "generated_at": {
          "$ref": "#/$defs/common/$defs/timestamp"
        },
        "clips": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/clip"
          }
        },
        "is_test": {
          "$ref": "#/$defs/common/$defs/is_test"
        },
        "replace": {
          "type": "boolean",
          "description": "true: the manifest is the room's full clip set; clips of the room not in it are removed (platform a1.12-inserts 5a8c9379 putClips). Absent = false = upsert only."
        }
      },
      "allOf": [
        {
          "if": {
            "properties": {
              "is_test": {
                "const": false
              }
            }
          },
          "then": {
            "properties": {
              "clips": {
                "items": {
                  "properties": {
                    "is_test": {
                      "const": false
                    }
                  }
                }
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "is_test": {
                "const": true
              }
            }
          },
          "then": {
            "properties": {
              "clips": {
                "items": {
                  "properties": {
                    "is_test": {
                      "const": true
                    }
                  }
                }
              }
            }
          }
        }
      ]
    },
    "rights_declaration": {
      "description": "1.23.0: the seller's attestation that they are the person shown or hold the person's permission (model release) for AI-generated video of this person in live selling, from the agent console checkbox. Not public (never in viewer_host.json).",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "attested_at",
        "attested_by"
      ],
      "properties": {
        "attested_at": {
          "$ref": "#/$defs/common/$defs/timestamp"
        },
        "attested_by": {
          "description": "Who ticked the box: the console account (e-mail or account id).",
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "release_url": {
          "description": "Optional uploaded signed model release.",
          "$ref": "#/$defs/common/$defs/url"
        }
      }
    }
  },
  "x-contracts-version": "1.24.11",
  "x-source-revision": "398cce3642b1d4ea398fd1c3fb0860b544559bd3",
  "x-submission-endpoint": {
    "environment": "staging",
    "method": "POST",
    "path": "/v1/agent/supply-submissions",
    "status_path": "/v1/agent/supply-submissions/{submission_id}",
    "auth": "Bearer agent credential",
    "profile": "/hosts/supply.json",
    "publication": "receive-only; pending_scheduling until platform review"
  },
  "x-submission-status": "staging receive-only preview; production unavailable",
  "x-fee": "Compute policy: first platform-room minute free; then USD2.99/minute. See specification. Accounting/display only; no real charging.",
  "x-document-version": "0.1.0",
  "x-media-profile": {
    "status": "published requirements; enforcement requires platform review",
    "container": "MP4",
    "video_codec": "H.264",
    "audio_codec": "AAC-LC when audio is present",
    "primary_dimensions": [
      720,
      1280
    ],
    "lower_dimensions": [
      480,
      854
    ],
    "duration_seconds": {
      "exclusiveMinimum": 0,
      "maximum": 120
    },
    "captions": "Exact spoken captions; WebVTT with actual timing; captions_lang required by onboarding profile",
    "ai_disclosure": true,
    "ai_marking": "c2pa; actual validation and trust decision required per file",
    "product_sku": "Approved real catalogue SKU; product-free null only for compatible kind",
    "metadata_warning": "These constraints are profile annotations, not changes to contracts 1.24.11."
  },
  "x-review-workflow": {
    "status": "proposed process; no current submission or receipt API",
    "states": [
      "prepared",
      "awaiting_manual_intake",
      "under_review",
      "changes_requested",
      "approved_for_test",
      "test_verified",
      "scheduled",
      "live",
      "withdrawn",
      "suspended"
    ],
    "transitions": [
      [
        "prepared",
        "awaiting_manual_intake"
      ],
      [
        "awaiting_manual_intake",
        "under_review"
      ],
      [
        "under_review",
        "changes_requested"
      ],
      [
        "changes_requested",
        "under_review"
      ],
      [
        "under_review",
        "approved_for_test"
      ],
      [
        "approved_for_test",
        "test_verified"
      ],
      [
        "test_verified",
        "scheduled"
      ],
      [
        "scheduled",
        "live"
      ],
      [
        "live",
        "withdrawn"
      ],
      [
        "live",
        "suspended"
      ]
    ],
    "authority": "Supplier may prepare/revise/request withdrawal; platform alone reviews, approves, schedules, suspends or restores. No automatic transition from local validation to live."
  },
  "x-proposed-rejection-reasons": {
    "status": "proposed taxonomy, not existing HTTP error codes",
    "codes": [
      "PROFILE_INCOMPLETE",
      "RIGHTS_UNCONFIRMED",
      "TERMS_NOT_ACCEPTED",
      "MEDIA_UNPLAYABLE",
      "MEDIA_SPEC_MISMATCH",
      "CAPTION_MISMATCH",
      "AI_MARK_INVALID",
      "SKU_UNAUTHORIZED",
      "PRODUCT_VISUAL_MISMATCH",
      "PACKAGING_TEXT_MISMATCH",
      "FACTS_UNSUPPORTED",
      "QUOTA_EXCEEDED",
      "SOURCE_PROVIDER_UNSUPPORTED"
    ]
  },
  "x-commercial-policy-as-of": "2026-11-11T23:21:00Z"
}
