fix(library): restore a shelf left before its first page answered

Leaving the Library while its first page was still loading (or after it
failed) saved a stream with no variant total. Returning to the shelf in
the same page restored that state, the restore validation rejected the
null variant total, and mounting threw "Invalid library page" as an
uncaught page error, leaving the shelf empty.

A saved state with no page yet (no items, no cursor, total 0, more to
load) now restores as a fresh stream, and the shelf reads page one as
it already does for a restored loading or failed state. Any other saved
state still goes through the full page validation.

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,83 @@ 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
+Images Tags filter (a file matches when every tag is on its linked positive or
+its current image tag set) and `q` search stream the tagged records once and
+stat only the listed files whose records carry a filter tag or a `q` hit; the
+inspector's `image_tags` facet (`current` / `none` / `unavailable`) uses the
+inspection's own stable stat (`tests/test_api_workspace_images.py`
+`TestWorkspaceImageTags`, `tests/test_api_prompt_inspector.py`). 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`).
+A case or Unicode spelling of a listed name (`A.PNG` for `a.png`, an NFD name)
+is an alias too: each path part must be spelled as its directory lists it, so a
+case- or normalization-insensitive filesystem (macOS, Windows) cannot store a
+second locator. The capture preview answers one byte range with 206 (416 for
+an unsatisfiable or multi-range header) inside the capture's pin, and a
+cancelled preview, observe or Generate still closes its handle and ends its pin
+or capture (`tests/test_api_annotations.py` `TestCancellation`,
+`tests/test_model_gate.py`).
+
+Follow-ups (tracked, not accepted): the legacy Auto-tag batch's cleanup
+`unload_model()` in `py/api/autotag_routes.py` is not gated against the
+batch's own in-flight inference when the batch coroutine is cancelled (other
+owners are kept out; the thread may log an error); and `py/autotag.py`,
+`py/api/images.py` and `database/operations.py` are over the 800-line ceiling
+(all three were before #249 PR B), with a split of `py/autotag.py` into
+backends and service planned first.
+
 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 +1756,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

__init__.py

@@ -90,6 +90,7 @@ try:
     host_app = getattr(config.server_instance, "app", None)
     if host_app is not None and hasattr(host_app, "on_cleanup"):
         host_app.on_cleanup.append(api.cleanup_history_reads)
+        host_app.on_cleanup.append(api.cleanup_annotation_captures)
 
 except Exception as e:
     # Log to internal logging system without console spam

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,461 @@
+"""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
+
+
+class ImageTagLimitError(ValueError):
+    """More than ``MAX_IMAGE_TAGS`` distinct names in one set."""
+
+
+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, and its subclass
+    ``ImageTagLimitError`` 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 ImageTagLimitError(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
@@ -231,6 +232,23 @@ JOIN prompts p ON p.id = COALESCE(pp.positive_prompt_id, gi.prompt_id)
 WHERE gi.file_path IS NOT NULL AND CASE WHEN {admit} THEN NOT EXISTS (
     SELECT 1 FROM generated_images other
     WHERE other.file_path = gi.file_path AND other.id <> gi.id) ELSE 0 END"""
+# The linked positive of each given path (one unambiguous link, pair scope as
+# in _LINK_FILTER_SQL) with its category; {hit} as in link_filter_query. Used
+# for the few files whose current image tags meet a Tags filter (#249 B3).
+_LINK_FACTS_SQL = """SELECT gi.file_path, p.rating, {hit}, p.id, p.category
+FROM generated_images gi
+LEFT JOIN prompt_pairs pp ON pp.id = (
+    SELECT CASE WHEN COUNT(DISTINCT ip.pair_id) = 1 THEN MIN(ip.pair_id) END
+    FROM image_prompt_pairs ip WHERE ip.image_id = gi.id)
+JOIN prompts p ON p.id = COALESCE(pp.positive_prompt_id, gi.prompt_id)
+WHERE gi.file_path IN ({marks}) AND NOT EXISTS (
+    SELECT 1 FROM generated_images other
+    WHERE other.file_path = gi.file_path AND other.id <> gi.id)"""
+_POSITIVE_TAG_NAMES_SQL = (
+    "SELECT pt.prompt_id, t.name FROM prompt_tags pt JOIN tags t "
+    "ON t.id = pt.tag_id WHERE pt.prompt_id IN ({marks})"
+)
+_FACTS_CHUNK = 500
 # The positive's text, its Library title or one of its tag names contains
 # :pattern (LIKE, so ASCII case is ignored as in Library search). A pair's own
 # title names its negative variant and is never searched (#249 D12).
@@ -322,6 +340,7 @@ class PromptDatabase(
     ExecutionOutputOperations,
     HistoryReadOperations,
     ImageFavoriteOperations,
+    AnnotationOperations,
     SavedViewOperations,
 ):
     """Database operations class for managing prompts."""
@@ -1084,16 +1103,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 +1188,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 +1230,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 +1283,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
@@ -2420,6 +2467,46 @@ class PromptDatabase(
                     matches[path] = (bool(matched), rating, positive)
         return matches
 
+    def get_image_link_facts(
+        self, paths: List[str], q: str = ""
+    ) -> Dict[str, Tuple[bool, Optional[int], int, Optional[str], Tuple[str, ...]]]:
+        """Map each normalized path with one unambiguous link to its positive's
+        (hit, rating, positive id, category, tag names).
+
+        The link is resolved as in get_image_link_matches, and ``hit`` says
+        whether *q* occurs in the positive's text, Library title or a tag
+        name (always true without *q*). Paths go in chunks of 500 through the
+        ``file_path`` index; the tag names are read for those positives only.
+        """
+        hit, params = "1", {}
+        if q:
+            hit = _LINK_FILTER_HIT
+            params["pattern"] = f"%{escape_like(q)}%"
+        rows: Dict[str, Tuple[bool, Optional[int], int, Optional[str]]] = {}
+        names: Dict[int, List[str]] = {}
+        unique = list(dict.fromkeys(paths))
+        with self.model.get_connection() as conn:
+            for start in range(0, len(unique), _FACTS_CHUNK):
+                chunk = unique[start : start + _FACTS_CHUNK]
+                bound = {f"path{i}": path for i, path in enumerate(chunk)}
+                marks = ",".join(f":{key}" for key in bound)
+                sql = _LINK_FACTS_SQL.format(hit=hit, marks=marks)
+                for path, rating, matched, positive, category in conn.execute(
+                    sql, {**params, **bound}
+                ):
+                    rows[path] = (bool(matched), rating, positive, category)
+            positives = sorted({row[2] for row in rows.values()})
+            for start in range(0, len(positives), _FACTS_CHUNK):
+                chunk = positives[start : start + _FACTS_CHUNK]
+                marks = ",".join("?" * len(chunk))
+                for positive, name in conn.execute(
+                    _POSITIVE_TAG_NAMES_SQL.format(marks=marks), chunk
+                ):
+                    names.setdefault(positive, []).append(name)
+        return {
+            path: (*row, tuple(names.get(row[2], ()))) for path, row in rows.items()
+        }
+
     def get_image_paths_matching(
         self, q: str, category: Optional[str], tags: List[str]
     ) -> Set[str]:

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.

py/api/__init__.py

@@ -26,6 +26,7 @@ from .prompts import PromptRoutesMixin
 from .pairs import PairRoutesMixin
 from .library import LibraryRoutesMixin
 from .vocabulary import VocabularyRoutesMixin
+from .annotations import AnnotationRoutesMixin
 from .saved_views import SavedViewRoutesMixin
 from .history import HistoryRoutesMixin
 from .images import ImageRoutesMixin
@@ -252,6 +253,7 @@ class PromptManagerAPI(
     PairRoutesMixin,
     LibraryRoutesMixin,
     VocabularyRoutesMixin,
+    AnnotationRoutesMixin,
     SavedViewRoutesMixin,
     HistoryRoutesMixin,
     PromptRoutesMixin,
@@ -285,6 +287,10 @@ class PromptManagerAPI(
         self.db = db if db is not None else PromptDatabase()
         self._history_read_fence = None
         self._history_reads_closed = False
+        # Private media captures of the annotation routes (py/api/annotations.py),
+        # created on first use with their restore subscription.
+        self._captures = None
+        self._captures_unsubscribe = None
         self._cached_output_dir = None  # Lazy-cached by _find_comfyui_output_dir()
         self._html_cache = {}  # Cached HTML file contents keyed by path
         self._gallery_cache = {}  # dict: path_str -> (files, timestamp)
@@ -441,6 +447,7 @@ class PromptManagerAPI(
         self._register_pair_routes(routes)
         self._register_library_routes(routes)
         self._register_vocabulary_routes(routes)
+        self._register_annotation_routes(routes)
         self._register_saved_view_routes(routes)
         self._register_history_routes(routes)
         self._register_prompt_routes(routes)

py/api/annotation_suggest.py

@@ -0,0 +1,121 @@
+"""Request validation and the worker of the Tag dialog's Generate (#249 B2).
+
+``POST /prompt_manager/image-annotations/suggest`` asks one of legacy's four
+engines for the top N tags of a captured image. Options are validated
+strictly, per engine: WD14 classifiers take two thresholds, the language
+models (GGUF and HuggingFace JoyCaption) take the instructions; every engine
+takes the suggestion count and the GPU switch. Nothing here touches the
+filesystem or the database.
+"""
+
+import math
+
+WD14_MODELS = frozenset({"wd14-swinv2", "wd14-vit"})
+LLM_MODELS = frozenset({"gguf", "hf"})
+MODEL_TYPES = WD14_MODELS | LLM_MODELS
+
+MAX_INSTRUCTION_CHARS = 4000
+MAX_INSTRUCTION_BYTES = 16 * 1024
+
+SUGGEST_FIELDS = frozenset(
+    {"target", "capture_token", "expected_epoch", "model_type", "options"}
+)
+_COMMON = frozenset({"suggestion_limit", "use_gpu"})
+_WD14_REQUIRED = frozenset({"general_threshold", "character_threshold"})
+_LLM_REQUIRED = frozenset({"instructions"})
+
+UNAVAILABLE_HINT = "Download it from the legacy Auto-tag page."
+
+
+class OptionError(ValueError):
+    """A suggest request whose model type or options are not acceptable."""
+
+
+def _threshold(name: str, value) -> float:
+    if type(value) not in (int, float) or not math.isfinite(value):
+        raise OptionError(f"{name} must be a finite number")
+    if not 0 <= value <= 1:
+        raise OptionError(f"{name} must be between 0 and 1")
+    return float(value)
+
+
+def _instructions(value) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise OptionError("instructions must be non-empty text")
+    if len(value) > MAX_INSTRUCTION_CHARS:
+        raise OptionError(
+            f"instructions must be at most {MAX_INSTRUCTION_CHARS} characters"
+        )
+    try:
+        encoded = value.encode("utf-8")
+    except UnicodeEncodeError:
+        raise OptionError("instructions must be valid Unicode text") from None
+    if len(encoded) > MAX_INSTRUCTION_BYTES:
+        raise OptionError("instructions are too long")
+    return value
+
+
+def validate_options(model_type, options, *, default_limit: int, max_limit: int):
+    """Normalised ``(model_type, options)`` or :class:`OptionError`.
+
+    The answer echoes every option the request will run with, the defaults
+    (suggestion count from the settings, GPU on) filled in.
+    """
+    if not isinstance(model_type, str) or model_type not in MODEL_TYPES:
+        raise OptionError("model_type must be one of " + ", ".join(sorted(MODEL_TYPES)))
+    if not isinstance(options, dict):
+        raise OptionError("options must be an object")
+    required = _WD14_REQUIRED if model_type in WD14_MODELS else _LLM_REQUIRED
+    keys = set(options)
+    if not required <= keys or not keys <= required | _COMMON:
+        raise OptionError(
+            f"options for {model_type} take exactly "
+            + ", ".join(sorted(required))
+            + " and optionally "
+            + ", ".join(sorted(_COMMON))
+        )
+    limit = options.get("suggestion_limit", default_limit)
+    if type(limit) is not int or not 1 <= limit <= max_limit:
+        raise OptionError(f"suggestion_limit must be an integer from 1 to {max_limit}")
+    use_gpu = options.get("use_gpu", True)
+    if not isinstance(use_gpu, bool):
+        raise OptionError("use_gpu must be true or false")
+    normalised = {"use_gpu": use_gpu, "suggestion_limit": limit}
+    if model_type in WD14_MODELS:
+        for name in sorted(_WD14_REQUIRED):
+            normalised[name] = _threshold(name, options[name])
+    else:
+        normalised["instructions"] = _instructions(options["instructions"])
+    return model_type, normalised
+
+
+def unavailable_message(model_name: str) -> str:
+    return f"{model_name} is not downloaded. {UNAVAILABLE_HINT}"
+
+
+def run_suggestions(service, capture_path: str, model_type: str, options: dict):
+    """Blocking: load (or swap to) *model_type*, then suggest for the capture.
+
+    The caller holds the model gate for the whole call; nothing is ever
+    downloaded (``load_model`` refuses a model that is not on disk).
+    """
+    if not service.is_model_loaded() or service.get_loaded_model_type() != model_type:
+        service.load_model(model_type, options["use_gpu"])
+    return service.generate_tag_suggestions(
+        capture_path,
+        limit=options["suggestion_limit"],
+        prompt=options.get("instructions"),
+        general_threshold=options.get("general_threshold"),
+        character_threshold=options.get("character_threshold"),
+    )
+
+
+def suggestion_rows(pairs) -> list:
+    """``[{name, confidence}]``; a non-finite score is reported as unknown."""
+    rows = []
+    for name, score in pairs:
+        confidence = None
+        if score is not None and math.isfinite(score):
+            confidence = float(score)
+        rows.append({"name": str(name), "confidence": confidence})
+    return rows

py/api/annotations.py

@@ -0,0 +1,759 @@
+"""Image annotation routes: observe, capture preview and byte-exact tag saves.
+
+Every route names its file through the listing identity ``{root_index,
+root_scope, path}`` and checks the scope against the current gallery roots
+before any file access. Observe copies the file into a private capture (the
+token the preview and Save refer to), Save re-hashes the current file and
+writes only when the bytes are still the captured ones. Responses carry no
+server path and no locator.
+"""
+
+import asyncio
+import datetime
+import functools
+import os
+import re
+from pathlib import Path
+
+from aiohttp import web
+
+from .annotation_suggest import (
+    SUGGEST_FIELDS,
+    OptionError,
+    run_suggestions,
+    suggestion_rows,
+    unavailable_message,
+    validate_options,
+)
+from .autotag_routes import model_busy_response
+from .images import _forbidden, _has_traversal, _unavailable_link, _verified_title
+from .prompts import bad_request
+from .. import model_gate
+
+try:
+    from ...database.annotations import (
+        MAX_IMAGE_TAGS,
+        AnnotationCommandError,
+        ImageTagLimitError,
+        normalize_image_tags,
+    )
+    from ...database.execution_history import subscribe_history_restore
+    from ...database.library_commands import LibraryCommandError
+    from ...utils.media_capture import CAPTURE_EXTENSIONS, CaptureError, CaptureStore
+except ImportError:
+    from database.annotations import (
+        MAX_IMAGE_TAGS,
+        AnnotationCommandError,
+        ImageTagLimitError,
+        normalize_image_tags,
+    )
+    from database.execution_history import subscribe_history_restore
+    from database.library_commands import LibraryCommandError
+    from utils.media_capture import CAPTURE_EXTENSIONS, CaptureError, CaptureStore
+
+# Request bodies of the annotation routes are small (a target plus a tag set).
+MAX_BODY_BYTES = 64 * 1024
+MAX_TARGET_PATH = 1024
+CAPTURE_URL = "/prompt_manager/image-annotations/capture/"
+_PREVIEW_CHUNK = 64 * 1024
+
+_TARGET_FIELDS = frozenset({"root_index", "root_scope", "path"})
+_OBSERVE_FIELDS = frozenset({"target"})
+_SAVE_FIELDS = frozenset(
+    {
+        "target",
+        "capture_token",
+        "sha256",
+        "expected_epoch",
+        "expected_tag_revision",
+        "tags",
+    }
+)
+_HEX64 = re.compile(r"[0-9a-f]{64}")
+_UUID = re.compile(r"[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}")
+# secrets.token_urlsafe(32) is 43 characters; the bound only rejects junk.
+_TOKEN = re.compile(r"[A-Za-z0-9_-]{1,128}")
+
+_PREVIEW_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".bmp": "image/bmp",
+    ".tiff": "image/tiff",
+    ".tif": "image/tiff",
+    ".mp4": "video/mp4",
+    ".m4v": "video/mp4",
+    ".webm": "video/webm",
+    ".mov": "video/quicktime",
+    ".mkv": "video/x-matroska",
+    ".avi": "video/x-msvideo",
+    ".wmv": "video/x-ms-wmv",
+}
+
+_STATUS = {
+    "review-capacity": 429,
+    "unsupported-media": 415,
+    "file-changed": 409,
+    "source-changed": 409,
+    "storage-changed": 409,
+    "tag-conflict": 409,
+    "capture-expired": 409,
+    "model-unavailable": 409,
+    "tag-limit": 400,
+    "metadata-conflict": 409,
+    "vocabulary-conflict": 409,
+}
+_MESSAGES = {
+    "source-changed": (
+        "The source changed. Refresh the image collection before tagging this file."
+    ),
+    "file-changed": "The file changed since it was previewed. Reopen the Tag dialog.",
+    "review-capacity": "Too many previews are open. Close a Tag dialog and try again.",
+    "storage-changed": "Prompt storage was restored; reopen the Tag dialog.",
+    "tag-conflict": (
+        "The tags of this image changed since the dialog opened; review them first."
+    ),
+    "capture-expired": "The preview expired. Open the Tag dialog again.",
+    "tag-limit": f"An image can carry at most {MAX_IMAGE_TAGS} tags.",
+}
+# Any other storage code (a conflict a later command adds) still answers a
+# coded envelope rather than a bare 500.
+_DEFAULT_STATUS = 409
+_DEFAULT_MESSAGE = "The tags could not be saved. Reopen the Tag dialog and try again."
+_OTHER_FILE = "The preview belongs to another file. Open the Tag dialog again."
+
+
+def preview_content_type(extension: str) -> str:
+    """The media type the preview is served as; never sniffed from bytes."""
+    return _PREVIEW_TYPES.get(extension.lower(), "application/octet-stream")
+
+
+def _error(status: int, code: str, message: str, **extra) -> web.Response:
+    return web.json_response(
+        {"success": False, "code": code, "error": message, **extra},
+        status=status,
+        headers={"Cache-Control": "no-store"},
+    )
+
+
+def _coded(code: str, message: str | None = None, **extra) -> web.Response:
+    status = _STATUS.get(code, _DEFAULT_STATUS)
+    return _error(
+        status, code, message or _MESSAGES.get(code, _DEFAULT_MESSAGE), **extra
+    )
+
+
+def _open_capture(path: str):
+    """Worker thread: the capture file opened for reading."""
+    return open(path, "rb")
+
+
+async def _settled(future, cleanup):
+    """Await an executor *future*; a cancelled caller still cleans up after it.
+
+    The future is shielded, so the worker call always runs to its end. When the
+    caller is cancelled first, ``cleanup(result)`` runs once the call is done
+    (``cleanup(None)`` when it failed): a handle is closed, a capture released.
+    """
+    try:
+        return await asyncio.shield(future)
+    except asyncio.CancelledError:
+        future.add_done_callback(functools.partial(_cleanup_result, cleanup))
+        raise
+
+
+def _cleanup_result(cleanup, future) -> None:
+    if future.cancelled() or future.exception() is not None:
+        cleanup(None)
+    else:
+        cleanup(future.result())
+
+
+def _submit(func, *args, **kwargs):
+    return asyncio.get_running_loop().run_in_executor(
+        None, functools.partial(func, *args, **kwargs)
+    )
+
+
+def _capture_error(exc: CaptureError) -> web.Response:
+    """The envelope for a capture outcome; messages never name a path."""
+    if exc.code not in _STATUS:
+        return _error(500, exc.code, "The file could not be captured.")
+    return _coded(exc.code, _MESSAGES.get(exc.code) or str(exc))
+
+
+def _target(data: object):
+    """``((index, scope, relative), None)`` for a target, else ``(None, error)``.
+
+    Only the listing identity is accepted: an int root index, the root's
+    64-hex scope and a bounded root-relative POSIX media path, never an
+    absolute, drive-qualified, backslash or ``..`` path. Nothing here touches
+    the filesystem or the database.
+    """
+    if not isinstance(data, dict) or set(data) != _TARGET_FIELDS:
+        return None, bad_request("target must name root_index, root_scope and path")
+    index, scope, relative = data["root_index"], data["root_scope"], data["path"]
+    if type(index) is not int or index < 0:
+        return None, bad_request("Invalid gallery root")
+    if not isinstance(scope, str) or _HEX64.fullmatch(scope) is None:
+        return None, bad_request("Invalid gallery root scope")
+    if not isinstance(relative, str) or not relative or len(relative) > MAX_TARGET_PATH:
+        return None, bad_request("path must be a relative media path")
+    parts = relative.split("/")
+    if (
+        "\0" in relative
+        or "\\" in relative
+        or relative.startswith("/")
+        or _has_traversal(relative)
+        or any(part in ("", ".", "..") or ":" in part for part in parts)
+    ):
+        return None, _forbidden()
+    if os.path.splitext(parts[-1])[1].lower() not in CAPTURE_EXTENSIONS:
+        return None, _forbidden("Only media files can be tagged")
+    return (index, scope, relative), None
+
+
+def _expires_at(seconds: float | None) -> str:
+    moment = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(
+        seconds=max(0.0, seconds or 0.0)
+    )
+    return moment.replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def _capture_info(store: CaptureStore, capture) -> dict:
+    return {
+        "token": capture.token,
+        "expires_at": _expires_at(store.expires_in(capture.token)),
+        "preview_url": CAPTURE_URL + capture.token,
+        "sha256": capture.sha256,
+        "size": capture.size,
+        "width": capture.width,
+        "height": capture.height,
+        "media_type": capture.media_type,
+        "generate": {
+            "supported": capture.inferable,
+            "reason": capture.inferable_reason,
+        },
+    }
+
+
+class AnnotationRoutesMixin:
+    """Observe, capture preview and tag save routes over PR A's storage."""
+
+    def _register_annotation_routes(self, routes: web.RouteTableDef) -> None:
+        routes.post("/prompt_manager/image-annotations/observe")(self.observe_image)
+        routes.get(CAPTURE_URL + "{token}")(self.get_capture_preview)
+        routes.delete(CAPTURE_URL + "{token}")(self.release_capture)
+        routes.put("/prompt_manager/image-annotations/tags")(self.save_image_tags)
+        routes.post("/prompt_manager/image-annotations/suggest")(
+            self.suggest_image_tags
+        )
+
+    # -- capture store lifetime ------------------------------------------------
+
+    def _capture_store(self) -> CaptureStore:
+        """The process's capture store, created on first use.
+
+        Created lazily so an API object that never observes a file (most tests,
+        a server that never opens the Tag dialog) owns no temp directory. A
+        restore of the database dooms every capture (``invalidate_all``).
+        """
+        if self._captures is None:
+            self._captures = CaptureStore()
+        if self._captures_unsubscribe is None:
+            self._captures_unsubscribe = subscribe_history_restore(
+                self.db.model.db_path, self._invalidate_captures
+            )
+        return self._captures
+
+    def _invalidate_captures(self) -> None:
+        store = self._captures
+        if store is not None:
+            store.invalidate_all()
+
+    def close_annotation_captures(self) -> None:
+        """Remove every capture file and the owned directory. Idempotent."""
+        unsubscribe, self._captures_unsubscribe = self._captures_unsubscribe, None
+        if unsubscribe is not None:
+            unsubscribe()
+        store, self._captures = self._captures, None
+        if store is not None:
+            store.close()
+
+    async def cleanup_annotation_captures(self, app: web.Application) -> None:
+        self.close_annotation_captures()
+
+    # -- shared request steps --------------------------------------------------
+
+    async def _annotation_body(self, request: web.Request, fields: frozenset):
+        data, error = await self._read_json_body(request, max_bytes=MAX_BODY_BYTES)
+        if error is not None:
+            return None, error
+        if set(data) != fields:
+            return None, bad_request(
+                "Request must contain exactly " + ", ".join(sorted(fields))
+            )
+        return data, None
+
+    def _scoped_root(self, index: int, scope: str):
+        """``(root, None)`` when the scope names a current root, else an error."""
+        roots = list(self._get_all_output_dirs())
+        error = self._gallery_scope_error(
+            {"root_scope": scope, "root": str(index)}, roots
+        )
+        if error is not None:
+            if error.status == 409:
+                return None, _coded("source-changed")
+            return None, error
+        return roots[index], None
+
+    # -- observe ---------------------------------------------------------------
+
+    async def observe_image(self, request: web.Request) -> web.Response:
+        """POST ``{target}``: capture the file and answer its saved tag set.
+
+        The capture is the byte-exact copy the preview and Save refer to; the
+        tags are those of exactly these bytes (an empty set at revision 0 for
+        unseen bytes). Observing never writes tags; equal bytes refresh the
+        record's verified fingerprint (S1).
+        """
+        data, error = await self._annotation_body(request, _OBSERVE_FIELDS)
+        if error is not None:
+            return error
+        target, error = _target(data["target"])
+        if error is not None:
+            return error
+        index, scope, relative = target
+        root, error = self._scoped_root(index, scope)
+        if error is not None:
+            return error
+        store = self._capture_store()
+        try:
+            epoch = await self._run_in_executor(self.db.get_execution_epoch)
+            capture = await _settled(
+                _submit(
+                    store.capture,
+                    root,
+                    relative,
+                    epoch=epoch,
+                    scope=scope,
+                    root_index=index,
+                ),
+                # A cancelled observe never hands its capture out: release it.
+                lambda made: made is not None and store.release(made.token),
+            )
+        except CaptureError as exc:
+            return _capture_error(exc)
+        except Exception:
+            self.logger.exception("Image observation failed")
+            return _error(500, "observe-failed", "The image could not be observed.")
+        try:
+            stored, title = await self._run_in_executor(
+                self._observe_capture, store, capture, root, relative
+            )
+        except asyncio.CancelledError:
+            store.release(capture.token)
+            raise
+        except Exception:
+            store.release(capture.token)
+            self.logger.exception("Image observation failed")
+            return _error(500, "observe-failed", "The image could not be observed.")
+        return web.json_response(
+            {
+                "success": True,
+                "library_epoch": capture.epoch,
+                "target": {"root_index": index, "root_scope": scope, "path": relative},
+                "capture": _capture_info(store, capture),
+                "title": title,
+                "filename": relative.rsplit("/", 1)[-1],
+                "tags": stored["tags"],
+                "tag_revision": stored["tag_revision"],
+            },
+            headers={"Cache-Control": "no-store"},
+        )
+
+    def _observe_capture(self, store: CaptureStore, capture, root, relative: str):
+        """Blocking part of observe: fingerprint refresh, tag read, title."""
+        self.db.refresh_image_fingerprint(
+            capture.locator, capture.sha256, capture.size, capture.mtime_ns
+        )
+        stored = self.db.read_image_tags(capture.locator, capture.sha256)
+        return stored, self._observed_title(store, capture, root, relative)
+
+    def _observed_title(self, store: CaptureStore, capture, root, relative: str):
+        """The dialog's title under the card and inspector rule (``_verified_title``).
+
+        A stored Library title always shows; a first-line title only when the
+        captured bytes' own records confirm it. An ambiguous association has no
+        title. Videos read no card metadata, so only a stored title shows.
+        """
+        path = str(Path(root) / relative)
+        summary = self._workspace_link_summaries([path]).get(path)
+        if summary is None:
+            summary = _unavailable_link()
+        positive_title = None
+        if (
+            capture.media_type != "video"
+            and summary.get("title_source") == "text"
+            and store.acquire(capture.token) is not None
+        ):
+            try:
+                facts = self._read_card_facts(Path(capture.path), parse=True)
+            finally:
+                store.release_use(capture.token)
+            positive_title = facts.positive_title if facts is not None else None
+        return _verified_title(summary, positive_title)
+
+    # -- capture preview -------------------------------------------------------
+
+    async def get_capture_preview(self, request: web.Request) -> web.StreamResponse:
+        """GET the captured bytes; the token is pinned while they stream."""
+        token = request.match_info["token"]
+        store = self._captures
+        if store is None or _TOKEN.fullmatch(token) is None:
+            return _error(404, "capture-expired", _MESSAGES["capture-expired"])
+        capture = store.acquire(token)
+        if capture is None:
+            return _error(404, "capture-expired", _MESSAGES["capture-expired"])
+        pinned = True
+        try:
+            _root, error = self._scoped_root(capture.root_index, capture.scope)
+            if error is not None:
+                # The roots changed under the token: it is no longer usable.
+                store.release(token)
+                return error
+            try:
+                handle = await _settled(
+                    _submit(_open_capture, capture.path),
+                    functools.partial(_close_then_release, store, token),
+                )
+            except asyncio.CancelledError:
+                # Cancelled while the file opens: the pin ends only after the
+                # handle closes (Windows cannot unlink an open file).
+                pinned = False
+                raise
+            except OSError:
+                store.release(token)
+                return _error(404, "capture-expired", _MESSAGES["capture-expired"])
+            try:
+                return await self._stream_capture(request, capture, handle)
+            finally:
+                handle.close()
+        finally:
+            if pinned:
+                store.release_use(token)
+
+    @staticmethod
+    async def _stream_capture(request, capture, handle) -> web.StreamResponse:
+        """The capture's bytes, or the one byte range a ``Range`` header asks for.
+
+        The response is written here, inside the caller's pin, so the handle
+        is closed and the pin ended only after the last byte is sent.
+        """
+        size = capture.size
+        headers = {
+            "Content-Type": preview_content_type(Path(capture.path).suffix),
+            "Accept-Ranges": "bytes",
+            "Cache-Control": "no-store",
+            "X-Content-Type-Options": "nosniff",
+        }
+        status, start, end = 200, 0, size
+        if "Range" in request.headers:
+            wanted = _byte_range(request, size)
+            if wanted is None:
+                return web.Response(
+                    status=416,
+                    headers={**headers, "Content-Range": f"bytes */{size}"},
+                )
+            status, (start, end) = 206, wanted
+            headers["Content-Range"] = f"bytes {start}-{end - 1}/{size}"
+        headers["Content-Length"] = str(end - start)
+        response = web.StreamResponse(status=status, headers=headers)
+        await response.prepare(request)
+        loop = asyncio.get_running_loop()
+        if start:
+            await loop.run_in_executor(None, handle.seek, start)
+        remaining = end - start
+        while remaining > 0 and request.method != "HEAD":
+            chunk = await loop.run_in_executor(
+                None, handle.read, min(_PREVIEW_CHUNK, remaining)
+            )
+            if not chunk:
+                break
+            remaining -= len(chunk)
+            await response.write(chunk)
+        await response.write_eof()
+        return response
+
+    async def release_capture(self, request: web.Request) -> web.Response:
+        """DELETE a capture token; releasing an unknown token is a success."""
+        token = request.match_info["token"]
+        store = self._captures
+        if store is not None and _TOKEN.fullmatch(token) is not None:
+            store.release(token)
+        return web.json_response(
+            {"success": True}, headers={"Cache-Control": "no-store"}
+        )
+
+    # -- save ------------------------------------------------------------------
+
+    async def save_image_tags(self, request: web.Request) -> web.Response:
+        """PUT the tag set of the previewed bytes, re-hashing the current file.
+
+        Writes only when the file still holds the captured bytes
+        (``file-changed`` with zero writes otherwise), under the storage epoch
+        and the tag revision the dialog read; an identical retry is
+        ``replayed``. The hash never runs inside a database transaction.
+        """
+        data, error = await self._annotation_body(request, _SAVE_FIELDS)
+        if error is not None:
+            return error
+        target, error = _target(data["target"])
+        if error is not None:
+            return error
+        guards, error = _save_guards(data)
+        if error is not None:
+            return error
+        token, sha256, expected_epoch, revision, tags = guards
+        index, scope, relative = target
+        root, error = self._scoped_root(index, scope)
+        if error is not None:
+            return error
+        store = self._captures
+        capture = store.get(token) if store is not None else None
+        if capture is None:
+            return _coded("capture-expired")
+        if capture.root_index != index or capture.scope != scope:
+            return _coded("capture-expired", _OTHER_FILE)
+        if sha256 != capture.sha256:
+            return bad_request("sha256 does not match the preview")
+        if expected_epoch != capture.epoch:
+            current = await self._run_in_executor(self.db.get_execution_epoch)
+            return _coded("storage-changed", library_epoch=current)
+        try:
+            facts = await self._run_in_executor(
+                _verify_captured_file, store, capture, root, relative
+            )
+        except CaptureError as exc:
+            return _capture_error(exc)
+        if facts is None or facts.locator != capture.locator:
+            return _coded("capture-expired", _OTHER_FILE)
+        if facts.sha256 != capture.sha256:
+            return _coded("file-changed")
+        try:
+            receipt = await self._run_in_executor(
+                self.db.replace_image_tags,
+                locator=facts.locator,
+                sha256=facts.sha256,
+                size=facts.size,
+                mtime_ns=facts.mtime_ns,
+                expected_epoch=expected_epoch,
+                expected_tag_revision=revision,
+                tags=tags,
+            )
+        except AnnotationCommandError as exc:
+            current = exc.current or {}
+            return _coded(
+                exc.code,
+                library_epoch=exc.epoch,
+                tags=current.get("tags", []),
+                tag_revision=current.get("tag_revision", 0),
+            )
+        except LibraryCommandError as exc:
+            return _coded(exc.code, library_epoch=exc.epoch)
+        except ValueError as exc:
+            return bad_request(str(exc))
+        except Exception:
+            self.logger.exception("Image tag save failed")
+            return _error(500, "save-failed", "The tags could not be saved.")
+        return web.json_response(
+            {"success": True, **receipt}, headers={"Cache-Control": "no-store"}
+        )
+
+    # -- suggest ---------------------------------------------------------------
+
+    async def suggest_image_tags(self, request: web.Request) -> web.Response:
+        """POST: the top N tags of the captured bytes from one legacy engine.
+
+        Runs only on the private capture (pinned for the whole inference),
+        under the shared model gate (``model-busy`` while anything else holds
+        it, including a legacy batch), never downloads (``model-unavailable``)
+        and never writes.
+        """
+        from ..autotag import MODELS, get_autotag_service
+        from ..config import MAX_SUGGESTION_LIMIT, AutotagConfig
+
+        data, error = await self._annotation_body(request, SUGGEST_FIELDS)
+        if error is not None:
+            return error
+        target, error = _target(data["target"])
+        if error is not None:
+            return error
+        try:
+            model_type, options = validate_options(
+                data["model_type"],
+                data["options"],
+                default_limit=AutotagConfig.suggestion_limit(),
+                max_limit=MAX_SUGGESTION_LIMIT,
+            )
+        except OptionError as exc:
+            return bad_request(str(exc))
+        token, epoch = data["capture_token"], data["expected_epoch"]
+        if not isinstance(token, str) or _TOKEN.fullmatch(token) is None:
+            return bad_request("Invalid capture token")
+        if not isinstance(epoch, str) or _UUID.fullmatch(epoch) is None:
+            return bad_request("expected_epoch must be a canonical UUID")
+        index, scope, relative = target
+        root, error = self._scoped_root(index, scope)
+        if error is not None:
+            return error
+        store = self._captures
+        capture = store.acquire(token) if store is not None else None
+        if capture is None:
+            return _coded("capture-expired")
+        started = False
+        try:
+            error = await self._suggest_guards(capture, target, root, epoch)
+            if error is not None:
+                return error
+            service = get_autotag_service()
+            status = await self._run_in_executor(service.get_models_status)
+            if not status.get(model_type, {}).get("downloaded"):
+                name = MODELS.get(model_type, {}).get("name", model_type)
+                return _coded("model-unavailable", unavailable_message(name))
+            owner = model_gate.new_owner("image-annotations")
+            if not model_gate.try_acquire(owner):
+                return model_busy_response()
+            try:
+                # From here the pin is the gate's to end: the worker ends it,
+                # or ``on_skipped`` does when the worker never starts.
+                started = True
+                pairs = await model_gate.run(
+                    owner,
+                    _pinned_suggestions,
+                    store,
+                    token,
+                    service,
+                    capture,
+                    model_type,
+                    options,
+                    on_skipped=functools.partial(store.release_use, token),
+                )
+            except Exception:
+                self.logger.exception("Tag suggestion failed")
+                return _error(
+                    500,
+                    "suggest-failed",
+                    "Auto-tagging failed. Check server logs for details.",
+                )
+            finally:
+                model_gate.release(owner)
+        finally:
+            if not started:
+                store.release_use(token)
+        return web.json_response(
+            {
+                "success": True,
+                "model_type": model_type,
+                "options": options,
+                "suggestions": suggestion_rows(pairs),
+            },
+            headers={"Cache-Control": "no-store"},
+        )
+
+    async def _suggest_guards(self, capture, target, root, epoch):
+        """The capture must be this target's, of this epoch, and inferable."""
+        index, scope, relative = target
+        expected = os.path.normcase(
+            os.path.join(os.path.realpath(root), *relative.split("/"))
+        )
+        if (
+            capture.root_index != index
+            or capture.scope != scope
+            or capture.locator != expected
+        ):
+            return _coded("capture-expired", _OTHER_FILE)
+        if epoch != capture.epoch:
+            current = await self._run_in_executor(self.db.get_execution_epoch)
+            return _coded("storage-changed", library_epoch=current)
+        if not capture.inferable:
+            return _coded("unsupported-media", capture.inferable_reason)
+        return None
+
+
+def _close_then_release(store: CaptureStore, token: str, handle) -> None:
+    """Close a preview handle a cancelled request opened, then end its pin."""
+    try:
+        if handle is not None:
+            handle.close()
+    finally:
+        store.release_use(token)
+
+
+def _byte_range(request: web.Request, size: int):
+    """``(start, end)`` of the one satisfiable byte range asked for, else None.
+
+    A malformed, multi-range or unsatisfiable header is None (416), as
+    aiohttp's own file responses answer it.
+    """
+    try:
+        wanted = request.http_range
+    except ValueError:
+        return None
+    start, stop = wanted.start, wanted.stop
+    if start is None:
+        return None
+    if start < 0:  # a suffix: the last -start bytes
+        start = max(0, size + start)
+        stop = size
+    stop = size if stop is None else min(stop, size)
+    if start >= size or stop <= start:
+        return None
+    return start, stop
+
+
+def _pinned_suggestions(store, token, service, capture, model_type, options):
+    """Worker thread: infer on the capture, then end its pin (even on error)."""
+    try:
+        return run_suggestions(service, capture.path, model_type, options)
+    finally:
+        store.release_use(token)
+
+
+def _verify_captured_file(store: CaptureStore, capture, root, relative: str):
+    """Re-hash the current file, or None when the token names another file.
+
+    The cheap locator comparison runs first, so a token sent for another
+    target never costs a whole-file hash.
+    """
+    expected = os.path.normcase(
+        os.path.join(os.path.realpath(root), *relative.split("/"))
+    )
+    if expected != capture.locator:
+        return None
+    return store.verify(root, relative)
+
+
+def _save_guards(data: dict):
+    """Validated ``(token, sha256, epoch, revision, tags)`` or ``(None, error)``."""
+    token = data["capture_token"]
+    if not isinstance(token, str) or _TOKEN.fullmatch(token) is None:
+        return None, bad_request("Invalid capture token")
+    sha256 = data["sha256"]
+    if not isinstance(sha256, str) or _HEX64.fullmatch(sha256) is None:
+        return None, bad_request("sha256 must be 64 lowercase hexadecimal characters")
+    epoch = data["expected_epoch"]
+    if not isinstance(epoch, str) or _UUID.fullmatch(epoch) is None:
+        return None, bad_request("expected_epoch must be a canonical UUID")
+    revision = data["expected_tag_revision"]
+    if type(revision) is not int or revision < 0:
+        return None, bad_request("expected_tag_revision must be a non-negative integer")
+    try:
+        tags = normalize_image_tags(data["tags"])
+    except ImageTagLimitError as exc:
+        return None, _error(400, "tag-limit", str(exc))
+    except ValueError as exc:
+        return None, bad_request(str(exc))
+    return (token, sha256, epoch, revision, tags), None

py/api/autotag_routes.py

@@ -9,11 +9,24 @@ from typing import Optional
 from urllib.parse import quote
 
 from .prompts import thumbnail_url_for
+from .. import model_gate
 
 from aiohttp import web
 
 _INTERNAL_ERROR = "An internal error occurred. Check server logs for details."
 _BUSY_ERROR = "Auto-tagging is already running"
+MODEL_BUSY_ERROR = (
+    "A tagging model is busy with another operation. Try again when it finishes."
+)
+
+
+def model_busy_response() -> web.Response:
+    """``409 model-busy``: another operation holds the shared model gate."""
+    return web.json_response(
+        {"success": False, "code": "model-busy", "error": MODEL_BUSY_ERROR},
+        status=409,
+    )
+
 
 # Only these may be handed to the tagging engine or listed by the scanner.
 _MEDIA_EXTENSIONS = frozenset(
@@ -86,6 +99,7 @@ class AutotagRoutesMixin:
         """Get status of available AutoTag models."""
         try:
             from ..autotag import get_autotag_service
+            from ..config import AutotagConfig
 
             service = get_autotag_service()
             models_status = service.get_models_status()
@@ -99,6 +113,7 @@ class AutotagRoutesMixin:
                     "loaded_model_type": service.get_loaded_model_type(),
                     "wd14_general_threshold": service.wd14_general_threshold,
                     "wd14_character_threshold": service.wd14_character_threshold,
+                    "suggestion_limit": AutotagConfig.suggestion_limit(),
                 }
             )
 
@@ -138,6 +153,7 @@ class AutotagRoutesMixin:
     async def download_autotag_model(self, request):
         """Download an AutoTag model with streaming progress (POST only)."""
         model_type = request.match_info.get("model_type")
+        owner = model_gate.new_owner("legacy-download")
 
         async def events():
             try:
@@ -160,8 +176,8 @@ class AutotagRoutesMixin:
                 def progress_callback(status: str, progress: float):
                     pass
 
-                success = await self._run_in_executor(
-                    service.download_model, model_type, progress_callback
+                success = await model_gate.run(
+                    owner, service.download_model, model_type, progress_callback
                 )
                 if success:
                     yield {
@@ -178,7 +194,12 @@ class AutotagRoutesMixin:
                     "message": _INTERNAL_ERROR,
                 }
 
-        return await self._stream_sse(request, events())
+        if not model_gate.try_acquire(owner):
+            return model_busy_response()
+        try:
+            return await self._stream_sse(request, events())
+        finally:
+            model_gate.release(owner)
 
     async def _read_start_params(self, request) -> Optional[dict]:
         """Merge query-string and optional JSON-body parameters for autotag/start.
@@ -239,8 +260,9 @@ class AutotagRoutesMixin:
             return
 
         yield {"type": "progress", "progress": 0, "status": "Loading model..."}
+        run = self._gated_runner(opts.get("gate_owner"))
         try:
-            await self._run_in_executor(service.load_model, model_type, True)
+            await run(service.load_model, model_type, True)
         except Exception:
             self.logger.exception("Failed to load model")
             yield {
@@ -338,7 +360,7 @@ class AutotagRoutesMixin:
                     continue
 
                 try:
-                    tags = await self._run_in_executor(
+                    tags = await run(
                         service.generate_tags,
                         allowed_path,
                         general_threshold=opts["general_threshold"],
@@ -423,10 +445,26 @@ class AutotagRoutesMixin:
                 {"success": False, "error": _BUSY_ERROR}, status=409
             )
         try:
-            return await self._stream_sse(request, events())
+            opts["gate_owner"] = model_gate.new_owner("legacy-batch")
+            if not model_gate.try_acquire(opts["gate_owner"]):
+                return model_busy_response()
+            try:
+                return await self._stream_sse(request, events())
+            finally:
+                model_gate.release(opts["gate_owner"])
         finally:
             _autotag_batch_lock.release()
 
+    def _gated_runner(self, owner):
+        """Executor calls under the model gate *owner* holds (plain when None)."""
+        if owner is None:
+            return self._run_in_executor
+
+        async def run(func, *args, **kwargs):
+            return await model_gate.run(owner, func, *args, **kwargs)
+
+        return run
+
     def _resolve_allowed_image_path(self, raw_path: str) -> Optional[str]:
         """Return the real path when it is a media file inside an output directory."""
         if Path(str(raw_path)).suffix.lower() not in _MEDIA_EXTENSIONS:
@@ -549,22 +587,28 @@ class AutotagRoutesMixin:
             from ..autotag import get_autotag_service
 
             service = get_autotag_service()
+            owner = model_gate.new_owner("legacy-single")
+            if not model_gate.try_acquire(owner):
+                return model_busy_response()
+            try:
+                if (
+                    not service.is_model_loaded()
+                    or service.get_loaded_model_type() != model_type
+                ):
+                    await model_gate.run(owner, service.load_model, model_type, use_gpu)
 
-            if (
-                not service.is_model_loaded()
-                or service.get_loaded_model_type() != model_type
-            ):
-                await self._run_in_executor(service.load_model, model_type, use_gpu)
+                if custom_prompt:
+                    service.custom_prompt = custom_prompt
 
-            if custom_prompt:
-                service.custom_prompt = custom_prompt
-
-            tags = await self._run_in_executor(
-                service.generate_tags,
-                image_path,
-                general_threshold=general_threshold,
-                character_threshold=character_threshold,
-            )
+                tags = await model_gate.run(
+                    owner,
+                    service.generate_tags,
+                    image_path,
+                    general_threshold=general_threshold,
+                    character_threshold=character_threshold,
+                )
+            finally:
+                model_gate.release(owner)
 
             return web.json_response(
                 {
@@ -636,14 +680,19 @@ class AutotagRoutesMixin:
             from ..autotag import get_autotag_service
 
             service = get_autotag_service()
+            owner = model_gate.new_owner("legacy-unload")
+            if not model_gate.try_acquire(owner):
+                return model_busy_response()
+            try:
+                if not service.is_model_loaded():
+                    return web.json_response(
+                        {"success": True, "message": "No model was loaded"}
+                    )
 
-            if not service.is_model_loaded():
-                return web.json_response(
-                    {"success": True, "message": "No model was loaded"}
-                )
-
-            model_type = service.get_loaded_model_type()
-            service.unload_model()
+                model_type = service.get_loaded_model_type()
+                service.unload_model()
+            finally:
+                model_gate.release(owner)
 
             return web.json_response(
                 {

py/api/images.py

@@ -14,7 +14,7 @@ import urllib.parse
 from bisect import bisect_left, bisect_right
 from collections.abc import Mapping
 from pathlib import Path
-from typing import NamedTuple
+from typing import Callable, NamedTuple
 
 from aiohttp import web
 from PIL import Image, UnidentifiedImageError
@@ -74,6 +74,7 @@ IMAGE_EXTENSIONS = _IMAGE_EXTENSIONS
 # The header records the card parses (see utils.card_seed.header_params).
 _CARD_RECORDS = ("prompt", "workflow")
 _PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+_LISTING_FAILED = "The image list could not be filtered. Check server logs for details."
 
 
 def _card_header(path: Path) -> tuple:
@@ -418,6 +419,29 @@ def _listed(path: Path, mtime: float, root: Path, index: int) -> _Listed:
     )
 
 
+class _ImageTagMatch(NamedTuple):
+    """How one listed file's current image tags meet the filters (#249 B3)."""
+
+    tags: bool  # every filter tag is in its image tags or linked positive tags
+    query: bool  # ``q`` is a case-folded substring of one image tag name
+    link: tuple | None  # (hit, rating, positive id) of its unambiguous link
+
+
+def _current_fingerprint(path: Path) -> tuple[int, int] | None:
+    """The file's present ``(st_size, st_mtime_ns)``; None when it is gone."""
+    try:
+        observed = os.stat(path)
+    except OSError:
+        return None
+    return observed.st_size, observed.st_mtime_ns
+
+
+def _image_tags_relevant(names: list, wanted: set, query: str) -> bool:
+    if wanted and not wanted.isdisjoint(names):
+        return True
+    return bool(query) and any(query in name.casefold() for name in names)
+
+
 def _workspace_key(entry: tuple, order: str) -> tuple:
     """The keyset sort key of *entry* (a _Listed or a 4-tuple entry)."""
     if not isinstance(entry, _Listed):
@@ -752,6 +776,7 @@ def _filtered_page(
     filters: dict,
     links: dict | None,
     favorites: frozenset | None = None,
+    image_tags: dict | None = None,
 ) -> tuple[int, list, int | None]:
     """Count the *entries* the filters admit and take *size* from *start* on.
 
@@ -761,6 +786,9 @@ def _filtered_page(
     or a linked-positive hit. Returns the total, the page and the number of
     distinct linked positives among all admitted entries (None without links).
     *favorites*, when given, admits only those listed paths (``favorites=1``).
+    *image_tags* maps normalized paths to their _ImageTagMatch: a tag filter
+    also admits a file whose current image tags (with its linked positive's
+    tags) carry every tag, and ``q`` also admits an image tag name hit.
     """
     query, media, folder = filters["query"], filters["media"], filters["folder"]
     members_only = filters["category"] is not None or bool(filters["tags"])
@@ -780,9 +808,15 @@ def _filtered_page(
         if favorites is not None and entry.path not in favorites:
             continue
         match = None if links is None else links.get(entry.normalized)
-        if members_only and match is None:
+        image = None if image_tags is None else image_tags.get(entry.normalized)
+        if members_only and match is None and not (image and image.tags):
             continue
-        if query and query not in entry.folded and not (match and match[0]):
+        if (
+            query
+            and query not in entry.folded
+            and not (match and match[0])
+            and not (image and image.query)
+        ):
             continue
         total += 1
         if match is not None:
@@ -1140,7 +1174,7 @@ class ImageRoutesMixin:
                 }
             )
         except Exception as e:
-            self.logger.error(f"Output images error: {e}")
+            self.logger.error(f"Output images error: {e}", exc_info=True)
             return web.json_response(
                 {"success": False, "error": _safe_error(e)}, status=500
             )
@@ -1184,11 +1218,27 @@ class ImageRoutesMixin:
             for index, root in enumerate(output_dirs)
             if root_index is None or index == root_index
         ]
-        page, total, has_more, next_cursor, positive_count = (
-            await self._run_in_executor(
-                self._select_workspace_page, listings, filters, after, limit, scope
+        try:
+            page, total, has_more, next_cursor, positive_count = (
+                await self._run_in_executor(
+                    self._select_workspace_page, listings, filters, after, limit, scope
+                )
+            )
+        except Exception:
+            # A filter that needs the prompt links or the image tags cannot be
+            # served without them. Never echo the exception: it can carry SQL
+            # or database text. The traceback goes to the server log.
+            self.logger.error(
+                "Workspace image list could not be filtered", exc_info=True
+            )
+            return web.json_response(
+                {
+                    "success": False,
+                    "code": "listing-failed",
+                    "error": _LISTING_FAILED,
+                },
+                status=500,
             )
-        )
         images = await self._run_in_executor(self._format_workspace_page, page)
         result = {
             "success": True,
@@ -1276,6 +1326,80 @@ class ImageRoutesMixin:
                 )
         return orders[order]
 
+    def _workspace_locators(self, listings: list[tuple]) -> dict:
+        """The selected listing's private locators -> _Listed (cached).
+
+        A locator is ``normcase(join(realpath(root), relative))``, the key
+        image tags are stored under (database/annotations.py); the listing
+        never follows symlinks, so it equals the listed file's own locator.
+        """
+        orders = self._workspace_orders(listings)
+        reals = tuple(os.path.realpath(root) for _index, root, _files in listings)
+        key = ("locators", reals)
+        if key not in orders:
+            located = {}
+            for (index, root, files), real in zip(listings, reals):
+                prefix = os.path.join(str(root), "")
+                for entry in self._workspace_listed(index, root, files):
+                    text = str(entry.path)
+                    relative = (
+                        text[len(prefix) :]
+                        if text.startswith(prefix)
+                        else str(entry.path.relative_to(root))
+                    )
+                    located[os.path.normcase(os.path.join(real, relative))] = entry
+            orders[key] = located
+        return orders[key]
+
+    def _image_tag_matches(self, listings: list[tuple], filters: dict) -> dict:
+        """Normalized path -> _ImageTagMatch for files whose image tags count.
+
+        Streams the tagged byte records once and keeps only listed locators
+        carrying a filter tag or a ``q`` hit; only those candidates are
+        stat'ed (never every listed file), and a candidate's tags count only
+        while a byte record is verified at its present ``(size, mtime_ns)``
+        (spec amendment S1). Under a Tags filter the candidates' linked
+        positives are read too, so their tags and category combine.
+        """
+        tags, query, category = filters["tags"], filters["query"], filters["category"]
+        wanted = set(tags)
+        located = self._workspace_locators(listings)
+        candidates = {}
+        records = self.db.iter_image_tag_records()
+        try:
+            for locator, _size, _mtime_ns, names in records:
+                entry = located.get(locator)
+                if entry is not None and locator not in candidates:
+                    if _image_tags_relevant(names, wanted, query):
+                        candidates[locator] = entry
+        finally:
+            records.close()
+        stats = {}
+        for locator, entry in candidates.items():
+            fingerprint = _current_fingerprint(entry.path)
+            if fingerprint is not None:
+                stats[locator] = fingerprint
+        current = self.db.current_image_tags(stats) if stats else {}
+        facts = {}
+        if wanted and current:
+            facts = self.db.get_image_link_facts(
+                [candidates[locator].normalized for locator in current],
+                filters["text"],
+            )
+        matches = {}
+        for locator, names in current.items():
+            entry = candidates[locator]
+            link = facts.get(entry.normalized)
+            carried = set(names).union(link[4] if link else ())
+            matches[entry.normalized] = _ImageTagMatch(
+                bool(wanted)
+                and wanted <= carried
+                and (category is None or (link is not None and link[3] == category)),
+                bool(query) and any(query in name.casefold() for name in names),
+                link[:3] if link else None,
+            )
+        return matches
+
     def _select_workspace_page(
         self,
         listings: list[tuple],
@@ -1328,6 +1452,30 @@ class ImageRoutesMixin:
                     ),
                     exc_info=True,
                 )
+        image_tags = None
+        if filters["query"] or tags:
+            try:
+                image_tags = self._image_tag_matches(listings, filters)
+            except Exception:
+                # A Tags filter cannot be served without them (as without the
+                # links); a search then matches without image tags.
+                if tags:
+                    raise
+                self.logger.warning(
+                    "Workspace image tags could not be read; searching without "
+                    "image tags",
+                    exc_info=True,
+                )
+        if image_tags and links is not None:
+            # A linked file admitted through its image tags keeps its rating
+            # and counts its positive.
+            admitted = {
+                path: match.link
+                for path, match in image_tags.items()
+                if match.tags and match.link is not None and path not in links
+            }
+            if admitted:
+                links = {**links, **admitted}
         if order == "rating":
 
             def rank(entry):
@@ -1360,7 +1508,7 @@ class ImageRoutesMixin:
             self._workspace_favorite_paths(listings) if filters["favorites"] else None
         )
         total, page, positive_count = _filtered_page(
-            entries, start, limit + 1, filters, links, favorites
+            entries, start, limit + 1, filters, links, favorites, image_tags
         )
         if not needed and after is not None:
             positive_count = _COUNT_OMITTED
@@ -2467,6 +2615,9 @@ class ImageRoutesMixin:
                         library=self._inspection_library(
                             saved, unavailable=unavailable
                         ),
+                        image_tags=self._inspection_image_tags(
+                            roots[index], Path(relative).parts
+                        ),
                     )
                 except CurrentFileChanged:
                     return None
@@ -2505,6 +2656,30 @@ class ImageRoutesMixin:
                 {"success": False, "error": "Prompt inspection failed"}, status=500
             )
 
+    def _inspection_image_tags(self, root: Path, parts: tuple) -> Callable:
+        """The inspector's ``image_tags`` reader for one rooted file (S1).
+
+        The returned function takes the inspection's own stable stat and
+        answers ``current`` only for a byte record verified at exactly that
+        ``(size, mtime_ns)``; a failed read is ``unavailable``, never an error.
+        """
+        locator = os.path.normcase(os.path.join(os.path.realpath(root), *parts))
+
+        def read(size: int, mtime_ns: int) -> dict:
+            try:
+                found = self.db.current_image_tags({locator: (size, mtime_ns)})
+            except Exception:
+                self.logger.warning(
+                    "Inspection image tags could not be read", exc_info=True
+                )
+                return {"state": "unavailable", "tags": []}
+            tags = found.get(locator)
+            if tags is None:
+                return {"state": "none", "tags": []}
+            return {"state": "current", "tags": list(tags)}
+
+        return read
+
     def _inspection_library(self, saved: dict | None, *, unavailable: bool) -> dict:
         """The inspector's Library facts; the route sets the title afterwards."""
         result = {

py/api/inspection_service.py

@@ -3,6 +3,7 @@
 import os
 import stat
 from pathlib import Path
+from typing import Callable
 
 try:
     from ...utils.prompt_inspector import (
@@ -93,8 +94,19 @@ def _in_host_temp(path: Path) -> bool:
 
 
 def inspect_current_file(
-    path: Path, *, source_label: str, saved: dict | None, library: dict
+    path: Path,
+    *,
+    source_label: str,
+    saved: dict | None,
+    library: dict,
+    image_tags: Callable[[int, int], dict] | None = None,
 ) -> dict:
+    """Current-file evidence read between two equal stats of *path*.
+
+    *image_tags*, when given, is called once with that stable
+    ``(st_size, st_mtime_ns)`` and its facet is returned as ``image_tags``
+    (spec amendment S1: tags of a byte record verified at exactly that stat).
+    """
     before = _current_file_facts(path)
     try:
         inspection = read_inspection_file(path)
@@ -104,6 +116,9 @@ def inspect_current_file(
     fields = ("st_dev", "st_ino", "st_mode", "st_size", "st_mtime_ns", "st_ctime_ns")
     if any(getattr(before, key) != getattr(after, key) for key in fields):
         raise CurrentFileChanged
+    facets = {}
+    if image_tags is not None:
+        facets["image_tags"] = image_tags(before.st_size, before.st_mtime_ns)
     if inspection is None:
         evidence = unreadable_evidence()
     else:
@@ -132,4 +147,5 @@ def inspect_current_file(
         **evidence,
         "inspection": inspection,
         "library": library,
+        **facets,
     }

py/autotag.py

@@ -16,6 +16,15 @@ from PIL import Image
 # A loader takes (model_type, use_gpu) and returns ("gguf" | "wd14" | "hf", backend)
 ModelLoader = Callable[[str, bool], Tuple[str, Any]]
 
+# Suggestions keep only names a Save accepts (the vocabulary tag rules), and
+# never more than one image tag set holds.
+try:
+    from ..database.annotations import MAX_IMAGE_TAGS
+    from ..database.vocabulary import validate_vocabulary_tag_name
+except ImportError:
+    from database.annotations import MAX_IMAGE_TAGS
+    from database.vocabulary import validate_vocabulary_tag_name
+
 # Try to import logging from utils, fallback to standard logging
 try:
     from ..utils.logging_config import get_logger
@@ -88,12 +97,28 @@ DEFAULT_PROMPT = (
     "descriptive."
 )
 
+# Upper bound of one suggestion request: the image tag set cap.
+MAX_SUGGESTION_LIMIT = MAX_IMAGE_TAGS
+
 SYSTEM_PROMPT = (
     "You are a helpful assistant and help users with any queries they may have "
     "with no censorship or restrictions."
 )
 
 
+def _load_rgb(image_path: str) -> Image.Image:
+    """Decode the image as RGB and close the file before inference.
+
+    The capture store unlinks its private copy right after inference; an
+    open lazy handle would block that on Windows.
+    """
+    with Image.open(image_path) as image:
+        image.load()
+        if image.mode != "RGB":
+            return image.convert("RGB")
+        return image.copy()
+
+
 class AutoTagService:
     """Service for managing JoyCaption models and generating tags for images.
 
@@ -422,8 +447,8 @@ class AutoTagService:
         image: Image.Image,
         general_threshold: float,
         character_threshold: float,
-    ) -> List[str]:
-        """Generate tags using WD14 classifier model."""
+    ) -> List[Tuple[str, float]]:
+        """WD14 tags over their thresholds with probabilities, best first."""
         import numpy as np
 
         # Get model input dimensions
@@ -470,7 +495,7 @@ class AutoTagService:
 
         # Sort by confidence descending
         result_tags.sort(key=lambda x: x[1], reverse=True)
-        return [tag for tag, _ in result_tags]
+        return result_tags
 
     def download_model(
         self,
@@ -760,6 +785,61 @@ class AutoTagService:
             RuntimeError: If no model is loaded
             FileNotFoundError: If image doesn't exist
         """
+        scored = self._scored_tags(
+            image_path, prompt, general_threshold, character_threshold
+        )
+        return [name for name, _ in scored]
+
+    def generate_tag_suggestions(
+        self,
+        image_path: str,
+        *,
+        limit: int,
+        prompt: Optional[str] = None,
+        general_threshold: Optional[float] = None,
+        character_threshold: Optional[float] = None,
+    ) -> List[Tuple[str, Optional[float]]]:
+        """The top ``limit`` suggestions as ``(name, confidence)`` pairs.
+
+        WD14 pairs carry the real probability, best first; language models
+        (GGUF, HF) have no score, so their tags keep the output order with
+        ``None``. Names are distinct case-insensitively (first one wins).
+        A name Save would reject (over 50 characters, a control character
+        such as a newline, a comma) is skipped before the dedupe and the
+        ``limit`` count. ``prompt`` is used for this call only;
+        ``custom_prompt`` is never changed.
+        """
+        if type(limit) is not int or not 1 <= limit <= MAX_SUGGESTION_LIMIT:
+            raise ValueError(
+                f"limit must be an integer from 1 to {MAX_SUGGESTION_LIMIT}"
+            )
+        scored = self._scored_tags(
+            image_path, prompt, general_threshold, character_threshold
+        )
+        suggestions: List[Tuple[str, Optional[float]]] = []
+        seen = set()
+        for raw, score in scored:
+            try:
+                name = validate_vocabulary_tag_name(raw)
+            except ValueError:
+                continue
+            key = name.casefold()
+            if key in seen:
+                continue
+            seen.add(key)
+            suggestions.append((name, score))
+            if len(suggestions) == limit:
+                break
+        return suggestions
+
+    def _scored_tags(
+        self,
+        image_path: str,
+        prompt: Optional[str],
+        general_threshold: Optional[float],
+        character_threshold: Optional[float],
+    ) -> List[Tuple[str, Optional[float]]]:
+        """Run the loaded model: WD14 ``(name, probability)``, LLM ``(name, None)``."""
         if self._tagger is None:
             raise RuntimeError("No model loaded. Call load_model() first.")
 
@@ -767,18 +847,14 @@ class AutoTagService:
             raise FileNotFoundError(errno.ENOENT, "Image not found", str(image_path))
 
         use_prompt = prompt or self._custom_prompt
-
-        # Load image
-        image = Image.open(image_path)
-        if image.mode != "RGB":
-            image = image.convert("RGB")
+        image = _load_rgb(image_path)
 
         # Generate based on model type
         model_type, tagger_obj = self._tagger
 
         if model_type == "gguf":
             raw_tags = self._generate_gguf(tagger_obj, image, use_prompt)
-            return self._parse_tags(raw_tags)
+            return [(tag, None) for tag in self._parse_tags(raw_tags)]
         elif model_type == "wd14":
             session, tags_list = tagger_obj
             gen_thresh = (
@@ -799,7 +875,7 @@ class AutoTagService:
             raw_tags = self._generate_hf(
                 model, processor, device, compute_dtype, image, use_prompt
             )
-            return self._parse_tags(raw_tags)
+            return [(tag, None) for tag in self._parse_tags(raw_tags)]
 
     def _generate_gguf(self, model, image: Image.Image, prompt: str) -> str:
         """Generate tags using GGUF model."""

py/config.py

@@ -465,6 +465,59 @@ class IntegrationConfig:
             cls.CIVITAI_API_KEY = lora["civitai_api_key"]
 
 
+# Number of tag suggestions the Tag dialogs request by default (D68). The cap
+# is the image tag set limit: more suggestions could never all be kept.
+DEFAULT_SUGGESTION_LIMIT = 10
+MAX_SUGGESTION_LIMIT = 100  # pinned to MAX_IMAGE_TAGS by tests/test_config.py
+
+
+class AutotagConfig:
+    """Persisted tagging defaults under ``autotag.defaults`` in config.json.
+
+    ``suggestion_limit`` is how many suggestions Generate returns (the top N
+    by score), an integer in ``1..MAX_SUGGESTION_LIMIT``. A hand-edited value
+    outside that range, or of another type, falls back to the default with a
+    warning rather than failing the load.
+    """
+
+    SUGGESTION_LIMIT = DEFAULT_SUGGESTION_LIMIT
+
+    @classmethod
+    def suggestion_limit(cls) -> int:
+        return cls.SUGGESTION_LIMIT
+
+    @staticmethod
+    def valid_suggestion_limit(value: Any) -> bool:
+        return (
+            type(value) is int and 1 <= value <= MAX_SUGGESTION_LIMIT
+        )  # bool, float and str are rejected
+
+    @classmethod
+    def get_config(cls) -> Dict[str, Any]:
+        return {"defaults": {"suggestion_limit": cls.SUGGESTION_LIMIT}}
+
+    @classmethod
+    def update_config(cls, new_config: Any) -> None:
+        if not isinstance(new_config, dict):
+            config_logger.warning("Ignoring autotag settings that are not an object")
+            return
+        defaults = new_config.get("defaults", {})
+        if not isinstance(defaults, dict):
+            config_logger.warning("Ignoring autotag.defaults that is not an object")
+            return
+        if "suggestion_limit" not in defaults:
+            return
+        value = defaults["suggestion_limit"]
+        if cls.valid_suggestion_limit(value):
+            cls.SUGGESTION_LIMIT = value
+            return
+        config_logger.warning(
+            "autotag.defaults.suggestion_limit must be an integer from 1 to "
+            f"{MAX_SUGGESTION_LIMIT}; using {DEFAULT_SUGGESTION_LIMIT}"
+        )
+        cls.SUGGESTION_LIMIT = DEFAULT_SUGGESTION_LIMIT
+
+
 class PromptManagerConfig:
     """Main configuration class for PromptManager core functionality.
 
@@ -566,6 +619,7 @@ class PromptManagerConfig:
             },
             "gallery": GalleryConfig.get_config(),
             "integrations": IntegrationConfig.get_config(),
+            "autotag": AutotagConfig.get_config(),
         }
 
     @classmethod
@@ -706,6 +760,9 @@ class PromptManagerConfig:
         if "integrations" in new_config:
             IntegrationConfig.update_config(new_config["integrations"])
 
+        if "autotag" in new_config:
+            AutotagConfig.update_config(new_config["autotag"])
+
 
 # Load configuration on import
 try:

py/model_gate.py

@@ -0,0 +1,177 @@
+"""One process-wide, non-blocking gate around the tagging models (#249 B2).
+
+Loading, swapping, running, downloading and unloading a tagging model all
+happen under this gate, whether the caller is a legacy Auto-tag route, the
+Tag dialog's Generate or (later) a bulk job. A caller that cannot take the
+gate is refused at once (``409 model-busy``), never queued.
+
+Work that runs in a worker thread is admitted with :meth:`ModelGate.run`. A
+release requested while such work still runs (a client disconnect cancels
+the waiting coroutine, not the thread) takes effect only when the last
+admitted call really exits, so nobody can swap the model under a running
+inference.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+import uuid
+from typing import Any, Callable, Optional
+
+
+class GateNotHeld(RuntimeError):
+    """Raised when work is admitted for an owner that does not hold the gate."""
+
+
+class ModelGate:
+    """A single-owner gate whose release waits for admitted worker calls."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._holder: Optional[str] = None
+        self._inflight = 0
+        self._releasing = False
+
+    def try_acquire(self, owner: str) -> bool:
+        """Take the gate for *owner*; False at once when anyone holds it."""
+        with self._lock:
+            if self._holder is not None:
+                return False
+            self._holder = owner
+            self._inflight = 0
+            self._releasing = False
+            return True
+
+    def release(self, owner: str) -> None:
+        """Let go; deferred until admitted work of *owner* has exited."""
+        with self._lock:
+            if self._holder != owner:
+                return
+            if self._inflight:
+                self._releasing = True
+            else:
+                self._clear_locked()
+
+    def holder(self) -> Optional[str]:
+        with self._lock:
+            return self._holder
+
+    def begin(self, owner: str) -> None:
+        """Admit one worker call; the holder must still hold the gate."""
+        with self._lock:
+            if self._holder != owner or self._releasing:
+                raise GateNotHeld(f"{owner} does not hold the model gate")
+            self._inflight += 1
+
+    def end(self, owner: str) -> None:
+        """One admitted call exited; completes a deferred release."""
+        with self._lock:
+            self._end_locked(owner)
+
+    async def run(
+        self,
+        owner: str,
+        func: Callable[..., Any],
+        *args,
+        on_skipped: Optional[Callable[[], None]] = None,
+        **kwargs,
+    ):
+        """Run ``func`` in the default executor while *owner* holds the gate.
+
+        The executor future is shielded: cancelling the caller never cancels
+        a call that has not started yet (which would leave it admitted
+        forever) and never ends the admission of a call that is running.
+        ``on_skipped`` runs once when ``func`` never starts (the gate is not
+        held, the executor refuses the call, or a loop shutdown drops it), so
+        a caller can free what ``func`` would have freed.
+        """
+        try:
+            self.begin(owner)
+        except GateNotHeld:
+            if on_skipped is not None:
+                on_skipped()
+            raise
+        state = {"started": False, "finished": False}
+
+        def finish() -> None:
+            with self._lock:
+                if not state["finished"]:
+                    state["finished"] = True
+                    self._end_locked(owner)
+
+        def work():
+            with self._lock:
+                if state["finished"]:
+                    # Already declared skipped (the future was cancelled as
+                    # the thread picked the call up): never run it twice over.
+                    return None
+                state["started"] = True
+            try:
+                return func(*args, **kwargs)
+            finally:
+                finish()
+
+        def never_ran(future) -> None:
+            # Only a loop shutdown cancels the shielded future; a call that
+            # never started must still give its admission back.
+            if future.cancelled():
+                with self._lock:
+                    skipped = not state["started"] and not state["finished"]
+                    if skipped:
+                        state["finished"] = True
+                        self._end_locked(owner)
+                if skipped and on_skipped is not None:
+                    on_skipped()
+
+        try:
+            future = asyncio.get_running_loop().run_in_executor(None, work)
+        except BaseException:
+            finish()
+            if on_skipped is not None:
+                on_skipped()
+            raise
+        future.add_done_callback(never_ran)
+        return await asyncio.shield(future)
+
+    def _end_locked(self, owner: str) -> None:
+        if self._holder != owner or self._inflight == 0:
+            return
+        self._inflight -= 1
+        if self._releasing and self._inflight == 0:
+            self._clear_locked()
+
+    def _clear_locked(self) -> None:
+        self._holder = None
+        self._inflight = 0
+        self._releasing = False
+
+
+_GATE = ModelGate()
+
+
+def new_owner(kind: str) -> str:
+    """A unique owner name such as ``legacy-single:<uuid>``."""
+    return f"{kind}:{uuid.uuid4()}"
+
+
+def try_acquire(owner: str) -> bool:
+    return _GATE.try_acquire(owner)
+
+
+def release(owner: str) -> None:
+    _GATE.release(owner)
+
+
+def holder() -> Optional[str]:
+    return _GATE.holder()
+
+
+async def run(
+    owner: str,
+    func: Callable[..., Any],
+    *args,
+    on_skipped: Optional[Callable[[], None]] = None,
+    **kwargs,
+):
+    return await _GATE.run(owner, func, *args, on_skipped=on_skipped, **kwargs)

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

@@ -80,6 +80,21 @@ class TestModel:
     def generate_tags(self, image_path: str, **kwargs: object) -> list[str]:
         return ["generated", Path(image_path).parent.parent.name]
 
+    def generate_tag_suggestions(
+        self, image_path: str, *, limit: int, **kwargs: object
+    ) -> list[tuple[str, float | None]]:
+        """Fixed scored suggestions (WD14) or unscored ones (language models)."""
+        scored = self.loaded is not None and self.loaded.startswith("wd14")
+        names = ["sandstone", "desert", "arch", "sky", "rock", "dune", "canyon"]
+        names += [f"tag_{index:02d}" for index in range(100)]
+        return [
+            (name, round(0.98 - index * 0.008, 3) if scored else None)
+            for index, name in enumerate(names[:limit])
+        ]
+
+    def download_model(self, model_type: str, progress_callback=None) -> bool:
+        raise AssertionError("browser tests never download a model")
+
 
 REVEAL_OUTCOMES = ("opened", "unavailable", "fail")
 
@@ -189,6 +204,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-library.spec.mjs

@@ -256,6 +256,19 @@ test('returning from history restores library context and mobile content stays i
     await expect(history(page)).toHaveCount(0);await expect(page.locator('dialog[open]')).toHaveCount(0);
 });
 
+test('leaving the shelf before its first page answers and returning reads page one without a page error',async({page})=>{
+    // Hold the first shelf page so the route changes while the shelf is still loading (a slow CI runner's natural order).
+    let reached;const firstRead=new Promise(resolve=>{reached=resolve;});
+    await page.route(url=>url.pathname==='/prompt_manager/library'&&!url.searchParams.has('cursor'),route=>{reached();});
+    await page.goto(route);await firstRead;await expect(page.locator('.library-status')).toHaveText('Loading prompt library…');
+    await page.evaluate(()=>{window.location.hash='#/tags';});
+    await expect(page.locator('#workspace-main > .heading h1')).toHaveText('Tags & categories');
+    await page.unrouteAll({behavior:'ignoreErrors'});
+    await page.evaluate(()=>{window.location.hash='#/library';});
+    await expect(page.locator('#workspace-main > .heading h1')).toHaveText('Prompt library');
+    await expect(cards(page)).toHaveCount(3);await expect(page.locator('.section-caption')).toContainText('3 positive prompts');
+    expect(page.libraryErrors).toEqual([]);
+});
 test('empty shelf visits restore saved scroll without inventing a parent anchor',async({page})=>{
     await page.setViewportSize({width:1600,height:300});await page.goto(route);
     await page.getByRole('searchbox',{name:'Search workspace',exact:true}).fill('No matching saved positive');

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/host_stubs.py

@@ -0,0 +1,29 @@
+"""One stand-in for ComfyUI's ``folder_paths`` module, shared by every test.
+
+Test modules that import the API standalone need a ``folder_paths`` module.
+It must be a real module, not a ``MagicMock``: ``patch("folder_paths.x",
+create=True)`` then adds and removes plain attributes, while a mock would
+hand a later test an auto-created child (or lose the attribute on exit), so
+the outcome depended on which test module discovery imported first.
+"""
+
+import sys
+import tempfile
+import types
+
+
+def install_folder_paths_stub() -> types.ModuleType:
+    """Install the shared ``folder_paths`` stub unless a real module is there.
+
+    A test that installs its own stand-in for a while (and restores it) is
+    left alone; a ``MagicMock`` left behind by older code is replaced.
+    """
+    current = sys.modules.get("folder_paths")
+    if isinstance(current, types.ModuleType):
+        return current
+    stub = types.ModuleType("folder_paths")
+    stub.models_dir = tempfile.gettempdir()
+    stub.base_path = tempfile.gettempdir()
+    stub.get_output_directory = tempfile.gettempdir
+    sys.modules["folder_paths"] = stub
+    return stub

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-library-state.test.js

@@ -47,6 +47,22 @@ test('restored shelves keep filters, loaded parents and continuation without a f
  const next=createLibraryStream({api:{get:async url=>{urls.push(url);return page([item(2)]);}},restore:{filters:{text:'retained',sort:'name'},state:old.state}});assert.equal(next.state.items.length,1);await next.loadMore();assert.match(urls[0],/text=retained/);assert.match(urls[0],/cursor=next/);assert.equal(next.state.items.length,2);next.dispose();
  assert.throws(()=>createLibraryStream({api:{},restore:{filters:{},state:{items:[item(1),item(1)],total:2,variantTotal:0,cursor:null,hasMore:false}}}));
 });
+test('a shelf left before its first page answered or after it failed restores and reads page one',async()=>{
+ const {createLibraryStream}=await source;
+ // The shelf saves whatever state it holds when the route changes; a first page still pending or failed has no variant total yet.
+ let pending;const left=createLibraryStream({api:{get:()=>new Promise(resolve=>{pending=resolve;})}});const first=left.reset({text:'kept'});
+ assert.equal(left.state.loading,true);assert.equal(left.state.variantTotal,null);const saved=left.state;left.dispose();pending(page([item(9)]));await first;
+ const failed=createLibraryStream({api:{get:async()=>{throw Error('offline');}}});await failed.reset();assert.ok(failed.state.error);failed.dispose();
+ for(const state of [saved,failed.state]) {
+  const urls=[];const next=createLibraryStream({api:{get:async url=>{urls.push(url);return page([item(1)]);}},restore:{filters:{text:'kept'},state}});
+  assert.deepEqual([next.state.items.length,next.state.loading,next.state.error,next.state.variantTotal,next.state.hasMore],[0,false,null,null,true]);
+  assert.equal(await next.loadMore(),1);assert.equal(new URL(urls[0],'https://x').searchParams.get('text'),'kept');assert.equal(new URL(urls[0],'https://x').searchParams.has('cursor'),false);
+  assert.equal(next.state.variantTotal,6);next.dispose();
+ }
+ // A pending first page is only the empty, cursorless state: anything else without a variant total stays invalid.
+ for(const state of [{items:[item(1)],total:1,variantTotal:null,cursor:null,hasMore:false},{items:[],total:0,variantTotal:null,cursor:'next',hasMore:true},{items:[],total:3,variantTotal:null,cursor:null,hasMore:true},{items:[],total:0,variantTotal:null,cursor:null,hasMore:false}])
+  assert.throws(()=>createLibraryStream({api:{},restore:{filters:{},state}}),/Invalid library page/);
+});
 test('parent shelf window bounds DOM and pins focused rows without changing logical order',async()=>{
  const {libraryWindow}=await source;const first=libraryWindow(500,2,0,900);assert.equal(first[0],0);assert.ok(first.length<24);
  const middle=libraryWindow(500,2,50000,900,0);assert.equal(middle[0],0);assert.ok(middle.some(index=>index>150));assert.ok(middle.length<24);assert.deepEqual(middle,[...middle].sort((a,b)=>a-b));assert.deepEqual(libraryWindow(3,2,0,900),[0,1,2]);

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_annotation_suggest.py

@@ -0,0 +1,556 @@
+"""Scored top-N tag suggestions for a captured image (#249 B2).
+
+``POST /prompt_manager/image-annotations/suggest`` runs the selected legacy
+engine on the private capture (never the current file), behind the one
+process-wide model gate shared with the legacy Auto-tag routes. It never
+downloads a model and never writes. No real model is loaded: the engine is a
+fake service.
+"""
+
+import asyncio
+import json
+import math
+import os
+import threading
+import unittest
+import uuid
+from unittest.mock import MagicMock, patch
+
+try:
+    from test_api_annotations import AnnotationAPITestCase
+    from test_api_images import make_png
+except ImportError:
+    from tests.test_api_annotations import AnnotationAPITestCase
+    from tests.test_api_images import make_png
+
+try:  # guarded so a missing module fails assertions, not test loading
+    from py import model_gate
+except ImportError:
+    model_gate = None
+
+from py import config as config_module
+
+AutotagConfig = getattr(config_module, "AutotagConfig", None)
+
+SUGGEST = "/prompt_manager/image-annotations/suggest"
+WAIT = 30.0
+WD14 = {"general_threshold": 0.35, "character_threshold": 0.85}
+LLM = {"instructions": "Generate tags."}
+UNAVAILABLE = "Download it from the legacy Auto-tag page."
+
+SCORED = [("sandstone", 0.98), ("desert", 0.96)] + [
+    (f"tag_{i:03d}", round(0.9 - i * 0.005, 4)) for i in range(150)
+]
+
+
+class FakeTagger:
+    """Stand-in for ``AutoTagService`` with the suggestion entry point."""
+
+    default_prompt = "server default prompt"
+    custom_prompt = "legacy prompt"
+    wd14_general_threshold = 0.35
+    wd14_character_threshold = 0.85
+
+    def __init__(self):
+        self.models_config = {
+            "wd14-swinv2": {},
+            "wd14-vit": {},
+            "gguf": {},
+            "hf": {},
+        }
+        self.downloaded = {name: True for name in self.models_config}
+        self.loaded = None
+        self.load_calls = []
+        self.unload_calls = 0
+        self.calls = []
+        self.read_paths = []
+        self.read_bytes = []
+        self.download_model = MagicMock(side_effect=AssertionError("downloaded"))
+        self.load_error = None
+        self.block = None  # (entered, proceed) events
+
+    def get_models_status(self):
+        return {
+            name: {"downloaded": self.downloaded[name], "model_path": None}
+            for name in self.models_config
+        }
+
+    def is_model_loaded(self):
+        return self.loaded is not None
+
+    def get_loaded_model_type(self):
+        return self.loaded
+
+    def load_model(self, model_type, use_gpu=True):
+        self.load_calls.append((model_type, use_gpu))
+        if self.load_error is not None:
+            raise self.load_error
+        self.loaded = model_type
+        return True
+
+    def unload_model(self):
+        self.unload_calls += 1
+        self.loaded = None
+
+    def generate_tags(self, image_path, **kwargs):
+        return ["legacy"]
+
+    def generate_tag_suggestions(
+        self,
+        image_path,
+        *,
+        limit,
+        prompt=None,
+        general_threshold=None,
+        character_threshold=None,
+    ):
+        self.read_paths.append(image_path)
+        with open(image_path, "rb") as handle:
+            self.read_bytes.append(handle.read())
+        self.calls.append(
+            {
+                "limit": limit,
+                "prompt": prompt,
+                "general_threshold": general_threshold,
+                "character_threshold": character_threshold,
+                "model": self.loaded,
+            }
+        )
+        if self.block is not None:
+            entered, proceed = self.block
+            entered.set()
+            proceed.wait(WAIT)
+        if self.loaded.startswith("wd14"):
+            return list(SCORED[:limit])
+        return [(name, None) for name, _ in SCORED[:limit]]
+
+
+class SuggestTestCase(AnnotationAPITestCase):
+    async def get_application(self):
+        app = await super().get_application()
+        self.assertIsNotNone(model_gate, "py.model_gate is not implemented")
+        self.assertIsNotNone(AutotagConfig, "AutotagConfig is not implemented")
+        self.tagger = FakeTagger()
+        patcher = patch("py.autotag.get_autotag_service", return_value=self.tagger)
+        patcher.start()
+        self.addCleanup(patcher.stop)
+        AutotagConfig.SUGGESTION_LIMIT = 10
+        self.addCleanup(setattr, AutotagConfig, "SUGGESTION_LIMIT", 10)
+        return app
+
+    async def tearDownAsync(self):
+        leaked = model_gate.holder() if model_gate is not None else None
+        if leaked is not None:
+            model_gate.release(leaked)
+        await super().tearDownAsync()
+        self.assertIsNone(leaked, "the suggest route left the model gate held")
+
+    async def observed(self, path="sub/a.png", size=(8, 6)):
+        make_png(self.output_dir / path, size=size)
+        return await self.observe_ok(path)
+
+    def suggest_body(self, observed, model_type="wd14-vit", options=None, **changes):
+        if options is None:
+            options = dict(WD14 if model_type.startswith("wd14") else LLM)
+        return {
+            "target": dict(observed["target"]),
+            "capture_token": observed["capture"]["token"],
+            "expected_epoch": observed["library_epoch"],
+            "model_type": model_type,
+            "options": options,
+            **changes,
+        }
+
+    async def suggest(self, body):
+        response = await self.client.post(SUGGEST, json=body)
+        return response.status, await self.json_of(response)
+
+    async def suggest_ok(self, body):
+        status, data = await self.suggest(body)
+        self.assertEqual(status, 200, data)
+        return data
+
+    def capture_path(self, observed):
+        return self.api._captures.get(observed["capture"]["token"]).path
+
+    async def wait_until_free(self):
+        for _ in range(3000):
+            if model_gate.holder() is None:
+                return
+            await asyncio.sleep(0.01)
+        self.fail(f"model gate still held by {model_gate.holder()}")
+
+
+class TestSuggestions(SuggestTestCase):
+    async def test_wd14_suggestions_are_scored_top_n_from_the_capture(self):
+        observed = await self.observed()
+
+        body = await self.suggest_ok(self.suggest_body(observed))
+
+        self.assertEqual(
+            body["suggestions"][:2],
+            [
+                {"name": "sandstone", "confidence": 0.98},
+                {"name": "desert", "confidence": 0.96},
+            ],
+        )
+        self.assertEqual(len(body["suggestions"]), 10)
+        self.assertEqual(body["model_type"], "wd14-vit")
+        self.assertEqual(
+            body["options"],
+            {
+                "general_threshold": 0.35,
+                "character_threshold": 0.85,
+                "use_gpu": True,
+                "suggestion_limit": 10,
+            },
+        )
+        self.assertEqual(self.tagger.read_paths, [self.capture_path(observed)])
+        self.assertEqual(
+            self.tagger.calls[0],
+            {
+                "limit": 10,
+                "prompt": None,
+                "general_threshold": 0.35,
+                "character_threshold": 0.85,
+                "model": "wd14-vit",
+            },
+        )
+        self.assertEqual(self.tagger.load_calls, [("wd14-vit", True)])
+        self.tagger.download_model.assert_not_called()
+        self.assertIsNone(model_gate.holder())
+        self.assert_no_paths(body)
+
+    async def test_suggestions_keep_the_requested_limit(self):
+        observed = await self.observed()
+        for limit in (1, 10, 100):
+            with self.subTest(limit=limit):
+                options = {**WD14, "suggestion_limit": limit}
+                body = await self.suggest_ok(
+                    self.suggest_body(observed, options=options)
+                )
+                self.assertEqual(len(body["suggestions"]), limit)
+                self.assertEqual(body["options"]["suggestion_limit"], limit)
+        # Omitted: the persisted autotag.defaults.suggestion_limit.
+        AutotagConfig.SUGGESTION_LIMIT = 3
+        body = await self.suggest_ok(self.suggest_body(observed))
+        self.assertEqual(len(body["suggestions"]), 3)
+        self.assertEqual(body["options"]["suggestion_limit"], 3)
+
+    async def test_llm_suggestions_send_instructions_and_null_confidence(self):
+        observed = await self.observed()
+        self.tagger.custom_prompt = "legacy prompt"
+        for model_type in ("gguf", "hf"):
+            with self.subTest(model_type=model_type):
+                options = {"instructions": f"tags for {model_type}", "use_gpu": False}
+                body = await self.suggest_ok(
+                    self.suggest_body(observed, model_type, options)
+                )
+                self.assertEqual(body["model_type"], model_type)
+                self.assertEqual(body["options"], {**options, "suggestion_limit": 10})
+                self.assertEqual(
+                    body["suggestions"][:2],
+                    [
+                        {"name": "sandstone", "confidence": None},
+                        {"name": "desert", "confidence": None},
+                    ],
+                )
+                call = self.tagger.calls[-1]
+                self.assertEqual(call["prompt"], f"tags for {model_type}")
+                self.assertIsNone(call["general_threshold"])
+                self.assertEqual(self.tagger.load_calls[-1], (model_type, False))
+        self.assertEqual(self.tagger.custom_prompt, "legacy prompt")
+
+    async def test_loaded_model_is_reused_and_another_is_swapped_in(self):
+        observed = await self.observed()
+        self.tagger.loaded = "wd14-vit"
+        await self.suggest_ok(self.suggest_body(observed))
+        self.assertEqual(self.tagger.load_calls, [])
+        await self.suggest_ok(self.suggest_body(observed, "wd14-swinv2"))
+        self.assertEqual(self.tagger.load_calls, [("wd14-swinv2", True)])
+        self.assertEqual(self.tagger.calls[-1]["model"], "wd14-swinv2")
+
+    async def test_suggest_uses_capture_bytes_not_current_file(self):
+        observed = await self.observed()
+        original = (self.output_dir / "sub" / "a.png").read_bytes()
+        make_png(self.output_dir / "sub" / "a.png", size=(9, 9), color=(0, 0, 255))
+        self.assertNotEqual((self.output_dir / "sub" / "a.png").read_bytes(), original)
+
+        await self.suggest_ok(self.suggest_body(observed))
+
+        capture_path = self.capture_path(observed)
+        self.assertEqual(self.tagger.read_paths, [capture_path])
+        self.assertEqual(self.tagger.read_bytes, [original])
+        self.assertNotEqual(
+            os.path.normcase(capture_path),
+            os.path.normcase(str(self.output_dir / "sub" / "a.png")),
+        )
+
+    async def test_suggest_writes_nothing(self):
+        observed = await self.observed()
+        before = self.db_snapshot()
+        rows = self.bytes_rows()
+
+        await self.suggest_ok(self.suggest_body(observed))
+        await self.suggest_ok(self.suggest_body(observed, "gguf"))
+
+        self.assertEqual(self.db_snapshot(), before)
+        self.assertEqual(self.bytes_rows(), rows)
+        # The capture stays usable for Save after Generate.
+        self.assertIsNotNone(self.api._captures.get(observed["capture"]["token"]))
+
+
+class TestModelAvailability(SuggestTestCase):
+    async def test_suggest_never_downloads_and_reports_model_unavailable(self):
+        observed = await self.observed()
+        self.tagger.downloaded["wd14-vit"] = False
+
+        status, body = await self.suggest(self.suggest_body(observed))
+
+        self.assertEqual((status, body["code"]), (409, "model-unavailable"))
+        self.assertIn(UNAVAILABLE, body["error"])
+        self.assertIn("WD14 ViT", body["error"])
+        self.tagger.download_model.assert_not_called()
+        self.assertEqual(self.tagger.load_calls, [])
+        self.assertEqual(self.tagger.calls, [])
+        self.assertIsNone(model_gate.holder())
+
+    async def test_load_failure_is_a_generic_error_and_frees_everything(self):
+        observed = await self.observed()
+        self.tagger.load_error = RuntimeError(f"cannot load {self.output_dir}")
+
+        status, body = await self.suggest(self.suggest_body(observed))
+
+        self.assertEqual((status, body["code"]), (500, "suggest-failed"))
+        self.assert_no_paths(body)
+        self.assertIsNone(model_gate.holder())
+        entry = self.api._captures._entries[observed["capture"]["token"]]
+        self.assertEqual(entry.uses, 0)
+
+    async def test_gate_work_that_never_starts_releases_the_capture_pin(self):
+        observed = await self.observed()
+        loop = asyncio.get_running_loop()
+        real = loop.run_in_executor
+
+        def refuse_gate_work(executor, func, *args):
+            if getattr(func, "__qualname__", "").startswith("ModelGate.run"):
+                raise RuntimeError("cannot schedule new futures after shutdown")
+            return real(executor, func, *args)
+
+        with patch.object(loop, "run_in_executor", refuse_gate_work):
+            status, body = await self.suggest(self.suggest_body(observed))
+
+        self.assertEqual((status, body["code"]), (500, "suggest-failed"))
+        self.assertIsNone(model_gate.holder())
+        entry = self.api._captures._entries[observed["capture"]["token"]]
+        self.assertEqual(entry.uses, 0)
+        self.assertEqual(self.tagger.calls, [])
+
+
+class TestModelGate(SuggestTestCase):
+    async def _blocked_suggest(self, observed, model_type="wd14-vit"):
+        entered, proceed = threading.Event(), threading.Event()
+        self.tagger.block = (entered, proceed)
+        task = asyncio.ensure_future(
+            self.client.post(SUGGEST, json=self.suggest_body(observed, model_type))
+        )
+        await asyncio.get_running_loop().run_in_executor(None, entered.wait, WAIT)
+        self.assertTrue(entered.is_set())
+        return task, proceed
+
+    async def test_suggest_reports_busy_while_legacy_batch_runs(self):
+        observed = await self.observed()
+        prompt_id = self._save_prompt("batch prompt")
+        self.api.db.link_image_to_prompt(prompt_id, str(self.output_dir / "sub/a.png"))
+        started, proceed = threading.Event(), threading.Event()
+
+        def slow_generate(image_path, **kwargs):
+            started.set()
+            proceed.wait(WAIT)
+            return ["batch"]
+
+        self.tagger.generate_tags = slow_generate
+        batch = asyncio.ensure_future(
+            self.client.post("/prompt_manager/autotag/start?model_type=wd14-vit")
+        )
+        try:
+            await asyncio.get_running_loop().run_in_executor(None, started.wait, WAIT)
+            status, body = await self.suggest(self.suggest_body(observed, "gguf"))
+            self.assertEqual((status, body["code"]), (409, "model-busy"))
+            self.assertEqual(self.tagger.calls, [])
+            self.assertEqual(self.tagger.loaded, "wd14-vit")  # not swapped
+        finally:
+            proceed.set()
+            response = await batch
+            await response.read()
+        await self.wait_until_free()
+        await self.suggest_ok(self.suggest_body(observed))
+
+    async def test_legacy_unload_returns_model_busy_while_native_generate_runs(self):
+        observed = await self.observed()
+        task, proceed = await self._blocked_suggest(observed)
+        try:
+            response = await self.client.post("/prompt_manager/autotag/unload")
+            self.assertEqual(response.status, 409)
+            self.assertEqual((await response.json())["code"], "model-busy")
+            response = await self.client.post(
+                "/prompt_manager/autotag/single",
+                json={"root_index": 0, "path": "sub/a.png", "model_type": "gguf"},
+            )
+            self.assertEqual(response.status, 409)
+            status, body = await self.suggest(self.suggest_body(observed, "gguf"))
+            self.assertEqual((status, body["code"]), (409, "model-busy"))
+            self.assertEqual(self.tagger.unload_calls, 0)
+            self.assertEqual(self.tagger.loaded, "wd14-vit")
+        finally:
+            proceed.set()
+            response = await task
+        self.assertEqual(response.status, 200)
+        await self.wait_until_free()
+        self.assertEqual([call["model"] for call in self.tagger.calls], ["wd14-vit"])
+
+    async def test_gate_held_after_client_disconnect_until_executor_finishes(self):
+        observed = await self.observed()
+        token = observed["capture"]["token"]
+        task, proceed = await self._blocked_suggest(observed)
+        task.cancel()
+        with self.assertRaises(asyncio.CancelledError):
+            await task
+        try:
+            # The client is gone; the inference still runs, so the gate and
+            # the capture pin stay until the worker thread exits.
+            self.assertIsNotNone(model_gate.holder())
+            response = await self.client.post("/prompt_manager/autotag/unload")
+            self.assertEqual(response.status, 409)
+            self.assertEqual(self.api._captures._entries[token].uses, 1)
+        finally:
+            proceed.set()
+        await self.wait_until_free()
+        for _ in range(3000):
+            if self.api._captures._entries[token].uses == 0:
+                break
+            await asyncio.sleep(0.01)
+        self.assertEqual(self.api._captures._entries[token].uses, 0)
+        response = await self.client.post("/prompt_manager/autotag/unload")
+        self.assertEqual(response.status, 200)
+
+
+class TestRequestValidation(SuggestTestCase):
+    async def test_strict_option_validation(self):
+        observed = await self.observed()
+        bad_options = {
+            "wd14-vit": [
+                {**WD14, "general_threshold": True},
+                {**WD14, "general_threshold": math.nan},
+                {**WD14, "general_threshold": math.inf},
+                {**WD14, "general_threshold": "0.3"},
+                {**WD14, "general_threshold": 1.5},
+                {**WD14, "character_threshold": -0.1},
+                {"general_threshold": 0.35},
+                {**WD14, "instructions": "x"},
+                {**WD14, "unknown": 1},
+                {**WD14, "use_gpu": "yes"},
+                {**WD14, "suggestion_limit": 0},
+                {**WD14, "suggestion_limit": 101},
+                {**WD14, "suggestion_limit": 2.5},
+                {**WD14, "suggestion_limit": "10"},
+                {**WD14, "suggestion_limit": True},
+            ],
+            "gguf": [
+                {**LLM, "general_threshold": 0.35},
+                {**LLM, "character_threshold": 0.85},
+                {"instructions": "x" * 4001},
+                {"instructions": "\ud800"},  # not encodable as UTF-8
+                {"instructions": "   "},
+                {"instructions": 5},
+                {},
+                {**LLM, "suggestion_limit": 0},
+            ],
+        }
+        for model_type, cases in bad_options.items():
+            for options in cases:
+                with self.subTest(model_type=model_type, options=repr(options)[:80]):
+                    status, body = await self.suggest(
+                        self.suggest_body(observed, model_type, options)
+                    )
+                    self.assertEqual(status, 400, body)
+        for body in (
+            {**self.suggest_body(observed), "extra": 1},
+            {k: v for k, v in self.suggest_body(observed).items() if k != "options"},
+            self.suggest_body(observed, options=[]),
+            self.suggest_body(observed, model_type="ollama"),
+            self.suggest_body(observed, model_type=7, options=dict(WD14)),
+            self.suggest_body(observed, capture_token="../x"),
+            self.suggest_body(observed, expected_epoch="nope"),
+            self.suggest_body(observed, target={"root_index": 0}),
+        ):
+            with self.subTest(body=json.dumps(body)[:120]):
+                status, _ = await self.suggest(body)
+                self.assertEqual(status, 400)
+        # The edges that are allowed.
+        await self.suggest_ok(
+            self.suggest_body(
+                observed,
+                options={
+                    "general_threshold": 0,
+                    "character_threshold": 1,
+                    "suggestion_limit": 100,
+                },
+            )
+        )
+        await self.suggest_ok(
+            self.suggest_body(observed, "hf", options={"instructions": "x" * 4000})
+        )
+        self.assertEqual(len(self.tagger.calls), 2)
+        self.tagger.download_model.assert_not_called()
+
+    async def test_capture_token_must_match_target_and_epoch(self):
+        observed = await self.observed()
+        make_png(self.output_dir / "sub" / "b.png")
+        other = await self.observe_ok("sub/b.png")
+
+        status, body = await self.suggest(
+            self.suggest_body(observed, capture_token="x" * 43)
+        )
+        self.assertEqual((status, body["code"]), (409, "capture-expired"))
+        status, body = await self.suggest(
+            self.suggest_body(observed, capture_token=other["capture"]["token"])
+        )
+        self.assertEqual((status, body["code"]), (409, "capture-expired"))
+        status, body = await self.suggest(
+            self.suggest_body(observed, expected_epoch=str(uuid.uuid4()))
+        )
+        self.assertEqual((status, body["code"]), (409, "storage-changed"))
+        self.assertEqual(body["library_epoch"], self.epoch)
+        status, body = await self.suggest(
+            self.suggest_body(
+                observed, target={**observed["target"], "root_scope": "0" * 64}
+            )
+        )
+        self.assertEqual((status, body["code"]), (409, "source-changed"))
+        self.api._captures.release(observed["capture"]["token"])
+        status, body = await self.suggest(self.suggest_body(observed))
+        self.assertEqual((status, body["code"]), (409, "capture-expired"))
+        self.assertEqual(self.tagger.calls, [])
+        for token in (observed, other):
+            entry = self.api._captures._entries.get(token["capture"]["token"])
+            self.assertTrue(entry is None or entry.uses == 0)
+
+    async def test_video_and_oversized_dimensions_unsupported_media(self):
+        (self.output_dir / "clip.mp4").write_bytes(b"\x00\x00\x00\x18ftypmp42" * 4)
+        video = await self.observe_ok("clip.mp4")
+        self.assertFalse(video["capture"]["generate"]["supported"])
+        big = await self.observed("big.png", size=(4097, 1))
+        self.assertFalse(big["capture"]["generate"]["supported"])
+
+        for observed in (video, big):
+            status, body = await self.suggest(self.suggest_body(observed))
+            self.assertEqual((status, body["code"]), (415, "unsupported-media"))
+            self.assertEqual(body["error"], observed["capture"]["generate"]["reason"])
+        self.assertEqual(self.tagger.calls, [])
+        self.assertEqual(self.tagger.load_calls, [])
+        self.assertIsNone(model_gate.holder())
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_api_autotag.py

@@ -11,7 +11,6 @@ import shutil
 import sys
 import tempfile
 import threading
-import types
 import unittest
 from unittest.mock import MagicMock
 from pathlib import Path
@@ -23,12 +22,12 @@ sys.modules.setdefault("server", _mock_server)  # py.config imports it at module
 
 sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 
-if "folder_paths" not in sys.modules:
-    _stub = types.ModuleType("folder_paths")
-    _stub.models_dir = tempfile.gettempdir()
-    _stub.base_path = tempfile.gettempdir()
-    _stub.get_output_directory = tempfile.gettempdir
-    sys.modules["folder_paths"] = _stub
+try:
+    from host_stubs import install_folder_paths_stub
+except ImportError:  # imported as tests.test_api_autotag
+    from tests.host_stubs import install_folder_paths_stub
+
+install_folder_paths_stub()
 
 from aiohttp import web
 from aiohttp.test_utils import AioHTTPTestCase
@@ -37,6 +36,11 @@ from database.operations import PromptDatabase
 from py.api import PromptManagerAPI
 from utils.hashing import generate_prompt_hash
 
+try:  # guarded so a missing module fails assertions, not test loading
+    from py import model_gate
+except ImportError:
+    model_gate = None
+
 
 class FakeAutotagService:
     """Stand-in for AutoTagService that records calls and returns fixed tags."""
@@ -128,6 +132,11 @@ class AutotagAPITestCase(AioHTTPTestCase):
     async def tearDownAsync(self):
         await super().tearDownAsync()  # closes the aiohttp test client
         self._service_patch.stop()
+        if model_gate is not None:
+            leaked = model_gate.holder()
+            if leaked is not None:  # never leak the process-wide gate
+                model_gate.release(leaked)
+            self.assertIsNone(leaked, "a route left the model gate held")
         self.api.db.close_all()
         for path in (
             self._temp_db.name,
@@ -947,6 +956,159 @@ class TestUnloadAutotag(AutotagAPITestCase):
         self.assertEqual(resp.status, 500)
 
 
+class TestLegacyRoutesShareTheModelGate(AutotagAPITestCase):
+    """While another model operation holds the gate, every legacy model route
+    answers ``409 model-busy`` and touches no model (the one allowed legacy
+    change)."""
+
+    BUSY = {"success": False, "code": "model-busy"}
+
+    def setUp(self):
+        super().setUp()
+        self.assertIsNotNone(model_gate, "py.model_gate is not implemented")
+
+    async def _busy(self, resp):
+        self.assertEqual(resp.status, 409)
+        data = await resp.json()
+        self.assertEqual({k: data[k] for k in self.BUSY}, self.BUSY)
+        self.assertIn("busy", data["error"].lower())
+        return data
+
+    async def test_legacy_single_download_start_return_model_busy_while_gate_held(
+        self,
+    ):
+        image = self._make_image(self.output_dir)
+        self.service._loaded_type = "wd14-vit"
+        self.assertTrue(model_gate.try_acquire("test-holder"))
+        try:
+            await self._busy(
+                await self._post_json(
+                    "/prompt_manager/autotag/single",
+                    {"path": str(image), "model_type": "gguf"},
+                )
+            )
+            await self._busy(
+                await self.client.request(
+                    "POST", "/prompt_manager/autotag/download/gguf"
+                )
+            )
+            await self._busy(
+                await self.client.request(
+                    "POST", "/prompt_manager/autotag/start?model_type=gguf"
+                )
+            )
+            await self._busy(
+                await self.client.request("POST", "/prompt_manager/autotag/unload")
+            )
+            self.assertEqual(model_gate.holder(), "test-holder")
+        finally:
+            model_gate.release("test-holder")
+
+        self.assertEqual(self.service.load_calls, [])
+        self.assertEqual(self.service.generate_calls, [])
+        self.assertEqual(self.service.download_calls, [])
+        self.assertEqual(self.service.unload_calls, 0)
+        self.assertEqual(self.service.get_loaded_model_type(), "wd14-vit")
+
+        # A refused start released the batch lock: the next start runs.
+        resp = await self.client.request(
+            "POST", "/prompt_manager/autotag/start?model_type=gguf"
+        )
+        self.assertEqual(resp.status, 200)
+        self.assertEqual(self._sse_events(await resp.text())[-1]["type"], "complete")
+
+    async def test_legacy_routes_hold_the_gate_only_while_they_run(self):
+        image = self._make_image(self.output_dir)
+        seen = []
+
+        def generate(image_path, **kwargs):
+            seen.append(model_gate.holder())
+            return ["x"]
+
+        def download(model_type, progress_callback=None):
+            seen.append(model_gate.holder())
+            return True
+
+        def load(model_type, use_gpu=True):
+            seen.append(model_gate.holder())
+            self.service._loaded_type = model_type
+            return True
+
+        self.service.generate_tags = generate
+        self.service.download_model = download
+        self.service.load_model = load
+
+        resp = await self._post_json(
+            "/prompt_manager/autotag/single", {"path": str(image)}
+        )
+        self.assertEqual(resp.status, 200)
+        self.assertIsNone(model_gate.holder())
+        resp = await self.client.request(
+            "POST", "/prompt_manager/autotag/download/gguf"
+        )
+        self.assertEqual(self._sse_events(await resp.text())[-1]["type"], "complete")
+        self.assertIsNone(model_gate.holder())
+        resp = await self.client.request("POST", "/prompt_manager/autotag/unload")
+        self.assertEqual(resp.status, 200)
+        self.assertIsNone(model_gate.holder())
+
+        self.assertEqual(len(seen), 3)
+        self.assertTrue(all(owner and owner.startswith("legacy-") for owner in seen))
+
+    async def test_validation_errors_win_over_the_gate(self):
+        self.assertTrue(model_gate.try_acquire("test-holder"))
+        try:
+            resp = await self._post_json("/prompt_manager/autotag/single", {})
+            self.assertEqual(resp.status, 400)
+            resp = await self.client.request(
+                "POST", "/prompt_manager/autotag/start?general_threshold=x"
+            )
+            self.assertEqual(resp.status, 400)
+        finally:
+            model_gate.release("test-holder")
+
+    async def test_batch_holds_the_gate_until_it_completes(self):
+        prompt = self._save_prompt("p")
+        self._link_image(prompt, self._make_image(self.output_dir, "a.png"))
+        started = threading.Event()
+        proceed = threading.Event()
+
+        def slow_generate(image_path, **kwargs):
+            started.set()
+            proceed.wait(30)
+            return ["slow"]
+
+        self.service.generate_tags = slow_generate
+        run = asyncio.ensure_future(
+            self.client.request("POST", "/prompt_manager/autotag/start")
+        )
+        try:
+            await asyncio.get_running_loop().run_in_executor(None, started.wait, 30)
+            self.assertTrue(model_gate.holder().startswith("legacy-batch:"))
+            await self._busy(
+                await self.client.request("POST", "/prompt_manager/autotag/unload")
+            )
+        finally:
+            proceed.set()
+            resp = await run
+            events = self._sse_events(await resp.text())
+        self.assertEqual(events[-1]["type"], "complete")
+        self.assertIsNone(model_gate.holder())
+
+    async def test_models_response_carries_the_suggestion_limit(self):
+        from py.config import AutotagConfig
+
+        resp = await self.client.get("/prompt_manager/autotag/models")
+        data = await resp.json()
+        self.assertEqual(data["suggestion_limit"], 10)
+        AutotagConfig.SUGGESTION_LIMIT = 25
+        try:
+            resp = await self.client.get("/prompt_manager/autotag/models")
+            self.assertEqual((await resp.json())["suggestion_limit"], 25)
+        finally:
+            AutotagConfig.SUGGESTION_LIMIT = 10
+
+
 class TestScanOutputDir(AutotagAPITestCase):
 
     async def test_lists_images_with_thumbnails(self):

tests/test_api_core.py

@@ -448,6 +448,20 @@ class TestUiRoutes(CoreRoutesTestCase):
         resp = await self.client.request("GET", "/prompt_manager/test")
         self.assertTrue((await resp.json())["success"])
 
+    async def test_image_annotation_routes_are_registered(self):
+        table = {
+            (route.method, route.resource.canonical)
+            for route in self.app.router.routes()
+            if route.resource is not None
+        }
+        for entry in (
+            ("POST", "/prompt_manager/image-annotations/observe"),
+            ("GET", "/prompt_manager/image-annotations/capture/{token}"),
+            ("DELETE", "/prompt_manager/image-annotations/capture/{token}"),
+            ("PUT", "/prompt_manager/image-annotations/tags"),
+        ):
+            self.assertIn(entry, table)
+
 
 class TestStaticRoutes(CoreRoutesTestCase):
 

tests/test_api_images.py

@@ -18,7 +18,12 @@ from unittest.mock import AsyncMock, MagicMock, patch
 sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 
 # ComfyUI-only modules are stubbed so the API can be imported standalone.
-sys.modules.setdefault("folder_paths", MagicMock())
+try:
+    from host_stubs import install_folder_paths_stub
+except ImportError:  # imported as tests.test_api_images
+    from tests.host_stubs import install_folder_paths_stub
+
+install_folder_paths_stub()
 sys.modules.setdefault("server", MagicMock())
 
 from aiohttp import web  # noqa: E402

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", "")
@@ -1444,3 +1642,86 @@ class TestPromptInspector(ImageAPITestCase):
                     lookup.assert_called_once_with(
                         str(path), False, report_ambiguity=True
                     )
+
+
+class TestInspectorImageTags(ImageAPITestCase):
+    """B3: the inspector envelope's ``image_tags`` facet (spec amendment S1)."""
+
+    inspect = TestPromptInspector.inspect
+
+    def tag(self, path, tags):
+        import hashlib
+        import os
+
+        stat = path.stat()
+        return self.api.db.replace_image_tags(
+            locator=os.path.normcase(os.path.realpath(path)),
+            sha256=hashlib.sha256(path.read_bytes()).hexdigest(),
+            size=stat.st_size,
+            mtime_ns=stat.st_mtime_ns,
+            expected_epoch=self.api.db.get_execution_epoch(),
+            expected_tag_revision=0,
+            tags=tags,
+        )
+
+    async def test_inspector_reports_current_none_and_unavailable_image_tags(self):
+        import os
+
+        tagged = png(self.output_dir / "sub" / "tagged.png", prompt=graph())
+        changed = png(self.output_dir / "changed.png", prompt=graph())
+        png(self.output_dir / "untagged.png", prompt=graph())
+        empty = png(self.output_dir / "empty.png", prompt=graph())
+        self.tag(tagged, ["dunes", "warm_light"])
+        self.tag(changed, ["dunes"])
+        self.tag(empty, [])
+        stat = changed.stat()
+        os.utime(changed, ns=(stat.st_atime_ns, stat.st_mtime_ns + 1_000_000))
+
+        response, envelope = await self.inspect("sub/tagged.png")
+        self.assertEqual(response.status, 200, envelope)
+        self.assertEqual(
+            envelope.get("image_tags"),
+            {"state": "current", "tags": ["dunes", "warm_light"]},
+        )
+        # The tags never change the Library facts of the prompt link.
+        self.assertEqual(envelope["library"]["tags"], [])
+        _, changed_body = await self.inspect("changed.png")
+        self.assertEqual(changed_body.get("image_tags"), {"state": "none", "tags": []})
+        _, untagged = await self.inspect("untagged.png")
+        self.assertEqual(untagged.get("image_tags"), {"state": "none", "tags": []})
+        _, saved_empty = await self.inspect("empty.png")
+        self.assertEqual(
+            saved_empty.get("image_tags"), {"state": "current", "tags": []}
+        )
+        with patch.object(
+            self.api.db, "current_image_tags", side_effect=RuntimeError("boom")
+        ):
+            with self.assertLogs("prompt_manager", level="WARNING") as logged:
+                response, failed = await self.inspect("sub/tagged.png")
+        self.assertTrue(
+            any(r.exc_info and "image tags" in r.getMessage() for r in logged.records),
+            logged.output,
+        )
+        self.assertEqual(response.status, 200, failed)
+        self.assertEqual(failed.get("image_tags"), {"state": "unavailable", "tags": []})
+        self.assertEqual(failed["prompts"], envelope["prompts"])
+        self.assertNotIn(str(self.comfy_dir), json.dumps(envelope))
+
+    async def test_inspector_image_tags_use_the_inspection_stable_stat(self):
+        tagged = png(self.output_dir / "tagged.png", prompt=graph())
+        self.tag(tagged, ["dunes"])
+        stat = tagged.stat()
+        seen = []
+        real = self.api.db.current_image_tags
+
+        def spy(stats):
+            seen.append(dict(stats))
+            return real(stats)
+
+        with patch.object(self.api.db, "current_image_tags", side_effect=spy):
+            _, body = await self.inspect("tagged.png")
+        self.assertEqual(
+            body.get("image_tags"), {"state": "current", "tags": ["dunes"]}
+        )
+        self.assertEqual(list(seen[0].values()), [(stat.st_size, stat.st_mtime_ns)])
+        self.assertEqual(len(seen), 1)

tests/test_api_prompts.py

@@ -11,7 +11,12 @@ from unittest.mock import MagicMock, patch
 
 sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 
-sys.modules.setdefault("folder_paths", MagicMock())
+try:
+    from host_stubs import install_folder_paths_stub
+except ImportError:  # imported as tests.test_api_prompts
+    from tests.host_stubs import install_folder_paths_stub
+
+install_folder_paths_stub()
 sys.modules.setdefault("server", MagicMock())
 
 from aiohttp import web  # noqa: E402

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_api_workspace_images.py

@@ -4,6 +4,7 @@ import asyncio
 import json
 import os
 import shutil
+import sqlite3
 import subprocess  # nosec B404
 import sys
 import unittest
@@ -1232,15 +1233,21 @@ class TestWorkspaceImages(ImageAPITestCase):
             {"q": "zebra", "category": "Night"},
             {"sort": "rating"},
         ):
+            leak = 'near "gi": syntax error FROM generation_images'
             with (
                 self.subTest(failing=params),
                 patch.object(
-                    db, "get_image_link_matches", side_effect=RuntimeError("gone")
+                    db, "get_image_link_matches", side_effect=RuntimeError(leak)
                 ),
+                self.assertLogs("prompt_manager", level="ERROR") as logged,
             ):
                 response, data = await self.get(**params)
                 self.assertEqual(response.status, 500, data)
                 self.assertNotIn("images", data)
+                self.assertEqual(data["code"], "listing-failed")
+                self.assertNotIn(leak, json.dumps(data))
+                self.assertNotIn("syntax error", json.dumps(data))
+                self.assertTrue(any(r.exc_info for r in logged.records))
 
     async def test_filename_search_survives_a_database_failure(self):
         for name, mtime in (("zebra-1.png", 300), ("zebra-2.png", 200)):
@@ -1361,8 +1368,10 @@ class TestWorkspaceImages(ImageAPITestCase):
             for query in statements
             if query.lstrip().upper().startswith(("SELECT", "WITH"))
         ]
-        self.assertEqual(len(selects), 3, selects)
+        # Plus the one stream of tagged image records q and tags read (B3).
+        self.assertEqual(len(selects), 4, selects)
         self.assertEqual(sum("image_favorites" in q for q in selects), 1, selects)
+        self.assertEqual(sum("media_image_tags" in q for q in selects), 1, selects)
 
     async def test_rating_sort_orders_linked_then_unlinked(self):
         self._filter_fixtures()
@@ -1626,7 +1635,15 @@ class TestWorkspaceImages(ImageAPITestCase):
                     response, data = await self.get(limit=10, **params)
                     self.assertEqual(response.status, 200, data)
                     self.assertEqual(built, [])
-                    self.assertEqual(len(selects()), 1)
+                    found = selects()
+                    # q and tags also stream the tagged image records once
+                    # (#249 B3); none are tagged here, so nothing is stat'ed.
+                    streamed = "q" in params or "tags" in params
+                    self.assertEqual(len(found), 2 if streamed else 1, found)
+                    self.assertEqual(
+                        sum("media_image_tags" in query for query in found),
+                        int(streamed),
+                    )
             self.assertIs(
                 self.api._workspace_order_cache[((0, str(self.output_dir)),)][1][
                     "newest"
@@ -1773,3 +1790,342 @@ class TestWorkspaceCursorEncoding(unittest.TestCase):
                 token = _workspace_cursor(key, "scope")
                 self.assertLessEqual(len(token), 4096)
                 self.assertEqual(_workspace_cursor_key(token, "scope", order), key)
+
+
+class TestWorkspaceImageTags(ImageAPITestCase):
+    """B3: image tags in the Tags filter and search (spec amendment S1)."""
+
+    media = TestWorkspaceImages.media
+    get = TestWorkspaceImages.get
+
+    async def tearDownAsync(self):
+        self.api.db.close_all()
+        assert_closed(self, self._temp_db.name, self._output_tmp.name)
+        await super().tearDownAsync()
+
+    def tag(self, path, tags):
+        """Save *tags* for the current bytes of *path*, as the Tag dialog does."""
+        import hashlib
+
+        stat = path.stat()
+        return self.api.db.replace_image_tags(
+            locator=os.path.normcase(os.path.realpath(path)),
+            sha256=hashlib.sha256(path.read_bytes()).hexdigest(),
+            size=stat.st_size,
+            mtime_ns=stat.st_mtime_ns,
+            expected_epoch=self.api.db.get_execution_epoch(),
+            expected_tag_revision=0,
+            tags=tags,
+        )
+
+    def names(self, data):
+        return [item["path"] for item in data["images"]]
+
+    async def test_tags_filter_admits_unlinked_image_with_current_image_tags(self):
+        tagged = self.media("unlinked_tagged.png", mtime=103)
+        self.media("plain.png", mtime=102)
+        linked = self.media("linked.png", mtime=101)
+        self.api.db.link_image_to_prompt(
+            self._save_prompt("Linked", tags=["other"]), str(linked)
+        )
+        self.tag(tagged, ["dunes", "warm_light"])
+        for tags in ("dunes", "dunes,warm_light", "warm_light"):
+            with self.subTest(tags=tags):
+                response, body = await self.get(tags=tags)
+                self.assertEqual(response.status, 200, body)
+                self.assertEqual(
+                    [i["path"] for i in body["images"]], ["unlinked_tagged.png"]
+                )
+                self.assertEqual(body["total"], 1)
+                self.assertEqual(body["positive_count"], 0)
+        # Exact names, as for prompt tags; a missing tag excludes the file.
+        for tags in ("Dunes", "dunes,missing", "dune"):
+            with self.subTest(tags=tags):
+                _, body = await self.get(tags=tags)
+                self.assertEqual(self.names(body), [])
+        # A category filter reads only the linked positive.
+        _, body = await self.get(tags="dunes", category="Night")
+        self.assertEqual(self.names(body), [])
+
+    async def test_tags_filter_combines_image_and_positive_tags(self):
+        both = self._save_prompt("Both", category="Night", tags=["a", "b"], rating=2)
+        only_a = self._save_prompt("Only a", category="Night", tags=["a"], rating=5)
+        day_a = self._save_prompt("Day a", category="Day", tags=["a"], rating=4)
+        files = {
+            name: self.media(f"{name}.png", mtime=100 + index)
+            for index, name in enumerate(
+                ("positive_ab", "positive_a_image_b", "image_ab", "image_a", "day")
+            )
+        }
+        self.api.db.link_image_to_prompt(both, str(files["positive_ab"]))
+        self.api.db.link_image_to_prompt(only_a, str(files["positive_a_image_b"]))
+        self.api.db.link_image_to_prompt(day_a, str(files["day"]))
+        self.tag(files["positive_a_image_b"], ["b"])
+        self.tag(files["image_ab"], ["a", "b"])
+        self.tag(files["image_a"], ["a"])
+        self.tag(files["day"], ["b"])
+        _, body = await self.get(tags="a,b", sort="name")
+        self.assertEqual(
+            self.names(body),
+            ["day.png", "image_ab.png", "positive_a_image_b.png", "positive_ab.png"],
+        )
+        self.assertEqual(body["total"], 4)
+        self.assertEqual(body["positive_count"], 3)
+        _, body = await self.get(tags="a,b", category="Night", sort="name")
+        self.assertEqual(
+            self.names(body), ["positive_a_image_b.png", "positive_ab.png"]
+        )
+        # The rating sort ranks an image-admitted linked file by its positive.
+        _, body = await self.get(tags="a,b", sort="rating")
+        self.assertEqual(
+            self.names(body),
+            ["positive_a_image_b.png", "day.png", "positive_ab.png", "image_ab.png"],
+        )
+        # With q, a linked positive hit admits as before.
+        _, body = await self.get(tags="b", q="only", sort="name")
+        self.assertEqual(self.names(body), ["positive_a_image_b.png"])
+
+    async def test_q_matches_image_tag_names(self):
+        tagged = self.media("unlinked_tagged.png", mtime=102)
+        self.media("plain.png", mtime=101)
+        self.tag(tagged, ["Sand Dunes", "warm_light"])
+        for query in ("dune", "DUNES", "sand d", "warm_"):
+            with self.subTest(q=query):
+                response, body = await self.get(q=query)
+                self.assertEqual(response.status, 200, body)
+                self.assertEqual(self.names(body), ["unlinked_tagged.png"])
+        _, body = await self.get(q="plain")
+        self.assertEqual(self.names(body), ["plain.png"])
+        _, body = await self.get(q="nothing")
+        self.assertEqual(self.names(body), [])
+
+    async def test_filter_ignores_tags_of_a_changed_fingerprint(self):
+        moved = self.media("touched.png", mtime=102)
+        grown = self.media("grown.png", mtime=101)
+        kept = self.media("kept.png", mtime=100)
+        for path in (moved, grown, kept):
+            self.tag(path, ["dunes"])
+        _, body = await self.get(tags="dunes")
+        self.assertEqual(self.names(body), ["touched.png", "grown.png", "kept.png"])
+        os.utime(moved, (500, 500))
+        with grown.open("ab") as handle:
+            handle.write(b"\0")
+        os.utime(grown, (101, 101))
+        self.api.invalidate_gallery_cache()
+        _, body = await self.get(tags="dunes")
+        self.assertEqual(self.names(body), ["kept.png"])
+        _, body = await self.get(q="dunes")
+        self.assertEqual(self.names(body), ["kept.png"])
+
+    async def test_stat_calls_equal_tagged_candidates_not_listing_size(self):
+        from py.api import images as images_module
+
+        listed = [
+            (self.output_dir / f"day-{i % 50:02}" / f"img_{i:05}.png", 1_000.0 + i)
+            for i in range(1_997)
+        ]
+        tagged = [self.media(f"tagged_{i}.png", mtime=5_000 + i) for i in range(3)]
+        listed += [(path, path.stat().st_mtime) for path in tagged]
+        # Tagged but outside the listing, and listed with a non-matching tag.
+        outside = self.media("elsewhere.png", root=self.comfy_dir)
+        unrelated = self.media("unrelated.png", mtime=4_000)
+        listed.append((unrelated, unrelated.stat().st_mtime))
+        for path in tagged:
+            self.tag(path, ["dunes"])
+        self.tag(outside, ["dunes"])
+        self.tag(unrelated, ["other"])
+        self.assertEqual(len(listed), 2_001)
+        stat_calls = 0
+        real = getattr(images_module, "_current_fingerprint", None)
+        self.assertIsNotNone(real, "the candidate stat helper is not implemented")
+
+        def counting(path):
+            nonlocal stat_calls
+            stat_calls += 1
+            return real(path)
+
+        with (
+            patch.object(
+                self.api, "_get_gallery_files", AsyncMock(return_value=listed)
+            ),
+            patch.object(
+                self.api, "_format_workspace_page", TestWorkspaceImages._stub_page
+            ),
+            patch.object(images_module, "_current_fingerprint", counting),
+        ):
+            response, body = await self.get(tags="dunes", limit=10)
+        self.assertEqual(response.status, 200, body)
+        self.assertEqual(
+            sorted(i["filename"] for i in body["images"]),
+            ["tagged_0.png", "tagged_1.png", "tagged_2.png"],
+        )
+        self.assertEqual(stat_calls, 3)
+
+    async def test_plain_listing_reads_no_image_tags(self):
+        prompt = self._save_prompt("Linked", category="Night", tags=["a"])
+        for index in range(4):
+            path = self.media(f"{index}.png", mtime=100 + index)
+            self.tag(path, ["dunes"])
+            self.api.db.link_image_to_prompt(prompt, str(path))
+        statements = []
+        original = self.api.db.model.get_connection
+
+        def trace_connection():
+            connection = original()
+            connection.set_trace_callback(statements.append)
+            return connection
+
+        with patch.object(
+            self.api.db.model, "get_connection", side_effect=trace_connection
+        ):
+            _, first = await self.get(limit=2)
+            _, rest = await self.get(limit=2, cursor=first["next_cursor"])
+            for params in (
+                {"sort": "rating"},
+                {"category": "Night"},
+                {"media": "image"},
+            ):
+                response, _ = await self.get(**params)
+                self.assertEqual(response.status, 200)
+        self.assertEqual(len(first["images"] + rest["images"]), 4)
+        self.assertFalse(
+            [q for q in statements if "media_" in q or "annotation" in q], statements
+        )
+
+    async def test_image_tag_read_failure_fails_tags_and_degrades_search(self):
+        tagged = self.media("unlinked_tagged.png", mtime=102)
+        self.media("dunes_by_name.png", mtime=101)
+        self.tag(tagged, ["dunes"])
+        leak = "no such table: media_annotation_files"
+        with patch.object(
+            self.api.db,
+            "iter_image_tag_records",
+            side_effect=sqlite3.OperationalError(leak),
+        ):
+            # As a failed link read does under a Tags filter: a fixed coded
+            # sentence, never the exception or SQL text; the traceback is logged.
+            with self.assertLogs("prompt_manager", level="ERROR") as failed:
+                response, body = await self.get(tags="dunes")
+            self.assertEqual((response.status, body["success"]), (500, False))
+            self.assertEqual(body["code"], "listing-failed")
+            self.assertNotIn(leak, body["error"])
+            self.assertNotIn("media_annotation_files", json.dumps(body))
+            self.assertTrue(any(r.exc_info for r in failed.records))
+            with self.assertLogs("prompt_manager", level="WARNING") as logged:
+                response, body = await self.get(q="dunes")
+        self.assertEqual(response.status, 200, body)
+        self.assertEqual(self.names(body), ["dunes_by_name.png"])
+        self.assertIn("image tags", "\n".join(logged.output))
+
+    async def test_legacy_output_failure_logs_its_traceback(self):
+        self.media("legacy.png", mtime=100)
+        with (
+            patch.object(
+                self.api, "_collect_output_images", side_effect=RuntimeError("x")
+            ),
+            self.assertLogs("prompt_manager", level="ERROR") as logged,
+        ):
+            response = await self.client.get("/prompt_manager/images/output")
+        self.assertEqual(response.status, 500)
+        self.assertTrue(any(r.exc_info for r in logged.records), logged.output)
+
+    async def test_legacy_gallery_and_search_shapes_unchanged(self):
+        path = self.media("legacy.png", mtime=100)
+        self.media("other.png", mtime=99)
+        self._link_image(path, "dunes at dusk")
+
+        async def legacy():
+            bodies = []
+            for url, params in (
+                ("/prompt_manager/images/output", {}),
+                ("/prompt_manager/images/search", {"q": "dunes"}),
+                ("/prompt_manager/images/all", {}),
+            ):
+                response = await self.client.get(url, params=params)
+                self.assertEqual(response.status, 200, url)
+                bodies.append(await response.json())
+            return bodies
+
+        before = await legacy()
+        self.tag(path, ["dunes", "warm_light"])
+        self.tag(self.output_dir / "other.png", ["dunes"])
+        self.api.invalidate_gallery_cache()
+        self.assertEqual(await legacy(), before)
+
+    def test_link_facts_resolve_pairs_skip_ambiguous_and_chunk(self):
+        from database.models import normalize_image_path
+
+        db = self.api.db
+        plain = self._save_prompt("Plain dunes", category="Day", tags=["a", "b"])
+        positive = self._save_prompt("Pair positive", category="Night", tags=["p"])
+        pair = db.save_prompt_pair("Pair positive", "Noise", title="Pair")
+        owners = (self._save_prompt("Owner one"), self._save_prompt("Owner two"))
+        paths = {
+            name: str(self.output_dir / f"{name}.png")
+            for name in ("plain", "paired", "ambiguous")
+        }
+        db.link_image_to_prompt(plain, paths["plain"])
+        image = db.link_image_to_prompt(positive, paths["paired"])
+        db.link_image_to_pair(pair, image, {"source": "fixture"})
+        for owner in owners:
+            db.link_image_to_prompt(owner, paths["ambiguous"])
+        keys = {name: normalize_image_path(path) for name, path in paths.items()}
+        padding = [f"/nowhere/{index}.png" for index in range(600)]
+        facts = db.get_image_link_facts([*padding, *keys.values(), keys["plain"]])
+        self.assertEqual(
+            facts,
+            {
+                keys["plain"]: (True, None, plain, "Day", ("a", "b")),
+                keys["paired"]: (True, None, positive, "Night", ("p",)),
+            },
+        )
+        searched = db.get_image_link_facts(list(keys.values()), "dunes")
+        self.assertEqual(
+            {path: row[0] for path, row in searched.items()},
+            {keys["plain"]: True, keys["paired"]: False},
+        )
+        self.assertEqual(db.get_image_link_facts([]), {})
+
+    def test_new_link_fact_reads_use_indexes(self):
+        from database.operations import (
+            _LINK_FACTS_SQL,
+            _LINK_FILTER_HIT,
+            _POSITIVE_TAG_NAMES_SQL,
+        )
+
+        with self.api.db.model.get_connection() as conn:
+            conn.executemany(
+                "INSERT INTO prompts(id,text,hash) VALUES(?,?,?)",
+                [(i, f"prompt {i}", f"hash-{i}") for i in range(1, 3_001)],
+            )
+            conn.executemany(
+                "INSERT INTO generated_images(prompt_id,image_path,filename,"
+                "file_path) VALUES(?,?,?,?)",
+                [
+                    (i, f"/x/{i}.png", f"{i}.png", f"/x/{i}.png")
+                    for i in range(1, 3_001)
+                ],
+            )
+            for hit, params in (
+                ("1", {}),
+                (_LINK_FILTER_HIT, {"pattern": "%prompt 1%"}),
+            ):
+                sql = _LINK_FACTS_SQL.format(hit=hit, marks=":path0,:path1")
+                bound = {**params, "path0": "/x/1.png", "path1": "/x/2.png"}
+                plan = [
+                    row[3] for row in conn.execute("EXPLAIN QUERY PLAN " + sql, bound)
+                ]
+                self.assertIn(
+                    "SEARCH gi USING INDEX idx_image_file_path (file_path=?)", plan
+                )
+                self.assertFalse(
+                    [s for s in plan if s.startswith(("SCAN gi", "SCAN other"))], plan
+                )
+            plan = [
+                row[3]
+                for row in conn.execute(
+                    "EXPLAIN QUERY PLAN " + _POSITIVE_TAG_NAMES_SQL.format(marks="?,?"),
+                    (1, 2),
+                )
+            ]
+        self.assertFalse([step for step in plan if step.startswith("SCAN")], plan)

tests/test_autotag_engine.py

@@ -301,6 +301,159 @@ class TestGgufNormalisation(EngineTestCase):
         )
 
 
+SCORED_TAGS = [
+    {"name": "desert", "category": "0"},
+    {"name": "sandstone", "category": "0"},
+    {"name": "Sandstone", "category": "0"},
+    {"name": "hatsune_miku", "category": "4"},
+    {"name": "rating:safe", "category": "9"},
+] + [{"name": f"tag_{i:03d}", "category": "0"} for i in range(120)]
+SCORED_PROBABILITIES = [0.96, 0.98, 0.5, 0.9, 0.99] + [
+    0.9 - i * 0.004 for i in range(120)
+]
+
+
+class TestTagSuggestions(EngineTestCase):
+    """``generate_tag_suggestions``: scored, ordered, bounded, distinct."""
+
+    def _wd14(self, tags=SCORED_TAGS, probabilities=SCORED_PROBABILITIES):
+        _touch_model_files(self.models_dir, "wd14-vit")
+        self.session = FakeOnnxSession(probabilities)
+        service = self._service(("wd14", (self.session, tags)))
+        service.load_model("wd14-vit")
+        return service
+
+    def _gguf(self, text):
+        _touch_model_files(self.models_dir, "gguf")
+        self.model = FakeGgufModel(text)
+        service = self._service(("gguf", self.model))
+        service.load_model("gguf")
+        return service
+
+    def test_wd14_suggestions_carry_real_probabilities_sorted(self):
+        service = self._wd14()
+
+        suggestions = service.generate_tag_suggestions(
+            str(self.image_path),
+            limit=10,
+            general_threshold=0.35,
+            character_threshold=0.85,
+        )
+
+        self.assertEqual(suggestions[:2], [("sandstone", 0.98), ("desert", 0.96)])
+        # The character tag passes its own threshold; rating tags never show.
+        self.assertIn(("hatsune_miku", 0.9), suggestions)
+        self.assertNotIn("rating:safe", [name for name, _ in suggestions])
+        scores = [score for _, score in suggestions]
+        self.assertEqual(scores, sorted(scores, reverse=True))
+        self.assertTrue(all(isinstance(score, float) for score in scores))
+        # "Sandstone" (0.5) repeats "sandstone" case-insensitively: dropped.
+        self.assertEqual(
+            [name.casefold() for name, _ in suggestions].count("sandstone"), 1
+        )
+
+    def test_suggestions_keep_the_requested_limit(self):
+        service = self._wd14()
+        for limit in (1, 10, 100):
+            with self.subTest(limit=limit):
+                suggestions = service.generate_tag_suggestions(
+                    str(self.image_path),
+                    limit=limit,
+                    general_threshold=0.0,
+                    character_threshold=0.0,
+                )
+                self.assertEqual(len(suggestions), limit)
+        for bad in (0, -1, 101, 2.5, "10", True, None):
+            with self.subTest(bad=bad), self.assertRaises(ValueError):
+                service.generate_tag_suggestions(str(self.image_path), limit=bad)
+
+    def test_thresholds_default_to_the_service_values(self):
+        service = self._wd14()
+        service.wd14_general_threshold = 0.95
+        service.wd14_character_threshold = 0.95
+
+        suggestions = service.generate_tag_suggestions(str(self.image_path), limit=10)
+
+        self.assertEqual(suggestions, [("sandstone", 0.98), ("desert", 0.96)])
+
+    def test_llm_suggestions_have_null_confidence_in_output_order(self):
+        service = self._gguf("Zebra, apple, ZEBRA, mango tree, kiwi, plum")
+
+        suggestions = service.generate_tag_suggestions(
+            str(self.image_path), limit=3, prompt="tags please"
+        )
+
+        self.assertEqual(
+            suggestions, [("zebra", None), ("apple", None), ("mango_tree", None)]
+        )
+
+    def test_suggestions_skip_names_save_would_reject_before_the_limit(self):
+        from database.annotations import normalize_image_tags
+
+        too_long = "x" * 60
+        service = self._gguf(f"{too_long}, sky\ncloud, zebra, apple, mango, kiwi, plum")
+
+        suggestions = service.generate_tag_suggestions(
+            str(self.image_path), limit=3, prompt="tags please"
+        )
+
+        # The 60-character part and the part holding a newline are dropped
+        # before the count, so three valid chips still come back.
+        names = [name for name, _ in suggestions]
+        self.assertEqual(names, ["zebra", "apple", "mango"])
+        self.assertEqual(normalize_image_tags(names), names)
+
+    def test_generate_tags_return_shape_unchanged(self):
+        service = self._wd14()
+        self.assertEqual(
+            service.generate_tags(
+                str(self.image_path), general_threshold=0.95, character_threshold=0.95
+            ),
+            ["sandstone", "desert"],
+        )
+        gguf = self._gguf("Smile, smile, long hair")
+        self.assertEqual(
+            gguf.generate_tags(str(self.image_path)), ["smile", "long_hair"]
+        )
+
+    def test_explicit_prompt_does_not_mutate_custom_prompt(self):
+        service = self._gguf("tag")
+        service.custom_prompt = "saved legacy prompt"
+
+        service.generate_tag_suggestions(
+            str(self.image_path), limit=10, prompt="dialog instructions"
+        )
+
+        self.assertEqual(
+            self.model.calls[0]["messages"][1]["content"][0]["text"],
+            "dialog instructions",
+        )
+        self.assertEqual(service.custom_prompt, "saved legacy prompt")
+
+    def test_suggestions_need_a_loaded_model(self):
+        service = self._service(("gguf", FakeGgufModel("x")))
+        with self.assertRaises(RuntimeError):
+            service.generate_tag_suggestions(str(self.image_path), limit=10)
+
+    def test_image_file_is_closed_after_inference(self):
+        service = self._gguf("tag")
+        opened = []
+        real_open = autotag.Image.open
+
+        def tracking_open(*args, **kwargs):
+            image = real_open(*args, **kwargs)
+            opened.append(image)
+            return image
+
+        with patch.object(autotag.Image, "open", tracking_open):
+            service.generate_tag_suggestions(str(self.image_path), limit=10)
+            service.generate_tags(str(self.image_path))
+
+        self.assertEqual(len(opened), 2)
+        for image in opened:
+            self.assertIsNone(getattr(image, "fp", None))
+
+
 class TestGenerateTagsErrors(EngineTestCase):
 
     def test_no_model_loaded(self):

tests/test_config.py

@@ -19,6 +19,7 @@ sys.modules.setdefault("server", _mock_server)
 
 sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 
+from py import config as config_module
 from py.config import GalleryConfig, IntegrationConfig, PromptManagerConfig
 
 
@@ -404,5 +405,85 @@ class TestConfigPathOverride(unittest.TestCase):
             self.assertEqual(PromptManagerConfig.RESULT_TIMEOUT, 77)
 
 
+class TestAutotagConfig(unittest.TestCase):
+    """``autotag.defaults.suggestion_limit``: integer 1..100, default 10 (D68)."""
+
+    def setUp(self):
+        self.config_class = getattr(config_module, "AutotagConfig", None)
+        self.assertIsNotNone(self.config_class, "AutotagConfig is not implemented")
+        self._orig = PromptManagerConfig.get_config()
+
+    def tearDown(self):
+        self.config_class.SUGGESTION_LIMIT = 10
+        PromptManagerConfig.update_config(self._orig)
+
+    def _load(self, value):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            path = os.path.join(tmpdir, "config.json")
+            with open(path, "w") as f:
+                # json writes NaN for float("nan"), which json.load reads back.
+                json.dump({"autotag": {"defaults": {"suggestion_limit": value}}}, f)
+            with self.assertLogs("prompt_manager.config", level="WARNING") as logs:
+                PromptManagerConfig.load_from_file(path)
+        return logs
+
+    def test_every_copy_of_the_tag_set_cap_is_one_value(self):
+        # A suggestion request is bounded by the image tag set cap; the
+        # copies that cannot import it (config loads before the database,
+        # the inspection envelope stays storage-free) are pinned to it here.
+        from database.annotations import MAX_IMAGE_TAGS
+        from py import autotag
+        from utils import inspection_response
+
+        self.assertEqual(autotag.MAX_SUGGESTION_LIMIT, MAX_IMAGE_TAGS)
+        self.assertEqual(config_module.MAX_SUGGESTION_LIMIT, MAX_IMAGE_TAGS)
+        self.assertEqual(inspection_response.MAX_IMAGE_TAGS, MAX_IMAGE_TAGS)
+
+    def test_default_is_ten_and_persisted_under_autotag_defaults(self):
+        self.assertEqual(config_module.DEFAULT_SUGGESTION_LIMIT, 10)
+        self.assertEqual(config_module.MAX_SUGGESTION_LIMIT, 100)
+        self.assertEqual(self.config_class.suggestion_limit(), 10)
+        self.assertEqual(
+            PromptManagerConfig.get_config()["autotag"],
+            {"defaults": {"suggestion_limit": 10}},
+        )
+        with tempfile.TemporaryDirectory() as tmpdir:
+            path = os.path.join(tmpdir, "config.json")
+            PromptManagerConfig.update_config(
+                {"autotag": {"defaults": {"suggestion_limit": 25}}}
+            )
+            PromptManagerConfig.save_to_file(path)
+            self.config_class.SUGGESTION_LIMIT = 10
+            PromptManagerConfig.load_from_file(path)
+        self.assertEqual(self.config_class.suggestion_limit(), 25)
+
+    def test_valid_limits_are_kept(self):
+        for value in (1, 10, 100):
+            with self.subTest(value=value):
+                PromptManagerConfig.update_config(
+                    {"autotag": {"defaults": {"suggestion_limit": value}}}
+                )
+                self.assertEqual(self.config_class.suggestion_limit(), value)
+
+    def test_suggestion_limit_setting_validated_on_load(self):
+        for value in (0, 101, "10", float("nan"), 2.5, True, None, [10]):
+            with self.subTest(value=value):
+                self.config_class.SUGGESTION_LIMIT = 42
+                logs = self._load(value)
+                self.assertEqual(self.config_class.suggestion_limit(), 10)
+                self.assertIn("suggestion_limit", "\n".join(logs.output))
+
+    def test_missing_or_malformed_sections_keep_the_current_value(self):
+        self.config_class.SUGGESTION_LIMIT = 7
+        for config in ({}, {"autotag": {}}, {"autotag": {"defaults": {}}}):
+            PromptManagerConfig.update_config(config)
+            self.assertEqual(self.config_class.suggestion_limit(), 7)
+        with self.assertLogs("prompt_manager.config", level="WARNING"):
+            PromptManagerConfig.update_config({"autotag": "nope"})
+        with self.assertLogs("prompt_manager.config", level="WARNING"):
+            PromptManagerConfig.update_config({"autotag": {"defaults": [1]}})
+        self.assertEqual(self.config_class.suggestion_limit(), 7)
+
+
 if __name__ == "__main__":
     unittest.main()

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,153 @@ def _png_with_chunks(path, chunks):
     return path
 
 
+class TestImageTagsFacet(unittest.TestCase):
+    """B3: the rooted envelope's ``image_tags`` facet is validated."""
+
+    def encoded(self, facet):
+        import inspect as signature_of
+
+        parameters = signature_of.signature(encode_inspection_response).parameters
+        if "image_tags" not in parameters:
+            self.fail("the image_tags facet is not implemented")
+        body = encode_inspection_response(
+            image=IMAGE,
+            root_scope="a" * 64,
+            file={
+                "observation": "current-file",
+                "source_label": "output",
+                "media_type": "image",
+                "extension": ".png",
+                "size": 100,
+                "modified_time": 100,
+            },
+            prompts=PROMPTS,
+            resolution={"state": "resolved", "sampler_id": "3", "reason": ""},
+            inspection=inspection({"prompt": graph_text()}),
+            library={"status": "none"},
+            image_tags=facet,
+        )
+        return json.loads(body)
+
+    def test_valid_facets_pass_through(self):
+        for facet in (
+            {"state": "current", "tags": ["dunes", "warm_light"]},
+            {"state": "current", "tags": []},
+            {"state": "none", "tags": []},
+            {"state": "unavailable", "tags": []},
+            {"state": "current", "tags": [f"tag {i}" for i in range(100)]},
+        ):
+            with self.subTest(facet=facet):
+                self.assertEqual(self.encoded(facet)["image_tags"], facet)
+
+    def test_envelope_rejects_malformed_image_tags(self):
+        unavailable = {"state": "unavailable", "tags": []}
+        for facet in (
+            "current",
+            ["dunes"],
+            {"state": "current"},
+            {"state": "stale", "tags": []},
+            {"state": "current", "tags": "dunes"},
+            {"state": "current", "tags": ["dunes", 3]},
+            {"state": "current", "tags": [""]},
+            {"state": "current", "tags": [" dunes"]},
+            {"state": "current", "tags": ["a,b"]},
+            {"state": "current", "tags": ["x" * 51]},
+            {"state": "current", "tags": [f"tag {i}" for i in range(101)]},
+            {"state": "none", "tags": ["dunes"]},
+            {"state": "unavailable", "tags": ["dunes"]},
+            {"state": "current", "tags": [], "locator": "/abs/path.png"},
+        ):
+            with self.subTest(facet=facet):
+                self.assertEqual(self.encoded(facet)["image_tags"], unavailable)
+
+    def test_facet_is_absent_unless_given(self):
+        self.assertNotIn("image_tags", json.loads(encode(inspection({}))))
+        self.assertNotIn("image_tags", self.encoded(None))
+
+
+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_model_gate.py

@@ -0,0 +1,217 @@
+"""The shared, non-blocking model gate (#249 B2).
+
+One owner at a time may load, swap, run, download or unload a tagging model.
+A release requested while gated work still runs in a worker thread takes
+effect only when that work really exits, so a client disconnect never lets a
+second owner swap the model under a running inference.
+"""
+
+import asyncio
+import os
+import sys
+import threading
+import unittest
+import unittest.mock
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+try:  # guarded so a missing module fails assertions, not test loading
+    from py import model_gate
+except ImportError:
+    model_gate = None
+
+WAIT = 30.0  # ceiling for cross-thread handoffs, never a short clock
+
+
+class GateTestCase(unittest.TestCase):
+    def setUp(self):
+        self.assertIsNotNone(model_gate, "py.model_gate is not implemented")
+        self.gate = model_gate.ModelGate()
+
+
+class TestGate(GateTestCase):
+    def test_gate_is_nonblocking_and_single_owner(self):
+        self.assertIsNone(self.gate.holder())
+        self.assertTrue(self.gate.try_acquire("legacy-batch"))
+        self.assertEqual(self.gate.holder(), "legacy-batch")
+
+        # A second owner is refused at once, never queued.
+        self.assertFalse(self.gate.try_acquire("image-annotations"))
+        self.assertFalse(self.gate.try_acquire("legacy-batch"))
+        self.assertEqual(self.gate.holder(), "legacy-batch")
+
+        # Only the holder can release.
+        self.gate.release("image-annotations")
+        self.assertEqual(self.gate.holder(), "legacy-batch")
+        self.gate.release("legacy-batch")
+        self.assertIsNone(self.gate.holder())
+        self.gate.release("legacy-batch")  # idempotent
+
+        self.assertTrue(self.gate.try_acquire("image-annotations"))
+        self.assertEqual(self.gate.holder(), "image-annotations")
+
+    def test_release_waits_for_running_work(self):
+        self.assertTrue(self.gate.try_acquire("owner"))
+        self.gate.begin("owner")
+        self.gate.release("owner")
+        self.assertEqual(self.gate.holder(), "owner")
+        self.assertFalse(self.gate.try_acquire("other"))
+        # No new work is admitted once the owner let go.
+        with self.assertRaises(model_gate.GateNotHeld):
+            self.gate.begin("owner")
+        self.gate.end("owner")
+        self.assertIsNone(self.gate.holder())
+
+    def test_begin_requires_the_holder(self):
+        with self.assertRaises(model_gate.GateNotHeld):
+            self.gate.begin("nobody")
+        self.assertTrue(self.gate.try_acquire("owner"))
+        with self.assertRaises(model_gate.GateNotHeld):
+            self.gate.begin("other")
+        self.gate.end("other")  # a stray end never disturbs the holder
+        self.assertEqual(self.gate.holder(), "owner")
+
+    def test_module_gate_is_one_process_wide_instance(self):
+        self.assertIsNone(model_gate.holder())
+        self.assertTrue(model_gate.try_acquire("a"))
+        try:
+            self.assertFalse(model_gate.try_acquire("b"))
+            self.assertEqual(model_gate.holder(), "a")
+        finally:
+            model_gate.release("a")
+        self.assertIsNone(model_gate.holder())
+
+    def test_new_owner_names_are_unique(self):
+        first = model_gate.new_owner("legacy-single")
+        second = model_gate.new_owner("legacy-single")
+        self.assertNotEqual(first, second)
+        self.assertTrue(first.startswith("legacy-single:"))
+
+
+class TestGatedExecutor(GateTestCase):
+    def test_cancelled_waiter_keeps_the_gate_until_the_thread_exits(self):
+        started = threading.Event()
+        proceed = threading.Event()
+        finished = threading.Event()
+
+        def blocking_work():
+            started.set()
+            proceed.wait(WAIT)
+            finished.set()
+            return "done"
+
+        async def scenario():
+            self.assertTrue(self.gate.try_acquire("native"))
+            task = asyncio.ensure_future(self.gate.run("native", blocking_work))
+            try:
+                await asyncio.get_running_loop().run_in_executor(
+                    None, started.wait, WAIT
+                )
+                task.cancel()
+                with self.assertRaises(asyncio.CancelledError):
+                    await task
+            finally:
+                self.gate.release("native")
+            # The waiter is gone but the inference still runs: still held.
+            self.assertEqual(self.gate.holder(), "native")
+            self.assertFalse(self.gate.try_acquire("legacy-unload"))
+            proceed.set()
+            await asyncio.get_running_loop().run_in_executor(None, finished.wait, WAIT)
+            for _ in range(1000):
+                if self.gate.holder() is None:
+                    break
+                await asyncio.sleep(0.01)
+            self.assertIsNone(self.gate.holder())
+
+        asyncio.run(scenario())
+
+    def test_run_returns_the_result_and_propagates_errors(self):
+        async def scenario():
+            self.assertTrue(self.gate.try_acquire("owner"))
+            try:
+                self.assertEqual(await self.gate.run("owner", lambda x: x * 2, 21), 42)
+
+                def boom():
+                    raise ValueError("bad")
+
+                with self.assertRaises(ValueError):
+                    await self.gate.run("owner", boom)
+                self.assertEqual(self.gate.holder(), "owner")
+            finally:
+                self.gate.release("owner")
+            self.assertIsNone(self.gate.holder())
+            with self.assertRaises(model_gate.GateNotHeld):
+                await self.gate.run("owner", lambda: None)
+
+        asyncio.run(scenario())
+
+    def test_work_that_never_starts_gives_its_admission_back(self):
+        async def scenario():
+            loop = asyncio.get_running_loop()
+            self.assertTrue(self.gate.try_acquire("owner"))
+
+            def refused(executor, func):
+                raise RuntimeError("executor shut down")
+
+            with unittest.mock.patch.object(loop, "run_in_executor", refused):
+                with self.assertRaises(RuntimeError):
+                    await self.gate.run("owner", lambda: None)
+
+            def cancelled(executor, func):
+                future = loop.create_future()
+                future.cancel()  # a loop shutdown drops the queued call
+                return future
+
+            with unittest.mock.patch.object(loop, "run_in_executor", cancelled):
+                with self.assertRaises(asyncio.CancelledError):
+                    await self.gate.run("owner", lambda: None)
+            await asyncio.sleep(0)  # let the done callback run
+            self.gate.release("owner")
+            self.assertIsNone(self.gate.holder())
+
+        asyncio.run(scenario())
+
+    def test_skipped_work_runs_its_cleanup_exactly_once(self):
+        async def scenario():
+            loop = asyncio.get_running_loop()
+            skipped = []
+
+            def cleanup():
+                skipped.append(True)
+
+            self.assertTrue(self.gate.try_acquire("owner"))
+            self.assertEqual(
+                await self.gate.run("owner", lambda: 7, on_skipped=cleanup), 7
+            )
+            self.assertEqual(skipped, [])
+
+            def refused(executor, func):
+                raise RuntimeError("executor shut down")
+
+            with unittest.mock.patch.object(loop, "run_in_executor", refused):
+                with self.assertRaises(RuntimeError):
+                    await self.gate.run("owner", lambda: None, on_skipped=cleanup)
+            self.assertEqual(skipped, [True])
+
+            def cancelled(executor, func):
+                future = loop.create_future()
+                future.cancel()
+                return future
+
+            with unittest.mock.patch.object(loop, "run_in_executor", cancelled):
+                with self.assertRaises(asyncio.CancelledError):
+                    await self.gate.run("owner", lambda: None, on_skipped=cleanup)
+            await asyncio.sleep(0)  # let the done callback run
+            self.assertEqual(skipped, [True, True])
+
+            self.gate.release("owner")
+            with self.assertRaises(model_gate.GateNotHeld):
+                await self.gate.run("owner", lambda: None, on_skipped=cleanup)
+            self.assertEqual(skipped, [True, True, True])
+            self.assertIsNone(self.gate.holder())
+
+        asyncio.run(scenario())
+
+
+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/inspection_response.py

@@ -6,12 +6,17 @@ from decimal import Decimal, InvalidOperation
 from typing import TYPE_CHECKING, Any, Literal, Optional
 
 from .inspection_outcomes import MESSAGE_LENGTH, project_resolution
+from .validators import validate_tags
 
 if TYPE_CHECKING:
     from .prompt_inspector import InspectionRead
 
 MAX_RESPONSE_BYTES = 8 * 1024 * 1024
 MAX_LIBRARY_BYTES = 32 * 1024
+# The image tag set cap (database/annotations.py MAX_IMAGE_TAGS; pinned equal
+# by tests/test_config.py).
+MAX_IMAGE_TAGS = 100
+_IMAGE_TAG_STATES = frozenset({"current", "none", "unavailable"})
 _MAX_SAFE_INTEGER = 2**53 - 1
 _RECORD_KEYS = frozenset(
     {"prompt", "workflow", "parameters", "comfyassets_prompt_pairs"}
@@ -363,6 +368,35 @@ def _library_projection(library: dict) -> dict:
     return result
 
 
+def _image_tag_name(value: object) -> bool:
+    if not isinstance(value, str) or value != value.strip() or "," in value:
+        return False
+    try:
+        return validate_tags([value])
+    except ValueError:
+        return False
+
+
+def project_image_tags(facet: object) -> dict:
+    """The ``image_tags`` facet as the client accepts it, else unavailable.
+
+    ``current`` carries the byte record's names (at most 100 valid vocabulary
+    names); ``none`` and ``unavailable`` carry no names. Anything else, extra
+    keys included, is reported as ``unavailable`` rather than passed on.
+    """
+    unavailable = {"state": "unavailable", "tags": []}
+    if not isinstance(facet, dict) or set(facet) != {"state", "tags"}:
+        return unavailable
+    state, tags = facet["state"], facet["tags"]
+    if state not in _IMAGE_TAG_STATES or not isinstance(tags, list):
+        return unavailable
+    if state != "current" and tags:
+        return unavailable
+    if len(tags) > MAX_IMAGE_TAGS or not all(_image_tag_name(tag) for tag in tags):
+        return unavailable
+    return {"state": state, "tags": list(tags)}
+
+
 def _bounded_message(value: Any) -> Optional[str]:
     """A role line as the client accepts it: 1 to 512 UTF-16 code units."""
     if not isinstance(value, str) or not value:
@@ -394,6 +428,7 @@ def _encode_inspection(
     resolution: dict,
     inspection: "InspectionRead | None",
     library: dict,
+    image_tags: dict | None = None,
 ) -> bytes:
     """Serialize exactly once per budget step, preserving identity and roles."""
     metadata = _metadata(inspection)
@@ -407,6 +442,8 @@ def _encode_inspection(
         "metadata": metadata,
         "library": _library_projection(library),
     }
+    if image_tags is not None:
+        response["image_tags"] = project_image_tags(image_tags)
     body = _bytes(response)
     # Omission order keeps prompt evidence longest: the workflow graph first,
     # then the prompt graph, then all raw records atomically.
@@ -438,8 +475,12 @@ def encode_inspection_response(
     resolution: dict,
     inspection: "InspectionRead | None",
     library: dict,
+    image_tags: dict | None = None,
 ) -> bytes:
-    """Preserve the existing rooted wire and its bounded metadata projection."""
+    """Preserve the existing rooted wire and its bounded metadata projection.
+
+    *image_tags*, when given, adds the validated ``image_tags`` facet (B3).
+    """
     return _encode_inspection(
         identity={"root_scope": root_scope, "image": image},
         file=file,
@@ -447,6 +488,7 @@ def encode_inspection_response(
         resolution=resolution,
         inspection=inspection,
         library=library,
+        image_tags=image_tags,
     )
 
 

utils/media_capture.py

@@ -0,0 +1,685 @@
+"""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 unicodedata
+from dataclasses import dataclass
+from typing import Callable
+
+from PIL import Image
+
+try:
+    from .video_metadata import VIDEO_EXTENSIONS, is_video_path
+except ImportError:  # imported with the repo root on sys.path
+    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.
+
+        Only the image header decides whether Generate is offered: prompt
+        metadata over the inspection budgets does not make a decodable image
+        unreadable (the metadata itself is read elsewhere, under its budgets).
+        """
+        if media_type == "video":
+            return None, None, False, VIDEO_ONLY_REASON
+        try:
+            width, height = header_dimensions(path)
+        except HeaderTooLarge:
+            return None, None, False, DIMENSION_REASON
+        except HeaderUnreadable:
+            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
+
+
+class HeaderUnreadable(Exception):
+    """The file has no image header Pillow can read."""
+
+
+class HeaderTooLarge(HeaderUnreadable):
+    """The header declares a decompression bomb (no pixel is decoded)."""
+
+
+def header_dimensions(path: str) -> tuple[int, int]:
+    """``(width, height)`` from the image header alone; the file is closed.
+
+    ``Image.open`` reads only the header. Pillow's decompression-bomb error
+    (twice its warning size) is ``HeaderTooLarge``; a size between the two
+    only warns, and the caller's inference pixel cap, far below Pillow's
+    warning size, refuses it. The process-global warnings filters are never
+    touched: this runs on capture workers inside the host process, and
+    ``warnings.catch_warnings`` is not thread-safe.
+    """
+    try:
+        with Image.open(path) as image:
+            width, height = image.size
+    except Image.DecompressionBombError as exc:
+        raise HeaderTooLarge(str(exc)) from None
+    except Exception as exc:  # any decoder failure means "no usable header"
+        raise HeaderUnreadable(str(exc)) from None
+    if not width or not height:
+        raise HeaderUnreadable("The header declares no size")
+    return int(width), int(height)
+
+
+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")
+    _deny_spelling_aliases(real_root, parts)
+    return candidate, locator
+
+
+def _spelling_key(name: str) -> str:
+    return unicodedata.normalize("NFC", name).casefold()
+
+
+def _deny_spelling_aliases(real_root: str, parts: list[str]) -> None:
+    """Deny a case or Unicode spelling of an entry the directory spells otherwise.
+
+    On a case- or normalization-insensitive filesystem (macOS APFS, Windows)
+    ``A.PNG`` or an NFD name opens the listed ``a.png`` or NFC name, while
+    ``realpath`` keeps the requested spelling (macOS), so the tags would be
+    stored under a second locator. Each part must be spelled as its directory
+    lists it. A part with no entry of any spelling is left to the open that
+    follows (a missing file keeps its usual outcome).
+    """
+    directory = real_root
+    for part in parts:
+        try:
+            names = os.listdir(directory)
+        except OSError:
+            return
+        if part not in names:
+            key = _spelling_key(part)
+            if any(_spelling_key(name) == key for name in names):
+                raise CaptureDenied("The file is not a listed rooted file")
+            return
+        directory = os.path.join(directory, part)

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/library-state.mjs

@@ -23,7 +23,9 @@ export function createLibraryStream({api,onChange=()=>{},restore}) {
     let query=parameters({},40),request,disposed=false,seen=new Set();
     if(restore) {
         query=parameters(restore.filters,40);const saved=restore.state;
-        validatePage({items:saved.items,total:saved.total,variant_total:saved.variantTotal,next_cursor:saved.cursor,has_more:saved.cursor!==null},null);
+        // A shelf left before its first page answered (or after it failed) has no page yet: it restores as a fresh stream.
+        const firstPagePending=saved?.variantTotal===null && Array.isArray(saved.items) && !saved.items.length && saved.total===0 && saved.cursor===null && saved.hasMore===true;
+        if(!firstPagePending) validatePage({items:saved.items,total:saved.total,variant_total:saved.variantTotal,next_cursor:saved.cursor,has_more:saved.cursor!==null},null);
         if(new Set(saved.items.map(item=>item.id)).size!==saved.items.length) throw new TypeError('Duplicate restored parent');
         state=Object.freeze({...saved,items:Object.freeze(saved.items.map(item=>Object.freeze({...item}))),loading:false,error:null});seen=new Set(state.items.map(item=>item.id));
     }

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.`;
 }