- G1 createEntityFromTmdbCandidate (sources-identity service): entity + accepted
manual external identity + season/episode units, idempotent per TMDB id;
POST /files/entity-from-candidate and organize items with `external`
- G2 minSizeBytes for organize (excluded below_min_size) and identify
(skipped + excludedBySize)
- G3 onExisting passed to planImport; dryRun marks each file
(same/skip/replace/conflict); replace = explicit grant
- G4 naming template|keep; planImport namingMode/namingSource, frozen
plan.naming {mode, templateSource, templateVersion}; targetSegments
- G5 identify prior-record hints, GET /files/record-sources, organize
refreshMetadata, POST /files/scrape-batch (dedupe by entity)
- G8 GET /files/tree (parent, subdirs hasChildren, video/registered counts)
- G9 POST /files/suggest-name returns 501 until the naming engine lands
Co-Authored-By: Claude Opus 5.5 <[email protected]>
- POST /files/probe writes media_asset.media_info, so scope organize.read -> organize.execute
- e2e e6-w4a-endpoints -> e10-w4a-endpoints (number clashed with e6-auto-recover)
- trash: reusing a consumed approval / retired planId is rejected and the file stays
Co-Authored-By: Claude Opus 5.5 <[email protected]>
- invoke-limits: sharedInvokeLimiter() (one semaphore set per process); agent
capability routes default to it
- /files/identify: catalog.lookup with includeRemote runs under the shared
TMDB semaphore + 15s timeout; at most 20 distinct remote queries per
request, further items fall back to local recall with a warning
Co-Authored-By: Claude Opus 5.5 <[email protected]>
S-1 (/files/move, /files/organize action=move):
- organize-guard: authorizeMoveEntities checks every source's media entities
(declared entity plus entities of registered assets under the source);
one-time approval still covers the whole request; any source that cannot
be attributed to an entity only passes with an approval; denial lists every
unauthorized item; optional non-consuming pre-check
- transfer: entities per source (directory = registered assets beneath it)
- organize: all move groups pre-checked before any group executes; any
denial -> whole request 403 approval_required
S-2:
- api.ts: GET /files/download and POST /files/trash/purge marked
auth:"session"; files routes attach requireAdminSession from the registry
annotation; handler-side purge check removed, download keeps a same-rule
defense check; permanent delete uses isAdminSession
- DEV key rule written down: equals an admin-scope key for session-only
endpoints, still admin for Move/delete approval bypass (as authorizeMove)
- api-registry.test: session list updated; new reverse assertion that no
non-session endpoint answers 403 to an admin-scope bearer
S-5 (trash restore):
- restore-to requires a writable managed library root (isWritableTarget)
- in-place restore rebuilds missing parents level by level without
following symlinks (mkdirWithin), realpath-checked per level
- cross-volume restore capped by FILES_TRASH_CROSS_MAX_BYTES; cross-volume
copies (trash in / restore out) go through fsproxy
Tests: multi-entity move 403 + listing, unattributed source, organize foreign
asset 403, download/purge 403 for DEV and admin-scope keys, restore target
not writable, symlinked parent, rebuild parents, cross-volume cap.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
- /files/move|copy go through planImport's new `transfer` variant (keep names, directory
expanded to per-file plan) → organization_record + verifyAndImport/executeRecord: per-file
ledger resumable, fsproxy, cross-volume directory move = per-file copy→verify→delete then
remove empty source dirs; shared plan store + plan_stale; asset_location follows per file,
path_binding revised when a whole directory moved (finalizeTransfer); request waits up to
FILES_TRANSFER_WAIT_SEC, else executed.pending
- /files/organize per-item overrides take effect: season/episodes (domain planOrganize
overrides), contentUnitId coverage, targetDir (no binding), operation, slotId (satisfied
after verify); warnings only for inapplicable overrides
- delete/trash/restore write organization_record (action trash|delete|restore, file-level
results; migration 0026)
- GET /files/download (admin session, nfo/subtitle/image, size cap, streamed, audited)
- GET /files/records?ids|planIds for the organize page
- fs race errors map to 503/404/403/400 instead of 500
- runbook updated
Co-Authored-By: Claude Opus 5.5 <[email protected]>
