# Ruliad extraction and intake contract v1

Schema: [ruliad-extraction-contract-v1.schema.json](/.well-known/ruliad-extraction-contract-v1.schema.json)

Example: [extraction-contract-v1.example.json](/agent-guides/extraction-contract-v1.example.json)

This versioned JSON Schema describes a portable intake envelope. It is not a new
production API endpoint and does not imply that every platform has a connected
importer. Validate the envelope before mapping it into the supported Setup or
authenticated production tools. Keep the original envelope with the project's
input evidence; consumers must explicitly preserve it when saving or exporting.
Publication of this contract alone does not establish that every existing
consumer carries provenance through to a deliverable.

## What to extract

- `inputs.brand`, `product` and `concept`: the actual ad subject and creative brief.
- `inputs.scriptInputs`: duration in seconds and aspect ratio; language, CTA,
  spoken text and creative direction when supplied.
- Optional `brandVoice` and `offers`: distinguish the user's direction from a
  source-page fact. Never turn an inferred voice or claim into a verified fact.
- `references`: original image references, each assigned an explicit `talent`,
  `product`, `location` or `storyboard` role. These are the production-input
  roles supported by the existing reference importer. Scraper categories such
  as logo, promo and supplemental are classification hints, not automatic
  production-role assignments. Preserve the original classification separately
  until an authorized caller chooses a supported role.

## Every field has evidence

Each extracted field contains `value`, `status` and `source`:

- `provided`: explicitly supplied by the user or an authorized source.
- `verified`: checked against the cited source; a claim, not cryptographic proof.
- `inferred`: a suggestion that must not be presented as page truth.
- `ambiguous`: conflicting evidence remains unresolved.
- `missing`: `value` and `source` are null. Do not fill gaps with invented facts.

A non-missing field requires source kind, source reference, extraction timestamp
and a locator identifying the exact page section, platform item or user message.
Use `connected-platform` only after an authorized connection actually retrieved
the item. A URL is not evidence that an account was connected. Do not include
credentials or reusable private access tokens in an envelope or public artifact.
Use a durable receipt identifier for private sources.

## Completeness and asset integrity

`partial` is valid intake. List unresolved paths in `missingFields` and keep
working only on independent tasks. `ready-for-script` requires provided or
verified brand, product, concept, duration and aspect ratio, and an empty
`missingFields` list. It is not permission to generate, consent for likeness,
payment authority, or a claim that storyboard/production/export are ready.
References may be empty when the brief does not require them; never fabricate a
person or asset to satisfy a field.

An asset starts with `integrity.state: "unverified"`. Only a stored-body receipt
can support `stored-body-verified`, which requires the full SHA256, byte length,
immutable storage generation and receipt ID. Upload-time hashes and filenames
alone do not establish stored-byte parity. The schema checks receipt shape;
the authenticated storage path must independently verify the receipt against
the original stored generation. Schema validity does not attest authenticity.

## Compatibility

- Existing URL analysis uses `AnalyzeUrlInput` / `AnalyzeUrlResult` in
  `packages/shared/src/intelligence.ts`; it remains a separate endpoint shape.
- Existing folder evidence uses `CampaignFolderManifest` and `EvidenceChainEntry`
  in `src/campaignFolderIntake/types.ts`. Per-file evidence is not automatically
  per-field provenance; retain each field's locator when adapting it.
- Existing ChatGPT reference import supports authenticated owned projects and
  explicit reference roles. This contract neither creates Drive/social/catalog
  connections nor grants an assistant access to another account.

Use the current account/identity workflow and preserve the source owner's rights.
Ordinary customer creation remains free. Internal QA/provider safeguards and
customer export unlocks remain governed by the existing product workflow.