# ISIS v2 PNG Output Schema and Metadata Contract

Generated: 2026-03-06T07:20:13.202Z Checklist: `MXD-0001` (ISIS2-01191) Format:
`png` (image/png) Phase: Phase 4 | Milestone: M3 Launch (2026-07-27 to
2026-10-30)

## Objective

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

## Canonical Schema

- Schema ID: `isis.v2.output.png.package`
- Schema Version: `1.0.0`
- Binary signature: `89 50 4E 47 0D 0A 1A 0A`
- Required top-level fields:
  - `schemaVersion`
  - `format`
  - `width`
  - `height`
  - `bitDepth`
  - `colorType`
  - `colorSpace`
  - `alphaMode`
  - `artifactRole`
  - `compression`
  - `chunkInventory`
  - `encoder`
  - `manifest`
- Manifest fields:
  - `filename`
  - `mimeType`
  - `checksumAlgorithm`
  - `checksum`
  - `generatedAt`
  - `provenance`
- Provenance fields:
  - `assetFamilyId`
  - `workflowId`
  - `workflowVariant`
  - `promptFingerprint`
  - `seed`
  - `modelId`
  - `dependencyManifestRef`

## Supported Package Classes

| Package Class   | Storage Tier | Required Artifacts                                                                                      |
| --------------- | ------------ | ------------------------------------------------------------------------------------------------------- |
| `preview`       | HOT          | `preview/hero-preview.{png,jpg,webp,mp4}`, `preview/thumbnail.{png,jpg,webp}`                           |
| `source-frames` | WARM         | `frames/frame_%06d.{png,exr,tiff}`, `frames/frame-index.json`                                           |
| `texture-set`   | WARM         | `textures/albedo.{png,tiff,exr}`, `textures/normal.{png,tiff,exr}`, `textures/roughness.{png,tiff,exr}` |

## Supported Output Classes

| Output Class     | Package Classes |
| ---------------- | --------------- |
| `image_sequence` | `source-frames` |
| `preview_image`  | `preview`       |
| `source_frames`  | `source-frames` |
| `sprite_sheet`   | `source-frames` |
| `texture_set`    | `texture-set`   |
| `video_master`   | `preview`       |

## Applicable Asset Families

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

## Validation Invariants

- IHDR, IDAT, and IEND chunks are mandatory for every PNG output.
- Indexed PNG outputs require a PLTE chunk and cannot use 16-bit depth.
- Alpha mode can only be straight or premultiplied when the color type includes
  alpha.
- ICC profile metadata requires an iCCP chunk.
- Pixel density metadata requires a pHYs chunk.
- Textual metadata requires at least one tEXt, zTXt, or iTXt chunk.
- RegisterOutputRequest dimensions must match pngPackage width and height when
  both are supplied.
- RegisterOutputRequest mimeType must be image/png and storage.key must end with
  .png when pngPackage is supplied.
- PNG manifest checksum uses sha256 and must preserve workflow/dependency
  provenance linkage.

## Verification Commands

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

## Acceptance Criteria

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

## Traceability

- Checklist item: `MXD-0001`
- Ticket key: `ISIS2-01191`
- Source references:
  - `docs/domains/isis/remediation-v2/ISIS_REMEDIATION_V2_TICKETS.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_OUTPUT_PACKAGE_TAXONOMY.json`
  - `apps/isis/output-registry/src/schemas/output.schema.ts`
  - `apps/isis/output-registry/src/schemas/output.schema.spec.ts`
  - `apps/isis/output-registry/src/services/output.service.ts`
  - `apps/isis/output-registry/src/types.ts`
  - `docs/domains/isis/remediation-v2/ISIS_V2_ANIMATIC_SHOT_SET_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_ARCHITECTURE_KITBASH_PACK_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_AUDIO_SFX_PACK_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_CHARACTER_CONCEPT_ART_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_CHARACTER_COSTUME_VARIANT_PACK_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_CHARACTER_EXPRESSION_SHEET_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_CHARACTER_PROP_INTERACTION_SHEET_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_CHARACTER_TURNAROUND_SHEET_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_CINEMATIC_SHOT_SEQUENCE_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_CREATURE_CONCEPT_ART_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_DECAL_PACK_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_ENVIRONMENT_CONCEPT_ART_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_ENVIRONMENT_MATTE_PAINTING_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_ENVIRONMENT_TILESET_PACK_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_FOLIAGE_PACK_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_HUD_ELEMENT_PACK_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_INTERIOR_SCENE_PACK_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_MARKETING_KEY_ART_PACK_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_MATERIAL_PBR_PACK_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_MUSIC_CUE_PACK_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_NPC_CROWD_VARIATION_PACK_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_PROP_PACK_GENERAL_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_SKY_ATMOSPHERE_PACK_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_SOCIAL_CUTDOWN_PACK_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_STORYBOARD_FRAME_SET_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_TERRAIN_HEIGHTMAP_PACK_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_UI_ICON_PACK_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_VEHICLE_EXTERIOR_PACK_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_VEHICLE_INTERIOR_PACK_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_VFX_ELEMENT_PACK_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_VOICE_LINE_PACK_OUTPUT_PACKAGE_CONTRACT.json`
  - `docs/domains/isis/remediation-v2/ISIS_V2_WEAPON_PACK_OUTPUT_PACKAGE_CONTRACT.json`
  - `ISIS_TODOS_2.md`
