Merge remote-tracking branch 'origin/main' into feat/249-inspect-local-readers

The recorded history timeline rewrote every marker's textContent on each
render, so a scroll-triggered re-render replaced the text node under the
pointer. When that frame landed between the press and the release of a
tap, Chromium touch dropped the click and the Recorded run dialog never
opened. Text is now written only when it changes.

Adds a deterministic regression test that re-renders the timeline between
mouse down and mouse up.

TESTING.md

@@ -332,7 +332,30 @@ becomes record format `limited` (no raw text, graph `limited`, roles and facts
 unaffected); other text chunks are skipped unread; byte-identical duplicates are
 accepted within a bounded read budget, while differing duplicates (and any duplicate
 role record over that budget) still fail. Other read bounds are unchanged: 8 MiB
-non-PNG header, 10,000 PNG chunks and a three-second ffprobe. Resolution under
+non-PNG header, 10,000 PNG chunks and a three-second ffprobe (per probe, at most two
+probes). Video containers are read through one shared carrier selector
+(`utils/video_metadata.select_video_carrier`, used by the inspector and by the admin
+scan): carriers are, in order, the per-key tags that current savers write (`prompt`,
+`workflow`, `parameters`, `comfyassets_prompt_pairs`, each `original-text`; Matroska
+upper-cased names fold on our side), then the old VideoHelperSuite `comment` JSON
+envelope, then `description` (object values are `reserialized-json`; envelope keys are
+matched exactly, as the legacy readers did, never folded). The first carrier holding a
+role key wins, otherwise the first holding a workflow, and carriers never merge. Two
+per-key tags folding to one key are a duplicate record: byte-identical ones are one
+record, differing ones fail the read. ffprobe is asked for exactly those six tags.
+Its JSON output escapes tag text (at most doubling it), so the stdout bounds are sized
+so that only the decoded per-record budgets above can fail or limit a record, and a
+video reads exactly as the identical PNG: the first probe allows twice the role and
+workflow budgets plus 64 KiB of envelope (12 MiB + 64 KiB); past that the inspector
+probes once more without the `workflow` tag within twice the role budget plus 64 KiB
+(4 MiB + 64 KiB) and the per-key workflow becomes `limited`, while an envelope over
+that bound still fails the read because it cannot be split. The admin scan reads the
+same carrier with the default resolver profile, so a per-key video links like the same
+graph in a PNG; the live monitor processes images only (unchanged, see the follow-up
+below) (`tests/test_utils_video_metadata.py`, `tests/test_api_admin.py`
+`TestScanReadsVideos`, `tests/test_api_prompt_inspector.py` `test_video_*`,
+`tests/test_inspection_response.py` `TestVideoProbeBoundsMatchPngBudgets`; the
+real-container round trips skip without ffmpeg). Resolution under
 `INSPECTION_PROFILE` bounds work, not graph size: 2,000 visits per candidate chain,
 20,000 in total, 64 link/JSON-container levels, 100,000 resolved characters, and a
 two 20,000-node ceilings: one over the top-level entries of the API prompt, and one
@@ -1344,6 +1367,61 @@ concept fixture stars the concept's favorites (each other prompt's first image).
   restore. Old backups without the table restore, and backup plus restore keeps
   WAL-resident favorites and closes every handle (`tests/test_database_backup.py`).
 
+Image annotations schema (#249, `database/annotation_schema.py`): the group
+`media_annotation_metadata` (one row: schema version, `image_index_revision`),
+`media_annotation_files` (one private locator per physical file,
+`normcase(join(realpath(root), relative))`, server-side only),
+`media_annotation_bytes` (one record per observed whole-file SHA-256 with the
+`size`/`mtime_ns` verified when those bytes were last seen and the set's
+`tag_revision`) and `media_image_tags` (the ordered tag set of one byte record,
+joined into the global `tags` registry). It installs like favorites: optional in
+old backups, required once current (`annotation_schema_error`, the single
+`require_library_state` flag), validated read-only before and after a SAVEPOINT
+install and on restore, never backfilled and never stat-ing media
+(`tests/test_annotation_schema.py`). Writers (`database/annotations.py`) always
+supply the UUID ids, run in `_pair_transaction` fenced by the storage epoch, and
+replace or union one byte record's set (`tag-conflict` / `tag-limit` with the
+current set, identical retries `replayed`); vocabulary rename, merge and delete
+carry `media_image_tags` through the one `_move_tag_links` loop, and tag rows,
+impact and command receipts report `image_count` / `images` /
+`images_changed` as files (`tests/test_annotations.py`,
+`tests/test_pair_tag_maintenance.py`, `tests/test_vocabulary.py`). Cheap reads
+(spec amendment S1) use a byte record only while the file's current
+`(size, mtime_ns)` equals its verified fingerprint; an in-place rewrite that
+preserves both keeps the old set matching until the file is next observed. The
+browser fixtures clear `media_image_tags`, `media_annotation_bytes` and
+`media_annotation_files` on reset and never the metadata row.
+
+Capture store (#249, `utils/media_capture.py`, `tests/test_media_capture.py`):
+one explicit action captures one rooted media file into an owner-only
+`prompt-manager-captures-*` temp directory, streaming it in 1 MiB chunks while
+hashing. Identity is compared like with like: the opened descriptor against
+the path only on the API-stable facts (`size`, `mtime_ns`); the full identity
+(`size`, `mtime_ns`, `ctime_ns`, `dev`/`ino` where meaningful) between the
+`fstat` before and after the copy and between the path stats before and after
+(native Windows CI with Python 3.12/3.13 showed `stat` and `fstat` disagreeing
+on `st_ctime_ns`: change time versus creation time; 3.10/3.11 agree). Any
+disagreement is `CaptureChanged` and the copy is removed. Error messages carry
+`strerror` only, never a path. Aliases (a symlinked
+file or directory, even inside the root), escapes, non-media names and
+directories are `CaptureDenied`; the locator is
+`normcase(join(realpath(root), relative))`, so a symlinked root shares the
+listing's identity. Fixed limits: 256 MiB per file (stat and stream), 8
+completed captures, 512 MiB reserved, 2 capture/verify workers, 900 s idle,
+1800 s hard; admission is nonblocking (`CaptureCapacity`) and lifetimes are
+tested with an injected clock. An acquired capture outlives expiry and release
+until its last use ends. Header-only dimensions (4096 px per side,
+16,777,216 px) and video mark Generate unsupported; `verify` re-hashes the
+current file without a copy. Every handle closes before unlink (a patched
+`os.unlink` asserts it, plus `assert_closed`), and files are unlinked outside
+the store lock. Known limit: on Windows before Python 3.13 `fstat` reports the
+creation time, so a same-size rewrite that restores `mtime_ns` during the copy
+window completes there with a digest of the copied bytes; POSIX and Windows on
+3.13+ detect it through the descriptor's change time (native CI, 3.13 only).
+Vocabulary rename, merge and delete bump the `tag_revision` of every image set
+they change (and `image_index_revision`), so a Tag dialog opened before the
+change gets `tag-conflict` on Save (`tests/test_pair_tag_maintenance.py`).
+
 Budgets: `test_filter_work_is_bounded` always runs. It asserts that a plain first
 page makes 1 link SELECT and a plain cursor page none, that every filter shape
 makes exactly 1, the covering-index plan, and that the per-file values are built
@@ -1656,6 +1734,47 @@ responsive production Viewer keeps its toolbar in the media panel and prompt det
 mobile toolbar collision. These are explicit remaining visual differences, not
 a whole-application or full-gallery/Viewer pixel-parity claim.
 
+Follow-up: monitor video support. The live image monitor (`utils/image_monitor.py`,
+`GalleryConfig.SUPPORTED_EXTENSIONS`) processes images only; videos written by
+ComfyUI savers reach the Library through the admin scan, which reads the shared video
+carrier. Accepting `VIDEO_EXTENSIONS` in the monitor and routing them through
+`read_video_metadata` is a separate, issue-linked change.
+
+Follow-up: local Inspect parity (#249 PR L1). The browser readers
+(`web/js/png-metadata.js`, `web/js/workspace/local-video.mjs`,
+`web/js/workspace/local-projection.mjs`) answer as the server does for the same bytes
+and a matching extension (`tests/test_local_inspect_parity.py`; the real-ffprobe cases
+skip without ffmpeg). The remaining known divergences, checked against ffprobe 9.0.2,
+`read_inspection_file` and `_metadata`, are tracked here, not accepted as parity:
+
+- Media kind comes from the bytes locally and from the extension on the server: a PNG
+  named `.mp4` is read as a PNG locally (format and size shown) while the server probes
+  it with ffprobe (no format, no size); MP4 bytes named `.png` read locally as video
+  while Pillow fails them on the server (`unreadable`). Parity is stated for the same
+  bytes with a matching extension.
+- JPEG dimensions: the local header read stops at 64 KiB, so a JPEG whose SOF follows
+  more than 64 KiB of APP segments (camera, Photoshop and EXIF/XMP workflow savers)
+  shows no dimensions, while Pillow reads them within the server's 8 MiB header bound.
+  The fix is a segment-header walk up to 8 MiB, which needs a plan amendment.
+- Classic QuickTime `moov/udta` text atoms (`©cmt`/`desc` with a 16-bit size and
+  language, outside `meta`) are not read locally; ffprobe reports them as
+  `comment`/`description`, so the server can select that envelope while the local
+  read is `absent`. No ComfyUI saver writes them.
+- Tag-size bounds count raw bytes locally and ffprobe's escaped JSON on the server
+  (first probe 12 MiB + 64 KiB, role-only re-probe 4 MiB + 64 KiB): only tag sets near
+  those bounds and dense with quotes or control characters can make one side re-probe
+  or fail while the other reads.
+- More than 10,000 container elements stop the local read (`limited`, metadata
+  `unreadable`); ffprobe reads such files.
+- An EBML DocType other than `matroska`/`webm` is an invalid container locally; ffmpeg
+  only warns and reads it.
+- Envelope JSON deeper than 1,000 levels is refused locally as Python's default
+  recursion limit refuses it; the server's real limit depends on the interpreter and
+  call stack. A duplicate key in an object enclosing a nest deeper than the running
+  Python's json limit is `malformed` locally and `limited` on that Python.
+- Decimal exponent limits assume CPython's C `_decimal`; on a `_pydecimal` interpreter
+  the server would read the over-limit exponents the local projection refuses.
+
 Preserve raw logs, failed traces, paired PNGs, geometry, runtime versions and
 source hashes before later managed commands clear their output directories.
 Frontend baseline updates are additive through `coverage:update` only after

database/annotation_schema.py

@@ -0,0 +1,290 @@
+"""Image annotation schema group (#249): file locators, byte records, image tags.
+
+The group installs like ``image_favorites`` and ``saved_views``: optional in old
+backups, required once a database is current. It owns
+
+- ``media_annotation_metadata``: one row, the group's schema version and the
+  image index revision;
+- ``media_annotation_files``: one private canonical locator per physical file
+  (``normcase(join(realpath(root), relative))``, server-side only);
+- ``media_annotation_bytes``: one record per observed whole-file SHA-256 of a
+  file, with the size and ``mtime_ns`` verified when those bytes were last seen
+  and the tag set's revision;
+- ``media_image_tags``: the ordered image tag set of one byte record, joined
+  into the global ``tags`` registry so vocabulary maintenance carries image
+  links like prompt and pair links.
+
+Installation never backfills anything from prompt or pair tags and never
+touches the filesystem. Validation reads only: the catalog objects are compared
+after whitespace compaction, columns, foreign keys and indexes through the
+PRAGMAs, and persisted values in single bounded SQL passes.
+"""
+
+import re
+import sqlite3
+from typing import Optional
+
+from .image_favorites import MAX_KEY_LENGTH
+
+SCHEMA_VERSION = 1
+METADATA_TABLE = "media_annotation_metadata"
+FILES_TABLE = "media_annotation_files"
+BYTES_TABLE = "media_annotation_bytes"
+IMAGE_TAGS_TABLE = "media_image_tags"
+TABLES = (METADATA_TABLE, FILES_TABLE, BYTES_TABLE, IMAGE_TAGS_TABLE)
+MAX_LOCATOR_LENGTH = MAX_KEY_LENGTH
+_TIMESTAMP_BYTES = 64
+
+_TABLE_DDL = {
+    METADATA_TABLE: (
+        f"CREATE TABLE {METADATA_TABLE} (singleton_id INTEGER PRIMARY KEY "
+        "CHECK(singleton_id=1), schema_version INTEGER NOT NULL "
+        f"CHECK(schema_version={SCHEMA_VERSION}), "
+        "image_index_revision INTEGER NOT NULL DEFAULT 0 "
+        "CHECK(image_index_revision>=0))"
+    ),
+    FILES_TABLE: (
+        f"CREATE TABLE {FILES_TABLE} (id TEXT PRIMARY KEY CHECK(length(id)=36), "
+        "locator TEXT NOT NULL UNIQUE, created_at TEXT NOT NULL)"
+    ),
+    BYTES_TABLE: (
+        f"CREATE TABLE {BYTES_TABLE} (id TEXT PRIMARY KEY CHECK(length(id)=36), "
+        f"file_id TEXT NOT NULL REFERENCES {FILES_TABLE}(id) ON DELETE CASCADE, "
+        "sha256 TEXT NOT NULL CHECK(length(sha256)=64 AND sha256 NOT GLOB "
+        "'*[^0-9a-f]*'), size INTEGER NOT NULL CHECK(size>=0), "
+        "mtime_ns INTEGER NOT NULL, verified_at TEXT NOT NULL, "
+        "first_seen_at TEXT NOT NULL, tag_revision INTEGER NOT NULL DEFAULT 0 "
+        "CHECK(tag_revision>=0), UNIQUE(file_id, sha256))"
+    ),
+    IMAGE_TAGS_TABLE: (
+        f"CREATE TABLE {IMAGE_TAGS_TABLE} (byte_id TEXT NOT NULL REFERENCES "
+        f"{BYTES_TABLE}(id) ON DELETE CASCADE, tag_id INTEGER NOT NULL "
+        "REFERENCES tags(id) ON DELETE CASCADE, position INTEGER NOT NULL "
+        "CHECK(position>=0), PRIMARY KEY(byte_id, tag_id))"
+    ),
+}
+_INDEX_DDL = {
+    "idx_media_annotation_bytes_fingerprint": (
+        "CREATE INDEX idx_media_annotation_bytes_fingerprint ON "
+        f"{BYTES_TABLE}(file_id, size, mtime_ns)"
+    ),
+    "idx_media_image_tags_tag": (
+        f"CREATE INDEX idx_media_image_tags_tag ON {IMAGE_TAGS_TABLE}(tag_id)"
+    ),
+    "idx_media_image_tags_position": (
+        "CREATE UNIQUE INDEX idx_media_image_tags_position ON "
+        f"{IMAGE_TAGS_TABLE}(byte_id, position)"
+    ),
+}
+# SQLite names the indexes behind TEXT primary keys and UNIQUE constraints
+# ``sqlite_autoindex_<table>_<n>``; their catalog rows carry no SQL.
+_AUTOINDEXES = {FILES_TABLE: 2, BYTES_TABLE: 2, IMAGE_TAGS_TABLE: 1}
+# (name, declared type, not null, default, primary key position)
+_COLUMNS = {
+    METADATA_TABLE: (
+        ("singleton_id", "INTEGER", 0, None, 1),
+        ("schema_version", "INTEGER", 1, None, 0),
+        ("image_index_revision", "INTEGER", 1, "0", 0),
+    ),
+    FILES_TABLE: (
+        ("id", "TEXT", 0, None, 1),
+        ("locator", "TEXT", 1, None, 0),
+        ("created_at", "TEXT", 1, None, 0),
+    ),
+    BYTES_TABLE: (
+        ("id", "TEXT", 0, None, 1),
+        ("file_id", "TEXT", 1, None, 0),
+        ("sha256", "TEXT", 1, None, 0),
+        ("size", "INTEGER", 1, None, 0),
+        ("mtime_ns", "INTEGER", 1, None, 0),
+        ("verified_at", "TEXT", 1, None, 0),
+        ("first_seen_at", "TEXT", 1, None, 0),
+        ("tag_revision", "INTEGER", 1, "0", 0),
+    ),
+    IMAGE_TAGS_TABLE: (
+        ("byte_id", "TEXT", 1, None, 1),
+        ("tag_id", "INTEGER", 1, None, 2),
+        ("position", "INTEGER", 1, None, 0),
+    ),
+}
+# (column, parent table, parent column, on delete)
+_FOREIGN_KEYS = {
+    METADATA_TABLE: set(),
+    FILES_TABLE: set(),
+    BYTES_TABLE: {("file_id", FILES_TABLE, "id", "CASCADE")},
+    IMAGE_TAGS_TABLE: {
+        ("byte_id", BYTES_TABLE, "id", "CASCADE"),
+        ("tag_id", "tags", "id", "CASCADE"),
+    },
+}
+
+
+def _compact(sql: str) -> str:
+    return re.sub(r"\s+", "", sql).lower()
+
+
+def _uuid(column: str) -> str:
+    """SQL: *column* is a lowercase hyphenated 36-character UUID string."""
+    return (
+        f"typeof({column}) = 'text' AND length({column}) = 36 "
+        f"AND substr({column}, 9, 1) = '-' AND substr({column}, 14, 1) = '-' "
+        f"AND substr({column}, 19, 1) = '-' AND substr({column}, 24, 1) = '-' "
+        f"AND length(replace({column}, '-', '')) = 32 "
+        f"AND replace({column}, '-', '') NOT GLOB '*[^0-9a-f]*'"
+    )
+
+
+def _timestamp(column: str) -> str:
+    return (
+        f"typeof({column}) = 'text' "
+        f"AND length(CAST({column} AS BLOB)) <= {_TIMESTAMP_BYTES}"
+    )
+
+
+def _non_negative(column: str) -> str:
+    return f"typeof({column}) = 'integer' AND {column} >= 0"
+
+
+# Every row of a table must satisfy its predicate; one pass each, LIMIT 1.
+_ROW_PREDICATES = {
+    FILES_TABLE: " AND ".join(
+        (
+            _uuid("id"),
+            "typeof(locator) = 'text'",
+            # UTF-8 is at most 4 bytes per character; the decoded length of
+            # the few candidates above the byte bound is checked in Python.
+            f"length(CAST(locator AS BLOB)) <= {MAX_LOCATOR_LENGTH * 4}",
+            _timestamp("created_at"),
+        )
+    ),
+    BYTES_TABLE: " AND ".join(
+        (
+            _uuid("id"),
+            _uuid("file_id"),
+            "typeof(sha256) = 'text' AND length(sha256) = 64 "
+            "AND sha256 NOT GLOB '*[^0-9a-f]*'",
+            _non_negative("size"),
+            "typeof(mtime_ns) = 'integer'",
+            _timestamp("verified_at"),
+            _timestamp("first_seen_at"),
+            _non_negative("tag_revision"),
+        )
+    ),
+    IMAGE_TAGS_TABLE: " AND ".join(
+        (_uuid("byte_id"), "typeof(tag_id) = 'integer'", _non_negative("position"))
+    ),
+}
+
+
+def _expected_catalog() -> set:
+    objects = {("table", name, _compact(sql)) for name, sql in _TABLE_DDL.items()}
+    objects |= {("index", name, _compact(sql)) for name, sql in _INDEX_DDL.items()}
+    objects |= {
+        ("index", f"sqlite_autoindex_{table}_{n}", "")
+        for table, count in _AUTOINDEXES.items()
+        for n in range(1, count + 1)
+    }
+    return objects
+
+
+def _catalog(conn: sqlite3.Connection) -> list:
+    names = TABLES + tuple(_INDEX_DDL)
+    marks = ",".join("?" * len(names))
+    table_marks = ",".join("?" * len(TABLES))
+    return conn.execute(  # only "?" placeholders are interpolated
+        "SELECT type,name,sql FROM sqlite_master "
+        f"WHERE name IN ({marks}) OR tbl_name IN ({table_marks})",  # nosec B608
+        names + TABLES,
+    ).fetchall()
+
+
+def _structure_error(conn: sqlite3.Connection) -> Optional[str]:
+    for table, expected in _COLUMNS.items():
+        columns = tuple(
+            (row[1], row[2].upper(), row[3], row[4], row[5])
+            for row in conn.execute(f"PRAGMA table_info({table})")
+        )
+        if columns != expected:
+            return f"Image annotations table {table} has invalid columns"
+        foreign_keys = {
+            (row[3], row[2], row[4], row[6])
+            for row in conn.execute(f"PRAGMA foreign_key_list({table})")
+        }
+        if foreign_keys != _FOREIGN_KEYS[table]:
+            return f"Image annotations table {table} has invalid foreign keys"
+        if conn.execute(f"PRAGMA foreign_key_check({table})").fetchone():
+            return f"Image annotations table {table} contains foreign key violations"
+    return None
+
+
+def _value_error(conn: sqlite3.Connection) -> Optional[str]:
+    # Only this module's constants are interpolated into the SQL below.
+    rows = conn.execute(
+        "SELECT COUNT(*), MIN(typeof(singleton_id) = 'integer' "  # nosec B608
+        "AND singleton_id = 1 AND typeof(schema_version) = 'integer' "
+        f"AND schema_version = {SCHEMA_VERSION} "
+        f"AND {_non_negative('image_index_revision')}) FROM {METADATA_TABLE}"
+    ).fetchone()
+    if rows[0] != 1 or rows[1] != 1:
+        return "Image annotations metadata is invalid"
+    for table, predicate in _ROW_PREDICATES.items():
+        if conn.execute(
+            f"SELECT 1 FROM {table} WHERE NOT ({predicate}) LIMIT 1"  # nosec B608
+        ).fetchone():
+            return f"Image annotations table {table} contains invalid values"
+    # length() stops at an embedded NUL, so the SQL pass bounds bytes and the
+    # few candidates over the character bound are measured decoded here.
+    for (raw,) in conn.execute(
+        f"SELECT CAST(locator AS BLOB) FROM {FILES_TABLE} "  # nosec B608
+        f"WHERE length(CAST(locator AS BLOB)) > {MAX_LOCATOR_LENGTH}"
+    ):
+        if len(bytes(raw).decode("utf-8", "replace")) > MAX_LOCATOR_LENGTH:
+            return f"Image annotations table {FILES_TABLE} contains invalid values"
+    return None
+
+
+def annotation_schema_error(
+    conn: sqlite3.Connection, *, allow_missing: bool = True
+) -> Optional[str]:
+    """Reject partial or unsupported annotation schemas and invalid rows.
+
+    Reads only: nothing is ever repaired. A database without any of the
+    group's objects is acceptable for backups that predate it unless
+    ``allow_missing`` is false.
+    """
+    objects = _catalog(conn)
+    if not objects:
+        return None if allow_missing else "Missing image annotation schema"
+    present = {name for kind, name, _sql in objects if kind == "table"}
+    if present != set(TABLES):
+        return "Incomplete image annotation schema"
+    actual = {(kind, name, _compact(sql or "")) for kind, name, sql in objects}
+    if actual != _expected_catalog():
+        return "Image annotations has an invalid schema definition"
+    return _structure_error(conn) or _value_error(conn)
+
+
+def migrate_annotation_state(conn: sqlite3.Connection) -> None:
+    """Install the group atomically; validate before and after creating it."""
+    conn.execute("SAVEPOINT media_annotation_schema")
+    try:
+        error = annotation_schema_error(conn)
+        if error:
+            raise sqlite3.DatabaseError(error)
+        for sql in _TABLE_DDL.values():
+            conn.execute(sql.replace("CREATE TABLE", "CREATE TABLE IF NOT EXISTS", 1))
+        for sql in _INDEX_DDL.values():
+            conn.execute(sql.replace("INDEX", "INDEX IF NOT EXISTS", 1))
+        conn.execute(
+            f"INSERT OR IGNORE INTO {METADATA_TABLE} "
+            "(singleton_id, schema_version, image_index_revision) VALUES (1, ?, 0)",
+            (SCHEMA_VERSION,),
+        )
+        error = annotation_schema_error(conn, allow_missing=False)
+        if error:
+            raise sqlite3.DatabaseError(error)
+        conn.execute("RELEASE media_annotation_schema")
+    except BaseException:
+        conn.execute("ROLLBACK TO media_annotation_schema")
+        conn.execute("RELEASE media_annotation_schema")
+        raise

database/annotations.py

@@ -0,0 +1,457 @@
+"""Per-image tag sets (#249): byte-exact storage in the shared vocabulary.
+
+A tag set belongs to one byte record (``media_annotation_bytes``): the
+whole-file SHA-256 of one physical file, owned by the file's private locator
+(``media_annotation_files``). Callers pass verified facts (digest, size,
+``mtime_ns``); nothing here reads the filesystem or resolves an owner through
+prompt links, so tagging one image never changes another image, a prompt or a
+pair.
+
+Commands run in one ``_pair_transaction`` fenced by the storage epoch, like the
+native Library and vocabulary commands. A save is a full replacement guarded
+by the set's ``tag_revision``; the identical set sent again (a lost-response
+retry, or the current set at its own revision) answers ``replayed: true`` and
+writes nothing. ``add_image_tags`` unions into the existing set, keeping the
+stored spelling. Names enter the global ``tags`` registry exactly as spelled,
+so vocabulary rename, merge and delete carry image links with prompt and pair
+links (``PromptDatabase._move_tag_links``).
+
+Cheap reads (spec amendment S1) treat a byte record as *current* only while
+the file's present ``(size, mtime_ns)`` equals the record's verified
+fingerprint; a file without a current record shows no image tags.
+"""
+
+import re
+import sqlite3
+from contextlib import contextmanager
+from typing import Iterator
+from uuid import uuid4
+
+from .annotation_schema import (
+    BYTES_TABLE,
+    FILES_TABLE,
+    IMAGE_TAGS_TABLE,
+    MAX_LOCATOR_LENGTH,
+    METADATA_TABLE,
+)
+from .library_commands import _UUID, LibraryCommandError, _validate_epoch
+from .models import utc_now_iso
+from .vocabulary import validate_vocabulary_tag_name
+
+MAX_IMAGE_TAGS = 100
+_LOOKUP_CHUNK = 500
+_DIGEST = re.compile(r"[0-9a-f]{64}")
+_MAX_INT = 2**63 - 1
+_MIN_INT = -(2**63)
+# Only this module's table constants are interpolated into the SQL below.
+_OWNER = f"SELECT id FROM {FILES_TABLE} WHERE locator=?"  # nosec B608
+_INSERT_OWNER = (
+    f"INSERT INTO {FILES_TABLE}(id,locator,created_at) VALUES(?,?,?)"  # nosec B608
+)
+_BYTE = (
+    f"SELECT id,tag_revision,size,mtime_ns FROM {BYTES_TABLE} "  # nosec B608
+    "WHERE file_id=? AND sha256=?"
+)
+_INSERT_BYTE = (
+    f"INSERT INTO {BYTES_TABLE}(id,file_id,sha256,size,mtime_ns,"  # nosec B608
+    "verified_at,first_seen_at,tag_revision) VALUES(?,?,?,?,?,?,?,0)"
+)
+_REFRESH_BYTE = (
+    f"UPDATE {BYTES_TABLE} SET size=?,mtime_ns=?,verified_at=? WHERE id=?"  # nosec B608
+)
+_REFRESH_BY_LOCATOR = (
+    f"UPDATE {BYTES_TABLE} SET size=?,mtime_ns=?,verified_at=? "  # nosec B608
+    f"WHERE sha256=? AND file_id=({_OWNER})"
+)
+_BYTE_TAGS = (
+    f"SELECT t.name FROM {IMAGE_TAGS_TABLE} mit "  # nosec B608
+    "JOIN tags t ON t.id=mit.tag_id WHERE mit.byte_id=? ORDER BY mit.position"
+)
+_CLEAR_TAGS = f"DELETE FROM {IMAGE_TAGS_TABLE} WHERE byte_id=?"  # nosec B608
+_INSERT_TAG = (
+    f"INSERT INTO {IMAGE_TAGS_TABLE}(byte_id,tag_id,position) "  # nosec B608
+    "VALUES(?,?,?)"
+)
+_BUMP_REVISION = (
+    f"UPDATE {BYTES_TABLE} SET tag_revision=tag_revision+1 WHERE id=?"  # nosec B608
+)
+_REVISION = f"SELECT tag_revision FROM {BYTES_TABLE} WHERE id=?"  # nosec B608
+_BUMP_INDEX = (
+    f"UPDATE {METADATA_TABLE} SET "  # nosec B608
+    "image_index_revision=image_index_revision+1 WHERE singleton_id=1"
+)
+_READ = (
+    "SELECT b.id,b.tag_revision,"  # nosec B608
+    f"(SELECT COUNT(*) FROM {BYTES_TABLE} o WHERE o.file_id=f.id AND o.sha256!=?) "
+    f"FROM {FILES_TABLE} f LEFT JOIN {BYTES_TABLE} b "
+    "ON b.file_id=f.id AND b.sha256=? WHERE f.locator=?"
+)
+_FINGERPRINTS = (
+    "SELECT f.locator,b.id,b.size,b.mtime_ns,b.verified_at "  # nosec B608
+    f"FROM {FILES_TABLE} f JOIN {BYTES_TABLE} b ON b.file_id=f.id "
+    "WHERE f.locator IN ({marks})"
+)
+_TAGS_OF = (
+    f"SELECT mit.byte_id,t.name FROM {IMAGE_TAGS_TABLE} mit "  # nosec B608
+    "JOIN tags t ON t.id=mit.tag_id WHERE mit.byte_id IN ({marks}) "
+    "ORDER BY mit.byte_id,mit.position"
+)
+_RECORDS = (
+    "SELECT f.locator,b.id,b.size,b.mtime_ns,t.name "  # nosec B608
+    f"FROM {FILES_TABLE} f JOIN {BYTES_TABLE} b ON b.file_id=f.id "
+    f"LEFT JOIN {IMAGE_TAGS_TABLE} mit ON mit.byte_id=b.id "
+    "LEFT JOIN tags t ON t.id=mit.tag_id "
+    "ORDER BY f.locator,b.first_seen_at,b.id,mit.position"
+)
+
+
+class AnnotationCommandError(LibraryCommandError):
+    """An image tag command lost a race or hit the set's bound.
+
+    ``code`` is ``tag-conflict`` (the set changed since it was read) or
+    ``tag-limit`` (the union would exceed ``MAX_IMAGE_TAGS``); ``current`` is
+    the stored set ``{sha256, tags, tag_revision}`` read inside the
+    transaction, so the caller can show it.
+    """
+
+    def __init__(self, code: str, epoch: str, current: dict | None = None):
+        super().__init__(code, epoch)
+        self.current = current
+
+
+def normalize_image_tags(names: object) -> list[str]:
+    """Trim and validate each name, fold case-insensitive repeats, cap at 100.
+
+    The first occurrence keeps its spelling and position. Raises ``ValueError``
+    for anything but a list of valid vocabulary names or for more than
+    ``MAX_IMAGE_TAGS`` distinct names.
+    """
+    if not isinstance(names, list):
+        raise ValueError("tags must be a list of strings")
+    result: list[str] = []
+    seen: set[str] = set()
+    for value in names:
+        name = validate_vocabulary_tag_name(value)
+        key = name.casefold()
+        if key in seen:
+            continue
+        seen.add(key)
+        result.append(name)
+    if len(result) > MAX_IMAGE_TAGS:
+        raise ValueError(f"An image can carry at most {MAX_IMAGE_TAGS} tags")
+    return result
+
+
+def _validate_locator(locator: object) -> None:
+    if not isinstance(locator, str) or not 0 < len(locator) <= MAX_LOCATOR_LENGTH:
+        raise ValueError(
+            f"locator must be a nonblank path of at most {MAX_LOCATOR_LENGTH} chars"
+        )
+
+
+def _validate_digest(sha256: object) -> None:
+    if not isinstance(sha256, str) or not _DIGEST.fullmatch(sha256):
+        raise ValueError("sha256 must be 64 lowercase hexadecimal characters")
+
+
+def _validate_int(value: object, name: str, minimum: int) -> None:
+    if type(value) is not int or not minimum <= value <= _MAX_INT:
+        raise ValueError(f"{name} must be an integer not below {minimum}")
+
+
+def _validate_target(locator: object, sha256: object, size: object, mtime_ns: object):
+    _validate_locator(locator)
+    _validate_digest(sha256)
+    _validate_int(size, "size", 0)
+    _validate_int(mtime_ns, "mtime_ns", _MIN_INT)
+
+
+def _validate_fingerprint(locator: object, fingerprint: object) -> None:
+    _validate_locator(locator)
+    if (
+        not isinstance(fingerprint, tuple)
+        or len(fingerprint) != 2
+        or any(type(value) is not int for value in fingerprint)
+    ):
+        raise ValueError("stats must map locators to (size, mtime_ns) integer pairs")
+
+
+def _new_id() -> str:
+    """A canonical UUID; the schema's CHECK lets NULL through, this does not."""
+    value = str(uuid4())
+    if not _UUID.fullmatch(value):
+        raise ValueError("Annotation ids must be canonical UUIDs")
+    return value
+
+
+def _receipt(epoch: str, sha256: str, tags: list, revision: int, replayed: bool):
+    return {
+        "library_epoch": epoch,
+        "sha256": sha256,
+        "tags": list(tags),
+        "tag_revision": revision,
+        "replayed": replayed,
+    }
+
+
+class AnnotationOperations:
+    """PromptDatabase mixin: image tag sets, fingerprints and cheap reads.
+
+    ``_`` helpers take the open ``_pair_transaction`` connection.
+    """
+
+    @contextmanager
+    def _annotation_read(self) -> Iterator[sqlite3.Connection]:
+        """One deferred read transaction, so paired SELECTs see one snapshot."""
+        conn = self.model.get_connection()
+        if conn.in_transaction:
+            raise sqlite3.ProgrammingError(
+                "Annotation reads require their own snapshot"
+            )
+        with conn:
+            conn.execute("BEGIN")
+            yield conn
+
+    @staticmethod
+    def _annotation_owner(conn: sqlite3.Connection, locator: str, now: str) -> str:
+        row = conn.execute(_OWNER, (locator,)).fetchone()
+        if row is not None:
+            return row[0]
+        file_id = _new_id()
+        conn.execute(_INSERT_OWNER, (file_id, locator, now))
+        return file_id
+
+    @staticmethod
+    def _annotation_byte(
+        conn: sqlite3.Connection,
+        file_id: str,
+        sha256: str,
+        size: int,
+        mtime_ns: int,
+        now: str,
+    ) -> tuple[str, int, bool, bool]:
+        """The byte record for these bytes, refreshed or created.
+
+        Returns ``(id, tag_revision, created, refingerprinted)``; the last is
+        True when an existing record's verified ``(size, mtime_ns)`` changed,
+        which moves its currency for cheap reads (the caller bumps the index
+        revision when nothing else does).
+        """
+        row = conn.execute(_BYTE, (file_id, sha256)).fetchone()
+        if row is None:
+            byte_id = _new_id()
+            conn.execute(
+                _INSERT_BYTE, (byte_id, file_id, sha256, size, mtime_ns, now, now)
+            )
+            return byte_id, 0, True, False
+        conn.execute(_REFRESH_BYTE, (size, mtime_ns, now, row[0]))
+        return row[0], row[1], False, (row[2], row[3]) != (size, mtime_ns)
+
+    @staticmethod
+    def _byte_tags(conn: sqlite3.Connection, byte_id: str) -> list[str]:
+        return [row[0] for row in conn.execute(_BYTE_TAGS, (byte_id,))]
+
+    def _write_image_tags(
+        self, conn: sqlite3.Connection, byte_id: str, tags: list[str]
+    ) -> int:
+        """Rewrite the junction in order, bump both revisions; return the new one."""
+        tag_ids = self._ensure_tags(conn, tags)
+        conn.execute(_CLEAR_TAGS, (byte_id,))
+        conn.executemany(
+            _INSERT_TAG,
+            [(byte_id, tag_ids[name], position) for position, name in enumerate(tags)],
+        )
+        conn.execute(_BUMP_REVISION, (byte_id,))
+        conn.execute(_BUMP_INDEX)
+        return conn.execute(_REVISION, (byte_id,)).fetchone()[0]
+
+    def _current_set(self, conn, sha256, byte_id, revision) -> dict:
+        return {
+            "sha256": sha256,
+            "tags": self._byte_tags(conn, byte_id),
+            "tag_revision": revision,
+        }
+
+    def read_image_tags(self, locator: str, sha256: str) -> dict:
+        """The stored set of these exact bytes, or an empty set at revision 0.
+
+        ``prior_count`` is the number of other byte records at the locator
+        (earlier or later bytes of the same file).
+        """
+        _validate_locator(locator)
+        _validate_digest(sha256)
+        with self._annotation_read() as conn:
+            row = conn.execute(_READ, (sha256, sha256, locator)).fetchone()
+            if row is None:
+                return {"tags": [], "tag_revision": 0, "prior_count": 0}
+            tags = self._byte_tags(conn, row[0]) if row[0] is not None else []
+            return {"tags": tags, "tag_revision": row[1] or 0, "prior_count": row[2]}
+
+    def replace_image_tags(
+        self,
+        *,
+        locator: str,
+        sha256: str,
+        size: int,
+        mtime_ns: int,
+        expected_epoch: str,
+        expected_tag_revision: int,
+        tags: list,
+    ) -> dict:
+        """Replace the set of these exact bytes, guarded by epoch and revision.
+
+        Creates the owner and byte record when the bytes are new (an explicit
+        empty set is a real save). The identical set at the current revision,
+        or one behind it (a lost-response retry), is ``replayed`` and writes
+        nothing; any other revision mismatch is ``tag-conflict`` with the
+        current set and no writes.
+        """
+        _validate_target(locator, sha256, size, mtime_ns)
+        _validate_epoch(expected_epoch)
+        _validate_int(expected_tag_revision, "expected_tag_revision", 0)
+        tags = normalize_image_tags(tags)
+        with self._pair_transaction() as conn:
+            epoch = self._library_epoch(conn, expected_epoch)
+            now = utc_now_iso()
+            file_id = self._annotation_owner(conn, locator, now)
+            byte_id, revision, created, refingerprinted = self._annotation_byte(
+                conn, file_id, sha256, size, mtime_ns, now
+            )
+            current = self._byte_tags(conn, byte_id)
+            if (
+                not created
+                and current == tags
+                and expected_tag_revision in (revision, revision - 1)
+            ):
+                if refingerprinted:
+                    conn.execute(_BUMP_INDEX)
+                return _receipt(epoch, sha256, current, revision, True)
+            if expected_tag_revision != revision:
+                raise AnnotationCommandError(
+                    "tag-conflict",
+                    epoch,
+                    {"sha256": sha256, "tags": current, "tag_revision": revision},
+                )
+            revision = self._write_image_tags(conn, byte_id, tags)
+            return _receipt(epoch, sha256, tags, revision, False)
+
+    def add_image_tags(
+        self,
+        *,
+        locator: str,
+        sha256: str,
+        size: int,
+        mtime_ns: int,
+        expected_epoch: str,
+        tags: list,
+    ) -> dict:
+        """Union ``tags`` into the set of these exact bytes, keeping stored spelling.
+
+        ``added`` counts the names that were new (case-insensitively). A union
+        over ``MAX_IMAGE_TAGS`` is ``tag-limit`` with the current set and no
+        writes; a union that adds nothing to an existing record is ``replayed``.
+        """
+        _validate_target(locator, sha256, size, mtime_ns)
+        _validate_epoch(expected_epoch)
+        tags = normalize_image_tags(tags)
+        with self._pair_transaction() as conn:
+            epoch = self._library_epoch(conn, expected_epoch)
+            now = utc_now_iso()
+            file_id = self._annotation_owner(conn, locator, now)
+            byte_id, revision, created, refingerprinted = self._annotation_byte(
+                conn, file_id, sha256, size, mtime_ns, now
+            )
+            current = self._byte_tags(conn, byte_id)
+            present = {name.casefold() for name in current}
+            added = [name for name in tags if name.casefold() not in present]
+            merged = current + added
+            if len(merged) > MAX_IMAGE_TAGS:
+                raise AnnotationCommandError(
+                    "tag-limit",
+                    epoch,
+                    {"sha256": sha256, "tags": current, "tag_revision": revision},
+                )
+            if not created and not added:
+                if refingerprinted:
+                    conn.execute(_BUMP_INDEX)
+                return {**_receipt(epoch, sha256, current, revision, True), "added": 0}
+            revision = self._write_image_tags(conn, byte_id, merged)
+            return {
+                **_receipt(epoch, sha256, merged, revision, False),
+                "added": len(added),
+            }
+
+    def refresh_image_fingerprint(
+        self, locator: str, sha256: str, size: int, mtime_ns: int
+    ) -> bool:
+        """Record that these exact bytes were just seen with this stat.
+
+        True when a byte record was refreshed; nothing is created and no tag
+        or tag revision changes. The image index revision moves because the
+        record's currency for cheap reads may have changed.
+        """
+        _validate_target(locator, sha256, size, mtime_ns)
+        with self.model.get_connection() as conn:
+            cursor = conn.execute(
+                _REFRESH_BY_LOCATOR, (size, mtime_ns, utc_now_iso(), sha256, locator)
+            )
+            if cursor.rowcount > 0:
+                conn.execute(_BUMP_INDEX)
+            return cursor.rowcount > 0
+
+    def current_image_tags(self, stats: dict) -> dict:
+        """Image tags of the files whose current ``(size, mtime_ns)`` is verified.
+
+        ``stats`` maps locators to their present fingerprint. A locator is
+        answered (possibly with an empty set) only when a byte record carries
+        exactly that verified fingerprint; the most recently verified record
+        wins when several do. Lookups go in chunks of 500 locators.
+        """
+        if not isinstance(stats, dict):
+            raise ValueError(
+                "stats must map locators to (size, mtime_ns) integer pairs"
+            )
+        for locator, fingerprint in stats.items():
+            _validate_fingerprint(locator, fingerprint)
+        locators = list(stats)
+        chosen: dict[str, tuple[tuple[str, str], str]] = {}
+        result: dict[str, list[str]] = {}
+        with self._annotation_read() as conn:
+            for start in range(0, len(locators), _LOOKUP_CHUNK):
+                chunk = locators[start : start + _LOOKUP_CHUNK]
+                marks = ",".join("?" * len(chunk))
+                for locator, byte_id, size, mtime_ns, verified_at in conn.execute(
+                    _FINGERPRINTS.format(marks=marks), chunk
+                ):
+                    if (size, mtime_ns) != stats[locator]:
+                        continue
+                    key = (verified_at, byte_id)
+                    if locator not in chosen or key > chosen[locator][0]:
+                        chosen[locator] = (key, byte_id)
+            owners = {byte_id: locator for locator, (_key, byte_id) in chosen.items()}
+            result = {locator: [] for locator in chosen}
+            byte_ids = list(owners)
+            for start in range(0, len(byte_ids), _LOOKUP_CHUNK):
+                chunk = byte_ids[start : start + _LOOKUP_CHUNK]
+                marks = ",".join("?" * len(chunk))
+                for byte_id, name in conn.execute(_TAGS_OF.format(marks=marks), chunk):
+                    result[owners[byte_id]].append(name)
+        return result
+
+    def iter_image_tag_records(self) -> Iterator[tuple[str, int, int, list[str]]]:
+        """Stream every byte record as ``(locator, size, mtime_ns, tags)``.
+
+        One SELECT ordered by locator, then by the bytes' first sighting, with
+        each set's names in position order.
+        """
+        conn = self.model.get_connection()
+        current: tuple | None = None
+        for locator, byte_id, size, mtime_ns, name in conn.execute(_RECORDS):
+            if current is None or current[0] != byte_id:
+                if current is not None:
+                    yield current[1]
+                current = (byte_id, (locator, size, mtime_ns, []))
+            if name is not None:
+                current[1][3].append(name)
+        if current is not None:
+            yield current[1]

database/models.py

@@ -17,6 +17,7 @@ from typing import Optional, Set, Tuple
 
 from .library_schema import library_schema_error, migrate_library_state
 from .image_favorites import image_favorites_schema_error, migrate_image_favorites
+from .annotation_schema import annotation_schema_error, migrate_annotation_state
 from .saved_views import migrate_saved_views, saved_views_schema_error
 from .execution_history_schema import (
     history_schema_error,
@@ -302,6 +303,7 @@ class PromptModel:
         migrate_library_state(conn)
         migrate_image_favorites(conn)
         migrate_saved_views(conn)
+        migrate_annotation_state(conn)
 
     def _migrate_prompt_pairs(self, conn: sqlite3.Connection) -> None:
         conn.execute("SAVEPOINT prompt_pair_schema")
@@ -1021,9 +1023,9 @@ class PromptModel:
         Args:
             path: File to inspect
             require_library_state: Also require the tables every current
-                database has (Library state, image favorites and saved
-                views), as a migrated restore stage must; old backups may
-                lack them.
+                database has (Library state, image favorites, saved views
+                and image annotations), as a migrated restore stage must;
+                old backups may lack them.
 
         Returns:
             (ok, reason): reason is "ok" when the file is acceptable, otherwise
@@ -1088,6 +1090,11 @@ class PromptModel:
             )
             if views_error:
                 return False, views_error
+            annotation_error = annotation_schema_error(
+                conn, allow_missing=not require_library_state
+            )
+            if annotation_error:
+                return False, annotation_error
             return True, "ok"
         except sqlite3.Error as e:
             return False, f"Invalid SQLite database: {e}"

database/operations.py

@@ -12,6 +12,7 @@ from .models import PromptModel, normalize_image_path, utc_now_iso
 from .pairs import PairDependencyError, PairOperations
 from .library import LibraryOperations, titled
 from .image_favorites import ImageFavoriteOperations
+from .annotations import AnnotationOperations
 from .saved_views import SavedViewOperations
 from .library_commands import LibraryCommandOperations
 from .vocabulary import VocabularyOperations
@@ -322,6 +323,7 @@ class PromptDatabase(
     ExecutionOutputOperations,
     HistoryReadOperations,
     ImageFavoriteOperations,
+    AnnotationOperations,
     SavedViewOperations,
 ):
     """Database operations class for managing prompts."""
@@ -1084,16 +1086,39 @@ class PromptDatabase(
             }
 
     @staticmethod
+    def _bump_image_tag_bytes(conn: sqlite3.Connection, tag_id: int) -> int:
+        """Move the tag revision of every image set that carries *tag_id*.
+
+        Vocabulary rename, merge and delete change what an image's set reads
+        as, so a Tag dialog opened before the change must see ``tag-conflict``
+        on Save instead of recreating the old name. Bumps the image index
+        revision once when any set was affected; returns that count.
+        """
+        cursor = conn.execute(
+            "UPDATE media_annotation_bytes SET tag_revision = tag_revision + 1 "
+            "WHERE id IN (SELECT byte_id FROM media_image_tags WHERE tag_id = ?)",
+            (tag_id,),
+        )
+        if cursor.rowcount > 0:
+            conn.execute(
+                "UPDATE media_annotation_metadata SET "
+                "image_index_revision = image_index_revision + 1 WHERE singleton_id = 1"
+            )
+        return cursor.rowcount
+
+    @classmethod
     def _move_tag_links(
-        conn: sqlite3.Connection, source_id: int, target_id: int
+        cls, conn: sqlite3.Connection, source_id: int, target_id: int
     ) -> None:
-        """Repoint component and pair links from source to target.
+        """Repoint component, pair and image links from source to target.
 
         Owners that already carry the target keep that one link; the source's
-        leftover duplicates are removed. The source registry row is left for the
-        caller to delete.
+        leftover duplicates are removed (an image set keeps the target's
+        position). The source registry row is left for the caller to delete.
+        Image sets that carried the source get a new tag revision first.
         """
-        for junction in ("prompt_tags", "prompt_pair_tags"):
+        cls._bump_image_tag_bytes(conn, source_id)
+        for junction in ("prompt_tags", "prompt_pair_tags", "media_image_tags"):
             conn.execute(
                 f"UPDATE OR IGNORE {junction} SET tag_id = ? WHERE tag_id = ?",
                 (target_id, source_id),
@@ -1146,6 +1171,7 @@ class PromptDatabase(
                 conn.execute("DELETE FROM tags WHERE id = ?", (old_tag_id,))
             else:
                 # Simple rename
+                self._bump_image_tag_bytes(conn, old_tag_id)
                 conn.execute(
                     "UPDATE tags SET name = ? WHERE id = ?", (new_name, old_tag_id)
                 )
@@ -1187,6 +1213,7 @@ class PromptDatabase(
             affected = cursor.fetchone()["c"]
 
             # CASCADE delete handles prompt_tags entries
+            self._bump_image_tag_bytes(conn, tag_id)
             conn.execute("DELETE FROM tags WHERE id = ?", (tag_id,))
             conn.commit()
 
@@ -1239,7 +1266,10 @@ class PromptDatabase(
                 pair_count = conn.execute(
                     "SELECT COUNT(*) FROM prompt_pair_tags WHERE tag_id = ?", (src_id,)
                 ).fetchone()[0]
-                if src_count or pair_count:
+                image_count = conn.execute(
+                    "SELECT COUNT(*) FROM media_image_tags WHERE tag_id = ?", (src_id,)
+                ).fetchone()[0]
+                if src_count or pair_count or image_count:
                     self._move_tag_links(conn, src_id, target_id)
                     tags_merged += 1
                     affected += src_count

database/vocabulary.py

@@ -3,6 +3,9 @@
 A count is the number of eligible Library parents that carry the value
 directly or through one active saved pair, which is exactly what
 ``list_library(tags=[name])`` / ``list_library(category=value)`` return.
+A tag row's ``image_count`` is the number of files (private locators) with any
+byte record carrying the tag (#249), so a file counts once however many of its
+byte versions carry it, and equal bytes at two paths count twice.
 
 Tag commands run in one ``_pair_transaction``: the storage epoch is checked
 first, then the exact ``{id, name}`` identity, and the receipt is read on the
@@ -26,6 +29,11 @@ except ImportError:
     from utils.validators import validate_category, validate_tags
 
 _CATEGORY_DOMAIN = "prompt-manager-vocabulary-category:v1\n"
+# Files carrying a tag through any of their byte records (#249 image tags).
+_IMAGE_FILES = (
+    "SELECT mit.tag_id,COUNT(DISTINCT b.file_id) FROM media_image_tags mit "
+    "JOIN media_annotation_bytes b ON b.id=mit.byte_id"
+)
 
 
 def _tag_rows(page: str) -> str:
@@ -40,9 +48,13 @@ def _tag_rows(page: str) -> str:
         "WHERE pt.tag_id IN (SELECT id FROM page) AND " + _ELIGIBLE + " "
         "UNION SELECT ppt.tag_id,pp.positive_prompt_id FROM prompt_pairs pp "
         "JOIN prompt_pair_tags ppt ON ppt.pair_id=pp.id "
-        "WHERE pp.archived=0 AND ppt.tag_id IN (SELECT id FROM page)) "
-        "SELECT page.id,page.name,COUNT(DISTINCT owners.pid) AS prompt_count "
+        "WHERE pp.archived=0 AND ppt.tag_id IN (SELECT id FROM page)),"
+        "images(tag_id,n) AS (" + _IMAGE_FILES + " "
+        "WHERE mit.tag_id IN (SELECT id FROM page) GROUP BY mit.tag_id) "
+        "SELECT page.id,page.name,COUNT(DISTINCT owners.pid) AS prompt_count,"
+        "COALESCE(MAX(images.n),0) AS image_count "
         "FROM page LEFT JOIN owners ON owners.tag_id=page.id "
+        "LEFT JOIN images ON images.tag_id=page.id "
         "GROUP BY page.id ORDER BY page.id"
     )
 
@@ -61,7 +73,10 @@ _TAG_IMPACT = (
     "AS negative_variants,"
     "(SELECT COUNT(*) FROM prompt_pairs pp JOIN prompt_pair_tags ppt "
     "ON ppt.pair_id=pp.id WHERE ppt.tag_id=:tag AND pp.archived!=0) "
-    "AS archived_negative_variants"
+    "AS archived_negative_variants,"
+    "(SELECT COUNT(DISTINCT b.file_id) FROM media_image_tags mit "
+    "JOIN media_annotation_bytes b ON b.id=mit.byte_id WHERE mit.tag_id=:tag) "
+    "AS images"
 )
 _MAX_ID = 2**63 - 1
 
@@ -205,7 +220,16 @@ class VocabularyOperations:
             "SELECT COUNT(DISTINCT pair_id) FROM prompt_pair_tags WHERE tag_id=?",
             (tag_id,),
         ).fetchone()[0]
-        return {"components_changed": components, "pairs_changed": pairs}
+        images = conn.execute(
+            "SELECT COUNT(DISTINCT b.file_id) FROM media_image_tags mit "
+            "JOIN media_annotation_bytes b ON b.id=mit.byte_id WHERE mit.tag_id=?",
+            (tag_id,),
+        ).fetchone()[0]
+        return {
+            "components_changed": components,
+            "pairs_changed": pairs,
+            "images_changed": images,
+        }
 
     def create_vocabulary_tag(self, name: str, *, expected_epoch: str) -> dict:
         """Insert an unused registry row, or reuse the exact existing name."""
@@ -250,6 +274,7 @@ class VocabularyOperations:
                 "SELECT id FROM tags WHERE name=?", (new_name,)
             ).fetchone()
             if target is None:
+                self._bump_image_tag_bytes(conn, tag_id)
                 conn.execute("UPDATE tags SET name=? WHERE id=?", (new_name, tag_id))
                 result_id = tag_id
             else:
@@ -275,6 +300,7 @@ class VocabularyOperations:
             epoch = self._library_epoch(conn, expected_epoch)
             self._vocabulary_identity(conn, epoch, tag_id, name)
             counts = self._tag_owner_counts(conn, tag_id)
+            self._bump_image_tag_bytes(conn, tag_id)
             conn.execute("DELETE FROM tags WHERE id=?", (tag_id,))
             return {"library_epoch": epoch, "deleted": True, **counts}
 

docs/prompt-inspector.md

@@ -29,6 +29,12 @@ Each role has `status` (`resolved`, `absent`, `unresolved`, or `ambiguous`), `te
 (string only when resolved, otherwise null), and `source`. Inspection does not
 index files, alter saved prompts, run scans, or decode image pixels. PNG text and
 video probe output are bounded; unsupported or malformed evidence remains
-unresolved rather than becoming sendable placeholder text.
+unresolved rather than becoming sendable placeholder text. Videos are read from
+one container carrier: the per-key tags written by core SaveVideo/SaveWEBM and
+current VideoHelperSuite (`prompt`, `workflow`, `parameters`,
+`comfyassets_prompt_pairs`), else the old VideoHelperSuite `comment` envelope,
+else `description`. The admin scan reads the same carrier, so Images and
+ingestion agree on a video's prompts (see TESTING.md for the order and budgets;
+the live monitor processes images only).
 
 Python route changes require restarting ComfyUI. Browser assets require a refresh.

tests/browser/full-inspector.spec.mjs

@@ -804,6 +804,7 @@ test('slideshow preference failures leave native playback usable',async({page,re
 });
 
 test('full inspector attaches matched theme and mobile evidence with reachable content',async({page,request},testInfo)=>{
+    test.setTimeout(120_000); // 32 evidence captures across four viewports, like the concept comparisons
     await expect(await request.post('/__test__/reset',{data:{full_inspector:true,include_video:true}})).toBeOK();
     await page.goto('/prompt_manager/workspace#/images');
     const measurements=[];

tests/browser/server.py

@@ -189,6 +189,9 @@ def create_app(root: Path) -> web.Application:
             for table in (
                 "saved_views",
                 "image_favorites",
+                "media_image_tags",
+                "media_annotation_bytes",
+                "media_annotation_files",
                 "image_prompt_pairs",
                 "prompt_pair_tags",
                 "prompt_pairs",

tests/browser/workspace-history.spec.mjs

@@ -317,6 +317,19 @@ test('marker labels disclose exact observed dequeue and outcome including times
     }
 });
 
+// A timeline scroll re-renders the markers on the next frame. On a slow runner that frame lands between the press and
+// the release of a marker tap (Playwright's own scroll-into-view scrolls the timeline first); the re-render must leave
+// the pressed marker's nodes alone, or Chromium touch drops the click. The scroll event is dispatched so the marker
+// stays under the pointer, and the two frames are the re-render itself.
+test('a timeline re-render between press and release keeps the marker tap',async({page})=>{
+    const f=page.fixture;await open(page,f.detail_id);
+    const target=marker(page,f.runs.shared,'z');await expect(target).toHaveAttribute('aria-disabled','false');await target.scrollIntoViewIfNeeded();
+    const box=await target.boundingBox();await page.mouse.move(box.x+box.width/2,box.y+box.height/2);await page.mouse.down();
+    await recorded(page).locator('.history-timeline').evaluate(timeline=>{timeline.dispatchEvent(new Event('scroll'));return new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)));});
+    await page.mouse.up();
+    await expect(dialog(page).locator('[data-receipt]')).toHaveCount(5);
+});
+
 test('same-epoch refresh retains recorded context mode and exact receipt after fresh candidate reads',async({page})=>{
     const f=page.fixture;await open(page,f.detail_id);await marker(page,f.runs.shared,'z').click();await expect(dialog(page).locator('[data-receipt]')).toHaveCount(5);
     await dialog(page).getByRole('button',{name:'Effective',exact:true}).click();

tests/browser/workspace-images.spec.mjs

@@ -1512,6 +1512,25 @@ test('Refine opened before discovery settles lists the discovered sources and fo
 });
 
 // #249 final review m1: as in the old field row, a Source offers only its own folders.
+test('a search reload keeps the Filters label node, so a click landing during the reload is not lost', async ({ page, request }) => {
+    // WebKit drops a click whose mousedown hit a text node that was replaced before mouseup; the reload reports the
+    // (unchanged) active count, so the label must keep its node.
+    await expect(await request.post('/__test__/reset', { data: { extra_images: 80 } })).toBeOK();
+    await page.goto(workspace);
+    const button = filtersButton(page);
+    await button.click();await expect(refineDialog(page).getByLabel('Folder', { exact: true }).locator('option[value="bulk"]')).toHaveCount(1);await page.keyboard.press('Escape');
+    await refine(page, { Source: '0', Folder: 'bulk' });
+    await expect(button).toHaveText('Filters · 2');
+    const label = await button.evaluateHandle(node => node.firstChild);
+    const reloaded = page.waitForResponse(response => {
+        const url = new URL(response.url());return imagePages(url) && url.searchParams.get('q') === 'png';
+    });
+    await search(page).fill('png');
+    await reloaded;
+    await expect(button).toHaveText('Filters · 2');
+    expect(await button.evaluate((node, text) => node.firstChild === text && text.isConnected, label)).toBe(true);
+});
+
 test('Refine offers only the chosen source folders', async ({ page, request }) => {
     await expect(await request.post('/__test__/add-nested-image')).toBeOK();
     await page.goto(workspace);

tests/browser/workspace_concept_fixture.py

@@ -170,6 +170,9 @@ _TABLES = (
     "execution_context_texts",
     "saved_views",
     "image_favorites",
+    "media_image_tags",
+    "media_annotation_bytes",
+    "media_annotation_files",
     "image_prompt_pairs",
     "prompt_pair_tags",
     "prompt_pairs",

tests/browser/workspace_library_editor_fixture.py

@@ -28,6 +28,9 @@ EDITOR_METADATA = {
 _TABLES = (
     "saved_views",
     "image_favorites",
+    "media_image_tags",
+    "media_annotation_bytes",
+    "media_annotation_files",
     "image_prompt_pairs",
     "prompt_pair_tags",
     "prompt_pairs",

tests/browser/workspace_visual_fixture.py

@@ -114,6 +114,9 @@ def seed_workspace_visual(api: PromptManagerAPI, root: Path) -> None:
         for table in (
             "saved_views",
             "image_favorites",
+            "media_image_tags",
+            "media_annotation_bytes",
+            "media_annotation_files",
             "image_prompt_pairs",
             "prompt_pair_tags",
             "prompt_pairs",

tests/browser/workspace_vocabulary_fixture.py

@@ -81,6 +81,9 @@ MAX_EXTRA_CATEGORIES = 200
 _TABLES = (
     "saved_views",
     "image_favorites",
+    "media_image_tags",
+    "media_annotation_bytes",
+    "media_annotation_files",
     "image_prompt_pairs",
     "prompt_pair_tags",
     "prompt_pairs",

tests/fixtures/README.md

@@ -13,6 +13,75 @@ ffmpeg -f lavfi -i testsrc=size=32x32:rate=4:duration=1 \
 
 Browser tests use the committed file; FFmpeg is not required to run them.
 
+# Local Inspect header fixtures
+
+`local-inspect/tiny.jpg` (48x32) and `local-inspect/tiny.webp` (40x24) are original
+synthetic FFmpeg color test patterns, under 4 KB, dedicated to the public domain
+under CC0-1.0. `tests/js/png-local-reader.test.js` reads their dimensions with the
+browser header reader and `tests/test_local_inspect_parity.py` checks the same two
+files against Pillow.
+
+Reproduce with FFmpeg:
+
+```sh
+ffmpeg -f lavfi -i testsrc=size=48x32:rate=1 -frames:v 1 -q:v 10 tiny.jpg
+ffmpeg -f lavfi -i testsrc=size=40x24:rate=1 -frames:v 1 -c:v libwebp -quality 40 tiny.webp
+```
+
+# Local Inspect video fixtures
+
+`local-inspect/core-faststart.mp4`, `core-moov-end.mp4`, `core.mov`, `core.m4v`,
+`core.mkv`, `core-tags.webm`, `legacy-comment.mp4` and `legacy-comment.webm` are
+0.2-second 16x16 black clips (each under 4 KB) carrying an original synthetic
+ComfyUI graph in their container tags, dedicated to the public domain under
+CC0-1.0. The `core-*` files carry one tag per key as core SaveVideo/SaveWEBM write
+them (MP4/MOV/M4V through `-movflags use_metadata_tags`; Matroska upper-cases the
+names); `core-faststart.mp4` also carries `parameters` and
+`comfyassets_prompt_pairs`. The `legacy-comment.*` files carry the old
+VideoHelperSuite `comment` JSON envelope (an ilst `©cmt` atom in MP4, a `COMMENT`
+tag in WebM). `video-tags-v1.json` records `ffprobe -show_entries format_tags -of
+json` for each file (ffmpeg 9.0.2); `tests/test_utils_video_metadata.py`
+`VideoFixtureFfprobeTests` re-checks it when ffprobe is installed, and
+`tests/js/workspace-local-video.test.js` plus `tests/test_local_inspect_parity.py`
+hold the browser video reader to the same maps.
+
+Reproduce with FFmpeg, from `tests/fixtures/local-inspect`:
+
+```sh
+PROMPT='{"3":{"class_type":"KSampler","inputs":{"seed":7,"steps":20,"cfg":8.0,"sampler_name":"euler","scheduler":"normal","denoise":1.0,"model":["4",0],"positive":["6",0],"negative":["7",0],"latent_image":["5",0]}},"4":{"class_type":"CheckpointLoaderSimple","inputs":{"ckpt_name":"synthetic-v1.safetensors"}},"5":{"class_type":"EmptyLatentImage","inputs":{"width":512,"height":512,"batch_size":1}},"6":{"class_type":"CLIPTextEncode","inputs":{"text":"a red fox in snow, detailed fur","clip":["4",1]}},"7":{"class_type":"CLIPTextEncode","inputs":{"text":"blurry, lowres","clip":["4",1]}},"8":{"class_type":"VAEDecode","inputs":{"samples":["3",0],"vae":["4",2]}},"9":{"class_type":"SaveVideo","inputs":{"filename_prefix":"video/synthetic","video":["8",0]}}}'
+WORKFLOW='{"last_node_id":9,"nodes":[{"id":3,"type":"KSampler","widgets_values":[7,"fixed",20,8.0,"euler","normal",1.0]},{"id":6,"type":"CLIPTextEncode","widgets_values":["a red fox in snow, detailed fur"]},{"id":7,"type":"CLIPTextEncode","widgets_values":["blurry, lowres"]}],"links":[],"version":0.4}'
+PARAMETERS=$'a red fox in snow, detailed fur\nNegative prompt: blurry, lowres\nSteps: 20, Sampler: Euler, CFG scale: 8.0, Seed: 7, Size: 512x512'
+PAIRS='{"version":1,"nodes":{"6":{"records":[{"positive_text":"a red fox in snow, detailed fur","negative_text":"blurry, lowres","negative_effective_text":"blurry, lowres","prepend_text":"","append_text":""}]}}}'
+COMMENT=$(PROMPT="$PROMPT" WORKFLOW="$WORKFLOW" python3 -c 'import json,os; print(json.dumps({"prompt": os.environ["PROMPT"], "workflow": json.loads(os.environ["WORKFLOW"])}))')
+SRC=(-v quiet -y -f lavfi -i "color=c=black:s=16x16:d=0.2")
+ffmpeg "${SRC[@]}" -movflags use_metadata_tags+faststart -metadata prompt="$PROMPT" -metadata workflow="$WORKFLOW" -metadata parameters="$PARAMETERS" -metadata comfyassets_prompt_pairs="$PAIRS" core-faststart.mp4
+ffmpeg "${SRC[@]}" -movflags use_metadata_tags -metadata prompt="$PROMPT" -metadata workflow="$WORKFLOW" core-moov-end.mp4
+ffmpeg "${SRC[@]}" -movflags use_metadata_tags -metadata prompt="$PROMPT" -metadata workflow="$WORKFLOW" core.mov
+ffmpeg "${SRC[@]}" -movflags use_metadata_tags -metadata prompt="$PROMPT" -metadata workflow="$WORKFLOW" core.m4v
+ffmpeg "${SRC[@]}" -metadata prompt="$PROMPT" -metadata workflow="$WORKFLOW" core.mkv
+ffmpeg "${SRC[@]}" -c:v libvpx -metadata prompt="$PROMPT" -metadata workflow="$WORKFLOW" core-tags.webm
+ffmpeg "${SRC[@]}" -metadata comment="$COMMENT" legacy-comment.mp4
+ffmpeg "${SRC[@]}" -c:v libvpx -metadata comment="$COMMENT" legacy-comment.webm
+for f in core-faststart.mp4 core-moov-end.mp4 core.mov core.m4v core.mkv core-tags.webm legacy-comment.mp4 legacy-comment.webm; do
+  ffprobe -v quiet -show_entries format_tags -of json "$f"   # -> video-tags-v1.json "fixtures"[f] = .format.tags
+done
+```
+
+# Local Inspect projection cases
+
+`local-inspect/projection-cases.json` holds synthetic record sets (prompt, workflow,
+parameters and pair-record texts, optional `record_formats`, a video `carrier_text`
+and `limited` records) that exercise every branch of the server's inspection
+projection: Python's Decimal spellings and exact-construction limits, the 4300-digit
+integer limit, duplicate keys, NaN/Infinity, the depth-64 and node ceilings, prompt
+node key filtering and the carrier rule. `records: null` stands for an unreadable
+file. `expect` pins both graph statuses; `needs` names an interpreter feature a case
+depends on. `tests/js/workspace-local-projection.test.js` runs them through
+`web/js/workspace/local-projection.mjs`, and `tests/test_local_inspect_parity.py`
+asserts that its answer equals `utils.inspection_response._metadata` byte for byte.
+All texts are original synthetic content, dedicated to the public domain under
+CC0-1.0.
+
 # Inspection parity fixtures
 
 `inspection_parity/` holds small synthetic PNGs (`f01b.png` ... `f24.png`, each

tests/fixtures/local-inspect/projection-cases.json

@@ -0,0 +1,849 @@
+{
+ "version": 1,
+ "about": "Synthetic record sets for utils/inspection_response.py _metadata parity with web/js/workspace/local-projection.mjs projectMetadata. records null = an unreadable file. record_formats default to original-text for each record. expect pins both graph statuses; needs names an interpreter feature the Python side must have.",
+ "cases": [
+  {
+   "name": "unreadable_read",
+   "records": null,
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "absent_records",
+   "records": {},
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "prompt_and_workflow_parsed",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}",
+    "workflow": "{\"nodes\":[],\"version\":0.4}"
+   },
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "all_four_records",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}",
+    "workflow": "{\"nodes\":[],\"version\":0.4}",
+    "parameters": "cat\nNegative prompt: dog\nSteps: 20, Sampler: Euler, Seed: 7",
+    "comfyassets_prompt_pairs": "{\"version\":1,\"nodes\":{}}"
+   },
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "parameters_only",
+   "records": {
+    "parameters": "cat\nSteps: 20"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "number_spellings",
+   "records": {
+    "workflow": "{\"nodes\":[],\"a\":[1e3,1e0,-0.0,6.50,0.0100,1.0e2,0e5,0.0000001,0.000001,1E+3,1e-0,0.5e1,0.05e1,0.0e0,1.5e+300,123e-8,2.5e-3,1.0,-1.50,0.0,100.0,1234567e-6,0.5E-6,0.5E-5,1e22,0.000000,-0.000000e-3,7.0e-6,7.0e-7,12345678901234567890.123,9007199254740992.0]}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "integer_spellings",
+   "records": {
+    "workflow": "{\"a\":[9007199254740991,-9007199254740991,9007199254740992,-9007199254740992,10000000000000000,123456789012345678901234567890,0,-0,42,-7,100]}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "nonfinite_literals_are_null",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"n\":NaN,\"i\":Infinity,\"m\":-Infinity},\"_meta\":{\"n\":NaN}}}",
+    "workflow": "{\"a\":[NaN,Infinity,-Infinity],\"b\":NaN}"
+   },
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "exponent_edges_valid",
+   "records": {
+    "workflow": "{\"a\":[1e999999999999999999,1e-1999999999999999997,0.0e1000000000000000000,1.5e999999999999999999,0.1e-1999999999999999996]}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "exponent_edge_invalid_1e1000000000000000000",
+   "records": {
+    "workflow": "{\"a\":1e1000000000000000000}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "exponent_edge_invalid_15e999999999999999999",
+   "records": {
+    "workflow": "{\"a\":15e999999999999999999}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "exponent_edge_invalid_1e_1999999999999999998",
+   "records": {
+    "workflow": "{\"a\":1e-1999999999999999998}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "exponent_edge_invalid_1_5e_1999999999999999997",
+   "records": {
+    "workflow": "{\"a\":1.5e-1999999999999999997}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "exponent_edge_invalid_0e1000000000000000000",
+   "records": {
+    "workflow": "{\"a\":0e1000000000000000000}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "exponent_edge_invalid_1e9223372036854775808",
+   "records": {
+    "workflow": "{\"a\":1e9223372036854775808}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "exponent_edge_invalid_0_0e1000000000000000001",
+   "records": {
+    "workflow": "{\"a\":0.0e1000000000000000001}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "exponent_edge_invalid_1e99999999999999999999999999",
+   "records": {
+    "workflow": "{\"a\":1e99999999999999999999999999}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "int_4300_digits_kept",
+   "records": {
+    "workflow": "{\"a\":7777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "int_4301_digits_malformed",
+   "records": {
+    "workflow": "{\"a\":77777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777}"
+   },
+   "needs": "int-max-str-digits",
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "int_negative_4301_digits_malformed",
+   "records": {
+    "workflow": "{\"a\":-77777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777}"
+   },
+   "needs": "int-max-str-digits",
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "string_escapes",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"t\":\"é😀\\u0000\\u001f/\\\\\\\"\\b\\f\\n\\r\\t\",\"raw\":\"é😀 — 
\"}}}",
+    "workflow": "{\"s\":\"\\u00E9\\uD83D\\uDE00\\uD800\\uDC00x\\u0000\\u001f\\/\\\\\\\"\\b\\f\\n\\r\\t\\uD800\\u0041\\uDC00\"}"
+   },
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "lone_surrogate_in_raw_text",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"t\":\"𐏿\\udc00\"}}}",
+    "parameters": "\ud800 lone\nSteps: 1"
+   },
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "keys_with_escapes_proto_and_order",
+   "records": {
+    "prompt": "{\"10\":{\"class_type\":\"B\",\"inputs\":{}},\"3\":{\"class_type\":\"A\",\"inputs\":{}},\"__proto__\":{\"class_type\":\"P\",\"inputs\":{\"constructor\":1}},\"constructor\":{\"class_type\":\"C\",\"inputs\":{}},\"\\u0000\":5,\"\":[]}",
+    "workflow": "{\"10\":1,\"3\":2,\"b\":3,\"a\":4,\"__proto__\":{\"x\":1},\"\":{}}"
+   },
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "duplicate_key_top_level",
+   "records": {
+    "workflow": "{\"a\":1,\"a\":2}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "duplicate_key_nested",
+   "records": {
+    "workflow": "{\"a\":{\"b\":[{\"c\":1,\"c\":1}]}}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "duplicate_key_in_dropped_prompt_meta",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"a\":1},\"_meta\":{\"t\":1,\"t\":2}}}"
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "duplicate_key_in_prompt_inputs",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"a\":1,\"a\":1}}}"
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "duplicate_key_after_deep_nest",
+   "records": {
+    "workflow": "{\"x\":[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]],\"a\":1,\"a\":2}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "workflow_depth_64_kept",
+   "records": {
+    "workflow": "{\"a\":[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "workflow_depth_65_limited",
+   "records": {
+    "workflow": "{\"a\":[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "limited"
+   }
+  },
+  {
+   "name": "prompt_inputs_depth_64_kept",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"v\":[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]}}}"
+   },
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "prompt_inputs_depth_65_limited",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"v\":[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]}}}"
+   },
+   "expect": {
+    "prompt_graph": "limited",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "prompt_dropped_meta_depth_65_limited",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{},\"_meta\":{\"v\":[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]}}}"
+   },
+   "expect": {
+    "prompt_graph": "limited",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "prompt_non_object_nodes_kept",
+   "records": {
+    "prompt": "{\"1\":5,\"2\":[1,2.50,\"x\",null,true],\"3\":\"s\",\"4\":null,\"5\":{\"inputs\":[1],\"class_type\":null,\"other\":{\"deep\":[NaN]}}}"
+   },
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "prompt_root_array_malformed",
+   "records": {
+    "prompt": "[]"
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "prompt_root_string_malformed",
+   "records": {
+    "prompt": "\"{}\""
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "prompt_root_number_malformed",
+   "records": {
+    "prompt": "5"
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "prompt_root_null_malformed",
+   "records": {
+    "prompt": "null"
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "workflow_root_array_malformed",
+   "records": {
+    "workflow": "[1,2]"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "workflow_root_nan_malformed",
+   "records": {
+    "workflow": "NaN"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "empty_text_malformed",
+   "records": {
+    "prompt": "",
+    "workflow": "   "
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "bom_malformed",
+   "records": {
+    "workflow": "{}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "trailing_data_malformed",
+   "records": {
+    "workflow": "{\"a\":1} x",
+    "prompt": "{}\u0000"
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "python_whitespace_only",
+   "records": {
+    "workflow": " \t\r\n{\n\t\"a\" :\r 1 }\n",
+    "prompt": "\u000b{}"
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "syntax_errors",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{},}}",
+    "workflow": "[1,]"
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "bad_escape_and_control_char",
+   "records": {
+    "prompt": "{\"1\":\"\\x\"}",
+    "workflow": "{\"a\":\"\u0001\"}"
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "number_grammar",
+   "records": {
+    "prompt": "{\"1\":01}",
+    "workflow": "{\"a\":1.,\"b\":.5}"
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "nodes_not_list_counts_zero",
+   "records": {
+    "workflow": "{\"nodes\":{\"a\":1},\"definitions\":{\"subgraphs\":[{\"nodes\":5},7,{\"nodes\":[1,2]}]}}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "limited_workflow_record",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}",
+    "workflow": "{\"nodes\":[],\"version\":0.4}"
+   },
+   "limited": [
+    "workflow"
+   ],
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "limited"
+   }
+  },
+  {
+   "name": "limited_workflow_without_text",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}"
+   },
+   "limited": [
+    "workflow"
+   ],
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "limited"
+   }
+  },
+  {
+   "name": "invalid_workflow_format",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}"
+   },
+   "record_formats": {
+    "prompt": "original-text",
+    "workflow": "invalid"
+   },
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "reserialized_without_carrier_is_limited",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}",
+    "workflow": "{\"nodes\":[],\"version\":0.4}"
+   },
+   "record_formats": {
+    "prompt": "reserialized-json",
+    "workflow": "reserialized-json"
+   },
+   "expect": {
+    "prompt_graph": "limited",
+    "workflow_graph": "limited"
+   }
+  },
+  {
+   "name": "unknown_format_dropped_but_projected",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}"
+   },
+   "record_formats": {
+    "prompt": "weird"
+   },
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "non_text_record_dropped",
+   "records": {
+    "prompt": 5,
+    "workflow": "{\"nodes\":[],\"version\":0.4}"
+   },
+   "record_formats": {
+    "prompt": "original-text",
+    "workflow": "original-text"
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "format_without_text_is_malformed",
+   "records": {},
+   "record_formats": {
+    "prompt": "original-text"
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "unknown_record_keys_ignored",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}",
+    "Software": "ComfyUI",
+    "WORKFLOW": "{\"nodes\":[],\"version\":0.4}"
+   },
+   "record_formats": {
+    "prompt": "original-text",
+    "Software": "original-text",
+    "WORKFLOW": "original-text"
+   },
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "carrier_prompt_string_workflow_object",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}",
+    "workflow": "{\"nodes\": [], \"v\": 1}"
+   },
+   "record_formats": {
+    "prompt": "original-text",
+    "workflow": "reserialized-json"
+   },
+   "carrier_text": "{\"prompt\":\"{\\\"1\\\":{\\\"class_type\\\":\\\"A\\\",\\\"inputs\\\":{\\\"x\\\":1}}}\",\"workflow\":{\"nodes\":[],\"v\":1}}",
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "carrier_prompt_object_projected",
+   "records": {
+    "prompt": "{\"1\": {\"class_type\": \"A\", \"inputs\": {\"x\": 8.0}, \"_meta\": {\"t\": \"x\"}}}",
+    "workflow": "{\"nodes\":[],\"version\":0.4}"
+   },
+   "record_formats": {
+    "prompt": "reserialized-json",
+    "workflow": "original-text"
+   },
+   "carrier_text": "{\"prompt\":{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":8.0},\"_meta\":{\"t\":\"x\"}}},\"workflow\":{\"nodes\":[],\"version\":0.4},\"title\":\"n\",\"extra\":[1e3]}",
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "carrier_root_array_fails_all",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}",
+    "workflow": "{\"nodes\":[],\"version\":0.4}"
+   },
+   "carrier_text": "[1]",
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "carrier_duplicate_key_fails_all",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}"
+   },
+   "carrier_text": "{\"prompt\":\"{}\",\"prompt\":\"{}\"}",
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "carrier_other_member_too_deep_limited",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}"
+   },
+   "carrier_text": "{\"title\":[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]],\"prompt\":\"{\\\"1\\\":{\\\"class_type\\\":\\\"A\\\",\\\"inputs\\\":{\\\"x\\\":1}}}\"}",
+   "expect": {
+    "prompt_graph": "limited",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "carrier_other_member_depth_64_kept",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}"
+   },
+   "carrier_text": "{\"title\":[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]],\"prompt\":\"{\\\"1\\\":{\\\"class_type\\\":\\\"A\\\",\\\"inputs\\\":{\\\"x\\\":1}}}\"}",
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "carrier_prompt_object_depth_shift",
+   "records": {
+    "prompt": "x"
+   },
+   "record_formats": {
+    "prompt": "reserialized-json"
+   },
+   "carrier_text": "{\"prompt\":{\"1\":{\"class_type\":\"A\",\"inputs\":{\"v\":[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]}}}}",
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "carrier_prompt_object_depth_shift_limited",
+   "records": {
+    "prompt": "x"
+   },
+   "record_formats": {
+    "prompt": "reserialized-json"
+   },
+   "carrier_text": "{\"prompt\":{\"1\":{\"class_type\":\"A\",\"inputs\":{\"v\":[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]}}}}",
+   "expect": {
+    "prompt_graph": "limited",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "carrier_prompt_string_invalid_json",
+   "records": {
+    "prompt": "{",
+    "workflow": "{\"nodes\":[],\"version\":0.4}"
+   },
+   "carrier_text": "{\"prompt\":\"{\",\"workflow\":\"{\\\"nodes\\\":[],\\\"version\\\":0.4}\"}",
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "carrier_prompt_string_too_deep",
+   "records": {
+    "prompt": "x"
+   },
+   "carrier_text": "{\"prompt\":\"{\\\"1\\\":{\\\"class_type\\\":\\\"A\\\",\\\"inputs\\\":{\\\"v\\\":[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]}}}\"}",
+   "expect": {
+    "prompt_graph": "limited",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "carrier_workflow_number_malformed",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}",
+    "workflow": "5"
+   },
+   "record_formats": {
+    "prompt": "original-text",
+    "workflow": "original-text"
+   },
+   "carrier_text": "{\"prompt\":\"{\\\"1\\\":{\\\"class_type\\\":\\\"A\\\",\\\"inputs\\\":{\\\"x\\\":1}}}\",\"workflow\":5}",
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "carrier_prompt_nonfinite_malformed",
+   "records": {
+    "prompt": "NaN"
+   },
+   "carrier_text": "{\"prompt\":NaN}",
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "carrier_prompt_bigint_malformed",
+   "records": {
+    "prompt": "123456789012345678901"
+   },
+   "carrier_text": "{\"prompt\":123456789012345678901}",
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "carrier_prompt_decimal_malformed",
+   "records": {
+    "prompt": "1.5"
+   },
+   "carrier_text": "{\"prompt\":1.5}",
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "carrier_missing_member_malformed",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}"
+   },
+   "carrier_text": "{\"workflow\":{}}",
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "carrier_without_graph_records",
+   "records": {
+    "parameters": "cat"
+   },
+   "carrier_text": "{\"parameters\":\"cat\"}",
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "carrier_with_limited_workflow",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}"
+   },
+   "limited": [
+    "workflow"
+   ],
+   "carrier_text": "{\"prompt\":\"{\\\"1\\\":{\\\"class_type\\\":\\\"A\\\",\\\"inputs\\\":{\\\"x\\\":1}}}\"}",
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "limited"
+   }
+  },
+  {
+   "name": "carrier_invalid_workflow_format",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}"
+   },
+   "record_formats": {
+    "prompt": "original-text",
+    "workflow": "invalid"
+   },
+   "carrier_text": "{\"prompt\":\"{\\\"1\\\":{\\\"class_type\\\":\\\"A\\\",\\\"inputs\\\":{\\\"x\\\":1}}}\",\"workflow\":null}",
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "carrier_non_string_text_malformed",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}"
+   },
+   "carrier_text": "",
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  }
+ ]
+}

tests/fixtures/local-inspect/video-tags-v1.json

@@ -0,0 +1,60 @@
+{
+  "generator": "ffmpeg -show_entries format_tags -of json over tests/fixtures/local-inspect, see tests/fixtures/README.md",
+  "fixtures": {
+    "core-faststart.mp4": {
+      "major_brand": "isom",
+      "minor_version": "512",
+      "compatible_brands": "isomiso2avc1mp41",
+      "prompt": "{\"3\":{\"class_type\":\"KSampler\",\"inputs\":{\"seed\":7,\"steps\":20,\"cfg\":8.0,\"sampler_name\":\"euler\",\"scheduler\":\"normal\",\"denoise\":1.0,\"model\":[\"4\",0],\"positive\":[\"6\",0],\"negative\":[\"7\",0],\"latent_image\":[\"5\",0]}},\"4\":{\"class_type\":\"CheckpointLoaderSimple\",\"inputs\":{\"ckpt_name\":\"synthetic-v1.safetensors\"}},\"5\":{\"class_type\":\"EmptyLatentImage\",\"inputs\":{\"width\":512,\"height\":512,\"batch_size\":1}},\"6\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"text\":\"a red fox in snow, detailed fur\",\"clip\":[\"4\",1]}},\"7\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"text\":\"blurry, lowres\",\"clip\":[\"4\",1]}},\"8\":{\"class_type\":\"VAEDecode\",\"inputs\":{\"samples\":[\"3\",0],\"vae\":[\"4\",2]}},\"9\":{\"class_type\":\"SaveVideo\",\"inputs\":{\"filename_prefix\":\"video/synthetic\",\"video\":[\"8\",0]}}}",
+      "workflow": "{\"last_node_id\":9,\"nodes\":[{\"id\":3,\"type\":\"KSampler\",\"widgets_values\":[7,\"fixed\",20,8.0,\"euler\",\"normal\",1.0]},{\"id\":6,\"type\":\"CLIPTextEncode\",\"widgets_values\":[\"a red fox in snow, detailed fur\"]},{\"id\":7,\"type\":\"CLIPTextEncode\",\"widgets_values\":[\"blurry, lowres\"]}],\"links\":[],\"version\":0.4}",
+      "parameters": "a red fox in snow, detailed fur\nNegative prompt: blurry, lowres\nSteps: 20, Sampler: Euler, CFG scale: 8.0, Seed: 7, Size: 512x512",
+      "comfyassets_prompt_pairs": "{\"version\":1,\"nodes\":{\"6\":{\"records\":[{\"positive_text\":\"a red fox in snow, detailed fur\",\"negative_text\":\"blurry, lowres\",\"negative_effective_text\":\"blurry, lowres\",\"prepend_text\":\"\",\"append_text\":\"\"}]}}}",
+      "encoder": "Lavf63.1.102"
+    },
+    "core-moov-end.mp4": {
+      "major_brand": "isom",
+      "minor_version": "512",
+      "compatible_brands": "isomiso2avc1mp41",
+      "prompt": "{\"3\":{\"class_type\":\"KSampler\",\"inputs\":{\"seed\":7,\"steps\":20,\"cfg\":8.0,\"sampler_name\":\"euler\",\"scheduler\":\"normal\",\"denoise\":1.0,\"model\":[\"4\",0],\"positive\":[\"6\",0],\"negative\":[\"7\",0],\"latent_image\":[\"5\",0]}},\"4\":{\"class_type\":\"CheckpointLoaderSimple\",\"inputs\":{\"ckpt_name\":\"synthetic-v1.safetensors\"}},\"5\":{\"class_type\":\"EmptyLatentImage\",\"inputs\":{\"width\":512,\"height\":512,\"batch_size\":1}},\"6\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"text\":\"a red fox in snow, detailed fur\",\"clip\":[\"4\",1]}},\"7\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"text\":\"blurry, lowres\",\"clip\":[\"4\",1]}},\"8\":{\"class_type\":\"VAEDecode\",\"inputs\":{\"samples\":[\"3\",0],\"vae\":[\"4\",2]}},\"9\":{\"class_type\":\"SaveVideo\",\"inputs\":{\"filename_prefix\":\"video/synthetic\",\"video\":[\"8\",0]}}}",
+      "workflow": "{\"last_node_id\":9,\"nodes\":[{\"id\":3,\"type\":\"KSampler\",\"widgets_values\":[7,\"fixed\",20,8.0,\"euler\",\"normal\",1.0]},{\"id\":6,\"type\":\"CLIPTextEncode\",\"widgets_values\":[\"a red fox in snow, detailed fur\"]},{\"id\":7,\"type\":\"CLIPTextEncode\",\"widgets_values\":[\"blurry, lowres\"]}],\"links\":[],\"version\":0.4}",
+      "encoder": "Lavf63.1.102"
+    },
+    "core.mov": {
+      "major_brand": "qt  ",
+      "minor_version": "512",
+      "compatible_brands": "qt  ",
+      "prompt": "{\"3\":{\"class_type\":\"KSampler\",\"inputs\":{\"seed\":7,\"steps\":20,\"cfg\":8.0,\"sampler_name\":\"euler\",\"scheduler\":\"normal\",\"denoise\":1.0,\"model\":[\"4\",0],\"positive\":[\"6\",0],\"negative\":[\"7\",0],\"latent_image\":[\"5\",0]}},\"4\":{\"class_type\":\"CheckpointLoaderSimple\",\"inputs\":{\"ckpt_name\":\"synthetic-v1.safetensors\"}},\"5\":{\"class_type\":\"EmptyLatentImage\",\"inputs\":{\"width\":512,\"height\":512,\"batch_size\":1}},\"6\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"text\":\"a red fox in snow, detailed fur\",\"clip\":[\"4\",1]}},\"7\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"text\":\"blurry, lowres\",\"clip\":[\"4\",1]}},\"8\":{\"class_type\":\"VAEDecode\",\"inputs\":{\"samples\":[\"3\",0],\"vae\":[\"4\",2]}},\"9\":{\"class_type\":\"SaveVideo\",\"inputs\":{\"filename_prefix\":\"video/synthetic\",\"video\":[\"8\",0]}}}",
+      "workflow": "{\"last_node_id\":9,\"nodes\":[{\"id\":3,\"type\":\"KSampler\",\"widgets_values\":[7,\"fixed\",20,8.0,\"euler\",\"normal\",1.0]},{\"id\":6,\"type\":\"CLIPTextEncode\",\"widgets_values\":[\"a red fox in snow, detailed fur\"]},{\"id\":7,\"type\":\"CLIPTextEncode\",\"widgets_values\":[\"blurry, lowres\"]}],\"links\":[],\"version\":0.4}",
+      "encoder": "Lavf63.1.102"
+    },
+    "core.m4v": {
+      "major_brand": "M4V ",
+      "minor_version": "512",
+      "compatible_brands": "M4V isomiso2avc1",
+      "prompt": "{\"3\":{\"class_type\":\"KSampler\",\"inputs\":{\"seed\":7,\"steps\":20,\"cfg\":8.0,\"sampler_name\":\"euler\",\"scheduler\":\"normal\",\"denoise\":1.0,\"model\":[\"4\",0],\"positive\":[\"6\",0],\"negative\":[\"7\",0],\"latent_image\":[\"5\",0]}},\"4\":{\"class_type\":\"CheckpointLoaderSimple\",\"inputs\":{\"ckpt_name\":\"synthetic-v1.safetensors\"}},\"5\":{\"class_type\":\"EmptyLatentImage\",\"inputs\":{\"width\":512,\"height\":512,\"batch_size\":1}},\"6\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"text\":\"a red fox in snow, detailed fur\",\"clip\":[\"4\",1]}},\"7\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"text\":\"blurry, lowres\",\"clip\":[\"4\",1]}},\"8\":{\"class_type\":\"VAEDecode\",\"inputs\":{\"samples\":[\"3\",0],\"vae\":[\"4\",2]}},\"9\":{\"class_type\":\"SaveVideo\",\"inputs\":{\"filename_prefix\":\"video/synthetic\",\"video\":[\"8\",0]}}}",
+      "workflow": "{\"last_node_id\":9,\"nodes\":[{\"id\":3,\"type\":\"KSampler\",\"widgets_values\":[7,\"fixed\",20,8.0,\"euler\",\"normal\",1.0]},{\"id\":6,\"type\":\"CLIPTextEncode\",\"widgets_values\":[\"a red fox in snow, detailed fur\"]},{\"id\":7,\"type\":\"CLIPTextEncode\",\"widgets_values\":[\"blurry, lowres\"]}],\"links\":[],\"version\":0.4}",
+      "encoder": "Lavf63.1.102"
+    },
+    "core.mkv": {
+      "WORKFLOW": "{\"last_node_id\":9,\"nodes\":[{\"id\":3,\"type\":\"KSampler\",\"widgets_values\":[7,\"fixed\",20,8.0,\"euler\",\"normal\",1.0]},{\"id\":6,\"type\":\"CLIPTextEncode\",\"widgets_values\":[\"a red fox in snow, detailed fur\"]},{\"id\":7,\"type\":\"CLIPTextEncode\",\"widgets_values\":[\"blurry, lowres\"]}],\"links\":[],\"version\":0.4}",
+      "PROMPT": "{\"3\":{\"class_type\":\"KSampler\",\"inputs\":{\"seed\":7,\"steps\":20,\"cfg\":8.0,\"sampler_name\":\"euler\",\"scheduler\":\"normal\",\"denoise\":1.0,\"model\":[\"4\",0],\"positive\":[\"6\",0],\"negative\":[\"7\",0],\"latent_image\":[\"5\",0]}},\"4\":{\"class_type\":\"CheckpointLoaderSimple\",\"inputs\":{\"ckpt_name\":\"synthetic-v1.safetensors\"}},\"5\":{\"class_type\":\"EmptyLatentImage\",\"inputs\":{\"width\":512,\"height\":512,\"batch_size\":1}},\"6\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"text\":\"a red fox in snow, detailed fur\",\"clip\":[\"4\",1]}},\"7\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"text\":\"blurry, lowres\",\"clip\":[\"4\",1]}},\"8\":{\"class_type\":\"VAEDecode\",\"inputs\":{\"samples\":[\"3\",0],\"vae\":[\"4\",2]}},\"9\":{\"class_type\":\"SaveVideo\",\"inputs\":{\"filename_prefix\":\"video/synthetic\",\"video\":[\"8\",0]}}}",
+      "ENCODER": "Lavf63.1.102"
+    },
+    "core-tags.webm": {
+      "WORKFLOW": "{\"last_node_id\":9,\"nodes\":[{\"id\":3,\"type\":\"KSampler\",\"widgets_values\":[7,\"fixed\",20,8.0,\"euler\",\"normal\",1.0]},{\"id\":6,\"type\":\"CLIPTextEncode\",\"widgets_values\":[\"a red fox in snow, detailed fur\"]},{\"id\":7,\"type\":\"CLIPTextEncode\",\"widgets_values\":[\"blurry, lowres\"]}],\"links\":[],\"version\":0.4}",
+      "PROMPT": "{\"3\":{\"class_type\":\"KSampler\",\"inputs\":{\"seed\":7,\"steps\":20,\"cfg\":8.0,\"sampler_name\":\"euler\",\"scheduler\":\"normal\",\"denoise\":1.0,\"model\":[\"4\",0],\"positive\":[\"6\",0],\"negative\":[\"7\",0],\"latent_image\":[\"5\",0]}},\"4\":{\"class_type\":\"CheckpointLoaderSimple\",\"inputs\":{\"ckpt_name\":\"synthetic-v1.safetensors\"}},\"5\":{\"class_type\":\"EmptyLatentImage\",\"inputs\":{\"width\":512,\"height\":512,\"batch_size\":1}},\"6\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"text\":\"a red fox in snow, detailed fur\",\"clip\":[\"4\",1]}},\"7\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"text\":\"blurry, lowres\",\"clip\":[\"4\",1]}},\"8\":{\"class_type\":\"VAEDecode\",\"inputs\":{\"samples\":[\"3\",0],\"vae\":[\"4\",2]}},\"9\":{\"class_type\":\"SaveVideo\",\"inputs\":{\"filename_prefix\":\"video/synthetic\",\"video\":[\"8\",0]}}}",
+      "ENCODER": "Lavf63.1.102"
+    },
+    "legacy-comment.mp4": {
+      "major_brand": "isom",
+      "minor_version": "512",
+      "compatible_brands": "isomiso2avc1mp41",
+      "encoder": "Lavf63.1.102",
+      "comment": "{\"prompt\": \"{\\\"3\\\":{\\\"class_type\\\":\\\"KSampler\\\",\\\"inputs\\\":{\\\"seed\\\":7,\\\"steps\\\":20,\\\"cfg\\\":8.0,\\\"sampler_name\\\":\\\"euler\\\",\\\"scheduler\\\":\\\"normal\\\",\\\"denoise\\\":1.0,\\\"model\\\":[\\\"4\\\",0],\\\"positive\\\":[\\\"6\\\",0],\\\"negative\\\":[\\\"7\\\",0],\\\"latent_image\\\":[\\\"5\\\",0]}},\\\"4\\\":{\\\"class_type\\\":\\\"CheckpointLoaderSimple\\\",\\\"inputs\\\":{\\\"ckpt_name\\\":\\\"synthetic-v1.safetensors\\\"}},\\\"5\\\":{\\\"class_type\\\":\\\"EmptyLatentImage\\\",\\\"inputs\\\":{\\\"width\\\":512,\\\"height\\\":512,\\\"batch_size\\\":1}},\\\"6\\\":{\\\"class_type\\\":\\\"CLIPTextEncode\\\",\\\"inputs\\\":{\\\"text\\\":\\\"a red fox in snow, detailed fur\\\",\\\"clip\\\":[\\\"4\\\",1]}},\\\"7\\\":{\\\"class_type\\\":\\\"CLIPTextEncode\\\",\\\"inputs\\\":{\\\"text\\\":\\\"blurry, lowres\\\",\\\"clip\\\":[\\\"4\\\",1]}},\\\"8\\\":{\\\"class_type\\\":\\\"VAEDecode\\\",\\\"inputs\\\":{\\\"samples\\\":[\\\"3\\\",0],\\\"vae\\\":[\\\"4\\\",2]}},\\\"9\\\":{\\\"class_type\\\":\\\"SaveVideo\\\",\\\"inputs\\\":{\\\"filename_prefix\\\":\\\"video/synthetic\\\",\\\"video\\\":[\\\"8\\\",0]}}}\", \"workflow\": {\"last_node_id\": 9, \"nodes\": [{\"id\": 3, \"type\": \"KSampler\", \"widgets_values\": [7, \"fixed\", 20, 8.0, \"euler\", \"normal\", 1.0]}, {\"id\": 6, \"type\": \"CLIPTextEncode\", \"widgets_values\": [\"a red fox in snow, detailed fur\"]}, {\"id\": 7, \"type\": \"CLIPTextEncode\", \"widgets_values\": [\"blurry, lowres\"]}], \"links\": [], \"version\": 0.4}}"
+    },
+    "legacy-comment.webm": {
+      "COMMENT": "{\"prompt\": \"{\\\"3\\\":{\\\"class_type\\\":\\\"KSampler\\\",\\\"inputs\\\":{\\\"seed\\\":7,\\\"steps\\\":20,\\\"cfg\\\":8.0,\\\"sampler_name\\\":\\\"euler\\\",\\\"scheduler\\\":\\\"normal\\\",\\\"denoise\\\":1.0,\\\"model\\\":[\\\"4\\\",0],\\\"positive\\\":[\\\"6\\\",0],\\\"negative\\\":[\\\"7\\\",0],\\\"latent_image\\\":[\\\"5\\\",0]}},\\\"4\\\":{\\\"class_type\\\":\\\"CheckpointLoaderSimple\\\",\\\"inputs\\\":{\\\"ckpt_name\\\":\\\"synthetic-v1.safetensors\\\"}},\\\"5\\\":{\\\"class_type\\\":\\\"EmptyLatentImage\\\",\\\"inputs\\\":{\\\"width\\\":512,\\\"height\\\":512,\\\"batch_size\\\":1}},\\\"6\\\":{\\\"class_type\\\":\\\"CLIPTextEncode\\\",\\\"inputs\\\":{\\\"text\\\":\\\"a red fox in snow, detailed fur\\\",\\\"clip\\\":[\\\"4\\\",1]}},\\\"7\\\":{\\\"class_type\\\":\\\"CLIPTextEncode\\\",\\\"inputs\\\":{\\\"text\\\":\\\"blurry, lowres\\\",\\\"clip\\\":[\\\"4\\\",1]}},\\\"8\\\":{\\\"class_type\\\":\\\"VAEDecode\\\",\\\"inputs\\\":{\\\"samples\\\":[\\\"3\\\",0],\\\"vae\\\":[\\\"4\\\",2]}},\\\"9\\\":{\\\"class_type\\\":\\\"SaveVideo\\\",\\\"inputs\\\":{\\\"filename_prefix\\\":\\\"video/synthetic\\\",\\\"video\\\":[\\\"8\\\",0]}}}\", \"workflow\": {\"last_node_id\": 9, \"nodes\": [{\"id\": 3, \"type\": \"KSampler\", \"widgets_values\": [7, \"fixed\", 20, 8.0, \"euler\", \"normal\", 1.0]}, {\"id\": 6, \"type\": \"CLIPTextEncode\", \"widgets_values\": [\"a red fox in snow, detailed fur\"]}, {\"id\": 7, \"type\": \"CLIPTextEncode\", \"widgets_values\": [\"blurry, lowres\"]}], \"links\": [], \"version\": 0.4}}",
+      "ENCODER": "Lavf63.1.102"
+    }
+  }
+}

tests/js/helpers/png-bytes.mjs

@@ -0,0 +1,148 @@
+// Byte-exact PNG builders for the local reader tests (real CRC32 and zlib), and
+// File-like blobs: one that records every [start, end) slice over a sparse layout
+// that is never allocated, one that answers slowly, one that fails or shrinks.
+import zlib from "node:zlib";
+
+export const SIGNATURE = Uint8Array.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+export function u32(n) {
+    return Uint8Array.from([(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff]);
+}
+
+export function latin1(text) {
+    return Buffer.from(text, "latin1");
+}
+
+export function utf8(text) {
+    return Buffer.from(text, "utf8");
+}
+
+export function concat(...parts) {
+    return Uint8Array.from(Buffer.concat(parts.map((part) => Buffer.from(part))));
+}
+
+/**
+ * One chunk with a real CRC32 over type + data. `crc` overrides the checksum and
+ * `declaredLength` the length field (to declare more data than is present).
+ */
+export function chunk(type, data, { crc, declaredLength } = {}) {
+    const typeBytes = latin1(type);
+    const body = Buffer.from(data);
+    const sum = crc ?? zlib.crc32(Buffer.concat([typeBytes, body]));
+    return concat(u32(declaredLength ?? body.length), typeBytes, body, u32(sum));
+}
+
+export function ihdr(width = 1, height = 1, options) {
+    return chunk("IHDR", concat(u32(width), u32(height), [8, 6, 0, 0, 0]), options);
+}
+
+export function idat(data = [0]) {
+    return chunk("IDAT", data);
+}
+
+export function iend(options) {
+    return chunk("IEND", [], options);
+}
+
+/** tEXt: keyword NUL text, Latin-1 (text may be a string or raw bytes). */
+export function tEXt(keyword, text, options) {
+    const body = typeof text === "string" ? latin1(text) : Buffer.from(text);
+    return chunk("tEXt", concat(latin1(keyword), [0], body), options);
+}
+
+/** zTXt: keyword NUL method zlib(text). `compressed` replaces the deflated body. */
+export function zTXt(keyword, text, { method = 0, compressed, level = 6 } = {}) {
+    const body = compressed ?? zlib.deflateSync(typeof text === "string" ? latin1(text) : Buffer.from(text), { level });
+    return chunk("zTXt", concat(latin1(keyword), [0, method], body));
+}
+
+/** iTXt: keyword NUL flag method lang NUL translated NUL text (UTF-8, deflated when flag). */
+export function iTXt(keyword, text, { flag = 0, method = 0, lang = "", translated = "", compressed } = {}) {
+    const raw = typeof text === "string" ? utf8(text) : Buffer.from(text);
+    const body = compressed ?? (flag ? zlib.deflateSync(raw) : raw);
+    const langBytes = typeof lang === "string" ? latin1(lang) : Buffer.from(lang);
+    const translatedBytes = typeof translated === "string" ? utf8(translated) : Buffer.from(translated);
+    return concat(chunk("iTXt", concat(latin1(keyword), [0, flag, method], langBytes, [0], translatedBytes, [0], body)));
+}
+
+/** A whole PNG: signature, IHDR, IDAT, the given chunks, IEND. */
+export function png(...chunks) {
+    return concat(SIGNATURE, ihdr(), idat(), ...chunks, iend());
+}
+
+/** Signature plus exactly the given chunks (no implied IHDR/IDAT/IEND). */
+export function raw(...chunks) {
+    return concat(SIGNATURE, ...chunks);
+}
+
+export function blobOf(bytes) {
+    return new Blob([bytes]);
+}
+
+/**
+ * A File-like object over a sparse layout: `parts` are [{offset, bytes}] placed in a
+ * file of `size` bytes, zero everywhere else; nothing of `size` is allocated. Every
+ * slice is recorded in `ranges` as [start, end).
+ */
+export function sparseBlob(parts, size) {
+    const ranges = [];
+    function bytesOf(start, end) {
+        const out = new Uint8Array(end - start);
+        for (const part of parts) {
+            const from = Math.max(start, part.offset);
+            const to = Math.min(end, part.offset + part.bytes.length);
+            if (from < to) out.set(part.bytes.subarray(from - part.offset, to - part.offset), from - start);
+        }
+        return out;
+    }
+    return {
+        size,
+        ranges,
+        slice(start, end) {
+            ranges.push([start, end]);
+            return { arrayBuffer: async () => bytesOf(start, end).buffer };
+        },
+    };
+}
+
+/** A recording blob over real bytes. */
+export function recordingBlob(bytes) {
+    return sparseBlob([{ offset: 0, bytes }], bytes.length);
+}
+
+/** Every slice resolves after `delayMs`. */
+export function slowBlob(bytes, delayMs) {
+    return {
+        size: bytes.length,
+        slice(start, end) {
+            return {
+                arrayBuffer: () => new Promise((resolve) => setTimeout(() => resolve(bytes.slice(start, end).buffer), delayMs)),
+            };
+        },
+    };
+}
+
+/** Slices fail (as a browser does when the file vanished). */
+export function failingBlob(size) {
+    return {
+        size,
+        slice() {
+            return { arrayBuffer: () => Promise.reject(new Error("NotReadableError")) };
+        },
+    };
+}
+
+/** Reports `size` but every slice beyond `actual` bytes comes back short. */
+export function shrunkBlob(bytes, size) {
+    return {
+        size,
+        slice(start, end) {
+            return { arrayBuffer: async () => bytes.slice(start, Math.min(end, bytes.length)).buffer };
+        },
+    };
+}
+
+/** An A1111 `parameters` record with one settings footer carrying a batch index. */
+export function parametersText(positive, batchIndex, { seedField = "Seed: 1" } = {}) {
+    return `${positive}\nNegative prompt: blurry\nSteps: 20, Sampler: Euler, Batch index: ${batchIndex}, ${seedField}`;
+}

tests/js/helpers/video-bytes.mjs

@@ -0,0 +1,277 @@
+// Byte-exact ISO-BMFF (MP4/MOV/M4V) and Matroska (MKV/WebM) builders for the local
+// video tag reader tests, laid out as ffmpeg's muxers write them (see the dumps in
+// tests/fixtures/local-inspect). The File-like blobs come from png-bytes.mjs.
+import { concat, u32, utf8, latin1 } from "./png-bytes.mjs";
+
+export { concat, u32, utf8, latin1 };
+export { sparseBlob, recordingBlob, slowBlob, failingBlob, blobOf } from "./png-bytes.mjs";
+
+const toBytes = (part) => (typeof part === "string" ? utf8(part) : Buffer.from(part));
+
+function u64(n) {
+    const out = new Uint8Array(8);
+    new DataView(out.buffer).setBigUint64(0, BigInt(n));
+    return out;
+}
+
+// ---------------------------------------------------------------- ISO-BMFF
+
+/** A box: 32-bit size, 4-byte type (string or raw bytes), payload. `size` overrides the field. */
+export function box(type, ...parts) {
+    const options = parts.length && parts[parts.length - 1] && parts[parts.length - 1].__options ? parts.pop() : {};
+    const payload = concat(...parts.map(toBytes));
+    const typeBytes = typeof type === "string" ? latin1(type) : Buffer.from(type);
+    const total = 8 + payload.length;
+    if (options.largesize) return concat(u32(1), typeBytes, u64(options.largesize === true ? total + 8 : options.largesize), payload);
+    return concat(u32(options.size ?? total), typeBytes, payload);
+}
+
+/** Marker for `box` options: box('ftyp', ..., opts({size: 3})). */
+export function opts(options) {
+    return { __options: true, ...options };
+}
+
+export function fullBox(type, ...parts) {
+    return box(type, u32(0), ...parts);
+}
+
+export function ftyp(brand = "isom", compatible = "isomiso2avc1mp41") {
+    return box("ftyp", latin1(brand), u32(512), latin1(compatible));
+}
+
+export function mdat(payload = [0, 0, 0, 0]) {
+    return box("mdat", payload);
+}
+
+export const moov = (...children) => box("moov", ...children);
+export const udta = (...children) => box("udta", ...children);
+export const free = (count = 0) => box("free", new Uint8Array(count));
+
+/** `meta` as ffmpeg writes it: a FullBox (version/flags) whose first child is hdlr. */
+export function meta(...children) {
+    return fullBox("meta", ...children);
+}
+
+export function hdlr(handler = "mdta") {
+    return fullBox("hdlr", u32(0), latin1(handler), new Uint8Array(12), [0]);
+}
+
+/** `keys`: one mdta entry per name (an entry may be [name, namespace]); `count` overrides the count field. */
+export function keys(names, { count } = {}) {
+    const entries = names.map((entry) => {
+        const [name, namespace] = Array.isArray(entry) ? entry : [entry, "mdta"];
+        const bytes = toBytes(name);
+        return concat(u32(8 + bytes.length), latin1(namespace), bytes);
+    });
+    return fullBox("keys", u32(count ?? names.length), ...entries);
+}
+
+export const ilst = (...items) => box("ilst", ...items);
+
+/** A `data` atom: type indicator (1 = UTF-8), locale, payload. */
+export function data(payload, { type = 1, locale = 0, size } = {}) {
+    return box("data", u32(type), u32(locale), toBytes(payload), ...(size === undefined ? [] : [opts({ size })]));
+}
+
+/** An ilst item addressed by its 1-based `keys` index. */
+export function item(index, ...children) {
+    return box(u32(index), ...children);
+}
+
+/** An ilst item addressed by a legacy fourcc such as "©cmt" (Latin-1 bytes). */
+export function legacyItem(fourcc, ...children) {
+    return box(latin1(fourcc), ...children);
+}
+
+/** `moov/udta/meta` carrying per-key mdta tags, as core SaveVideo writes through ffmpeg. */
+export function mdtaUdta(tags) {
+    const names = Object.keys(tags);
+    return udta(meta(hdlr("mdta"), keys(names), ilst(...names.map((name, index) => item(index + 1, data(tags[name]))))));
+}
+
+/** `moov/udta/meta` with legacy ilst atoms: {comment, description} → ©cmt / desc. */
+export function legacyUdta({ comment, description, tool = "Lavf" } = {}) {
+    const items = [legacyItem("©too", data(tool))];
+    if (comment !== undefined) items.push(legacyItem("©cmt", data(comment)));
+    if (description !== undefined) items.push(legacyItem("desc", data(description)));
+    return udta(meta(hdlr("mdir"), ilst(...items)));
+}
+
+/** A whole MP4: ftyp, (moov first when faststart), mdat, moov with the given udta. */
+export function mp4(udtaBox, { brand = "isom", faststart = false, extraMoov = [], payload } = {}) {
+    const movie = moov(...extraMoov, udtaBox);
+    const media = mdat(payload);
+    return faststart ? concat(ftyp(brand), movie, media) : concat(ftyp(brand), free(), media, movie);
+}
+
+export function perKeyMp4(tags, options) {
+    return mp4(mdtaUdta(tags), options);
+}
+
+/** Top-level boxes of `bytes` as [{type, start, end}]. */
+export function topLevelBoxes(bytes) {
+    const out = [];
+    let offset = 0;
+    while (offset + 8 <= bytes.length) {
+        const view = new DataView(bytes.buffer, bytes.byteOffset + offset);
+        let size = view.getUint32(0);
+        if (size === 1) size = Number(view.getBigUint64(8));
+        if (size === 0) size = bytes.length - offset;
+        out.push({ type: latin1Of(bytes.subarray(offset + 4, offset + 8)), start: offset, end: offset + size });
+        offset += size;
+    }
+    return out;
+}
+
+function latin1Of(bytes) {
+    return Buffer.from(bytes).toString("latin1");
+}
+
+// ---------------------------------------------------------------- Matroska
+
+export const ID = {
+    EBML: 0x1a45dfa3,
+    EBMLVersion: 0x4286,
+    DocType: 0x4282,
+    DocTypeVersion: 0x4287,
+    Segment: 0x18538067,
+    SeekHead: 0x114d9b74,
+    Seek: 0x4dbb,
+    SeekID: 0x53ab,
+    SeekPosition: 0x53ac,
+    Void: 0xec,
+    CRC32: 0xbf,
+    Info: 0x1549a966,
+    Tracks: 0x1654ae6b,
+    Tags: 0x1254c367,
+    Tag: 0x7373,
+    Targets: 0x63c0,
+    TargetTypeValue: 0x68ca,
+    TagTrackUID: 0x63c5,
+    SimpleTag: 0x67c8,
+    TagName: 0x45a3,
+    TagString: 0x4487,
+    TagLanguage: 0x447a,
+    TagDefault: 0x4484,
+    TagBinary: 0x4485,
+    Cluster: 0x1f43b675,
+    Timestamp: 0xe7,
+    Cues: 0x1c53bb6b,
+};
+
+/** The ID's bytes (EBML IDs carry their own length marker). */
+export function idBytes(id) {
+    const out = [];
+    let value = id;
+    while (value > 0) {
+        out.unshift(value & 0xff);
+        value = Math.floor(value / 256);
+    }
+    return Uint8Array.from(out);
+}
+
+/** A size VINT: minimal width unless `width` is given; `unknown` writes all ones. */
+export function vint(value, { width, unknown = false } = {}) {
+    let length = width;
+    if (!length) {
+        length = 1;
+        while (length < 8 && value >= 2 ** (7 * length) - 1) length += 1;
+    }
+    const out = new Uint8Array(length);
+    if (unknown) {
+        out.fill(0xff);
+        out[0] = 0xff >> (length - 1);
+        return out;
+    }
+    let rest = BigInt(value);
+    for (let index = length - 1; index >= 0; index -= 1) {
+        out[index] = Number(rest & 0xffn);
+        rest >>= 8n;
+    }
+    out[0] |= 0x80 >> (length - 1);
+    return out;
+}
+
+/** An element: ID, size VINT, payload. `size`/`width`/`unknown` shape the size field. */
+export function el(id, ...parts) {
+    const options = parts.length && parts[parts.length - 1] && parts[parts.length - 1].__options ? parts.pop() : {};
+    const payload = concat(...parts.map(toBytes));
+    const size = vint(options.size ?? payload.length, { width: options.width, unknown: options.unknown });
+    return concat(idBytes(id), size, payload);
+}
+
+export function uint(value, width) {
+    const out = [];
+    let rest = BigInt(value);
+    do {
+        out.unshift(Number(rest & 0xffn));
+        rest >>= 8n;
+    } while (rest > 0n);
+    while (width && out.length < width) out.unshift(0);
+    return Uint8Array.from(out);
+}
+
+export function ebmlHeader(docType = "matroska") {
+    return el(ID.EBML, el(ID.EBMLVersion, [1]), el(ID.DocType, docType), el(ID.DocTypeVersion, [4]));
+}
+
+/** Segment with an 8-byte size field as ffmpeg writes it; `unknown` makes it unknown-sized. */
+export function segment(children, { unknown = false } = {}) {
+    return el(ID.Segment, ...children, opts({ width: 8, unknown }));
+}
+
+/** SeekHead entries: [[id, position]] with positions relative to the Segment payload. */
+export function seekHead(entries) {
+    return el(ID.SeekHead, ...entries.map(([id, position]) => el(ID.Seek, el(ID.SeekID, idBytes(id)), el(ID.SeekPosition, uint(position)))));
+}
+
+export function voidEl(count = 4) {
+    return el(ID.Void, new Uint8Array(count));
+}
+
+/** A SimpleTag with TagName and TagString (`value` undefined omits the string). */
+export function simpleTag(name, value, { lang, def, binary, nested = [], extra = [] } = {}) {
+    const children = [el(ID.TagName, name)];
+    if (lang !== undefined) children.push(el(ID.TagLanguage, lang));
+    if (def !== undefined) children.push(el(ID.TagDefault, [def]));
+    if (value !== undefined) children.push(el(ID.TagString, value));
+    if (binary !== undefined) children.push(el(ID.TagBinary, binary));
+    return el(ID.SimpleTag, ...children, ...nested, ...extra);
+}
+
+/** A Tag whose Targets carry the given track UID (none → global). */
+export function tag(simpleTags, { trackUid, targetType } = {}) {
+    const targets = [];
+    if (targetType !== undefined) targets.push(el(ID.TargetTypeValue, uint(targetType)));
+    if (trackUid !== undefined) targets.push(el(ID.TagTrackUID, uint(trackUid, 8)));
+    return el(ID.Tag, el(ID.Targets, ...targets), ...simpleTags);
+}
+
+export function tagsEl(...tagElements) {
+    return el(ID.Tags, ...tagElements);
+}
+
+/** A Cluster of `size` payload bytes (zeros); `unknown` makes its size unknown. */
+export function cluster(size = 8, { unknown = false, payload } = {}) {
+    return el(ID.Cluster, payload ?? new Uint8Array(size), opts({ unknown }));
+}
+
+/** A Cluster header only, declaring `size` payload bytes (for sparse layouts). */
+export function clusterHeader(size) {
+    return concat(idBytes(ID.Cluster), vint(size, { width: 8 }));
+}
+
+/** A whole Matroska file: EBML header + Segment(children). */
+export function mkv(children, { docType = "matroska", unknown = false } = {}) {
+    return concat(ebmlHeader(docType), segment(children, { unknown }));
+}
+
+/** A global Tags element from {name: value} (ffmpeg upper-cases names at mux time). */
+export function globalTags(tags, options) {
+    return tagsEl(tag(Object.entries(tags).map(([name, value]) => simpleTag(name, value)), options));
+}
+
+/** A Matroska file whose global Tags hold {name: value}, ffmpeg layout. */
+export function perKeyMkv(tags, { docType = "matroska" } = {}) {
+    return mkv([el(ID.Info, new Uint8Array(4)), globalTags(tags), cluster()], { docType });
+}

tests/js/png-local-reader.test.js

@@ -0,0 +1,549 @@
+// Run with: node --test tests/js/
+// The browser PNG File reader is a port of utils/prompt_inspector.py's bounded
+// reader (_png_metadata, _PngRecords, _png_text, _inflate, _batch_normalized). Each
+// rule below names the Python branch it mirrors; tests/test_local_inspect_parity.py
+// proves the two agree on the committed parity corpus.
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const path = require("node:path");
+const zlib = require("node:zlib");
+const { classifyPrefix, readPngMetadataFile, readImageHeader } = require("../../web/js/png-metadata.js");
+const bytes = require("./helpers/png-bytes.mjs");
+
+const { png, raw, ihdr, idat, iend, tEXt, zTXt, iTXt, chunk, blobOf, sparseBlob, recordingBlob, slowBlob, failingBlob, shrunkBlob, concat, u32, latin1, parametersText } = bytes;
+
+const MiB = 1024 * 1024;
+const ROLE_BUDGET = 2 * MiB;
+const WORKFLOW_BUDGET = 4 * MiB;
+const PNG_READ_CEILING = 19794389;
+const FIXTURES = path.join(__dirname, "..", "fixtures", "local-inspect");
+
+async function read(fileBytes, options) {
+    return readPngMetadataFile(blobOf(fileBytes), options);
+}
+
+function fill(byte, count) {
+    return Buffer.alloc(count, byte);
+}
+
+test("contract: the reader, classifier and header reader are exported", () => {
+    assert.equal(typeof readPngMetadataFile, "function");
+    assert.equal(typeof classifyPrefix, "function");
+    assert.equal(typeof readImageHeader, "function");
+});
+
+test("reads the four retained records and the IHDR size from a core SaveImage PNG", async () => {
+    const result = await read(raw(
+        ihdr(640, 480),
+        idat(),
+        tEXt("prompt", '{"1":{"class_type":"KSampler"}}'),
+        iTXt("workflow", '{"nodes":[]}'),
+        tEXt("parameters", "cat\nSteps: 20, Seed: 1"),
+        zTXt("comfyassets_prompt_pairs", '{"pairs":[]}'),
+        tEXt("Software", "ComfyUI"),
+        iend(),
+    ));
+    assert.deepEqual(result, {
+        status: "complete",
+        records: {
+            prompt: '{"1":{"class_type":"KSampler"}}',
+            workflow: '{"nodes":[]}',
+            parameters: "cat\nSteps: 20, Seed: 1",
+            comfyassets_prompt_pairs: '{"pairs":[]}',
+        },
+        limited: [],
+        width: 640,
+        height: 480,
+    });
+});
+
+test("local PNG skips sparse pixels and reads post-IDAT text", async () => {
+    // Two 1.5 GiB IDAT chunks (each under the 0x7FFFFFFF chunk ceiling) with the
+    // prompt after them: nothing of the 3 GiB is read or allocated.
+    const half = 1.5 * 1024 * 1024 * 1024;
+    const head = concat(bytes.SIGNATURE, ihdr(8192, 8192), u32(half), latin1("IDAT"));
+    const idat1 = { start: bytes.SIGNATURE.length + ihdr().length, end: bytes.SIGNATURE.length + ihdr().length + 8 + half + 4 };
+    const idat2 = { start: idat1.end, end: idat1.end + 8 + half + 4 };
+    const between = concat(u32(0), u32(half), latin1("IDAT"));
+    const tail = concat(u32(0), tEXt("prompt", '{"3":{"class_type":"KSampler"}}'), iend());
+    const size = idat2.end - 4 + tail.length;
+    const file = sparseBlob([
+        { offset: 0, bytes: head },
+        { offset: idat1.end - 4, bytes: between },
+        { offset: idat2.end - 4, bytes: tail },
+    ], size);
+
+    const result = await readPngMetadataFile(file);
+
+    assert.equal(result.status, "complete");
+    assert.deepEqual(result.records, { prompt: '{"3":{"class_type":"KSampler"}}' });
+    assert.deepEqual([result.width, result.height], [8192, 8192]);
+    const insideIdat = file.ranges.filter(([start, end]) => [idat1, idat2].some((region) => start >= region.start && end <= region.end));
+    assert.ok(insideIdat.length >= 2, "the IDAT headers were read");
+    for (const [start, end] of insideIdat) assert.ok(end - start <= 12, `range inside IDAT longer than 12: [${start}, ${end})`);
+    const total = file.ranges.reduce((sum, [start, end]) => sum + (end - start), 0);
+    assert.ok(total <= PNG_READ_CEILING, `read ${total} bytes`);
+});
+
+test("serves the retained prefix without slicing it again", async () => {
+    const whole = png(tEXt("prompt", "p"));
+    const file = recordingBlob(whole);
+    const result = await readPngMetadataFile(file, { prefix: whole.subarray(0, 32) });
+    assert.equal(result.status, "complete");
+    assert.ok(file.ranges.every(([start]) => start >= 32), JSON.stringify(file.ranges));
+    assert.deepEqual(result.records, { prompt: "p" });
+});
+
+test("unknown text keys are skipped by length without reading their body", async () => {
+    const body = fill(0x41, 1000);
+    const whole = png(tEXt("Software", body), tEXt("prompt", "p"));
+    const softwareStart = bytes.SIGNATURE.length + ihdr().length + idat().length;
+    const bodyStart = softwareStart + 8 + "Software".length + 1;
+    const bodyEnd = bodyStart + body.length + 4;
+    const file = recordingBlob(whole);
+    const result = await readPngMetadataFile(file);
+    assert.equal(result.status, "complete");
+    const insideBody = file.ranges.filter(([start, end]) => start < bodyEnd && end > softwareStart + 8 + 80);
+    assert.deepEqual(insideBody, [], "the body past the 80-byte keyword prefix was sliced");
+});
+
+const WF_OVER = WORKFLOW_BUDGET + 1;
+const bigWorkflow = () => tEXt("workflow", fill(0x7b, WF_OVER - "workflow".length - 1));
+
+// One row per Python branch (prompt_inspector.py:91-260).
+const RULES = [
+    { name: "bad IHDR CRC", file: () => raw(ihdr(1, 1, { crc: 1 }), idat(), iend()), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "bad text CRC", file: () => png(tEXt("prompt", "p", { crc: 1 })), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "bad IEND CRC", file: () => raw(ihdr(), idat(), iend({ crc: 1 })), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "first chunk not IHDR", file: () => raw(idat(), ihdr(), iend()), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "IHDR not 13 bytes", file: () => raw(chunk("IHDR", concat(u32(1), u32(1), [8, 6, 0, 0])), idat(), iend()), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "second IHDR", file: () => raw(ihdr(), idat(), ihdr(), iend()), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "zero width", file: () => raw(ihdr(0, 1), idat(), iend()), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "zero height", file: () => raw(ihdr(1, 0), idat(), iend()), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "length 0x80000000", file: () => raw(ihdr(), idat(), chunk("tEXt", latin1("k\0v"), { declaredLength: 0x80000000 }), iend()), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "end past size", file: () => raw(ihdr(), idat(), chunk("tEXt", latin1("k\0v"), { declaredLength: 100 }), iend()), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "file ends inside a chunk header", file: () => raw(ihdr(), idat(), u32(5)), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "file ends before any chunk", file: () => raw(), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "too short for a signature", file: () => bytes.SIGNATURE.subarray(0, 5), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "not a PNG", file: () => latin1("GIF89a................................."), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "IEND without IDAT", file: () => raw(ihdr(), tEXt("prompt", "p"), iend()), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "nonzero IEND length", file: () => raw(ihdr(), idat(), chunk("IEND", [1])), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "duplicate key with a different length", file: () => png(tEXt("prompt", "one"), tEXt("prompt", "other")), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "duplicate key, same length, different bytes", file: () => png(tEXt("prompt", "one"), tEXt("prompt", "two")), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "duplicate key, same bytes, different chunk type", file: () => png(tEXt("prompt", "one"), chunk("zTXt", latin1("prompt\0one"))), expect: { status: "unreadable", reason: "invalid-png" } },
+    {
+        name: "byte-identical duplicate kept once",
+        file: () => png(tEXt("prompt", "same"), tEXt("prompt", "same"), tEXt("prompt", "same")),
+        expect: { status: "complete", records: { prompt: "same" }, limited: [], width: 1, height: 1 },
+    },
+    {
+        name: "parameters copies differing only in Batch index keep the last",
+        file: () => png(tEXt("parameters", parametersText("cat", 0)), tEXt("parameters", parametersText("cat", 1)), tEXt("parameters", parametersText("cat", 12))),
+        expect: { status: "complete", records: { parameters: parametersText("cat", 12) }, limited: [], width: 1, height: 1 },
+    },
+    { name: "parameters copies with any other difference", file: () => png(tEXt("parameters", parametersText("cat", 0)), tEXt("parameters", parametersText("dog", 1))), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "parameters copies without a settings footer", file: () => png(tEXt("parameters", "cat"), tEXt("parameters", "dog")), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "parameters copies with two footers", file: () => png(tEXt("parameters", `${parametersText("cat", 0)}\nSteps: 1, x`), tEXt("parameters", `${parametersText("cat", 1)}\nSteps: 1, x`)), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "parameters copies with two batch indexes", file: () => png(tEXt("parameters", parametersText("cat", 0, { seedField: "Batch index: 0" })), tEXt("parameters", parametersText("cat", 1, { seedField: "Batch index: 1" }))), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "parameters copies whose batch index is not a whole settings field", file: () => png(tEXt("parameters", "Steps: 20, Batch index: 0 trailing"), tEXt("parameters", "Steps: 20, Batch index: 1 trailing")), expect: { status: "unreadable", reason: "invalid-png" } },
+    {
+        name: "workflow 4 MiB + 1 encoded is limited, other records intact",
+        file: () => png(tEXt("prompt", "p"), bigWorkflow(), tEXt("parameters", "cat\nSteps: 1, x")),
+        expect: { status: "complete", records: { prompt: "p", parameters: "cat\nSteps: 1, x" }, limited: ["workflow"], width: 1, height: 1 },
+    },
+    {
+        name: "a duplicate of a limited workflow is skipped",
+        file: () => png(bigWorkflow(), bigWorkflow(), tEXt("prompt", "p")),
+        expect: { status: "complete", records: { prompt: "p" }, limited: ["workflow"], width: 1, height: 1 },
+    },
+    {
+        name: "workflow over 4 MiB decoded (zTXt) is limited",
+        file: () => png(zTXt("workflow", fill(0x7b, WORKFLOW_BUDGET + 1), { level: 9 }), tEXt("prompt", "p")),
+        expect: { status: "complete", records: { prompt: "p" }, limited: ["workflow"], width: 1, height: 1 },
+    },
+    {
+        name: "workflow at exactly 4 MiB decoded is kept",
+        file: () => png(zTXt("workflow", fill(0x7b, WORKFLOW_BUDGET), { level: 9 })),
+        check: (result) => {
+            assert.equal(result.status, "complete");
+            assert.equal(result.records.workflow.length, WORKFLOW_BUDGET);
+            assert.deepEqual(result.limited, []);
+        },
+    },
+    {
+        name: "workflow under 4 MiB inflated but over 4 MiB as UTF-8 is limited",
+        file: () => png(zTXt("workflow", fill(0xe9, WORKFLOW_BUDGET - 10), { level: 9 }), tEXt("prompt", "p")),
+        expect: { status: "complete", records: { prompt: "p" }, limited: ["workflow"], width: 1, height: 1 },
+    },
+    { name: "roles 2 MiB + 1 encoded", file: () => png(tEXt("prompt", fill(0x41, ROLE_BUDGET + 1 - "prompt".length - 1))), expect: { status: "unreadable", reason: "metadata-limit" } },
+    { name: "roles summed over 2 MiB encoded", file: () => png(tEXt("prompt", fill(0x41, 1.5 * MiB)), tEXt("parameters", fill(0x41, 0.5 * MiB))), expect: { status: "unreadable", reason: "metadata-limit" } },
+    { name: "roles 2 MiB + 1 decoded via zTXt", file: () => png(zTXt("prompt", fill(0x41, ROLE_BUDGET + 1), { level: 9 })), expect: { status: "unreadable", reason: "metadata-limit" } },
+    { name: "roles over 2 MiB as UTF-8 from Latin-1 high bytes", file: () => png(tEXt("prompt", fill(0xe9, MiB + 1))), expect: { status: "unreadable", reason: "metadata-limit" } },
+    {
+        name: "roles share the decoded budget across records",
+        file: () => png(zTXt("prompt", fill(0x41, 1.5 * MiB), { level: 9 }), zTXt("parameters", fill(0x41, 0.5 * MiB + 1), { level: 9 })),
+        expect: { status: "unreadable", reason: "metadata-limit" },
+    },
+    {
+        name: "roles at exactly 2 MiB decoded are kept",
+        file: () => png(zTXt("prompt", fill(0x41, 1.5 * MiB), { level: 9 }), zTXt("parameters", fill(0x41, 0.5 * MiB), { level: 9 })),
+        check: (result) => {
+            assert.equal(result.status, "complete");
+            assert.equal(result.records.prompt.length + result.records.parameters.length, ROLE_BUDGET);
+        },
+    },
+    {
+        name: "duplicate workflow bytes capped at 8 MiB: the workflow becomes limited",
+        file: () => {
+            const workflow = tEXt("workflow", fill(0x7b, 3 * MiB));
+            return png(workflow, workflow, workflow, workflow, tEXt("prompt", "p"));
+        },
+        expect: { status: "complete", records: { prompt: "p" }, limited: ["workflow"], width: 1, height: 1 },
+    },
+    {
+        name: "duplicate workflow bytes within 8 MiB keep the workflow",
+        file: () => {
+            const workflow = tEXt("workflow", fill(0x7b, 3 * MiB));
+            return png(workflow, workflow, workflow);
+        },
+        check: (result) => {
+            assert.equal(result.status, "complete");
+            assert.equal(result.records.workflow.length, 3 * MiB);
+            assert.deepEqual(result.limited, []);
+        },
+    },
+    {
+        name: "duplicate role bytes capped at 4 MiB",
+        file: () => {
+            const prompt = tEXt("prompt", fill(0x41, 1.5 * MiB));
+            return png(prompt, prompt, prompt, prompt);
+        },
+        expect: { status: "unreadable", reason: "metadata-limit" },
+    },
+    {
+        name: "duplicate decoded parameters capped at 4 MiB",
+        file: () => {
+            const copy = (index) => zTXt("parameters", parametersText(fill(0x41, 1.5 * MiB).toString("latin1"), index), { level: 9 });
+            return png(copy(0), copy(1), copy(2), copy(3));
+        },
+        expect: { status: "unreadable", reason: "metadata-limit" },
+    },
+    {
+        name: "a longer batch copy draws the growth from the role budget",
+        file: () => {
+            const base = parametersText("", 9);
+            const positive = fill(0x41, ROLE_BUDGET - base.length - 1).toString("latin1");
+            return png(zTXt("parameters", parametersText(positive, 9), { level: 9 }), zTXt("parameters", parametersText(positive, 100), { level: 9 }));
+        },
+        expect: { status: "unreadable", reason: "metadata-limit" },
+    },
+    {
+        name: "a longer batch copy within the role budget is kept",
+        file: () => {
+            const base = parametersText("", 9);
+            const positive = fill(0x41, ROLE_BUDGET - base.length - 2).toString("latin1");
+            return png(zTXt("parameters", parametersText(positive, 9), { level: 9 }), zTXt("parameters", parametersText(positive, 10), { level: 9 }));
+        },
+        check: (result) => {
+            assert.equal(result.status, "complete");
+            assert.ok(result.records.parameters.endsWith("Batch index: 10, Seed: 1"));
+        },
+    },
+    {
+        name: "a batch copy inflating past the role budget",
+        file: () => png(tEXt("parameters", parametersText("cat", 0)), zTXt("parameters", parametersText(fill(0x41, ROLE_BUDGET).toString("latin1"), 1), { level: 9 })),
+        expect: { status: "unreadable", reason: "metadata-limit" },
+    },
+    {
+        name: "10,000 chunks without IEND",
+        file: () => concat(bytes.SIGNATURE, ihdr(), idat(), ...Array.from({ length: 9999 }, () => chunk("xxXx", [])), iend()),
+        expect: { status: "unreadable", reason: "metadata-limit" },
+    },
+    {
+        name: "IEND as the 10,000th chunk is read",
+        file: () => concat(bytes.SIGNATURE, ihdr(), idat(), ...Array.from({ length: 9997 }, () => chunk("xxXx", [])), iend()),
+        expect: { status: "complete", records: {}, limited: [], width: 1, height: 1 },
+    },
+    { name: "zTXt method not 0", file: () => png(zTXt("prompt", "p", { method: 1 })), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "zTXt without a method byte", file: () => png(chunk("zTXt", latin1("prompt\0"))), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "iTXt flag 2", file: () => png(iTXt("prompt", "p", { flag: 2 })), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "iTXt compressed with method 1", file: () => png(iTXt("prompt", "p", { flag: 1, method: 1 })), expect: { status: "unreadable", reason: "invalid-png" } },
+    {
+        name: "iTXt uncompressed ignores the method byte",
+        file: () => png(iTXt("prompt", "p", { flag: 0, method: 7 })),
+        expect: { status: "complete", records: { prompt: "p" }, limited: [], width: 1, height: 1 },
+    },
+    { name: "iTXt shorter than flag and method", file: () => png(chunk("iTXt", latin1("prompt\0\0"))), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "iTXt missing the translated keyword separator", file: () => png(chunk("iTXt", concat(latin1("prompt\0"), [0, 0], latin1("en\0text")))), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "iTXt non-ASCII language tag", file: () => png(iTXt("prompt", "p", { lang: [0xc3, 0xa9] })), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "iTXt invalid UTF-8 translated keyword", file: () => png(iTXt("prompt", "p", { translated: [0xff] })), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "iTXt invalid UTF-8 text", file: () => png(iTXt("prompt", [0xc3, 0x28])), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "iTXt encoded surrogate", file: () => png(iTXt("prompt", [0xed, 0xa0, 0x80])), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "NUL in tEXt text", file: () => png(tEXt("prompt", "a\0b")), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "NUL in inflated zTXt text", file: () => png(zTXt("prompt", "a\0b")), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "NUL in iTXt text", file: () => png(iTXt("prompt", "a\0b")), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "keyword of 0 bytes", file: () => png(chunk("tEXt", latin1("\0v"))), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "keyword of 80 bytes", file: () => png(tEXt("k".repeat(80), "v")), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "keyword without a NUL", file: () => png(chunk("tEXt", latin1("nonul"))), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "empty text chunk", file: () => png(chunk("tEXt", [])), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "malformed keyword on an unknown key still fails", file: () => png(tEXt("prompt", "p"), chunk("tEXt", latin1("x".repeat(100)))), expect: { status: "unreadable", reason: "invalid-png" } },
+    {
+        name: "keyword of 79 bytes is read",
+        file: () => png(tEXt("k".repeat(79), "v"), tEXt("prompt", "p")),
+        expect: { status: "complete", records: { prompt: "p" }, limited: [], width: 1, height: 1 },
+    },
+    {
+        name: "Latin-1 0xE9 is an e-acute in tEXt and zTXt",
+        file: () => png(tEXt("prompt", [0xe9]), zTXt("parameters", [0xe9, 0x0a, 0x53, 0x74, 0x65, 0x70, 0x73, 0x3a, 0x20, 0x31])),
+        expect: { status: "complete", records: { prompt: "é", parameters: "é\nSteps: 1" }, limited: [], width: 1, height: 1 },
+    },
+    {
+        name: "iTXt BOM is preserved, compressed and not",
+        file: () => png(iTXt("prompt", "{}"), iTXt("workflow", "[]", { flag: 1, lang: "en", translated: "wörkflow" })),
+        expect: { status: "complete", records: { prompt: "{}", workflow: "[]" }, limited: [], width: 1, height: 1 },
+    },
+    { name: "truncated zlib data", file: () => png(zTXt("prompt", "x".repeat(500), { compressed: zlib.deflateSync(latin1("x".repeat(500))).subarray(0, 8) })), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "trailing bytes after the zlib stream", file: () => png(zTXt("prompt", "p", { compressed: concat(zlib.deflateSync(latin1("p")), [1, 2, 3]) })), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "empty zlib data", file: () => png(zTXt("prompt", "p", { compressed: [] })), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "garbage zlib data", file: () => png(zTXt("prompt", "p", { compressed: [1, 2, 3, 4, 5, 6, 7, 8] })), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "truncated compressed iTXt", file: () => png(iTXt("prompt", "p", { flag: 1, compressed: zlib.deflateSync(latin1("x".repeat(500))).subarray(0, 8) })), expect: { status: "unreadable", reason: "invalid-png" } },
+    {
+        name: "chunks after IEND are ignored",
+        file: () => concat(png(tEXt("prompt", "p")), tEXt("workflow", "w")),
+        expect: { status: "complete", records: { prompt: "p" }, limited: [], width: 1, height: 1 },
+    },
+    {
+        name: "non-ASCII chunk types are skipped",
+        file: () => png(chunk("\xff\xfe\x80\x81", [1, 2, 3]), tEXt("prompt", "p")),
+        expect: { status: "complete", records: { prompt: "p" }, limited: [], width: 1, height: 1 },
+    },
+];
+
+for (const rule of RULES) {
+    test(`server rules, one by one: ${rule.name}`, async () => {
+        const result = await read(rule.file());
+        if (rule.check) rule.check(result);
+        else assert.deepEqual(result, rule.expect);
+    });
+}
+
+test("decompress: undefined with zTXt is decompression-unavailable and yields no records", async () => {
+    const result = await read(png(tEXt("prompt", "p"), zTXt("workflow", "w")), { decompress: undefined });
+    assert.deepEqual(result, { status: "unreadable", reason: "decompression-unavailable" });
+    const plain = await read(png(tEXt("prompt", "p"), zTXt("Comment", "skipped")), { decompress: undefined });
+    assert.deepEqual(plain.records, { prompt: "p" });
+});
+
+function instrumentedStream(transform) {
+    const stats = { writes: [], inFlight: 0, maxInFlight: 0 };
+    return {
+        stats,
+        Stream: class {
+            constructor() {
+                const stream = new TransformStream({
+                    async transform(chunk, controller) {
+                        stats.writes.push(chunk.byteLength);
+                        stats.inFlight += 1;
+                        stats.maxInFlight = Math.max(stats.maxInFlight, stats.inFlight);
+                        await transform(chunk, controller);
+                        stats.inFlight -= 1;
+                    },
+                });
+                this.writable = stream.writable;
+                this.readable = stream.readable;
+            }
+        },
+    };
+}
+
+test("inflation keeps one <=256-byte write in flight", async () => {
+    const body = fill(0x41, 3000);
+    const { stats, Stream } = instrumentedStream(async (chunk, controller) => {
+        await new Promise((resolve) => setTimeout(resolve, 1));
+        controller.enqueue(chunk);
+    });
+    // The fake "inflates" by passing bytes through, so the stored body is the text.
+    const result = await read(png(chunk("zTXt", concat(latin1("prompt\0"), [0], body))), { decompress: Stream });
+    assert.equal(result.status, "complete");
+    assert.equal(result.records.prompt, body.toString("latin1"));
+    assert.ok(stats.writes.every((size) => size <= 256), JSON.stringify(stats.writes));
+    assert.equal(stats.writes.reduce((sum, size) => sum + size, 0), body.length);
+    assert.equal(stats.maxInFlight, 1);
+});
+
+test("inflation settles once on abort with an AbortError and no unhandled rejection", async () => {
+    const unhandled = [];
+    const onUnhandled = (reason) => unhandled.push(reason);
+    process.on("unhandledRejection", onUnhandled);
+    try {
+        const { stats, Stream } = instrumentedStream(() => new Promise(() => {}));
+        const controller = new AbortController();
+        const pending = readPngMetadataFile(blobOf(png(zTXt("prompt", "p".repeat(1000)))), { decompress: Stream, signal: controller.signal });
+        let settled = 0;
+        pending.then(() => settled++, () => settled++);
+        await new Promise((resolve) => setTimeout(resolve, 5));
+        assert.equal(settled, 0, "the read waits on the stream");
+        controller.abort();
+        await assert.rejects(pending, (error) => error.name === "AbortError");
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        assert.equal(settled, 1);
+        assert.equal(stats.maxInFlight, 1);
+        assert.deepEqual(unhandled, []);
+    } finally {
+        process.off("unhandledRejection", onUnhandled);
+    }
+});
+
+test("a stream error under a live signal is still invalid-png, not an abort", async () => {
+    const controller = new AbortController();
+    const result = await read(png(zTXt("prompt", "p", { compressed: [1, 2, 3, 4, 5, 6, 7, 8] })), { signal: controller.signal });
+    assert.deepEqual(result, { status: "unreadable", reason: "invalid-png" });
+    assert.equal(controller.signal.aborted, false);
+});
+
+test("an already aborted signal rejects before any slice", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const file = recordingBlob(png(tEXt("prompt", "p")));
+    await assert.rejects(readPngMetadataFile(file, { signal: controller.signal }), (error) => error.name === "AbortError");
+    assert.deepEqual(file.ranges, []);
+});
+
+test("aborting between slices rejects with an AbortError", async () => {
+    const controller = new AbortController();
+    const whole = png(tEXt("prompt", "p"));
+    let slices = 0;
+    const file = {
+        size: whole.length,
+        slice(start, end) {
+            return {
+                arrayBuffer: async () => {
+                    if (++slices === 3) controller.abort();
+                    return whole.slice(start, end).buffer;
+                },
+            };
+        },
+    };
+    await assert.rejects(readPngMetadataFile(file, { signal: controller.signal }), (error) => error.name === "AbortError");
+});
+
+test("aborting while inflating a real deflate stream rejects with an AbortError", async () => {
+    const controller = new AbortController();
+    let inflating = false;
+    class Tracked extends DecompressionStream {
+        constructor(format) {
+            super(format);
+            inflating = true;
+        }
+    }
+    // The slow slices make the pacer yield inside the inflater's feed loop; that
+    // yield aborts, so the real stream is torn down mid-inflation.
+    const yieldControl = async () => {
+        if (inflating) controller.abort();
+    };
+    const slow = slowBlob(png(zTXt("prompt", "p", { compressed: require("node:crypto").randomBytes(5000) })), 10);
+    await assert.rejects(readPngMetadataFile(slow, { signal: controller.signal, yieldControl, decompress: Tracked }), (error) => error.name === "AbortError");
+    assert.equal(inflating, true);
+});
+
+test("yields control about every 8 ms while the file answers slowly", async () => {
+    let yields = 0;
+    const yieldControl = async () => {
+        yields += 1;
+    };
+    const result = await readPngMetadataFile(slowBlob(png(tEXt("prompt", "p")), 10), { yieldControl });
+    assert.equal(result.status, "complete");
+    assert.ok(yields >= 1, `yielded ${yields} times`);
+});
+
+test("the default yield lets the event loop turn", async () => {
+    const result = await readPngMetadataFile(slowBlob(png(tEXt("prompt", "p")), 10));
+    assert.deepEqual(result.records, { prompt: "p" });
+});
+
+test("a slice that fails is a read failure", async () => {
+    assert.deepEqual(await readPngMetadataFile(failingBlob(100)), { status: "unreadable", reason: "read-failure" });
+    assert.deepEqual(await readPngMetadataFile(null), { status: "unreadable", reason: "read-failure" });
+});
+
+test("a file that shrank under the reader is a read failure", async () => {
+    const whole = png(tEXt("prompt", "p"));
+    assert.deepEqual(await readPngMetadataFile(shrunkBlob(whole.subarray(0, 40), whole.length)), { status: "unreadable", reason: "read-failure" });
+});
+
+test("classifier", () => {
+    assert.deepEqual(classifyPrefix(bytes.SIGNATURE), { media: "image", kind: "png" });
+    assert.deepEqual(classifyPrefix(Uint8Array.from([0xff, 0xd8, 0xff, 0xe0])), { media: "image", kind: "jpeg" });
+    assert.deepEqual(classifyPrefix(latin1("RIFF\0\0\0\0WEBPVP8 ")), { media: "image", kind: "webp" });
+    assert.deepEqual(classifyPrefix(latin1("\0\0\0\x18ftypisom\0\0\0\0")), { media: "video", kind: "iso-bmff" });
+    assert.deepEqual(classifyPrefix(latin1("\0\0\0\x14ftypqt  ")), { media: "video", kind: "iso-bmff" });
+    assert.deepEqual(classifyPrefix(Uint8Array.from([0x1a, 0x45, 0xdf, 0xa3, 0x01])), { media: "video", kind: "matroska" });
+    assert.deepEqual(classifyPrefix(latin1("RIFF\0\0\0\0AVI LIST")), { media: "video", kind: "avi" });
+    const asf = Uint8Array.from([0x30, 0x26, 0xb2, 0x75, 0x8e, 0x66, 0xcf, 0x11, 0xa6, 0xd9, 0x00, 0xaa, 0x00, 0x62, 0xce, 0x6c, 0, 0]);
+    assert.deepEqual(classifyPrefix(asf), { media: "video", kind: "asf" });
+    assert.deepEqual(classifyPrefix(asf.buffer), { media: "video", kind: "asf" });
+    for (const text of ["plain text file", "<!DOCTYPE html><html>", '<?xml version="1.0"?><svg', "#EXTM3U\n#EXT-X-VERSION:3", "RIFF\0\0\0\0WAVEfmt ", "\0\0\0\x18moov", ""]) {
+        assert.equal(classifyPrefix(latin1(text)), null, text);
+    }
+    assert.equal(classifyPrefix(bytes.SIGNATURE.subarray(0, 7)), null);
+    assert.equal(classifyPrefix(Uint8Array.from([0xff, 0xd8])), null);
+    assert.equal(classifyPrefix("not bytes"), null);
+    assert.equal(classifyPrefix(null), null);
+});
+
+test("image header: JPEG and WebP fixtures match Pillow's dimensions", async () => {
+    // tests/test_local_inspect_parity.py asserts the same two files against Pillow.
+    const jpeg = blobOf(fs.readFileSync(path.join(FIXTURES, "tiny.jpg")));
+    assert.deepEqual(await readImageHeader(jpeg, "jpeg"), { format: "JPEG", width: 48, height: 32 });
+    const webp = blobOf(fs.readFileSync(path.join(FIXTURES, "tiny.webp")));
+    assert.deepEqual(await readImageHeader(webp, "webp"), { format: "WEBP", width: 40, height: 24 });
+});
+
+test("image header: JPEG marker walk skips padding, junk, standalone markers and tables", async () => {
+    const segment = (marker, body) => concat([0xff, marker], u32(body.length + 2).subarray(2), body);
+    const sof = (marker, width, height) => segment(marker, concat([8], u32(height).subarray(2), u32(width).subarray(2), [3]));
+    const sized = concat([0xff, 0xd8], segment(0xe1, fill(0, 20)), [0xff, 0xff, 0xff, 0x00, 0x00, 0x11], [0xff, 0xd0], [0xff, 0x01], segment(0xc4, fill(0, 4)), segment(0xc8, []), segment(0xcc, [1]), sof(0xc2, 300, 200));
+    assert.deepEqual(await readImageHeader(blobOf(sized), "jpeg"), { format: "JPEG", width: 300, height: 200 });
+    for (const marker of [0xc0, 0xc1, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf]) {
+        assert.deepEqual(await readImageHeader(blobOf(concat([0xff, 0xd8], sof(marker, 7, 9))), "jpeg"), { format: "JPEG", width: 7, height: 9 }, marker.toString(16));
+    }
+    const none = { format: "JPEG", width: null, height: null };
+    assert.deepEqual(await readImageHeader(blobOf(concat([0xff, 0xd8], segment(0xda, [1]))), "jpeg"), none, "SOS before SOF");
+    assert.deepEqual(await readImageHeader(blobOf(concat([0xff, 0xd8], [0xff])), "jpeg"), none, "ends on a marker byte");
+    assert.deepEqual(await readImageHeader(blobOf(concat([0xff, 0xd8], [0xff, 0xe1, 0x00])), "jpeg"), none, "ends inside a length");
+    assert.deepEqual(await readImageHeader(blobOf(concat([0xff, 0xd8], [0xff, 0xc0, 0x00, 0x08, 8, 0])), "jpeg"), none, "ends inside SOF");
+    assert.deepEqual(await readImageHeader(blobOf(concat([0xff, 0xd8], segment(0xe1, []))), "jpeg"), none, "no SOF at all");
+    assert.deepEqual(await readImageHeader(blobOf(Uint8Array.from([0xff])), "jpeg"), none, "too short");
+    assert.deepEqual(await readImageHeader(blobOf(latin1("RIFF")), "jpeg"), none, "not a JPEG");
+    // A SOF past the 64 KiB read gives no dimensions rather than reading on.
+    assert.deepEqual(await readImageHeader(blobOf(concat([0xff, 0xd8], segment(0xe1, fill(0, 65000)), segment(0xe2, fill(0, 1000)), sof(0xc0, 5, 5))), "jpeg"), none, "SOF beyond 64 KiB");
+});
+
+test("image header: WebP VP8, VP8L and VP8X headers", async () => {
+    const riff = (...rest) => concat(latin1("RIFF"), u32(0), latin1("WEBP"), ...rest);
+    const chunkHeader = (type, size) => concat(latin1(type), Uint8Array.from([size & 0xff, (size >>> 8) & 0xff, (size >>> 16) & 0xff, 0]));
+    const vp8 = riff(chunkHeader("VP8 ", 100), [0x30, 0x0b, 0x00, 0x9d, 0x01, 0x2a], [40, 0x40], [24, 0x80], fill(0, 20));
+    assert.deepEqual(await readImageHeader(blobOf(vp8), "webp"), { format: "WEBP", width: 40, height: 24 }, "scale bits are masked");
+    // 14-bit width-1 = 63 and height-1 = 47, little-endian bit-packed after the 0x2f signature.
+    const vp8l = riff(chunkHeader("VP8L", 100), [0x2f], [0x3f, 0xc0, 0x0b, 0x00, 0x00], fill(0, 20));
+    assert.deepEqual(await readImageHeader(blobOf(vp8l), "webp"), { format: "WEBP", width: 64, height: 48 });
+    const vp8x = riff(chunkHeader("VP8X", 10), [0x10, 0, 0, 0], [0xff, 0x00, 0x01], [0x2f, 0x00, 0x00], fill(0, 20));
+    assert.deepEqual(await readImageHeader(blobOf(vp8x), "webp"), { format: "WEBP", width: 65792, height: 48 });
+    const none = { format: "WEBP", width: null, height: null };
+    assert.deepEqual(await readImageHeader(blobOf(riff(chunkHeader("VP8 ", 100), [0x30, 0x0b, 0x00, 0x00, 0x01, 0x2a], fill(0, 24))), "webp"), none, "bad start code");
+    assert.deepEqual(await readImageHeader(blobOf(riff(chunkHeader("VP8L", 100), [0x00], fill(0, 24))), "webp"), none, "bad VP8L signature");
+    assert.deepEqual(await readImageHeader(blobOf(riff(chunkHeader("ALPH", 100), fill(0, 24))), "webp"), none, "unknown first chunk");
+    assert.deepEqual(await readImageHeader(blobOf(riff(chunkHeader("VP8 ", 100))), "webp"), none, "too short");
+    assert.deepEqual(await readImageHeader(blobOf(latin1("RIFF\0\0\0\0WAVEfmt ".padEnd(40, "\0"))), "webp"), none, "not WebP");
+});
+
+test("image header: other kinds give no format and the read stays within 64 KiB", async () => {
+    assert.deepEqual(await readImageHeader(blobOf(bytes.SIGNATURE), "png"), { format: null, width: null, height: null });
+    const file = recordingBlob(concat([0xff, 0xd8], fill(0, 200000)));
+    await readImageHeader(file, "jpeg");
+    assert.deepEqual(file.ranges, [[0, 65536]]);
+    const small = recordingBlob(concat([0xff, 0xd8, 0xff]));
+    await readImageHeader(small, "jpeg");
+    assert.deepEqual(small.ranges, [[0, 3]]);
+});

tests/js/support-module-urls.test.js

@@ -0,0 +1,39 @@
+// The Node oracles that Python drives (tests/js/support/*.mjs) import product
+// modules dynamically. A dynamic import takes a URL or a bare/relative specifier,
+// never a filesystem path: on Windows `D:\...\x.mjs` parses as the `d:` scheme
+// (ERR_UNSUPPORTED_ESM_URL_SCHEME). Every such import goes through moduleUrl, and
+// this test proves the Windows form on any host so Linux catches a regression.
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const support = path.join(here, "support");
+const m = await import("./support/module-url.mjs").catch((error) => {
+    if (error.code !== "ERR_MODULE_NOT_FOUND") throw error;
+    return {};
+});
+
+test("moduleUrl turns a filesystem path into a file: URL on every platform", async () => {
+    assert.equal(typeof m.moduleUrl, "function", "moduleUrl is exported");
+    assert.equal(m.moduleUrl("D:\\x\\y z.mjs", { windows: true }), "file:///D:/x/y%20z.mjs");
+    assert.equal(m.moduleUrl("C:\\repo\\web\\js\\workspace\\local-video.mjs", { windows: true }), "file:///C:/repo/web/js/workspace/local-video.mjs");
+    assert.equal(m.moduleUrl("/repo/web/js/a b.mjs", { windows: false }), "file:///repo/web/js/a%20b.mjs");
+    const own = m.moduleUrl(path.join(here, "support", "module-url.mjs"));
+    assert.ok(own.startsWith("file:///"), own);
+    assert.equal((await import(own)).moduleUrl, m.moduleUrl, "the URL imports the same module instance");
+});
+
+test("every dynamic import in the Node oracles is a file URL, never a path", () => {
+    const scripts = fs.readdirSync(support).filter((name) => name.endsWith(".mjs"));
+    assert.ok(scripts.includes("local-inspect-oracle.mjs"));
+    for (const name of scripts) {
+        const source = fs.readFileSync(path.join(support, name), "utf8").split("\n").filter((line) => !line.trim().startsWith("//")).join("\n");
+        for (const match of source.matchAll(/\bimport\(\s*([^)]*?)[,)]/g)) {
+            const argument = match[1].trim();
+            assert.ok(/^(moduleUrl\(|pathToFileURL\(|["'`]\.{1,2}\/)/.test(argument), `${name}: import(${argument}) must be a file URL or a relative specifier`);
+        }
+    }
+});

tests/js/support/local-inspect-oracle.mjs

@@ -0,0 +1,59 @@
+// The browser's local readers and projection run over files on disk, for
+// tests/test_local_inspect_parity.py, which compares every answer with the server's
+// utils.prompt_inspector.read_inspection_file and utils.inspection_response._metadata
+// on the same file. Each file is opened as a Blob (fs.openAsBlob) so the reader
+// slices it exactly as it slices a File.
+// stdin: [{name, path} | {name, tags, limited?} | {name, records, record_formats?, carrier_text?, limited?}]
+// stdout: {name: {classified, result, metadata}} where result is readPngMetadataFile's
+//         answer for a PNG, readImageHeader's for another image, for a video
+//         {read: readVideoTags(...), selection: selectVideoCarrier(read.tags, {limited})}
+//         (selection null unless the read completed), else null; metadata is
+//         projectMetadata(...) of the local read (the server's _metadata) for every
+//         classified file, else null.
+//         A {tags} entry answers {classified: null, result: {selection}, metadata} for
+//         the carrier rule alone, as the server selects from ffprobe's tag map.
+//         A {records} entry (records null = an unreadable file) answers
+//         {classified: null, result: null, metadata} for the projection alone.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { moduleUrl } from './module-url.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+const pngMetadata = require(path.join(here, '..', '..', '..', 'web', 'js', 'png-metadata.js'));
+const web = path.join(here, '..', '..', '..', 'web', 'js', 'workspace');
+// ES modules import by file URL (a Windows path would parse as a URL scheme).
+const { selectVideoCarrier } = await import(moduleUrl(path.join(web, 'local-video.mjs')));
+const { projectMetadata } = await import(moduleUrl(path.join(web, 'local-projection.mjs')));
+const { readLocalFile, toInspectionRead } = await import(moduleUrl(path.join(web, 'local-inspection.mjs')));
+
+const selectionRead = (selection) => selection.status === 'complete' ?
+    { records: selection.records, record_formats: selection.record_formats, carrierText: selection.carrierText, limited: selection.limited } : null;
+
+const chunks = [];
+for await (const chunk of process.stdin) chunks.push(chunk);
+const output = {};
+for (const entry of JSON.parse(Buffer.concat(chunks).toString('utf8'))) {
+    const { name } = entry;
+    if (entry.records !== undefined) {
+        const read = entry.records === null ? null : {
+            records: entry.records,
+            record_formats: entry.record_formats ?? Object.fromEntries(Object.keys(entry.records).map((key) => [key, 'original-text'])),
+            carrierText: entry.carrier_text ?? null, limited: entry.limited ?? [],
+        };
+        output[name] = { classified: null, result: null, metadata: projectMetadata(read) };
+        continue;
+    }
+    if (entry.path === undefined) {
+        const selection = selectVideoCarrier(entry.tags, { limited: entry.limited || [] });
+        output[name] = { classified: null, result: { selection }, metadata: projectMetadata(selectionRead(selection)) };
+        continue;
+    }
+    const file = await fs.openAsBlob(entry.path);
+    const { classification, result } = await readLocalFile(file, { pngMetadata });
+    const metadata = classification === null ? null : projectMetadata(toInspectionRead(classification, result).read);
+    output[name] = { classified: classification, result, metadata };
+}
+process.stdout.write(JSON.stringify(output));

tests/js/support/module-url.mjs

@@ -0,0 +1,9 @@
+// A dynamic import() takes a URL, never a filesystem path: on Windows a path such
+// as D:\repo\x.mjs parses as the "d:" scheme (ERR_UNSUPPORTED_ESM_URL_SCHEME).
+// Every oracle in this directory imports product modules through moduleUrl.
+import { pathToFileURL } from 'node:url';
+
+/** The file: URL for a filesystem path; `windows` forces the Windows form on any host (for tests). */
+export function moduleUrl(filePath, { windows = process.platform === 'win32' } = {}) {
+    return pathToFileURL(filePath, { windows }).href;
+}

tests/js/workspace-local-inspection.test.js

@@ -0,0 +1,308 @@
+// web/js/workspace/local-inspection.mjs turns one chosen File's local reads into
+// the inspection wire the workspace already renders, fits it into the 8 MiB
+// response budget exactly as the server does, and plugs into the shared
+// inspection controller, inspector and viewer through localFileAdapter.
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { raw, ihdr, idat, iend, tEXt, iTXt, utf8 } from "./helpers/png-bytes.mjs";
+import { createInspectionController, toInspectionRecord, projectInspectionPayload } from "../../web/js/workspace/inspection-state.mjs";
+import { inspectionDownloads } from "../../web/js/workspace/file-inspector.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+const PngMetadata = require("../../web/js/png-metadata.js");
+const ComfyMetadata = require("../../web/js/comfy-metadata.js");
+const { extractGenerationFacts } = ComfyMetadata;
+// The page loads both as scripts; the legacy fill and the PNG reader find them on the global.
+globalThis.PngMetadata = PngMetadata;
+globalThis.ComfyMetadata = ComfyMetadata;
+const m = await import("../../web/js/workspace/local-inspection.mjs").catch((error) => {
+    if (error.code !== "ERR_MODULE_NOT_FOUND") throw error;
+    return {};
+});
+
+const FIXTURES = path.join(here, "..", "fixtures", "local-inspect");
+const PARITY = path.join(here, "..", "fixtures", "inspection_parity");
+const PROMPT = '{"3":{"class_type":"KSampler","inputs":{"seed":7,"steps":20,"cfg":8.0,"sampler_name":"euler","scheduler":"normal","denoise":1.0,"model":["4",0],"positive":["6",0],"negative":["7",0],"latent_image":["5",0]}},"4":{"class_type":"CheckpointLoaderSimple","inputs":{"ckpt_name":"synthetic-v1.safetensors"}},"5":{"class_type":"EmptyLatentImage","inputs":{"width":512,"height":512,"batch_size":1}},"6":{"class_type":"CLIPTextEncode","inputs":{"text":"a red fox in snow, detailed fur","clip":["4",1]}},"7":{"class_type":"CLIPTextEncode","inputs":{"text":"blurry, lowres","clip":["4",1]}}}';
+const WORKFLOW = '{"last_node_id":7,"nodes":[{"id":3,"type":"KSampler","widgets_values":[7,"fixed",20,8.0,"euler","normal",1.0]}],"links":[],"version":0.4}';
+const CONTAINER_WORKFLOW = "Original workflow JSON text is unavailable for this container record. Download metadata or the original file.";
+const LIMIT = 8388608;
+const plain = (value) => JSON.parse(JSON.stringify(value));
+const bytes = (value) => Buffer.byteLength(JSON.stringify(value), "utf8");
+
+function pngFile(name, chunks, { lastModified = 1_700_000_000_123 } = {}) {
+    return new File([raw(ihdr(640, 480), idat(), ...chunks, iend())], name, { type: "image/png", lastModified });
+}
+const fixtureFile = (name, directory = FIXTURES) => new File([fs.readFileSync(path.join(directory, name))], name, { lastModified: 1_700_000_000_000 });
+const classify = async (file) => PngMetadata.classifyPrefix(new Uint8Array(await file.slice(0, 32).arrayBuffer()));
+async function handleFor(file, { url = "blob:http://host.test/11111111-2222-3333-4444-555555555555", filename } = {}) {
+    return m.createLocalFileHandle({ file, url, classification: await classify(file), filename });
+}
+async function recordFor(file, options) {
+    const handle = await handleFor(file, options);
+    const wire = await m.localFileAdapter.read(handle);
+    return { handle, wire, record: m.localFileAdapter.toRecord(wire, handle, extractGenerationFacts) };
+}
+
+test("contract", () => {
+    for (const name of ["buildLocalPayload", "fitLocalPayload", "createLocalFileHandle", "readLocalFile", "toInspectionRead", "sanitizeLocalFilename"]) {
+        assert.equal(typeof m[name], "function", `${name} is exported`);
+    }
+    assert.equal(typeof m.localFileAdapter, "object");
+    for (const name of ["validate", "key", "scope", "inspectionPath", "read", "toRecord", "originalDownload", "mediaUrl"]) {
+        assert.equal(typeof m.localFileAdapter[name], "function", `adapter.${name}`);
+    }
+    assert.ok(Object.isFrozen(m.localFileAdapter));
+});
+
+test("a PNG File becomes the server-shaped wire with local provenance", async () => {
+    const file = pngFile("Fox Render.PNG", [tEXt("prompt", PROMPT), tEXt("workflow", WORKFLOW)]);
+    const { wire, record, handle } = await recordFor(file);
+    assert.deepEqual(wire.file, { observation: "selected-local-file", source_label: "Selected local file", media_type: "image", extension: ".png", format: "PNG",
+        size: file.size, width: 640, height: 480, modified_time: 1_700_000_000.123 });
+    assert.equal(wire.success, true);
+    assert.equal(wire.inspection_version, 1);
+    assert.deepEqual(wire.prompts, { positive: { status: "unresolved" }, negative: { status: "unresolved" } });
+    assert.deepEqual(wire.resolution, { state: "unresolved", sampler_id: null, reason: "Resolved in this browser from the workflow.", reason_code: null, node: null });
+    assert.deepEqual(wire.library, { status: "unavailable", scope: "saved-library", tags: [], category_scope: null, tags_scope: null });
+    assert.equal(wire.metadata.status, "available");
+    assert.deepEqual(wire.metadata.raw, { prompt: PROMPT, workflow: WORKFLOW });
+    assert.deepEqual(wire.metadata.record_formats, { prompt: "original-text", workflow: "original-text" });
+    assert.equal(wire.metadata.prompt_graph.status, "parsed");
+    assert.equal(plain(wire.metadata.prompt_graph.value)["3"].inputs.cfg, "8.0");
+    assert.equal(wire.metadata.workflow_graph.status, "parsed");
+    assert.equal(wire.metadata.parameters, null);
+    for (const key of Object.keys(wire)) assert.ok(["success", "inspection_version", "file", "prompts", "resolution", "metadata", "library"].includes(key), key);
+    // The existing projection renders it: facts from the API graph, legacy fill for the roles, no library link.
+    assert.deepEqual(record.identity, { kind: "local-file", key: handle.key, path: "Fox Render.PNG" });
+    assert.equal(record.file.observation, "selected-local-file");
+    assert.equal(record.generation.seed.value, "7");
+    assert.equal(record.generation.cfg.value, "8.0");
+    assert.equal(record.prompts.positive.text, "a red fox in snow, detailed fur");
+    assert.equal(record.prompts.positive.source, "graph-inferred");
+    assert.equal(record.prompts.negative.text, "blurry, lowres");
+    assert.equal(record.historyTarget, null);
+    assert.deepEqual(record.download, { url: "blob:http://host.test/11111111-2222-3333-4444-555555555555", filename: "Fox Render.PNG" });
+    const downloads = inspectionDownloads(record);
+    assert.equal(downloads.metadata.available, true);
+    assert.equal(downloads.workflow.bodyText, WORKFLOW);
+    assert.equal(downloads.metadata.filename, "Fox Render.metadata.json");
+    const exported = JSON.parse(downloads.metadata.bodyText);
+    assert.equal(exported.identity.kind, "local-file");
+    assert.equal(exported.file.source_label, "Selected local file");
+});
+
+test("file facts follow the server: extension like Path.suffix, null when unknown", async () => {
+    const cases = [["a.b.PnG", ".png"], [".hidden", ""], ["noext", ""], ["dot.", ""], ["x.tar.gz", ".gz"]];
+    for (const [name, extension] of cases) {
+        const wire = m.buildLocalPayload({ read: { status: "complete", records: {}, limited: [], width: 2, height: 3 }, file: { name, size: 10, lastModified: 0 }, classification: { media: "image", kind: "png" } });
+        assert.equal(wire.file.extension, extension, name);
+        assert.equal(wire.file.modified_time, 0);
+    }
+    const sparse = m.buildLocalPayload({ read: { status: "complete", records: {}, limited: [], width: 2, height: 3 }, file: { name: "a.png" }, classification: { media: "image", kind: "png" } });
+    assert.deepEqual([sparse.file.size, sparse.file.modified_time], [null, null]);
+    assert.equal(m.buildLocalPayload({ read: { status: "complete", records: {}, limited: [], width: 2, height: 3 }, file: { name: "a.png", size: -1, lastModified: NaN }, classification: { media: "image", kind: "png" } }).file.size, null);
+    assert.throws(() => m.buildLocalPayload({ read: null, file: { name: "a" }, classification: null }), TypeError);
+    assert.throws(() => m.buildLocalPayload({ read: null, file: { name: "a" }, classification: { media: "text", kind: "svg" } }), TypeError);
+});
+
+test("sanitized filenames carry no separators or control characters", () => {
+    assert.equal(m.sanitizeLocalFilename("../a/b\\c\u0000\u001f\u007f.png"), ".._a_b_c.png");
+    assert.equal(m.sanitizeLocalFilename("  spaced .png  "), "spaced .png");
+    assert.equal(m.sanitizeLocalFilename(""), "file");
+    assert.equal(m.sanitizeLocalFilename(undefined), "file");
+    assert.equal(m.sanitizeLocalFilename("\u0000"), "file");
+    assert.equal([...m.sanitizeLocalFilename("😀".repeat(300))].length, 255);
+});
+
+test("unreadable PNG metadata is unreadable, not absent", async () => {
+    const { wire, record } = await recordFor(pngFile("bad.png", [tEXt("prompt", PROMPT, { crc: 0 })]));
+    assert.equal(wire.metadata.status, "unreadable");
+    assert.deepEqual([wire.file.format, wire.file.width, wire.file.height], [null, null, null]);
+    assert.equal(record.generation.seed.reason, "metadata-unreadable");
+    assert.equal(record.prompts.positive.status, "unresolved");
+    assert.equal(JSON.parse(inspectionDownloads(record).metadata.bodyText).metadata.status, "unreadable");
+    const limited = await recordFor(pngFile("big.png", [tEXt("prompt", PROMPT), tEXt("workflow", "[" + "0,".repeat(2_097_153) + "]")]));
+    assert.deepEqual(limited.wire.metadata.record_formats, { prompt: "original-text", workflow: "limited" });
+    assert.equal(limited.wire.metadata.workflow_graph.status, "limited");
+    assert.equal(limited.record.metadata.record_formats.workflow, "limited");
+});
+
+test("JPEG and WebP previews have header facts and absent metadata", async () => {
+    for (const [name, format, width, height] of [["tiny.jpg", "JPEG", 48, 32], ["tiny.webp", "WEBP", 40, 24]]) {
+        const { wire, record } = await recordFor(fixtureFile(name));
+        assert.deepEqual([wire.file.format, wire.file.width, wire.file.height, wire.file.media_type], [format, width, height, "image"], name);
+        assert.equal(wire.metadata.status, "absent");
+        assert.equal(record.generation.seed.status, "not-recorded");
+    }
+});
+
+test("video payloads", async () => {
+    const legacy = await recordFor(fixtureFile("legacy-comment.mp4"));
+    assert.deepEqual([legacy.wire.file.media_type, legacy.wire.file.format, legacy.wire.file.width, legacy.wire.file.extension], ["video", null, null, ".mp4"]);
+    assert.equal(legacy.wire.metadata.record_formats.workflow, "reserialized-json");
+    assert.equal(legacy.wire.metadata.record_formats.prompt, "original-text");
+    assert.equal(legacy.wire.metadata.workflow_graph.status, "parsed");
+    assert.equal(inspectionDownloads(legacy.record).workflow.available, false);
+    assert.equal(inspectionDownloads(legacy.record).workflow.reason, CONTAINER_WORKFLOW);
+    assert.equal(legacy.record.prompts.positive.text, "a red fox in snow, detailed fur");
+    // Ruling M1: a Matroska COMMENT tag is not the exact-case `comment` envelope, so it is absent, as Images reports it.
+    const webm = await recordFor(fixtureFile("legacy-comment.webm"));
+    assert.equal(webm.wire.metadata.status, "absent");
+    const tags = await recordFor(fixtureFile("core-tags.webm"));
+    assert.deepEqual(tags.wire.metadata.record_formats, { prompt: "original-text", workflow: "original-text" });
+    assert.equal(tags.record.generation.seed.value, "7");
+    // AVI and ASF are recognised, previewable, and never read.
+    const avi = new File([utf8("RIFF"), new Uint8Array([0, 0, 0, 0]), utf8("AVI LIST"), new Uint8Array(64)], "clip.avi");
+    const aviRecord = await recordFor(avi);
+    assert.equal(aviRecord.wire.metadata.status, "unreadable");
+    assert.equal(aviRecord.wire.file.media_type, "video");
+    assert.equal(aviRecord.record.generation.seed.reason, "metadata-unreadable");
+    const asf = new File([new Uint8Array([0x30, 0x26, 0xb2, 0x75, 0x8e, 0x66, 0xcf, 0x11, 0xa6, 0xd9, 0x00, 0xaa, 0x00, 0x62, 0xce, 0x6c]), new Uint8Array(64)], "clip.wmv");
+    assert.equal((await recordFor(asf)).wire.metadata.status, "unreadable");
+    // A pre-classified video needs no PNG reader; an image without one is an error, not a silent absence.
+    const clip = fixtureFile("core.mkv");
+    assert.equal((await m.readLocalFile(clip, { classification: { media: "video", kind: "matroska" }, pngMetadata: null })).result.read.status, "complete");
+    await assert.rejects(m.readLocalFile(clip, { pngMetadata: null }), /PNG reader/);
+    await assert.rejects(m.readLocalFile(fixtureFile("tiny.jpg"), { classification: { media: "image", kind: "jpeg" }, pngMetadata: null }), /PNG reader/);
+    await assert.rejects(m.readLocalFile("not a blob"), TypeError);
+    assert.deepEqual(await m.readLocalFile(new File([utf8("<svg/>")], "x.png"), { pngMetadata: PngMetadata }), { classification: null, result: null });
+    // A container that fails to parse is unreadable too.
+    const broken = new File([utf8("\0\0\0\x08ftypisom"), utf8("\0\0\0\x01moov")], "broken.mp4");
+    assert.equal((await recordFor(broken)).wire.metadata.status, "unreadable");
+});
+
+test("local cap measures escaped UTF-8 atomically", async () => {
+    // A 1 MiB Latin-1 prompt of 'é' (2 UTF-8 bytes, 1 code unit each) and a 4 MiB UTF-8 workflow of
+    // emoji (4 bytes, 2 units): the UTF-16 length of the wire is well under the limit while its UTF-8
+    // size is not, so a cap counting code units would keep too much.
+    const prompt = `{"1":{"class_type":"A","inputs":{"t":"${"é".repeat(1_000_000)}"}}}`;
+    const workflow = `{"nodes":[],"u":"${"😀".repeat(1_000_000)}"}`;
+    const file = pngFile("wide.png", [iTXt("workflow", workflow), tEXt("prompt", prompt)]);
+    const handle = await handleFor(file);
+    const raw = await m.readLocalFile(handle.file, { classification: handle.classification, pngMetadata: PngMetadata });
+    assert.equal(raw.result.status, "complete");
+    const wire = m.buildLocalPayload({ read: raw.result, file: { name: file.name, size: file.size, lastModified: file.lastModified }, classification: handle.classification });
+    const text = JSON.stringify(wire);
+    assert.ok(text.length < LIMIT && bytes(wire) > LIMIT, `${text.length} code units, ${bytes(wire)} bytes`);
+    const fitted = await m.fitLocalPayload(wire);
+    assert.ok(bytes(fitted) <= LIMIT);
+    assert.equal(fitted.metadata.workflow_graph.status, "limited", "the workflow graph goes first");
+    assert.equal(fitted.metadata.prompt_graph.status, "parsed");
+    assert.deepEqual(Object.keys(fitted.metadata.raw).sort(), ["prompt", "workflow"], "raw is kept");
+    const record = m.localFileAdapter.toRecord(fitted, handle, extractGenerationFacts);
+    assert.equal(inspectionDownloads(record).metadata.available, true);
+    assert.equal(inspectionDownloads(record).workflow.available, false);
+    // Whole-raw omission is atomic and marks the response-size limit; the inspector offers no metadata download.
+    const squeezed = await m.fitLocalPayload(wire, bytes(fitted) - 1);
+    assert.deepEqual([squeezed.metadata.workflow_graph.status, squeezed.metadata.prompt_graph.status], ["limited", "limited"]);
+    const tiny = await m.fitLocalPayload(wire, 2000);
+    assert.equal(tiny.metadata.status, "limited");
+    assert.equal(tiny.metadata.omitted_reason, "response-size-limit");
+    assert.deepEqual(tiny.metadata.raw, {});
+    assert.equal(tiny.metadata.parameters, null);
+    assert.ok(bytes(tiny) <= 2000);
+    const omitted = m.localFileAdapter.toRecord(tiny, handle, extractGenerationFacts);
+    assert.equal(inspectionDownloads(omitted).metadata.available, false);
+    assert.equal(omitted.generation.seed.reason, "projection-limited");
+    await assert.rejects(m.fitLocalPayload(wire, 100), /exceeds/);
+    assert.equal(wire.metadata.status, "available", "the input wire is not mutated");
+    assert.equal((await m.localFileAdapter.read(handle)).metadata.workflow_graph.status, "limited", "adapter.read returns the fitted wire");
+});
+
+test("adapter rejects foreign blob URLs and never resolves owned ones", async () => {
+    const file = pngFile("a.png", [tEXt("prompt", PROMPT)]);
+    const classification = await classify(file);
+    const owned = m.createLocalFileHandle({ file, url: "blob:http://host.test/0b0e", classification });
+    assert.ok(Object.isFrozen(owned));
+    assert.deepEqual(m.localFileAdapter.originalDownload(owned), { url: "blob:http://host.test/0b0e", filename: "a.png" });
+    assert.equal(m.localFileAdapter.mediaUrl(owned), "blob:http://host.test/0b0e");
+    // The controller and the viewer session spread-copy descriptors: a copy is the same selection.
+    const copy = { ...owned, occurrence: {}, reference: {} };
+    assert.equal(m.localFileAdapter.key(copy), owned.key);
+    assert.equal(m.localFileAdapter.mediaUrl(copy), "blob:http://host.test/0b0e");
+    // A tampered URL, key, File or name, or a descriptor this module never made, is foreign.
+    const tampered = [{ ...owned, url: "blob:http://host.test/other" }, { ...owned, key: "local:1" }, { ...owned, file: new File([], "x.png") }, { ...owned, filename: "other.png" },
+        { kind: "local-file", key: owned.key, filename: owned.filename, url: owned.url, file, is_video: false, classification }, null, "local:1"];
+    for (const foreign of tampered) {
+        for (const method of ["validate", "originalDownload", "mediaUrl", "key", "scope", "inspectionPath"]) assert.throws(() => m.localFileAdapter[method](foreign), TypeError, method);
+        await assert.rejects(m.localFileAdapter.read(foreign), TypeError);
+        assert.throws(() => m.localFileAdapter.toRecord({ success: true, inspection_version: 1 }, foreign, extractGenerationFacts), TypeError);
+    }
+    for (const url of ["http://host.test/x.png", "/prompt_manager/images/serve/a.png", "javascript:alert(1)", "data:image/png;base64,AA==", "", 5]) {
+        assert.throws(() => m.createLocalFileHandle({ file, url, classification }), TypeError, String(url));
+    }
+    assert.throws(() => m.createLocalFileHandle({ file: "not a blob", url: "blob:http://host.test/1", classification }), TypeError);
+    assert.throws(() => m.createLocalFileHandle({ file, url: "blob:http://host.test/1", classification: null }), TypeError);
+    assert.throws(() => m.createLocalFileHandle({ file, url: "blob:http://host.test/1", classification: { media: "text", kind: "svg" } }), TypeError);
+    // A proxy-mounted host resolves API URLs; blob URLs are session-owned and bypass it.
+    const before = Object.getOwnPropertyDescriptor(globalThis, "window");
+    Object.defineProperty(globalThis, "window", { configurable: true, value: { location: { href: "https://example.test/proxy/prompt_manager/workspace" }, ApiClient: { resolveUrl: (url) => `/proxy${url}` } } });
+    try {
+        assert.equal(m.localFileAdapter.mediaUrl(owned), "blob:http://host.test/0b0e");
+        assert.equal(m.localFileAdapter.originalDownload(owned).url, "blob:http://host.test/0b0e");
+    } finally {
+        if (before) Object.defineProperty(globalThis, "window", before); else delete globalThis.window;
+    }
+    // Without an object URL the record has no download and the viewer cannot show the original.
+    const previewless = m.createLocalFileHandle({ file, url: null, classification });
+    assert.equal(m.localFileAdapter.mediaUrl(previewless), null);
+    assert.throws(() => m.localFileAdapter.originalDownload(previewless), TypeError);
+    const record = m.localFileAdapter.toRecord(await m.localFileAdapter.read(previewless), previewless, extractGenerationFacts);
+    assert.equal(record.download, null);
+    assert.equal(inspectionDownloads(record).metadata.filename, "a.metadata.json");
+});
+
+test("select reuses the same local key", async () => {
+    const file = pngFile("a.png", [tEXt("prompt", PROMPT)]);
+    const classification = await classify(file);
+    const first = m.createLocalFileHandle({ file, url: "blob:http://host.test/1", classification });
+    const second = m.createLocalFileHandle({ file, url: "blob:http://host.test/2", classification });
+    assert.notEqual(first.key, second.key, "the same bytes chosen twice are two selections");
+    assert.equal(m.localFileAdapter.scope(first), "local");
+    assert.equal(m.localFileAdapter.inspectionPath(first), `local-file:${first.key}`);
+    assert.equal(m.localFileAdapter.key(first), first.key);
+    const reads = [];
+    // Until the loader seam lands (PR L2 Task 4) the controller reaches the adapter through api.get.
+    const api = { get: (sentinel) => { reads.push(sentinel); return m.localFileAdapter.read(reads.length === 1 || sentinel === `local-file:${first.key}` ? first : second); } };
+    const controller = createInspectionController({ api, extractFacts: extractGenerationFacts, adapter: m.localFileAdapter });
+    const pending = controller.select(first);
+    assert.equal(controller.select(first), pending, "the same handle returns the pending read");
+    await pending;
+    assert.deepEqual(reads, [`local-file:${first.key}`]);
+    assert.equal(controller.state.record.identity.key, first.key);
+    assert.equal(controller.state.record.prompts.positive.text, "a red fox in snow, detailed fur");
+    await controller.select(second);
+    assert.equal(reads.length, 2);
+    assert.equal(controller.state.record.identity.key, second.key);
+    await controller.select({ ...second, occurrence: {}, reference: {} });
+    assert.equal(reads.length, 2, "the controller's own copy is the same selection");
+    await controller.select({ ...second, url: "blob:http://host.test/evil" });
+    assert.equal(controller.state.error, true, "a foreign handle is published as an error, never read");
+    assert.equal(reads.length, 2);
+    controller.dispose();
+});
+
+test("fileFor admits selected-local-file only for a local identity", async () => {
+    const file = pngFile("a.png", [tEXt("prompt", PROMPT)]);
+    const { wire, handle } = await recordFor(file);
+    const rooted = { root_index: 0, path: "folder/a.png", filename: "a.png", url: "/prompt_manager/images/serve/folder/a.png?root=0" };
+    assert.throws(() => toInspectionRecord({ ...wire, image: { root_index: 0, path: "folder/a.png", filename: "a.png" } }, rooted, extractGenerationFacts), /Invalid inspection file/);
+    assert.throws(() => projectInspectionPayload({ ...wire, file: { ...wire.file, observation: "current-file" } }, { kind: "local-file", key: handle.key, path: "a.png" }, null, extractGenerationFacts), /Invalid inspection file/);
+    assert.throws(() => m.localFileAdapter.toRecord({ ...wire, success: false }, handle, extractGenerationFacts), TypeError);
+    assert.throws(() => m.localFileAdapter.toRecord({ ...wire, inspection_version: 2 }, handle, extractGenerationFacts), TypeError);
+    assert.throws(() => m.localFileAdapter.toRecord(null, handle, extractGenerationFacts), TypeError);
+});
+
+test("the parity corpus PNGs read into renderable records", async () => {
+    for (const name of ["f02.png", "f06a.png", "f23.png"]) {
+        const { wire, record } = await recordFor(fixtureFile(name, PARITY));
+        assert.equal(wire.metadata.status, "available", name);
+        assert.equal(record.file.format, "PNG");
+        assert.ok(["parsed", "limited", "malformed"].includes(wire.metadata.prompt_graph.status));
+    }
+});

tests/js/workspace-local-projection.test.js

@@ -0,0 +1,249 @@
+// web/js/workspace/local-projection.mjs ports utils/inspection_response.py: the
+// strict Decimal/duplicate-key parse, the prompt/workflow/carrier projection, the
+// depth and node ceilings, _metadata and the 8 MiB omission steps. These units pin
+// the rules the plan names; tests/test_local_inspect_parity.py proves byte parity
+// with the server over the committed corpus.
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const m = await import("../../web/js/workspace/local-projection.mjs").catch((error) => {
+    if (error.code !== "ERR_MODULE_NOT_FOUND") throw error;
+    return {};
+});
+const CASES = JSON.parse(fs.readFileSync(path.join(here, "..", "fixtures", "local-inspect", "projection-cases.json"), "utf8")).cases;
+
+const plain = (value) => JSON.parse(JSON.stringify(value));
+const bytes = (value) => Buffer.byteLength(JSON.stringify(value), "utf8");
+const graphOf = (text, kind = "workflow") => plain(m.projectGraph(text, kind));
+const nested = (depth, close = "]", open = "[") => open.repeat(depth) + close.repeat(depth);
+const nodes = (count) => `{${Array.from({ length: count }, (_, i) => `"${i}":{"class_type":"A","inputs":{}}`).join(",")}}`;
+
+test("contract", () => {
+    for (const name of ["projectGraph", "projectMetadata", "fitInspectionPayload", "inspectionBytes", "parseStrictJson"]) {
+        assert.equal(typeof m[name], "function", `${name} is exported`);
+    }
+    assert.equal(m.MAX_RESPONSE_BYTES, 8388608);
+    assert.equal(m.MAX_PROJECTION_DEPTH, 64);
+    assert.equal(m.GRAPH_NODE_CEILING, 20000);
+});
+
+test("projection spells numbers like the server", () => {
+    // literal -> Python str(Decimal(literal)) (or the int when it is a safe integer)
+    const table = [
+        ["1e3", "1E+3"], ["1e0", "1"], ["-0.0", "-0.0"], ["6.50", "6.50"], ["0.0100", "0.0100"], ["1.0e2", "1.0E+2"],
+        ["0e5", "0E+5"], ["0.0000001", "1E-7"], ["0.000001", "0.000001"], ["1E+3", "1E+3"], ["1e-0", "1"], ["0.5e1", "5"],
+        ["0.05e1", "0.5"], ["0.0e0", "0.0"], ["1.5e+300", "1.5E+300"], ["123e-8", "0.00000123"], ["2.5e-3", "0.0025"],
+        ["1.0", "1.0"], ["-1.50", "-1.50"], ["0.0", "0.0"], ["100.0", "100.0"], ["1234567e-6", "1.234567"], ["0.5E-6", "5E-7"],
+        ["0.5E-5", "0.000005"], ["1e22", "1E+22"], ["0.000000", "0.000000"], ["-0.000000e-3", "-0E-9"], ["7.0e-6", "0.0000070"],
+        ["7.0e-7", "7.0E-7"], ["12345678901234567890.123", "12345678901234567890.123"], ["9007199254740992.0", "9007199254740992.0"],
+        ["1e999999999999999999", "1E+999999999999999999"], ["1e-1999999999999999997", "1E-1999999999999999997"],
+        ["0.0e1000000000000000000", "0E+999999999999999999"], ["1.5e999999999999999999", "1.5E+999999999999999999"],
+        ["0.1e-1999999999999999996", "1E-1999999999999999997"],
+        ["9007199254740991", 9007199254740991], ["-9007199254740991", -9007199254740991], ["9007199254740992", "9007199254740992"],
+        ["-9007199254740992", "-9007199254740992"], ["10000000000000000", "10000000000000000"], ["123456789012345678901234567890", "123456789012345678901234567890"],
+        ["0", 0], ["-0", 0], ["42", 42], ["-7", -7],
+    ];
+    for (const [literal, expected] of table) {
+        const graph = graphOf(`{"n":${literal}}`);
+        assert.equal(graph.status, "parsed", literal);
+        assert.deepEqual(graph.value, { n: expected }, literal);
+    }
+    assert.deepEqual(graphOf('{"n":[NaN,Infinity,-Infinity]}').value, { n: [null, null, null] });
+    // A 4300-digit integer is Python's int() limit; one more digit fails the parse.
+    assert.deepEqual(graphOf(`{"n":${"1".repeat(4300)}}`).value, { n: "1".repeat(4300) });
+    assert.equal(graphOf(`{"n":${"1".repeat(4301)}}`).status, "malformed");
+    assert.equal(graphOf(`{"n":-${"1".repeat(4301)}}`).status, "malformed");
+    // Exact Decimal construction fails past the C library's exponent range.
+    for (const literal of ["1e1000000000000000000", "15e999999999999999999", "1e-1999999999999999998", "1.5e-1999999999999999997",
+        "0e1000000000000000000", "1e9223372036854775808", "0.0e1000000000000000001", "1e99999999999999999999999999"]) {
+        assert.equal(graphOf(`{"n":${literal}}`).status, "malformed", literal);
+    }
+    // Escapes: surrogate pairs join, lone surrogates stay, control characters decode.
+    const text = graphOf('{"s":"\\u00E9\\uD83D\\uDE00\\uD800\\u0000\\u001f\\/\\\\\\"\\b\\f\\n\\r\\t\\uD800\\u0041"}').value.s;
+    assert.equal(text, "é\u{1f600}\ud800\u0000\u001f/\\\"\b\f\n\r\t\ud800A");
+    assert.equal(JSON.stringify(m.projectGraph('{"s":"\\ud800"}', "workflow").value), '{"s":"\\ud800"}');
+});
+
+test("projection rejects what Python's json rejects and nothing else", () => {
+    const rejected = ["{}", "\f1", "  1", '{"a":1,}', "[1,]", "{'a':1}", '{"a"}', "[1 2]", "tru", "nul", "-NaN", "1.", ".5", "01", "+1",
+        "1e", "-", '"\\x"', '"abc', "", "  ", '"\u0001"', '{"a":1}x', '"\\u12"', '{"a":1,"a":2}', '{"a":{"b":1,"b":1}}', "[1,[2,{\"k\":1,\"k\":2}]]",
+        '{"a":1 "b":2}', "[,1]", "{,}", '{"a":}', "[1}", "{1:2}", "
[]", "[]\u000b", "0x10", "1_000", "--1", "1e+", "1E-", '"\\uD800\\uDC"'];
+    for (const text of rejected) assert.equal(graphOf(text).status, "malformed", JSON.stringify(text));
+    for (const text of [" \t\r\n{}\n\t ", '{"a":[1,{"b":null}],"c":"d"}', '{"\\u0000":1}', '{"a":1,"A":1}', '{"":[]}']) {
+        assert.equal(graphOf(text).status, "parsed", JSON.stringify(text));
+    }
+    // Top-level values that are not objects parse but are not graphs.
+    for (const text of ["[]", '"x"', "1", "null", "true", "NaN", "1.5", "-Infinity"]) assert.equal(graphOf(text).status, "malformed", text);
+    assert.equal(graphOf(undefined).status, "malformed");
+    assert.equal(graphOf(null).status, "malformed");
+});
+
+test("projection limits", () => {
+    // A workflow's root is depth 1; the 64th nested container is kept, the 65th is limited.
+    assert.equal(graphOf(`{"a":${nested(63)}}`).status, "parsed");
+    assert.equal(graphOf(`{"a":${nested(64)}}`).status, "limited");
+    // Prompt: root 1, node 2, inputs 3; a value chain reaching depth 64 is kept, 65 is limited.
+    assert.equal(graphOf(`{"1":{"class_type":"A","inputs":{"v":${nested(61)}}}}`, "prompt").status, "parsed");
+    assert.equal(graphOf(`{"1":{"class_type":"A","inputs":{"v":${nested(62)}}}}`, "prompt").status, "limited");
+    // Dropped node keys are still validated for depth.
+    assert.equal(graphOf(`{"1":{"class_type":"A","inputs":{},"_meta":{"v":${nested(61)}}}}`, "prompt").status, "parsed");
+    assert.equal(graphOf(`{"1":{"class_type":"A","inputs":{},"_meta":{"v":${nested(62)}}}}`, "prompt").status, "limited");
+    // A workflow is normalized before its shape is checked, so a deep non-object is limited; a
+    // prompt checks its root first. Depth never overflows the parser (100,000 nested arrays).
+    assert.equal(graphOf(nested(10)).status, "malformed");
+    assert.equal(graphOf(nested(5000)).status, "limited");
+    assert.equal(graphOf(nested(5000), "prompt").status, "malformed");
+    assert.equal(graphOf(`{"a":${nested(100000)}}`).status, "limited");
+    // Node ceilings: 20,000 API nodes parse, 20,001 are limited.
+    assert.equal(graphOf(nodes(20000), "prompt").status, "parsed");
+    assert.equal(graphOf(nodes(20001), "prompt").status, "limited");
+    const list = (count) => `[${Array.from({ length: count }, () => "{}").join(",")}]`;
+    assert.equal(graphOf(`{"nodes":${list(20000)}}`).status, "parsed");
+    assert.equal(graphOf(`{"nodes":${list(20001)}}`).status, "limited");
+    assert.equal(graphOf(`{"nodes":${list(10001)},"definitions":{"subgraphs":[{"nodes":${list(10000)}},5,{"nodes":3}]}}`).status, "limited");
+    assert.equal(graphOf(`{"nodes":${list(10000)},"definitions":{"subgraphs":[{"nodes":${list(10000)}}]}}`).status, "parsed");
+    assert.equal(graphOf(`{"nodes":{"${"x".repeat(5)}":1},"definitions":[]}`).status, "parsed");
+    // Duplicate keys anywhere are malformed, including inside dropped node keys.
+    assert.equal(graphOf('{"1":{"class_type":"A","inputs":{},"_meta":{"t":1,"t":2}}}', "prompt").status, "malformed");
+    assert.equal(graphOf('{"1":{"class_type":"A","inputs":{"a":1,"a":1}}}', "prompt").status, "malformed");
+});
+
+test("prompt nodes keep only class_type and inputs on null-prototype objects", () => {
+    const text = '{"3":{"class_type":"KSampler","inputs":{"seed":9007199254740993,"cfg":8.0,"n":NaN},"_meta":{"title":"x"},"is_changed":[1]},"4":5,"5":[1,2.50],"__proto__":{"class_type":"P","inputs":{}},"constructor":"c"}';
+    const graph = m.projectGraph(text, "prompt");
+    assert.equal(graph.status, "parsed");
+    assert.equal(Object.getPrototypeOf(graph.value), null);
+    assert.equal(Object.getPrototypeOf(graph.value["3"]), null);
+    assert.equal(Object.getPrototypeOf(graph.value["3"].inputs), null);
+    // JSON.parse, like the projection, makes "__proto__" an own key; an object literal would not.
+    assert.deepEqual(plain(graph.value), JSON.parse('{"3":{"class_type":"KSampler","inputs":{"seed":"9007199254740993","cfg":"8.0","n":null}},"4":5,"5":[1,"2.50"],"__proto__":{"class_type":"P","inputs":{}},"constructor":"c"}'));
+    assert.ok(Object.hasOwn(graph.value, "__proto__"));
+    assert.deepEqual(plain(graph.value["__proto__"]), { class_type: "P", inputs: {} });
+    assert.equal(graph.value.constructor, "c");
+    for (const text of ["[]", '"3"', "5", "null", '{"nodes":[]}x']) assert.equal(m.projectGraph(text, "prompt").status, text === '{"nodes":[]}x' ? "malformed" : "malformed", text);
+    // A workflow keeps everything, normalized.
+    assert.deepEqual(graphOf('{"nodes":[{"id":1,"widgets_values":[7,"fixed",8.0,1e3]}],"links":[],"version":0.4}').value,
+        { nodes: [{ id: 1, widgets_values: [7, "fixed", "8.0", "1E+3"] }], links: [], version: "0.4" });
+});
+
+test("projectMetadata mirrors _metadata for records, formats and carriers", () => {
+    const prompt = '{"1":{"class_type":"A","inputs":{"x":1.0}}}', workflow = '{"nodes":[],"version":0.4}';
+    const read = (records, record_formats, carrierText = null, limited = []) => ({ records, record_formats, carrierText, limited });
+    assert.deepEqual(plain(m.projectMetadata(null)), { status: "unreadable", omitted_reason: null, raw: {}, record_formats: {}, parameters: null,
+        prompt_graph: { status: "absent", value: null }, workflow_graph: { status: "absent", value: null } });
+    assert.deepEqual(plain(m.projectMetadata(read({}, {}))), { status: "absent", omitted_reason: null, raw: {}, record_formats: {}, parameters: null,
+        prompt_graph: { status: "absent", value: null }, workflow_graph: { status: "absent", value: null } });
+    const full = plain(m.projectMetadata(read({ prompt, workflow, parameters: "cat\nSteps: 1", comfyassets_prompt_pairs: "{}", other: "x" },
+        { prompt: "original-text", workflow: "original-text", parameters: "original-text", comfyassets_prompt_pairs: "original-text", other: "original-text" })));
+    assert.deepEqual(full, { status: "available", omitted_reason: null,
+        raw: { prompt, workflow, parameters: "cat\nSteps: 1", comfyassets_prompt_pairs: "{}" },
+        record_formats: { prompt: "original-text", workflow: "original-text", parameters: "original-text", comfyassets_prompt_pairs: "original-text" },
+        parameters: "cat\nSteps: 1", prompt_graph: { status: "parsed", value: { 1: { class_type: "A", inputs: { x: "1.0" } } } },
+        workflow_graph: { status: "parsed", value: { nodes: [], version: "0.4" } } });
+    // limited records lose their text; invalid is malformed; reserialized without a carrier is limited.
+    const limited = plain(m.projectMetadata(read({ prompt, workflow }, { prompt: "original-text" }, null, ["workflow"])));
+    assert.deepEqual(limited.raw, { prompt });
+    assert.deepEqual(limited.record_formats, { prompt: "original-text", workflow: "limited" });
+    assert.equal(limited.workflow_graph.status, "limited");
+    assert.equal(plain(m.projectMetadata(read({ prompt }, { prompt: "original-text", workflow: "invalid" }))).workflow_graph.status, "malformed");
+    assert.equal(plain(m.projectMetadata(read({ workflow }, { workflow: "reserialized-json" }))).workflow_graph.status, "limited");
+    assert.equal(plain(m.projectMetadata(read({ prompt: "{" }, { prompt: "original-text" }))).prompt_graph.status, "malformed");
+    // Unknown formats are dropped from record_formats but the raw text still projects.
+    const odd = plain(m.projectMetadata(read({ prompt }, { prompt: "weird" })));
+    assert.deepEqual(odd.record_formats, {});
+    assert.equal(odd.prompt_graph.status, "parsed");
+    // A non-text record vanishes from raw and its named graph is malformed.
+    assert.equal(plain(m.projectMetadata(read({ prompt: 5 }, { prompt: "original-text" }))).prompt_graph.status, "malformed");
+    // Carriers: strings re-parse by kind, objects were projected at depth 2; a bad carrier fails every present graph.
+    const envelope = JSON.stringify({ prompt, workflow: { nodes: [], v: 1 } });
+    const carried = plain(m.projectMetadata(read({ prompt, workflow: '{"nodes": [], "v": 1}' }, { prompt: "original-text", workflow: "reserialized-json" }, envelope)));
+    assert.deepEqual(carried.prompt_graph, { status: "parsed", value: { 1: { class_type: "A", inputs: { x: "1.0" } } } });
+    assert.deepEqual(carried.workflow_graph, { status: "parsed", value: { nodes: [], v: 1 } });
+    const broken = plain(m.projectMetadata(read({ prompt, workflow }, { prompt: "original-text", workflow: "original-text" }, "[1]")));
+    assert.deepEqual([broken.prompt_graph.status, broken.workflow_graph.status], ["malformed", "malformed"]);
+    const deep = plain(m.projectMetadata(read({ prompt }, { prompt: "original-text" }, `{"title":${nested(70)},"prompt":${JSON.stringify(prompt)}}`)));
+    assert.equal(deep.prompt_graph.status, "limited");
+    const partial = plain(m.projectMetadata(read({ prompt, workflow }, { prompt: "original-text", workflow: "original-text" }, '{"prompt":"{","workflow":5}')));
+    assert.deepEqual([partial.prompt_graph.status, partial.workflow_graph.status], ["malformed", "malformed"]);
+    const missing = plain(m.projectMetadata(read({ prompt }, { prompt: "original-text" }, '{"workflow":{}}')));
+    assert.deepEqual([missing.prompt_graph.status, missing.workflow_graph.status], ["malformed", "absent"]);
+    // The carrier's own prompt object is projected: depth 2, node keys filtered.
+    const objectPrompt = plain(m.projectMetadata(read({ prompt: "x" }, { prompt: "reserialized-json" }, '{"prompt":{"1":{"class_type":"A","inputs":{},"_meta":{}}}}')));
+    assert.deepEqual(objectPrompt.prompt_graph, { status: "parsed", value: { 1: { class_type: "A", inputs: {} } } });
+});
+
+test("fitInspectionPayload omits the workflow graph, then the prompt graph, then all raw atomically", async () => {
+    const payload = {
+        success: true, inspection_version: 1, metadata: {
+            status: "available", omitted_reason: null, raw: { prompt: "é".repeat(100), workflow: "{}" }, record_formats: { prompt: "original-text", workflow: "original-text" },
+            parameters: null, prompt_graph: { status: "parsed", value: { 1: { class_type: "A", inputs: { t: "\ud800".repeat(50) } } } },
+            workflow_graph: { status: "parsed", value: { nodes: Array.from({ length: 50 }, (_, i) => ({ id: i })) } },
+        },
+    };
+    const text = JSON.stringify(payload);
+    // UTF-8 bytes, not UTF-16 code units: 'é' is 2 bytes, an escaped lone surrogate 6.
+    assert.equal(m.inspectionBytes(payload), Buffer.byteLength(text, "utf8"));
+    assert.ok(m.inspectionBytes(payload) > text.length);
+    // Measured in bounded chunks: pairs and 2-byte characters across every chunk edge count once.
+    for (const shift of [0, 1, 2, 3]) {
+        const wide = { s: "x".repeat(shift) + "é😀".repeat(200000) + "\ud800", t: "a😀".repeat(70000) };
+        assert.equal(m.inspectionBytes(wide), Buffer.byteLength(JSON.stringify(wide), "utf8"), `shift ${shift}`);
+    }
+    const whole = await m.fitInspectionPayload(payload, bytes(payload));
+    assert.equal(whole, payload, "a payload within the limit is returned as is");
+    const first = await m.fitInspectionPayload(payload, bytes(payload) - 1);
+    assert.equal(first.metadata.workflow_graph.status, "limited");
+    assert.equal(first.metadata.prompt_graph.status, "parsed");
+    assert.deepEqual(first.metadata.raw, payload.metadata.raw);
+    assert.ok(bytes(first) <= bytes(payload) - 1);
+    const second = await m.fitInspectionPayload(payload, bytes(first) - 1);
+    assert.deepEqual([second.metadata.workflow_graph.status, second.metadata.prompt_graph.status], ["limited", "limited"]);
+    assert.equal(second.metadata.status, "available");
+    assert.deepEqual(second.metadata.raw, payload.metadata.raw);
+    const third = await m.fitInspectionPayload(payload, bytes(second) - 1);
+    assert.deepEqual(third.metadata, { ...second.metadata, raw: {}, parameters: null, status: "limited", omitted_reason: "response-size-limit" });
+    assert.ok(bytes(third) <= bytes(second) - 1);
+    await assert.rejects(m.fitInspectionPayload(payload, bytes(third) - 1), /exceeds/);
+    // The caller's payload is never mutated and absent graphs are left alone.
+    assert.equal(JSON.stringify(payload), text);
+    const absent = { ...payload, metadata: { ...payload.metadata, workflow_graph: { status: "absent", value: null } } };
+    const fitted = await m.fitInspectionPayload(absent, bytes(absent) - 1);
+    assert.equal(fitted.metadata.workflow_graph.status, "absent");
+    assert.equal(fitted.metadata.prompt_graph.status, "limited");
+    assert.equal((await m.fitInspectionPayload(payload)).metadata.status, "available", "the default limit is 8 MiB");
+    // Every omission step after the first measure hands the event loop a turn, and an
+    // abort between steps rejects with AbortError; the answer itself is unchanged.
+    let turns = 0;
+    const counted = await m.fitInspectionPayload(payload, bytes(second) - 1, { yieldControl: async () => { turns += 1; } });
+    assert.equal(JSON.stringify(counted), JSON.stringify(third));
+    assert.equal(turns, 3);
+    assert.equal(await m.fitInspectionPayload(payload, bytes(payload), { yieldControl: async () => { turns += 1; } }), payload);
+    assert.equal(turns, 3, "a payload within the limit is measured once, without a turn");
+    const controller = new AbortController();
+    await assert.rejects(m.fitInspectionPayload(payload, bytes(second) - 1, { signal: controller.signal, yieldControl: async () => controller.abort() }), { name: "AbortError" });
+});
+
+test("the committed projection corpus has every outcome and parses with the oracle entry shape", () => {
+    assert.ok(CASES.length >= 40);
+    const names = new Set(), statuses = new Set(), graphs = new Set();
+    for (const entry of CASES) {
+        assert.equal(typeof entry.name, "string");
+        assert.ok(!names.has(entry.name), `duplicate case ${entry.name}`);
+        names.add(entry.name);
+        const read = entry.records === null ? null : { records: entry.records, record_formats: entry.record_formats ?? Object.fromEntries(Object.keys(entry.records).map((key) => [key, "original-text"])),
+            carrierText: entry.carrier_text ?? null, limited: entry.limited ?? [] };
+        const metadata = m.projectMetadata(read);
+        statuses.add(metadata.status);
+        graphs.add(metadata.prompt_graph.status);
+        graphs.add(metadata.workflow_graph.status);
+        if (entry.expect) {
+            for (const [field, status] of Object.entries(entry.expect)) assert.equal(metadata[field].status, status, `${entry.name} ${field}`);
+        }
+    }
+    assert.deepEqual([...statuses].sort(), ["absent", "available", "unreadable"]);
+    assert.deepEqual([...graphs].sort(), ["absent", "limited", "malformed", "parsed"]);
+});

tests/js/workspace-local-video.test.js

@@ -0,0 +1,622 @@
+// Run with: node --test tests/js/
+// The browser video tag readers mirror what the server reads through ffprobe
+// (utils/prompt_inspector.py _video_metadata) and the carrier rule of
+// utils/video_metadata.py select_video_carrier. Each rule names its server twin;
+// tests/test_local_inspect_parity.py proves the two agree on the committed fixtures
+// and on recorded tag maps.
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as v from "./helpers/video-bytes.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const FIXTURES = path.join(here, "..", "fixtures", "local-inspect");
+const RECORDED = JSON.parse(fs.readFileSync(path.join(FIXTURES, "video-tags-v1.json"), "utf8")).fixtures;
+const m = await import("../../web/js/workspace/local-video.mjs").catch((error) => {
+    if (error.code !== "ERR_MODULE_NOT_FOUND") throw error;
+    return {};
+});
+const { readVideoTags, selectVideoCarrier, pythonJsonDumps, pythonJsonLoads } = m;
+
+const MiB = 1024 * 1024;
+const GiB = 1024 * MiB;
+const ROLE_BUDGET = 2 * MiB;
+const WORKFLOW_BUDGET = 4 * MiB;
+const TAG_READ_BYTES = 12 * MiB + 64 * 1024;
+const PER_KEY = new Set(["prompt", "workflow", "parameters", "comfyassets_prompt_pairs"]);
+const GRAPH = '{"3":{"class_type":"KSampler","inputs":{"seed":7}}}';
+const WORKFLOW = '{"nodes":[],"version":0.4}';
+
+// The tags ffprobe reports to the server: the six probed names, ASCII case folded.
+function knownTags(map) {
+    return Object.fromEntries(Object.entries(map).filter(([name]) => PER_KEY.has(name.toLowerCase()) || ["comment", "description"].includes(name.toLowerCase())));
+}
+
+function fixture(name) {
+    return new Uint8Array(fs.readFileSync(path.join(FIXTURES, name)));
+}
+
+async function read(bytes, options = {}) {
+    return readVideoTags(v.blobOf(bytes), options);
+}
+
+function fill(byte, count) {
+    return Buffer.alloc(count, byte);
+}
+
+function complete(tags, extra = {}) {
+    return { status: "complete", tags, limited: [], ...extra };
+}
+
+test("contract: the readers, the carrier rule and the json port are exported", () => {
+    assert.equal(typeof readVideoTags, "function");
+    assert.equal(typeof selectVideoCarrier, "function");
+    assert.equal(typeof pythonJsonDumps, "function");
+    assert.equal(typeof pythonJsonLoads, "function");
+});
+
+test("iso-bmff reader finds per-key tags with moov after mdat", async () => {
+    for (const [name, recorded] of Object.entries(RECORDED)) {
+        const blob = v.recordingBlob(fixture(name));
+        const result = await readVideoTags(blob, { prefix: fixture(name).subarray(0, 32) });
+        assert.equal(result.status, "complete", name);
+        assert.deepEqual(result.tags, knownTags(recorded), name);
+        assert.equal(result.container, name.endsWith(".mkv") || name.endsWith(".webm") ? "matroska" : "iso-bmff", name);
+        assert.ok(["isom", "qt", "M4V", "matroska", "webm"].includes(result.format), `${name}: ${result.format}`);
+        assert.deepEqual(result.limited, [], name);
+        assert.ok(blob.ranges.length > 0, name);
+    }
+    // core-moov-end.mp4 behind a 3 GiB mdat: only the box headers and the tag bytes are sliced.
+    const bytes = fixture("core-moov-end.mp4");
+    const boxes = v.topLevelBoxes(bytes);
+    const mdat = boxes.find((box) => box.type === "mdat");
+    const moov = boxes.find((box) => box.type === "moov");
+    const mdatSize = 3 * GiB + 16;
+    const header = v.concat(v.u32(1), v.latin1("mdat"), new Uint8Array(8));
+    new DataView(header.buffer).setBigUint64(8, BigInt(mdatSize));
+    const moovOffset = mdat.start + mdatSize;
+    const blob = v.sparseBlob(
+        [
+            { offset: 0, bytes: bytes.subarray(0, mdat.start) },
+            { offset: mdat.start, bytes: header },
+            { offset: moovOffset, bytes: bytes.subarray(moov.start, moov.end) },
+        ],
+        moovOffset + (moov.end - moov.start),
+    );
+    const result = await readVideoTags(blob, { prefix: bytes.subarray(0, 32) });
+    assert.deepEqual(result.tags, knownTags(RECORDED["core-moov-end.mp4"]));
+    const inside = blob.ranges.filter(([start]) => start >= mdat.start && start < moovOffset);
+    assert.ok(inside.every(([start, end]) => start === mdat.start && end - start <= 16), JSON.stringify(inside));
+    const total = blob.ranges.reduce((sum, [start, end]) => sum + (end - start), 0);
+    assert.ok(total <= m.VIDEO_READ_CEILING && total < 64 * 1024, `${total}`);
+});
+
+test("iso-bmff: legacy ilst atoms, moov/meta, sticky mdta handler and data types", async () => {
+    // ©cmt and desc map to comment and description, as ffprobe reports them.
+    const legacy = await read(v.mp4(v.legacyUdta({ comment: '{"prompt":"{}"}', description: "note" })));
+    assert.deepEqual(legacy, complete({ comment: '{"prompt":"{}"}', description: "note" }, { container: "iso-bmff", format: "isom" }));
+    // moov/meta (ISO style) is read like moov/udta/meta.
+    const isoMeta = await read(v.mp4(v.box("meta", v.u32(0), v.hdlr("mdta"), v.keys(["prompt"]), v.ilst(v.item(1, v.data(GRAPH))))));
+    assert.deepEqual(isoMeta.tags, { prompt: GRAPH });
+    // meta without the version/flags word (QuickTime) still finds hdlr.
+    const qtMeta = await read(v.mp4(v.udta(v.box("meta", v.hdlr("mdta"), v.keys(["prompt"]), v.ilst(v.item(1, v.data(GRAPH)))))));
+    assert.deepEqual(qtMeta.tags, { prompt: GRAPH });
+    // Index items need an mdta handler and a keys box; with a legacy handler they are skipped.
+    const noKeys = await read(v.mp4(v.udta(v.meta(v.hdlr("mdir"), v.ilst(v.item(1, v.data(GRAPH)))))));
+    assert.deepEqual(noKeys.tags, {});
+    // The mdta handler is sticky across the file, as ffmpeg's found_hdlr_mdta.
+    const sticky = await read(v.mp4(v.udta(v.meta(v.hdlr("mdta"), v.keys(["prompt"])), v.meta(v.hdlr("mdir"), v.ilst(v.item(1, v.data(GRAPH)))))));
+    assert.deepEqual(sticky.tags, { prompt: GRAPH });
+    // As ffprobe reports them: consecutive data children join with ";", integer data
+    // types print as decimals, other types are not tags, text types 0/1/4 are read, NUL
+    // truncates, and the run of data children stops at the first other child.
+    const mixed = await read(v.mp4(v.udta(v.meta(
+        v.hdlr("mdta"),
+        v.keys(["prompt", "workflow", "parameters", "comfyassets_prompt_pairs", "comment", "description"]),
+        v.ilst(
+            v.item(1, v.data("first"), v.data("second"), v.box("name", "x"), v.data("not read")),
+            v.item(2, v.data([0, 0, 0, 7], { type: 21 }), v.data([0xff, 0xfe], { type: 21 }), v.data([0xff, 0xfe], { type: 22 })),
+            v.item(3, v.data("cut\0off")),
+            v.item(4, v.data("sort", { type: 4 }), v.data("mac", { type: 0 })),
+            v.item(5, v.data([0, 0, 0, 0, 0, 0, 0], { type: 21 })),
+            v.item(6, v.data("float", { type: 23 })),
+        ),
+    ))));
+    assert.deepEqual(mixed.tags, { prompt: "first;second", workflow: "7;-2;65534", parameters: "cut", comfyassets_prompt_pairs: "sort;mac" });
+    // Keys outside the mdta namespace address nothing; unknown names are skipped unread.
+    const blob = v.recordingBlob(v.mp4(v.udta(v.meta(
+        v.hdlr("mdta"),
+        v.keys([["prompt", "udta"], "encoder", "workflow"]),
+        v.ilst(v.item(1, v.data(GRAPH)), v.item(2, v.data(fill(0x41, 5000))), v.item(3, v.data(WORKFLOW))),
+    ))));
+    const result = await readVideoTags(blob);
+    assert.deepEqual(result.tags, { workflow: WORKFLOW });
+    assert.ok(blob.ranges.every(([start, end]) => end - start < 5000), "the encoder value was never sliced");
+    // Legacy fourccs are mapped even in mdta mode, and a repeated name joins with ";".
+    const repeated = await read(v.mp4(v.udta(v.meta(
+        v.hdlr("mdta"),
+        v.keys(["prompt", "prompt", "comment"]),
+        v.ilst(v.item(1, v.data("one")), v.item(2, v.data("two")), v.item(3, v.data("mdta")), v.legacyItem("©cmt", v.data("c"))),
+    ))));
+    assert.deepEqual(repeated.tags, { prompt: "one;two", comment: "mdta;c" });
+    // Apple's namespaced keys are reported verbatim, so they are never an envelope.
+    const apple = await read(v.perKeyMp4({ "com.apple.quicktime.description": '{"prompt":"{}"}', prompt: GRAPH }));
+    assert.deepEqual(apple.tags, { prompt: GRAPH });
+    // An item whose first child is not a data atom, or a data atom shorter than its
+    // 16-byte header, is skipped as ffmpeg skips it.
+    const junk = await read(v.mp4(v.udta(v.meta(v.hdlr("mdta"), v.keys(["prompt"]), v.ilst(v.item(1, v.box("name", "x"), v.data(GRAPH)))))));
+    assert.deepEqual(junk.tags, {});
+    const short = await read(v.mp4(v.udta(v.meta(v.hdlr("mdta"), v.keys(["prompt"]), v.ilst(v.item(1, v.data(GRAPH, { size: 12 })))))));
+    assert.deepEqual(short.tags, {});
+    // A box declared with size 0 runs to the end of its parent; faststart puts moov first.
+    const fast = await read(v.perKeyMp4({ prompt: GRAPH }, { faststart: true, brand: "mp42" }));
+    assert.deepEqual(fast, complete({ prompt: GRAPH }, { container: "iso-bmff", format: "mp42" }));
+    const toEnd = await read(v.concat(v.ftyp(), v.mdat(), v.moov(v.mdtaUdta({ prompt: GRAPH }), v.opts({ size: 0 }))));
+    assert.deepEqual(toEnd.tags, { prompt: GRAPH });
+});
+
+test("matroska reads global Tags and skips clusters", async () => {
+    const { ID } = v;
+    // ffmpeg layout: SeekHead, Info, Tracks, Tags, Cluster, Cues; names upper-cased.
+    const plain = await read(v.perKeyMkv({ PROMPT: GRAPH, WORKFLOW, ENCODER: "Lavf" }, { docType: "webm" }));
+    assert.deepEqual(plain, complete({ PROMPT: GRAPH, WORKFLOW }, { container: "matroska", format: "webm" }));
+    // Tags after a 3 GiB Cluster, located through the SeekHead: no slice inside the cluster.
+    const tags = v.globalTags({ PROMPT: GRAPH });
+    const clusterSize = 3 * GiB;
+    // The Tags position (relative to the Segment payload) is a 4-byte uint either way,
+    // so the SeekHead's length can be measured with a placeholder first.
+    const seekLength = v.seekHead([[ID.Tags, clusterSize]]).length;
+    const seekHead = v.seekHead([[ID.Tags, seekLength + 12 + clusterSize]]);
+    assert.equal(seekHead.length, seekLength);
+    const head = v.concat(v.ebmlHeader(), v.idBytes(ID.Segment), v.vint(seekHead.length + 12 + clusterSize + tags.length, { width: 8 }), seekHead, v.clusterHeader(clusterSize));
+    const clusterStart = v.ebmlHeader().length + 12 + seekHead.length;
+    const tagsOffset = head.length + clusterSize;
+    const blob = v.sparseBlob([{ offset: 0, bytes: head }, { offset: tagsOffset, bytes: tags }], tagsOffset + tags.length);
+    const seeked = await readVideoTags(blob, { prefix: head.subarray(0, 32) });
+    assert.deepEqual(seeked.tags, { PROMPT: GRAPH });
+    const inside = blob.ranges.filter(([start]) => start >= clusterStart && start < tagsOffset);
+    assert.ok(inside.every(([start, end]) => start === clusterStart && end - start <= 16), JSON.stringify(inside));
+    assert.ok(blob.ranges.reduce((sum, [start, end]) => sum + (end - start), 0) <= m.VIDEO_READ_CEILING);
+    // ffprobe reads level-1 elements up to the first Cluster: Tags behind it are found
+    // only through a SeekHead, so without one they are not read (nor sliced).
+    const behind = v.recordingBlob(v.mkv([v.cluster(64), v.globalTags({ PROMPT: GRAPH }), el(ID.Cues, new Uint8Array(2))]));
+    const sequential = await readVideoTags(behind);
+    assert.deepEqual(sequential.tags, {});
+    assert.ok(behind.ranges.every(([, end]) => end <= v.ebmlHeader().length + 12 + 12 + 32), JSON.stringify(behind.ranges));
+    // Track-targeted Tags are ignored; chapter and attachment targets too.
+    const targeted = await read(v.mkv([
+        v.tagsEl(
+            v.tag([v.simpleTag("PROMPT", "track")], { trackUid: 1 }),
+            v.tag([v.simpleTag("WORKFLOW", WORKFLOW)], { targetType: 50 }),
+            v.tag([v.simpleTag("PROMPT", "zero uid is global")], { trackUid: 0 }),
+        ),
+        v.cluster(),
+    ]));
+    assert.deepEqual(targeted.tags, { WORKFLOW, PROMPT: "zero uid is global" });
+    // An unknown-size Cluster (live recordings) is the same stop; a SeekHead still works.
+    const hidden = await read(v.mkv([v.cluster(8, { unknown: true }), v.globalTags({ PROMPT: GRAPH })]));
+    assert.deepEqual(hidden, complete({}, { container: "matroska", format: "matroska" }));
+    const before = await read(v.mkv([v.globalTags({ PROMPT: GRAPH }), v.cluster(8, { unknown: true })]));
+    assert.deepEqual(before.tags, { PROMPT: GRAPH });
+    const info = el(ID.Info, new Uint8Array(4));
+    const clusterUnknown = v.cluster(8, { unknown: true });
+    const seekToTags = v.seekHead([[ID.Tags, 0x7f]]); // a one-byte position, like the real one
+    const viaSeek = await read(v.mkv([v.seekHead([[ID.Tags, seekToTags.length + info.length + clusterUnknown.length]]), info, clusterUnknown, v.globalTags({ PROMPT: GRAPH })]));
+    assert.deepEqual(viaSeek.tags, { PROMPT: GRAPH });
+    // An unknown-size Segment is fine (live recordings); other unknown sizes are invalid.
+    const liveSegment = await read(v.mkv([v.globalTags({ PROMPT: GRAPH }), v.cluster()], { unknown: true }));
+    assert.deepEqual(liveSegment.tags, { PROMPT: GRAPH });
+    const unknownTags = await read(v.mkv([el(ID.Tags, v.tag([v.simpleTag("PROMPT", GRAPH)]), v.opts({ unknown: true }))]));
+    assert.deepEqual(unknownTags, { status: "unreadable", reason: "invalid-container" });
+    // ffmpeg's tag naming (checked against ffprobe 9.0.2): a language other than und
+    // files the tag under NAME-lang only, unless TagDefault is set; nested SimpleTags
+    // become PARENT/CHILD (never ours); a string-less tag deletes the key; a repeated
+    // name keeps the last value; NUL ends the string; Void and CRC-32 are skipped.
+    const naming = await read(v.mkv([
+        v.voidEl(8),
+        v.tagsEl(
+            el(ID.CRC32, new Uint8Array(4)),
+            v.tag([
+                v.simpleTag("PROMPT", "eng only", { lang: "eng" }),
+                v.simpleTag("WORKFLOW", "eng only", { lang: "eng", def: 0 }),
+                v.simpleTag("workflow", "default and eng", { lang: "eng", def: 1 }),
+                v.simpleTag("PARAMETERS", "und", { lang: "und", nested: [v.simpleTag("prompt", "nested")] }),
+                v.simpleTag("comfyassets_prompt_pairs", "cut\0here"),
+                v.simpleTag("description", undefined, { binary: [1, 2, 3] }),
+                v.simpleTag("comment", "note"),
+                v.simpleTag("comment", undefined),
+                v.simpleTag("prompt", "first"),
+                v.simpleTag("prompt", "last", { binary: [1] }),
+            ]),
+        ),
+        v.cluster(),
+    ]));
+    assert.deepEqual(naming.tags, { workflow: "default and eng", PARAMETERS: "und", comfyassets_prompt_pairs: "cut", prompt: "last" });
+    // Long names are never ours and are skipped without reading their strings.
+    const longName = v.recordingBlob(v.mkv([v.tagsEl(v.tag([v.simpleTag("N".repeat(300), fill(0x41, 4000)), v.simpleTag("PROMPT", GRAPH)])), v.cluster()]));
+    const skipped = await readVideoTags(longName);
+    assert.deepEqual(skipped.tags, { PROMPT: GRAPH });
+    assert.ok(longName.ranges.every(([start, end]) => end - start < 300));
+    function el(id, ...parts) {
+        return v.el(id, ...parts);
+    }
+});
+
+test("containers fail closed", async () => {
+    const { ID } = v;
+    const invalid = { status: "unreadable", reason: "invalid-container" };
+    const rows = [
+        ["box size below its header", v.concat(v.ftyp(), v.box("free", v.opts({ size: 4 })), v.mdat(), v.moov(v.mdtaUdta({ prompt: GRAPH })))],
+        ["child box past its parent", v.concat(v.ftyp(), v.mdat(), v.moov(v.udta(v.meta(v.hdlr("mdta"), v.keys(["prompt"]), v.ilst(v.item(1, v.data(GRAPH), v.opts({ size: 5000 })))))))],
+        ["top-level box past the end of the file", v.concat(v.ftyp(), v.mdat(), v.box("moov", v.opts({ size: 4000 })))],
+        ["64-bit size above MAX_SAFE_INTEGER", v.concat(v.ftyp(), v.box("mdat", v.opts({ largesize: 2 ** 60 })), v.moov(v.mdtaUdta({ prompt: GRAPH })))],
+        ["64-bit size below its header", v.concat(v.ftyp(), v.box("mdat", v.opts({ largesize: 12 })), v.moov(v.mdtaUdta({ prompt: GRAPH })))],
+        ["keys count larger than the entries", v.mp4(v.udta(v.meta(v.hdlr("mdta"), v.keys(["prompt"], { count: 3 }), v.ilst(v.item(1, v.data(GRAPH))))))],
+        ["keys entry overrunning the box", v.mp4(v.udta(v.meta(v.hdlr("mdta"), v.box("keys", v.u32(0), v.u32(1), v.u32(90), v.latin1("mdta"), v.utf8("prompt")), v.ilst(v.item(1, v.data(GRAPH))))))],
+        ["no moov box", v.concat(v.ftyp(), v.mdat(), v.free(32))],
+        ["not a container at all", v.utf8("#EXTM3U\n#EXT-X-VERSION:3\n".padEnd(64, "x"))],
+        ["bad VINT: zero ID byte", v.concat(v.ebmlHeader(), v.idBytes(ID.Segment), v.vint(20, { width: 8 }), [0x00, 0x81, 0x00], new Uint8Array(17))],
+        ["bad VINT: zero size byte", v.concat(v.ebmlHeader(), v.idBytes(ID.Segment), v.vint(20, { width: 8 }), v.idBytes(ID.Info), [0x00], new Uint8Array(17))],
+        ["element past its parent", v.mkv([v.el(ID.Tags, v.tag([v.simpleTag("PROMPT", GRAPH)]), v.opts({ size: 5000 }))])],
+        ["element past the end of the file", v.concat(v.ebmlHeader(), v.idBytes(ID.Segment), v.vint(5000, { width: 8 }), v.globalTags({ PROMPT: GRAPH }))],
+        ["unknown DocType", v.perKeyMkv({ PROMPT: GRAPH }, { docType: "avi" })],
+        ["EBML header without a DocType", v.concat(v.el(ID.EBML, v.el(ID.EBMLVersion, [1])), v.segment([v.globalTags({ PROMPT: GRAPH })]))],
+        ["Matroska bytes after a stray size", v.concat(v.ebmlHeader(), v.idBytes(ID.Segment), v.vint(3, { width: 8 }), [0xec, 0x82, 0x00])],
+    ];
+    for (const [name, bytes] of rows) {
+        assert.deepEqual(await read(bytes), invalid, name);
+    }
+    // Trailing bytes shorter than a box header are ignored, as ffmpeg does.
+    assert.deepEqual((await read(v.concat(v.perKeyMp4({ prompt: GRAPH }), [1, 2, 3]))).tags, { prompt: GRAPH });
+    // 10,001 boxes stop the read.
+    const many = v.concat(v.ftyp(), ...Array.from({ length: 10001 }, () => v.free()), v.mdat(), v.moov(v.mdtaUdta({ prompt: GRAPH })));
+    assert.deepEqual(await read(many), { status: "limited", reason: "chunk-limit" });
+    const manyElements = v.mkv([...Array.from({ length: 10001 }, () => v.voidEl(1)), v.globalTags({ PROMPT: GRAPH })]);
+    assert.deepEqual(await read(manyElements), { status: "limited", reason: "chunk-limit" });
+    // Exactly 10,000 elements still read (ftyp, mdat, moov, udta, meta, hdlr, keys, its entry, ilst, the item and its data atom).
+    const exact = v.concat(v.ftyp(), ...Array.from({ length: 10000 - 11 }, () => v.free()), v.mdat(), v.moov(v.mdtaUdta({ prompt: GRAPH })));
+    assert.deepEqual((await read(exact)).tags, { prompt: GRAPH });
+    // A vanished file is a read failure, not a container error.
+    assert.deepEqual(await readVideoTags(v.failingBlob(4096), { prefix: v.ftyp() }), { status: "unreadable", reason: "read-failure" });
+    assert.deepEqual(await readVideoTags({}), { status: "unreadable", reason: "read-failure" });
+});
+
+// ffprobe's string_validation=replace (av_utf8_decode): one U+FFFD per failing
+// decode step. A bad continuation or a truncated sequence fails one byte at a time;
+// an overlong form, a surrogate, a code above U+10FFFF, U+FFFE/U+FFFF and 5/6-byte
+// forms fail as one whole sequence. Each row was read through ffprobe 9.0.2.
+const FFPROBE_REPLACEMENTS = [
+    ["one Latin-1 byte", [0x63, 0x61, 0x66, 0xe9], "caf�"],
+    ["truncated 4-byte sequence", [0x61, 0xf0, 0x9f, 0x22, 0x62], 'a��"b'],
+    ["overlong 2-byte form", [0x61, 0xc0, 0xaf, 0x62], "a�b"],
+    ["C1 overlong lead", [0x61, 0xc1, 0xbf, 0x62], "a�b"],
+    ["overlong 3-byte form", [0x61, 0xe0, 0x80, 0x80, 0x62], "a�b"],
+    ["overlong 4-byte form", [0x61, 0xf0, 0x80, 0x80, 0x80, 0x62], "a�b"],
+    ["UTF-16 surrogate", [0x61, 0xed, 0xa0, 0x80, 0x62], "a�b"],
+    ["U+FFFE", [0x61, 0xef, 0xbf, 0xbe, 0x62], "a�b"],
+    ["U+FFFF", [0x61, 0xef, 0xbf, 0xbf, 0x62], "a�b"],
+    ["U+FDD0 is kept", [0x61, 0xef, 0xb7, 0x90, 0x62], "a﷐b"],
+    ["5-byte form", [0x61, 0xf8, 0x88, 0x80, 0x80, 0x80, 0x62], "a�b"],
+    ["6-byte form", [0x61, 0xfc, 0x84, 0x80, 0x80, 0x80, 0x80, 0x62], "a�b"],
+    ["truncated 5-byte form", [0x61, 0xf8, 0x88, 0x62], "a��b"],
+    ["above U+10FFFF", [0x61, 0xf4, 0x90, 0x80, 0x80, 0x62], "a�b"],
+    ["0xFE", [0x61, 0xfe, 0x62], "a�b"],
+    ["0xFF", [0x61, 0xff, 0x62], "a�b"],
+    ["0xFE 0xFF", [0xfe, 0xff], "��"],
+    ["lone continuation byte", [0x61, 0x80, 0x62], "a�b"],
+    ["truncated at the end", [0x61, 0xe2, 0x82], "a��"],
+    ["lead byte before a whole sequence", [0x61, 0xc3, 0xc3, 0xa9, 0x62], "a�éb"],
+    ["valid emoji", [0x61, 0xf0, 0x9f, 0x98, 0x80, 0x62], "a\u{1f600}b"],
+    ["control characters", [0x61, 0x01, 0x1f, 0x62], "a\u0001\u001fb"],
+];
+
+test("invalid UTF-8 reads as ffprobe replaces it; names that do not decode are not carriers", async () => {
+    for (const [name, bytes, expected] of FFPROBE_REPLACEMENTS) {
+        assert.deepEqual((await read(v.perKeyMp4({ prompt: bytes }))).tags, { prompt: expected }, name);
+        assert.deepEqual((await read(v.perKeyMkv({ PROMPT: bytes }))).tags, { PROMPT: expected }, `${name} (Matroska)`);
+    }
+    // A long value with one bad byte keeps every other byte.
+    const long = Buffer.concat([Buffer.from('{"a":"'), Buffer.alloc(100000, 0x78), Buffer.from([0xe9]), Buffer.from('"}')]);
+    assert.equal((await read(v.perKeyMp4({ workflow: long }))).tags.workflow, `{"a":"${"x".repeat(100000)}�"}`);
+    assert.deepEqual((await read(v.perKeyMp4({ prompt: [0x7b, 0xff, 0xfe, 0x7d] }))).tags, { prompt: "{��}" });
+    // A keys name with a bad byte is reported as "prom�pt", which is no carrier.
+    const badKey = v.mp4(v.udta(v.meta(v.hdlr("mdta"), v.keys([Uint8Array.from([0x70, 0x72, 0x6f, 0x6d, 0xff, 0x70, 0x74]), "prompt"]), v.ilst(v.item(1, v.data("junk")), v.item(2, v.data(GRAPH))))));
+    assert.deepEqual(await read(badKey), complete({ prompt: GRAPH }, { container: "iso-bmff", format: "isom" }));
+    const onlyBadKey = v.mp4(v.udta(v.meta(v.hdlr("mdta"), v.keys([Uint8Array.from([0xc3, 0x28])]), v.ilst(v.item(1, v.data(GRAPH))))));
+    assert.deepEqual((await read(onlyBadKey)).tags, {});
+    assert.deepEqual((await read(v.mkv([v.tagsEl(v.tag([v.simpleTag([0xff], GRAPH), v.simpleTag("WORKFLOW", WORKFLOW)]))]))).tags, { WORKFLOW: WORKFLOW });
+    assert.deepEqual((await read(v.mkv([v.tagsEl(v.tag([v.simpleTag("PROMPT", [0xff, 0xfe])]))]))).tags, { PROMPT: "��" });
+});
+
+test("ilst items with index 0 or past the keys are skipped; the first keys box wins", async () => {
+    const wf = '{"nodes":[]}';
+    const stray = v.mp4(v.udta(v.meta(v.hdlr("mdta"), v.keys(["prompt", "workflow"]), v.ilst(v.item(1, v.data(GRAPH)), v.item(5, v.data("junk")), v.item(2, v.data(wf))))));
+    assert.deepEqual((await read(stray)).tags, { prompt: GRAPH, workflow: wf });
+    const zero = v.mp4(v.udta(v.meta(v.hdlr("mdta"), v.keys(["prompt", "workflow"]), v.ilst(v.item(0, v.data("junk")), v.item(1, v.data(GRAPH)), v.item(2, v.data(wf))))));
+    assert.deepEqual((await read(zero)).tags, { prompt: GRAPH, workflow: wf });
+    assert.deepEqual((await read(v.mp4(v.udta(v.meta(v.hdlr("mdta"), v.keys(["prompt"]), v.ilst(v.item(2, v.data(GRAPH)))))))).tags, {});
+    // ffmpeg reads one keys box: a second one (even malformed) addresses nothing.
+    const twoKeys = v.mp4(v.udta(v.meta(v.hdlr("mdta"), v.keys(["prompt"]), v.keys(["workflow"]), v.ilst(v.item(1, v.data(GRAPH))))));
+    assert.deepEqual((await read(twoKeys)).tags, { prompt: GRAPH });
+    const brokenSecond = v.mp4(v.udta(v.meta(v.hdlr("mdta"), v.keys(["prompt"]), v.keys(["workflow"], { count: 9 }), v.ilst(v.item(1, v.data(GRAPH))))));
+    assert.deepEqual((await read(brokenSecond)).tags, { prompt: GRAPH });
+    const emptyFirst = v.mp4(v.udta(v.meta(v.hdlr("mdta"), v.keys([]), v.keys(["prompt"]), v.ilst(v.item(1, v.data(GRAPH))))));
+    assert.deepEqual((await read(emptyFirst)).tags, {});
+    // A keys box too short for its count field is not read, so the next one is.
+    const shortFirst = v.mp4(v.udta(v.meta(v.hdlr("mdta"), v.fullBox("keys"), v.keys(["prompt"]), v.ilst(v.item(1, v.data(GRAPH))))));
+    assert.deepEqual((await read(shortFirst)).tags, { prompt: GRAPH });
+});
+
+test("one tag per ASCII-folded name and Mac Roman text, as ffmpeg's tag dictionary holds them", async () => {
+    const mdta = (names, items, legacy = []) => v.mp4(v.udta(v.meta(v.hdlr("mdta"), v.keys(names), v.ilst(...items.map(([index, value, type = 1]) => v.item(index, v.data(value, { type }))), ...legacy))));
+    // ISO-BMFF joins case variants with ";" under the spelling set last (checked through ffprobe).
+    assert.deepEqual((await read(mdta(["workflow", "Workflow"], [[1, "A"], [2, "B"]]))).tags, { Workflow: "A;B" });
+    // A legacy comment atom and a later mdta COMMENT key become one COMMENT tag: no exact-case envelope.
+    const merged = await read(mdta(["COMMENT"], [[1, "y"]], [v.legacyItem("©cmt", v.data("x"))]));
+    assert.deepEqual(merged.tags, { comment: "y;x" });
+    const mergedUpper = await read(v.mp4(v.udta(v.meta(v.hdlr("mdta"), v.keys(["COMMENT"]), v.ilst(v.legacyItem("©cmt", v.data("x")), v.item(1, v.data("y")))))));
+    assert.deepEqual(mergedUpper.tags, { COMMENT: "x;y" });
+    assert.deepEqual(selectVideoCarrier(mergedUpper.tags).records, {});
+    // Matroska keeps the last spelling and value; a string-less SimpleTag deletes any spelling.
+    assert.deepEqual((await read(v.mkv([v.tagsEl(v.tag([v.simpleTag("PROMPT", GRAPH), v.simpleTag("Prompt", "B")]))]))).tags, { Prompt: "B" });
+    assert.deepEqual((await read(v.mkv([v.tagsEl(v.tag([v.simpleTag("PROMPT", GRAPH), v.simpleTag("Prompt", undefined)]))]))).tags, {});
+    // ffprobe's format_tags filter folds ASCII only: a Kelvin-sign "workflow" is never reported.
+    assert.deepEqual((await read(mdta(["prompt", "worKflow"], [[1, GRAPH], [2, WORKFLOW]]))).tags, { prompt: GRAPH });
+    // data types 0 and 3 are Mac Roman to ffmpeg (types 1 and 4 UTF-8, type 2 not text).
+    const cafe = [0x63, 0x61, 0x66, 0x8e];
+    for (const [type, expected] of [[0, "café"], [3, "café"], [1, "caf�"], [4, "caf�"]]) {
+        assert.deepEqual((await read(mdta(["prompt"], [[1, cafe, type]]))).tags, { prompt: expected }, `type ${type}`);
+    }
+    assert.deepEqual((await read(mdta(["prompt"], [[1, cafe, 2]]))).tags, {});
+    const high = Uint8Array.from({ length: 128 }, (_, index) => 0x80 + index);
+    const roomy = Buffer.concat([high, Buffer.alloc(400, 0x7c)]);
+    assert.equal((await read(mdta(["prompt"], [[1, roomy, 0]]))).tags.prompt, new TextDecoder("macintosh").decode(roomy));
+    // ffmpeg writes the UTF-8 into twice the input size: a long non-ASCII value is cut,
+    // here inside U+00DA, which ffprobe then replaces (its own output for these bytes).
+    const tight = Buffer.concat([high, Buffer.from([0x7c, 0x01, 0x7f])]);
+    assert.equal((await read(mdta(["prompt"], [[1, tight, 0]]))).tags.prompt, new TextDecoder("macintosh").decode(high).slice(0, 114) + "�");
+});
+
+test("budgets: roles share 2 MiB, an oversized workflow is left unread, duplicates and the total are bounded", async () => {
+    const limited = { status: "limited", reason: "metadata-limit" };
+    // Role tags over 2 MiB together stop the read (the server fails the whole read).
+    assert.deepEqual(await read(v.perKeyMp4({ prompt: fill(0x41, ROLE_BUDGET + 1) })), limited);
+    assert.deepEqual(await read(v.perKeyMkv({ PROMPT: fill(0x41, ROLE_BUDGET - 10), PARAMETERS: fill(0x42, 11) })), limited);
+    const atRole = await read(v.perKeyMp4({ prompt: fill(0x41, ROLE_BUDGET - 10), comfyassets_prompt_pairs: fill(0x42, 10) }));
+    assert.equal(atRole.status, "complete");
+    assert.equal(atRole.tags.prompt.length, ROLE_BUDGET - 10);
+    // A per-key workflow over 4 MiB is not sliced; the result says the workflow is limited.
+    const big = v.recordingBlob(v.perKeyMp4({ prompt: GRAPH, workflow: fill(0x7b, WORKFLOW_BUDGET + 1) }));
+    const over = await readVideoTags(big);
+    // It stays in the tag map as a marker, so the carrier choice still sees a per-key workflow.
+    assert.deepEqual(over, { status: "complete", container: "iso-bmff", format: "isom", tags: { prompt: GRAPH, workflow: m.OVERSIZED_WORKFLOW }, limited: ["workflow"] });
+    assert.ok(big.ranges.every(([start, end]) => end - start < WORKFLOW_BUDGET), "the oversized workflow was never sliced");
+    const bigMkv = await read(v.perKeyMkv({ WORKFLOW: fill(0x7b, WORKFLOW_BUDGET + 1), PROMPT: GRAPH }));
+    assert.deepEqual([bigMkv.limited, Object.keys(bigMkv.tags)], [["workflow"], ["WORKFLOW", "PROMPT"]]);
+    const atWorkflow = await read(v.perKeyMp4({ workflow: fill(0x7b, WORKFLOW_BUDGET) }));
+    assert.deepEqual([atWorkflow.limited, atWorkflow.tags.workflow.length], [[], WORKFLOW_BUDGET]);
+    // Fold-duplicates draw from the duplicate budgets (2x each class), then stop.
+    // (ffmpeg keeps one tag per ASCII-folded name: Matroska keeps the last spelling and value.)
+    const twice = await read(v.perKeyMkv({ PROMPT: fill(0x41, ROLE_BUDGET), prompt: fill(0x42, ROLE_BUDGET) }));
+    assert.deepEqual(Object.keys(twice.tags), ["prompt"]);
+    assert.equal(twice.tags.prompt[0], "B");
+    const thrice = await read(v.perKeyMkv({ PROMPT: fill(0x41, ROLE_BUDGET), prompt: fill(0x41, ROLE_BUDGET), Prompt: fill(0x41, ROLE_BUDGET + 1) }));
+    assert.deepEqual(thrice, limited);
+    const workflowTwice = await read(v.perKeyMkv({ WORKFLOW: fill(0x7b, WORKFLOW_BUDGET), workflow: fill(0x7b, WORKFLOW_BUDGET) }));
+    assert.equal(workflowTwice.status, "complete");
+    // Envelopes count against the total only; the total is the server's probe bound.
+    const envelope = await read(v.mp4(v.legacyUdta({ comment: fill(0x41, 5 * MiB) })));
+    assert.equal(envelope.tags.comment.length, 5 * MiB);
+    const tooMuch = await read(v.mp4(v.legacyUdta({ comment: fill(0x41, TAG_READ_BYTES - 10), description: fill(0x42, 11) })));
+    assert.deepEqual(tooMuch, limited);
+    assert.equal(m.VIDEO_TAG_READ_BYTES, TAG_READ_BYTES);
+});
+
+test("an oversized per-key workflow keeps its place in the carrier choice, as in the server's first probe", async () => {
+    const big = fill(0x7b, WORKFLOW_BUDGET + 1);
+    const envelope = '{"workflow": {"nodes": [1]}}';
+    const beside = (comment) => v.mp4(v.udta(v.meta(v.hdlr("mdta"), v.keys(["workflow"]), v.ilst(v.item(1, v.data(big)), v.legacyItem("©cmt", v.data(comment))))));
+    const read1 = await read(beside(envelope));
+    assert.deepEqual([read1.tags, read1.limited], [{ workflow: m.OVERSIZED_WORKFLOW, comment: envelope }, ["workflow"]]);
+    // The server picks the per-key carrier (no role on either side) and marks the workflow limited.
+    assert.deepEqual(selectVideoCarrier(read1.tags, { limited: read1.limited }), { status: "complete", records: {}, record_formats: { workflow: "limited" }, carrierText: null, limited: ["workflow"] });
+    // A role envelope still wins and clears it.
+    const roleEnvelope = '{"prompt": "{}", "workflow": {"a": 1}}';
+    const read2 = await read(beside(roleEnvelope));
+    assert.deepEqual(selectVideoCarrier(read2.tags, { limited: read2.limited }), { status: "complete", records: { prompt: "{}", workflow: '{"a": 1}' }, record_formats: { prompt: "original-text", workflow: "reserialized-json" }, carrierText: roleEnvelope, limited: [] });
+    // ISO-BMFF joins a repeat onto the oversized value, which stays over budget and unread.
+    const repeat = (extra) => v.mp4(v.udta(v.meta(v.hdlr("mdta"), v.keys(["workflow", "prompt"]), v.ilst(v.item(1, v.data(big)), v.item(1, v.data(extra)), v.item(2, v.data(GRAPH))))));
+    const repeatedBlob = v.recordingBlob(repeat(WORKFLOW));
+    const repeated = await readVideoTags(repeatedBlob);
+    assert.deepEqual([repeated.tags, repeated.limited], [{ workflow: m.OVERSIZED_WORKFLOW, prompt: GRAPH }, ["workflow"]]);
+    assert.ok(repeatedBlob.ranges.every(([start, end]) => end - start < 1024), "neither workflow part was sliced");
+    // When the first probe would overflow its bound, the server re-probes without the
+    // per-key workflow: then it takes no part in the choice ...
+    const dropped = await read(repeat(fill(0x41, TAG_READ_BYTES - WORKFLOW_BUDGET)));
+    assert.deepEqual([dropped.tags, dropped.limited], [{ prompt: GRAPH }, ["workflow"]]);
+    // ... and the re-probe's own bound (twice the role budget plus 64 KiB) applies to the rest.
+    const wide = '{"workflow": {"n": "' + "x".repeat(TAG_READ_BYTES - WORKFLOW_BUDGET) + '"}}';
+    assert.deepEqual(await read(beside(wide)), { status: "limited", reason: "metadata-limit" });
+    assert.equal(m.VIDEO_REPROBE_BYTES, 2 * ROLE_BUDGET + 64 * 1024);
+    // Matroska keeps the last value of a name, and a string-less SimpleTag deletes it.
+    const replaced = await read(v.mkv([v.tagsEl(v.tag([v.simpleTag("WORKFLOW", big), v.simpleTag("WORKFLOW", WORKFLOW)]))]));
+    assert.deepEqual([replaced.tags, replaced.limited], [{ WORKFLOW: WORKFLOW }, []]);
+    const deleted = await read(v.mkv([v.tagsEl(v.tag([v.simpleTag("WORKFLOW", big), v.simpleTag("WORKFLOW", undefined), v.simpleTag("PROMPT", GRAPH)]))]));
+    assert.deepEqual([deleted.tags, deleted.limited], [{ PROMPT: GRAPH }, []]);
+});
+
+test("avi and asf are recognised but not read", async () => {
+    const avi = v.concat(v.latin1("RIFF"), v.u32(1000), v.latin1("AVI LIST"), new Uint8Array(16));
+    const asf = v.concat([0x30, 0x26, 0xb2, 0x75, 0x8e, 0x66, 0xcf, 0x11, 0xa6, 0xd9, 0x00, 0xaa, 0x00, 0x62, 0xce, 0x6c], new Uint8Array(16));
+    for (const bytes of [avi, asf]) {
+        const blob = v.recordingBlob(v.concat(bytes, new Uint8Array(4096)));
+        assert.deepEqual(await readVideoTags(blob, { prefix: bytes }), { status: "unsupported", reason: "video-container-unsupported" });
+        assert.deepEqual(blob.ranges, []);
+    }
+    // The classifier's kind can be handed in instead of a prefix.
+    const blob = v.recordingBlob(new Uint8Array(64));
+    assert.deepEqual(await readVideoTags(blob, { kind: "avi" }), { status: "unsupported", reason: "video-container-unsupported" });
+    assert.deepEqual(blob.ranges, []);
+    // Without a prefix the reader slices the first 32 bytes itself.
+    const mp4 = v.recordingBlob(v.perKeyMp4({ prompt: GRAPH }));
+    assert.deepEqual((await readVideoTags(mp4)).tags, { prompt: GRAPH });
+    assert.deepEqual(mp4.ranges[0], [0, 32]);
+});
+
+test("abort during a moov walk settles once", async () => {
+    const unhandled = [];
+    const onUnhandled = (reason) => unhandled.push(reason);
+    process.on("unhandledRejection", onUnhandled);
+    try {
+        const bytes = v.concat(v.ftyp(), ...Array.from({ length: 50 }, () => v.free()), v.mdat(), v.moov(v.mdtaUdta({ prompt: GRAPH, workflow: WORKFLOW })));
+        const controller = new AbortController();
+        let slices = 0;
+        const blob = {
+            size: bytes.length,
+            slice(start, end) {
+                slices += 1;
+                if (slices === 3) controller.abort();
+                return { arrayBuffer: () => new Promise((resolve) => setTimeout(() => resolve(bytes.slice(start, end).buffer), 2)) };
+            },
+        };
+        await assert.rejects(readVideoTags(blob, { signal: controller.signal }), { name: "AbortError" });
+        const already = new AbortController();
+        already.abort();
+        await assert.rejects(readVideoTags(v.blobOf(bytes), { signal: already.signal }), { name: "AbortError" });
+        const slow = v.slowBlob(bytes, 1);
+        const during = new AbortController();
+        const pending = readVideoTags(slow, { signal: during.signal, yieldControl: async () => during.abort() });
+        await assert.rejects(pending, { name: "AbortError" });
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        assert.deepEqual(unhandled, []);
+    } finally {
+        process.off("unhandledRejection", onUnhandled);
+    }
+});
+
+test("yieldControl is awaited while walking many boxes", async () => {
+    let yields = 0;
+    const many = v.concat(v.ftyp(), ...Array.from({ length: 3000 }, () => v.free()), v.mdat(), v.moov(v.mdtaUdta({ prompt: GRAPH })));
+    const result = await readVideoTags(v.slowBlob(many, 0), { yieldControl: async () => { yields += 1; } });
+    assert.equal(result.status, "complete");
+    assert.ok(yields > 0, "the reader handed control back");
+});
+
+test("carrier selection: per-key tags, then the comment envelope, then description, never merged", () => {
+    const ENVELOPE_WORKFLOW = '{"last_node_id": 9, "nodes": [{"id": 3, "type": "KSampler", "widgets_values": [7, "fixed", 20, 8.0, "euler", "normal", 1.0]}, {"id": 6, "type": "CLIPTextEncode", "widgets_values": ["a red fox in snow, detailed fur"]}, {"id": 7, "type": "CLIPTextEncode", "widgets_values": ["blurry, lowres"]}], "links": [], "version": 0.4}';
+    const original = (keys) => Object.fromEntries(keys.map((key) => [key, "original-text"]));
+    const text = (tags, keys) => Object.fromEntries(keys.map((key) => [key, tags[key] ?? tags[key.toUpperCase()]]));
+    // The recorded fixtures.
+    for (const name of ["core-faststart.mp4", "core-moov-end.mp4", "core.mov", "core.m4v", "core.mkv", "core-tags.webm"]) {
+        const tags = RECORDED[name];
+        const keys = Object.keys(tags).map((key) => key.toLowerCase()).filter((key) => PER_KEY.has(key));
+        assert.deepEqual(selectVideoCarrier(tags), { status: "complete", records: text(tags, keys), record_formats: original(keys), carrierText: null, limited: [] }, name);
+    }
+    const legacy = RECORDED["legacy-comment.mp4"];
+    const comment = pythonJsonLoads(legacy.comment);
+    assert.deepEqual(selectVideoCarrier(legacy), {
+        status: "complete",
+        records: { prompt: comment.get("prompt"), workflow: ENVELOPE_WORKFLOW },
+        record_formats: { prompt: "original-text", workflow: "reserialized-json" },
+        carrierText: legacy.comment,
+        limited: [],
+    });
+    assert.ok(comment.get("prompt").startsWith('{"3":{"class_type":"KSampler"'));
+    // Matroska upper-cases COMMENT, and envelope names are exact-case (ruling M1): nothing is read.
+    assert.deepEqual(selectVideoCarrier(RECORDED["legacy-comment.webm"]), { status: "complete", records: {}, record_formats: {}, carrierText: null, limited: [] });
+    // Synthetic maps.
+    const envelope = JSON.stringify({ prompt: '{"9":{}}', workflow: { v: 1 } });
+    const cases = [
+        ["per-key wins over comment", { prompt: GRAPH, workflow: WORKFLOW, comment: envelope }, { records: { prompt: GRAPH, workflow: WORKFLOW }, record_formats: original(["prompt", "workflow"]), carrierText: null }],
+        ["Matroska names fold", { PROMPT: GRAPH, Workflow: WORKFLOW, ENCODER: "Lavf" }, { records: { prompt: GRAPH, workflow: WORKFLOW }, record_formats: original(["prompt", "workflow"]), carrierText: null }],
+        ["identical fold-duplicates are one record", { PROMPT: GRAPH, prompt: GRAPH }, { records: { prompt: GRAPH }, record_formats: original(["prompt"]), carrierText: null }],
+        ["differing fold-duplicates fail", { PROMPT: GRAPH, prompt: '{"9":{}}' }, { status: "unreadable", reason: "duplicate-metadata" }],
+        ["differing workflow duplicates fail even with a prompt", { Workflow: WORKFLOW, WORKFLOW: "{}", prompt: GRAPH }, { status: "unreadable", reason: "duplicate-metadata" }],
+        ["envelope names never fold", { comment: envelope, COMMENT: "a free-text note" }, { records: { prompt: '{"9":{}}', workflow: '{"v": 1}' }, record_formats: { prompt: "original-text", workflow: "reserialized-json" }, carrierText: envelope }],
+        ["non-JSON comment falls through to description", { comment: "not json", description: envelope }, { records: { prompt: '{"9":{}}', workflow: '{"v": 1}' }, record_formats: { prompt: "original-text", workflow: "reserialized-json" }, carrierText: envelope }],
+        ["a JSON array comment is not an envelope", { comment: '["prompt"]', description: '{"workflow": {}}' }, { records: { workflow: "{}" }, record_formats: { workflow: "reserialized-json" }, carrierText: '{"workflow": {}}' }],
+        ["a role envelope beats a workflow-only per-key carrier", { workflow: WORKFLOW, comment: envelope }, { records: { prompt: '{"9":{}}', workflow: '{"v": 1}' }, record_formats: { prompt: "original-text", workflow: "reserialized-json" }, carrierText: envelope }],
+        ["role description beats workflow-only comment", { comment: '{"workflow": {"a": 1}}', description: '{"parameters": "cat"}' }, { records: { parameters: "cat" }, record_formats: { parameters: "original-text" }, carrierText: '{"parameters": "cat"}' }],
+        ["workflow-only carriers: the first wins, never merged", { comment: '{"workflow": {"a": 1}}', description: '{"workflow": {"b": 2}}' }, { records: { workflow: '{"a": 1}' }, record_formats: { workflow: "reserialized-json" }, carrierText: '{"workflow": {"a": 1}}' }],
+        ["description only", { description: envelope }, { records: { prompt: '{"9":{}}', workflow: '{"v": 1}' }, record_formats: { prompt: "original-text", workflow: "reserialized-json" }, carrierText: envelope }],
+        ["no known key", { encoder: "Lavf", major_brand: "isom" }, { records: {}, record_formats: {}, carrierText: null }],
+        ["envelope with only unknown keys is no carrier", { comment: '{"title": "x"}' }, { records: {}, record_formats: {}, carrierText: null }],
+        ["null role marker is refused", { comment: '{"prompt": null, "workflow": {}}' }, { status: "unreadable", reason: "invalid-metadata" }],
+        ["numeric role is refused", { description: '{"parameters": 5}' }, { status: "unreadable", reason: "invalid-metadata" }],
+        ["a non-text non-object workflow is invalid but the roles stay", { comment: '{"prompt": "{}", "workflow": null}' }, { records: { prompt: "{}" }, record_formats: { prompt: "original-text", workflow: "invalid" }, carrierText: '{"prompt": "{}", "workflow": null}' }],
+        ["an object prompt is reserialized", { comment: '{"prompt": {"1": {"class_type": "A"}}}' }, { records: { prompt: '{"1": {"class_type": "A"}}' }, record_formats: { prompt: "reserialized-json" }, carrierText: '{"prompt": {"1": {"class_type": "A"}}}' }],
+        ["a non-text per-key role marker is refused", { prompt: 5, workflow: WORKFLOW }, { status: "unreadable", reason: "invalid-metadata" }],
+        ["a non-text per-key workflow is invalid", { prompt: GRAPH, workflow: 5 }, { records: { prompt: GRAPH }, record_formats: { prompt: "original-text", workflow: "invalid" }, carrierText: null }],
+        ["a workflow-only envelope with an invalid workflow is still the carrier", { comment: '{"workflow": 5}' }, { records: {}, record_formats: { workflow: "invalid" }, carrierText: '{"workflow": 5}' }],
+        ["not a map", null, { records: {}, record_formats: {}, carrierText: null }],
+    ];
+    for (const [name, tags, expected] of cases) {
+        const want = expected.status ? expected : { status: "complete", limited: [], ...expected };
+        assert.deepEqual(selectVideoCarrier(tags), want, name);
+    }
+    // The server's budget loop: a 4 MiB workflow is limited, roles over 2 MiB fail, exact sizes pass.
+    const bigWorkflow = "{" + "0".repeat(WORKFLOW_BUDGET);
+    assert.deepEqual(selectVideoCarrier({ prompt: GRAPH, workflow: bigWorkflow }), { status: "complete", records: { prompt: GRAPH }, record_formats: { prompt: "original-text", workflow: "limited" }, carrierText: null, limited: ["workflow"] });
+    assert.deepEqual(selectVideoCarrier({ workflow: bigWorkflow.slice(1) }).records, { workflow: bigWorkflow.slice(1) });
+    assert.deepEqual(selectVideoCarrier({ comment: JSON.stringify({ prompt: "x", workflow: { k: "0".repeat(WORKFLOW_BUDGET) } }) }).record_formats, { prompt: "original-text", workflow: "limited" });
+    assert.deepEqual(selectVideoCarrier({ prompt: "a".repeat(ROLE_BUDGET), parameters: "b" }), { status: "limited", reason: "metadata-limit" });
+    assert.deepEqual(selectVideoCarrier({ prompt: "é".repeat(ROLE_BUDGET / 2) }).records.prompt.length, ROLE_BUDGET / 2);
+    assert.deepEqual(selectVideoCarrier({ prompt: "é".repeat(ROLE_BUDGET / 2) + "a" }), { status: "limited", reason: "metadata-limit" });
+    assert.deepEqual(selectVideoCarrier({ prompt: "\ud800".repeat(ROLE_BUDGET / 3) + "aaa" }), { status: "limited", reason: "metadata-limit" });
+    assert.deepEqual(selectVideoCarrier({ prompt: "\u{1f600}".repeat(ROLE_BUDGET / 4) }).records.prompt.length, ROLE_BUDGET / 2);
+    assert.deepEqual(selectVideoCarrier({ prompt: "\u{1f600}".repeat(ROLE_BUDGET / 4) + "a" }), { status: "limited", reason: "metadata-limit" });
+    // The reader's limited workflow (the server's role-only re-probe): kept with the per-key
+    // carrier or no carrier, cleared when an envelope wins.
+    assert.deepEqual(selectVideoCarrier({ prompt: GRAPH }, { limited: ["workflow"] }).record_formats, { prompt: "original-text", workflow: "limited" });
+    assert.deepEqual(selectVideoCarrier({ encoder: "x" }, { limited: ["workflow"] }), { status: "complete", records: {}, record_formats: { workflow: "limited" }, carrierText: null, limited: ["workflow"] });
+    assert.deepEqual(selectVideoCarrier({ comment: envelope }, { limited: ["workflow"] }).limited, []);
+    assert.deepEqual(selectVideoCarrier({ comment: envelope }, { limited: ["workflow"] }).record_formats, { prompt: "original-text", workflow: "reserialized-json" });
+});
+
+test("pythonJsonLoads and pythonJsonDumps spell values as Python's json module does", () => {
+    const rows = [
+        ["1.0", "1.0"], ["8.0", "8.0"], ["0.1", "0.1"], ["1e16", "1e+16"], ["1e15", "1000000000000000.0"],
+        ["123456789012345678", "123456789012345678"], ["0.0001", "0.0001"], ["0.00001", "1e-05"], ["1e-7", "1e-07"],
+        ["1.5e300", "1.5e+300"], ["1e400", "Infinity"], ["-0", "0"], ["-0.0", "-0.0"], ["1E2", "100.0"], ["2.5", "2.5"],
+        ["100.0", "100.0"], ["1e21", "1e+21"], ["123456.789", "123456.789"], ["0.000123", "0.000123"], ["-1e-05", "-1e-05"],
+        ["9007199254740993", "9007199254740993"], ["1.7976931348623157e308", "1.7976931348623157e+308"], ["5e-324", "5e-324"],
+        ["NaN", "NaN"], ["-Infinity", "-Infinity"], ["Infinity", "Infinity"], ["[1.0e+2]", "[100.0]"], ["-1e400", "-Infinity"],
+        ["[]", "[]"], ["{}", "{}"], ["[true, false, null]", "[true, false, null]"], ['{"k":[1,{"z":1}]}', '{"k": [1, {"z": 1}]}'],
+        [' \t\n\r{"a" : 1 } ', '{"a": 1}'],
+        ['{"a":"é\\u0001\u007f\\"\\\\\\n\\t\\b\\f\\r\\/ 😀 \\ud800"}', '{"a": "\\u00e9\\u0001\\u007f\\"\\\\\\n\\t\\b\\f\\r/ \\ud83d\\ude00 \\ud800"}'],
+        ['{"a":"\\ud83d\\ude00"}', '{"a": "\\ud83d\\ude00"}'],
+        ['{"10":1,"3":2,"b":3,"a":4}', '{"10": 1, "3": 2, "b": 3, "a": 4}'],
+        ['{"a":1,"b":2,"a":3}', '{"a": 3, "b": 2}'],
+    ];
+    for (const [input, output] of rows) {
+        assert.equal(pythonJsonDumps(pythonJsonLoads(input)), output, input);
+    }
+    const bad = ['{"a":1} x', '{"a":"\u0001"}', '{"a":"\\x"}', "01", "1.", ".5", "+1", "[1,]", '{"a":1,}', "{a:1}", "'a'", "", "   ", "[", "nul", "-", "1e", '"\\u12"', "[1 2]", "tru", "Infinit"];
+    for (const input of bad) {
+        assert.throws(() => pythonJsonLoads(input), { name: "PythonJsonError" }, JSON.stringify(input));
+    }
+    assert.throws(() => pythonJsonLoads("[".repeat(2000) + "]".repeat(2000)), { name: "PythonJsonError", recursion: true });
+    // CPython's int() refuses more than 4300 digits (sign excluded); floats have no such limit.
+    const digits = (count) => "1" + "0".repeat(count - 1);
+    assert.equal(pythonJsonDumps(pythonJsonLoads(digits(4300))), digits(4300));
+    assert.equal(pythonJsonDumps(pythonJsonLoads("-" + digits(4300))), "-" + digits(4300));
+    for (const input of [digits(4301), "-" + digits(4301), `[${digits(5000)}]`]) {
+        assert.throws(() => pythonJsonLoads(input), (error) => error.name === "PythonJsonError" && error.recursion === false, input.slice(0, 8));
+    }
+    assert.equal(pythonJsonLoads(digits(4301) + ".0").isFloat, true);
+    // So an envelope holding such an integer is skipped, as the server's _carriers does.
+    const hugeInt = `{"workflow": {"a": ${digits(4400)}}}`;
+    assert.deepEqual(selectVideoCarrier({ comment: hugeInt, description: '{"workflow": {"b": 2}}' }).carrierText, '{"workflow": {"b": 2}}');
+    assert.throws(() => pythonJsonDumps(undefined), { name: "PythonJsonError" });
+    assert.throws(() => pythonJsonLoads(5), { name: "PythonJsonError" });
+    assert.equal(pythonJsonDumps(pythonJsonLoads("[".repeat(500) + "]".repeat(500))), "[".repeat(500) + "]".repeat(500));
+    const parsed = pythonJsonLoads('{"s":"x","n":1,"f":1.5,"b":true,"z":null,"l":[1]}');
+    assert.ok(parsed instanceof Map);
+    assert.deepEqual([...parsed.keys()], ["s", "n", "f", "b", "z", "l"]);
+    assert.equal(parsed.get("s"), "x");
+    assert.equal(parsed.get("b"), true);
+    assert.equal(parsed.get("z"), null);
+    assert.ok(Array.isArray(parsed.get("l")));
+});

tests/js/workspace-toolbar.test.js

@@ -765,6 +765,20 @@ test('the Filters button shows the active refinement count', async () => {
         assert.equal(filtersButton.textContent, 'Filters');
         for (const bad of [-1, 1.5, '1', null, Number.NaN]) assert.throws(() => toolbar.setActiveFilters(bad), TypeError);
         assert.equal(filtersButton.textContent, 'Filters');
+        // An unchanged count leaves the label's text node alone: every listing reload reports the count, and WebKit
+        // drops a click whose mousedown hit a text node that was replaced before mouseup.
+        let writes = 0;
+        const proto = Object.getPrototypeOf(filtersButton);
+        const descriptor = Object.getOwnPropertyDescriptor(proto, 'textContent');
+        Object.defineProperty(filtersButton, 'textContent', {
+            get() { return descriptor.get.call(this); },
+            set(text) { writes += 1; descriptor.set.call(this, text); },
+            configurable: true,
+        });
+        toolbar.setActiveFilters(0);
+        assert.equal(writes, 0);
+        toolbar.setActiveFilters(3);
+        assert.deepEqual([writes, filtersButton.textContent], [1, 'Filters · 3']);
         assert.throws(() => mountToolbar(new dom.Element('div'), { scope, categories: [], sorts: [['newest', 'Recently added']],
             activeFilters: -1, onChange() {}, onFilters() {}, onSaveView() {} }), TypeError);
     } finally {

tests/js/workspace-vocabulary-state.test.js

@@ -507,10 +507,49 @@ test('category preview text states the real impact and whether it renames or con
         '“Landscapes” is used by 2 other saved prompts. Apply renames it to “Scenery”.');
 });
 
+test('accepts image_count and names images in the delete text', async () => {
+    const {createVocabularyStream, createVocabularyCommand, readTagImpact, deleteTagText} = await helpers;
+    const rows = [{...tag(1, 'mist', 2), image_count: 3}, tag(2, 'dusk', 0)];
+    const stream = createVocabularyStream({api: queued([tagPage(rows)]).api, kind: 'tags'});
+    assert.equal(await stream.loadMore(), 2);
+    assert.deepEqual(stream.state.items.map(row => row.image_count), [3, undefined]);
+    for (const bad of [{...tag(1), image_count: -1}, {...tag(1), image_count: '3'}, {...tag(1), image_count: 1.5}]) {
+        const rejected = createVocabularyStream({api: queued([tagPage([bad])]).api, kind: 'tags'});
+        await rejected.loadMore();
+        assert.ok(rejected.state.error instanceof TypeError, JSON.stringify(bad));
+        assert.deepEqual(rejected.state.items, []);
+    }
+    const withImages = {...impact, images: 2};
+    const api = {get: async () => ({success: true, library_epoch: EPOCH, impact: withImages})};
+    assert.deepEqual((await readTagImpact(api, {id: 4, name: 'mist'})).impact, withImages);
+    await assert.rejects(readTagImpact({get: async () => ({success: true, library_epoch: EPOCH, impact: {...impact, images: -2}})},
+        {id: 4, name: 'mist'}), TypeError);
+    const command = createVocabularyCommand({api: {
+        patch: async () => renameReceipt({tag: {...tag(1, 'dusk', 2), image_count: 1}, images_changed: 1}),
+        post: async () => ({success: true, library_epoch: EPOCH, deleted: true, components_changed: 0, pairs_changed: 0, images_changed: 2}),
+    }});
+    await command.renameTag({id: 1, name: 'dawn', prompt_count: 2}, 'dusk', EPOCH);
+    assert.equal(command.state.phase, 'done');
+    assert.equal(command.state.receipt.images_changed, 1);
+    command.reset();
+    await command.deleteTag({id: 1, name: 'dusk'}, EPOCH);
+    assert.equal(command.state.phase, 'done');
+    const malformed = createVocabularyCommand({api: {post: async () => ({success: true, library_epoch: EPOCH, deleted: true,
+        components_changed: 0, pairs_changed: 0, images_changed: 'two'})}});
+    await malformed.deleteTag({id: 1, name: 'dusk'}, EPOCH);
+    assert.equal(malformed.state.phase, 'unknown-outcome');
+    assert.equal(deleteTagText('mist', withImages),
+        'Deleting “mist” removes the name and its links from 3 positive prompts, 3 negative variants (1 archived), 1 other saved prompt and 2 images. The prompts, negative variants, images and history themselves are kept.');
+    assert.equal(deleteTagText('mist', {...zero, images: 1}),
+        'Deleting “mist” removes the name and its links from 1 image. The prompts, negative variants, images and history themselves are kept.');
+    assert.equal(deleteTagText('unused', {...zero, images: 0}),
+        '“unused” is not linked to any saved prompt or image. Deleting it removes only the name.');
+});
+
 test('delete text names the tag, its real links and what stays unchanged', async () => {
     const {deleteTagText} = await helpers;
     assert.equal(deleteTagText('mist', impact),
         'Deleting “mist” removes the name and its links from 3 positive prompts, 3 negative variants (1 archived) and 1 other saved prompt. The prompts, negative variants, images and history themselves are kept.');
     assert.equal(deleteTagText('unused', zero),
-        '“unused” is not linked to any saved prompt. Deleting it removes only the name.');
+        '“unused” is not linked to any saved prompt or image. Deleting it removes only the name.');
 });

tests/test_annotation_schema.py

@@ -0,0 +1,602 @@
+"""Image annotation schema group (#249): install, validation and restore safety."""
+
+import hashlib
+import re
+import sqlite3
+import tempfile
+import unittest
+from contextlib import closing
+from pathlib import Path
+from unittest.mock import patch
+
+try:
+    from tests.open_handles import assert_closed
+except ImportError:  # discovered with tests/ as the top-level directory
+    from open_handles import assert_closed
+
+from database.models import PromptModel
+
+try:  # guarded so a missing module fails assertions, not test loading
+    from database.annotation_schema import (
+        annotation_schema_error,
+        migrate_annotation_state,
+    )
+except ImportError:
+    annotation_schema_error = None
+    migrate_annotation_state = None
+
+METADATA = "media_annotation_metadata"
+FILES = "media_annotation_files"
+BYTES = "media_annotation_bytes"
+IMAGE_TAGS = "media_image_tags"
+TABLES = (METADATA, FILES, BYTES, IMAGE_TAGS)
+# The exact DDL the plan pins; the module must produce precisely these objects.
+DDL = {
+    METADATA: (
+        f"CREATE TABLE {METADATA}(singleton_id INTEGER PRIMARY KEY "
+        "CHECK(singleton_id=1), schema_version INTEGER NOT NULL "
+        "CHECK(schema_version=1), image_index_revision INTEGER NOT NULL DEFAULT 0 "
+        "CHECK(image_index_revision>=0))"
+    ),
+    FILES: (
+        f"CREATE TABLE {FILES}(id TEXT PRIMARY KEY CHECK(length(id)=36), "
+        "locator TEXT NOT NULL UNIQUE, created_at TEXT NOT NULL)"
+    ),
+    BYTES: (
+        f"CREATE TABLE {BYTES}(id TEXT PRIMARY KEY CHECK(length(id)=36), "
+        f"file_id TEXT NOT NULL REFERENCES {FILES}(id) ON DELETE CASCADE, "
+        "sha256 TEXT NOT NULL CHECK(length(sha256)=64 AND sha256 NOT GLOB "
+        "'*[^0-9a-f]*'), size INTEGER NOT NULL CHECK(size>=0), "
+        "mtime_ns INTEGER NOT NULL, verified_at TEXT NOT NULL, "
+        "first_seen_at TEXT NOT NULL, tag_revision INTEGER NOT NULL DEFAULT 0 "
+        "CHECK(tag_revision>=0), UNIQUE(file_id, sha256))"
+    ),
+    IMAGE_TAGS: (
+        f"CREATE TABLE {IMAGE_TAGS}(byte_id TEXT NOT NULL REFERENCES {BYTES}(id) "
+        "ON DELETE CASCADE, tag_id INTEGER NOT NULL REFERENCES tags(id) "
+        "ON DELETE CASCADE, position INTEGER NOT NULL CHECK(position>=0), "
+        "PRIMARY KEY(byte_id, tag_id))"
+    ),
+}
+INDEXES = {
+    "idx_media_annotation_bytes_fingerprint": (
+        f"CREATE INDEX idx_media_annotation_bytes_fingerprint ON {BYTES}"
+        "(file_id, size, mtime_ns)"
+    ),
+    "idx_media_image_tags_tag": (
+        f"CREATE INDEX idx_media_image_tags_tag ON {IMAGE_TAGS}(tag_id)"
+    ),
+    "idx_media_image_tags_position": (
+        f"CREATE UNIQUE INDEX idx_media_image_tags_position ON {IMAGE_TAGS}"
+        "(byte_id, position)"
+    ),
+}
+AUTOINDEXES = {FILES: 2, BYTES: 2, IMAGE_TAGS: 1}
+LEGACY_TABLES = (
+    "prompts",
+    "generated_images",
+    "tags",
+    "prompt_tags",
+    "prompt_pair_tags",
+    "image_favorites",
+)
+FILE_ID = "0f8e4b2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b"
+BYTE_ID = "6a1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d"
+OTHER_ID = "7b2c3d4e-5f6a-4b7c-9d0e-1f2a3b4c5d6e"
+DIGEST = hashlib.sha256(b"img").hexdigest()
+NOW = "2026-10-22T00:00:00.000000+00:00"
+MAX_LOCATOR = 4096
+
+
+def _compact(sql):
+    return re.sub(r"\s+", "", sql or "").lower()
+
+
+def expected_catalog():
+    objects = {("table", name, _compact(sql)) for name, sql in DDL.items()}
+    objects |= {("index", name, _compact(sql)) for name, sql in INDEXES.items()}
+    objects |= {
+        ("index", f"sqlite_autoindex_{table}_{n}", "")
+        for table, count in AUTOINDEXES.items()
+        for n in range(1, count + 1)
+    }
+    return objects
+
+
+def catalog(conn):
+    names = tuple(TABLES) + tuple(INDEXES)
+    marks = ",".join("?" * len(names))
+    table_marks = ",".join("?" * len(TABLES))
+    return {
+        (kind, name, _compact(sql))
+        for kind, name, sql in conn.execute(
+            "SELECT type,name,sql FROM sqlite_master "
+            f"WHERE name IN ({marks}) OR tbl_name IN ({table_marks})",  # nosec B608
+            names + tuple(TABLES),
+        )
+    }
+
+
+def insert_group_rows(conn, tag_name="img-only", locator="/out/img.png"):
+    """One file, one byte record and one image tag carrying *tag_name*."""
+    tag_id = conn.execute("INSERT INTO tags(name) VALUES(?)", (tag_name,)).lastrowid
+    conn.execute(f"INSERT INTO {FILES} VALUES(?,?,?)", (FILE_ID, locator, NOW))
+    conn.execute(
+        f"INSERT INTO {BYTES} VALUES(?,?,?,?,?,?,?,?)",
+        (BYTE_ID, FILE_ID, DIGEST, 3, 1_700_000_000_000_000_000, NOW, NOW, 1),
+    )
+    conn.execute(f"INSERT INTO {IMAGE_TAGS} VALUES(?,?,0)", (BYTE_ID, tag_id))
+    return tag_id
+
+
+def rows(conn, sql, *params):
+    """Plain tuples whatever row factory *conn* uses."""
+    return [tuple(row) for row in conn.execute(sql, params)]
+
+
+def image_tags(conn):
+    return rows(
+        conn,
+        f"SELECT t.name, it.position FROM {IMAGE_TAGS} it "
+        "JOIN tags t ON t.id = it.tag_id ORDER BY it.position",
+    )
+
+
+def metadata(conn):
+    return rows(conn, f"SELECT schema_version,image_index_revision FROM {METADATA}")
+
+
+def table_rows(conn, tables):
+    found = {}
+    for table in tables:
+        present = conn.execute(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (table,)
+        ).fetchone()
+        if present:
+            found[table] = rows(conn, f"SELECT * FROM {table}")  # nosec B608
+    return found
+
+
+def populate_legacy(conn):
+    conn.execute(
+        "INSERT INTO prompts(id,text,hash,category,notes,run_count) VALUES"
+        "(7,'positive','p','keep','notes',12)"
+    )
+    conn.execute("INSERT INTO prompts(id,text,hash) VALUES(9,'negative','n')")
+    conn.execute(
+        "INSERT INTO generated_images(id,prompt_id,image_path,filename,file_path) "
+        "VALUES(4,7,'/tmp/image.png','image.png','/tmp/image.png')"
+    )
+    conn.execute("INSERT INTO tags(id,name) VALUES(3,'keep-tag')")
+    conn.execute("INSERT INTO prompt_tags VALUES(7,3)")
+    conn.execute(
+        "INSERT INTO prompt_pairs(id,positive_prompt_id,negative_prompt_id) "
+        "VALUES(6,7,9)"
+    )
+    conn.execute("INSERT INTO prompt_pair_tags VALUES(6,3)")
+    conn.execute("INSERT INTO image_favorites VALUES('root','a.png',?)", (NOW,))
+
+
+class AnnotationSchemaTests(unittest.TestCase):
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.temp.cleanup)
+        self.addCleanup(assert_closed, self, self.temp.name)
+        self.addCleanup(PromptModel.reset_schema_cache)
+        self.models = []
+        self.addCleanup(self.close_models)
+        self.path = str(Path(self.temp.name) / "live.db")
+
+    def close_models(self):
+        for model in self.models:
+            model.close_all()
+
+    def model(self, path=None):
+        model = PromptModel(path or self.path)
+        self.models.append(model)
+        return model
+
+    def require_module(self):
+        self.assertIsNotNone(
+            annotation_schema_error, "database.annotation_schema is not implemented"
+        )
+
+    def drop_group(self, path):
+        """Remove the group from a closed database file (an old backup)."""
+        with closing(sqlite3.connect(path)) as raw, raw:
+            raw.execute("PRAGMA foreign_keys=OFF")
+            for table in reversed(TABLES):
+                raw.execute(f"DROP TABLE {table}")
+
+    def test_fresh_install_and_reopen_is_idempotent(self):
+        self.require_module()
+        model = self.model()
+        with model.get_connection() as conn:
+            self.assertEqual(catalog(conn), expected_catalog())
+            self.assertIsNone(annotation_schema_error(conn, allow_missing=False))
+            self.assertEqual(metadata(conn), [(1, 0)])
+            insert_group_rows(conn)
+        self.assertEqual(
+            PromptModel.verify_database_file(self.path, require_library_state=True),
+            (True, "ok"),
+        )
+        model.close_all()
+        for _ in range(2):
+            PromptModel.reset_schema_cache()
+            model = self.model()
+            with model.get_connection() as conn:
+                self.assertEqual(catalog(conn), expected_catalog())
+                self.assertIsNone(annotation_schema_error(conn, allow_missing=False))
+                self.assertEqual(metadata(conn), [(1, 0)])
+                self.assertEqual(image_tags(conn), [("img-only", 0)])
+                # Running the migration again on a current database changes nothing.
+                migrate_annotation_state(conn)
+                self.assertEqual(metadata(conn), [(1, 0)])
+                self.assertEqual(image_tags(conn), [("img-only", 0)])
+            model.close_all()
+        # A tag delete and a file delete cascade into the junction and bytes.
+        PromptModel.reset_schema_cache()
+        model = self.model()
+        with model.get_connection() as conn:
+            conn.execute("DELETE FROM tags WHERE name='img-only'")
+            self.assertEqual(image_tags(conn), [])
+            conn.execute(f"DELETE FROM {FILES}")
+            self.assertEqual(rows(conn, f"SELECT * FROM {BYTES}"), [])
+            self.assertIsNone(annotation_schema_error(conn, allow_missing=False))
+
+    def test_old_database_without_group_migrates_without_touching_legacy_rows(self):
+        self.require_module()
+        model = self.model()
+        with model.get_connection() as conn:
+            populate_legacy(conn)
+        model.close_all()
+        self.drop_group(self.path)
+        with closing(sqlite3.connect(self.path)) as raw:
+            self.assertIsNone(annotation_schema_error(raw))
+            self.assertEqual(
+                annotation_schema_error(raw, allow_missing=False),
+                "Missing image annotation schema",
+            )
+            legacy_rows_before = table_rows(raw, LEGACY_TABLES)
+        self.assertTrue(PromptModel.verify_database_file(self.path)[0])
+        self.assertFalse(
+            PromptModel.verify_database_file(self.path, require_library_state=True)[0]
+        )
+        PromptModel.reset_schema_cache()
+
+        model = self.model()
+
+        with model.get_connection() as conn:
+            self.assertEqual(catalog(conn), expected_catalog())
+            self.assertIsNone(annotation_schema_error(conn, allow_missing=False))
+            self.assertEqual(metadata(conn), [(1, 0)])
+            legacy_rows_after = table_rows(conn, LEGACY_TABLES)
+            # No backfill: existing prompt tags never become image tags.
+            counts = [
+                conn.execute(f"SELECT COUNT(*) FROM {table}").fetchone()[0]
+                for table in (FILES, BYTES, IMAGE_TAGS)
+            ]
+        self.assertEqual(counts, [0, 0, 0])
+        self.assertEqual(legacy_rows_after, legacy_rows_before)
+        self.assertEqual(
+            PromptModel.verify_database_file(self.path, require_library_state=True),
+            (True, "ok"),
+        )
+
+    def tampered(self, name, statements, *, checks_off=False):
+        """A closed current database whose group was altered after the fact."""
+        path = str(Path(self.temp.name) / f"{name.replace(' ', '-')}.db")
+        model = self.model(path)
+        with model.get_connection() as conn:
+            populate_legacy(conn)
+            insert_group_rows(conn)
+        model.close_all()
+        with closing(sqlite3.connect(path)) as raw, raw:
+            raw.execute("PRAGMA foreign_keys=OFF")
+            if checks_off:
+                raw.execute("PRAGMA ignore_check_constraints=ON")
+            for statement in statements:
+                if isinstance(statement, tuple):
+                    raw.execute(*statement)
+                else:
+                    raw.execute(statement)
+        return path
+
+    def assert_rejected_unrepaired(self, path):
+        with closing(sqlite3.connect(path)) as raw:
+            schema_before = raw.execute(
+                "SELECT type,name,tbl_name,sql FROM sqlite_master ORDER BY name"
+            ).fetchall()
+            rows_before = table_rows(raw, TABLES)
+            for allow_missing in (False, True):
+                error = annotation_schema_error(raw, allow_missing=allow_missing)
+                self.assertIsNotNone(error)
+                self.assertIn("image annotation", error.lower())
+        self.assertFalse(PromptModel.verify_database_file(path)[0])
+        self.assertFalse(
+            PromptModel.verify_database_file(path, require_library_state=True)[0]
+        )
+        PromptModel.reset_schema_cache()
+        with self.assertRaises(sqlite3.DatabaseError):
+            self.model(path)
+        PromptModel.reset_schema_cache()
+        with closing(sqlite3.connect(path)) as raw:
+            self.assertEqual(
+                raw.execute(
+                    "SELECT type,name,tbl_name,sql FROM sqlite_master ORDER BY name"
+                ).fetchall(),
+                schema_before,
+            )
+            self.assertEqual(table_rows(raw, TABLES), rows_before)
+
+    def test_partial_or_malformed_group_is_rejected_without_repair(self):
+        self.require_module()
+        cases = {
+            "missing metadata": (f"DROP TABLE {METADATA}",),
+            "missing files": (f"DROP TABLE {FILES}",),
+            "missing bytes": (f"DROP TABLE {BYTES}",),
+            "missing image tags": (f"DROP TABLE {IMAGE_TAGS}",),
+            "reserved view": (
+                f"DROP TABLE {FILES}",
+                f"CREATE VIEW {FILES} AS SELECT 'x' AS id",
+            ),
+            "extra trigger": (
+                f"CREATE TRIGGER media_annotation_trigger AFTER INSERT ON {FILES} "
+                "BEGIN SELECT 1; END",
+            ),
+            "extra index": (
+                f"CREATE INDEX idx_media_annotation_extra ON {FILES}(created_at)",
+            ),
+            "extra column": (
+                f"DROP TABLE {IMAGE_TAGS}",
+                DDL[IMAGE_TAGS].replace(
+                    "position INTEGER", "note TEXT, position INTEGER"
+                ),
+            ),
+            "wrong primary key": (
+                f"DROP TABLE {FILES}",
+                DDL[FILES].replace("id TEXT PRIMARY KEY", "id TEXT"),
+            ),
+            "wrong foreign key": (
+                f"DROP TABLE {BYTES}",
+                DDL[BYTES].replace("ON DELETE CASCADE", "ON DELETE RESTRICT"),
+                INDEXES["idx_media_annotation_bytes_fingerprint"],
+            ),
+            "wrong check": (
+                f"DROP TABLE {METADATA}",
+                DDL[METADATA].replace("schema_version=1", "schema_version=2"),
+                f"INSERT INTO {METADATA} VALUES(1,2,0)",
+            ),
+            "missing unique": (
+                f"DROP TABLE {FILES}",
+                DDL[FILES].replace("NOT NULL UNIQUE", "NOT NULL"),
+            ),
+            "missing index": ("DROP INDEX idx_media_image_tags_tag",),
+            "non-unique position index": (
+                "DROP INDEX idx_media_image_tags_position",
+                INDEXES["idx_media_image_tags_position"].replace("UNIQUE ", ""),
+            ),
+            "wrong index columns": (
+                "DROP INDEX idx_media_annotation_bytes_fingerprint",
+                INDEXES["idx_media_annotation_bytes_fingerprint"].replace(
+                    ", mtime_ns", ""
+                ),
+            ),
+            "orphan tag": (f"INSERT INTO {IMAGE_TAGS} VALUES('{BYTE_ID}',404,1)",),
+            "orphan byte": (
+                (
+                    f"INSERT INTO {BYTES} VALUES(?,?,?,1,1,?,?,0)",
+                    (
+                        OTHER_ID,
+                        "9" * 8 + "-0000-4000-8000-" + "0" * 12,
+                        DIGEST,
+                        NOW,
+                        NOW,
+                    ),
+                ),
+            ),
+            "bad file uuid": (
+                (f"UPDATE {FILES} SET id=?", ("x" * 36,)),
+                (f"UPDATE {BYTES} SET file_id=?", ("x" * 36,)),
+            ),
+            "uppercase byte uuid": (
+                f"UPDATE {BYTES} SET id=upper(id)",
+                f"UPDATE {IMAGE_TAGS} SET byte_id=upper(byte_id)",
+            ),
+            "null file id": ((f"INSERT INTO {FILES} VALUES(NULL,?,?)", ("/n", NOW)),),
+            "blob ids": (
+                f"UPDATE {FILES} SET id=CAST(id AS BLOB)",
+                f"UPDATE {BYTES} SET file_id=CAST(file_id AS BLOB)",
+            ),
+            "no metadata row": (f"DELETE FROM {METADATA}",),
+            "long created_at": ((f"UPDATE {FILES} SET created_at=?", ("x" * 65,)),),
+            "blob verified_at": (f"UPDATE {BYTES} SET verified_at=X'00'",),
+            "text mtime": (f"UPDATE {BYTES} SET mtime_ns='soon'",),
+            "duplicate position": (
+                "DROP INDEX idx_media_image_tags_position",
+                "INSERT INTO tags(id,name) VALUES(77,'dup')",
+                f"INSERT INTO {IMAGE_TAGS} VALUES('{BYTE_ID}',77,0)",
+            ),
+            "long locator": (
+                (f"UPDATE {FILES} SET locator=?", ("x" * (MAX_LOCATOR + 1),)),
+            ),
+            "multibyte long locator": (
+                (f"UPDATE {FILES} SET locator=?", ("é" * (MAX_LOCATOR + 1),)),
+            ),
+            "nul locator bypass": (
+                (f"UPDATE {FILES} SET locator=?", ("x\0" + "y" * MAX_LOCATOR,)),
+            ),
+        }
+        for label, statements in cases.items():
+            with self.subTest(label):
+                self.assert_rejected_unrepaired(self.tampered(label, statements))
+        unchecked = {
+            "two metadata rows": (f"INSERT INTO {METADATA} VALUES(2,1,0)",),
+            "wrong schema version": (f"UPDATE {METADATA} SET schema_version=2",),
+            "negative index revision": (
+                f"UPDATE {METADATA} SET image_index_revision=-1",
+            ),
+            "bad digest": (f"UPDATE {BYTES} SET sha256=upper(sha256)",),
+            "short digest": (f"UPDATE {BYTES} SET sha256=substr(sha256,1,63)",),
+            "negative size": (f"UPDATE {BYTES} SET size=-1",),
+            "negative tag revision": (f"UPDATE {BYTES} SET tag_revision=-1",),
+            "negative position": (f"UPDATE {IMAGE_TAGS} SET position=-1",),
+        }
+        for label, statements in unchecked.items():
+            with self.subTest(label):
+                path = self.tampered(label, statements, checks_off=True)
+                self.assert_rejected_unrepaired(path)
+        accepted = {
+            "locator at bound": ("x" * MAX_LOCATOR,),
+            "multibyte locator at bound": ("é" * MAX_LOCATOR,),
+        }
+        for label, (locator,) in accepted.items():
+            with self.subTest(label):
+                path = self.tampered(
+                    label, ((f"UPDATE {FILES} SET locator=?", (locator,)),)
+                )
+                with closing(sqlite3.connect(path)) as raw:
+                    self.assertIsNone(annotation_schema_error(raw, allow_missing=False))
+                self.assertEqual(
+                    PromptModel.verify_database_file(path, require_library_state=True),
+                    (True, "ok"),
+                )
+
+    def test_install_failure_rolls_back_and_retries(self):
+        self.require_module()
+        with patch(
+            "database.annotation_schema.annotation_schema_error",
+            side_effect=[None, "injected final validation failure"],
+        ):
+            with self.assertRaisesRegex(sqlite3.DatabaseError, "injected"):
+                self.model()
+        with closing(sqlite3.connect(self.path)) as raw:
+            self.assertEqual(catalog(raw), set())
+            self.assertIsNotNone(
+                raw.execute(
+                    "SELECT 1 FROM sqlite_master WHERE name='saved_views'"
+                ).fetchone()
+            )
+        PromptModel.reset_schema_cache()
+        model = self.model()
+        self.assertEqual(
+            PromptModel.verify_database_file(model.db_path, require_library_state=True),
+            (True, "ok"),
+        )
+        with model.get_connection() as conn:
+            self.assertEqual(metadata(conn), [(1, 0)])
+
+    def test_wal_backup_restore_round_trips_group(self):
+        self.require_module()
+        source_path = str(Path(self.temp.name) / "source.db")
+        source = self.model(source_path)
+        with source.get_connection() as conn:
+            conn.execute("PRAGMA wal_autocheckpoint=0")
+            conn.execute("INSERT INTO prompts(id,text,hash) VALUES(7,'p','p')")
+            insert_group_rows(conn)
+            conn.commit()
+            source_files = rows(conn, f"SELECT * FROM {FILES}")
+            source_bytes = rows(conn, f"SELECT * FROM {BYTES}")
+        self.assertGreater(Path(source_path + "-wal").stat().st_size, 0)
+        live = self.model()
+        with live.get_connection() as conn:
+            conn.execute("INSERT INTO prompts(id,text,hash) VALUES(1,'live','live')")
+            insert_group_rows(conn, tag_name="live-only", locator="/out/live.png")
+        source_before = Path(source_path).read_bytes()
+        self.assertEqual(
+            PromptModel.verify_database_file(source_path, require_library_state=True),
+            (True, "ok"),
+        )
+        # The rows still sit in the WAL; a backup file must carry them too.
+        backup_file = str(Path(self.temp.name) / "backup.db")
+        self.assertTrue(source.backup_database(backup_file))
+        with closing(sqlite3.connect(backup_file)) as raw:
+            self.assertEqual(image_tags(raw), [("img-only", 0)])
+            self.assertIsNone(annotation_schema_error(raw, allow_missing=False))
+
+        safety = live.restore_from_file(source_path)
+
+        self.assertTrue(Path(safety).is_file())
+        self.assertEqual(Path(source_path).read_bytes(), source_before)
+        with live.get_connection() as conn:
+            restored_image_tags = image_tags(conn)
+            self.assertEqual(rows(conn, f"SELECT * FROM {FILES}"), source_files)
+            self.assertEqual(rows(conn, f"SELECT * FROM {BYTES}"), source_bytes)
+            self.assertEqual(metadata(conn), [(1, 0)])
+            self.assertIsNone(annotation_schema_error(conn, allow_missing=False))
+            self.assertEqual(rows(conn, "SELECT id FROM prompts"), [(7,)])
+        self.assertEqual(restored_image_tags, [("img-only", 0)])
+        with closing(sqlite3.connect(safety)) as raw:
+            self.assertEqual(image_tags(raw), [("live-only", 0)])
+            self.assertEqual(raw.execute("SELECT id FROM prompts").fetchall(), [(1,)])
+        # The same rows restore from the backup file as well.
+        PromptModel.reset_schema_cache()
+        live.restore_from_file(backup_file)
+        with live.get_connection() as conn:
+            self.assertEqual(image_tags(conn), [("img-only", 0)])
+        PromptModel.close_all_instances()
+        assert_closed(self, self.temp.name)
+
+    def test_staged_failure_preserves_source_live_safety_and_handles(self):
+        self.require_module()
+        live = self.model()
+        with live.get_connection() as conn:
+            conn.execute("INSERT INTO prompts(id,text,hash) VALUES(1,'live','live')")
+            insert_group_rows(conn, tag_name="live-only")
+        # A source with a malformed group is refused before any change.
+        bad = self.tampered(
+            "restore bad",
+            (f"UPDATE {BYTES} SET sha256=upper(sha256)",),
+            checks_off=True,
+        )
+        # A staging failure while installing the group must be refused too.
+        old = str(Path(self.temp.name) / "old.db")
+        self.model(old).close_all()
+        self.drop_group(old)
+        for source, patched in ((bad, False), (old, True)):
+            with self.subTest(source=Path(source).name):
+                before = Path(source).read_bytes()
+                safety = sorted(Path(self.temp.name).glob("live.db.backup_*"))
+                if patched:
+                    context = patch(
+                        "database.models.migrate_annotation_state",
+                        side_effect=sqlite3.OperationalError("staging failed"),
+                    )
+                    expected = sqlite3.OperationalError
+                else:
+                    context = patch.object(PromptModel, "backup_database")
+                    expected = ValueError
+                with context as hook, self.assertRaises(expected):
+                    live.restore_from_file(source)
+                if not patched:
+                    hook.assert_not_called()
+                self.assertEqual(Path(source).read_bytes(), before)
+                self.assertEqual(
+                    sorted(Path(self.temp.name).glob("live.db.backup_*")), safety
+                )
+                assert_closed(self, source)
+                with live.get_connection() as conn:
+                    self.assertEqual(image_tags(conn), [("live-only", 0)])
+                    self.assertEqual(metadata(conn), [(1, 0)])
+        self.assertFalse(
+            PromptModel.verify_database_file(old, require_library_state=True)[0]
+        )
+        self.assertTrue(PromptModel.verify_database_file(old)[0])
+
+    def test_verify_requires_group_only_with_require_library_state(self):
+        self.require_module()
+        self.model().close_all()
+        self.assertEqual(
+            PromptModel.verify_database_file(self.path, require_library_state=True),
+            (True, "ok"),
+        )
+        self.drop_group(self.path)
+        self.assertEqual(PromptModel.verify_database_file(self.path), (True, "ok"))
+        self.assertEqual(
+            PromptModel.verify_database_file(self.path, require_library_state=True),
+            (False, "Missing image annotation schema"),
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_annotations.py

@@ -0,0 +1,598 @@
+"""Per-image tag sets (#249 A2): byte-exact storage in the shared vocabulary."""
+
+import hashlib
+import os
+import re
+import sqlite3
+import tempfile
+import unittest
+from unittest.mock import patch
+
+try:
+    from tests.open_handles import assert_closed
+except ImportError:  # discovered with tests/ as the top-level directory
+    from open_handles import assert_closed
+
+from database.annotation_schema import annotation_schema_error
+from database.library_commands import LibraryCommandError
+from database.operations import PromptDatabase
+from utils.hashing import generate_prompt_hash
+
+try:  # guarded so a missing module fails assertions, not test loading
+    from database import annotations as annotations_module
+    from database.annotations import (
+        MAX_IMAGE_TAGS,
+        AnnotationCommandError,
+        normalize_image_tags,
+    )
+except ImportError:
+    annotations_module = None
+    MAX_IMAGE_TAGS = None
+    AnnotationCommandError = None
+    normalize_image_tags = None
+
+UUID = re.compile(r"[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}")
+DIGEST_A = hashlib.sha256(b"bytes a").hexdigest()
+DIGEST_B = hashlib.sha256(b"bytes b").hexdigest()
+SIZE = 7
+MTIME = 1_700_000_000_123_456_789
+ANNOTATION_TABLES = (
+    "media_annotation_files",
+    "media_annotation_bytes",
+    "media_image_tags",
+    "media_annotation_metadata",
+)
+LEGACY_TABLES = (
+    "tags",
+    "prompt_tags",
+    "prompt_pair_tags",
+    "generated_images",
+    "image_prompt_pairs",
+)
+
+
+class AnnotationTestCase(unittest.TestCase):
+    def setUp(self):
+        self.assertIsNotNone(
+            annotations_module, "database.annotations is not implemented"
+        )
+        directory = tempfile.TemporaryDirectory()
+        self.addCleanup(directory.cleanup)
+        self.addCleanup(assert_closed, self, directory.name)
+        self.root = directory.name
+        self.db = PromptDatabase(os.path.join(self.root, "annotations.db"))
+        self.addCleanup(self.db.close_all)
+        self.epoch = self.db.get_execution_epoch()
+
+    def locator(self, name: str) -> str:
+        return os.path.normcase(os.path.join(os.path.realpath(self.root), name))
+
+    def replace(self, loc, digest=DIGEST_A, tags=(), *, revision=0, **over):
+        options = {
+            "locator": loc,
+            "sha256": digest,
+            "size": SIZE,
+            "mtime_ns": MTIME,
+            "expected_epoch": self.epoch,
+            "expected_tag_revision": revision,
+            "tags": list(tags) if isinstance(tags, tuple) else tags,
+        }
+        options.update(over)
+        return self.db.replace_image_tags(**options)
+
+    def add(self, loc, digest=DIGEST_A, tags=(), **over):
+        options = {
+            "locator": loc,
+            "sha256": digest,
+            "size": SIZE,
+            "mtime_ns": MTIME,
+            "expected_epoch": self.epoch,
+            "tags": list(tags) if isinstance(tags, tuple) else tags,
+        }
+        options.update(over)
+        return self.db.add_image_tags(**options)
+
+    def read(self, loc, digest=DIGEST_A):
+        return self.db.read_image_tags(loc, digest)
+
+    def rows(self, *tables):
+        """Every row of each table; ``verified_at`` is a fingerprint, not content."""
+        conn = self.db.model.get_connection()
+        result = []
+        for table in tables:
+            columns = [
+                row[1]
+                for row in conn.execute(f"PRAGMA table_info({table})")
+                if row[1] != "verified_at"
+            ]
+            result.append(
+                [
+                    tuple(row)
+                    for row in conn.execute(
+                        f"SELECT {','.join(columns)} FROM {table} ORDER BY 1,2"
+                    )
+                ]
+            )
+        return result
+
+    def counts(self):
+        conn = self.db.model.get_connection()
+        return {
+            table: conn.execute(f"SELECT COUNT(*) FROM {table}").fetchone()[0]
+            for table in ANNOTATION_TABLES
+        }
+
+    def index_revision(self):
+        return (
+            self.db.model.get_connection()
+            .execute("SELECT image_index_revision FROM media_annotation_metadata")
+            .fetchone()[0]
+        )
+
+    def schema_clean(self):
+        self.assertIsNone(
+            annotation_schema_error(self.db.model.get_connection(), allow_missing=False)
+        )
+
+
+class NormalizeImageTagsTests(unittest.TestCase):
+    def setUp(self):
+        self.assertIsNotNone(
+            normalize_image_tags, "database.annotations is not implemented"
+        )
+
+    def test_case_insensitive_dedupe_keeps_first_spelling_and_position(self):
+        self.assertEqual(
+            normalize_image_tags([" Forest ", "mist", "forest", "MIST", "Rain"]),
+            ["Forest", "mist", "Rain"],
+        )
+        self.assertEqual(normalize_image_tags([]), [])
+        self.assertEqual(MAX_IMAGE_TAGS, 100)
+
+    def test_limit_and_invalid_names_rejected(self):
+        for bad in (
+            None,
+            "forest",
+            {"a": 1},
+            [1],
+            [None],
+            ["a,b"],
+            [""],
+            ["   "],
+            ["x" * 101],
+            [f"t{i}" for i in range(MAX_IMAGE_TAGS + 1)],
+        ):
+            with self.subTest(bad=bad), self.assertRaises(ValueError):
+                normalize_image_tags(bad)
+        # Duplicates fold before the cap is applied.
+        many = [f"t{i}" for i in range(MAX_IMAGE_TAGS)]
+        self.assertEqual(normalize_image_tags(many + ["T0", "T99"]), many)
+
+
+class ReplaceImageTagsTests(AnnotationTestCase):
+    def test_first_save_creates_owner_and_byte_atomically_including_empty_set(self):
+        loc = self.locator("a.png")
+        receipt = self.replace(loc, tags=["Forest", "mist", "forest"])
+        self.assertEqual(receipt["tags"], ["Forest", "mist"])
+        self.assertEqual(receipt["tag_revision"], 1)
+        self.assertEqual(
+            receipt,
+            {
+                "library_epoch": self.epoch,
+                "sha256": DIGEST_A,
+                "tags": ["Forest", "mist"],
+                "tag_revision": 1,
+                "replayed": False,
+            },
+        )
+        conn = self.db.model.get_connection()
+        files = conn.execute("SELECT * FROM media_annotation_files").fetchall()
+        self.assertEqual(len(files), 1)
+        self.assertRegex(files[0]["id"], UUID)
+        self.assertEqual(files[0]["locator"], loc)
+        byte = conn.execute("SELECT * FROM media_annotation_bytes").fetchone()
+        self.assertRegex(byte["id"], UUID)
+        self.assertEqual(
+            (byte["file_id"], byte["sha256"], byte["size"], byte["mtime_ns"]),
+            (files[0]["id"], DIGEST_A, SIZE, MTIME),
+        )
+        self.assertEqual(byte["tag_revision"], 1)
+        self.assertEqual(byte["verified_at"], byte["first_seen_at"])
+        self.assertEqual(
+            [
+                tuple(row)
+                for row in conn.execute(
+                    "SELECT t.name, mit.position FROM media_image_tags mit "
+                    "JOIN tags t ON t.id = mit.tag_id ORDER BY mit.position"
+                )
+            ],
+            [("Forest", 0), ("mist", 1)],
+        )
+        self.assertEqual(self.index_revision(), 1)
+        # An explicit empty set is a real save: owner and byte record exist.
+        empty = self.replace(self.locator("b.png"), DIGEST_B, [])
+        self.assertEqual((empty["tags"], empty["tag_revision"]), ([], 1))
+        self.assertEqual(self.counts()["media_annotation_files"], 2)
+        self.assertEqual(self.counts()["media_annotation_bytes"], 2)
+        self.assertEqual(
+            self.db.read_image_tags(self.locator("b.png"), DIGEST_B),
+            {"tags": [], "tag_revision": 1, "prior_count": 0},
+        )
+        self.assertEqual(self.index_revision(), 2)
+        self.schema_clean()
+
+    def test_save_changes_only_target_byte_set(self):
+        a, b, c = self.locator("a.png"), self.locator("b.png"), self.locator("c.png")
+        prompt = self.db.save_prompt(
+            "Shared forest",
+            tags=["shared"],
+            prompt_hash=generate_prompt_hash("Shared forest"),
+        )
+        pair = self.db.save_prompt_pair("Shared forest", "blurry", tags=["pairtag"])
+        image_a = self.db.link_image_to_prompt(prompt, a)
+        image_b = self.db.link_image_to_prompt(prompt, b)
+        self.db.link_image_to_pair(pair, image_a, {"seed": 1})
+        self.db.link_image_to_pair(pair, image_b, {"seed": 2})
+        self.replace(b, DIGEST_A, ["sibling"])
+        self.replace(c, DIGEST_A, ["copy"])  # equal bytes at another path
+        before = self.rows(*LEGACY_TABLES)
+        sibling_before = self.db.read_image_tags(b, DIGEST_A)
+        copy_before = self.db.read_image_tags(c, DIGEST_A)
+
+        receipt = self.replace(a, DIGEST_A, ["only a"])
+
+        self.assertEqual((receipt["tags"], receipt["tag_revision"]), (["only a"], 1))
+        after = self.rows(*LEGACY_TABLES)
+        # The registry gained the new name; nothing else moved.
+        self.assertEqual(after[1:], before[1:])
+        self.assertEqual([row for row in after[0] if row[1] != "only a"], before[0])
+        self.assertEqual(self.db.read_image_tags(b, DIGEST_A), sibling_before)
+        self.assertEqual(self.db.read_image_tags(c, DIGEST_A), copy_before)
+        self.assertEqual(self.db.get_prompt_by_id(prompt)["tags"], ["shared"])
+        self.assertEqual(self.db.get_prompt_pair(pair)["tags"], ["pairtag"])
+
+    def test_changed_bytes_at_same_locator_start_empty_and_keep_prior(self):
+        loc = self.locator("a.png")
+        self.replace(loc, DIGEST_A, ["old"])
+        self.assertEqual(
+            self.db.read_image_tags(loc, DIGEST_B),
+            {"tags": [], "tag_revision": 0, "prior_count": 1},
+        )
+        receipt = self.replace(loc, DIGEST_B, ["new"], mtime_ns=MTIME + 5)
+        self.assertEqual((receipt["tags"], receipt["tag_revision"]), (["new"], 1))
+        self.assertEqual(
+            self.db.read_image_tags(loc, DIGEST_A),
+            {"tags": ["old"], "tag_revision": 1, "prior_count": 1},
+        )
+        self.assertEqual(
+            self.db.read_image_tags(loc, DIGEST_B),
+            {"tags": ["new"], "tag_revision": 1, "prior_count": 1},
+        )
+        self.assertEqual(self.counts()["media_annotation_files"], 1)
+        self.assertEqual(self.counts()["media_annotation_bytes"], 2)
+        self.assertEqual(
+            self.db.read_image_tags(self.locator("unseen.png"), DIGEST_A),
+            {"tags": [], "tag_revision": 0, "prior_count": 0},
+        )
+
+    def test_revision_conflict_returns_current_set(self):
+        loc = self.locator("a.png")
+        self.replace(loc, tags=["a"])
+        before = self.rows(*ANNOTATION_TABLES, "tags")
+        with self.assertRaises(AnnotationCommandError) as ctx:
+            self.replace(loc, tags=["b"], revision=0)
+        self.assertEqual(
+            (ctx.exception.code, ctx.exception.current["tag_revision"]),
+            ("tag-conflict", 1),
+        )
+        self.assertIsInstance(ctx.exception, LibraryCommandError)
+        self.assertEqual(ctx.exception.epoch, self.epoch)
+        self.assertEqual(ctx.exception.current["tags"], ["a"])
+        self.assertEqual(ctx.exception.current["sha256"], DIGEST_A)
+        with self.assertRaises(AnnotationCommandError) as ahead:
+            self.replace(loc, tags=["a"], revision=5)
+        self.assertEqual(ahead.exception.code, "tag-conflict")
+        self.assertEqual(self.rows(*ANNOTATION_TABLES, "tags"), before)
+        self.assertFalse(self.db.model.get_connection().in_transaction)
+
+    def test_identical_replay_after_commit_is_success_replayed(self):
+        loc = self.locator("a.png")
+        first = self.replace(loc, tags=["a", "b"])
+        self.assertEqual((first["tag_revision"], first["replayed"]), (1, False))
+        before = self.rows(*ANNOTATION_TABLES)
+        # The lost-response retry: same set, the revision it was sent against.
+        retry = self.replace(loc, tags=["a", "b"], revision=0)
+        self.assertEqual(retry, {**first, "replayed": True})
+        # Saving the current set at the current revision writes nothing either.
+        again = self.replace(loc, tags=["a", "b"], revision=1)
+        self.assertEqual(again, {**first, "replayed": True})
+        self.assertEqual(self.rows(*ANNOTATION_TABLES), before)
+        # Order is part of the set.
+        reordered = self.replace(loc, tags=["b", "a"], revision=1)
+        self.assertEqual(
+            (reordered["tags"], reordered["tag_revision"], reordered["replayed"]),
+            (["b", "a"], 2, False),
+        )
+        self.assertEqual(self.index_revision(), 2)
+
+    def test_replay_with_new_fingerprint_moves_only_the_index_revision(self):
+        loc = self.locator("a.png")
+        first = self.replace(loc, tags=["a"])
+        index = self.index_revision()
+        same = self.replace(loc, tags=["a"], revision=1)
+        self.assertEqual(same, {**first, "replayed": True})
+        self.assertEqual(self.index_revision(), index)  # identical: nothing moved
+        touched = self.replace(loc, tags=["a"], revision=1, mtime_ns=MTIME + 5)
+        self.assertEqual(touched, {**first, "replayed": True})
+        self.assertEqual(self.index_revision(), index + 1)  # currency changed
+        self.assertEqual(
+            self.db.current_image_tags({loc: (SIZE, MTIME + 5)}), {loc: ["a"]}
+        )
+        self.assertEqual(self.db.current_image_tags({loc: (SIZE, MTIME)}), {})
+        self.assertEqual(self.read(loc)["tag_revision"], 1)
+
+    def test_epoch_checked_inside_transaction(self):
+        loc = self.locator("a.png")
+        seen = []
+        original = PromptDatabase._library_epoch
+
+        def spy(db, conn, expected_epoch):
+            seen.append(conn.in_transaction)
+            return original(db, conn, expected_epoch)
+
+        with patch.object(PromptDatabase, "_library_epoch", spy):
+            self.replace(loc, tags=["a"])
+            self.add(loc, tags=["b"])
+        self.assertEqual(seen, [True, True])
+        stale = "11111111-2222-4333-8444-555555555555"
+        for call in (
+            lambda: self.replace(
+                self.locator("x.png"), tags=["a"], expected_epoch=stale
+            ),
+            lambda: self.add(self.locator("x.png"), tags=["a"], expected_epoch=stale),
+        ):
+            with self.assertRaises(LibraryCommandError) as ctx:
+                call()
+            self.assertEqual(ctx.exception.code, "storage-changed")
+            self.assertEqual(ctx.exception.epoch, self.epoch)
+        self.assertEqual(self.counts()["media_annotation_files"], 1)
+        for bad_epoch in (None, 7, "not-a-uuid"):
+            with self.assertRaises(ValueError):
+                self.replace(loc, tags=["a"], expected_epoch=bad_epoch)
+
+    def test_limit_and_invalid_names_rejected_without_partial_write(self):
+        loc = self.locator("a.png")
+        before = self.rows(*ANNOTATION_TABLES, "tags")
+        for tags in (
+            ["ok", "a,b"],
+            ["ok", ""],
+            ["ok", 3],
+            "ok",
+            [f"t{i}" for i in range(101)],
+        ):
+            with self.subTest(tags=tags), self.assertRaises(ValueError):
+                self.replace(loc, tags=tags)
+            with self.subTest(tags=tags, command="add"), self.assertRaises(ValueError):
+                self.add(loc, tags=tags)
+        for field, value in (
+            ("locator", ""),
+            ("locator", None),
+            ("locator", "x" * 4097),
+            ("sha256", DIGEST_A.upper()),
+            ("sha256", DIGEST_A[:-1]),
+            ("sha256", None),
+            ("size", -1),
+            ("size", True),
+            ("size", "7"),
+            ("mtime_ns", 1.5),
+            ("mtime_ns", None),
+            ("expected_tag_revision", -1),
+            ("expected_tag_revision", False),
+        ):
+            with self.subTest(field=field, value=value), self.assertRaises(ValueError):
+                self.replace(loc, tags=["ok"], **{field: value})
+        self.assertEqual(self.rows(*ANNOTATION_TABLES, "tags"), before)
+        self.assertEqual(self.index_revision(), 0)
+
+    def test_writers_supply_uuid_ids_and_refuse_to_write_without_one(self):
+        loc = self.locator("a.png")
+        before = self.rows(*ANNOTATION_TABLES)
+        with patch.object(annotations_module, "uuid4", return_value=""):
+            with self.assertRaises(ValueError):
+                self.replace(loc, tags=["a"])
+        self.assertEqual(self.rows(*ANNOTATION_TABLES), before)
+        self.replace(loc, tags=["a"])
+        self.add(self.locator("b.png"), DIGEST_B, ["b"])
+        conn = self.db.model.get_connection()
+        for table in ("media_annotation_files", "media_annotation_bytes"):
+            for (value,) in conn.execute(f"SELECT id FROM {table}"):
+                self.assertRegex(value, UUID)
+        self.schema_clean()
+
+    def test_never_resolves_owner_through_prompt_lookup(self):
+        loc = self.locator("a.png")
+        prompt = self.db.save_prompt("Linked", tags=["prompt-tag"])
+        self.db.link_image_to_prompt(prompt, loc)
+        with patch.object(
+            PromptDatabase,
+            "get_prompt_id_for_image",
+            side_effect=AssertionError("prompt lookup is not an owner"),
+        ):
+            self.replace(loc, tags=["img"])
+            self.add(loc, tags=["more"])
+            self.assertEqual(
+                self.db.read_image_tags(loc, DIGEST_A)["tags"], ["img", "more"]
+            )
+            self.assertEqual(
+                self.db.current_image_tags({loc: (SIZE, MTIME)}),
+                {loc: ["img", "more"]},
+            )
+            self.assertTrue(
+                self.db.refresh_image_fingerprint(loc, DIGEST_A, SIZE, MTIME + 1)
+            )
+            list(self.db.iter_image_tag_records())
+        self.assertEqual(self.db.get_prompt_by_id(prompt)["tags"], ["prompt-tag"])
+
+
+class AddImageTagsTests(AnnotationTestCase):
+    def test_add_merges_without_removing_and_caps_at_100(self):
+        loc = self.locator("a.png")
+        self.replace(loc, tags=["Forest", "mist"])
+        receipt = self.add(loc, tags=["forest", "Rain", "rain"])
+        self.assertEqual(
+            receipt,
+            {
+                "library_epoch": self.epoch,
+                "sha256": DIGEST_A,
+                "tags": ["Forest", "mist", "Rain"],
+                "tag_revision": 2,
+                "replayed": False,
+                "added": 1,
+            },
+        )
+        nothing = self.add(loc, tags=["MIST"])
+        self.assertEqual(
+            (nothing["tags"], nothing["tag_revision"], nothing["replayed"]),
+            (["Forest", "mist", "Rain"], 2, True),
+        )
+        self.assertEqual(nothing["added"], 0)
+        before = self.rows(*ANNOTATION_TABLES, "tags")
+        with self.assertRaises(AnnotationCommandError) as ctx:
+            self.add(loc, tags=[f"t{i}" for i in range(98)])
+        self.assertEqual(ctx.exception.code, "tag-limit")
+        self.assertEqual(ctx.exception.current["tag_revision"], 2)
+        self.assertEqual(self.rows(*ANNOTATION_TABLES, "tags"), before)
+        exact = self.add(loc, tags=[f"t{i}" for i in range(97)])
+        self.assertEqual((len(exact["tags"]), exact["added"]), (100, 97))
+        # An unseen file: add creates the owner and byte record like a save.
+        fresh = self.add(self.locator("b.png"), DIGEST_B, ["one"])
+        self.assertEqual(
+            (fresh["tags"], fresh["tag_revision"], fresh["added"]), (["one"], 1, 1)
+        )
+        self.schema_clean()
+
+
+class CurrentImageTagsTests(AnnotationTestCase):
+    def test_current_tags_require_matching_fingerprint(self):
+        loc = self.locator("a.png")
+        other = self.locator("b.png")
+        self.replace(loc, tags=["a"])
+        self.replace(other, DIGEST_B, [], mtime_ns=MTIME + 9)
+        self.assertEqual(
+            self.db.current_image_tags({loc: (SIZE, MTIME), other: (SIZE, MTIME + 9)}),
+            {loc: ["a"], other: []},
+        )
+        self.assertEqual(self.db.current_image_tags({loc: (SIZE, MTIME + 1)}), {})
+        self.assertEqual(self.db.current_image_tags({loc: (SIZE + 1, MTIME)}), {})
+        self.assertEqual(self.db.current_image_tags({}), {})
+        self.assertEqual(
+            self.db.current_image_tags({self.locator("none.png"): (SIZE, MTIME)}), {}
+        )
+        # Refreshing the verified fingerprint makes the record current again.
+        self.assertTrue(
+            self.db.refresh_image_fingerprint(loc, DIGEST_A, SIZE, MTIME + 1)
+        )
+        self.assertFalse(self.db.refresh_image_fingerprint(loc, DIGEST_B, SIZE, MTIME))
+        self.assertFalse(
+            self.db.refresh_image_fingerprint(
+                self.locator("x.png"), DIGEST_A, SIZE, MTIME
+            )
+        )
+        self.assertEqual(
+            self.db.current_image_tags({loc: (SIZE, MTIME + 1)}), {loc: ["a"]}
+        )
+        self.assertEqual(self.db.current_image_tags({loc: (SIZE, MTIME)}), {})
+        self.assertEqual(
+            self.db.read_image_tags(loc, DIGEST_A),
+            {"tags": ["a"], "tag_revision": 1, "prior_count": 0},
+        )
+        for bad in (None, [], {loc: (SIZE,)}, {loc: (SIZE, 1.5)}, {3: (SIZE, MTIME)}):
+            with self.subTest(bad=bad), self.assertRaises(ValueError):
+                self.db.current_image_tags(bad)
+
+    def test_newest_verification_wins_on_equal_fingerprints(self):
+        loc = self.locator("a.png")
+        stamps = iter(f"2026-10-22T00:00:0{i}.000000+00:00" for i in range(10))
+        with patch.object(annotations_module, "utc_now_iso", side_effect=stamps):
+            self.replace(loc, DIGEST_A, ["old bytes"])
+            self.replace(loc, DIGEST_B, ["new bytes"])  # same size and mtime
+        self.assertEqual(
+            self.db.current_image_tags({loc: (SIZE, MTIME)}), {loc: ["new bytes"]}
+        )
+        with patch.object(
+            annotations_module,
+            "utc_now_iso",
+            return_value="2026-10-22T00:01:00.000000+00:00",
+        ):
+            self.assertTrue(
+                self.db.refresh_image_fingerprint(loc, DIGEST_A, SIZE, MTIME)
+            )
+        self.assertEqual(
+            self.db.current_image_tags({loc: (SIZE, MTIME)}), {loc: ["old bytes"]}
+        )
+
+    def test_lookup_is_chunked_and_records_stream_in_position_order(self):
+        locators = [self.locator(f"{i:04}.png") for i in range(503)]
+        self.replace(locators[0], tags=["z", "y"])
+        self.replace(locators[502], DIGEST_B, ["x"], mtime_ns=MTIME + 2)
+        self.replace(locators[250], DIGEST_B, [], mtime_ns=MTIME + 1)
+        statements = []
+        conn = self.db.model.get_connection()
+        conn.set_trace_callback(statements.append)
+        try:
+            current = self.db.current_image_tags(
+                {
+                    loc: (SIZE, MTIME + (2 if i == 502 else 0))
+                    for i, loc in enumerate(locators)
+                }
+            )
+        finally:
+            conn.set_trace_callback(None)
+        self.assertEqual(current, {locators[0]: ["z", "y"], locators[502]: ["x"]})
+        lookups = [s for s in statements if "media_annotation_files" in s]
+        self.assertEqual(len(lookups), 2)
+        self.assertEqual(
+            list(self.db.iter_image_tag_records()),
+            [
+                (locators[0], SIZE, MTIME, ["z", "y"]),
+                (locators[250], SIZE, MTIME + 1, []),
+                (locators[502], SIZE, MTIME + 2, ["x"]),
+            ],
+        )
+
+
+class AnnotationIsolationTests(AnnotationTestCase):
+    def test_cascade_from_vocabulary_delete_keeps_byte_records(self):
+        loc = self.locator("a.png")
+        self.replace(loc, tags=["gone", "kept"])
+        self.db.delete_tag_all_prompts("gone")
+        self.assertEqual(
+            self.db.read_image_tags(loc, DIGEST_A),
+            {
+                "tags": ["kept"],
+                "tag_revision": 2,
+                "prior_count": 0,
+            },  # moved by the delete
+        )
+        self.schema_clean()
+
+    def test_junction_failure_leaves_nothing_behind(self):
+        loc = self.locator("a.png")
+        self.replace(loc, tags=["a"])
+        conn = self.db.model.get_connection()
+        conn.execute(
+            "CREATE TRIGGER reject_image_tag BEFORE INSERT ON media_image_tags "
+            "BEGIN SELECT RAISE(ABORT,'image tag failure'); END"
+        )
+        conn.commit()
+        before = self.rows(*ANNOTATION_TABLES, "tags")
+        with self.assertRaises(sqlite3.IntegrityError):
+            self.replace(loc, tags=["b"], revision=1)
+        with self.assertRaises(sqlite3.IntegrityError):
+            self.add(self.locator("new.png"), DIGEST_B, ["c"])
+        self.assertFalse(conn.in_transaction)
+        self.assertEqual(self.rows(*ANNOTATION_TABLES, "tags"), before)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_api_admin.py

@@ -2476,7 +2476,8 @@ def _write_mp4(path, comment):
 
 
 class TestScanReadsVideos(AdminAPITestCase):
-    """Videos saved by ComfyUI carry the graph in their comment tag."""
+    """Videos carry the graph in per-key container tags (current savers) or in
+    the old VideoHelperSuite comment envelope; the scan reads one carrier."""
 
     def setUp(self):
         super().setUp()
@@ -2506,6 +2507,56 @@ class TestScanReadsVideos(AdminAPITestCase):
         images = self.api.db.get_prompt_images(prompts[0]["id"])
         self.assertTrue(images[0]["image_path"].endswith("clip.mp4"))
 
+    async def test_scan_links_per_key_tag_video_with_default_profile(self):
+        """A current saver's per-key tags scan exactly like the same graph as PNG."""
+        from utils import video_metadata
+
+        _write_png(self.output_dir / "same.png", prompt_text="a cat")
+        graph = {
+            "1": {"class_type": "CLIPTextEncode", "inputs": {"text": "a cat"}},
+            "2": {"class_type": "CLIPTextEncode", "inputs": {"text": "bad"}},
+            "3": {
+                "class_type": "KSampler",
+                "inputs": {"positive": ["1", 0], "negative": ["2", 0]},
+            },
+        }
+        (self.output_dir / "clip.mkv").write_bytes(b"\x1aE\xdf\xa3 fixture")
+        probed = {
+            "format": {
+                "tags": {
+                    "PROMPT": json.dumps(graph),
+                    "WORKFLOW": '{"nodes":[]}',
+                    "COMMENT": json.dumps({"prompt": "must not win"}),
+                }
+            }
+        }
+        GalleryConfig.MONITORING_DIRECTORIES = [self._root(self.output_dir)]
+
+        with (
+            patch.object(video_metadata.shutil, "which", return_value="/bin/ffprobe"),
+            patch.object(
+                video_metadata.subprocess,
+                "run",
+                return_value=MagicMock(returncode=0, stdout=json.dumps(probed)),
+            ) as run,
+            self.assertNoLogs(level="ERROR"),
+        ):
+            body = await (
+                await self.client.request("POST", "/prompt_manager/scan")
+            ).text()
+
+        self.assertEqual(run.call_args.args[0][-1], str(self.output_dir / "clip.mkv"))
+        self.assertIn('"found": 2', body)
+        prompts = self.api.db.get_recent_prompts(limit=10)["prompts"]
+        self.assertEqual(sorted(p["text"] for p in prompts), ["a cat", "bad"])
+        positive = next(p for p in prompts if p["text"] == "a cat")
+        images = self.api.db.get_prompt_images(positive["id"])
+        self.assertEqual(
+            sorted(os.path.basename(image["image_path"]) for image in images),
+            ["clip.mkv", "same.png"],
+        )
+        self.assertNotIn("must not win", json.dumps(prompts))
+
     async def test_scan_without_ffprobe_skips_videos_quietly(self):
         from unittest.mock import patch
         from utils import video_metadata

tests/test_api_prompt_inspector.py

@@ -1,7 +1,11 @@
 """Physical-file prompt inspection is bounded, conservative and read-only."""
 
+import io
 import json
-from unittest.mock import patch
+import shutil
+import subprocess
+import unittest
+from unittest.mock import MagicMock, patch
 
 from PIL import Image, PngImagePlugin
 
@@ -15,6 +19,9 @@ except ImportError:
 from utils.pair_execution import EXECUTION_KEY, record_pair_execution
 from database.pair_ingestion import ingest_resolved_pair
 from utils.prompt_pair_resolver import resolve_prompt_pair
+from utils import video_metadata
+
+HAVE_FFMPEG = bool(shutil.which("ffmpeg") and shutil.which("ffprobe"))
 
 
 def graph(positive="portrait", negative="blurry"):
@@ -28,6 +35,54 @@ def graph(positive="portrait", negative="blurry"):
     }
 
 
+def write_video(path, metadata_tags=True, **tags):
+    """Tiny black clip carrying one container tag per keyword (needs ffmpeg).
+
+    MP4 keeps arbitrary keys only with ``use_metadata_tags`` (mdta atoms), the
+    movflag the core SaveVideo node sets; without it ffmpeg writes the legacy
+    ilst atoms that old VideoHelperSuite files carry. Matroska and WebM
+    upper-case the key names.
+    """
+    command = [
+        "ffmpeg",
+        "-v",
+        "quiet",
+        "-f",
+        "lavfi",
+        "-i",
+        "color=c=black:s=16x16:d=0.2",
+    ]
+    if metadata_tags and path.suffix.lower() in (".mp4", ".mov", ".m4v"):
+        command += ["-movflags", "use_metadata_tags"]
+    for key, value in tags.items():
+        command += ["-metadata", f"{key}={value}"]
+    subprocess.run(command + ["-y", str(path)], check=True, timeout=60)
+    return path
+
+
+class ProbeOutput(io.BytesIO):
+    """ffprobe stdout that records the bounded read size asked of it."""
+
+    requested_size = None
+
+    def read(self, size=-1):
+        self.requested_size = size
+        return super().read(size)
+
+
+def probe_process(payload, poll=0, returncode=0):
+    """A fake ffprobe whose stdout is ``payload`` bytes."""
+    process = MagicMock()
+    process.stdout = ProbeOutput(payload)
+    process.poll.return_value = poll
+    process.returncode = returncode
+    return process
+
+
+def probe_payload(tags):
+    return json.dumps({"format": {"tags": tags}}).encode()
+
+
 def png(path, **metadata):
     info = PngImagePlugin.PngInfo()
     for key, value in metadata.items():
@@ -312,7 +367,7 @@ class TestPromptInspector(ImageAPITestCase):
     async def test_corrupt_truncated_duplicate_and_expanding_metadata_fail_closed(self):
         import struct
         import zlib
-        from utils.prompt_inspector import MAX_METADATA_BYTES
+        from utils.prompt_inspector import VIDEO_REPROBE_BYTES
 
         path = self.output_dir / "image.png"
         base = png(path, prompt=graph()).read_bytes()
@@ -325,8 +380,8 @@ class TestPromptInspector(ImageAPITestCase):
         cases.append(bytes(broken))
         for kind, payload in (
             (b"tEXt", b"prompt\0{}"),
-            (b"zTXt", b"prompt\0\0" + zlib.compress(b"x" * (MAX_METADATA_BYTES + 1))),
-            (b"tEXt", b"prompt\0" + b"x" * (MAX_METADATA_BYTES + 1)),
+            (b"zTXt", b"prompt\0\0" + zlib.compress(b"x" * (VIDEO_REPROBE_BYTES + 1))),
+            (b"tEXt", b"prompt\0" + b"x" * (VIDEO_REPROBE_BYTES + 1)),
             (b"tEXt", b"bad-key-without-separator"),
             (b"zTXt", b"prompt\0\1bad-compression"),
             (b"iTXt", b"prompt\0\2\0\0\0text"),
@@ -385,9 +440,7 @@ class TestPromptInspector(ImageAPITestCase):
         self.assertEqual(result["prompts"]["positive"]["status"], "absent")
 
     async def test_video_inspection_uses_bounded_container_evidence(self):
-        import io
-        from unittest.mock import MagicMock
-        from utils.prompt_inspector import MAX_METADATA_BYTES
+        from utils.prompt_inspector import VIDEO_PROBE_BYTES, VIDEO_REPROBE_BYTES
 
         (self.output_dir / "clip.mp4").write_bytes(b"video fixture")
         metadata = {"prompt": graph("Video portrait", "")}
@@ -412,14 +465,25 @@ class TestPromptInspector(ImageAPITestCase):
         process.wait.assert_called()
         self.assertNotIn("shell", spawn.call_args.kwargs)
         self.assertIn(str(self.output_dir / "clip.mp4"), spawn.call_args.args[0])
-        process.stdout = io.BytesIO(b"x" * (MAX_METADATA_BYTES + 1))
+        # An envelope over the probe bound cannot be split: the role-only
+        # re-probe overflows too and the read fails instead of guessing.
+        processes = [
+            probe_process(b"x" * (VIDEO_PROBE_BYTES + 1)),
+            probe_process(b"x" * (VIDEO_REPROBE_BYTES + 1)),
+        ]
         with (
             patch("utils.prompt_inspector.ffprobe_path", return_value="/tool/ffprobe"),
-            patch("utils.prompt_inspector.subprocess.Popen", return_value=process),
+            patch(
+                "utils.prompt_inspector.subprocess.Popen", side_effect=processes
+            ) as spawn,
         ):
             _, result = await self.inspect("clip.mp4")
+        self.assertEqual(spawn.call_count, 2)
         self.assertEqual(result["prompts"]["positive"]["status"], "unresolved")
-        self.assertTrue(process.stdout.closed)
+        self.assertEqual(result["metadata"]["status"], "unreadable")
+        for process in processes:
+            self.assertTrue(process.stdout.closed)
+            process.wait.assert_called()
 
     async def test_video_missing_probe_and_timeout_preserve_uncertainty(self):
         import io
@@ -895,11 +959,9 @@ class TestPromptInspector(ImageAPITestCase):
         self.assertNotIn("\ufffd".encode(), body)
         self.assertLessEqual(len(body), 8 * 1024 * 1024)
 
-    async def video_inspect(self, comment=None, description=None):
-        import io
+    async def video_inspect(self, comment=None, description=None, **per_key):
         import threading
-        from unittest.mock import MagicMock
-        from utils.prompt_inspector import MAX_METADATA_BYTES
+        from utils.prompt_inspector import VIDEO_PROBE_BYTES
 
         path = self.output_dir / "clip.mp4"
         path.write_bytes(b"fixture")
@@ -908,17 +970,8 @@ class TestPromptInspector(ImageAPITestCase):
             for key, value in (("comment", comment), ("description", description))
             if value is not None
         }
-        payload = json.dumps({"format": {"tags": tags}}).encode()
-
-        class ProbeOutput(io.BytesIO):
-            def read(self, size=-1):
-                self.requested_size = size
-                return super().read(size)
-
-        process = MagicMock()
-        process.stdout = ProbeOutput(payload)
-        process.poll.return_value = 0
-        process.returncode = 0
+        tags.update(per_key)
+        process = probe_process(probe_payload(tags))
         timers = []
         timer_type = threading.Timer
 
@@ -937,11 +990,156 @@ class TestPromptInspector(ImageAPITestCase):
             response, result = await self.inspect("clip.mp4")
         self.assertEqual(spawn.call_count, 1)
         self.assertTrue(process.stdout.closed)
-        self.assertEqual(process.stdout.requested_size, MAX_METADATA_BYTES + 1)
+        self.assertEqual(process.stdout.requested_size, VIDEO_PROBE_BYTES + 1)
         self.assertEqual(len(timers), 1)
         self.assertTrue(timers[0].finished.is_set())
+        self.assertEqual(
+            spawn.call_args.args[0][spawn.call_args.args[0].index("-show_entries") + 1],
+            "format_tags=prompt,workflow,parameters,"
+            "comfyassets_prompt_pairs,comment,description",
+        )
         return response, result
 
+    async def test_video_separate_prompt_workflow_tags_are_read(self):
+        source = graph("per-key portrait", "per-key negative")
+        workflow = '{"nodes":[{"id":"per-key"}],"cfg":6.5000000000000000001}'
+        for tags in (
+            {"prompt": json.dumps(source), "workflow": workflow},
+            {"PROMPT": json.dumps(source), "WORKFLOW": workflow},
+        ):
+            _, result = await self.video_inspect(
+                json.dumps({"prompt": graph("comment must not win")}), **tags
+            )
+            self.assertEqual(
+                result["prompts"]["positive"], self.side("per-key portrait")
+            )
+            self.assertEqual(
+                result["prompts"]["negative"], self.side("per-key negative")
+            )
+            self.assertEqual(
+                result["metadata"]["record_formats"],
+                {"prompt": "original-text", "workflow": "original-text"},
+            )
+            self.assertEqual(result["metadata"]["raw"]["workflow"], workflow)
+            self.assertEqual(
+                result["metadata"]["workflow_graph"]["value"]["cfg"],
+                "6.5000000000000000001",
+            )
+            self.assertNotIn("must not win", json.dumps(result))
+        _, result = await self.video_inspect(
+            **{"PROMPT": json.dumps(source), "prompt": json.dumps(graph("other"))}
+        )
+        self.assertEqual(result["prompts"]["positive"]["status"], "unresolved")
+        self.assertEqual(result["metadata"]["status"], "unreadable")
+
+    @unittest.skipUnless(HAVE_FFMPEG, "ffmpeg/ffprobe not installed")
+    async def test_video_per_key_and_comment_tags_read_from_real_containers(self):
+        video_metadata.ffprobe_path.cache_clear()
+        self.addCleanup(video_metadata.ffprobe_path.cache_clear)
+        source = json.dumps(graph("real portrait", ""))
+        workflow = '{"nodes":[{"id":"real"}]}'
+        for name in ("per_key.mp4", "per_key.mkv", "per_key.webm"):
+            write_video(self.output_dir / name, prompt=source, workflow=workflow)
+            response, result = await self.inspect(name)
+            self.assertEqual(response.status, 200, name)
+            self.assertEqual(
+                result["prompts"]["positive"], self.side("real portrait"), name
+            )
+            self.assertEqual(result["metadata"]["raw"]["workflow"], workflow, name)
+            self.assertEqual(
+                result["metadata"]["record_formats"],
+                {"prompt": "original-text", "workflow": "original-text"},
+                name,
+            )
+        # Old VideoHelperSuite envelope in the legacy ilst comment atom, unchanged.
+        write_video(
+            self.output_dir / "vhs.mp4",
+            metadata_tags=False,
+            comment=json.dumps({"prompt": json.loads(source), "workflow": {"v": 1}}),
+        )
+        _, result = await self.inspect("vhs.mp4")
+        self.assertEqual(result["prompts"]["positive"], self.side("real portrait"))
+        self.assertEqual(
+            result["metadata"]["record_formats"],
+            {"prompt": "reserialized-json", "workflow": "reserialized-json"},
+        )
+        self.assertEqual(result["metadata"]["workflow_graph"]["value"], {"v": 1})
+
+    async def test_video_oversize_workflow_reprobes_role_only_and_marks_limited(self):
+        from utils.prompt_inspector import VIDEO_PROBE_BYTES, VIDEO_REPROBE_BYTES
+
+        path = self.output_dir / "clip.mp4"
+        path.write_bytes(b"fixture")
+        source = json.dumps(graph("bounded portrait", ""))
+        processes = [
+            probe_process(b"x" * (VIDEO_PROBE_BYTES + 1)),
+            probe_process(probe_payload({"PROMPT": source})),
+        ]
+        with (
+            patch("utils.prompt_inspector.ffprobe_path", return_value="/tool/ffprobe"),
+            patch(
+                "utils.prompt_inspector.subprocess.Popen", side_effect=processes
+            ) as spawn,
+        ):
+            response, result = await self.inspect("clip.mp4")
+        self.assertEqual(response.status, 200)
+        self.assertEqual(spawn.call_count, 2)
+        first, second = (call.args[0] for call in spawn.call_args_list)
+        self.assertEqual(
+            first[first.index("-show_entries") + 1],
+            "format_tags=prompt,workflow,parameters,"
+            "comfyassets_prompt_pairs,comment,description",
+        )
+        self.assertEqual(
+            second[second.index("-show_entries") + 1],
+            "format_tags=prompt,parameters,comfyassets_prompt_pairs,"
+            "comment,description",
+        )
+        self.assertEqual(processes[0].stdout.requested_size, VIDEO_PROBE_BYTES + 1)
+        self.assertEqual(processes[1].stdout.requested_size, VIDEO_REPROBE_BYTES + 1)
+        for process in processes:
+            self.assertTrue(process.stdout.closed)
+            process.wait.assert_called()
+        self.assertEqual(result["prompts"]["positive"], self.side("bounded portrait"))
+        self.assertEqual(result["metadata"]["status"], "available")
+        self.assertEqual(
+            result["metadata"]["record_formats"],
+            {"prompt": "original-text", "workflow": "limited"},
+        )
+        self.assertNotIn("workflow", result["metadata"]["raw"])
+        self.assertEqual(result["metadata"]["workflow_graph"]["status"], "limited")
+        # The dropped per-key workflow belonged to an unselected carrier when
+        # an envelope wins the re-probe: that envelope is whole, not limited.
+        envelope = json.dumps({"prompt": json.loads(source), "workflow": {"v": 2}})
+        processes = [
+            probe_process(b"x" * (VIDEO_PROBE_BYTES + 1)),
+            probe_process(probe_payload({"comment": envelope})),
+        ]
+        with (
+            patch("utils.prompt_inspector.ffprobe_path", return_value="/tool/ffprobe"),
+            patch("utils.prompt_inspector.subprocess.Popen", side_effect=processes),
+        ):
+            _, result = await self.inspect("clip.mp4")
+        self.assertEqual(result["prompts"]["positive"], self.side("bounded portrait"))
+        self.assertEqual(result["metadata"]["workflow_graph"]["value"], {"v": 2})
+        self.assertEqual(
+            result["metadata"]["record_formats"]["workflow"], "reserialized-json"
+        )
+        # A workflow-only per-key video over budget is limited, not absent.
+        processes = [
+            probe_process(b"x" * (VIDEO_PROBE_BYTES + 1)),
+            probe_process(probe_payload({})),
+        ]
+        with (
+            patch("utils.prompt_inspector.ffprobe_path", return_value="/tool/ffprobe"),
+            patch("utils.prompt_inspector.subprocess.Popen", side_effect=processes),
+        ):
+            _, result = await self.inspect("clip.mp4")
+        self.assertEqual(result["metadata"]["status"], "available")
+        self.assertEqual(result["metadata"]["record_formats"], {"workflow": "limited"})
+        self.assertEqual(result["metadata"]["workflow_graph"]["status"], "limited")
+        self.assertEqual(result["prompts"]["positive"]["status"], "absent")
+
     async def test_video_role_description_wins_over_workflow_only_comment(self):
         evidence = {}
         source = graph("chosen", "")

tests/test_api_vocabulary.py

@@ -1,6 +1,8 @@
 """Vocabulary read routes page with signed, epoch-scoped cursors."""
 
+import hashlib
 import json
+import os
 import unittest
 from unittest.mock import patch
 
@@ -184,6 +186,7 @@ class TestVocabularyAPI(ImageAPITestCase):
                     "id": created["tag"]["id"],
                     "name": "sunset",
                     "prompt_count": 0,
+                    "image_count": 0,
                 },
             },
         )
@@ -202,6 +205,7 @@ class TestVocabularyAPI(ImageAPITestCase):
                     "other_prompts": 0,
                     "negative_variants": 1,
                     "archived_negative_variants": 0,
+                    "images": 0,
                 },
             },
         )
@@ -221,9 +225,11 @@ class TestVocabularyAPI(ImageAPITestCase):
                     "id": created["tag"]["id"],
                     "name": "sunset",
                     "prompt_count": 2,
+                    "image_count": 0,
                 },
                 "components_changed": 1,
                 "pairs_changed": 1,
+                "images_changed": 0,
             },
         )
         self.assertEqual(self.api.db.get_prompt_by_id(parent)["tags"], ["sunset"])
@@ -242,6 +248,7 @@ class TestVocabularyAPI(ImageAPITestCase):
                 "deleted": True,
                 "components_changed": 1,
                 "pairs_changed": 1,
+                "images_changed": 0,
             },
         )
         self.assertEqual(self.api.db.get_all_tags(), [])
@@ -253,6 +260,95 @@ class TestVocabularyAPI(ImageAPITestCase):
             self.assertEqual(response.status, 400, bad)
             self.assertNotIn("code", result)
 
+    def image(self, name, tags, digest="a", mtime_ns=1):
+        """Tag the bytes ``digest`` of the file ``name``; return its locator."""
+        locator = os.path.normcase(str(self.output_dir / name))
+        self.api.db.replace_image_tags(
+            locator=locator,
+            sha256=hashlib.sha256(digest.encode()).hexdigest(),
+            size=1,
+            mtime_ns=mtime_ns,
+            expected_epoch=self.api.db.get_execution_epoch(),
+            expected_tag_revision=0,
+            tags=tags,
+        )
+        return locator
+
+    async def test_tag_rows_report_image_count_by_locator(self):
+        self._save_prompt("Prompt only", tags=["prompt-only", "shared"])
+        self.image("one.png", ["twice", "shared"], digest="old")
+        self.image("one.png", ["twice"], digest="new", mtime_ns=2)
+        self.image("two.png", ["shared"], digest="new")
+        self.image("three.png", ["prior-only"], digest="first")
+        self.image("three.png", [], digest="second", mtime_ns=2)
+        response, page = await self.get("tags")
+        self.assertEqual(response.status, 200, page)
+        rows = {row["name"]: row for row in page["tags"]}
+        self.assertEqual(
+            {
+                name: (row["prompt_count"], row["image_count"])
+                for name, row in rows.items()
+            },
+            {
+                "prompt-only": (1, 0),
+                "shared": (1, 2),
+                "twice": (0, 1),
+                "prior-only": (0, 1),
+            },
+        )
+        row = rows["shared"]
+        self.assertEqual(row["image_count"], 2)
+        self.assertEqual(set(row), {"id", "name", "prompt_count", "image_count"})
+
+    async def test_impact_and_delete_counts_include_images(self):
+        epoch = self.api.db.get_execution_epoch()
+        self._save_prompt("Parent", tags=["moody"])
+        self.image("a.png", ["moody", "keep"])
+        self.image("b.png", ["moody"])
+        _, page = await self.get("tags")
+        moody = next(row for row in page["tags"] if row["name"] == "moody")
+        self.assertEqual(moody["image_count"], 2)
+        response, impact = await self.get(f"tags/{moody['id']}/impact")
+        self.assertEqual(response.status, 200, impact)
+        self.assertEqual(
+            impact["impact"],
+            {
+                "positive_prompts": 1,
+                "other_prompts": 0,
+                "negative_variants": 0,
+                "archived_negative_variants": 0,
+                "images": 2,
+            },
+        )
+        response, deleted = await self.send(
+            "POST",
+            f"tags/{moody['id']}/delete",
+            {"expected_epoch": epoch, "name": "moody"},
+        )
+        self.assertEqual(response.status, 200, deleted)
+        self.assertEqual(
+            deleted,
+            {
+                "success": True,
+                "library_epoch": epoch,
+                "deleted": True,
+                "components_changed": 1,
+                "pairs_changed": 0,
+                "images_changed": 2,
+            },
+        )
+        keep = next(
+            row for row in (await self.get("tags"))[1]["tags"] if row["name"] == "keep"
+        )
+        response, renamed = await self.send(
+            "PATCH",
+            f"tags/{keep['id']}",
+            {"expected_epoch": epoch, "name": "keep", "new_name": "kept"},
+        )
+        self.assertEqual(response.status, 200, renamed)
+        self.assertEqual(renamed["images_changed"], 1)
+        self.assertEqual(renamed["tag"]["image_count"], 1)
+
     async def test_create_route_validates_names(self):
         epoch = self.api.db.get_execution_epoch()
         before = self.tag_rows()

tests/test_database_backup.py

@@ -452,6 +452,44 @@ class TestRestoreFromFile(BackupTestCase):
                 ).fetchone()
             )
 
+    def test_restore_old_backup_without_annotations(self):
+        tables = (
+            "media_image_tags",
+            "media_annotation_bytes",
+            "media_annotation_files",
+            "media_annotation_metadata",
+        )
+        src = self._make_source_db(["predates image annotations"])
+        with closing(sqlite3.connect(src)) as conn:
+            conn.execute("PRAGMA foreign_keys=OFF")
+            for table in tables:
+                conn.execute(f"DROP TABLE {table}")
+            conn.commit()
+        self.assertTrue(PromptModel.verify_database_file(src)[0])
+        ok, reason = PromptModel.verify_database_file(src, require_library_state=True)
+        self.assertFalse(ok)
+        self.assertEqual(reason, "Missing image annotation schema")
+
+        self.db.model.restore_from_file(src)
+
+        self.assertEqual(_texts(self.path), ["predates image annotations"])
+        with closing(sqlite3.connect(self.path)) as conn:
+            self.assertEqual(
+                conn.execute("SELECT * FROM media_annotation_metadata").fetchall(),
+                [(1, 1, 0)],
+            )
+        ok, reason = PromptModel.verify_database_file(
+            self.path, require_library_state=True
+        )
+        self.assertTrue(ok, reason)
+        with closing(sqlite3.connect(src)) as conn:  # the source is untouched
+            self.assertEqual(
+                conn.execute(
+                    "SELECT COUNT(*) FROM sqlite_master WHERE name LIKE 'media_%'"
+                ).fetchone()[0],
+                0,
+            )
+
     def test_restore_preserves_favorites_and_closes_handles(self):
         self.db.set_image_favorite("output", "live.png")
         with tempfile.TemporaryDirectory() as directory:

tests/test_database_migrations.py

@@ -200,6 +200,104 @@ class TestIdempotentMigrations(MigrationTestCase):
 
         self.assertEqual(self._columns("prompt_library_state"), ["prompt_id", "title"])
 
+    def test_legacy_database_gains_annotation_group(self):
+        self._legacy_db([])
+
+        self._open()
+
+        for table in (
+            "media_annotation_metadata",
+            "media_annotation_files",
+            "media_annotation_bytes",
+            "media_image_tags",
+        ):
+            self.assertIn(table, self._table_names())
+        conn = sqlite3.connect(self.path)
+        try:
+            self.assertEqual(
+                conn.execute("SELECT * FROM media_annotation_metadata").fetchall(),
+                [(1, 1, 0)],
+            )
+            # No backfill: a legacy database starts with no image tags.
+            self.assertEqual(
+                conn.execute("SELECT COUNT(*) FROM media_image_tags").fetchone()[0], 0
+            )
+        finally:
+            conn.close()
+
+    def test_rebuild_keeps_annotation_rows(self):
+        # The prompts rebuild runs with foreign keys off; image tags that
+        # reference the tags table must survive it untouched.
+        file_id = "0f8e4b2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b"
+        byte_id = "6a1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d"
+        self._legacy_db(
+            [
+                "INSERT INTO prompts (text, hash, workflow_name)"
+                " VALUES ('a', 'h1', 'wf')",
+                "CREATE TABLE tags (id INTEGER PRIMARY KEY AUTOINCREMENT,"
+                " name TEXT NOT NULL UNIQUE)",
+                "INSERT INTO tags (id, name) VALUES (3, 'img-only')",
+                "CREATE TABLE media_annotation_metadata (singleton_id INTEGER"
+                " PRIMARY KEY CHECK(singleton_id=1), schema_version INTEGER NOT"
+                " NULL CHECK(schema_version=1), image_index_revision INTEGER NOT"
+                " NULL DEFAULT 0 CHECK(image_index_revision>=0))",
+                "INSERT INTO media_annotation_metadata VALUES (1, 1, 4)",
+                "CREATE TABLE media_annotation_files (id TEXT PRIMARY KEY"
+                " CHECK(length(id)=36), locator TEXT NOT NULL UNIQUE,"
+                " created_at TEXT NOT NULL)",
+                f"INSERT INTO media_annotation_files VALUES ('{file_id}',"
+                " '/out/a.png', '2026-10-22T00:00:00.000000+00:00')",
+                "CREATE TABLE media_annotation_bytes (id TEXT PRIMARY KEY"
+                " CHECK(length(id)=36), file_id TEXT NOT NULL REFERENCES"
+                " media_annotation_files(id) ON DELETE CASCADE, sha256 TEXT NOT"
+                " NULL CHECK(length(sha256)=64 AND sha256 NOT GLOB"
+                " '*[^0-9a-f]*'), size INTEGER NOT NULL CHECK(size>=0), mtime_ns"
+                " INTEGER NOT NULL, verified_at TEXT NOT NULL, first_seen_at TEXT"
+                " NOT NULL, tag_revision INTEGER NOT NULL DEFAULT 0"
+                " CHECK(tag_revision>=0), UNIQUE(file_id, sha256))",
+                "CREATE INDEX idx_media_annotation_bytes_fingerprint ON"
+                " media_annotation_bytes(file_id, size, mtime_ns)",
+                f"INSERT INTO media_annotation_bytes VALUES ('{byte_id}',"
+                f" '{file_id}', '{'a' * 64}', 3, 1700000000000000000,"
+                " '2026-10-22T00:00:00.000000+00:00',"
+                " '2026-10-22T00:00:00.000000+00:00', 2)",
+                "CREATE TABLE media_image_tags (byte_id TEXT NOT NULL REFERENCES"
+                " media_annotation_bytes(id) ON DELETE CASCADE, tag_id INTEGER"
+                " NOT NULL REFERENCES tags(id) ON DELETE CASCADE, position"
+                " INTEGER NOT NULL CHECK(position>=0), PRIMARY KEY(byte_id,"
+                " tag_id))",
+                "CREATE INDEX idx_media_image_tags_tag ON media_image_tags(tag_id)",
+                "CREATE UNIQUE INDEX idx_media_image_tags_position ON"
+                " media_image_tags(byte_id, position)",
+                f"INSERT INTO media_image_tags VALUES ('{byte_id}', 3, 0)",
+            ]
+        )
+
+        self._open()
+
+        self.assertNotIn("workflow_name", self._columns("prompts"))
+        conn = sqlite3.connect(self.path)
+        try:
+            self.assertEqual(
+                conn.execute("SELECT * FROM media_annotation_metadata").fetchall(),
+                [(1, 1, 4)],
+            )
+            self.assertEqual(
+                conn.execute(
+                    "SELECT t.name, it.position FROM media_image_tags it"
+                    " JOIN tags t ON t.id = it.tag_id"
+                ).fetchall(),
+                [("img-only", 0)],
+            )
+            self.assertEqual(
+                conn.execute(
+                    "SELECT tag_revision FROM media_annotation_bytes"
+                ).fetchall(),
+                [(2,)],
+            )
+        finally:
+            conn.close()
+
     def test_migration_error_is_logged_and_raised(self):
         # The legacy table has no CHECK on rating; the rebuilt one does, so the
         # copy into prompts_new fails inside the migration.

tests/test_inspection_response.py

@@ -823,6 +823,88 @@ def _png_with_chunks(path, chunks):
     return path
 
 
+class TestVideoProbeBoundsMatchPngBudgets(unittest.TestCase):
+    """ffprobe escapes tag text; the stdout bounds must never gate a record
+    that the identical PNG reads within its decoded budget (I3)."""
+
+    @staticmethod
+    def _dense(size):
+        # Quote-dense JSON text: every other byte escapes, so ffprobe's JSON
+        # output is close to twice the decoded size.
+        unit = '{"k":"v",' + "".join('"' for _ in range(6)) + "}"
+        return (unit * (size // len(unit) + 1))[:size]
+
+    def _video_read(self, path, tags, bound):
+        payload = json.dumps({"format": {"tags": tags}}).encode()
+        self.assertGreater(len(payload), bound)
+        process = MagicMock()
+        process.stdout = io.BytesIO(payload)
+        process.poll.return_value = 0
+        process.returncode = 0
+        with (
+            patch("utils.prompt_inspector.ffprobe_path", return_value="/tool/ffprobe"),
+            patch(
+                "utils.prompt_inspector.subprocess.Popen", return_value=process
+            ) as spawn,
+        ):
+            read = read_inspection_file(path)
+        self.assertEqual(spawn.call_count, 1)
+        self.assertTrue(process.stdout.closed)
+        return read
+
+    def test_near_budget_records_read_the_same_as_png(self):
+        from utils.prompt_inspector import (
+            ROLE_METADATA_BYTES,
+            VIDEO_PROBE_BYTES,
+            VIDEO_REPROBE_BYTES,
+            WORKFLOW_METADATA_BYTES,
+        )
+
+        prompt = self._dense(ROLE_METADATA_BYTES - 1024)
+        workflow = self._dense(WORKFLOW_METADATA_BYTES - 1024)
+        with tempfile.TemporaryDirectory() as directory:
+            png = _png_with_chunks(
+                Path(directory) / "same.png",
+                [
+                    _text_chunk(b"tEXt", "prompt", prompt.encode("latin-1")),
+                    _text_chunk(b"tEXt", "workflow", workflow.encode("latin-1")),
+                ],
+            )
+            expected = read_inspection_file(png)
+            self.assertEqual(
+                expected.record_formats,
+                {"prompt": "original-text", "workflow": "original-text"},
+            )
+            video = Path(directory) / "same.mp4"
+            video.write_bytes(b"fixture")
+            # Escaped output is over the old 6 MiB + 64 KiB stdout bound.
+            read = self._video_read(
+                video,
+                {"prompt": prompt, "workflow": workflow},
+                ROLE_METADATA_BYTES + WORKFLOW_METADATA_BYTES + 64 * 1024,
+            )
+            self.assertEqual(read.metadata, expected.metadata)
+            self.assertEqual(read.record_formats, expected.record_formats)
+            self.assertEqual(read.limited_records, frozenset())
+            self.assertGreaterEqual(
+                VIDEO_PROBE_BYTES,
+                2 * (ROLE_METADATA_BYTES + WORKFLOW_METADATA_BYTES) + 64 * 1024,
+            )
+            self.assertGreaterEqual(
+                VIDEO_REPROBE_BYTES, 2 * ROLE_METADATA_BYTES + 64 * 1024
+            )
+            # A role record near its budget alone escapes past 2 MiB and must
+            # still read as the PNG does.
+            png = _png_with_chunks(
+                Path(directory) / "role.png",
+                [_text_chunk(b"tEXt", "prompt", prompt.encode("latin-1"))],
+            )
+            expected = read_inspection_file(png)
+            read = self._video_read(video, {"prompt": prompt}, ROLE_METADATA_BYTES)
+            self.assertEqual(read.metadata, expected.metadata)
+            self.assertEqual(read.record_formats, {"prompt": "original-text"})
+
+
 class TestPerRecordBudgets(unittest.TestCase):
     """Role records keep the 2 MiB budget; a workflow has its own 4 MiB budget."""
 

tests/test_media_capture.py

@@ -0,0 +1,886 @@
+"""Bounded private capture store (#249 A3): exact bytes, hard limits, cleanup."""
+
+import hashlib
+import os
+import stat
+import struct
+import tempfile
+import threading
+import time
+import unittest
+import zlib
+from pathlib import Path
+from unittest.mock import patch
+
+try:
+    from tests.open_handles import assert_closed, open_handles_under
+except ImportError:  # discovered with tests/ as the top-level directory
+    from open_handles import assert_closed, open_handles_under
+
+try:  # guarded so a missing module fails assertions, not test loading
+    from utils import media_capture as capture_module
+    from utils.media_capture import (
+        CAPTURE_EXTENSIONS,
+        CaptureCapacity,
+        CaptureChanged,
+        CaptureDenied,
+        CaptureStore,
+        CaptureTooLarge,
+    )
+except ImportError:
+    capture_module = None
+    CAPTURE_EXTENSIONS = None
+    CaptureCapacity = CaptureChanged = CaptureDenied = CaptureTooLarge = None
+    CaptureStore = None
+
+EPOCH = "epoch-1"
+SCOPE = "a" * 64
+WAIT = 30.0  # generous ceiling for cross-thread handoffs, never a short clock
+
+
+def _chunk(kind: bytes, data: bytes) -> bytes:
+    return (
+        struct.pack(">I", len(data))
+        + kind
+        + data
+        + struct.pack(">I", zlib.crc32(kind + data))
+    )
+
+
+def png_bytes(width: int, height: int, pixels: bytes = b"\x00" * 16) -> bytes:
+    """A structurally valid PNG whose header declares *width* x *height*."""
+    ihdr = struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0)
+    return (
+        b"\x89PNG\r\n\x1a\n"
+        + _chunk(b"IHDR", ihdr)
+        + _chunk(b"IDAT", pixels)
+        + _chunk(b"IEND", b"")
+    )
+
+
+class FakeClock:
+    def __init__(self, now: float = 1_000.0):
+        self.now = now
+
+    def __call__(self) -> float:
+        return self.now
+
+    def advance(self, seconds: float) -> None:
+        self.now += seconds
+
+
+class CaptureStoreTestCase(unittest.TestCase):
+    def setUp(self):
+        self.assertIsNotNone(capture_module, "utils.media_capture is not implemented")
+        parent = tempfile.TemporaryDirectory()
+        self.addCleanup(parent.cleanup)
+        self.addCleanup(assert_closed, self, parent.name)
+        # The resolved path: macOS /var -> /private/var, Windows 8.3 names.
+        self.parent = Path(os.path.realpath(parent.name))
+        self.root = self.parent / "output"
+        self.root.mkdir()
+        self.clock = FakeClock()
+
+    def make_store(self, **options) -> "CaptureStore":
+        options.setdefault("clock", self.clock)
+        store = CaptureStore(self.parent / "captures", **options)
+        self.addCleanup(store.close)
+        return store
+
+    def write(self, relative: str, data: bytes) -> Path:
+        path = self.root / relative
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(data)
+        return path
+
+    def symlink(self, target, link):
+        try:
+            os.symlink(str(target), str(link))
+        except (OSError, NotImplementedError) as error:
+            self.skipTest(f"symlinks unavailable here: {error}")
+
+    def wait_for_change_time_after(self, ns: int) -> None:
+        """Block until a new file's ``st_ctime_ns`` passes *ns*.
+
+        File timestamps tick coarsely (Linux jiffies, Windows ~1-16 ms). Each
+        probe is a fresh name: Windows reports the creation time (or, on
+        Python 3.12+, the change time) and tunnels the creation time of a
+        reused name for 15 s.
+        """
+        deadline = time.monotonic() + WAIT
+        for index in range(1_000_000):
+            probe = self.parent / f"tick-{index}"
+            probe.write_bytes(b"x")
+            advanced = os.stat(probe).st_ctime_ns > ns
+            probe.unlink()
+            if advanced:
+                return
+            if time.monotonic() >= deadline:
+                break
+            time.sleep(0.001)
+        self.fail("the filesystem clock did not advance")  # pragma: no cover
+
+    def capture(self, store, relative="a.png", **options):
+        options.setdefault("epoch", EPOCH)
+        options.setdefault("scope", SCOPE)
+        return store.capture(self.root, relative, **options)
+
+    def assert_empty(self, store):
+        self.assertFalse(any(Path(store.directory).iterdir()))
+        self.assertEqual(
+            store.stats(), {"captures": 0, "reserved_bytes": 0, "workers": 0}
+        )
+
+    # -- exact bytes and identity -------------------------------------------
+
+    def test_capture_hashes_and_copies_exact_bytes_owner_only(self):
+        source_bytes = png_bytes(3, 2, os.urandom(40))
+        source = self.write("a.png", source_bytes)
+        store = self.make_store()
+
+        cap = self.capture(store, root_index=1)
+
+        self.assertEqual(Path(cap.path).read_bytes(), source_bytes)
+        self.assertEqual(cap.sha256, hashlib.sha256(source_bytes).hexdigest())
+        self.assertEqual(cap.mtime_ns, os.stat(source).st_mtime_ns)
+        self.assertEqual(cap.size, len(source_bytes))
+        self.assertEqual(
+            cap.locator,
+            os.path.normcase(os.path.join(os.path.realpath(self.root), "a.png")),
+        )
+        self.assertEqual((cap.root_index, cap.scope, cap.epoch), (1, SCOPE, EPOCH))
+        self.assertEqual((cap.media_type, cap.width, cap.height), ("image", 3, 2))
+        self.assertTrue(cap.inferable)
+        self.assertIsNone(cap.inferable_reason)
+        self.assertIsInstance(cap.token, str)
+        self.assertGreaterEqual(len(cap.token), 32)
+        self.assertNotIn(cap.token, str(cap.path))
+        self.assertNotIn(str(self.root), str(cap.path))
+        capture_path = Path(cap.path)
+        self.assertEqual(capture_path.parent, Path(store.directory))
+        self.assertEqual(capture_path.suffix, ".png")
+        self.assertTrue(
+            Path(store.directory).name.startswith("prompt-manager-captures-")
+        )
+        if os.name == "posix":
+            self.assertEqual(stat.S_IMODE(os.stat(store.directory).st_mode) & 0o077, 0)
+            self.assertEqual(stat.S_IMODE(os.stat(cap.path).st_mode) & 0o077, 0)
+        self.assertIs(store.get(cap.token), cap)
+        self.assertEqual(
+            store.stats(),
+            {"captures": 1, "reserved_bytes": len(source_bytes), "workers": 0},
+        )
+        self.assertTrue(store.release(cap.token))
+        self.assertFalse(store.release(cap.token))
+        self.assertIsNone(store.get(cap.token))
+        self.assert_empty(store)
+        assert_closed(self, self.parent)
+
+    def test_streams_in_bounded_chunks_never_the_whole_file(self):
+        data = png_bytes(1, 1, os.urandom(5 * capture_module.CHUNK_SIZE + 7))
+        self.write("big.png", data)
+        store = self.make_store(max_file=len(data))
+        sizes = []
+        original = CaptureStore._read
+
+        def hook(store_, stream, size):
+            sizes.append(size)
+            return original(store_, stream, size)
+
+        with patch.object(CaptureStore, "_read", hook):
+            cap = self.capture(store, "big.png")
+        self.assertTrue(sizes)
+        self.assertLessEqual(max(sizes), capture_module.CHUNK_SIZE)
+        self.assertEqual(cap.sha256, hashlib.sha256(data).hexdigest())
+
+    def test_symlinked_file_or_root_escape_is_denied(self):
+        outside = self.parent / "outside"
+        outside.mkdir()
+        (outside / "real.png").write_bytes(png_bytes(1, 1))
+        self.write("a.png", png_bytes(1, 1))
+        self.write("notes.txt", b"text")
+        (self.root / "folder").mkdir()
+        store = self.make_store()
+
+        denied = [
+            "../outside/real.png",
+            "a/../a.png",
+            "./a.png",
+            "a.png/",
+            "",
+            "/a.png",
+            "C:/a.png",
+            "a\\b.png",
+            "a\x00.png",
+            "notes.txt",
+            "folder",
+            "x" * 1021 + ".png",
+        ]
+        for relative in denied:
+            with self.subTest(relative=relative):
+                with self.assertRaises(CaptureDenied):
+                    self.capture(store, relative)
+        with self.assertRaises(CaptureDenied):
+            self.capture(store, "a.png", root_index=True)
+        with self.assertRaises(CaptureChanged):
+            self.capture(store, "missing.png")
+        self.assert_empty(store)
+
+        self.symlink(outside / "real.png", self.root / "link.png")
+        self.symlink(outside, self.root / "linked-dir")
+        with self.assertRaises(CaptureDenied):
+            self.capture(store, "link.png")
+        with self.assertRaises(CaptureDenied):
+            self.capture(store, "linked-dir/real.png")
+        self.assert_empty(store)
+        # A symlink to a file inside the root is still an alias, never a locator.
+        self.symlink(self.root / "a.png", self.root / "alias.png")
+        with self.assertRaises(CaptureDenied):
+            self.capture(store, "alias.png")
+        self.assert_empty(store)
+
+    def test_locator_matches_listing_identity_for_symlinked_root(self):
+        real_root = self.parent / "real-output"
+        real_root.mkdir()
+        (real_root / "sub").mkdir()
+        source_bytes = png_bytes(2, 2)
+        (real_root / "sub" / "a.png").write_bytes(source_bytes)
+        link_root = self.parent / "link-output"
+        self.symlink(real_root, link_root)
+        store = self.make_store()
+
+        cap = store.capture(link_root, "sub/a.png", epoch=EPOCH, scope=SCOPE)
+
+        expected = os.path.normcase(
+            os.path.join(os.path.realpath(link_root), "sub", "a.png")
+        )
+        self.assertEqual(cap.locator, expected)
+        self.assertEqual(
+            cap.locator, os.path.normcase(os.path.realpath(link_root / "sub/a.png"))
+        )
+        self.assertTrue(
+            cap.locator.startswith(os.path.normcase(os.path.realpath(real_root)))
+        )
+        self.assertEqual(cap.sha256, hashlib.sha256(source_bytes).hexdigest())
+
+    # -- change detection ----------------------------------------------------
+
+    def test_change_during_copy_is_detected_and_temp_removed(self):
+        source_bytes = png_bytes(1, 1, b"\x11" * 40)
+        source = self.write("a.png", source_bytes)
+        store = self.make_store(max_file=4096)
+        original = CaptureStore._read
+
+        def appending(store_, stream, size):
+            data = original(store_, stream, 16)
+            if data and not getattr(appending, "done", False):
+                appending.done = True
+                with open(source, "ab") as handle:
+                    handle.write(b"\x22" * 8)
+            return data
+
+        with patch.object(CaptureStore, "_read", appending):
+            with self.assertRaises(CaptureChanged):
+                store.capture(self.root, "a.png", epoch=EPOCH, scope=SCOPE)
+        self.assert_empty(store)
+
+        # Same size, different bytes, mtime restored: only the change time
+        # (POSIX ctime) can tell. Windows exposes no change time through stat,
+        # so there the torn copy completes and its digest describes the copy.
+        source.write_bytes(source_bytes)
+        before = os.stat(source)
+        self.wait_for_change_time_after(before.st_ctime_ns)
+        rewritten = bytes(b ^ 0xFF for b in source_bytes)
+
+        def rewriting(store_, stream, size):
+            data = original(store_, stream, 16)
+            if data and not getattr(rewriting, "done", False):
+                rewriting.done = True
+                with open(source, "r+b") as handle:
+                    handle.write(rewritten)
+                os.utime(source, ns=(before.st_atime_ns, before.st_mtime_ns))
+            return data
+
+        # Only a change time can tell: POSIX always has one; Windows exposes
+        # it from stat on Python 3.12+ (where the OS supports the fast path)
+        # and never from fstat, so detection there is best effort. The test
+        # asserts the outcome, not the platform: a detected change leaves no
+        # temp file; an undetected one (Windows only) completes with a digest
+        # that describes the copied bytes.
+        with patch.object(CaptureStore, "_read", rewriting):
+            try:
+                cap = store.capture(self.root, "a.png", epoch=EPOCH, scope=SCOPE)
+            except CaptureChanged:
+                detected = True
+            else:
+                detected = False
+                self.assertEqual(os.name, "nt", "only Windows may miss the rewrite")
+                copied = Path(cap.path).read_bytes()
+                self.assertEqual(cap.sha256, hashlib.sha256(copied).hexdigest())
+                store.release(cap.token)
+        if os.name == "posix":
+            self.assertTrue(detected)
+        self.assert_empty(store)
+        self.assertEqual(os.stat(source).st_mtime_ns, before.st_mtime_ns)
+
+        if os.name == "posix":
+            # The path now names another file (new inode) once the copy ends.
+            source.write_bytes(source_bytes)
+
+            def replacing(store_, stream, size):
+                data = original(store_, stream, size)
+                if not data and not getattr(replacing, "done", False):
+                    replacing.done = True
+                    other = self.root / "other.png"
+                    other.write_bytes(source_bytes)
+                    os.replace(other, source)
+                return data
+
+            with patch.object(CaptureStore, "_read", replacing):
+                with self.assertRaises(CaptureChanged):
+                    store.capture(self.root, "a.png", epoch=EPOCH, scope=SCOPE)
+            self.assert_empty(store)
+        assert_closed(self, self.parent)
+
+    def test_size_cap_on_stat_and_stream(self):
+        store = self.make_store(max_file=64)
+        self.write("large.png", bytes(65))
+        self.write("fits.png", bytes(64))
+
+        def never(store_, stream, size):  # pragma: no cover - guard only
+            raise AssertionError("an over-cap file must not be read")
+
+        with patch.object(CaptureStore, "_read", never):
+            with self.assertRaises(CaptureTooLarge):
+                self.capture(store, "large.png")
+        self.assert_empty(store)
+
+        cap = self.capture(store, "fits.png")
+        self.assertEqual(cap.size, 64)
+        store.release(cap.token)
+
+        growing = self.write("growing.png", bytes(40))
+        original = CaptureStore._read
+
+        def grow(store_, stream, size):
+            data = original(store_, stream, 16)
+            if data and not getattr(grow, "done", False):
+                grow.done = True
+                with open(growing, "ab") as handle:
+                    handle.write(bytes(40))
+            return data
+
+        with patch.object(CaptureStore, "_read", grow):
+            with self.assertRaises(CaptureTooLarge):
+                self.capture(store, "growing.png")
+        self.assert_empty(store)
+
+    # -- admission -----------------------------------------------------------
+
+    def test_count_byte_and_worker_admission_is_nonblocking(self):
+        for name in ("a", "b", "c"):
+            self.write(f"{name}.png", bytes(60))
+        store = self.make_store(max_captures=2, max_bytes=1000)
+        first = self.capture(store, "a.png")
+        self.capture(store, "b.png")
+        with self.assertRaises(CaptureCapacity):
+            self.capture(store, "c.png")
+        self.assertTrue(store.release(first.token))
+        third = self.capture(store, "c.png")
+        self.assertEqual(store.stats()["captures"], 2)
+        store.invalidate_all()
+        self.assertIsNone(store.get(third.token))
+        self.assert_empty(store)
+
+        bytes_store = self.make_store(max_bytes=100)
+        kept = self.capture(bytes_store, "a.png")
+        with self.assertRaises(CaptureCapacity):
+            self.capture(bytes_store, "b.png")
+        self.assertEqual(bytes_store.stats()["reserved_bytes"], 60)
+        bytes_store.release(kept.token)
+        self.capture(bytes_store, "b.png")
+
+        workers = self.make_store(max_workers=1)
+        entered, proceed = threading.Event(), threading.Event()
+        original = CaptureStore._read
+        results = {}
+
+        def blocking(store_, stream, size):
+            if not entered.is_set():
+                entered.set()
+                self.assertTrue(proceed.wait(WAIT))
+            return original(store_, stream, size)
+
+        def worker():
+            try:
+                results["capture"] = self.capture(workers, "a.png")
+            except Exception as error:  # pragma: no cover - reported below
+                results["error"] = error
+
+        with patch.object(CaptureStore, "_read", blocking):
+            thread = threading.Thread(target=worker)
+            thread.start()
+            try:
+                self.assertTrue(entered.wait(WAIT))
+                self.assertEqual(workers.stats()["workers"], 1)
+                with self.assertRaises(CaptureCapacity):
+                    self.capture(workers, "b.png")
+            finally:
+                proceed.set()
+                thread.join(WAIT)
+        self.assertFalse(thread.is_alive())
+        self.assertNotIn("error", results)
+        self.assertEqual(workers.stats()["workers"], 0)
+        self.assertEqual(results["capture"].size, 60)
+        self.capture(workers, "b.png")
+
+    # -- lifetime ------------------------------------------------------------
+
+    def test_idle_and_hard_expiry_and_in_use_retention(self):
+        self.write("a.png", png_bytes(1, 1))
+        self.write("b.png", png_bytes(1, 1))
+        store = self.make_store(idle=900, hard=1800)
+        cap = self.capture(store, "a.png")
+
+        self.clock.advance(899)
+        self.assertIs(store.get(cap.token), cap)  # touches idle
+        self.assertAlmostEqual(store.expires_in(cap.token), 900)
+        self.clock.advance(899)
+        self.assertIs(store.get(cap.token), cap)
+        self.assertAlmostEqual(store.expires_in(cap.token), 2)
+        self.clock.advance(2)
+        self.assertIsNone(store.get(cap.token))  # hard limit despite touches
+        self.assertIsNone(store.expires_in(cap.token))
+        self.assertFalse(Path(cap.path).exists())
+        self.assert_empty(store)
+
+        idle = self.capture(store, "a.png")
+        self.clock.advance(900)
+        store.sweep()
+        self.assertIsNone(store.get(idle.token))
+        self.assert_empty(store)
+
+        used = self.capture(store, "b.png")
+        self.assertIs(store.acquire(used.token), used)
+        self.assertIs(store.acquire(used.token), used)
+        self.clock.advance(901)
+        store.sweep()
+        self.assertIs(store.get(used.token), used)  # in use is not idle
+        self.clock.advance(900)
+        store.sweep()
+        self.assertIsNone(store.get(used.token))  # expired for new requests
+        self.assertIsNone(store.acquire(used.token))
+        self.assertTrue(Path(used.path).exists())  # retained while in use
+        self.assertEqual(store.stats()["captures"], 1)
+        store.release_use(used.token)
+        self.assertTrue(Path(used.path).exists())
+        store.release_use(used.token)
+        self.assertFalse(Path(used.path).exists())
+        self.assert_empty(store)
+        store.release_use(used.token)  # unknown token: no error, nothing freed
+        self.assertIsNone(store.acquire("unknown"))
+
+    def test_release_while_in_use_keeps_file_until_last_use_ends(self):
+        self.write("a.png", png_bytes(1, 1))
+        store = self.make_store()
+        cap = self.capture(store, "a.png")
+        self.assertIs(store.acquire(cap.token), cap)
+        self.assertTrue(store.release(cap.token))
+        self.assertIsNone(store.get(cap.token))
+        self.assertTrue(Path(cap.path).exists())
+        store.invalidate_all()
+        self.assertTrue(Path(cap.path).exists())
+        store.release_use(cap.token)
+        self.assertFalse(Path(cap.path).exists())
+        self.assert_empty(store)
+
+    def test_invalidate_all_and_close_remove_owned_directory_only(self):
+        self.write("a.png", png_bytes(1, 1))
+        self.write("b.png", png_bytes(1, 1))
+        sibling = self.parent / "captures" / "sibling.txt"
+        sibling.parent.mkdir()
+        sibling.write_bytes(b"keep")
+        store = CaptureStore(self.parent / "captures", clock=self.clock)
+        try:
+            a = self.capture(store, "a.png")
+            b = self.capture(store, "b.png")
+            self.assertEqual(Path(store.directory).parent, sibling.parent)
+            store.invalidate_all()
+            self.assertIsNone(store.get(a.token))
+            self.assertIsNone(store.get(b.token))
+            self.assert_empty(store)
+            self.assertTrue(Path(store.directory).is_dir())
+            c = self.capture(store, "a.png")
+            self.assertTrue(Path(c.path).exists())
+        finally:
+            store.close()
+        self.assertFalse(Path(store.directory).exists())
+        self.assertEqual(sibling.read_bytes(), b"keep")
+        self.assertTrue((self.root / "a.png").exists())
+        store.close()  # idempotent
+        with self.assertRaises(RuntimeError):
+            self.capture(store, "a.png")
+        self.assertIsNone(store.get(c.token))
+        assert_closed(self, self.parent)
+
+    def test_windows_handles_closed_before_unlink(self):
+        source_bytes = png_bytes(1, 1, b"\x33" * 40)
+        source = self.write("a.png", source_bytes)
+        store = self.make_store()
+        original_unlink = os.unlink
+        unlinked = []
+
+        def checked_unlink(path, *args, **kwargs):
+            self.assertEqual(open_handles_under(path), [])
+            self.assertTrue(store._lock.acquire(blocking=False))  # no I/O under lock
+            store._lock.release()
+            unlinked.append(os.fspath(path))
+            return original_unlink(path, *args, **kwargs)
+
+        with patch("os.unlink", checked_unlink):
+            cap = self.capture(store, "a.png")
+            self.assertEqual(open_handles_under(cap.path), [])
+            self.assertEqual(open_handles_under(source), [])
+            store.release(cap.token)
+            original = CaptureStore._read
+
+            def appending(store_, stream, size):
+                data = original(store_, stream, 16)
+                if data and not getattr(appending, "done", False):
+                    appending.done = True
+                    with open(source, "ab") as handle:
+                        handle.write(b"\x44")
+                return data
+
+            with patch.object(CaptureStore, "_read", appending):
+                with self.assertRaises(CaptureChanged):
+                    self.capture(store, "a.png")
+            self.assertEqual(open_handles_under(source), [])
+        self.assertEqual(len(unlinked), 2)
+        self.assertTrue(all(p.startswith(str(store.directory)) for p in unlinked))
+        self.assert_empty(store)
+        assert_closed(self, self.parent)
+
+    # -- inference readiness -------------------------------------------------
+
+    def test_dimension_limits_mark_generate_unsupported(self):
+        cases = {
+            "edge.png": (png_bytes(4096, 4096), True),
+            "wide.png": (png_bytes(4097, 1), False),
+            "tall.png": (png_bytes(1, 4097), False),
+        }
+        for name, (data, _) in cases.items():
+            self.write(name, data)
+        self.write("garbage.jpg", b"\xff\xd8not really a jpeg")
+        store = self.make_store()
+
+        for name, (data, supported) in cases.items():
+            with self.subTest(name=name):
+                cap = self.capture(store, name)
+                self.assertEqual(cap.inferable, supported)
+                self.assertEqual((cap.width, cap.height) != (None, None), True)
+                if supported:
+                    self.assertIsNone(cap.inferable_reason)
+                else:
+                    self.assertIn("4096", cap.inferable_reason)
+                store.release(cap.token)
+        self.assertEqual(
+            (capture_module.MAX_INFERENCE_SIDE, capture_module.MAX_INFERENCE_PIXELS),
+            (4096, 16_777_216),
+        )
+        cap = self.capture(store, "garbage.jpg")
+        self.assertEqual((cap.media_type, cap.width, cap.height), ("image", None, None))
+        self.assertFalse(cap.inferable)
+        self.assertIn("header", cap.inferable_reason)
+        self.assertEqual(
+            cap.sha256, hashlib.sha256(b"\xff\xd8not really a jpeg").hexdigest()
+        )
+
+    def test_video_capture_is_not_inferable(self):
+        data = b"\x00\x00\x00\x18ftypmp42" + os.urandom(32)
+        self.write("clip.mp4", data)
+        store = self.make_store()
+
+        def never(path):  # pragma: no cover - guard only
+            raise AssertionError("video captures are never probed")
+
+        with patch.object(capture_module, "read_inspection_file", never):
+            cap = self.capture(store, "clip.mp4")
+        self.assertEqual((cap.media_type, cap.width, cap.height), ("video", None, None))
+        self.assertFalse(cap.inferable)
+        self.assertEqual(
+            cap.inferable_reason,
+            "Auto-tagging is available for supported still images only.",
+        )
+        self.assertEqual(Path(cap.path).suffix, ".mp4")
+        self.assertEqual(cap.sha256, hashlib.sha256(data).hexdigest())
+
+    # -- verification without a copy -------------------------------------
+
+    def test_verify_hashes_current_file_without_retaining_a_copy(self):
+        source_bytes = png_bytes(1, 1, b"\x55" * 30)
+        source = self.write("a.png", source_bytes)
+        store = self.make_store(max_file=128, max_workers=1)
+
+        facts = store.verify(self.root, "a.png")
+
+        self.assertEqual(facts.sha256, hashlib.sha256(source_bytes).hexdigest())
+        self.assertEqual(facts.size, len(source_bytes))
+        self.assertEqual(facts.mtime_ns, os.stat(source).st_mtime_ns)
+        self.assertEqual(
+            facts.locator,
+            os.path.normcase(os.path.join(os.path.realpath(self.root), "a.png")),
+        )
+        self.assert_empty(store)
+        self.write("large.png", bytes(129))
+        with self.assertRaises(CaptureTooLarge):
+            store.verify(self.root, "large.png")
+        with self.assertRaises(CaptureDenied):
+            store.verify(self.root, "../a.png")
+        self.assert_empty(store)
+
+    # -- arguments and failure paths ---------------------------------------
+
+    def test_constructor_and_arguments_are_validated(self):
+        for options in (
+            {"max_file": 0},
+            {"max_captures": True},
+            {"max_bytes": -1},
+            {"max_workers": "2"},
+            {"idle": 0},
+            {"hard": -5},
+        ):
+            with self.subTest(options=options):
+                with self.assertRaises(ValueError):
+                    CaptureStore(self.parent / "captures", **options)
+        self.write("a.png", png_bytes(1, 1))
+        store = self.make_store()
+        with self.assertRaises(ValueError):
+            store.capture(self.root, "a.png", epoch="", scope=SCOPE)
+        with self.assertRaises(ValueError):
+            store.capture(self.root, "a.png", epoch=EPOCH, scope=None)
+        with self.assertRaises(CaptureDenied):
+            self.capture(store, root_index=-1)
+        with self.assertRaises(CaptureDenied):
+            store.capture(
+                self.parent / "missing-root", "a.png", epoch=EPOCH, scope=SCOPE
+            )
+        self.assert_empty(store)
+
+        default = CaptureStore(clock=self.clock)
+        try:
+            self.assertEqual(
+                Path(default.directory).parent, Path(tempfile.gettempdir())
+            )
+            self.assertTrue(Path(default.directory).is_dir())
+        finally:
+            default.close()
+        self.assertFalse(Path(default.directory).exists())
+
+    def test_directory_target_and_unreadable_file(self):
+        (self.root / "dir.png").mkdir()
+        store = self.make_store()
+        with self.assertRaises(CaptureDenied):
+            self.capture(store, "dir.png")
+        self.assert_empty(store)
+        if os.name != "posix" or os.geteuid() == 0:
+            return  # read permission cannot be withdrawn here
+        locked = self.write("locked.png", png_bytes(1, 1))
+        os.chmod(locked, 0)
+        try:
+            with self.assertRaises(CaptureChanged):
+                self.capture(store, "locked.png")
+        finally:
+            os.chmod(locked, 0o600)
+        self.assert_empty(store)
+
+    def test_removal_failures_are_logged_and_never_touch_other_files(self):
+        self.write("a.png", png_bytes(1, 1))
+        store = CaptureStore(self.parent / "captures", clock=self.clock)
+        stray = Path(store.directory) / "stray.bin"
+        try:
+            cap = self.capture(store, "a.png")
+            self.assertIs(store.acquire(cap.token), cap)
+            self.assertAlmostEqual(store.expires_in(cap.token), 1800)  # in use
+            store.release_use(cap.token)
+            original_unlink = os.unlink
+
+            def failing(path, *args, **kwargs):
+                if os.fspath(path) == cap.path:
+                    raise PermissionError("busy")
+                return original_unlink(path, *args, **kwargs)
+
+            with patch("os.unlink", failing):
+                with self.assertLogs("utils.media_capture", "WARNING") as logs:
+                    self.assertTrue(store.release(cap.token))
+            self.assertIn("could not be removed", logs.output[0])
+            self.assertIsNone(store.get(cap.token))
+            self.assertTrue(Path(cap.path).exists())
+            os.unlink(cap.path)
+            stray.write_bytes(b"not ours")
+        finally:
+            with self.assertLogs("utils.media_capture", "WARNING") as logs:
+                store.close()
+        self.assertIn("could not be removed", logs.output[0])
+        self.assertEqual(stray.read_bytes(), b"not ours")
+        stray.unlink()
+        os.rmdir(store.directory)
+        assert_closed(self, self.parent)
+
+    # -- platform identity checks -------------------------------------------
+
+    def test_path_and_handle_stats_are_never_compared_across_apis(self):
+        """Windows (Python 3.12+) reports the change time from stat but the
+        creation time from fstat, and may encode dev/ino differently; only
+        size and mtime_ns may be compared across the two APIs."""
+        source_bytes = png_bytes(2, 2, b"\x66" * 40)
+        self.write("a.png", source_bytes)
+        store = self.make_store()
+        original_fstat = os.fstat
+
+        def shifted(fd):
+            st = original_fstat(fd)
+            return os.stat_result(
+                (
+                    st.st_mode,
+                    st.st_ino + 7,
+                    st.st_dev + 7,
+                    st.st_nlink,
+                    st.st_uid,
+                    st.st_gid,
+                    st.st_size,
+                    st.st_atime,
+                    st.st_mtime,
+                    st.st_ctime + 1,
+                ),
+                {
+                    "st_atime_ns": st.st_atime_ns,
+                    "st_mtime_ns": st.st_mtime_ns,
+                    "st_ctime_ns": st.st_ctime_ns + 1_000_000_000,
+                },
+            )
+
+        with patch.object(capture_module.os, "fstat", shifted):
+            cap = self.capture(store, "a.png")
+            facts = store.verify(self.root, "a.png")
+        self.assertEqual(cap.sha256, hashlib.sha256(source_bytes).hexdigest())
+        self.assertEqual(facts.sha256, cap.sha256)
+        store.release(cap.token)
+        self.assert_empty(store)
+
+    def test_change_time_moving_between_fstat_reads_is_detected(self):
+        """The Windows 3.13 / POSIX signal, forced on every platform: the
+        descriptor's change time differs after the copy, size and mtime equal."""
+        self.write("a.png", png_bytes(1, 1, b"\x77" * 40))
+        store = self.make_store()
+        original_fstat = os.fstat
+        calls = []
+
+        def drifting(fd):
+            st = original_fstat(fd)
+            calls.append(fd)
+            if len(calls) < 2:
+                return st
+            return os.stat_result(
+                tuple(st)[:10],
+                {
+                    "st_atime_ns": st.st_atime_ns,
+                    "st_mtime_ns": st.st_mtime_ns,
+                    "st_ctime_ns": st.st_ctime_ns + 1,
+                },
+            )
+
+        with patch.object(capture_module.os, "fstat", drifting):
+            with self.assertRaises(CaptureChanged):
+                self.capture(store, "a.png")
+        self.assertEqual(len(calls), 2)
+        self.assert_empty(store)
+
+    def test_fresh_file_captures_twice_on_every_platform(self):
+        data = png_bytes(1, 1, os.urandom(3 * capture_module.CHUNK_SIZE))
+        self.write("fresh.png", data)
+        store = self.make_store()
+        first = self.capture(store, "fresh.png")
+        second = self.capture(store, "fresh.png")
+        self.assertEqual(first.sha256, hashlib.sha256(data).hexdigest())
+        self.assertEqual(second.sha256, first.sha256)
+        self.assertNotEqual(first.token, second.token)
+        self.assertEqual(store.stats()["captures"], 2)
+
+    def test_error_messages_never_name_server_paths(self):
+        self.write("a.png", png_bytes(1, 1))
+        self.write("dir.png/x", b"")  # dir.png is a directory
+        store = self.make_store(max_file=64)
+        attempts = [
+            lambda: self.capture(store, "missing.png"),
+            lambda: self.capture(store, "a.png"),  # over the 64-byte cap
+            lambda: self.capture(store, "dir.png"),
+            lambda: self.capture(store, "../a.png"),
+            lambda: self.capture(store, "notes.txt"),
+            lambda: store.verify(self.root, "missing.png"),
+        ]
+        if os.name == "posix" and os.geteuid() != 0:
+            locked = self.write("locked.png", bytes(10))
+            os.chmod(locked, 0)
+            self.addCleanup(os.chmod, locked, 0o600)
+            attempts.append(lambda: self.capture(store, "locked.png"))
+        for attempt in attempts:
+            with self.assertRaises(capture_module.CaptureError) as caught:
+                attempt()
+            message = str(caught.exception)
+            self.assertTrue(message)
+            self.assertNotIn(str(self.root), message)
+            self.assertNotIn(str(self.parent), message)
+            self.assertNotIn(os.sep, message)
+        self.assert_empty(store)
+
+    def test_close_during_a_capture_removes_the_directory_once_it_finishes(self):
+        self.write("a.png", png_bytes(1, 1, bytes(64)))
+        store = CaptureStore(self.parent / "captures", clock=self.clock)
+        original = CaptureStore._read
+
+        def closing(store_, stream, size):
+            data = original(store_, stream, 16)
+            if data and not getattr(closing, "done", False):
+                closing.done = True
+                store.close()
+            return data
+
+        with patch.object(CaptureStore, "_read", closing):
+            with self.assertRaises(RuntimeError):
+                self.capture(store, "a.png")
+        self.assertFalse(Path(store.directory).exists())
+        self.assertEqual(store.stats()["reserved_bytes"], 0)
+        store.close()
+        assert_closed(self, self.parent)
+
+    # -- constants ---------------------------------------------------------
+
+    def test_defaults_match_the_plan(self):
+        store = self.make_store()
+        self.assertEqual(
+            (
+                store.max_file,
+                store.max_captures,
+                store.max_bytes,
+                store.max_workers,
+                store.idle,
+                store.hard,
+            ),
+            (256 * 2**20, 8, 512 * 2**20, 2, 900, 1800),
+        )
+        from py.api.inspection_service import SERVABLE_EXTENSIONS
+
+        self.assertEqual(CAPTURE_EXTENSIONS, SERVABLE_EXTENSIONS)
+
+    def test_exceptions_carry_codes(self):
+        self.assertEqual(CaptureCapacity.code, "review-capacity")
+        self.assertEqual(CaptureChanged.code, "file-changed")
+        self.assertEqual(CaptureTooLarge.code, "unsupported-media")
+        self.assertEqual(CaptureDenied.code, "source-changed")
+        for cls in (CaptureCapacity, CaptureChanged, CaptureTooLarge, CaptureDenied):
+            self.assertTrue(issubclass(cls, capture_module.CaptureError))
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_pair_schema_restore.py

@@ -251,7 +251,19 @@ class PairSchemaTests(unittest.TestCase):
                 [r[1] for r in conn.execute("PRAGMA table_info(prompt_library_state)")],
                 ["prompt_id", "title"],
             )
+            self.assertEqual(
+                [
+                    tuple(r)
+                    for r in conn.execute("SELECT * FROM media_annotation_metadata")
+                ],
+                [(1, 1, 0)],
+            )
         self.assertTrue(PromptModel.verify_database_file(live.db_path)[0])
+        self.assertTrue(
+            PromptModel.verify_database_file(live.db_path, require_library_state=True)[
+                0
+            ]
+        )
 
     def test_restore_staged_verification_failure_does_not_replace_live_pages(self):
         live = self.model()

tests/test_pair_tag_maintenance.py

@@ -1,5 +1,6 @@
 """Global tag maintenance preserves pair and standalone tag relationships."""
 
+import hashlib
 import os
 import sqlite3
 import tempfile
@@ -10,6 +11,7 @@ try:
 except ImportError:  # discovered with tests/ as the top-level directory
     from open_handles import assert_closed
 
+from database.library_commands import LibraryCommandError
 from database.operations import PromptDatabase
 
 
@@ -18,6 +20,7 @@ class TestPairTagMaintenance(unittest.TestCase):
         directory = tempfile.TemporaryDirectory()
         self.addCleanup(directory.cleanup)
         self.addCleanup(assert_closed, self, directory.name)
+        self.root = directory.name
         self.db = PromptDatabase(os.path.join(directory.name, "pair-tags.db"))
         self.addCleanup(self.db.close_all)
 
@@ -27,6 +30,36 @@ class TestPairTagMaintenance(unittest.TestCase):
     def tags(self, pair_id: int) -> list:
         return self.db.get_prompt_pair(pair_id)["tags"]
 
+    def image(self, name: str, tags: list, digest: str = "a", revision: int = 0):
+        """Tag the bytes ``digest`` of the file ``name``; return its locator."""
+        locator = os.path.normcase(os.path.join(os.path.realpath(self.root), name))
+        replace = getattr(self.db, "replace_image_tags", None)
+        self.assertTrue(callable(replace), "replace_image_tags is missing")
+        replace(
+            locator=locator,
+            sha256=hashlib.sha256(digest.encode()).hexdigest(),
+            size=1,
+            mtime_ns=1,
+            expected_epoch=self.db.get_execution_epoch(),
+            expected_tag_revision=revision,
+            tags=tags,
+        )
+        return locator
+
+    def image_tags(self, locator: str, digest: str = "a") -> list:
+        return self.db.read_image_tags(
+            locator, hashlib.sha256(digest.encode()).hexdigest()
+        )["tags"]
+
+    def image_rows(self) -> list:
+        conn = self.db.model.get_connection()
+        return [
+            tuple(row)
+            for row in conn.execute(
+                "SELECT byte_id, tag_id, position FROM media_image_tags ORDER BY 1,3"
+            )
+        ]
+
     def test_rename_to_existing_tag_preserves_pair_links_and_deduplicates(self):
         first = self.pair("portrait", ["old", "new", "keep"])
         second = self.pair("landscape", ["old"])
@@ -136,6 +169,207 @@ class TestPairTagMaintenance(unittest.TestCase):
         self.assertEqual(self.tags(other), ["source"])
         self.assertEqual(self.db.get_prompt_by_id(prompt)["tags"], ["source"])
 
+    def test_rename_and_merge_move_image_links_with_dedup(self):
+        pair = self.pair("portrait", ["old", "new"])
+        both = self.image("both.png", ["new", "old", "keep"])
+        only_old = self.image("old.png", ["old"])
+        result = self.db.rename_tag_all_prompts("old", "new")
+        self.assertEqual(result["affected_count"], 0)  # prompts only, as before
+        self.assertEqual(self.tags(pair), ["new"])
+        self.assertEqual(self.image_tags(both), ["new", "keep"])
+        self.assertEqual(self.image_tags(only_old), ["new"])
+        self.assertNotIn("old", self.db.get_all_tags())
+        self.db.rename_tag_all_prompts("keep", "kept")
+        self.assertEqual(self.image_tags(both), ["new", "kept"])
+        merged = self.db.merge_tags(["kept", "new"], "final")
+        self.assertEqual(merged["tags_merged"], 2)
+        self.assertEqual(merged["affected_count"], 0)
+        self.assertEqual(self.image_tags(both), ["final"])
+        self.assertEqual(self.image_tags(only_old), ["final"])
+        self.assertEqual(self.tags(pair), ["final"])
+        epoch = self.db.get_execution_epoch()
+        conn = self.db.model.get_connection()
+        final = conn.execute("SELECT id FROM tags WHERE name='final'").fetchone()[0]
+        native = self.db.rename_vocabulary_tag(
+            final, expected_epoch=epoch, name="final", new_name="native"
+        )
+        self.assertEqual(native["images_changed"], 2)
+        self.assertEqual(self.image_tags(both), ["native"])
+        self.assertEqual(self.image_tags(only_old), ["native"])
+        self.image("again.png", ["native", "merge-me"])
+        source = conn.execute("SELECT id FROM tags WHERE name='merge-me'").fetchone()
+        receipt = self.db.rename_vocabulary_tag(
+            source[0], expected_epoch=epoch, name="merge-me", new_name="native"
+        )
+        self.assertTrue(receipt["merged"])
+        self.assertEqual(receipt["images_changed"], 1)
+        self.assertEqual(receipt["tag"]["image_count"], 3)
+        self.assertEqual(len(self.image_rows()), 3)
+
+    def test_delete_cascades_image_links_and_keeps_legacy_counts(self):
+        pair = self.pair("portrait", ["remove", "keep"])
+        prompt = self.db.save_prompt("standalone", tags=["remove", "keep"])
+        locator = self.image("a.png", ["keep", "remove"])
+        result = self.db.delete_tag_all_prompts("remove")
+        self.assertEqual(result["affected_count"], 1)
+        self.assertEqual(self.tags(pair), ["keep"])
+        self.assertEqual(self.db.get_prompt_by_id(prompt)["tags"], ["keep"])
+        self.assertEqual(self.image_tags(locator), ["keep"])
+        self.assertEqual(len(self.image_rows()), 1)
+        epoch = self.db.get_execution_epoch()
+        conn = self.db.model.get_connection()
+        keep = conn.execute("SELECT id FROM tags WHERE name='keep'").fetchone()[0]
+        impact = self.db.vocabulary_tag_impact(keep)["impact"]
+        self.assertEqual(impact["images"], 1)
+        deleted = self.db.delete_vocabulary_tag(keep, expected_epoch=epoch, name="keep")
+        self.assertEqual(
+            (
+                deleted["components_changed"],
+                deleted["pairs_changed"],
+                deleted["images_changed"],
+            ),
+            (1, 1, 1),
+        )
+        self.assertEqual(self.image_tags(locator), [])
+        self.assertEqual(self.image_rows(), [])
+        self.assertEqual(
+            conn.execute("SELECT COUNT(*) FROM media_annotation_bytes").fetchone()[0], 1
+        )
+
+    def index_revision(self) -> int:
+        return (
+            self.db.model.get_connection()
+            .execute("SELECT image_index_revision FROM media_annotation_metadata")
+            .fetchone()[0]
+        )
+
+    def revision(self, locator: str, digest: str = "a") -> int:
+        return self.db.read_image_tags(
+            locator, hashlib.sha256(digest.encode()).hexdigest()
+        )["tag_revision"]
+
+    def tag_id(self, name: str) -> int:
+        conn = self.db.model.get_connection()
+        return conn.execute("SELECT id FROM tags WHERE name=?", (name,)).fetchone()[0]
+
+    def test_vocabulary_maintenance_bumps_image_revisions_so_stale_saves_conflict(
+        self,
+    ):
+        forest = self.image("a.png", ["forest"])
+        misty = self.image("b.png", ["mist"])
+        self.pair("portrait", ["unlinked"])
+        index = self.index_revision()
+        epoch = self.db.get_execution_epoch()
+
+        # A rename of a tag no image carries moves nothing image-side.
+        self.db.rename_vocabulary_tag(
+            self.tag_id("unlinked"), expected_epoch=epoch, name="unlinked", new_name="u"
+        )
+        self.assertEqual(self.index_revision(), index)
+
+        self.db.rename_vocabulary_tag(
+            self.tag_id("forest"), expected_epoch=epoch, name="forest", new_name="woods"
+        )
+        self.assertEqual(self.image_tags(forest), ["woods"])
+        self.assertEqual((self.revision(forest), self.revision(misty)), (2, 1))
+        self.assertEqual(self.index_revision(), index + 1)
+        # The Tag dialog still open at revision 1 cannot recreate "forest".
+        with self.assertRaises(LibraryCommandError) as caught:
+            self.db.replace_image_tags(
+                locator=forest,
+                sha256=hashlib.sha256(b"a").hexdigest(),
+                size=1,
+                mtime_ns=1,
+                expected_epoch=epoch,
+                expected_tag_revision=1,
+                tags=["forest", "mist"],
+            )
+        self.assertEqual(caught.exception.code, "tag-conflict")
+        self.assertEqual(caught.exception.current["tags"], ["woods"])
+        self.assertEqual(caught.exception.current["tag_revision"], 2)
+        self.assertNotIn("forest", self.db.get_all_tags())
+
+        self.db.rename_tag_all_prompts("woods", "trees")  # legacy rename
+        self.assertEqual((self.revision(forest), self.revision(misty)), (3, 1))
+        self.db.merge_tags(["trees"], "mist")  # legacy merge: only the source side
+        self.assertEqual(self.image_tags(forest), ["mist"])
+        self.assertEqual((self.revision(forest), self.revision(misty)), (4, 1))
+        self.db.rename_tag_all_prompts("mist", "fog")  # both carry it now
+        self.assertEqual((self.revision(forest), self.revision(misty)), (5, 2))
+        self.db.delete_vocabulary_tag(
+            self.tag_id("fog"), expected_epoch=epoch, name="fog"
+        )
+        self.assertEqual((self.revision(forest), self.revision(misty)), (6, 3))
+        self.assertEqual((self.image_tags(forest), self.image_tags(misty)), ([], []))
+        self.image("c.png", ["gone"])
+        self.db.delete_tag_all_prompts("gone")  # legacy delete
+        self.assertEqual(self.revision(forest), 6)
+        self.assertEqual(
+            self.index_revision(), index + 7
+        )  # 6 maintenance ops + the c.png save
+
+    def test_image_only_and_prior_only_names_participate(self):
+        only = self.image("only.png", ["image-only"])
+        prior = self.image("prior.png", ["prior-only"], digest="old")
+        self.image("prior.png", [], digest="new")  # the file's bytes changed
+        self.db.save_prompt("standalone", tags=["target"])
+        merged = self.db.merge_tags(["image-only"], "target")
+        self.assertEqual((merged["tags_merged"], merged["affected_count"]), (1, 0))
+        self.assertEqual(self.image_tags(only), ["target"])
+        self.assertEqual(
+            self.db.rename_tag_all_prompts("prior-only", "renamed")["affected_count"], 0
+        )
+        self.assertEqual(self.image_tags(prior, "old"), ["renamed"])
+        self.assertEqual(self.image_tags(prior, "new"), [])
+        self.assertEqual(set(self.db.get_all_tags()), {"target", "renamed"})
+        epoch = self.db.get_execution_epoch()
+        conn = self.db.model.get_connection()
+        renamed = conn.execute("SELECT id FROM tags WHERE name='renamed'").fetchone()[0]
+        receipt = self.db.rename_vocabulary_tag(
+            renamed, expected_epoch=epoch, name="renamed", new_name="target"
+        )
+        self.assertTrue(receipt["merged"])
+        self.assertEqual(receipt["images_changed"], 1)
+        self.assertEqual(self.image_tags(prior, "old"), ["target"])
+        self.assertEqual(receipt["tag"]["image_count"], 2)
+
+    def test_image_junction_failure_rolls_back_prompt_pair_and_name_changes(self):
+        pair = self.pair("portrait", ["source", "target"])
+        prompt = self.db.save_prompt("standalone", tags=["source"])
+        locator = self.image("a.png", ["source"])
+        conn = self.db.model.get_connection()
+        tables = ("tags", "prompt_tags", "prompt_pair_tags", "media_image_tags")
+        before = [
+            conn.execute(f"SELECT * FROM {table} ORDER BY 1,2").fetchall()
+            for table in tables
+        ]
+        source = conn.execute("SELECT id FROM tags WHERE name='source'").fetchone()[0]
+        conn.execute(
+            "CREATE TRIGGER reject_image_tag_change BEFORE UPDATE "
+            "ON media_image_tags BEGIN SELECT RAISE(ABORT,'image tag failure'); END"
+        )
+        conn.commit()
+        with self.assertRaises(sqlite3.IntegrityError):
+            self.db.rename_vocabulary_tag(
+                source,
+                expected_epoch=self.db.get_execution_epoch(),
+                name="source",
+                new_name="target",
+            )
+        with self.assertRaises(sqlite3.IntegrityError):
+            self.db.merge_tags(["source"], "target")
+        with self.assertRaises(sqlite3.IntegrityError):
+            self.db.rename_tag_all_prompts("source", "target")
+        self.assertFalse(conn.in_transaction)
+        after = [
+            conn.execute(f"SELECT * FROM {table} ORDER BY 1,2").fetchall()
+            for table in tables
+        ]
+        self.assertEqual(after, before)
+        self.assertEqual(self.tags(pair), ["source", "target"])
+        self.assertEqual(self.db.get_prompt_by_id(prompt)["tags"], ["source"])
+        self.assertEqual(self.image_tags(locator), ["source"])
+
 
 if __name__ == "__main__":
     unittest.main()

tests/test_utils_video_metadata.py

@@ -1,8 +1,11 @@
 """Tests for utils/video_metadata.py: prompt metadata from video containers.
 
-ComfyUI's video savers store ``{"prompt": ..., "workflow": ...}`` as JSON in
-the container's ``comment`` tag. ffprobe reads it; when ffprobe is missing
-videos are skipped without noise.
+Current ComfyUI savers (core SaveVideo/SaveWEBM, VideoHelperSuite) write one
+container tag per key (``prompt``, ``workflow``, ``parameters``,
+``comfyassets_prompt_pairs``); older VideoHelperSuite wrote one ``comment``
+JSON envelope, with ``description`` as a fallback. One selector picks a single
+carrier for the inspector and the scan. ffprobe reads the tags; when ffprobe
+is missing videos are skipped without noise.
 """
 
 import json
@@ -19,34 +22,44 @@ sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 from utils import video_metadata  # noqa: E402
 from utils.video_metadata import (  # noqa: E402
     VIDEO_EXTENSIONS,
+    DuplicateVideoTagError,
     is_video_path,
     metadata_from_tags,
     read_video_metadata,
+    select_video_carrier,
 )
 
 HAVE_FFMPEG = bool(shutil.which("ffmpeg") and shutil.which("ffprobe"))
 GRAPH = json.dumps({"1": {"class_type": "CLIPTextEncode", "inputs": {"text": "a cat"}}})
 
 
+def write_video(path, metadata_tags=True, **tags):
+    """Write a tiny black video carrying one container tag per keyword.
+
+    MP4 keeps arbitrary keys only with ``use_metadata_tags`` (mdta atoms), the
+    movflag the core SaveVideo node sets; without it ffmpeg writes the legacy
+    ilst atoms (``comment`` becomes ``©cmt``) that old VideoHelperSuite files
+    carry. Matroska and WebM upper-case the key names.
+    """
+    command = [
+        "ffmpeg",
+        "-v",
+        "quiet",
+        "-f",
+        "lavfi",
+        "-i",
+        "color=c=black:s=16x16:d=0.2",
+    ]
+    if metadata_tags and str(path).lower().endswith((".mp4", ".mov", ".m4v")):
+        command += ["-movflags", "use_metadata_tags"]
+    for key, value in tags.items():
+        command += ["-metadata", f"{key}={value}"]
+    subprocess.run(command + ["-y", str(path)], check=True, timeout=60)
+
+
 def write_mp4(path, comment):
-    """Write a tiny black video carrying ``comment`` in its container tags."""
-    subprocess.run(
-        [
-            "ffmpeg",
-            "-v",
-            "quiet",
-            "-f",
-            "lavfi",
-            "-i",
-            "color=c=black:s=16x16:d=0.2",
-            "-metadata",
-            f"comment={comment}",
-            "-y",
-            str(path),
-        ],
-        check=True,
-        timeout=60,
-    )
+    """Write a tiny black MP4 with ``comment`` in its legacy ilst ``©cmt`` atom."""
+    write_video(path, metadata_tags=False, comment=comment)
 
 
 class TestMetadataFromTags(unittest.TestCase):
@@ -69,6 +82,158 @@ class TestMetadataFromTags(unittest.TestCase):
         self.assertEqual(metadata_from_tags(tags), {"prompt": GRAPH})
 
 
+class TestSelectVideoCarrier(unittest.TestCase):
+    """Spec 2026-10-19 resolution parity section 8: one carrier, never merged."""
+
+    WORKFLOW = json.dumps({"nodes": [{"id": "per-key"}]})
+
+    def test_per_key_tags_win_over_comment(self):
+        tags = {
+            "prompt": GRAPH,
+            "workflow": self.WORKFLOW,
+            "comment": json.dumps({"prompt": json.dumps({"9": {}})}),
+        }
+        metadata, formats, carrier = select_video_carrier(tags)
+        self.assertEqual(metadata, {"prompt": GRAPH, "workflow": self.WORKFLOW})
+        self.assertEqual(
+            formats, {"prompt": "original-text", "workflow": "original-text"}
+        )
+        self.assertIsNone(carrier)
+
+    def test_matroska_uppercase_keys_fold(self):
+        tags = {"PROMPT": GRAPH, "Workflow": self.WORKFLOW, "ENCODER": "Lavf"}
+        metadata, formats, carrier = select_video_carrier(tags)
+        self.assertEqual(metadata, {"prompt": GRAPH, "workflow": self.WORKFLOW})
+        self.assertEqual(
+            formats, {"prompt": "original-text", "workflow": "original-text"}
+        )
+        self.assertIsNone(carrier)
+        # Envelope keys are read exactly as legacy did: no fold, so a Matroska
+        # upper-cased COMMENT is not an envelope.
+        self.assertIsNone(
+            select_video_carrier({"COMMENT": json.dumps({"prompt": GRAPH})})
+        )
+
+    def test_folded_duplicate_keys_fail(self):
+        for tags in (
+            {"PROMPT": GRAPH, "prompt": json.dumps({"9": {}})},
+            {"Workflow": self.WORKFLOW, "WORKFLOW": "{}", "prompt": GRAPH},
+        ):
+            with self.assertRaises(DuplicateVideoTagError):
+                select_video_carrier(tags)
+        # Byte-identical duplicates are one record, as for PNG text chunks.
+        metadata, _, _ = select_video_carrier({"PROMPT": GRAPH, "prompt": GRAPH})
+        self.assertEqual(metadata, {"prompt": GRAPH})
+        # Envelope keys never fold, so a foreign COMMENT note is not a duplicate.
+        envelope = json.dumps({"prompt": GRAPH})
+        metadata, _, carrier = select_video_carrier(
+            {"comment": envelope, "COMMENT": "a free-text note"}
+        )
+        self.assertEqual(metadata, {"prompt": GRAPH})
+        self.assertEqual(carrier, envelope)
+
+    def test_comment_envelope_still_read(self):
+        envelope = json.dumps({"prompt": GRAPH, "workflow": {"nodes": []}})
+        metadata, formats, carrier = select_video_carrier(
+            {"comment": envelope, "encoder": "Lavf"}
+        )
+        self.assertEqual(metadata["prompt"], GRAPH)
+        self.assertEqual(json.loads(metadata["workflow"]), {"nodes": []})
+        self.assertEqual(
+            formats, {"prompt": "original-text", "workflow": "reserialized-json"}
+        )
+        self.assertEqual(carrier, envelope)
+
+    def test_description_fallback(self):
+        envelope = json.dumps({"prompt": GRAPH})
+        tags = {"comment": "not json", "description": envelope}
+        self.assertEqual(
+            select_video_carrier(tags),
+            ({"prompt": GRAPH}, {"prompt": "original-text"}, envelope),
+        )
+        self.assertIsNone(select_video_carrier({"comment": "note", "encoder": "x"}))
+        self.assertIsNone(select_video_carrier({"comment": "[1]"}))
+        self.assertIsNone(select_video_carrier({}))
+        self.assertIsNone(select_video_carrier(None))
+        self.assertIsNone(select_video_carrier({"comment": 7}))
+
+    def test_role_carrier_beats_workflow_only_carrier(self):
+        envelope = json.dumps({"prompt": GRAPH, "workflow": {"nodes": ["c"]}})
+        metadata, formats, carrier = select_video_carrier(
+            {"workflow": self.WORKFLOW, "comment": envelope}
+        )
+        self.assertEqual(metadata["prompt"], GRAPH)
+        self.assertEqual(json.loads(metadata["workflow"]), {"nodes": ["c"]})
+        self.assertEqual(carrier, envelope)
+        for role in ("parameters", "comfyassets_prompt_pairs"):
+            metadata, _, carrier = select_video_carrier(
+                {"comment": json.dumps({"workflow": {}}), role: "x"}
+            )
+            self.assertEqual(metadata, {role: "x"})
+            self.assertIsNone(carrier)
+        # Without a role anywhere, the first workflow-only carrier wins.
+        metadata, _, carrier = select_video_carrier(
+            {"workflow": self.WORKFLOW, "comment": json.dumps({"workflow": {}})}
+        )
+        self.assertEqual(metadata, {"workflow": self.WORKFLOW})
+        self.assertIsNone(carrier)
+
+    def test_carriers_never_merge(self):
+        metadata, _, carrier = select_video_carrier(
+            {
+                "prompt": GRAPH,
+                "comment": json.dumps({"workflow": {"nodes": ["comment"]}}),
+                "description": json.dumps({"parameters": "Steps: 1"}),
+            }
+        )
+        self.assertEqual(metadata, {"prompt": GRAPH})
+        self.assertIsNone(carrier)
+        metadata, _, carrier = select_video_carrier(
+            {
+                "workflow": self.WORKFLOW,
+                "comment": json.dumps({"prompt": GRAPH}),
+                "description": json.dumps({"parameters": "Steps: 1"}),
+            }
+        )
+        self.assertEqual(metadata, {"prompt": GRAPH})
+        self.assertEqual(carrier, json.dumps({"prompt": GRAPH}))
+
+    def test_per_key_values_are_original_text_and_envelope_objects_reserialized(
+        self,
+    ):
+        exact = '{"3":{"inputs":{"cfg":6.5000000000000000001}}}'
+        metadata, formats, _ = select_video_carrier({"prompt": exact})
+        self.assertEqual(metadata, {"prompt": exact})
+        self.assertEqual(formats, {"prompt": "original-text"})
+        envelope = json.dumps(
+            {"prompt": {"3": {}}, "workflow": {"nodes": []}, "parameters": "Steps: 1"}
+        )
+        metadata, formats, carrier = select_video_carrier({"comment": envelope})
+        self.assertEqual(json.loads(metadata["prompt"]), {"3": {}})
+        self.assertEqual(json.loads(metadata["workflow"]), {"nodes": []})
+        self.assertEqual(metadata["parameters"], "Steps: 1")
+        self.assertEqual(
+            formats,
+            {
+                "prompt": "reserialized-json",
+                "workflow": "reserialized-json",
+                "parameters": "original-text",
+            },
+        )
+        self.assertEqual(carrier, envelope)
+
+    def test_null_role_markers_and_invalid_workflow_keep_their_shape(self):
+        # The inspector refuses a null role marker rather than falling back.
+        metadata, formats, _ = select_video_carrier(
+            {"comment": json.dumps({"prompt": None, "workflow": [1]})}
+        )
+        self.assertEqual(metadata, {"prompt": None})
+        self.assertEqual(formats, {"workflow": "invalid"})
+        metadata, formats, _ = select_video_carrier({"prompt": 7, "workflow": 1})
+        self.assertEqual(metadata, {"prompt": None})
+        self.assertEqual(formats, {"workflow": "invalid"})
+
+
 class TestIsVideoPath(unittest.TestCase):
 
     def test_extensions(self):
@@ -125,6 +290,37 @@ class TestReadVideoMetadataWithoutFfprobe(unittest.TestCase):
             ):
                 self.assertEqual(read_video_metadata("clip.mp4"), {})
 
+    def test_read_video_metadata_returns_per_key_prompt(self):
+        payload = {
+            "format": {
+                "tags": {
+                    "PROMPT": GRAPH,
+                    "WORKFLOW": '{"nodes":[]}',
+                    "COMFYASSETS_PROMPT_PAIRS": '{"version":1}',
+                    "COMMENT": json.dumps({"prompt": "must not win"}),
+                    "ENCODER": "Lavf",
+                }
+            }
+        }
+        with mock.patch.object(
+            video_metadata.shutil, "which", return_value="/bin/ffprobe"
+        ):
+            with self._run_returning(stdout=json.dumps(payload)):
+                self.assertEqual(
+                    read_video_metadata("clip.mkv"),
+                    {
+                        "prompt": GRAPH,
+                        "workflow": '{"nodes":[]}',
+                        "comfyassets_prompt_pairs": '{"version":1}',
+                    },
+                )
+            duplicates = {"format": {"tags": {"PROMPT": GRAPH, "prompt": "{}"}}}
+            with self._run_returning(stdout=json.dumps(duplicates)):
+                self.assertEqual(read_video_metadata("clip.mkv"), {})
+            markers = {"format": {"tags": {"comment": json.dumps({"prompt": None})}}}
+            with self._run_returning(stdout=json.dumps(markers)):
+                self.assertEqual(read_video_metadata("clip.mp4"), {})
+
     def test_ffprobe_output_is_parsed(self):
         payload = {"format": {"tags": {"comment": json.dumps({"prompt": GRAPH})}}}
         with mock.patch.object(
@@ -155,11 +351,83 @@ class TestReadVideoMetadataWithRealFfprobe(unittest.TestCase):
         self.assertEqual(meta["prompt"], GRAPH)
         self.assertEqual(json.loads(meta["workflow"]), {"v": 1})
 
+    def test_per_key_tags_round_trip_through_real_containers(self):
+        for name in ("per_key.mp4", "per_key.mkv", "per_key.webm"):
+            path = os.path.join(self.tmpdir, name)
+            write_video(path, prompt=GRAPH, workflow='{"nodes":[]}')
+            self.assertEqual(
+                read_video_metadata(path),
+                {"prompt": GRAPH, "workflow": '{"nodes":[]}'},
+                name,
+            )
+
+    def test_legacy_ilst_comment_atom_is_read(self):
+        path = os.path.join(self.tmpdir, "vhs.mp4")
+        write_mp4(path, json.dumps({"prompt": GRAPH}))
+        probe = subprocess.run(
+            [
+                shutil.which("ffprobe"),
+                "-v",
+                "quiet",
+                "-show_entries",
+                "format_tags",
+                "-of",
+                "json",
+                path,
+            ],
+            capture_output=True,
+            text=True,
+            check=True,
+            timeout=60,
+        )
+        tags = json.loads(probe.stdout)["format"]["tags"]
+        self.assertIn("comment", tags)
+        self.assertEqual(read_video_metadata(path), {"prompt": GRAPH})
+
     def test_video_without_a_comment_is_empty(self):
         path = os.path.join(self.tmpdir, "plain.mp4")
         write_mp4(path, "")
         self.assertEqual(read_video_metadata(path), {})
 
 
+@unittest.skipUnless(HAVE_FFMPEG, "ffmpeg/ffprobe not installed")
+class VideoFixtureFfprobeTests(unittest.TestCase):
+    """Characterization: the committed local-inspect video fixtures still carry the
+    tag maps recorded in ``video-tags-v1.json``, which the browser reader parity
+    tests use in place of ffprobe. A different ffprobe that reports other names or
+    values for the same bytes shows up here, not as a silent parity gap."""
+
+    FIXTURES = os.path.join(
+        os.path.dirname(os.path.abspath(__file__)), "fixtures", "local-inspect"
+    )
+
+    def test_committed_fixtures_produce_their_recorded_tags(self):
+        with open(
+            os.path.join(self.FIXTURES, "video-tags-v1.json"), encoding="utf-8"
+        ) as stream:
+            recorded = json.load(stream)["fixtures"]
+        self.assertEqual(len(recorded), 8)
+        for name, tags in recorded.items():
+            with self.subTest(fixture=name):
+                probe = subprocess.run(
+                    [
+                        shutil.which("ffprobe"),
+                        "-v",
+                        "quiet",
+                        "-show_entries",
+                        "format_tags",
+                        "-of",
+                        "json",
+                        os.path.join(self.FIXTURES, name),
+                    ],
+                    capture_output=True,
+                    text=True,
+                    encoding="utf-8",
+                    check=True,
+                    timeout=60,
+                )
+                self.assertEqual(json.loads(probe.stdout)["format"]["tags"], tags)
+
+
 if __name__ == "__main__":
     unittest.main()

tests/test_vocabulary.py

@@ -1,5 +1,7 @@
 """Bounded vocabulary reads count exactly what Library Browse shows."""
 
+import hashlib
+import os
 import re
 import sqlite3
 import tempfile
@@ -61,7 +63,48 @@ class TestVocabularyReads(unittest.TestCase):
         by_name = {row["name"]: row for row in page["tags"]}
         self.assertEqual(by_name["z"]["prompt_count"], 0)
         self.assertEqual(by_name["a"]["prompt_count"], 2)
-        self.assertEqual(set(by_name["c"]), {"id", "name", "prompt_count"})
+        self.assertEqual(
+            set(by_name["c"]), {"id", "name", "prompt_count", "image_count"}
+        )
+        self.assertEqual({row["image_count"] for row in page["tags"]}, {0})
+
+    def image(self, name, tags, digest="a", mtime_ns=1):
+        """Tag the bytes ``digest`` of the file ``name``; return its locator."""
+        locator = os.path.normcase(os.path.join(os.path.realpath(self.temp.name), name))
+        self.read(
+            "replace_image_tags",
+            locator=locator,
+            sha256=hashlib.sha256(digest.encode()).hexdigest(),
+            size=1,
+            mtime_ns=mtime_ns,
+            expected_epoch=self.db.get_execution_epoch(),
+            expected_tag_revision=0,
+            tags=tags,
+        )
+        return locator
+
+    def test_tag_rows_report_image_count_by_locator(self):
+        self.save("Prompt only", tags=["prompt-only"])
+        self.image("one.png", ["twice", "shared"], digest="old")
+        self.image(
+            "one.png", ["twice"], digest="new", mtime_ns=2
+        )  # two bytes, one file
+        self.image("two.png", ["shared"], digest="new")  # equal digest, other locator
+        self.image("three.png", ["prior-only"], digest="first")
+        self.image("three.png", [], digest="second", mtime_ns=2)
+        rows = {row["name"]: row for row in self.all_tags()}
+        self.assertEqual(rows["twice"]["image_count"], 1)
+        row = rows["shared"]
+        self.assertEqual(row["image_count"], 2)
+        self.assertEqual(rows["prior-only"]["image_count"], 1)
+        self.assertEqual(rows["prompt-only"]["image_count"], 0)
+        self.assertEqual(
+            {name: r["prompt_count"] for name, r in rows.items()},
+            {"prompt-only": 1, "twice": 0, "shared": 0, "prior-only": 0},
+        )
+        self.assertEqual(
+            self.db.list_library(tags=["shared"])["total"], row["prompt_count"]
+        )
 
     def test_prompt_count_equals_library_browse_total_for_every_tag(self):
         self.save("Parent only", tags=["parent-only"])
@@ -302,7 +345,12 @@ class TestVocabularyTagCommands(unittest.TestCase):
         self.assertTrue(created["created"])
         self.assertEqual(
             created["tag"],
-            {"id": self.tag_id("sunset"), "name": "sunset", "prompt_count": 0},
+            {
+                "id": self.tag_id("sunset"),
+                "name": "sunset",
+                "prompt_count": 0,
+                "image_count": 0,
+            },
         )
         after = self.junction_rows()
         self.assertEqual(after[1:], before[1:])
@@ -345,9 +393,15 @@ class TestVocabularyTagCommands(unittest.TestCase):
             {
                 "library_epoch": self.epoch,
                 "merged": False,
-                "tag": {"id": tag_id, "name": "dramatic", "prompt_count": 2},
+                "tag": {
+                    "id": tag_id,
+                    "name": "dramatic",
+                    "prompt_count": 2,
+                    "image_count": 0,
+                },
                 "components_changed": 2,
                 "pairs_changed": 2,
+                "images_changed": 0,
             },
         )
         self.assertIsNone(self.tag_id("moody"))
@@ -397,7 +451,8 @@ class TestVocabularyTagCommands(unittest.TestCase):
         )
         self.assertFalse(result["merged"])
         self.assertEqual(
-            result["tag"], {"id": tag_id, "name": "cat", "prompt_count": 1}
+            result["tag"],
+            {"id": tag_id, "name": "cat", "prompt_count": 1, "image_count": 0},
         )
         self.assertEqual(self.db.get_prompt_by_id(prompt)["tags"], ["cat"])
 
@@ -467,6 +522,7 @@ class TestVocabularyTagCommands(unittest.TestCase):
                     "other_prompts": 1,
                     "negative_variants": 1,
                     "archived_negative_variants": 1,
+                    "images": 0,
                 },
             },
         )
@@ -482,6 +538,7 @@ class TestVocabularyTagCommands(unittest.TestCase):
                 "deleted": True,
                 "components_changed": 2,
                 "pairs_changed": 2,
+                "images_changed": 0,
             },
         )
         self.assertIsNone(self.tag_id("moody"))
@@ -494,6 +551,69 @@ class TestVocabularyTagCommands(unittest.TestCase):
             )
         self.assertEqual(caught.exception.code, "vocabulary-conflict")
 
+    def image(self, name, tags, digest="a", mtime_ns=1):
+        locator = os.path.normcase(os.path.join(os.path.realpath(self.temp.name), name))
+        self.command(
+            "replace_image_tags",
+            locator=locator,
+            sha256=hashlib.sha256(digest.encode()).hexdigest(),
+            size=1,
+            mtime_ns=mtime_ns,
+            expected_epoch=self.epoch,
+            expected_tag_revision=0,
+            tags=tags,
+        )
+        return locator
+
+    def test_impact_and_delete_counts_include_images(self):
+        self.owners()
+        self.image("a.png", ["moody", "keep"])
+        self.image("a.png", ["moody"], digest="prior", mtime_ns=2)
+        self.image("b.png", ["moody"])
+        tag_id = self.tag_id("moody")
+        impact = self.command("vocabulary_tag_impact", tag_id)["impact"]
+        self.assertEqual(impact["images"], 2)
+        self.assertEqual(
+            self.command("vocabulary_tag_impact", self.tag_id("keep"))["impact"],
+            {
+                "positive_prompts": 0,
+                "other_prompts": 0,
+                "negative_variants": 0,
+                "archived_negative_variants": 0,
+                "images": 1,
+            },
+        )
+        result = self.command(
+            "delete_vocabulary_tag", tag_id, expected_epoch=self.epoch, name="moody"
+        )
+        self.assertEqual(
+            (
+                result["components_changed"],
+                result["pairs_changed"],
+                result["images_changed"],
+            ),
+            (2, 2, 2),
+        )
+        with self.db.model.get_connection() as conn:
+            self.assertEqual(
+                conn.execute("SELECT COUNT(*) FROM media_image_tags").fetchone()[0], 1
+            )
+            self.assertEqual(
+                conn.execute("SELECT COUNT(*) FROM media_annotation_bytes").fetchone()[
+                    0
+                ],
+                3,
+            )
+        renamed = self.command(
+            "rename_vocabulary_tag",
+            self.tag_id("keep"),
+            expected_epoch=self.epoch,
+            name="keep",
+            new_name="kept",
+        )
+        self.assertEqual(renamed["images_changed"], 1)
+        self.assertEqual(renamed["tag"]["image_count"], 1)
+
 
 _OLD_STAMP = "2000-01-01T00:00:00+00:00"
 _DML = re.compile(r"\s*(INSERT|UPDATE|DELETE|REPLACE)\b", re.IGNORECASE)

tools/vendor/frontend-coverage-baseline.json

@@ -73,7 +73,7 @@
   },
   "png-metadata.js": {
     "lines": 98,
-    "branches": 90,
+    "branches": 96,
     "functions": 98,
     "statements": 98
   },
@@ -293,6 +293,24 @@
     "functions": 96,
     "statements": 96
   },
+  "workspace/local-inspection.mjs": {
+    "lines": 98,
+    "branches": 89,
+    "functions": 98,
+    "statements": 98
+  },
+  "workspace/local-projection.mjs": {
+    "lines": 97,
+    "branches": 96,
+    "functions": 98,
+    "statements": 97
+  },
+  "workspace/local-video.mjs": {
+    "lines": 98,
+    "branches": 94,
+    "functions": 98,
+    "statements": 98
+  },
   "workspace/media-viewer.mjs": {
     "lines": 98,
     "branches": 93,

utils/media_capture.py

@@ -0,0 +1,632 @@
+"""Bounded private capture store for image annotations (#249 A3).
+
+One explicit Tag or review action captures exactly one selected media file:
+the rooted file is streamed to a private, owner-only temporary copy while its
+whole-file SHA-256 is computed, and the identity of the opened descriptor is
+checked against the path before and after the copy. Preview, inference and the
+metadata read use only that copy, so what the user reviewed is what the model
+saw and what Save re-checks. Everything is bounded: bytes per file, completed
+captures, reserved bytes, concurrent capture/verify workers, idle and hard
+lifetimes.
+
+The contract is "these bytes at this location, last checked at this time".
+Stat equality is never content proof: a same-size rewrite that restores
+``mtime_ns`` is visible only through the change time between the two
+``fstat`` reads, which Windows before Python 3.13 reports as the creation time
+(no signal).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import secrets
+import stat as stat_module
+import tempfile
+import threading
+import time
+import warnings
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+
+from PIL import Image
+
+try:
+    from .prompt_inspector import MetadataReadError, read_inspection_file
+    from .video_metadata import VIDEO_EXTENSIONS, is_video_path
+except ImportError:  # imported with the repo root on sys.path
+    from utils.prompt_inspector import MetadataReadError, read_inspection_file
+    from utils.video_metadata import VIDEO_EXTENSIONS, is_video_path
+
+logger = logging.getLogger(__name__)
+
+CHUNK_SIZE = 1024 * 1024
+DEFAULT_MAX_FILE = 256 * 2**20
+DEFAULT_MAX_CAPTURES = 8
+DEFAULT_MAX_BYTES = 512 * 2**20
+DEFAULT_MAX_WORKERS = 2
+DEFAULT_IDLE_SECONDS = 900
+DEFAULT_HARD_SECONDS = 1800
+MAX_INFERENCE_SIDE = 4096
+MAX_INFERENCE_PIXELS = 16_777_216
+MAX_RELATIVE_LENGTH = 1024
+
+VIDEO_ONLY_REASON = "Auto-tagging is available for supported still images only."
+HEADER_REASON = "The image header could not be read."
+DIMENSION_REASON = (
+    "Images larger than 4096 px per side or 16,777,216 px are not supported."
+)
+
+# The listing's media allowlist (``py.api.inspection_service.SERVABLE_EXTENSIONS``),
+# restated here so utilities never import the aiohttp API package; a test pins
+# the two sets equal.
+_STILL_EXTENSIONS = frozenset(
+    {".png", ".jpg", ".jpeg", ".webp", ".gif", ".bmp", ".tiff", ".tif"}
+)
+CAPTURE_EXTENSIONS = _STILL_EXTENSIONS | frozenset(VIDEO_EXTENSIONS)
+
+_DIRECTORY_PREFIX = "prompt-manager-captures-"
+_OPEN_FLAGS = (
+    os.O_RDONLY
+    | getattr(os, "O_BINARY", 0)
+    | getattr(os, "O_NOFOLLOW", 0)
+    | getattr(os, "O_CLOEXEC", 0)
+)
+
+
+class CaptureError(Exception):
+    """Base of the capture outcomes; ``code`` is the API error code."""
+
+    code = "capture-error"
+
+
+class CaptureCapacity(CaptureError):
+    """Count, byte or worker admission failed (nonblocking)."""
+
+    code = "review-capacity"
+
+
+class CaptureTooLarge(CaptureError):
+    """The file exceeds the per-file byte cap on stat or on the stream."""
+
+    code = "unsupported-media"
+
+
+class CaptureChanged(CaptureError):
+    """The file changed, vanished or was replaced across the copy (retryable)."""
+
+    code = "file-changed"
+
+
+class CaptureDenied(CaptureError):
+    """The target is not a listed rooted media file (alias, escape, non-media)."""
+
+    code = "source-changed"
+
+
+@dataclass(frozen=True)
+class FileFacts:
+    """Whole-file facts of the current rooted file, without a retained copy."""
+
+    locator: str
+    sha256: str
+    size: int
+    mtime_ns: int
+
+
+@dataclass(frozen=True)
+class Capture:
+    """One completed private copy; ``path`` is the owner-only temporary file."""
+
+    token: str
+    locator: str
+    root_index: int
+    scope: str
+    epoch: str
+    sha256: str
+    size: int
+    mtime_ns: int
+    path: str
+    media_type: str
+    width: int | None
+    height: int | None
+    inferable: bool
+    inferable_reason: str | None
+
+
+class _Entry:
+    __slots__ = ("capture", "created_at", "last_used_at", "uses", "doomed")
+
+    def __init__(self, capture: Capture, now: float):
+        self.capture = capture
+        self.created_at = now
+        self.last_used_at = now
+        self.uses = 0
+        self.doomed = False
+
+
+def _same_facts(before: os.stat_result, after: os.stat_result) -> bool:
+    """The facts every stat API reports alike: size and modification time.
+
+    This is the only comparison made across APIs (a path ``stat`` against the
+    opened descriptor's ``fstat``). Windows reports the creation time from
+    ``fstat`` but, on Python 3.12+, the change time from ``stat``, and may
+    encode device and inode differently, so those fields are compared only
+    between two reads of the same kind (``_same_identity``).
+    """
+    return before.st_size == after.st_size and before.st_mtime_ns == after.st_mtime_ns
+
+
+def _same_identity(before: os.stat_result, after: os.stat_result) -> bool:
+    """Full identity between two reads of the same kind (both ``fstat`` or both
+    path stats): size, mtime, change time, and device/inode where meaningful."""
+    if not _same_facts(before, after) or before.st_ctime_ns != after.st_ctime_ns:
+        return False
+    if before.st_ino and after.st_ino and before.st_ino != after.st_ino:
+        return False
+    if before.st_dev and after.st_dev and before.st_dev != after.st_dev:
+        return False
+    return True
+
+
+def _reason(error: OSError) -> str:
+    """The OS error text without the path, so messages never name server paths."""
+    return error.strerror or type(error).__name__
+
+
+def _unlink_quietly(path: str) -> None:
+    try:
+        os.unlink(path)
+    except FileNotFoundError:
+        pass
+    except OSError as error:
+        logger.warning("Capture file %s could not be removed: %s", path, error)
+
+
+class CaptureStore:
+    """Bounded, lock-protected registry of private media captures."""
+
+    def __init__(
+        self,
+        temp_parent: os.PathLike | str | None = None,
+        *,
+        max_file: int = DEFAULT_MAX_FILE,
+        max_captures: int = DEFAULT_MAX_CAPTURES,
+        max_bytes: int = DEFAULT_MAX_BYTES,
+        max_workers: int = DEFAULT_MAX_WORKERS,
+        idle: float = DEFAULT_IDLE_SECONDS,
+        hard: float = DEFAULT_HARD_SECONDS,
+        clock: Callable[[], float] = time.monotonic,
+    ):
+        for name, value in (
+            ("max_file", max_file),
+            ("max_captures", max_captures),
+            ("max_bytes", max_bytes),
+            ("max_workers", max_workers),
+        ):
+            if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+                raise ValueError(f"{name} must be a positive integer")
+        if not (idle > 0 and hard > 0):
+            raise ValueError("idle and hard must be positive")
+        self.max_file = max_file
+        self.max_captures = max_captures
+        self.max_bytes = max_bytes
+        self.max_workers = max_workers
+        self.idle = idle
+        self.hard = hard
+        self._clock = clock
+        parent = None if temp_parent is None else os.fspath(temp_parent)
+        if parent is not None:
+            os.makedirs(parent, exist_ok=True)
+        # mkdtemp creates the directory with owner-only permissions.
+        self.directory = tempfile.mkdtemp(prefix=_DIRECTORY_PREFIX, dir=parent)
+        self._lock = threading.Lock()
+        self._entries: dict[str, _Entry] = {}
+        self._completed_bytes = 0
+        self._pending = 0
+        self._pending_bytes = 0
+        self._workers = 0
+        self._closed = False
+        self._stale: list[str] = []
+
+    # -- public API ------------------------------------------------------------
+
+    def capture(
+        self,
+        root: os.PathLike | str,
+        relative: str,
+        *,
+        epoch: str,
+        scope: str,
+        root_index: int = 0,
+    ) -> Capture:
+        """Copy and hash one rooted media file into a private capture."""
+        if isinstance(root_index, bool) or not isinstance(root_index, int):
+            raise CaptureDenied("Invalid gallery root")
+        if root_index < 0:
+            raise CaptureDenied("Invalid gallery root")
+        for name, value in (("epoch", epoch), ("scope", scope)):
+            if not isinstance(value, str) or not value:
+                raise ValueError(f"{name} must be a non-empty string")
+        parts, extension = _relative_parts(relative)
+        candidate, locator = _resolve(root, parts)
+        before = self._pre_stat(candidate)
+        self._admit(before.st_size, reserve=True)
+        try:
+            capture = self._copy(
+                candidate, locator, extension, before, root_index, epoch, scope
+            )
+        finally:
+            self._release_admission(before.st_size, reserve=True)
+        return capture
+
+    def verify(self, root: os.PathLike | str, relative: str) -> FileFacts:
+        """Hash the current rooted file under the same bounds, keeping no copy."""
+        parts, _extension = _relative_parts(relative)
+        candidate, locator = _resolve(root, parts)
+        before = self._pre_stat(candidate)
+        self._admit(0, reserve=False)
+        try:
+            sha256 = self._stream(candidate, locator, before, None)
+        finally:
+            self._release_admission(0, reserve=False)
+        return FileFacts(locator, sha256, before.st_size, before.st_mtime_ns)
+
+    def get(self, token: str) -> Capture | None:
+        """The live capture for *token*, touching its idle clock; else None.
+
+        ``get`` does not pin the file: a reader that streams ``capture.path``
+        (the preview route) must bracket the read with ``acquire`` and
+        ``release_use``, or a concurrent ``sweep``/``release`` may unlink the
+        file under it (and, on Windows, leak it until ``close``).
+        """
+        try:
+            with self._lock:
+                entry = self._live_locked(token)
+                if entry is None:
+                    return None
+                entry.last_used_at = self._clock()
+                return entry.capture
+        finally:
+            self._flush()
+
+    def acquire(self, token: str) -> Capture | None:
+        """Mark the capture in use (inference); it outlives expiry until released."""
+        try:
+            with self._lock:
+                entry = self._live_locked(token)
+                if entry is None:
+                    return None
+                entry.uses += 1
+                entry.last_used_at = self._clock()
+                return entry.capture
+        finally:
+            self._flush()
+
+    def release_use(self, token: str) -> None:
+        """End one ``acquire``; a doomed capture is removed with its last use."""
+        with self._lock:
+            entry = self._entries.get(token)
+            if entry is not None:
+                entry.uses = max(0, entry.uses - 1)
+                entry.last_used_at = self._clock()
+                if entry.doomed and entry.uses == 0:
+                    self._remove_locked(entry)
+        self._flush()
+
+    def release(self, token: str) -> bool:
+        """Explicit release; True when the token was live."""
+        with self._lock:
+            entry = self._entries.get(token)
+            live = entry is not None and not entry.doomed
+            if live:
+                self._doom_locked(entry)
+        self._flush()
+        return live
+
+    def invalidate_all(self) -> None:
+        """Expire every capture now (storage epoch changed, restore, shutdown)."""
+        with self._lock:
+            for entry in list(self._entries.values()):
+                self._doom_locked(entry)
+        self._flush()
+
+    def sweep(self) -> None:
+        """Remove idle and hard-expired captures that are not in use."""
+        with self._lock:
+            self._sweep_locked(self._clock())
+        self._flush()
+
+    def expires_in(self, token: str) -> float | None:
+        """Seconds until *token* expires without further use; None when gone."""
+        try:
+            with self._lock:
+                entry = self._live_locked(token)
+                if entry is None:
+                    return None
+                now = self._clock()
+                remaining = self.hard - (now - entry.created_at)
+                if entry.uses == 0:
+                    remaining = min(remaining, self.idle - (now - entry.last_used_at))
+                return max(0.0, remaining)
+        finally:
+            self._flush()
+
+    def stats(self) -> dict:
+        with self._lock:
+            return {
+                "captures": len(self._entries),
+                "reserved_bytes": self._completed_bytes + self._pending_bytes,
+                "workers": self._workers,
+            }
+
+    def close(self) -> None:
+        """Remove every owned capture file and the owned directory. Idempotent.
+
+        A capture still in flight finishes first: its worker removes its own
+        temp file and then the directory (``_release_admission``).
+        """
+        with self._lock:
+            self._closed = True
+            for entry in list(self._entries.values()):
+                self._remove_locked(entry)
+            busy = self._pending > 0
+        self._flush()
+        if not busy:
+            self._remove_directory()
+
+    def _remove_directory(self) -> None:
+        try:
+            os.rmdir(self.directory)
+        except FileNotFoundError:
+            pass
+        except OSError as error:
+            logger.warning(
+                "Capture directory %s could not be removed: %s", self.directory, error
+            )
+
+    # -- admission -------------------------------------------------------------
+
+    def _admit(self, size: int, *, reserve: bool) -> None:
+        try:
+            self._admit_locked(size, reserve=reserve)
+        finally:
+            self._flush()
+
+    def _admit_locked(self, size: int, *, reserve: bool) -> None:
+        with self._lock:
+            if self._closed:
+                raise RuntimeError("The capture store is closed")
+            self._sweep_locked(self._clock())
+            if self._workers >= self.max_workers:
+                raise CaptureCapacity("Too many captures are in progress")
+            if reserve:
+                if len(self._entries) + self._pending >= self.max_captures:
+                    raise CaptureCapacity("Too many captures are held")
+                reserved = self._completed_bytes + self._pending_bytes
+                if reserved + size > self.max_bytes:
+                    raise CaptureCapacity("Capture byte budget exhausted")
+                self._pending += 1
+                self._pending_bytes += size
+            self._workers += 1
+
+    def _release_admission(self, size: int, *, reserve: bool) -> None:
+        with self._lock:
+            self._workers -= 1
+            if reserve:
+                self._pending -= 1
+                self._pending_bytes -= size
+            last_out = self._closed and self._pending == 0 and self._workers == 0
+        if last_out:
+            self._remove_directory()
+
+    def _register(self, capture: Capture) -> None:
+        with self._lock:
+            if self._closed:
+                raise RuntimeError("The capture store is closed")
+            self._completed_bytes += capture.size
+            self._entries[capture.token] = _Entry(capture, self._clock())
+
+    # -- lifetime (all under the lock) -----------------------------------------
+
+    def _expired(self, entry: _Entry, now: float) -> bool:
+        if now - entry.created_at >= self.hard:
+            return True
+        return entry.uses == 0 and now - entry.last_used_at >= self.idle
+
+    def _live_locked(self, token: str) -> _Entry | None:
+        entry = self._entries.get(token)
+        if entry is None or entry.doomed:
+            return None
+        if self._expired(entry, self._clock()):
+            self._doom_locked(entry)
+            return None
+        return entry
+
+    def _sweep_locked(self, now: float) -> None:
+        for entry in list(self._entries.values()):
+            if entry.doomed or self._expired(entry, now):
+                self._doom_locked(entry)
+
+    def _doom_locked(self, entry: _Entry) -> None:
+        entry.doomed = True
+        if entry.uses == 0:
+            self._remove_locked(entry)
+
+    def _remove_locked(self, entry: _Entry) -> None:
+        """Forget the entry; its file is unlinked by ``_flush`` after the lock."""
+        if self._entries.pop(entry.capture.token, None) is not None:
+            self._completed_bytes -= entry.capture.size
+            self._stale.append(entry.capture.path)
+
+    def _flush(self) -> None:
+        """Unlink files released under the lock, without holding it (slow I/O)."""
+        with self._lock:
+            stale, self._stale = self._stale, []
+        for path in stale:
+            _unlink_quietly(path)
+
+    # -- copy and hash -----------------------------------------------------------
+
+    def _pre_stat(self, candidate: str) -> os.stat_result:
+        try:
+            facts = os.lstat(candidate)
+        except FileNotFoundError:
+            raise CaptureChanged("The file is no longer there") from None
+        except OSError as error:
+            logger.debug("Capture pre-stat failed for %s: %s", candidate, error)
+            raise CaptureChanged(
+                f"The file could not be read ({_reason(error)})"
+            ) from None
+        if stat_module.S_ISLNK(facts.st_mode):
+            raise CaptureDenied("Symbolic links are not captured")
+        if not stat_module.S_ISREG(facts.st_mode):
+            raise CaptureDenied("Only regular files are captured")
+        if facts.st_size > self.max_file:
+            raise CaptureTooLarge("The file is larger than the capture limit")
+        return facts
+
+    def _copy(
+        self,
+        candidate: str,
+        locator: str,
+        extension: str,
+        before: os.stat_result,
+        root_index: int,
+        epoch: str,
+        scope: str,
+    ) -> Capture:
+        fd, temp_path = tempfile.mkstemp(
+            prefix="capture-", suffix=extension, dir=self.directory
+        )
+        sink = os.fdopen(fd, "wb")
+        completed = False
+        try:
+            sha256 = self._stream(candidate, locator, before, sink)
+            sink.close()
+            media_type = "video" if is_video_path(candidate) else "image"
+            width, height, inferable, reason = self._probe(temp_path, media_type)
+            capture = Capture(
+                token=secrets.token_urlsafe(32),
+                locator=locator,
+                root_index=root_index,
+                scope=scope,
+                epoch=epoch,
+                sha256=sha256,
+                size=before.st_size,
+                mtime_ns=before.st_mtime_ns,
+                path=temp_path,
+                media_type=media_type,
+                width=width,
+                height=height,
+                inferable=inferable,
+                inferable_reason=reason,
+            )
+            self._register(capture)
+            completed = True
+            return capture
+        finally:
+            if not sink.closed:
+                sink.close()
+            if not completed:
+                _unlink_quietly(temp_path)
+
+    def _read(self, stream, size: int) -> bytes:
+        """One bounded read of the source; a seam for change-detection tests."""
+        return stream.read(size)
+
+    def _stream(self, candidate: str, locator: str, before, sink) -> str:
+        """Hash (and copy into *sink*) the file; every handle closes here."""
+        digest = hashlib.sha256()
+        total = 0
+        try:
+            fd = os.open(candidate, _OPEN_FLAGS)
+        except OSError as error:
+            logger.debug("Capture open failed for %s: %s", candidate, error)
+            raise CaptureChanged(
+                f"The file could not be opened ({_reason(error)})"
+            ) from None
+        with os.fdopen(fd, "rb") as stream:
+            opened = os.fstat(stream.fileno())
+            if not _same_facts(before, opened):
+                raise CaptureChanged("The file changed before it was read")
+            while True:
+                chunk = self._read(stream, CHUNK_SIZE)
+                if not chunk:
+                    break
+                total += len(chunk)
+                if total > self.max_file:
+                    raise CaptureTooLarge("The file grew past the capture limit")
+                digest.update(chunk)
+                if sink is not None:
+                    sink.write(chunk)
+            after = os.fstat(stream.fileno())
+        if total != before.st_size or not _same_identity(opened, after):
+            raise CaptureChanged("The file changed while it was read")
+        try:
+            current = os.lstat(candidate)
+        except OSError:
+            raise CaptureChanged("The file is no longer there") from None
+        if not _same_identity(before, current):
+            raise CaptureChanged("The path names another file now")
+        if os.path.normcase(os.path.realpath(candidate)) != locator:
+            raise CaptureChanged("The path resolves elsewhere now")
+        return digest.hexdigest()
+
+    def _probe(self, path: str, media_type: str):
+        """Header-only dimensions of the capture; never decodes pixels.
+
+        Uses the inspection reader, so a PNG whose prompt metadata is over the
+        inspection budgets is reported as unreadable (not inferable) although
+        its pixels decode; B2 may switch to a dimensions-only header read.
+        """
+        if media_type == "video":
+            return None, None, False, VIDEO_ONLY_REASON
+        try:
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore", Image.DecompressionBombWarning)
+                read = read_inspection_file(Path(path))
+        except (MetadataReadError, Image.DecompressionBombError):
+            return None, None, False, HEADER_REASON
+        width, height = read.width, read.height
+        if width is None or height is None:
+            return None, None, False, HEADER_REASON
+        if (
+            width > MAX_INFERENCE_SIDE
+            or height > MAX_INFERENCE_SIDE
+            or width * height > MAX_INFERENCE_PIXELS
+        ):
+            return width, height, False, DIMENSION_REASON
+        return width, height, True, None
+
+
+def _relative_parts(relative) -> tuple[list[str], str]:
+    """Split a safe relative POSIX media path; anything else is denied."""
+    if not isinstance(relative, str) or not relative:
+        raise CaptureDenied("Invalid file path")
+    if len(relative) > MAX_RELATIVE_LENGTH or "\x00" in relative:
+        raise CaptureDenied("Invalid file path")
+    if "\\" in relative or relative.startswith("/"):
+        raise CaptureDenied("Invalid file path")
+    parts = relative.split("/")
+    for part in parts:
+        if part in ("", ".", "..") or ":" in part:
+            raise CaptureDenied("Invalid file path")
+    extension = os.path.splitext(parts[-1])[1].lower()
+    if extension not in CAPTURE_EXTENSIONS:
+        raise CaptureDenied("Unsupported media type")
+    return parts, extension
+
+
+def _resolve(root, parts: list[str]) -> tuple[str, str]:
+    """The candidate path and its locator; aliases and escapes are denied."""
+    real_root = os.path.realpath(os.fspath(root))
+    if not os.path.isdir(real_root):
+        raise CaptureDenied("Unknown gallery root")
+    candidate = os.path.join(real_root, *parts)
+    locator = os.path.normcase(candidate)
+    if os.path.normcase(os.path.realpath(candidate)) != locator:
+        raise CaptureDenied("The file is not a listed rooted file")
+    return candidate, locator

utils/prompt_inspector.py

@@ -23,7 +23,15 @@ from .prompt_pair_resolver import (
     ResolverProfile,
     resolve_prompt_pair,
 )
-from .video_metadata import ffprobe_path, is_video_path
+from .video_metadata import (
+    ENVELOPE_TAG_KEYS,
+    ROLE_TAG_KEYS,
+    VIDEO_TAG_KEYS,
+    DuplicateVideoTagError,
+    ffprobe_path,
+    is_video_path,
+    select_video_carrier,
+)
 
 # Role records (prompt, parameters, the pair execution record) share one
 # budget, encoded and decoded: roles cannot be trusted from a partial record,
@@ -36,7 +44,18 @@ WORKFLOW_METADATA_BYTES = 4 * 1024 * 1024
 # repeated chunks cost bounded I/O instead of file size.
 DUPLICATE_WORKFLOW_BYTES = 2 * WORKFLOW_METADATA_BYTES
 DUPLICATE_ROLE_BYTES = 2 * ROLE_METADATA_BYTES
-MAX_METADATA_BYTES = ROLE_METADATA_BYTES  # video stdout bound, unchanged here
+# ffprobe stdout bounds. ffprobe JSON-escapes tag text (at most doubling it),
+# and the decoded per-record budgets below are the only gate that may make a
+# record fail or ``limited``: a video must read exactly as the identical PNG.
+# So the first probe allows twice the role and workflow budgets plus 64 KiB of
+# JSON envelope; past that only the per-key ``workflow`` tag can be dropped,
+# and the re-probe asks for role and envelope tags within twice the role
+# budget (an envelope cannot be split, so an over-budget one fails the read).
+MAX_METADATA_BYTES = ROLE_METADATA_BYTES
+VIDEO_PROBE_BYTES = 2 * (ROLE_METADATA_BYTES + WORKFLOW_METADATA_BYTES) + 64 * 1024
+VIDEO_REPROBE_BYTES = 2 * ROLE_METADATA_BYTES + 64 * 1024
+VIDEO_PROBE_SECONDS = 3
+_VIDEO_ROLE_PROBE_KEYS = ROLE_TAG_KEYS + ENVELOPE_TAG_KEYS
 MAX_KEYWORD_BYTES = 80  # a 1-79 byte PNG keyword plus its NUL separator
 MAX_HEADER_BYTES = 8 * 1024 * 1024
 MAX_PNG_CHUNKS = 10_000
@@ -86,6 +105,7 @@ class _VideoInspection:
     metadata: dict[str, str | None]
     record_formats: dict[str, str]
     carrier_text: str | None
+    limited: frozenset[str] = dataclass_field(default_factory=frozenset)
 
 
 def _inflate(data: bytes, limit: int) -> bytes | None:
@@ -274,16 +294,16 @@ def _png_metadata(stream: Any, size: int) -> tuple[dict, frozenset, int, int]:
     raise MetadataReadError("PNG chunk count exceeds inspection limits")
 
 
-def _video_metadata(path: Path) -> _VideoInspection:
-    probe = ffprobe_path()
-    if not probe:
-        raise MetadataReadError("Video metadata reader is unavailable")
+def _probe_video_tags(
+    probe: str, path: Path, keys: tuple[str, ...], limit: int
+) -> bytes | None:
+    """ffprobe's JSON for the container tags ``keys``; ``None`` past ``limit``."""
     command = [
         probe,
         "-v",
         "quiet",
         "-show_entries",
-        "format_tags=comment,description",
+        "format_tags=" + ",".join(keys),
         "-of",
         "json",
         str(path),
@@ -303,13 +323,13 @@ def _video_metadata(path: Path) -> _VideoInspection:
                 # Timeout and final cleanup can race with the process exiting.
                 pass
 
-    timer = threading.Timer(3, stop)
+    timer = threading.Timer(VIDEO_PROBE_SECONDS, stop)
     timer.daemon = True
     timer.start()
     try:
-        raw = process.stdout.read(MAX_METADATA_BYTES + 1)
-        if len(raw) > MAX_METADATA_BYTES:
-            raise MetadataReadError("Video metadata exceeds inspection limits")
+        raw = process.stdout.read(limit + 1)
+        if len(raw) > limit:
+            return None
         process.wait()
         if process.returncode:
             raise MetadataReadError("Video metadata could not be read")
@@ -318,49 +338,45 @@ def _video_metadata(path: Path) -> _VideoInspection:
         stop()
         process.wait()
         process.stdout.close()
+    return raw
+
+
+def _video_metadata(path: Path) -> _VideoInspection:
+    probe = ffprobe_path()
+    if not probe:
+        raise MetadataReadError("Video metadata reader is unavailable")
+    limited = frozenset()
+    raw = _probe_video_tags(probe, path, VIDEO_TAG_KEYS, VIDEO_PROBE_BYTES)
+    if raw is None:
+        raw = _probe_video_tags(
+            probe, path, _VIDEO_ROLE_PROBE_KEYS, VIDEO_REPROBE_BYTES
+        )
+        if raw is None:
+            raise MetadataReadError("Video metadata exceeds inspection limits")
+        # Only the per-key workflow tag was left out, so it is the record over
+        # budget: limited when the per-key carrier (or no carrier) is selected.
+        limited = frozenset({"workflow"})
     probed = json.loads(raw)
     if not isinstance(probed, dict) or not isinstance(probed.get("format"), dict):
         raise MetadataReadError("Malformed video metadata")
     tags = probed["format"].get("tags", {})
     if not isinstance(tags, dict):
         raise MetadataReadError("Malformed video metadata")
-    # The scan normalizer drops null fields and unknown keys. Inspection must
-    # retain explicit prompt/execution markers so malformed evidence cannot
-    # silently fall back to an unrelated saved recipe or another comment.
-    candidates = []
-    for key in ("comment", "description"):
-        raw = tags.get(key)
-        if not isinstance(raw, str):
-            continue
-        try:
-            envelope = json.loads(raw)
-        except ValueError:
-            continue
-        if not isinstance(envelope, dict):
-            continue
-        candidates.append((raw, envelope))
-    selected = next(
-        (item for item in candidates if _ROLE_METADATA_KEYS.intersection(item[1])),
-        None,
-    )
+    # The shared selector keeps explicit null role markers so malformed
+    # evidence cannot silently fall back to an unrelated saved recipe or
+    # another carrier; ``read_inspection_file`` refuses them.
+    try:
+        selected = select_video_carrier(tags)
+    except DuplicateVideoTagError:
+        raise MetadataReadError("Duplicate prompt metadata") from None
     if selected is None:
-        selected = next((item for item in candidates if "workflow" in item[1]), None)
-    if selected is not None:
-        raw, envelope = selected
-        metadata, formats = {}, {}
-        for field in _METADATA_KEYS.intersection(envelope):
-            value = envelope[field]
-            if field == "workflow" and not isinstance(value, (str, dict)):
-                formats[field] = "invalid"
-                continue
-            metadata[field] = (
-                value if value is None or isinstance(value, str) else json.dumps(value)
-            )
-            formats[field] = (
-                "original-text" if isinstance(value, str) else "reserialized-json"
-            )
-        return _VideoInspection(metadata, formats, raw)
-    return _VideoInspection({}, {}, None)
+        return _VideoInspection({}, {}, None, limited)
+    metadata, formats, carrier = selected
+    if carrier is not None:
+        # An envelope carrier is whole; the dropped per-key workflow belonged
+        # to the carrier that lost.
+        limited = frozenset()
+    return _VideoInspection(metadata, formats, carrier, limited)
 
 
 def read_inspection_file(path: Path) -> InspectionRead:
@@ -370,10 +386,11 @@ def read_inspection_file(path: Path) -> InspectionRead:
         format_name = width = height = None
         if is_video_path(path):
             video = _video_metadata(path)
-            metadata, formats, carrier = (
+            metadata, formats, carrier, limited = (
                 video.metadata,
                 video.record_formats,
                 video.carrier_text,
+                video.limited,
             )
         else:
             with path.open("rb") as stream:

utils/video_metadata.py

@@ -1,14 +1,18 @@
 """Prompt metadata from video containers.
 
-ComfyUI's video savers (core SaveVideo, VideoHelperSuite, ...) write the
-queued graph into the container's ``comment`` tag as JSON:
-``{"prompt": "<graph json>", "workflow": {...}}``. ffprobe reads it on every
-platform; when ffprobe is not installed, videos are skipped with a single
-notice instead of one error per file.
+Current ComfyUI video savers (core SaveVideo/SaveWEBM, VideoHelperSuite since
+``c67ff3e``) write one container tag per key, each a JSON string:
+``prompt``, ``workflow``, ``parameters``, ``comfyassets_prompt_pairs``. Older
+VideoHelperSuite wrote one ``comment`` tag holding a JSON envelope
+``{"prompt": "<graph json>", "workflow": {...}}``; ``description`` is read as a
+fallback envelope. ffprobe reads the tags on every platform; when ffprobe is
+not installed, videos are skipped with a single notice instead of one error
+per file.
 
+``select_video_carrier`` picks exactly one carrier for both the inspector and
+the scan, so Images and ingestion read the same prompts from the same file.
 The result uses the same shape as PNG text chunks (string values keyed
-``prompt`` / ``workflow`` / ``parameters``) so the existing prompt parser
-handles both.
+``prompt`` / ``workflow`` / ...) so the existing prompt parser handles both.
 """
 
 import functools
@@ -20,10 +24,15 @@ import shutil
 # Fixed argv, absolute binary, no shell.
 import subprocess  # nosec B404
 
+from .pair_execution import EXECUTION_KEY
+
 VIDEO_EXTENSIONS = (".mp4", ".mov", ".m4v", ".webm", ".mkv", ".avi", ".wmv")
 FFPROBE_TIMEOUT = 20  # seconds; a stuck probe must not hang a worker thread
-_COMMENT_TAGS = ("comment", "description")
-_METADATA_KEYS = ("prompt", "workflow", "parameters")
+# Carrier order: per-key tags, then the ``comment`` envelope, then ``description``.
+ROLE_TAG_KEYS = ("prompt", "parameters", EXECUTION_KEY)
+METADATA_TAG_KEYS = ("prompt", "workflow", "parameters", EXECUTION_KEY)
+ENVELOPE_TAG_KEYS = ("comment", "description")
+VIDEO_TAG_KEYS = METADATA_TAG_KEYS + ENVELOPE_TAG_KEYS
 _NO_WINDOW = getattr(subprocess, "CREATE_NO_WINDOW", 0)  # no console flash on Windows
 
 logger = logging.getLogger("prompt_manager.video")
@@ -46,32 +55,122 @@ def reset_missing_notice():
     _missing_notice_shown = False
 
 
-def metadata_from_tags(tags) -> dict:
-    """Normalise container tags into PNG-text-chunk shaped metadata.
+class DuplicateVideoTagError(ValueError):
+    """Two container tags fold to the same metadata key with different text."""
 
-    Returns ``{}`` when no tag carries a JSON object with a known key.
+
+def _folded_tags(tags: dict) -> dict:
+    """Known tags keyed by their carrier name.
+
+    Per-key prompt carriers fold ASCII case: Matroska muxers upper-case tag
+    names and ffprobe reports them as written. Two tags folding to one key are
+    a duplicate record: byte-identical duplicates are one record (as for PNG
+    text chunks), differing ones fail the read. Envelope keys (``comment``,
+    ``description``) are read exactly as the legacy readers did, never folded.
     """
-    if not isinstance(tags, dict):
-        return {}
-    for tag in _COMMENT_TAGS:
-        raw = tags.get(tag)
+    folded = {}
+    for key, value in tags.items():
+        if not isinstance(key, str):
+            continue
+        if key in ENVELOPE_TAG_KEYS:
+            folded[key] = value
+            continue
+        name = key.lower()
+        if name not in METADATA_TAG_KEYS:
+            continue
+        if name in folded and folded[name] != value:
+            raise DuplicateVideoTagError(f"Duplicate video metadata tag: {name}")
+        folded[name] = value
+    return folded
+
+
+def _record(value, key):
+    """One carrier field as (metadata text or None, record format or None).
+
+    A null marker (or a non-text role value) has no record format: it is kept
+    in the metadata as ``None`` so the inspector refuses it instead of letting
+    fallback evidence win, while scans drop it.
+    """
+    if key == "workflow" and not isinstance(value, (str, dict)):
+        return None, "invalid"
+    if isinstance(value, str):
+        return value, "original-text"
+    if isinstance(value, dict):
+        return json.dumps(value), "reserialized-json"
+    return None, None
+
+
+def _carriers(folded: dict):
+    """Candidate carriers in order: (fields, raw envelope text or None)."""
+    per_key = {key: folded[key] for key in METADATA_TAG_KEYS if key in folded}
+    if per_key:
+        yield per_key, None
+    for tag in ENVELOPE_TAG_KEYS:
+        raw = folded.get(tag)
         if not isinstance(raw, str):
             continue
         try:
-            data = json.loads(raw)
+            envelope = json.loads(raw)
         except ValueError:
             continue
-        if not isinstance(data, dict):
+        if isinstance(envelope, dict):
+            yield envelope, raw
+
+
+def select_video_carrier(tags):
+    """Choose the one container carrier of prompt metadata.
+
+    Returns ``(metadata, record_formats, carrier_text)`` or ``None`` when no
+    carrier holds a known key. ``metadata`` maps known keys to their text, or
+    to ``None`` for an explicit null marker that the inspector must refuse;
+    ``record_formats`` is ``original-text``, ``reserialized-json`` (an envelope
+    object) or ``invalid`` (a workflow that is neither text nor an object), and
+    ``carrier_text`` is the exact envelope for reserialized values (``None``
+    for per-key tags). The first carrier holding a role key wins; otherwise the
+    first holding ``workflow``. Carriers are never merged.
+    Raises :class:`DuplicateVideoTagError` for differing fold-duplicate tags.
+    """
+    if not isinstance(tags, dict):
+        return None
+    candidates = list(_carriers(_folded_tags(tags)))
+    selected = next(
+        (item for item in candidates if any(key in item[0] for key in ROLE_TAG_KEYS)),
+        None,
+    )
+    if selected is None:
+        selected = next((item for item in candidates if "workflow" in item[0]), None)
+    if selected is None:
+        return None
+    fields, carrier_text = selected
+    metadata, formats = {}, {}
+    for key in METADATA_TAG_KEYS:
+        if key not in fields:
             continue
-        found = {}
-        for key in _METADATA_KEYS:
-            value = data.get(key)
-            if value is None:
-                continue
-            found[key] = value if isinstance(value, str) else json.dumps(value)
-        if found:
-            return found
-    return {}
+        text, record_format = _record(fields[key], key)
+        if record_format == "invalid":
+            formats[key] = record_format
+            continue
+        metadata[key] = text
+        if record_format is not None:
+            formats[key] = record_format
+    return metadata, formats, carrier_text
+
+
+def metadata_from_tags(tags) -> dict:
+    """Normalise container tags into PNG-text-chunk shaped metadata for scans.
+
+    Returns ``{}`` when no carrier holds a known key, and when fold-duplicate
+    tags make the file's evidence untrustworthy.
+    """
+    try:
+        selected = select_video_carrier(tags)
+    except DuplicateVideoTagError as e:
+        logger.debug(f"Video tags skipped: {e}")
+        return {}
+    if selected is None:
+        return {}
+    metadata, _, _ = selected
+    return {key: value for key, value in metadata.items() if isinstance(value, str)}
 
 
 def read_video_metadata(path, timeout=FFPROBE_TIMEOUT) -> dict:

web/js/png-metadata.js

@@ -2,9 +2,14 @@
  * PNG text-chunk reader: the one place that walks a PNG's chunks to pull out
  * the tEXt/iTXt entries ComfyUI writes (`prompt`, `workflow`, ...).
  *
- * Only uncompressed text is returned. zTXt chunks and iTXt chunks with the
- * compression flag set are skipped rather than decoded as garbage; ComfyUI
- * never writes those. Nothing throws: unreadable input yields {}.
+ * `parsePngTextChunks` (the legacy pages): only uncompressed text is returned.
+ * zTXt chunks and iTXt chunks with the compression flag set are skipped rather
+ * than decoded as garbage; ComfyUI never writes those. Nothing throws:
+ * unreadable input yields {}.
+ *
+ * `readPngMetadataFile`, `classifyPrefix` and `readImageHeader` (the Inspect
+ * page, #249): bounded readers over a File that port the server's inspection
+ * reader so a local file shows exactly what Images shows for the same bytes.
  *
  * Loadable in the browser (window.PngMetadata) and in Node for tests.
  */
@@ -94,7 +99,605 @@
         return result;
     }
 
-    const api = { parsePngTextChunks, PNG_SIGNATURE };
+    // ------------------------------------------------------------------------
+    // Local File readers for the Inspect page (#249): a port of the server's
+    // bounded PNG reader (utils/prompt_inspector.py: _png_metadata, _PngRecords,
+    // _png_text, _inflate, _batch_normalized), a media classifier and a JPEG/WebP
+    // header reader. Nothing here uploads, stores or logs the file. The reader
+    // slices only chunk headers, keyword prefixes and the retained records, so a
+    // multi-gigabyte PNG costs at most PNG_READ_CEILING bytes of reads.
+    // tests/test_local_inspect_parity.py proves it answers as the server does.
+    // ------------------------------------------------------------------------
+
+    // Role records (prompt, parameters, the pair execution record) share one
+    // budget, encoded and decoded: past it the read fails. A workflow has its own
+    // budget; past it only the workflow is "limited". Duplicate chunks draw from
+    // separate budgets per class, so repeats cost bounded reads, not file size.
+    const ROLE_METADATA_BYTES = 2 * 1024 * 1024;
+    const WORKFLOW_METADATA_BYTES = 4 * 1024 * 1024;
+    const DUPLICATE_WORKFLOW_BYTES = 2 * WORKFLOW_METADATA_BYTES;
+    const DUPLICATE_ROLE_BYTES = 2 * ROLE_METADATA_BYTES;
+    const MAX_KEYWORD_BYTES = 80; // a 1-79 byte keyword plus its NUL separator
+    const MAX_PNG_CHUNKS = 10000;
+    const MAX_CHUNK_LENGTH = 0x7fffffff;
+    const IHDR_LENGTH = 13;
+    // Every byte the reader can slice from a PNG of any size: the signature, each
+    // chunk's header, CRC and keyword prefix, the retained-data budgets and IHDR.
+    const PNG_READ_CEILING =
+        PNG_SIGNATURE.length +
+        MAX_PNG_CHUNKS * (CHUNK_HEADER + CHUNK_CRC + MAX_KEYWORD_BYTES) +
+        ROLE_METADATA_BYTES +
+        WORKFLOW_METADATA_BYTES +
+        DUPLICATE_WORKFLOW_BYTES +
+        DUPLICATE_ROLE_BYTES +
+        IHDR_LENGTH; // 19,794,389
+    const HEADER_READ_BYTES = 64 * 1024;
+    const INFLATE_WRITE_BYTES = 256;
+    const YIELD_INTERVAL_MS = 8;
+    const LATIN1_SLICE = 8192;
+    const ROLE_KEYS = new Set(["prompt", "parameters", "comfyassets_prompt_pairs"]);
+    const METADATA_KEYS = new Set([...ROLE_KEYS, "workflow"]);
+    const TEXT_CHUNKS = new Set(["tEXt", "zTXt", "iTXt"]);
+    // The server's _FOOTER (with its MULTILINE anchors spelled out: a line start is
+    // the text start or after "\n"; a line end is before "\n" or the text end) and
+    // _BATCH_INDEX, with Python's Unicode \d.
+    const FOOTER = /(?:^|(?<=\n))Steps:\s*\p{Nd}+\s*,[^\n]*(?=\n|$)/gu;
+    const BATCH_INDEX = /(?:^|(?<=, ))Batch index: \p{Nd}+(?=, |$)/gu;
+    const ASF_GUID = [0x30, 0x26, 0xb2, 0x75, 0x8e, 0x66, 0xcf, 0x11, 0xa6, 0xd9, 0x00, 0xaa, 0x00, 0x62, 0xce, 0x6c];
+    const JPEG_SOF = new Set([0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf]);
+    const JPEG_SOS = 0xda;
+
+    const CRC_TABLE = (() => {
+        const table = new Uint32Array(256);
+        for (let n = 0; n < 256; n++) {
+            let c = n;
+            for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+            table[n] = c;
+        }
+        return table;
+    })();
+
+    function crc32(...parts) {
+        let c = 0xffffffff;
+        for (const bytes of parts) for (let i = 0; i < bytes.length; i++) c = CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+        return (c ^ 0xffffffff) >>> 0;
+    }
+
+    function readUint32(bytes, offset) {
+        return bytes[offset] * 0x1000000 + ((bytes[offset + 1] << 16) | (bytes[offset + 2] << 8) | bytes[offset + 3]);
+    }
+
+    function startsWith(bytes, prefix, at = 0) {
+        if (bytes.length < at + prefix.length) return false;
+        for (let i = 0; i < prefix.length; i++) if (bytes[at + i] !== prefix[i]) return false;
+        return true;
+    }
+
+    function sameBytes(a, b) {
+        if (a.length !== b.length) return false;
+        for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+        return true;
+    }
+
+    function concatBytes(parts, total) {
+        const out = new Uint8Array(total);
+        let offset = 0;
+        for (const part of parts) {
+            out.set(part, offset);
+            offset += part.length;
+        }
+        return out;
+    }
+
+    /** ISO-8859-1 in slices: TextDecoder's "latin1" label is windows-1252, not this. */
+    function latin1Text(bytes) {
+        let out = "";
+        for (let i = 0; i < bytes.length; i += LATIN1_SLICE) out += String.fromCharCode.apply(null, bytes.subarray(i, i + LATIN1_SLICE));
+        return out;
+    }
+
+    /** UTF-8 length of the Latin-1 decoding: each byte >= 0x80 becomes two bytes. */
+    function latin1Utf8Length(bytes) {
+        let high = 0;
+        for (let i = 0; i < bytes.length; i++) if (bytes[i] >= 0x80) high++;
+        return bytes.length + high;
+    }
+
+    function isAscii(bytes) {
+        for (let i = 0; i < bytes.length; i++) if (bytes[i] >= 0x80) return false;
+        return true;
+    }
+
+    function utf8Length(text) {
+        return new TextEncoder().encode(text).length;
+    }
+
+    class PngReadError extends Error {
+        constructor(reason, message) {
+            super(message);
+            this.name = "PngReadError";
+            this.reason = reason;
+        }
+    }
+
+    const invalid = (message) => new PngReadError("invalid-png", message);
+    const overLimit = () => new PngReadError("metadata-limit", "Metadata exceeds inspection limits");
+    const readFailure = (message) => new PngReadError("read-failure", message);
+
+    function abortError() {
+        return new DOMException("The file read was aborted", "AbortError");
+    }
+
+    function throwIfAborted(signal) {
+        if (signal && signal.aborted) throw abortError();
+    }
+
+    function quiet(promise) {
+        Promise.resolve(promise).catch(() => {});
+    }
+
+    /** `promise`, or an AbortError as soon as `signal` aborts (the promise is left handled). */
+    function untilAborted(promise, signal) {
+        if (!signal) return promise;
+        if (signal.aborted) {
+            quiet(promise);
+            return Promise.reject(abortError());
+        }
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                quiet(promise);
+                reject(abortError());
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+            promise.then(
+                (value) => {
+                    signal.removeEventListener("abort", onAbort);
+                    resolve(value);
+                },
+                (error) => {
+                    signal.removeEventListener("abort", onAbort);
+                    reject(error);
+                },
+            );
+        });
+    }
+
+    /** Strict UTF-8 (invalid sequences and encoded surrogates fail), BOM kept, as Python's decode. */
+    function utf8Strict(bytes) {
+        try {
+            return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+        } catch (error) {
+            throw invalid("Media metadata could not be read");
+        }
+    }
+
+    function defaultYield() {
+        return new Promise((resolve) => setTimeout(resolve, 0));
+    }
+
+    /** Hands the event loop a turn about every YIELD_INTERVAL_MS of work. */
+    function createPacer(yieldControl) {
+        let last = performance.now();
+        return {
+            async maybeYield() {
+                if (performance.now() - last < YIELD_INTERVAL_MS) return;
+                await yieldControl();
+                last = performance.now();
+            },
+        };
+    }
+
+    /**
+     * Logical byte ranges of `file`, served from the retained `prefix` where it
+     * covers them. Every sliced byte is charged against PNG_READ_CEILING, and every
+     * range is checked against `file.size` before it is sliced.
+     */
+    function createSliceReader(file, prefix, signal) {
+        const retained = prefix || new Uint8Array(0);
+        let charged = 0;
+        return {
+            async read(start, end) {
+                if (!Number.isSafeInteger(end) || end > file.size) throw invalid("Incomplete PNG metadata");
+                if (end <= retained.length) return retained.subarray(start, end);
+                const head = start < retained.length ? retained.subarray(start) : null;
+                const sliceStart = head ? retained.length : start;
+                charged += end - sliceStart;
+                if (charged > PNG_READ_CEILING) throw readFailure("PNG read exceeds the inspection ceiling");
+                const buffer = await file.slice(sliceStart, end).arrayBuffer();
+                throwIfAborted(signal);
+                const bytes = new Uint8Array(buffer);
+                if (bytes.length !== end - sliceStart) throw readFailure("The file changed while it was being read");
+                return head ? concatBytes([head, bytes], end - start) : bytes;
+            },
+        };
+    }
+
+    /**
+     * Inflates zlib data through `decompress` (a DecompressionStream constructor)
+     * with one <=256-byte write in flight, keeping at most `limit` output bytes.
+     * Returns null when the output is over `limit`, as the server's _inflate does.
+     */
+    function createInflater(decompress, signal, pacer) {
+        return async function inflate(compressed, limit) {
+            if (typeof decompress !== "function") {
+                throw new PngReadError("decompression-unavailable", "This browser cannot inflate compressed PNG text");
+            }
+            const stream = new decompress("deflate");
+            const writer = stream.writable.getWriter();
+            const reader = stream.readable.getReader();
+            const parts = [];
+            let total = 0;
+            let over = false;
+            const stop = () => {
+                quiet(writer.abort());
+                quiet(reader.cancel());
+            };
+            if (signal) signal.addEventListener("abort", stop, { once: true });
+            try {
+                const drain = (async () => {
+                    for (;;) {
+                        const { value, done } = await untilAborted(reader.read(), signal);
+                        if (done) return;
+                        total += value.byteLength;
+                        if (total > limit) {
+                            over = true;
+                            stop();
+                            return;
+                        }
+                        parts.push(value);
+                    }
+                })();
+                const feed = (async () => {
+                    for (let offset = 0; offset < compressed.length; offset += INFLATE_WRITE_BYTES) {
+                        await pacer.maybeYield();
+                        await untilAborted(writer.ready, signal);
+                        await untilAborted(writer.write(compressed.subarray(offset, offset + INFLATE_WRITE_BYTES)), signal);
+                    }
+                    await untilAborted(writer.close(), signal);
+                })();
+                const outcomes = await Promise.allSettled([drain, feed]);
+                throwIfAborted(signal);
+                if (over) return null;
+                if (outcomes.some((outcome) => outcome.status === "rejected")) {
+                    throw invalid("Compressed metadata is invalid or exceeds limits");
+                }
+                return concatBytes(parts, total);
+            } finally {
+                if (signal) signal.removeEventListener("abort", stop);
+            }
+        };
+    }
+
+    /** The keyword before the first NUL of a <=80-byte prefix: 1-79 Latin-1 bytes. */
+    function keywordOf(prefix) {
+        const nul = indexOfNul(prefix, 0, prefix.length);
+        if (nul < 1 || nul > MAX_KEYWORD_BYTES - 1) throw invalid("Malformed PNG text metadata");
+        return latin1(prefix, 0, nul);
+    }
+
+    /** Splits on NUL at most `limit` times (Python's bytes.split(b"\\0", limit)). */
+    function splitNul(bytes, limit) {
+        const fields = [];
+        let start = 0;
+        while (fields.length < limit) {
+            const nul = indexOfNul(bytes, start, bytes.length);
+            if (nul === -1) break;
+            fields.push(bytes.subarray(start, nul));
+            start = nul + 1;
+        }
+        fields.push(bytes.subarray(start));
+        return fields;
+    }
+
+    /**
+     * Decodes one retained text chunk (the server's _png_text): {text, size} with
+     * size the UTF-8 length of text, or null when it inflates past `limit`.
+     */
+    async function pngText(kind, data, limit, inflate) {
+        let body = data.subarray(indexOfNul(data, 0, data.length) + 1);
+        let unicode = false;
+        if (kind === "zTXt") {
+            if (body.length === 0 || body[0] !== 0) throw invalid("Unsupported PNG text compression");
+            body = await inflate(body.subarray(1), limit);
+        } else if (kind === "iTXt") {
+            if (body.length < 2 || body[0] > 1) throw invalid("Malformed international PNG metadata");
+            const flag = body[0];
+            const method = body[1];
+            const fields = splitNul(body.subarray(2), 2);
+            if (fields.length !== 3 || (flag && method !== 0)) throw invalid("Malformed international PNG metadata");
+            if (!isAscii(fields[0])) throw invalid("Media metadata could not be read");
+            utf8Strict(fields[1]);
+            body = flag ? await inflate(fields[2], limit) : fields[2];
+            unicode = true;
+        }
+        if (body === null) return null;
+        if (indexOfNul(body, 0, body.length) !== -1) throw invalid("Malformed PNG text metadata");
+        if (unicode) return { text: utf8Strict(body), size: body.length };
+        return { text: latin1Text(body), size: latin1Utf8Length(body) };
+    }
+
+    /** The server's _batch_normalized: the footer's single batch index blanked, else null. */
+    function batchNormalized(text) {
+        const footers = [...text.matchAll(FOOTER)];
+        if (footers.length !== 1) return null;
+        const [footer] = footers;
+        let count = 0;
+        const line = footer[0].replace(BATCH_INDEX, () => {
+            count++;
+            return "Batch index: #";
+        });
+        if (count !== 1) return null;
+        return text.slice(0, footer.index) + line + text.slice(footer.index + footer[0].length);
+    }
+
+    /** Retained records with per-class budgets and byte-identical duplicates (the server's _PngRecords). */
+    class PngRecords {
+        constructor() {
+            this.found = {};
+            this.limited = new Set();
+            this.retained = new Map(); // key -> {kind, data} of the kept chunk, compared byte for byte
+            this.roleEncoded = 0;
+            this.roleDecoded = 0;
+            this.duplicateWorkflow = 0;
+            this.duplicateRole = 0;
+            this.duplicateDecoded = 0;
+        }
+
+        /** Decide from the keyword and length alone whether to seek past a chunk. */
+        skip(key, length) {
+            if (!METADATA_KEYS.has(key) || this.limited.has(key)) return true; // never retained, or a duplicate of a limited workflow
+            const kept = this.retained.get(key);
+            if (kept) {
+                if (kept.data.length !== length && key !== "parameters") throw invalid("Duplicate prompt metadata");
+                if (key === "workflow") {
+                    if (this.duplicateWorkflow + length > DUPLICATE_WORKFLOW_BYTES) {
+                        this.limited.add(key);
+                        delete this.found[key];
+                        return true;
+                    }
+                    this.duplicateWorkflow += length;
+                } else {
+                    if (this.duplicateRole + length > DUPLICATE_ROLE_BYTES) throw overLimit();
+                    this.duplicateRole += length;
+                }
+                return false; // same length: read and compare bytes
+            }
+            if (key === "workflow") {
+                if (length > WORKFLOW_METADATA_BYTES) {
+                    this.limited.add(key);
+                    return true;
+                }
+                return false;
+            }
+            this.roleEncoded += length;
+            if (this.roleEncoded > ROLE_METADATA_BYTES) throw overLimit();
+            return false;
+        }
+
+        async add(kind, data, inflate) {
+            const key = keywordOf(data.subarray(0, MAX_KEYWORD_BYTES));
+            const kept = this.retained.get(key);
+            if (kept) {
+                if (kept.kind !== kind || !sameBytes(kept.data, data)) {
+                    if (key !== "parameters") throw invalid("Duplicate prompt metadata");
+                    await this.batchCopy(kind, data, inflate);
+                    // The kept copy is the last one; later repeats compare with it.
+                    this.retained.set(key, { kind, data });
+                }
+                return;
+            }
+            this.retained.set(key, { kind, data });
+            const workflow = key === "workflow";
+            const limit = workflow ? WORKFLOW_METADATA_BYTES : ROLE_METADATA_BYTES - this.roleDecoded;
+            const decoded = await pngText(kind, data, limit, inflate);
+            if (workflow) {
+                if (decoded === null || decoded.size > WORKFLOW_METADATA_BYTES) {
+                    this.limited.add(key);
+                    return;
+                }
+            } else {
+                this.roleDecoded += decoded === null ? limit + 1 : decoded.size;
+                if (this.roleDecoded > ROLE_METADATA_BYTES) throw overLimit();
+            }
+            this.found[key] = decoded.text;
+        }
+
+        /**
+         * Keep a later `parameters` copy that differs only in its batch index. Each
+         * copy must carry exactly one `Batch index: N` settings field; any other
+         * difference is a conflict. Decoding every copy draws from the duplicate
+         * role budget, so small compressed copies stay bounded.
+         */
+        async batchCopy(kind, data, inflate) {
+            const decoded = await pngText(kind, data, ROLE_METADATA_BYTES, inflate);
+            const size = decoded === null ? ROLE_METADATA_BYTES + 1 : decoded.size;
+            this.duplicateDecoded += size;
+            if (decoded === null || this.duplicateDecoded > DUPLICATE_ROLE_BYTES) throw overLimit();
+            const kept = this.found.parameters;
+            const normalized = batchNormalized(kept);
+            if (normalized === null || normalized !== batchNormalized(decoded.text)) throw invalid("Duplicate prompt metadata");
+            this.roleDecoded += Math.max(0, size - utf8Length(kept));
+            if (this.roleDecoded > ROLE_METADATA_BYTES) throw overLimit();
+            this.found.parameters = decoded.text;
+        }
+    }
+
+    /**
+     * Walks the chunk layout (the server's _png_metadata): CRC-checks IHDR, IEND
+     * and retained text chunks, reads keyword prefixes, and seeks past everything
+     * else by length, so pixel data and unknown text are never read.
+     */
+    async function readPngChunks(reader, fileSize, { signal, inflate, pacer }) {
+        const records = new PngRecords();
+        let sawHeader = false;
+        let sawPixels = false;
+        let width = 0;
+        let height = 0;
+        let offset = PNG_SIGNATURE.length;
+        for (let index = 0; index < MAX_PNG_CHUNKS; index++) {
+            await pacer.maybeYield();
+            throwIfAborted(signal);
+            const header = await reader.read(offset, offset + CHUNK_HEADER);
+            const length = readUint32(header, 0);
+            const kindBytes = header.subarray(4, 8);
+            const kind = latin1(header, 4, 8);
+            const dataStart = offset + CHUNK_HEADER;
+            const next = dataStart + length + CHUNK_CRC;
+            if (length > MAX_CHUNK_LENGTH || next > fileSize) throw invalid("Incomplete PNG chunk");
+            if (index === 0 && (kind !== "IHDR" || length !== IHDR_LENGTH)) throw invalid("Missing PNG header");
+            let data;
+            let checksum;
+            if (TEXT_CHUNKS.has(kind)) {
+                const prefix = await reader.read(dataStart, dataStart + Math.min(length, MAX_KEYWORD_BYTES));
+                if (records.skip(keywordOf(prefix), length)) {
+                    offset = next;
+                    continue;
+                }
+                const rest = await reader.read(dataStart + prefix.length, next);
+                data = concatBytes([prefix, rest.subarray(0, rest.length - CHUNK_CRC)], length);
+                checksum = rest.subarray(rest.length - CHUNK_CRC);
+            } else if (kind === "IHDR" || kind === "IEND") {
+                const bytes = await reader.read(dataStart, next);
+                data = bytes.subarray(0, length);
+                checksum = bytes.subarray(length);
+            } else {
+                sawPixels = sawPixels || kind === "IDAT";
+                offset = next;
+                continue;
+            }
+            if (crc32(kindBytes, data) !== readUint32(checksum, 0)) throw invalid("PNG metadata checksum mismatch");
+            if (kind === "IHDR") {
+                const w = readUint32(data, 0);
+                const h = readUint32(data, 4);
+                if (sawHeader || !w || !h) throw invalid("Malformed PNG header");
+                sawHeader = true;
+                width = w;
+                height = h;
+            } else if (kind === "IEND") {
+                if (length || !sawPixels) throw invalid("Incomplete PNG image");
+                return { records: { ...records.found }, limited: [...records.limited].sort(), width, height };
+            } else {
+                await records.add(kind, data, inflate);
+            }
+            offset = next;
+        }
+        throw new PngReadError("metadata-limit", "PNG chunk count exceeds inspection limits");
+    }
+
+    /**
+     * Reads the retained text records and the IHDR size of a PNG File without
+     * reading its pixels or sending it anywhere.
+     *
+     * @param {Blob} file - the chosen File (only `size` and `slice` are used)
+     * @param {Object} [options]
+     * @param {AbortSignal} [options.signal] - rejects the read with an AbortError
+     * @param {Uint8Array} [options.prefix] - the file's first bytes, already read for classification
+     * @param {Function} [options.yieldControl] - awaited about every 8 ms of work
+     * @param {Function} [options.decompress] - DecompressionStream constructor; pass undefined where none exists
+     * @returns {Promise<{status:'complete', records:Object<string,string>, limited:string[], width:number, height:number}
+     *   | {status:'unreadable', reason:'invalid-png'|'read-failure'|'metadata-limit'|'decompression-unavailable'}>}
+     */
+    async function readPngMetadataFile(file, options = {}) {
+        const { signal, prefix, yieldControl = defaultYield } = options;
+        const decompress = Object.hasOwn(options, "decompress") ? options.decompress : globalThis.DecompressionStream;
+        try {
+            throwIfAborted(signal);
+            if (!file || !Number.isSafeInteger(file.size) || typeof file.slice !== "function") throw readFailure("Not a readable file");
+            const reader = createSliceReader(file, toBytes(prefix), signal);
+            const pacer = createPacer(yieldControl);
+            const signature = await reader.read(0, PNG_SIGNATURE.length);
+            if (!hasSignature(signature)) throw invalid("Not a PNG file");
+            const inflate = createInflater(decompress, signal, pacer);
+            const result = await readPngChunks(reader, file.size, { signal, inflate, pacer });
+            return { status: "complete", ...result };
+        } catch (error) {
+            if (error && error.name === "AbortError") throw error;
+            if (error instanceof PngReadError) return { status: "unreadable", reason: error.reason };
+            return { status: "unreadable", reason: "read-failure" };
+        }
+    }
+
+    /**
+     * Media kind from a file's first bytes (<= 32), or null for anything else.
+     * @returns {{media:'image'|'video', kind:'png'|'jpeg'|'webp'|'iso-bmff'|'matroska'|'avi'|'asf'}|null}
+     */
+    function classifyPrefix(input) {
+        const bytes = toBytes(input);
+        if (!bytes) return null;
+        if (hasSignature(bytes)) return { media: "image", kind: "png" };
+        if (startsWith(bytes, [0xff, 0xd8, 0xff])) return { media: "image", kind: "jpeg" };
+        if (bytes.length >= 12 && latin1(bytes, 0, 4) === "RIFF") {
+            const form = latin1(bytes, 8, 12);
+            if (form === "WEBP") return { media: "image", kind: "webp" };
+            if (form === "AVI ") return { media: "video", kind: "avi" };
+            return null;
+        }
+        if (bytes.length >= 8 && latin1(bytes, 4, 8) === "ftyp") return { media: "video", kind: "iso-bmff" };
+        if (startsWith(bytes, [0x1a, 0x45, 0xdf, 0xa3])) return { media: "video", kind: "matroska" };
+        if (startsWith(bytes, ASF_GUID)) return { media: "video", kind: "asf" };
+        return null;
+    }
+
+    /** [width, height] from the first SOFn segment, walking markers as Pillow does. */
+    function jpegSize(bytes) {
+        if (!startsWith(bytes, [0xff, 0xd8])) return null;
+        let offset = 2;
+        while (offset + 1 < bytes.length) {
+            if (bytes[offset] !== 0xff) {
+                offset++; // junk between segments
+                continue;
+            }
+            const marker = bytes[offset + 1];
+            if (marker === 0xff) {
+                offset++; // padding
+                continue;
+            }
+            if (marker === 0x00 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd9)) {
+                offset += 2; // escaped 0xFF, TEM, RSTn, SOI, EOI: no length
+                continue;
+            }
+            if (marker === JPEG_SOS || offset + 4 > bytes.length) return null;
+            if (JPEG_SOF.has(marker)) {
+                if (offset + 9 > bytes.length) return null;
+                return [(bytes[offset + 7] << 8) | bytes[offset + 8], (bytes[offset + 5] << 8) | bytes[offset + 6]];
+            }
+            offset += 2 + ((bytes[offset + 2] << 8) | bytes[offset + 3]);
+        }
+        return null;
+    }
+
+    /** [width, height] from the first WebP chunk: VP8 frame, VP8L header or VP8X canvas. */
+    function webpSize(bytes) {
+        if (bytes.length < 30 || latin1(bytes, 0, 4) !== "RIFF" || latin1(bytes, 8, 12) !== "WEBP") return null;
+        const kind = latin1(bytes, 12, 16);
+        if (kind === "VP8 ") {
+            if (!startsWith(bytes, [0x9d, 0x01, 0x2a], 23)) return null;
+            return [(bytes[26] | (bytes[27] << 8)) & 0x3fff, (bytes[28] | (bytes[29] << 8)) & 0x3fff];
+        }
+        if (kind === "VP8L") {
+            if (bytes[20] !== 0x2f) return null;
+            const packed = bytes[21] | (bytes[22] << 8) | (bytes[23] << 16) | (bytes[24] << 24);
+            return [(packed & 0x3fff) + 1, ((packed >>> 14) & 0x3fff) + 1];
+        }
+        if (kind === "VP8X") {
+            return [1 + (bytes[24] | (bytes[25] << 8) | (bytes[26] << 16)), 1 + (bytes[27] | (bytes[28] << 8) | (bytes[29] << 16))];
+        }
+        return null;
+    }
+
+    /**
+     * Format and dimensions of a JPEG or WebP File from at most 64 KiB of its head.
+     * @returns {Promise<{format:'JPEG'|'WEBP'|null, width:number|null, height:number|null}>}
+     */
+    async function readImageHeader(file, kind) {
+        const format = kind === "jpeg" ? "JPEG" : kind === "webp" ? "WEBP" : null;
+        if (!format) return { format: null, width: null, height: null };
+        const bytes = new Uint8Array(await file.slice(0, Math.min(file.size, HEADER_READ_BYTES)).arrayBuffer());
+        const size = (format === "JPEG" ? jpegSize : webpSize)(bytes);
+        return { format, width: size ? size[0] : null, height: size ? size[1] : null };
+    }
+
+    const api = { parsePngTextChunks, PNG_SIGNATURE, classifyPrefix, readPngMetadataFile, readImageHeader };
     if (typeof module !== "undefined" && module.exports) module.exports = api;
     else root.PngMetadata = api;
 })(typeof window !== "undefined" ? window : globalThis);

web/js/workspace/history.mjs

@@ -22,6 +22,12 @@ function observedLabel(value) {
     return `Observed dequeue ${value} ms (${Number.isSafeInteger(time) && time <= 8640000000000000 ? new Date(time).toISOString() : 'outside display range'})`;
 }
 
+// Writing textContent replaces the text node even when the text is unchanged. A marker re-rendered between the press and
+// the release of a tap would lose the node under the pointer, and Chromium touch then drops the click.
+function setText(node, text) {
+    if (node.textContent !== text) node.textContent = text;
+}
+
 // New nodes use ordinary insertion; connected moves preserve browser state where supported.
 function place(parent, node, before) {
     if (node === before || (node.parentNode === parent && node.nextSibling === before)) return;
@@ -115,7 +121,7 @@ export function mountRecordedHistory(container, {api, positiveId, parentScope, s
             const {node, buttons} = column;
             node.style.insetInlineStart = `${38 + index * 64}px`;node.value = index + 1;
             node.setAttribute('aria-posinset', String(index + 1));node.setAttribute('aria-setsize', String(items.length));
-            column.position.textContent = String(index + 1);
+            setText(column.position, String(index + 1));
             const anchors = new Map();for (const anchor of run.matching_anchors) if (!anchors.has(anchor.context_id)) anchors.set(anchor.context_id, anchor);
             for (const anchor of anchors.values()) {
                 let button = buttons.get(anchor.context_id);
@@ -126,7 +132,7 @@ export function mountRecordedHistory(container, {api, positiveId, parentScope, s
                 const context = contexts.get(anchor.context_id), first = context.first === index;
                 button.classList.toggle('history-context-anchor', first);
                 button.style.insetBlockStart = `${80 + context.row * 57}px`;
-                button.textContent = first ? '−' : '';
+                setText(button, first ? '−' : '');
                 const label = `Recorded run ${index + 1} of ${items.length} loaded · ${observedLabel(run.observed_dequeue_at)} · Outcome ${run.outcome} · ${preview(context.summary)} · context ${anchor.context_id.slice(0, 8)} · anchor ${anchor.anchor_id}`;
                 button.setAttribute('aria-label', label);button.title = label;
                 button.setAttribute('aria-pressed', String(state.selection.run_id === run.run_id && state.selection.context_id === anchor.context_id));
@@ -157,7 +163,7 @@ export function mountRecordedHistory(container, {api, positiveId, parentScope, s
                 let branch = branchNodes.get(id);
                 if (!branch) {branch = el('div', undefined, 'history-context-branch');branch.dataset.contextBranch = id;branch.append(el('span', '', 'history-context-label'));branchNodes.set(id, branch);}
                 branch.style.insetBlockStart = `${80 + context.row * 57}px`;branch.style.insetInlineStart = `${38 + context.first * 64}px`;
-                branch.firstChild.textContent = `${preview(context.summary)} · ${id.slice(0, 8)} · ${distinction(context.summary)}`;
+                setText(branch.firstChild, `${preview(context.summary)} · ${id.slice(0, 8)} · ${distinction(context.summary)}`);
                 place(branches, branch, before);before = branch.nextSibling;
             }
             if (anchor) {
@@ -176,7 +182,7 @@ export function mountRecordedHistory(container, {api, positiveId, parentScope, s
         selected.hidden = !outside;selected.disabled = next.validating || window.loading || !!next.refreshRequired;
         earlier.hidden = !window.has_more;earlier.disabled = window.loading || !!next.refreshRequired;earlier.setAttribute('aria-disabled', String(earlier.disabled));
         refresh.disabled = window.loading || next.validating;retry.hidden = !window.error || !!next.refreshRequired;
-        reload.hidden = !next.refreshRequired;reload.textContent = next.refreshLabel || 'Reload recorded history';
+        reload.hidden = !next.refreshRequired;setText(reload, next.refreshLabel || 'Reload recorded history');
         timeline.hidden = !items.length;
         let initialAnchor = null;
         if (!initialized && items.length && !window.loading && !next.validating && !next.refreshRequired) {

web/js/workspace/inspection-state.mjs

@@ -87,8 +87,10 @@ function promptsFor(value) {
     return value;
 }
 
-function fileFor(value) {
-    if (!object(value) || value.observation !== 'current-file' || typeof value.source_label !== 'string' ||
+function fileFor(value, identity) {
+    // A local record observes the selected file itself; every other adapter observes a current server file.
+    const observation = identity?.kind === 'local-file' ? 'selected-local-file' : 'current-file';
+    if (!object(value) || value.observation !== observation || typeof value.source_label !== 'string' ||
         !['image', 'video'].includes(value.media_type) || typeof value.extension !== 'string' ||
         (value.format !== null && typeof value.format !== 'string')) throw new TypeError('Invalid inspection file');
     const file = { observation: value.observation, source_label: value.source_label, media_type: value.media_type, extension: value.extension, format: value.format };
@@ -281,7 +283,7 @@ export function projectInspectionPayload(result, identity, download, extractFact
     };
     if (legacy) return record;
     const resolution = resolutionFor(result.resolution);
-    record.file = fileFor(result.file);
+    record.file = fileFor(result.file, identity);
     record.metadata = metadataFor(result.metadata);
     record.library = libraryFor(result.library);
     if (typeof extractFacts !== 'function') throw new TypeError('Inspection facts parser unavailable');

web/js/workspace/local-inspection.mjs

@@ -0,0 +1,175 @@
+// One chosen local File, read entirely in this browser, as the inspection wire
+// the workspace already renders. The readers are ports of the server's
+// (png-metadata.js readPngMetadataFile/readImageHeader, local-video.mjs); the
+// projection is local-projection.mjs. Nothing here builds a URL or sends bytes:
+// the only URL a handle carries is the session-owned blob: URL it was created with.
+import { readVideoTags, selectVideoCarrier } from './local-video.mjs';
+import { projectMetadata, fitInspectionPayload, MAX_RESPONSE_BYTES } from './local-projection.mjs';
+import { projectInspectionPayload } from './inspection-state.mjs';
+
+export const LOCAL_OBSERVATION = 'selected-local-file';
+export const LOCAL_SOURCE_LABEL = 'Selected local file';
+// Interim roles until PR L3 ports the inspection resolver: every role is open, and
+// the legacy fill in projectInspectionPayload shows what the legacy pages show.
+const LOCAL_RESOLUTION_REASON = 'Resolved in this browser from the workflow.';
+const LOCAL_LIBRARY = Object.freeze({ status: 'unavailable', scope: 'saved-library', tags: [], category_scope: null, tags_scope: null });
+const LOCAL_SCOPE = 'local';
+const PREFIX_BYTES = 32;
+const MAX_FILENAME_CHARS = 255;
+const MEDIA_TYPES = new Set(['image', 'video']);
+
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const pngReader = () => globalThis.PngMetadata || globalThis.window?.PngMetadata;
+
+/** A display name with no path separators or control characters; never empty. */
+export function sanitizeLocalFilename(name) {
+    const text = typeof name === 'string' ? name : '';
+    const cleaned = text.replace(/[\x00-\x1f\x7f]/g, '').replace(/[\\/]/g, '_').trim();
+    return [...cleaned].slice(0, MAX_FILENAME_CHARS).join('') || 'file';
+}
+
+/** `pathlib.Path(name).suffix.lower()`. */
+function localExtension(filename) {
+    const dot = filename.lastIndexOf('.');
+    return dot > 0 && dot < filename.length - 1 ? filename.slice(dot).toLowerCase() : '';
+}
+
+function classificationOf(value) {
+    if (!object(value) || !MEDIA_TYPES.has(value.media) || typeof value.kind !== 'string' || !value.kind) throw new TypeError('Unsupported local file');
+    return Object.freeze({ media: value.media, kind: value.kind });
+}
+
+/**
+ * Run the readers the server would run for these bytes: the bounded PNG reader,
+ * the JPEG/WebP header reader, or the container tag readers plus the carrier rule.
+ * Returns `{classification, result}` in the oracle's shape; `result` is null for
+ * bytes no reader claims.
+ */
+export async function readLocalFile(file, { classification, signal, pngMetadata = pngReader() } = {}) {
+    if (!(file instanceof Blob)) throw new TypeError('A local file is required');
+    const reader = () => {
+        if (!pngMetadata || typeof pngMetadata.classifyPrefix !== 'function') throw new TypeError('The local PNG reader is unavailable');
+        return pngMetadata;
+    };
+    const prefix = new Uint8Array(await file.slice(0, Math.min(PREFIX_BYTES, file.size)).arrayBuffer());
+    const classified = classification === undefined ? reader().classifyPrefix(prefix) : classification;
+    if (classified === null) return { classification: null, result: null };
+    const { media, kind } = classificationOf(classified);
+    if (kind === 'png') return { classification: classified, result: await reader().readPngMetadataFile(file, { signal, prefix }) };
+    if (media === 'image') return { classification: classified, result: await reader().readImageHeader(file, kind) };
+    const read = await readVideoTags(file, { signal, prefix, kind });
+    return { classification: classified, result: { read, selection: read.status === 'complete' ? selectVideoCarrier(read.tags, { limited: read.limited }) : null } };
+}
+
+/**
+ * The server's InspectionRead for a reader result: `read` is null when the server
+ * would have raised MetadataReadError (unreadable), else
+ * `{records, record_formats, carrierText, limited}`; `format`, `width` and
+ * `height` follow `read_inspection_file` (a video has none).
+ */
+export function toInspectionRead(classification, result) {
+    const { media, kind } = classificationOf(classification);
+    const none = { read: null, format: null, width: null, height: null };
+    if (kind === 'png') {
+        if (!object(result) || result.status !== 'complete') return none;
+        const limited = [...(result.limited ?? [])];
+        const record_formats = Object.fromEntries(Object.keys(result.records).map(key => [key, 'original-text']));
+        for (const key of limited) record_formats[key] = 'limited';
+        return { read: { records: { ...result.records }, record_formats, carrierText: null, limited }, format: 'PNG', width: result.width ?? null, height: result.height ?? null };
+    }
+    if (media === 'image') {
+        if (!object(result)) return none;
+        return { read: { records: {}, record_formats: {}, carrierText: null, limited: [] }, format: result.format ?? null, width: result.width ?? null, height: result.height ?? null };
+    }
+    const selection = result?.selection;
+    if (result?.read?.status !== 'complete' || !object(selection) || selection.status !== 'complete') return none;
+    return { read: { records: { ...selection.records }, record_formats: { ...selection.record_formats }, carrierText: selection.carrierText ?? null, limited: [...(selection.limited ?? [])] }, format: null, width: null, height: null };
+}
+
+const dimension = value => Number.isSafeInteger(value) && value > 0 ? value : null;
+
+/** The `inspection_version: 1` wire for one local read, before the response budget. */
+export function buildLocalPayload({ read, file, classification }) {
+    const classified = classificationOf(classification);
+    const inspection = toInspectionRead(classified, read);
+    const filename = sanitizeLocalFilename(file?.name);
+    const size = Number.isSafeInteger(file?.size) && file.size >= 0 ? file.size : null;
+    const modified = typeof file?.lastModified === 'number' && Number.isFinite(file.lastModified) && file.lastModified >= 0 ? file.lastModified / 1000 : null;
+    return {
+        success: true, inspection_version: 1,
+        file: {
+            observation: LOCAL_OBSERVATION, source_label: LOCAL_SOURCE_LABEL, media_type: classified.media, extension: localExtension(filename),
+            format: inspection.format, size, width: dimension(inspection.width), height: dimension(inspection.height), modified_time: modified,
+        },
+        prompts: { positive: { status: 'unresolved' }, negative: { status: 'unresolved' } },
+        resolution: { state: 'unresolved', sampler_id: null, reason: LOCAL_RESOLUTION_REASON, reason_code: null, node: null },
+        metadata: projectMetadata(inspection.read),
+        library: { ...LOCAL_LIBRARY, tags: [] },
+    };
+}
+
+/** The server's 8 MiB response budget, applied to the local wire with the same omission order. */
+export function fitLocalPayload(wire, limit = MAX_RESPONSE_BYTES, options = {}) {
+    return fitInspectionPayload(wire, limit, options);
+}
+
+// Handles this module created, by a private token: the controller and the viewer
+// session spread-copy descriptors, so a copy of an owned handle is the same
+// selection, while a hand-made descriptor or a tampered URL is foreign.
+const TOKEN = Symbol('local-file');
+const OWNED = new WeakMap();
+let sequence = 0;
+
+/**
+ * One selection of a local file. `url` is the session's own `blob:` URL (or null
+ * when none could be created); every selection gets a new key, so choosing the
+ * same bytes twice never reuses a stale read.
+ */
+export function createLocalFileHandle({ file, url = null, classification, filename = file?.name }) {
+    if (!(file instanceof Blob)) throw new TypeError('A local file is required');
+    if (url !== null && (typeof url !== 'string' || !url.startsWith('blob:'))) throw new TypeError('Local media must be a blob: URL');
+    const classified = classificationOf(classification);
+    const token = Object.freeze({});
+    const secret = Object.freeze({ key: `local:${++sequence}`, filename: sanitizeLocalFilename(filename), url, file, classification: classified });
+    OWNED.set(token, secret);
+    return Object.freeze({ kind: 'local-file', key: secret.key, filename: secret.filename, is_video: classified.media === 'video', url, file, classification: classified, [TOKEN]: token });
+}
+
+/** The owned selection behind a handle (or a copy of one); throws for anything else. */
+function owned(handle) {
+    const secret = object(handle) ? OWNED.get(handle[TOKEN]) : undefined;
+    if (!secret || secret.key !== handle.key || secret.url !== handle.url || secret.file !== handle.file || secret.filename !== handle.filename) throw new TypeError('Unknown local file');
+    return secret;
+}
+
+function validate(handle) {
+    owned(handle);
+}
+
+function originalDownload(handle) {
+    const secret = owned(handle);
+    if (secret.url === null) throw new TypeError('Original media is unavailable');
+    return { url: secret.url, filename: secret.filename };
+}
+
+export const localFileAdapter = Object.freeze({
+    validate,
+    key(handle) { return owned(handle).key; },
+    scope(handle) { owned(handle); return LOCAL_SCOPE; },
+    // An inert sentinel: the controller's same-key check works and no URL is ever built.
+    inspectionPath(handle) { return `local-file:${owned(handle).key}`; },
+    async read(handle, { signal } = {}) {
+        const secret = owned(handle);
+        const { result } = await readLocalFile(secret.file, { classification: secret.classification, signal });
+        return fitLocalPayload(buildLocalPayload({ read: result, file: { name: secret.filename, size: secret.file.size, lastModified: secret.file.lastModified }, classification: secret.classification }), MAX_RESPONSE_BYTES, { signal });
+    },
+    toRecord(result, handle, extractFacts) {
+        const secret = owned(handle);
+        if (!object(result) || result.success !== true || result.inspection_version !== 1) throw new TypeError('Invalid local inspection');
+        return projectInspectionPayload(result, { kind: 'local-file', key: secret.key, path: secret.filename },
+            secret.url === null ? null : originalDownload(handle), extractFacts);
+    },
+    originalDownload,
+    // Session-owned, never resolved through the API client.
+    mediaUrl(handle) { return owned(handle).url; },
+});

web/js/workspace/local-projection.mjs

@@ -0,0 +1,404 @@
+// Browser port of utils/inspection_response.py: the strict parse (Decimal
+// spelling, no duplicate keys, NaN/Infinity as null, integers past 2^53-1 as
+// text), the prompt/workflow/carrier projection with its depth and node
+// ceilings, `_metadata`, and the response-size omission steps of
+// `_encode_inspection`. A local file must project exactly as the server does for
+// the same bytes; tests/test_local_inspect_parity.py holds both to one answer.
+// Pure: no DOM, no I/O.
+
+export const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+export const MAX_PROJECTION_DEPTH = 64;
+// Backstop, not an expected outcome: executable API nodes for a prompt; UI nodes
+// including subgraph definitions for a workflow.
+export const GRAPH_NODE_CEILING = 20000;
+export const RECORD_KEYS = Object.freeze(['prompt', 'workflow', 'parameters', 'comfyassets_prompt_pairs']);
+const FORMATS = new Set(['original-text', 'reserialized-json', 'invalid', 'limited']);
+const PROMPT_NODE_KEYS = new Set(['class_type', 'inputs']);
+const MAX_SAFE_DIGITS = '9007199254740991';
+// Python's int() refuses more digits than sys.get_int_max_str_digits() (4300).
+export const INT_MAX_STR_DIGITS = 4300;
+// decimal's exact constructor (libmpdec, 64-bit) refuses values outside its
+// maximal context: adjusted exponent above MAX_EMAX or exponent below Etiny.
+const DECIMAL_MAX_EMAX = 999999999999999999n;
+const DECIMAL_ETINY = -1999999999999999997n;
+const NUMBER = /-?(?:0|[1-9][0-9]*)(\.[0-9]+)?([eE][-+]?[0-9]+)?/y;
+const STRING_STOP = /["\\\u0000-\u001f]/g;
+const HEX4 = /^[0-9a-fA-F]{4}$/;
+const ESCAPES = { '"': '"', '\\': '\\', '/': '/', b: '\b', f: '\f', n: '\n', r: '\r', t: '\t' };
+// Python's json: `null`/`true`/`false`, then the constants parse_constant receives.
+const LITERALS = [['null', null], ['true', true], ['false', false], ['NaN', null], ['Infinity', null], ['-Infinity', null]];
+
+/** A present graph cannot be projected within inspection limits (`_ProjectionLimit`). */
+export class ProjectionLimit extends Error {
+    constructor() {
+        super('Projection exceeds inspection limits');
+        this.name = 'ProjectionLimit';
+    }
+}
+
+/** The server's ValueError/TypeError family: the text or tree is malformed. */
+export class ProjectionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ProjectionError';
+    }
+}
+
+const isArray = Array.isArray;
+const isObject = value => value !== null && typeof value === 'object' && !isArray(value);
+const isContainer = value => value !== null && typeof value === 'object';
+
+/** Python's `str(Decimal(literal))` from the literal's digits and exponent, never through a float. */
+export function spellDecimal(literal) {
+    const negative = literal[0] === '-';
+    const body = negative ? literal.slice(1) : literal;
+    const exponentAt = body.search(/[eE]/);
+    const mantissa = exponentAt < 0 ? body : body.slice(0, exponentAt);
+    const dot = mantissa.indexOf('.');
+    const integer = dot < 0 ? mantissa : mantissa.slice(0, dot), fraction = dot < 0 ? '' : mantissa.slice(dot + 1);
+    const exponent = (exponentAt < 0 ? 0n : BigInt(body.slice(exponentAt + 1))) - BigInt(fraction.length);
+    const digits = (integer + fraction).replace(/^0+/, '') || '0';
+    const adjusted = exponent + BigInt(digits.length) - 1n;
+    if (adjusted > DECIMAL_MAX_EMAX || exponent < DECIMAL_ETINY) throw new ProjectionError('JSON decimal exceeds supported range');
+    const leftDigits = exponent + BigInt(digits.length);
+    const dotPlace = exponent <= 0n && leftDigits > -6n ? leftDigits : 1n;
+    let intPart, fracPart;
+    if (dotPlace <= 0n) {
+        intPart = '0'; fracPart = '.' + '0'.repeat(Number(-dotPlace)) + digits;
+    } else if (dotPlace >= BigInt(digits.length)) {
+        intPart = digits + '0'.repeat(Number(dotPlace - BigInt(digits.length))); fracPart = '';
+    } else {
+        intPart = digits.slice(0, Number(dotPlace)); fracPart = '.' + digits.slice(Number(dotPlace));
+    }
+    const shift = leftDigits - dotPlace;
+    const exp = shift === 0n ? '' : `E${shift > 0n ? '+' : '-'}${shift < 0n ? -shift : shift}`;
+    return (negative ? '-' : '') + intPart + fracPart + exp;
+}
+
+function numberValue(match) {
+    const [literal, fraction, exponent] = match;
+    if (fraction || exponent) return spellDecimal(literal);
+    const digits = literal[0] === '-' ? literal.slice(1) : literal;
+    if (digits.length > INT_MAX_STR_DIGITS) throw new ProjectionError('Exceeds the limit for integer string conversion');
+    if (digits.length > MAX_SAFE_DIGITS.length || (digits.length === MAX_SAFE_DIGITS.length && digits > MAX_SAFE_DIGITS)) return literal;
+    return Number(literal) || 0;
+}
+
+/**
+ * `json.loads(text, parse_float=Decimal, object_pairs_hook=_pairs, parse_constant=_nonfinite)`
+ * with its results already normalized: objects have a null prototype, fractions and
+ * exponents are Decimal text, integers past 2^53-1 are their literal text, and
+ * NaN/Infinity are null. Iterative, so nesting depth never overflows the stack.
+ */
+export function parseStrictJson(text) {
+    if (typeof text !== 'string') throw new ProjectionError('JSON text must be a string');
+    let pos = 0;
+    const fail = message => new ProjectionError(`${message} at ${pos}`);
+    const skip = () => {
+        while (pos < text.length) {
+            const c = text.charCodeAt(pos);
+            if (c !== 0x20 && c !== 0x09 && c !== 0x0a && c !== 0x0d) break;
+            pos++;
+        }
+    };
+    function string() {
+        pos++;
+        let out = '';
+        for (;;) {
+            STRING_STOP.lastIndex = pos;
+            const stop = STRING_STOP.exec(text);
+            if (!stop) throw fail('Unterminated string');
+            out += text.slice(pos, stop.index);
+            pos = stop.index + 1;
+            if (stop[0] === '"') return out;
+            if (stop[0] !== '\\') throw fail('Invalid control character');
+            const escape = text[pos];
+            if (escape === 'u') {
+                const hex = text.slice(pos + 1, pos + 5);
+                if (!HEX4.test(hex)) throw fail('Invalid \\uXXXX escape');
+                pos += 5;
+                const code = parseInt(hex, 16);
+                if (code >= 0xd800 && code <= 0xdbff && text[pos] === '\\' && text[pos + 1] === 'u') {
+                    const low = text.slice(pos + 2, pos + 6);
+                    const lowCode = HEX4.test(low) ? parseInt(low, 16) : -1;
+                    if (lowCode >= 0xdc00 && lowCode <= 0xdfff) {
+                        out += String.fromCharCode(code, lowCode);
+                        pos += 6;
+                        continue;
+                    }
+                }
+                out += String.fromCharCode(code);
+            } else if (Object.hasOwn(ESCAPES, escape)) {
+                out += ESCAPES[escape];
+                pos++;
+            } else throw fail('Invalid \\escape');
+        }
+    }
+    function key() {
+        if (text[pos] !== '"') throw fail('Expecting property name enclosed in double quotes');
+        const name = string();
+        skip();
+        if (text[pos] !== ':') throw fail("Expecting ':' delimiter");
+        pos++;
+        skip();
+        return name;
+    }
+    function scalar() {
+        if (text[pos] === '"') return string();
+        for (const [literal, value] of LITERALS) {
+            if (text.startsWith(literal, pos)) {
+                pos += literal.length;
+                return value;
+            }
+        }
+        NUMBER.lastIndex = pos;
+        const match = NUMBER.exec(text);
+        if (!match) throw fail('Expecting value');
+        pos += match[0].length;
+        return numberValue(match);
+    }
+    skip();
+    const stack = [];
+    let result;
+    for (;;) {
+        let value;
+        if (text[pos] === '{') {
+            pos++; skip();
+            const frame = { value: Object.create(null), object: true, key: null, duplicate: false };
+            if (text[pos] === '}') pos++;
+            else { frame.key = key(); stack.push(frame); continue; }
+            value = frame.value;
+        } else if (text[pos] === '[') {
+            pos++; skip();
+            const frame = { value: [], object: false };
+            if (text[pos] === ']') pos++;
+            else { stack.push(frame); continue; }
+            value = frame.value;
+        } else value = scalar();
+        // Attach the finished value, closing containers whose last member it was.
+        for (;;) {
+            if (!stack.length) { result = value; break; }
+            const frame = stack[stack.length - 1];
+            if (frame.object) {
+                if (Object.hasOwn(frame.value, frame.key)) frame.duplicate = true;
+                frame.value[frame.key] = value;
+            } else frame.value.push(value);
+            skip();
+            if (text[pos] === ',') {
+                pos++; skip();
+                if (frame.object) frame.key = key();
+                break;
+            }
+            if (text[pos] !== (frame.object ? '}' : ']')) throw fail("Expecting ',' delimiter");
+            pos++;
+            stack.pop();
+            // `_pairs` runs when the object closes, after everything inside it parsed.
+            if (frame.object && frame.duplicate) throw new ProjectionError('Duplicate JSON key');
+            value = frame.value;
+        }
+        if (!stack.length) break;
+    }
+    skip();
+    if (pos !== text.length) throw fail('Extra data');
+    return result;
+}
+
+/** `_normalize`: walk once; unretained values are only checked against the depth bound. */
+function normalize(value, depth, retain) {
+    if (!isContainer(value)) return retain ? value : null;
+    if (depth > MAX_PROJECTION_DEPTH) throw new ProjectionLimit();
+    if (isArray(value)) {
+        const result = retain ? [] : null;
+        for (const child of value) {
+            const normalized = normalize(child, depth + 1, retain);
+            if (retain) result.push(normalized);
+        }
+        return result;
+    }
+    const result = retain ? Object.create(null) : null;
+    for (const key of Object.keys(value)) {
+        const normalized = normalize(value[key], depth + 1, retain);
+        if (retain) result[key] = normalized;
+    }
+    return result;
+}
+
+/** `_project_prompt`: each API node keeps exactly `class_type` and `inputs`; other keys are validated and dropped. */
+function projectPrompt(tree, depth) {
+    if (!isObject(tree)) throw new ProjectionError('Prompt graph must be an object of nodes');
+    if (depth + 1 > MAX_PROJECTION_DEPTH) throw new ProjectionLimit();
+    const result = Object.create(null);
+    for (const id of Object.keys(tree)) {
+        const node = tree[id];
+        if (!isObject(node)) {
+            result[id] = normalize(node, depth + 1, true);
+            continue;
+        }
+        const projected = Object.create(null);
+        for (const key of Object.keys(node)) {
+            const keep = PROMPT_NODE_KEYS.has(key);
+            const normalized = normalize(node[key], depth + 2, keep);
+            if (keep) projected[key] = normalized;
+        }
+        result[id] = projected;
+    }
+    return result;
+}
+
+function project(tree, kind, depth) {
+    if (kind === 'prompt') return projectPrompt(tree, depth);
+    if (kind === 'workflow') return normalize(tree, depth, true);
+    if (!isObject(tree)) throw new ProjectionError('Malformed carrier');
+    const result = Object.create(null);
+    for (const key of Object.keys(tree)) {
+        const member = tree[key];
+        if (key !== 'prompt' && key !== 'workflow') normalize(member, depth + 1, false);
+        else if (typeof member === 'string') result[key] = member; // projected by its own kind when read
+        else if (key === 'prompt' && !isObject(member)) result[key] = normalize(member, depth + 1, true);
+        else result[key] = project(member, key, depth + 1);
+    }
+    return result;
+}
+
+/** `_strict_projection`: parse exactly and project by record kind ('prompt'|'workflow'|'carrier'). */
+export function strictProjection(text, kind) {
+    return project(parseStrictJson(text), kind, 1);
+}
+
+function nodeCount(value, workflow) {
+    if (!workflow) return Object.keys(value).length;
+    const nodes = value.nodes;
+    let count = isArray(nodes) ? nodes.length : 0;
+    const definitions = value.definitions;
+    const subgraphs = isObject(definitions) ? definitions.subgraphs : null;
+    for (const subgraph of isArray(subgraphs) ? subgraphs : []) {
+        const inner = isObject(subgraph) ? subgraph.nodes : null;
+        count += isArray(inner) ? inner.length : 0;
+    }
+    return count;
+}
+
+function graph(value, workflow) {
+    if (!isObject(value)) return { status: 'malformed', value: null };
+    if (nodeCount(value, workflow) > GRAPH_NODE_CEILING) return { status: 'limited', value: null };
+    return { status: 'parsed', value };
+}
+
+function outcome(error) {
+    if (error instanceof ProjectionLimit) return { status: 'limited', value: null };
+    if (error instanceof ProjectionError) return { status: 'malformed', value: null };
+    throw error;
+}
+
+/**
+ * One record's graph as the inspector projects it: `{status, value}` with `status`
+ * `parsed` (the projected graph the facts parser receives), `limited` (past the
+ * depth or node bound) or `malformed`.
+ */
+export function projectGraph(text, kind) {
+    try {
+        return graph(strictProjection(text, kind), kind === 'workflow');
+    } catch (error) {
+        return outcome(error);
+    }
+}
+
+/**
+ * `_metadata` for one local read: `{records, record_formats, carrierText, limited}`
+ * (the server's InspectionRead) or null when the file's metadata is unreadable.
+ */
+export function projectMetadata(inspection) {
+    const formats = {}, raw = {};
+    if (inspection) {
+        for (const [key, value] of Object.entries(inspection.record_formats ?? {})) {
+            if (RECORD_KEYS.includes(key) && FORMATS.has(value)) formats[key] = value;
+        }
+        // A record over its read budget has no text: like `invalid`, raw omits it,
+        // and its graph is `limited` rather than parsed from nothing.
+        for (const key of inspection.limited ?? []) if (RECORD_KEYS.includes(key)) formats[key] = 'limited';
+        for (const [key, value] of Object.entries(inspection.records ?? {})) {
+            if (RECORD_KEYS.includes(key) && typeof value === 'string' && formats[key] !== 'limited') raw[key] = value;
+        }
+    }
+    const result = {
+        status: inspection === null || inspection === undefined ? 'unreadable' : Object.keys(raw).length || Object.keys(formats).length ? 'available' : 'absent',
+        omitted_reason: null, raw, record_formats: formats, parameters: Object.hasOwn(raw, 'parameters') ? raw.parameters : null,
+    };
+    let carrier = null, failed = null;
+    if (inspection && inspection.carrierText !== null && inspection.carrierText !== undefined) {
+        try { carrier = strictProjection(inspection.carrierText, 'carrier'); } catch (error) { failed = outcome(error).status; }
+    }
+    for (const [key, field] of [['prompt', 'prompt_graph'], ['workflow', 'workflow_graph']]) {
+        let value = { status: 'absent', value: null };
+        if (Object.hasOwn(raw, key) || Object.hasOwn(formats, key)) {
+            if (failed || formats[key] === 'limited') value.status = failed || 'limited';
+            else if (formats[key] === 'invalid') value.status = 'malformed';
+            else if (carrier === null && formats[key] === 'reserialized-json') value.status = 'limited';
+            else if (carrier === null) value = projectGraph(raw[key], key);
+            else {
+                try {
+                    let member = carrier[key];
+                    if (typeof member === 'string') member = strictProjection(member, key);
+                    value = graph(member, key === 'workflow');
+                } catch (error) { value.status = outcome(error).status; }
+            }
+        }
+        result[field] = value;
+    }
+    return result;
+}
+
+const UTF8 = new TextEncoder();
+const MEASURE_CHUNK_BYTES = 256 * 1024;
+
+/**
+ * UTF-8 length of `JSON.stringify(value)`: the server's `_bytes` count. The text
+ * holds no lone surrogate (JSON.stringify escapes them), so the encoder's count is
+ * exact; it encodes into one bounded scratch buffer and never splits a pair.
+ */
+export function inspectionBytes(value) {
+    const text = JSON.stringify(value);
+    const scratch = new Uint8Array(Math.min(MEASURE_CHUNK_BYTES, text.length * 3 + 4));
+    let count = 0;
+    for (let offset = 0; offset < text.length; ) {
+        const { read, written } = UTF8.encodeInto(offset ? text.slice(offset) : text, scratch);
+        offset += read;
+        count += written;
+    }
+    return count;
+}
+
+const withMetadata = (payload, changes) => ({ ...payload, metadata: { ...payload.metadata, ...changes } });
+
+function defaultYield() {
+    return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+/**
+ * The omission steps of `_encode_inspection`: the workflow graph first, then the
+ * prompt graph, then all raw records atomically, each measured as encoded bytes.
+ * Each re-measure of a multi-megabyte payload follows a `yieldControl` turn, and
+ * `signal` aborts between steps. Resolves to a new payload; rejects when even the
+ * bare payload is over `limit`.
+ */
+export async function fitInspectionPayload(payload, limit = MAX_RESPONSE_BYTES, { yieldControl = defaultYield, signal } = {}) {
+    const measure = async (candidate) => {
+        await yieldControl();
+        if (signal && signal.aborted) throw new DOMException('The inspection was aborted', 'AbortError');
+        return inspectionBytes(candidate);
+    };
+    let fitted = payload, body = inspectionBytes(payload);
+    for (const field of ['workflow_graph', 'prompt_graph']) {
+        if (body <= limit) break;
+        if (fitted.metadata[field].status !== 'absent') {
+            fitted = withMetadata(fitted, { [field]: { status: 'limited', value: null } });
+            body = await measure(fitted);
+        }
+    }
+    if (body > limit) {
+        fitted = withMetadata(fitted, { raw: {}, parameters: null, status: 'limited', omitted_reason: 'response-size-limit' });
+        body = await measure(fitted);
+    }
+    if (body > limit) throw new RangeError('Inspection response exceeds limits');
+    return fitted;
+}

web/js/workspace/toolbar.mjs

@@ -107,7 +107,10 @@ export function mountToolbar(container, { scope, categories = [], sorts, value =
         category.value = [...category.options].some(node => node.value === selected) ? selected : '';
     }
     function setActiveFilters(count) {
-        filters.textContent = filtersLabel(count);
+        const next = filtersLabel(count);
+        // Every listing reload reports the count; only a changed label rewrites the text node, because WebKit drops a
+        // click whose mousedown hit a text node that was replaced before mouseup.
+        if (filters.textContent !== next) filters.textContent = next;
     }
     setValue(value);
 

web/js/workspace/vocabulary-state.mjs

@@ -16,7 +16,8 @@ import { countOf } from './plural.mjs';
 const LIMIT = 100;
 const BASE = '/prompt_manager/vocabulary';
 const KINDS = {
-    tags: {key: row => row.id, valid: row => id(row.id) && typeof row.name === 'string' && row.name.length > 0},
+    // image_count (#249 image tags) is optional until every server reports it.
+    tags: {key: row => row.id, valid: row => id(row.id) && typeof row.name === 'string' && row.name.length > 0 && optionalCount(row.image_count)},
     categories: {key: row => row.value, valid: row => typeof row.value === 'string' && row.value.length > 0},
 };
 const RECOVERY = {'storage-changed': 'storage-changed', 'vocabulary-conflict': 'conflict'};
@@ -29,6 +30,7 @@ const IMPACT_FIELDS = ['positive_prompts', 'other_prompts', 'negative_variants',
 const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
 const id = value => Number.isSafeInteger(value) && value > 0;
 const count = value => Number.isSafeInteger(value) && value >= 0;
+const optionalCount = value => value === undefined || count(value);
 const epochOf = value => typeof value === 'string' && /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/.test(value);
 const hexToken = value => typeof value === 'string' && /^[0-9a-f]{64}$/.test(value);
 
@@ -108,7 +110,7 @@ export function createVocabularyStream({api, kind, onChange = () => {}}) {
 }
 
 function validateTag(value) {return object(value) && KINDS.tags.valid(value) && count(value.prompt_count);}
-function validateImpact(value) {return object(value) && IMPACT_FIELDS.every(name => count(value[name]));}
+function validateImpact(value) {return object(value) && IMPACT_FIELDS.every(name => count(value[name])) && optionalCount(value.images);}
 function requireRow(row) {requireValue(object(row) && id(row.id) && typeof row.name === 'string', 'Invalid tag row');}
 function requireEpoch(epoch) {requireValue(epochOf(epoch), 'Invalid library epoch');}
 function requireText(value, name) {requireValue(typeof value === 'string', `${name} must be a string`);}
@@ -116,8 +118,9 @@ function requireText(value, name) {requireValue(typeof value === 'string', `${na
 const RECEIPTS = {
     'create-tag': value => typeof value.created === 'boolean' && validateTag(value.tag),
     'rename-tag': value => typeof value.merged === 'boolean' && validateTag(value.tag) &&
-        count(value.components_changed) && count(value.pairs_changed),
-    'delete-tag': value => value.deleted === true && count(value.components_changed) && count(value.pairs_changed),
+        count(value.components_changed) && count(value.pairs_changed) && optionalCount(value.images_changed),
+    'delete-tag': value => value.deleted === true && count(value.components_changed) && count(value.pairs_changed) &&
+        optionalCount(value.images_changed),
     'apply-category': (value, body) => value.source === body.source && value.target === body.target &&
         typeof value.consolidated === 'boolean' && validateImpact(value.impact),
 };
@@ -270,6 +273,7 @@ function impactList(impact) {
         parts.push(`${countOf(negatives, 'negative variant')}${archived}`);
     }
     if (impact.other_prompts) parts.push(countOf(impact.other_prompts, 'other saved prompt'));
+    if (impact.images) parts.push(countOf(impact.images, 'image'));
     return parts.length > 1 ? `${parts.slice(0, -1).join(', ')} and ${parts.at(-1)}` : parts.join('');
 }
 
@@ -282,6 +286,6 @@ export function categoryPreviewText(shown) {
 /** The Delete tag confirmation sentence (decision D14). */
 export function deleteTagText(name, impact) {
     const list = impactList(impact);
-    if (!list) return `“${name}” is not linked to any saved prompt. Deleting it removes only the name.`;
+    if (!list) return `“${name}” is not linked to any saved prompt or image. Deleting it removes only the name.`;
     return `Deleting “${name}” removes the name and its links from ${list}. The prompts, negative variants, images and history themselves are kept.`;
 }