# SOP: Holographic Surface Workflow

Use this SOP when creating, verifying, querying, or importing `SEAM-HS/1`
surfaces.

## Compile Source Text Straight To A Surface

```powershell
python seam.py surface compile input.txt --output input.seam.png --mode rgb24
python seam.py surface verify input.seam.png
python seam.py --db seam.db surface compile input.txt --output input.seam.png --mode rgb24 --store
```

This is the automatic flow: source text is compiled into MIRL, then MIRL is
encoded into a `SEAM-HS/1` PNG. It does not persist the records into SQLite
unless `--persist` is supplied.

## Create A Surface From RC/1

```powershell
python seam.py readable-compress input.txt --output input.seamrc
python seam.py surface encode input.seamrc --output input.seam.png --mode rgb24
python seam.py surface verify input.seam.png
python seam.py --db seam.db surface encode input.seamrc --output input.seam.png --mode rgb24 --store
```

Expected result: verification reports `PASS` and shows `payload_format:
SEAM-RC/1`.

## Query A Surface Directly

```powershell
python seam.py surface query input.seam.png "exact phrase or topic"
python seam.py surface search input.seam.png "stable compression"
python seam.py surface context input.seam.png --query "agent behavior" --budget 1200
python seam.py --db seam.db surface query hs:<surface-id> "exact phrase or topic"
```

These commands read embedded MIRL or `SEAM-RC/1` from PNG pixel data in memory.
They do not use OCR, natural-language recompilation, or SQLite import.

## Store And Inspect A Surface Library Entry

```powershell
python seam.py --db seam.db surface store input.seam.png
python seam.py --db seam.db surface list
python seam.py --db seam.db surface show hs:<surface-id>
python seam.py --db seam.db surface repair hs:<surface-id>
```

The library stores metadata and hashes only. PNG artifacts remain
operator-controlled files at their recorded paths; keep generated user artifacts
out of the runtime repo unless they are deliberate fixtures or docs assets.
Repair verifies the redundant copy and restores it from the recorded original
source path when available. If no valid source remains, repair records the
failure in SQLite so future query attempts do not silently trust a missing or
corrupt artifact.

## Gate Stored Surfaces

```powershell
python seam.py benchmark run surface
python seam.py benchmark run all --output benchmark-release.json
python seam.py benchmark gate benchmark-release.json
```

The surface benchmark stores each fixture in a temporary surface library,
removes the original output path before querying the stored surface, removes the
redundant copy, repairs it from the recorded source path, and queries the
repaired copy. The release gate runs across all benchmark families; stored
lookup, stored query, repair, and repair-query rates must all stay at 100%.

Do not put intentionally failing research cases in the public `surface` fixture.
If a case is in `benchmarks/fixtures/surface_cases.json`, it is release-blocking
and should make pytest fail until the direct-read behavior is fixed. Exploratory
partial-pass loops belong in a separate suite or local fixture.

## Decode For Audit

```powershell
python seam.py surface decode input.seam.png --output restored.seamrc
python seam.py readable-rebuild restored.seamrc --output restored.txt
```

Use decode/rebuild for audit or export. Direct query does not require this step.

## Import When Needed

```powershell
python seam.py --db seam.db surface import input.seam.png
```

MIRL payloads are persisted as records. Non-MIRL payloads are stored as machine
artifact metadata so the original surface contract remains auditable.

## Rules

- Use PNG for v1 exact surfaces.
- Do not use JPEG or other lossy formats for exact SEAM memory.
- Prefer `rgb24` for default density and `bw1` for proof/debug fixtures.
- `rgb` is accepted as an alias for the canonical `rgb24` adapter.
- Use `rgba32` only when the extra channel density is worth the operational
  risk; it stores 4 bytes per pixel but alpha channels are often modified by
  image tooling.
- Use `rgba64` only when 16-bit RGBA density is required; it stores 8 bytes per
  pixel and has the highest risk of image tooling rewriting channel data.
- Treat the surface as a queryable snapshot, not as the replacement for SQLite
  canonical storage.
