# Watermark Repository Specification

## 1. Version

The current schema version is `1.0.0`. Every `metadata.json` and the root
`manifest.json` must declare this version.

## 2. Dataset identities

| Benchmark | Suite key | Display name |
|---|---|---|
| `libero` | `long` | LIBERO-Long |
| `libero` | `goal` | LIBERO-Goal |
| `libero` | `object` | LIBERO-Object |
| `libero` | `spatial` | LIBERO-Spatial |
| `robotwin` | `main` | RoboTwin |

Do not use machine-specific aliases as suite keys.

## 3. Regimes

### Full data

```text
artifacts/full/<benchmark>/<suite>/<variant>/
```

Full runs must have:

- `ablation: null`
- no task-range restriction
- no episode-pool restriction
- the complete official suite for the declared dataset revision

### Episode-pool ablation

```text
artifacts/ablation/episode_pool/<benchmark>/<suite>/top_<N>/<variant>/
```

`N` is one of `10, 20, 30, 40, 50`. One episode is selected per task, but the
random choice is restricted to the first `N` episodes. Metadata must record
the random seed and `episode_pool_limit`.

### Task-fraction ablation

```text
artifacts/ablation/task_fraction/<benchmark>/<suite>/p<P>/<variant>/
```

`P` is one of `10, 20, ..., 90`. Metadata must record the exact selected task
count, exact task identifiers, epochs, and target optimization budget. Do not
infer the selected tasks only from the percentage.

## 4. Variant identities

`A` means action-loss weight and `V` means video-loss weight.

| Variant | Method | Action weight | Video weight |
|---|---:|---:|---:|
| `direct_A1V0` | `direct` | 1 | 0 |
| `direct_A0V1` | `direct` | 0 | 1 |
| `direct_A1V1` | `direct` | 1 | 1 |
| `de_proj_A1V0` | `de_proj` | 1 | 0 |
| `de_proj_A0V1` | `de_proj` | 0 | 1 |
| `bisect_A1V1` | `bisect` | 1 | 1 |

The directory name is authoritative. Metadata weights must agree with it.

## 5. Required artifact semantics

- `top1.npy`: best-ranked patch under the run's declared selection metric.
- `top2.npy` through `top5.npy`: remaining ranked patches.
- `final.npy`: patch at termination.
- `optimization.jsonl`: optional per-step trace.
- `metadata.json`: required provenance and integrity record.

Watermarks must be stored as NumPy arrays. For the current eye-in-hand setup,
the expected logical patch size is `128 x 128`; the exact array layout and
dtype must be declared in metadata.

## 6. Metadata requirements

Every metadata file must include:

- benchmark, suite, regime, variant, and weights
- public dataset repository and immutable revision
- public model repository and immutable revision
- selected tasks/episodes or the explicit full-data declaration
- seed, camera, patch parameters, optimization settings, and stopping reason
- Attack-WAM commit and hashes of the three critical source files
- Python, PyTorch, CUDA build, runtime cuDNN, GPU, and SDPA policy
- artifact paths, byte sizes, and SHA-256 hashes
- run status and any recovered anomaly

Never upload local absolute paths, access tokens, usernames, hostnames, or
private cache paths.

## 7. Status values

- `complete`: clean completion.
- `complete_with_note`: usable completion with a documented recovered event.
- `failed`: not valid for evaluation.

Only `complete` and `complete_with_note` runs belong in the root manifest.

## 8. Upload rules

1. Stage artifacts outside the source-code repository.
2. Rename artifacts to the canonical filenames.
3. Generate SHA-256 hashes and update metadata.
4. Update `manifest.json`.
5. Run the validator.
6. Upload only the staging directory.

Example:

```bash
hf upload Wjjjh/Attack /path/to/staging . \
  --exclude "**/.DS_Store" \
  --exclude "**/__pycache__/**"
```

Do not run `hf upload Wjjjh/Attack .` from an Attack-WAM source checkout.