Files
Chronos/docs/DECISIONS.md
T

11 KiB

| 2026-10-12 | An analysis records nothing when the frames it read are no longer the sequence's. Under the sequence lock it reads the sidecar and the index row. If the sidecar's frames version differs from the row's, another process (a desktop sharing a server's archive, or that server) changed the frames and this index does not hold them yet. The job then logs Advisor.Log.FramesChangedElsewhere and queues nothing: that process analyses the frames it changed, and this host's next scan indexes them. A server's scan then queues their light analysis; a desktop's scan takes the statuses from the sidecar. If the row's version moved since the analysis read it and no light analysis is queued for the sequence, the job logs Advisor.Log.FramesChanged and queues a light analysis. If one is already queued, the pass records as before and the queued one replaces it. Recording nothing leaves the status, warning count, compact summary and Auto values as they were in the index, the sidecar and project.json. A deep pass keeps only analysis.json and its per-frame measurements, which describe the frames they name. Refines 2026-10-12 'A deep analysis checks its own report…'. | Never record once a version moved, even with a light analysis queued; recompute the light statistics from the frames as they are under the lock; compare only the row's version; queue a light analysis when only the sidecar moved; queue a deep analysis again | A pass that loaded its frames before an upload, an import or a scan's reconcile recorded AnalyzedLight, the old warning count and Auto values counted on the old frame count. It did so over the newer light analysis, and nothing analysed the new frames again, since scans list only sequences without AnalyzedLight. Comparing only the row missed frames another process listed in a shared sidecar before this host's scan. The pass then wrote Auto values and statuses for the old frames over that process's analysis in the shared files, and a desktop's scan clears nothing (row 'A scan reads a sidecar again…'), so nothing analysed them again. A light analysis queued here while only the sidecar moved would read the same index and be overtaken again until the scan. During an upload burst every pass is overtaken, so never recording would leave a sequence being shot without any analysis until uploads paused, as with image passes (row 'An image pass sets ThumbsBuilt…'). Recomputing would mean probing and reading the new frames under the lock. A deep pass can run for hours: the light analysis restores status and advice, and the user starts a deep pass again when wanted. | | 2026-10-12 | SyncService.ApplyLocallyAsync records the folder's scan stamps after writing the server's title, tags, rating or notes into the sidecar only when ArchiveIndexer.InStepAsync held before that write, like the other partial writers. Refines 2026-10-12 'Such a writer records the folder's scan stamps…', which left it recording them unconditionally. | Keep recording them unconditionally; write the whole row from the sidecar | Frames another process (a desktop sharing this archive) listed in the sidecar since this index last synced the folder stayed out of the index until the folder changed again, and the row's frames version stayed behind the sidecar's. An analysis now records nothing while the two differ (row 'An analysis records nothing…'), so the gap would also have kept the sequence from being analysed here. | | 2026-10-12 | With Keep proxies offline, a proxy cache counts as filled only when every frame is cached as a proxy, missing or damaged frames aside. A thumbnail or no file stands in for a proxy whether or not the server has ProxiesBuilt. A stale cache of a sequence without ProxiesBuilt is compared with the manifest's per-frame HasProxy once per change of the server's update time. A frame offered as a proxy that the cache holds only a thumbnail for (or a file of unknown kind, or nothing) queues the background proxy download. With ProxiesBuilt, a download that left stand-ins is queued again once the server's update time moves; a frames change still downloads at once. A comparison or download that queued a download counts only once that download is done: a failed or cancelled one is compared again after its backoff. Replaces the 2026-10-12 row 'With Keep proxies offline, a stale proxy cache of a server sequence without ProxiesBuilt is compared…'. Refines the proxy-cache kinds row. | Wait for ProxiesBuilt; trust ProxiesBuilt when a download ends; count only frames that want or offer a proxy; download at every refresh while stand-ins remain; read the manifest at every refresh; offer a manual re-download on ProxiesOnly rows | ProxiesBuilt does not wait for every frame. It stays set between an insert and the next background proxy pass, and through an upload burst while a pass is queued (rows 'The server's manifests…' and 'An image pass sets ThumbsBuilt…'). Frames added meanwhile were offered but answered 404, and a cache marked filled then kept thumbnails or holes until the frames changed again. While the flag is clear it waits for every frame the server cannot decode, and a missing or damaged frame never gets a proxy, so the flag may never come. Counting every frame also covers a manifest read while the flag changed. A proxy that arrives, or a pass that draws new frames, leaves a new update time, so one comparison or download per change is enough. Fetching at every refresh would queue a job every 2 minutes while a pass waits. The server's sequence may never change after a failed download, so the failure itself must reopen the comparison. | | 2026-10-12 | Every transaction that writes a sequence's frames takes the sequence row first, then the frames. It takes either a row lock (SequenceRepository.GetForUpdateAsync) or an update of the row. Decode tiers record the row before their frames. A verify's integrity flags and maintenance's duplicate flags lock the row in the same transaction as their frames. On PostgreSQL, a light analysis's statistics lock the rows of their frames' sequences before the frames (FrameRepository.UpdateLightStatsAsync). | Make the scan's sync take the sequence lease; reorder only FrameTiers.RecordAsync; retry transactions PostgreSQL aborts with 40P01 | The scan's sync, the ingest, a rename and a restore already locked the row before the frames. Tier writes and light statistics locked their frames first. On PostgreSQL, a scan or rebuild then deadlocked with an analysis, image pass or render on the same sequence, and nothing retries a transaction. One order closes the cycle for every pair. Frame-only writers under the lease also stop committing between a scan's row lock and its write; the scan's check of the sidecar it read relies on this (next row). SQLite serialises writers and was not affected. | | 2026-10-12 | A scan writes a sidecar it read without the sequence lease only when, under the row lock, the sidecar still has the stamp the scan listed and the row holds the sidecar's frames version. Otherwise it reads the sidecar again under the lease and indexes that. Such a write records the stamps it was checked against. The index snapshot files each sidecar's bytes under the stamp they were read at. | Take the lease for every folder a scan indexes; compare only the frames versions | An upload or a partial writer could commit between the scan's read and its transaction. The scan then wrote its older copy over the row and frames, dropping uploaded frame rows or tier flags, and recorded stamps that hid this from every incremental scan. Partial writers keep the frames version, so comparing versions alone misses them. A lease per folder would slow a rebuild of thousands of folders on a share; the check costs one stat. Only folders changed since the listing, or adopted or rewritten by the scan itself, go through the lease. | | 2026-10-12 | The index's frames version never goes back. A sidecar read under the lease whose frames version is behind the locked row is written again one version past the row, then indexed. That happens when an older copy was put back by hand, from a backup or by a file-sync tool. | Index the lower version; keep the row's version in the index only; refuse to index the folder | Editors and clients detect frame changes by the frames version (expectedFramesVersion, the local save check). A version that goes back and up again can repeat one a client holds for other frames. A row left ahead of its sidecar would read as moved at every scan. The sidecar stays the truth for the frames. | | 2026-10-12 | An upload's batch asks ArchiveIndexer.InStepAsync under the lease before it changes the folder. It appends its frame rows and records the folder's stamps only when that held and its frames went at the end. Otherwise it writes the whole row and every frame from the sidecar. This extends the partial-writer stamps row above to ArchiveIngest. | Keep the frame-count check alone; append and leave the stamps unrecorded | A desktop's verify, decode tiers, duplicates or title change only existing frames or fields, so the frame count still matched. The appended rows and the recorded stamps then hid those changes from the server's index until a full scan, and a sequence that keeps receiving uploads never healed. Appending without recording stamps would still leave the server's frames stale until its next poll. | | 2026-10-12 | Before an upload's batch files its photos, it asks under the lease whether the photo directory still has the stamp the index recorded (ArchiveIndexer.PhotosChangedAsync). The photo directory is originals/, or the folder for a sequence adopted in place. If it changed, because photos were copied in or removed by hand or by another process since the last scan, the resync from the sidecar records the photo stamp the index held before, or none when none was recorded. The folder's new stamp is not recorded, so the next incremental scan reconciles the folder with its photos. | Reconcile the photos in the upload under the lease; record the new stamp as before | The batch's own files change the photo directory's stamp. Recording it hid the copied photos from every incremental scan, so only a full scan or the orphans check found them. A reconcile in the upload would read new photos while uploads to the sequence wait. The scan's reconcile already clears and queues what covers the frames. Until that scan, which server and desktop run every 10 minutes, every upload batch to that sequence writes all its frames instead of appending. | | 2026-10-12 | A verify writes only Missing and Corrupt, merged into the frame's flags as the sidecar has them under the lease. The index sets and clears only those bits, with the new hash. A check is written only while the sidecar lists the frame with the file, size and hash that were checked, and the file still has the size and modification time it had before it was read. Otherwise the next verify checks it. | Write every flag computed from the frame read at the start (as before); merge the bits but write every verdict; hash the file again under the lease | A verify reads each sidecar once, possibly hours before it writes. Tiers, duplicates and repairs recorded meanwhile were reverted. A photo an upload repaired during the run was flagged missing, so the next copy moved the good file aside. Hashing again under the lease would hold uploads back for as long as the files take to read. One case remains: during the run, a good copy with the same size and modification time is put back over a same-size corrupt file, and it is still flagged corrupt. A card import keeps the camera file's time, so it can do this. The next verify clears the flag. |