# ISIS v2 JPEG Output Schema and Metadata Contract

Generated: 2026-03-06T07:47:37.173Z Checklist: `MXD-0005` (ISIS2-01195) Format:
`jpeg` (image/jpeg) Phase: Phase 4 | Milestone: M3 Launch (2026-07-27 to
2026-10-30)

## Objective

Define a canonical schema and metadata contract for JPEG outputs with strict
marker-level validation, deterministic integrity metadata, and workflow
provenance suitable for reproducible downstream ingest across Isis preview
packages.

## Canonical Schema

- Schema ID: `isis.v2.output.jpeg.package`
- Schema Version: `1.0.0`
- Binary signature: `FF D8 FF`
- Required top-level fields:
  - `schemaVersion`
  - `format`
  - `width`
  - `height`
  - `bitDepth`
  - `colorModel`
  - `chromaSubsampling`
  - `scanMode`
  - `artifactRole`
  - `markerInventory`
  - `encoder`
  - `manifest`
- Manifest fields:
  - `filename`
  - `mimeType`
  - `checksumAlgorithm`
  - `checksum`
  - `generatedAt`
  - `provenance`
- Provenance fields:
  - `assetFamilyId`
  - `workflowId`
  - `workflowVariant`
  - `promptFingerprint`
  - `seed`
  - `modelId`
  - `dependencyManifestRef`

## Validation Invariants

- SOI, SOS, and EOI markers are mandatory for every JPEG output.
- Baseline JPEG outputs require SOF0; progressive JPEG outputs require SOF2.
- Grayscale JPEG outputs must use chromaSubsampling none.
- ICC profile metadata requires an APP2 marker.
- EXIF metadata requires an APP1 marker.
- RegisterOutputRequest dimensions must match jpegPackage width and height when
  both are supplied.
- RegisterOutputRequest mimeType must be image/jpeg and storage.key must end
  with .jpg or .jpeg when jpegPackage is supplied.
- JPEG manifest checksum uses sha256 and must preserve workflow/dependency
  provenance linkage.

## Supported Package Classes

| Package Class | Storage Tier | Required Artifacts                                                            |
| ------------- | ------------ | ----------------------------------------------------------------------------- |
| `preview`     | `HOT`        | `preview/hero-preview.{png,jpg,webp,mp4}`, `preview/thumbnail.{png,jpg,webp}` |

## Applicable Asset Families

| Asset Family                       | Output Classes  | Naming Rules |
| ---------------------------------- | --------------- | ------------ |
| `animatic-shot-set`                | `preview_image` | `FN-001`     |
| `architecture-kitbash-pack`        | `preview_image` | `FN-001`     |
| `audio-sfx-pack`                   |                 |              |
| `character-concept-art`            | `preview_image` | `FN-001`     |
| `character-costume-variant-pack`   | `preview_image` | `FN-001`     |
| `character-expression-sheet`       | `preview_image` | `FN-001`     |
| `character-prop-interaction-sheet` | `preview_image` | `FN-001`     |
| `character-turnaround-sheet`       | `preview_image` | `FN-001`     |
| `cinematic-shot-sequence`          |                 |              |
| `creature-concept-art`             | `preview_image` | `FN-001`     |
| `decal-pack`                       | `preview_image` | `FN-001`     |
| `environment-concept-art`          | `preview_image` | `FN-001`     |
| `environment-matte-painting`       | `preview_image` | `FN-001`     |
| `environment-tileset-pack`         | `preview_image` | `FN-001`     |
| `foliage-pack`                     | `preview_image` | `FN-001`     |
| `hud-element-pack`                 | `preview_image` | `FN-001`     |
| `interior-scene-pack`              | `preview_image` | `FN-001`     |
| `marketing-key-art-pack`           | `preview_image` | `FN-001`     |
| `material-pbr-pack`                | `preview_image` | `FN-001`     |
| `music-cue-pack`                   |                 |              |
| `npc-crowd-variation-pack`         | `preview_image` | `FN-001`     |
| `prop-pack-general`                | `preview_image` | `FN-001`     |
| `sky-atmosphere-pack`              | `preview_image` | `FN-001`     |
| `social-cutdown-pack`              | `preview_image` | `FN-001`     |
| `storyboard-frame-set`             | `preview_image` | `FN-001`     |
| `terrain-heightmap-pack`           | `preview_image` | `FN-001`     |
| `ui-icon-pack`                     | `preview_image` | `FN-001`     |
| `vehicle-exterior-pack`            | `preview_image` | `FN-001`     |
| `vehicle-interior-pack`            | `preview_image` | `FN-001`     |
| `vfx-element-pack`                 | `preview_image` | `FN-001`     |
| `voice-line-pack`                  |                 |              |
| `weapon-pack`                      | `preview_image` | `FN-001`     |

## Verification Commands

- `pnpm --filter @isis/output-registry exec vitest run src/schemas/output.schema.spec.ts`
- `node scripts/isis/validate-v2-jpeg-output-schema-metadata-contract.mjs`

## Acceptance Criteria

- Output registry accepts first-class JPEG package metadata with strict
  validation over marker inventory, scan mode, chroma subsampling, and manifest
  checksum fields.
- Canonical JPEG contract enumerates the package classes and output classes that
  legitimately emit JPEG artifacts under the shared output taxonomy.
- JPEG manifest provenance preserves workflow-variant and dependency-manifest
  linkage needed for deterministic downstream ingest.
- Validator and schema tests catch invalid JPEG registrations and enforce the
  canonical metadata surface.
