<!-- source-hash: a8a83c1fb84a9906fd7502112718264a -->
Isomorphic SSOT module for stable per-element identity on `video_bites` / `teasers` JSONB array elements. Provides ID generation, ID stamping, and the canonical element-matching predicate shared across the admin editor (browser) and Mux reconciliation sweep (Node).

## Key Components

| Export | Type | Description |
|---|---|---|
| `BiteIdentity` | Interface | Identity-relevant subset of `VideoTeaser` (`id?`, `url`, `source_url?`) |
| `BITE_ID_RE` | `RegExp` | Validates 8 lowercase hex char IDs — collision-safe within a single array |
| `generateBiteId()` | Function | Produces a new 8-hex ID via `crypto.randomUUID()` |
| `ensureBiteIds()` | Function | Stamps missing IDs and re-stamps in-array duplicates; returns same reference when unchanged |
| `matchBiteElement()` | Function | Canonical three-leg predicate for identifying the same clip across array states |

## Usage Example

```typescript
import { ensureBiteIds, matchBiteElement } from './video-bite-id'

// Stamp incoming bites before persistence
const { bites, changed } = ensureBiteIds(rawBites)
if (changed) await persistBites(bites)

// Match an incoming element against the existing array (multiset — consume each existing once)
const matched = existingBites.find(existing => matchBiteElement(existing, incoming))
if (matched) {
  // Carry matched.id forward — id equality, url match, or source_url flip
}
```

## Matching Legs

`matchBiteElement` uses an **any-of** strategy (not short-circuit on ID mismatch) to handle cases where two sides represent the same clip with different IDs:

1. **ID equality** — both sides carry an ID and they match
2. **URL equality** — `incoming.url === existing.url` (pre-flip sessions, plain re-saves)
3. **Source URL flip** — `incoming.url === existing.source_url` (Mux HLS pipeline already flipped the URL; redelivered Vizard ingests)

> **Caller contract:** When matching a whole incoming array, each existing element must be consumed at most once to prevent duplicate incoming URLs from cloning a single element's ID.

---

**Source:** [`video-bite-id.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/video-bite-id.ts)