[helgehoi]

Ticket

VI-5068 — [tamstool] Upgrade TAMS Store Browser to TAMS 8.2 — latest-source sorting, multi-source filtering and standard Flow status

Summary

Adds support for TAMS 8.2 (released 2026-08-10) while keeping 8.0 and 8.1 stores working exactly as they do today.

Since tamstool is a public tool pointed at whatever store a user configures, every 8.2 feature is gated on the api_version the store advertises at /service. Anything missing or unreadable resolves to the 8.0 baseline rather than an error, so an older store degrades cleanly instead of collecting 400s.

The three additions that remove workarounds we were carrying

sort_by / reverse_order — the store orders listings, so the newest sources arrive in the first request instead of after walking every page. Capable stores stop after a page and offer Load more; older stores keep the previous fetch-everything behaviour, since their first page has no guaranteed order. The table's own column sorting drives the query, so there is still a single sorting control. toReverseOrder handles 8.2 defining the natural order per field rather than as one direction — created is newest-first, label is A–Z.

collected_by_ids= (empty value = entities in no collection) — both listings gain an All / Top-level only / Multi-sources only scope selector. The same parameter fetches a collection's members in one request, which is what makes the label/format/editorial-purpose columns on the collections tab possible at all, and it collapses the Diagram's per-child fan-out into one batched request per collection.

Flow status — the flow_status tag is now a core Flow attribute with a defined enum, surfaced as a status column and filter. The staleness guard is kept as a secondary check, because the spec is explicit that status is client-maintained and a crashed ingest can leave it reading ingesting forever. It now degrades honestly: where no activity timestamp is available, the reported status is trusted rather than silently returning false.

Fixes a latent break

8.2 makes the collection role optional and says clients MUST NOT rely on it. src/views/Embed/index.jsx did exactly that (source_collection.find(s => s.role === "video")), so against a store that omits role the Embed view would have silently lost fps, duration and live status. Video resolution now falls back to the editorial_purpose tag (AppNote0025) and then to the NMOS video format. Collections also render in server order — 8.2 states the collection is an ordered list — and show role only where a store still sets it.

Related: the Embed view previously cached a source as closed forever, so a recording that started after page load never lit up. A status=ingesting query now re-opens those.

Also included

• Flow Profiles browser (/service/profiles), linked from the Flow detail
• init_segments (which lives under essence_parameters, not on the Flow) and segment init_object
• storage_backend_tag filters on the segments tab, driven by the tags the store's backends actually carry
• include_object_timerange on webhook registration
• Column-preference migration, so columns added by this release actually appear for existing users instead of being hidden by their persisted settings
• Client credentials is now the default auth for a new store (requested separately) — it is what most TAMS deployments use. Editing an existing store still respects whatever it was configured with.
• Ported upstream a753141 (container_mapping on the flow collections tab, by Dan Johns) — verified against the 8.2 schema first: container_mapping genuinely is a property of flow collection items

Review fixes

A full review of this branch turned up nine issues, each fixed in its own commit. Two were wrong answers presented as fact on the default code path:

• The status filter and server sort were silently ignored in hierarchical view. Tree mode keys SWR on "tree" and fetches via fetchEntityTree, which builds its own queries, so status/sort_by were never sent — while the view skipped its client-side fallback because the store was capable. Hierarchy is on by default, so on an 8.2 store picking a status changed nothing at all, and the header claimed the store was doing the filtering. Filters now fall back to local filtering whenever the query was not sent.
• A failed /service was indistinguishable from an 8.0 store. resolved flips true when SWR rejects, and the returned error was read by none of the eleven consumers, so an unreachable or 401ing store was reported to the user as "reports TAMS 8.0 or earlier". Added detectionFailed, used wherever the UI states a version, and re-enabled error retry.

Also fixed: the Diagram ran its whole traversal twice with a setElements race; fetchEntityTree truncated the hierarchy invisibly at depth 4 and dropped per-batch hasMore; isFlowGrowing's ?? flow.created made its documented face-value branch unreachable, so a live ingest older than ten minutes read as stale; Sources' Editorial purpose column sorted on a field that does not exist; and the column merge ran only on a version bump, so the next release adding a column would have silently regressed.

Removed as unreachable: describeCollectionMember, isFlowClosed, EDITORIAL_PURPOSE.PRIMARY, capabilities.editorialPurpose, and the profileId/initSegments options that were gated and threaded into the query but never passed by any view. The README's "8.0 and 8.1 are fully supported" and its init_segments filter were corrected to match what the code does.

Sony store gap closed. Init segment support had been written to the 8.2 shape only (essence_parameters.init_segments, per-segment init_object). Pre-8.2 stores — including the sonytams store on labs — name the init object in the tags.init_segment Flow tag and list it at the head of the segment listing with a zero-length timerange. Against those stores the column read blank for flows that do have an init segment, and the init object rendered as an ordinary media segment. hasInitSegments/isInitSegmentEntry now cover both conventions.

Dependencies and CI

All 14 npm audit vulnerabilities fixed (10 high, 3 moderate, 1 low → 0), lockfile-only: every advisory resolved to a version already permitted by the existing semver ranges, so package.json is unchanged.

Package		Fixes
axios	1.13.6 → 1.19.0	10 high — DoS, prototype pollution, proxy bypass
react-router-dom	7.13.1 → 7.18.2	12 high — XSS, open redirect, CSRF, DoS
vite	6.4.1 → 6.4.3	server.fs.deny bypass, NTLM disclosure
postcss	8.5.25 → 8.5.26	arbitrary .map file read
js-yaml, nanoid, brace-expansion, form-data, tmp, @babel/core		DoS, CRLF injection, path traversal

axios was reported by npm as fixAvailable: false, but @byomakase/omakase-player declares a ^1.13.5 range rather than a pin, so the bump was permitted after all — no player upgrade needed. This also settles a pre-existing inconsistency where package.json asked for vite ^6.4.2 while the lockfile pinned 6.4.1, leaving npm ls reporting the tree as invalid.

Added a PR build check. deploy.yml triggered only on push to main, so nothing verified a pull request and the first build of a change ran as part of the public Pages deploy — a broken build took the site down rather than failing a check. ci.yml now runs the same build on pull_request.

Notes for reviewers

Cloudscape cannot lazy-load an expandable tree. A row only becomes expandable once its children are in the item set, and expandedItems is not a controlled prop. Hierarchy mode therefore descends level by level via collected_by_ids (batched 40 ids per request, depth-capped) rather than fetching on expand. That is still a few requests instead of one per collection, and unlike the previous client-side tree it is correct across page boundaries and handles an entity collected by more than one parent — the old code took collected_by[0].

npm run lint still does not run, but is now one step from working. It had two independent causes: ESLint 9 needs a flat config and only .eslintrc.cjs exists; and eslint-plugin-react-hooks@7 failed to load against the hoisted zod@3.23.8. The dependency refresh below resolved the second — the plugin now gets its own zod@4.4.3 and loads cleanly. Adding the flat config is all that remains, and is left out of this PR because it surfaces a batch of pre-existing errors that deserve their own review.

Verified instead with:

• npm run build (Node 22, same as CI)
• a temporary flat config confirming no new lint errors — the same 8 pre-existing ones remain, including a useSWR import in Embed that was already unused
• an import-cycle scan (clean, 80 modules / 187 edges)
• executable assertions over the new pure logic: collected_by_ids= surviving as an empty value, version gating, the status fallback chain, reverse-order mapping, and video-member resolution without role
• the review fixes were re-verified the same way against their real dependencies: zero-length timerange detection through parseTimerange (10 cases), every isFlowGrowing/getFlowStatus branch (15 cases), and the column merge against zustand 5.0.11 (including the future-release case that was previously broken)
• the spec claims this code relies on were checked against bbc/tams@8.2 rather than taken on trust: collected_by_ids= meaning "in no collection", the per-field natural sort order behind toReverseOrder, the sort_by enums, and the Flow status enum all match. The api_version pattern is ^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$ — strictly MAJOR.MINOR — which confirms the deliberately strict regex in capabilities.js is correct
• npm ci --legacy-peer-deps from a clean tree, matching CI

Not verified against a live 8.2 store — I had no endpoint available, so the 8.2 paths are exercised only by the version gate and unit-level logic. Worth a pass against a real 8.2 store before merge.

Upstream has not adopted 8.2 — aws-samples/time-addressable-media-store-tools has zero usage of sort_by, editorial_purpose, init_segments, profile_id, /service/profiles or storage_backend_tag, and still reads the deprecated tag. This fork is now ahead of upstream here.

Merging deploys. .github/workflows/deploy.yml publishes to GitHub Pages on push to main, so merging puts this straight on the public site.

🤖 Generated with Claude Code