# Visual Asset Binary Transfer & Storage v0.1

Status: active operational policy.
Date: 2026-09-08.
Project: `PROJ-LUMINAUTAS-v1`.

## Goal

Preserve original generated PNG masters safely, make them available to Higgsfield, and move reviewed references into a durable production path without corrupting provenance or bloating Git unnecessarily.

## Current truth

- Original recovered PNG masters are preserved in the local source pack.
- A complete source archive and registry are staged in Google Drive under `Google Drive/CartoonOS/Visual_Source_Pack_2026-09-08/`.
- Individual source PNGs for Lumi, Tiko, Nova, Marina, Rin, Arqueo and Pepe are staged in versioned Drive folders.
- Shared backgrounds, scenarios, storyboard, brand-reference and workflow-guide PNGs are staged in matching Drive folders.
- Repository SVG/materialized previews are not equivalent to the original lossless PNG masters.
- Raster PNGs must never be relabeled as true vectors.

## Transfer-path audit

### 1. Direct GitHub binary API / Git Data API
Best when a binary-capable connector or authenticated Git client is available. Preserves exact bytes and commit provenance. Current chat connector requires payload embedding and is inefficient for dozens of multi-megabyte PNGs.

### 2. Git LFS
Preferred when reviewed image masters must live alongside Git history. Keeps repository clones lean while retaining versioned binary pointers. Requires LFS-capable authenticated push path.

### 3. Google Drive staging → authenticated GitHub UI / Git client
Best interactive fallback. Drive acts as durable transfer staging, then reviewed files are uploaded through an authenticated binary-capable GitHub path.

### 4. Google Drive/object storage → GitHub Actions ingestion
Efficient for repeatable ingestion only after Actions runners work and credentials are configured. Workflow downloads exact staged bytes, verifies checksums, then commits/LFS-pushes reviewed references.

### 5. Object storage as canonical media + Git manifests/pointers
Preferred long-term for large production media, intermediate renders and episode assets. Git stores manifests, checksums, provenance and reviewed lightweight references; object storage stores immutable binaries.

### 6. Base64/chunk reconstruction inside text commits
Emergency-only. Technically possible but inefficient, noisy and easy to misuse. Do not adopt as the normal pipeline.

## Selected architecture

Use a hybrid:

`Google Drive staging/recovery → reviewed reference masters → Git LFS or binary-capable Git path`

and for large/generated production media:

`Higgsfield/provider → CartoonOS object storage → checksum/provenance → Git manifest/reference`

Google Drive is temporary staging/backup, not the canonical transactional database.

## Required verification before a binary becomes canonical

For every asset:
- SHA-256 matches master registry;
- native width/height recorded;
- original format recorded;
- character/environment ID and version resolved;
- lifecycle state recorded;
- native vs upscaled truth recorded;
- vector status recorded;
- no duplicate checksum at another canonical path unless intentionally aliased;
- visual QA state recorded;
- source generation/provenance retained when known.

## Git storage policy

Store in normal Git:
- code;
- Markdown canon;
- schemas;
- prompt libraries;
- JSON/CSV registries;
- checksums;
- lightweight diagrams and README visuals.

Use Git LFS or object storage for:
- large PNG reference masters;
- 4K+ generated stills;
- video/audio masters;
- animatics;
- model outputs and intermediate renders.

Do not duplicate the same binary inside episode folders. Reference canonical asset IDs instead.

## Higgsfield ingestion

For reviewed character references:
1. resolve exact `character_id` + version;
2. verify checksum against the asset registry;
3. upload confirmed PNG master;
4. create/use a Higgsfield Element only after visual QA;
5. persist Element ID, workspace, source checksum and version;
6. keep original Drive/Git/object-storage reference immutable;
7. run Golden Character Test before `production_approved`.

## Recovery rule

A preview/gallery file can help humans browse the project but cannot replace a missing original master. If the original cannot be checksum-verified, the asset remains `candidate_unverified` and must not silently become production canon.